diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 694e17330..783814be7 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -65,6 +65,18 @@ }, "category": "Developer Tools" }, + { + "name": "cloud-inference-skills", + "source": { + "source": "local", + "path": "./plugins/cloud-inference-skills" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Developer Tools" + }, { "name": "dotnet-skills", "source": { @@ -240,10 +252,10 @@ "category": "Developer Tools" }, { - "name": "codex-utilities", + "name": "agentdeck", "source": { "source": "local", - "path": "./plugins/codex-utilities" + "path": "./plugins/agentdeck" }, "policy": { "installation": "AVAILABLE", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 022a54bee..db419f1ae 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -137,7 +137,9 @@ The installable local child entries currently point at: - `./plugins/android-dev-skills` - `./plugins/apple-dev-skills` - `./plugins/cardhop-app` -- `./plugins/codex-utilities` +- `./plugins/cloud-deployment-skills` +- `./plugins/cloud-inference-skills` +- `./plugins/agentdeck` - `./plugins/dotnet-skills` - `./plugins/game-dev-skills` - `./plugins/network-protocol-skills` diff --git a/README.md b/README.md index db962445f..8109e646a 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,8 @@ Currently available from the catalog: - `apple-dev-skills` - `cardhop-app` - `cloud-deployment-skills` -- `codex-utilities` +- `cloud-inference-skills` +- `agentdeck` - `dotnet-skills` - `game-dev-skills` - `network-protocol-skills` @@ -114,7 +115,8 @@ Current Socket catalog shape: - `apple-dev-skills`: Apple, Swift, SwiftUI animation and architecture, Core Animation, Apple typography, SF Symbols, AppKit, Xcode, strict media type selection for AVFoundation, AVFAudio, Core Media, Core Audio, Audio Toolbox, Swift OpenAPI client, Safari, DocC workflows, and the source-bundled `swift-steward` custom-agent definition with its own roadmap - `cardhop-app`: mixed skill plus bundled MCP server for Cardhop.app contact workflows - `cloud-deployment-skills`: cloud provider deployment routing, official provider plugin selection, credential and mutation boundary checks, and AWS handoff to the official AWS Agent Toolkit rather than duplicated AWS MCP, CLI, or SAM setup -- `codex-utilities`: local Codex runtime utilities, starting with hooks that prefix generated Codex thread titles with the project directory name +- `cloud-inference-skills`: cloud AI inference, training, model conversion, and GPU infrastructure routing for Runpod, Hugging Face, AWS, Vast.ai, CoreWeave, and similar providers, with bundled Runpod MCP server configuration, upstream Runpod skill mirrors, and first-party Hugging Face/AWS handoffs +- `agentdeck`: local Codex runtime utilities, starting with hooks that prefix generated Codex thread titles with the project directory name - `dotnet-skills`: .NET, F#, and C# project-shape, bootstrap, implementation, test, package, diagnostics, ASP.NET Core, interop, CI, upgrade, and tooling guidance - `game-dev-skills`: Apple platform game development workflows for SpriteKit, SceneKit, GameplayKit simulation, Game Controller input, Core Haptics feedback, Xcode game profiling, game-stack routing, and device-aware validation handoffs - `network-protocol-skills`: modern networking and application-protocol workflows for transport selection, HTTP/3 and QUIC planning, Media over QUIC draft-aware guidance, WebRTC signaling/media/data-channel work, and protocol diagnostics with stack-plugin handoffs diff --git a/ROADMAP.md b/ROADMAP.md index 76ae8543e..1d0be20d7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -11,7 +11,7 @@ - [Milestone 8: Server-Side Swift skills plugin](#milestone-8-server-side-swift-skills-plugin) - [Milestone 9: Rust skills plugin](#milestone-9-rust-skills-plugin) - [Milestone 10: Expo inline native modules workflow](#milestone-10-expo-inline-native-modules-workflow) -- [Milestone 11: Codex Utilities plugin](#milestone-11-codex-utilities-plugin) +- [Milestone 11: AgentDeck plugin](#milestone-11-agentdeck-plugin) - [Milestone 12: Xcode 27 agentic tooling workflows](#milestone-12-xcode-27-agentic-tooling-workflows) - [Milestone 13: Reverse Engineering skills plugin](#milestone-13-reverse-engineering-skills-plugin) - [Milestone 14: Core AI and Foundation Models workflow ownership](#milestone-14-core-ai-and-foundation-models-workflow-ownership) @@ -23,6 +23,7 @@ - [Milestone 20: Game Dev Skills plugin](#milestone-20-game-dev-skills-plugin) - [Milestone 21: Cloud Deployment Skills plugin](#milestone-21-cloud-deployment-skills-plugin) - [Milestone 22: Network Protocol Skills plugin](#milestone-22-network-protocol-skills-plugin) +- [Milestone 23: Cloud Inference Skills plugin](#milestone-23-cloud-inference-skills-plugin) - [Small Tickets](#small-tickets) - [Backlog Candidates](#backlog-candidates) - [History](#history) @@ -47,7 +48,7 @@ - Milestone 8: Server-Side Swift skills plugin - Completed - Milestone 9: Rust skills plugin - Completed - Milestone 10: Expo inline native modules workflow - Completed -- Milestone 11: Codex Utilities plugin - In Progress +- Milestone 11: AgentDeck plugin - In Progress - Milestone 12: Xcode 27 agentic tooling workflows - In Progress - Milestone 13: Reverse Engineering skills plugin - In Progress - Milestone 14: Core AI and Foundation Models workflow ownership - Completed @@ -59,6 +60,7 @@ - Milestone 20: Game Dev Skills plugin - Completed - Milestone 21: Cloud Deployment Skills plugin - Completed - Milestone 22: Network Protocol Skills plugin - Completed +- Milestone 23: Cloud Inference Skills plugin - Completed ## Milestone 5: SwiftASB skills plugin @@ -150,7 +152,7 @@ Completed - [x] Keep `python-skills:uv-pytest-unit-testing` as the release-compatible pytest workflow name for now. - [x] Update Python plugin metadata after the first new skill slice lands. - [x] Run child validation with `uv run scripts/validate_repo_metadata.py`, `uv run pytest`, `uv run ruff check .`, and `uv run mypy .`. -- [x] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. +- [ ] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. ### Exit Criteria @@ -264,7 +266,7 @@ Completed Decision note: the root marketplace entry is installable now that `web-dev-skills` ships real skill content. -## Milestone 11: Codex Utilities plugin +## Milestone 11: AgentDeck plugin ### Status @@ -272,47 +274,47 @@ In Progress ### Scope -- [x] Add a Socket-hosted `codex-utilities` child plugin for local Codex runtime utilities that do not belong to a language-specific skill pack, app integration, or repository-maintenance plugin. +- [x] Add a Socket-hosted `agentdeck` child plugin for local Codex runtime utilities that do not belong to a language-specific skill pack, app integration, or repository-maintenance plugin. - [x] Keep the first slice capture-only: record real `SessionStart` hook payloads before mutating thread titles. - [x] Prefer Codex App Server metadata operations for future thread renaming instead of invoking `codex exec` as a separate agent run. - [x] Keep explicit `capture` and `dry-run` modes so the same hook can test title prefixing without changing thread metadata. - [x] Enable thread-title mutation by default after a real new-thread test confirmed the captured `session_id` maps to the target thread id and Codex GUI hook settings provide the behavior toggle. - [x] Prefix titles on the second `Stop` hook by default so Codex's own generated-title writer has settled before the plugin writes the project prefix. - [x] Add a diagnostic `PostToolUse` hook log so title-generation timing can be compared against hook-visible tool activity. -- [ ] Add a desktop bridge MCP and skill surface that talks to the separate `UtilitiesForCodex` app instead of bundling a macOS app inside the plugin. -- [ ] Add Codex GUI restart request/cancel/status tools and a narrow skill that delegates waiting and final restart execution to `UtilitiesForCodex`. -- [ ] Add an agent configuration sync surface that lets `UtilitiesForCodex` discover, diff, and safely render compatible guidance/config for normal Codex, Xcode Codex, and Xcode Claude while `codex-utilities` owns the agent-facing adapter and policy. +- [ ] Add a desktop bridge MCP and skill surface that talks to the separate `AgentDeck` app instead of bundling a macOS app inside the plugin. +- [ ] Add Codex GUI restart request/cancel/status tools and a narrow skill that delegates waiting and final restart execution to `AgentDeck`. +- [ ] Add an agent configuration sync surface that lets `AgentDeck` discover, diff, and safely render compatible guidance/config for normal Codex, Xcode Codex, and Xcode Claude while `agentdeck` owns the agent-facing adapter and policy. ### Tickets -- [x] Create `plugins/codex-utilities/` with its own `.codex-plugin/plugin.json`, `AGENTS.md`, `hooks/`, `scripts/`, and local design note. +- [x] Create `plugins/agentdeck/` with its own `.codex-plugin/plugin.json`, `AGENTS.md`, `hooks/`, `scripts/`, and local design note. - [x] Add a `SessionStart` hook that captures stdin to a local JSONL runtime log. - [x] Add a Node stdlib App Server control-socket client for opt-in `thread/name/set` tests. -- [x] Wire `codex-utilities` into the root Socket marketplace as a normal local child plugin. +- [x] Wire `agentdeck` into the root Socket marketplace as a normal local child plugin. - [x] Update root README so users can see the new installable plugin surface. - [x] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. - [x] Run a hook test from the Codex GUI and inspect `thread-title-decisions.jsonl`. - [x] Install or refresh the plugin locally, trust the hook, start a real new thread, and compare captured `session_id` with the created thread id. -- [x] Record the desktop bridge MCP and skill plan in `plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md`. -- [ ] Add a bridge-status-only MCP server once `UtilitiesForCodex` exposes a local status endpoint. +- [x] Record the desktop bridge MCP and skill plan in `plugins/agentdeck/docs/desktop-bridge-mcp-skill-plan.md`. +- [ ] Add a bridge-status-only MCP server once `AgentDeck` exposes a local status endpoint. - [ ] Add a `desktop-bridge` skill after the MCP status surface exists. - [x] Extend the desktop bridge MCP and skill plan with Codex GUI restart coordination. -- [ ] Add a `codex-gui-restart` skill after `UtilitiesForCodex` exposes restart request, cancellation, and status endpoints. +- [ ] Add a `codex-gui-restart` skill after `AgentDeck` exposes restart request, cancellation, and status endpoints. - [ ] Implement `if-idle` restart requests before `when-idle`; keep automatic waiting blocked until the app has a supported thread-status source. -- [x] Record the UtilitiesForCodex agent configuration sync plan in `plugins/codex-utilities/docs/agent-configuration-sync-plan.md`. -- [ ] Add a read-only bridge/status tool for agent configuration sync after `UtilitiesForCodex` can report detected target homes, versions, and compatibility-profile status. +- [x] Record the AgentDeck agent configuration sync plan in `plugins/agentdeck/docs/agent-configuration-sync-plan.md`. +- [ ] Add a read-only bridge/status tool for agent configuration sync after `AgentDeck` can report detected target homes, versions, and compatibility-profile status. - [ ] Add an agent-facing sync skill after the app exposes dry-run previews and backup-backed apply endpoints. ### Exit Criteria -- [x] The Socket marketplace exposes `codex-utilities` as an installable child plugin. +- [x] The Socket marketplace exposes `agentdeck` as an installable child plugin. - [ ] The first hook captures `SessionStart` payloads without writing captured data into the Socket repository. - [ ] Thread-title automation has a confirmed target-thread identity before it calls `thread/name/set`. - [x] Opt-in thread-title automation can be tested without invoking `codex exec` or starting a separate agent run. - [x] Root Socket docs, marketplace wiring, and validation agree on the plugin's install surface. - [ ] Desktop bridge MCP and skill surfaces are available without packaging the signed macOS app inside the plugin cache. - [ ] Codex GUI restart requests require explicit user intent, report pending/cancelled/blocked/completed status clearly, and never infer thread idleness from process state alone. -- [ ] Agent configuration sync previews omit unsupported keys by default, preserve target-owned files, and route writes through `UtilitiesForCodex` rather than direct plugin-side filesystem mutation. +- [ ] Agent configuration sync previews omit unsupported keys by default, preserve target-owned files, and route writes through `AgentDeck` rather than direct plugin-side filesystem mutation. ## Milestone 12: Xcode 27 agentic tooling workflows @@ -587,7 +589,7 @@ Planned - [ ] Add later skills for architecture mapping, adoption-risk decisions, and remediation planning after the first two workflows prove useful. - [ ] Wire the plugin into the root marketplace as `NOT_AVAILABLE` while it is a placeholder, then switch it to installable only after real skill content exists. - [ ] Update root README and ROADMAP when the plugin becomes installable. -- [ ] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. +- [x] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. ### Exit Criteria @@ -701,6 +703,39 @@ Completed Completed Milestone 22 by adding the `network-protocol-skills` child plugin, shipping five protocol and diagnostics workflows, wiring the Socket marketplace entry, adding missing plugin icon assets, and keeping implementation handoffs delegated to the owning stack plugins. +## Milestone 23: Cloud Inference Skills plugin + +### Status + +Completed + +### Scope + +- [x] Add a Socket-hosted `cloud-inference-skills` child plugin for cloud AI inference, model training, model conversion, and GPU infrastructure routing. +- [x] Prefer Gale's familiar provider lanes when they fit: Runpod for quick GPU Pods, Serverless endpoints, Flash, and agent-managed resources; Hugging Face for model, dataset, conversion, endpoint, Space, and Hub-native workflows; AWS for existing account, IAM, S3, Lambda, SageMaker, Bedrock, ECS, EKS, and Batch surfaces. +- [x] Include Vast.ai for cheap flexible GPU rentals and CoreWeave for cluster-shaped GPU infrastructure without pretending either is the default for quick experiments. +- [x] Keep official-provider ownership explicit: bundle Runpod's official MCP config, install Runpod's upstream `companion-clis`, `flash`, and `runpodctl` skills through `npx skills add runpod/skills`, and hand Hugging Face/AWS work to their first-party plugins and CLIs when those fit. + +### Tickets + +- [x] Record the detailed plan in [`docs/maintainers/cloud-inference-skills-plugin-plan.md`](./docs/maintainers/cloud-inference-skills-plugin-plan.md). +- [x] Create `plugins/cloud-inference-skills/` with `.codex-plugin/plugin.json`, `.mcp.json`, `AGENTS.md`, an icon asset, and authored `skills/` source. +- [x] Add `cloud-inference-skills:cloud-inference-routing-workflow` for provider selection, model/workload triage, credential boundaries, cost boundaries, mutation checks, and validation choices. +- [x] Bundle Runpod's official `runpod` and `runpod-docs` MCP server configuration without committing API keys. +- [x] Install Runpod's upstream `companion-clis`, `flash`, and `runpodctl` skills into the exported plugin `skills/` tree, with `.agents/skills` kept as a symlink discovery mirror. +- [x] Wire `cloud-inference-skills` into the root Socket marketplace as an installable child plugin. +- [x] Update root README, CONTRIBUTING, and ROADMAP so users and maintainers understand the new plugin surface. +- [x] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. + +### Exit Criteria + +- [x] The Socket marketplace exposes `cloud-inference-skills` as an installable child plugin. +- [x] The shipped skill routes cloud inference and GPU work across Runpod, Hugging Face, AWS, Vast.ai, CoreWeave, and adjacent providers without absorbing provider-specific setup owned by official plugins and CLIs. +- [x] Runpod MCP config is available through the plugin, while Runpod's upstream skills are exported through `skills/` and tracked by `skills-lock.json`. +- [x] Root Socket docs, marketplace wiring, and plugin metadata agree on the exported cloud inference surface. + +Completed Milestone 23 by adding the `cloud-inference-skills` child plugin, shipping the provider-routing workflow, bundling Runpod MCP server configuration, installing the upstream Runpod skill mirror, adding the neon cloud GPU icon, wiring the Socket marketplace entry, and documenting first-party Runpod, Hugging Face, and AWS handoffs. + ## Small Tickets - [ ] Record issue-sized fixes, TODO/FIXME imports, and cleanup work that is too small or too unplanned for a milestone. @@ -810,9 +845,9 @@ Completed Milestone 22 by adding the `network-protocol-skills` child plugin, shi - Added the first repo-local Socket Steward prototype under `.agents/socket-steward`, giving the superproject a Python and OpenAI Agents SDK maintainer-agent scaffold with offline docs, guidance, and marketplace audits before any write-capable or background-service behavior. - Added Socket Steward's first docs-sync planner so the repo-local agent can produce structured read-only documentation alignment work before any guarded write mode exists. - Added `docs/agents/` for repo-local agent report artifacts and limited Socket Steward proposal writes to that directory. -- Planned a `codex-utilities` desktop bridge MCP and skill surface that talks to the separate `UtilitiesForCodex` macOS app over a local transport instead of bundling a signed app in the plugin cache. -- Planned Codex GUI restart request/cancel/status tools and a narrow skill that keep restart execution in `UtilitiesForCodex` and leave automatic `when-idle` waiting blocked until a supported thread-status source exists. -- Planned a UtilitiesForCodex agent configuration sync surface so normal Codex, Xcode Codex, and Xcode Claude can be discovered, diffed, and rendered through target-specific compatibility rules while `codex-utilities` remains the Codex-facing adapter. +- Planned an `agentdeck` desktop bridge MCP and skill surface that talks to the separate `AgentDeck` macOS app over a local transport instead of bundling a signed app in the plugin cache. +- Planned Codex GUI restart request/cancel/status tools and a narrow skill that keep restart execution in `AgentDeck` and leave automatic `when-idle` waiting blocked until a supported thread-status source exists. +- Planned an AgentDeck agent configuration sync surface so normal Codex, Xcode Codex, and Xcode Claude can be discovered, diffed, and rendered through target-specific compatibility rules while `agentdeck` remains the Codex-facing adapter. - Added serialized Socket Steward prepare/apply commands so maintainers can run audit, docs-sync planning, and proposal refresh in one guarded pass. - Extended the roadmap maintainer skill with one-ticket add/update flags and updated automation-design guidance to prefer existing skills, plugins, scripts, and official workflow owners as the source of truth for workflow knowledge. - Removed the stale Apple Dev Skills release-time subtree push gate after the standalone Apple Dev Skills repository became a compatibility marketplace pointer to Socket's canonical `plugins/apple-dev-skills` payload. diff --git a/docs/agents/token-efficiency-automation-audit-2026-06-22.md b/docs/agents/token-efficiency-automation-audit-2026-06-22.md index eb4c01548..711a2834b 100644 --- a/docs/agents/token-efficiency-automation-audit-2026-06-22.md +++ b/docs/agents/token-efficiency-automation-audit-2026-06-22.md @@ -180,9 +180,9 @@ Poor first `.fsx` candidates: Evidence: -- `plugins/codex-utilities/hooks/run-thread-title-hook.sh` currently launches +- `plugins/agentdeck/hooks/run-thread-title-hook.sh` currently launches the hook with `node`. -- `plugins/codex-utilities/scripts/session-start-hook.mjs` hand-rolls hook JSON +- `plugins/agentdeck/scripts/session-start-hook.mjs` hand-rolls hook JSON parsing, environment configuration, App Server JSON-RPC over stdio, state file updates, and JSONL logging in one 592-line script. - `plugins/dotnet-skills/AGENTS.md` treats F# and C# as equal first-party .NET @@ -288,7 +288,7 @@ Recommended proof: 2. Compare the same task in Python and `.fsx` for line count, startup time, dependency setup, error messages, and testability. 3. Only after that comparison, decide whether the first durable `.fsx` home is - `dotnet-skills`, `codex-utilities`, or root Socket maintainer tooling. + `dotnet-skills`, `agentdeck`, or root Socket maintainer tooling. Keep the current `.mjs` hook unless the proof shows F# materially improves the hook's event model or maintainability. Node is already available in many Codex @@ -337,18 +337,18 @@ stewardship report should include them so they do not silently become stale catalog clutter, but there is no evidence that they should be deleted in this audit. -### 4. Decide whether `.fsx` belongs to `dotnet-skills` or `codex-utilities` +### 4. Decide whether `.fsx` belongs to `dotnet-skills` or `agentdeck` There are two plausible ownership models: - `dotnet-skills` owns the authoring convention because `.fsx` is a .NET/F# runtime choice. -- `codex-utilities` owns hook-specific conventions because hook event payloads, +- `agentdeck` owns hook-specific conventions because hook event payloads, App Server JSON-RPC, and runtime data paths are Codex utility concerns. Recommendation: split the ownership. Put general `.fsx` style, validation, and project-shape guidance in `dotnet-skills`; put Codex hook payload contracts and -runtime-data conventions in `codex-utilities`. Avoid a root Socket scripting +runtime-data conventions in `agentdeck`. Avoid a root Socket scripting policy until at least one proof exists. ## Do Not Consolidate Yet diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 951c2df86..3c88069ee 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -14,7 +14,7 @@ See [SLICES.md](./SLICES.md) for provable end-to-end code paths. - `android-dev-skills` (codex-plugin) uses targets: no targets recorded. - `apple-dev-skills` (codex-plugin) uses targets: skills:plugins/apple-dev-skills/skills, mcp:plugins/apple-dev-skills/.mcp.json. - `cardhop-app` (codex-plugin) uses targets: skills:plugins/cardhop-app/skills, mcp:plugins/cardhop-app/.mcp.json. -- `codex-utilities` (codex-plugin) uses targets: no targets recorded. +- `agentdeck` (codex-plugin) uses targets: no targets recorded. - `dotnet-skills` (codex-plugin) uses targets: skills:plugins/dotnet-skills/skills. - `productivity-skills` (codex-plugin) uses targets: skills:plugins/productivity-skills/skills, mcp:plugins/productivity-skills/.mcp.json. - `python-skills` (codex-plugin) uses targets: skills:plugins/python-skills/skills. @@ -26,7 +26,7 @@ See [SLICES.md](./SLICES.md) for provable end-to-end code paths. - `swiftasb-skills` (codex-plugin) uses targets: skills:plugins/swiftasb-skills/skills. - `things-app` (codex-plugin) uses targets: skills:plugins/things-app/skills, mcp:plugins/things-app/.mcp.json. - `web-dev-skills` (codex-plugin) uses targets: skills:plugins/web-dev-skills/skills. -- `socket` (codex-plugin-marketplace) uses targets: agent-portability-skills, android-dev-skills, apple-dev-skills, cardhop-app, dotnet-skills, productivity-skills, python-skills, server-side-swift, server-side-jvm, rust-skills, speak-swiftly, swiftasb-skills, things-app, spotify, web-dev-skills, reverse-engineering-skills, codex-utilities. +- `socket` (codex-plugin-marketplace) uses targets: agent-portability-skills, android-dev-skills, apple-dev-skills, cardhop-app, dotnet-skills, productivity-skills, python-skills, server-side-swift, server-side-jvm, rust-skills, speak-swiftly, swiftasb-skills, things-app, spotify, web-dev-skills, reverse-engineering-skills, agentdeck. - `speak-swiftly` (remote-plugin-entry) uses targets: no targets recorded. @@ -185,7 +185,7 @@ The structured visual model lives in [architecture.json](./architecture.json). I - `skill-manifest` evidence from `plugins/cardhop-app/skills/cardhop-contact-workflow/SKILL.md`. - `mcp-config` evidence from `plugins/cardhop-app/.mcp.json`. - `codex-plugin-manifest` evidence from `plugins/cardhop-app/.codex-plugin/plugin.json`. -- `codex-plugin-manifest` evidence from `plugins/codex-utilities/.codex-plugin/plugin.json`. +- `codex-plugin-manifest` evidence from `plugins/agentdeck/.codex-plugin/plugin.json`. - `skill-manifest` evidence from `plugins/dotnet-skills/skills/aspnet-core-service-workflow/SKILL.md`. - `skill-manifest` evidence from `plugins/dotnet-skills/skills/bootstrap-solution/SKILL.md`. - `skill-manifest` evidence from `plugins/dotnet-skills/skills/build-csharp-project/SKILL.md`. diff --git a/docs/architecture/architecture.json b/docs/architecture/architecture.json index b6d0c1f7c..d1fac288b 100644 --- a/docs/architecture/architecture.json +++ b/docs/architecture/architecture.json @@ -124,7 +124,7 @@ }, { "kind": "codex-plugin-manifest", - "path": "plugins/codex-utilities/.codex-plugin/plugin.json" + "path": "plugins/agentdeck/.codex-plugin/plugin.json" }, { "kind": "skill-manifest", @@ -553,12 +553,12 @@ "evidence": [ { "kind": "codex-plugin-manifest", - "path": "plugins/codex-utilities/.codex-plugin/plugin.json" + "path": "plugins/agentdeck/.codex-plugin/plugin.json" } ], "kind": "codex-plugin", - "name": "codex-utilities", - "path": "plugins/codex-utilities", + "name": "agentdeck", + "path": "plugins/agentdeck", "targets": [] }, { @@ -742,7 +742,7 @@ "spotify", "web-dev-skills", "reverse-engineering-skills", - "codex-utilities" + "agentdeck" ] }, { @@ -2402,7 +2402,7 @@ "from": "product:socket", "kind": "exposes", "label": "marketplace exposes plugin entry", - "to": "product:codex-utilities" + "to": "product:agentdeck" }, { "evidence": [ @@ -2411,10 +2411,10 @@ "path": ".agents/plugins/marketplace.json" } ], - "from": "product:codex-utilities", + "from": "product:agentdeck", "kind": "owns", "label": "marketplace entry points at local plugin root", - "to": "path:./plugins/codex-utilities" + "to": "path:./plugins/agentdeck" } ], "schemaVersion": 1, diff --git a/docs/maintainers/cloud-inference-skills-plugin-plan.md b/docs/maintainers/cloud-inference-skills-plugin-plan.md new file mode 100644 index 000000000..07bf5b9b7 --- /dev/null +++ b/docs/maintainers/cloud-inference-skills-plugin-plan.md @@ -0,0 +1,66 @@ +# Cloud Inference Skills Plugin Plan + +## Purpose + +The `cloud-inference-skills` plugin helps agents choose and operate cloud AI inference, training, conversion, and GPU infrastructure workflows without turning `cloud-deployment-skills`, `python-skills`, Hugging Face, AWS, or Runpod guidance into one overloaded surface. + +## Ownership + +- `cloud-inference-skills` owns provider selection, official-tool routing, credential and cost boundaries, inference readiness, model artifact handling, and cross-provider handoffs. +- `cloud-deployment-skills` owns ordinary cloud application deployment routing, production infrastructure mutation boundaries, and non-model deployment handoffs. +- Stack plugins own application implementation details once the inference provider lane is chosen. +- Official provider plugins, MCP servers, CLIs, SDKs, and docs own provider-specific setup where they are current and available. + +## First Slice + +Create: + +```text +plugins/cloud-inference-skills/ +├── .codex-plugin/plugin.json +├── .mcp.json +├── AGENTS.md +├── assets/cloud-inference-icon.svg +└── skills/ + └── cloud-inference-routing-workflow/ + └── SKILL.md +``` + +The first skill should prefer Gale's familiar surfaces when they fit: + +- Runpod for quick GPU Pods, Serverless endpoints, Flash, flexible experiments, templates, and MCP-backed resource management. +- Hugging Face for model and dataset repos, conversion artifacts, Inference Endpoints, Spaces, jobs, and Hub-native workflows. +- AWS for existing-account infrastructure, IAM, S3, CloudWatch, Lambda, SageMaker, Bedrock, ECS, EKS, and Batch. +- Vast.ai for cheap flexible GPU boxes where cleanup and artifact transfer are explicit. +- CoreWeave for cluster-shaped GPU infrastructure, Kubernetes, storage, networking, and production-grade GPU services. + +## MCP Boundary + +Bundle Runpod's official MCP configuration because it provides direct agent value for resource management and documentation lookup: + +- `runpod`: stdio server via `npx -y @runpod/mcp-server@latest`, requiring `RUNPOD_API_KEY` from the Codex MCP environment. +- `runpod-docs`: unauthenticated remote docs MCP at `https://docs.runpod.io/mcp`. + +Keep Runpod's upstream agent skills under the exported `skills/` tree, tracked by `skills-lock.json`, with `.agents/skills/` as a symlink discovery mirror. Refresh the upstream skills with Runpod's official package rather than hand-editing the copied skill files: + +```bash +npx skills add runpod/skills +``` + +Do not duplicate Hugging Face or AWS setup while their first-party Codex plugins and CLIs already cover those surfaces. + +## Later Slices + +- Add provider-specific follow-up skills only after repeated real tasks show a narrow contract that official provider tools do not already cover. +- Consider a `cloud-inference-cost-review` workflow if GPU spend, idle resources, attached storage, and cleanup checks become frequent enough to justify a dedicated pass. +- Consider a `model-artifact-transfer-workflow` only if cross-provider weight, dataset, checkpoint, and cache movement becomes a repeated source of mistakes. + +## Checklist + +- [x] Create `plugins/cloud-inference-skills/` with `.codex-plugin/plugin.json`, `.mcp.json`, `AGENTS.md`, an icon asset, authored `skills/` source, and exported upstream Runpod skills. +- [x] Add `cloud-inference-skills:cloud-inference-routing-workflow`. +- [x] Bundle Runpod's official MCP server config without committing API keys. +- [x] Install Runpod's upstream `companion-clis`, `flash`, and `runpodctl` skills with `npx skills add runpod/skills`. +- [x] Wire `cloud-inference-skills` into the root Socket marketplace as an installable child plugin. +- [x] Update root README, CONTRIBUTING, and ROADMAP so users and maintainers understand the new plugin surface. +- [x] Run root metadata validation with `uv run scripts/validate_socket_metadata.py`. diff --git a/docs/maintainers/xcode-27-agentic-tooling-plan.md b/docs/maintainers/xcode-27-agentic-tooling-plan.md index b01f1dee6..a6ae11bf4 100644 --- a/docs/maintainers/xcode-27-agentic-tooling-plan.md +++ b/docs/maintainers/xcode-27-agentic-tooling-plan.md @@ -102,7 +102,7 @@ Scope: ``` - Track the difference between normal Codex config and Xcode-launched Codex config. -- Hand off broader agent configuration sync to `codex-utilities` once that plugin exposes a supported bridge/status surface. +- Hand off broader agent configuration sync to `agentdeck` once that plugin exposes a supported bridge/status surface. Non-goals: @@ -369,7 +369,7 @@ Observed import behavior: - Which Socket child plug-ins can be imported from the public Git URL with full runtime behavior, not just recognized metadata? - Can one authored skill surface be packaged for both Codex and Xcode, or does Xcode require a separate distribution artifact? -- Should Xcode-launched Codex config sync remain entirely in `codex-utilities`, with Apple Dev Skills only describing the Xcode side? +- Should Xcode-launched Codex config sync remain entirely in `agentdeck`, with Apple Dev Skills only describing the Xcode side? - Should Socket ship a dedicated Xcode plug-in artifact per child plugin, a generated aggregate Xcode manifest, or only a dry-run/apply adapter for Xcode-launched Codex until Apple's plug-in schema is public? - Which Apple Dev Skills workflow should own UIKit guidance if UIKit-specific beta changes keep accumulating? - Should beta-support notes live directly in skills, in per-skill references, or in one beta compatibility reference that skills link to? diff --git a/plugins/agent-portability-skills/.codex-plugin/plugin.json b/plugins/agent-portability-skills/.codex-plugin/plugin.json index 49d1535be..05c5f5f09 100644 --- a/plugins/agent-portability-skills/.codex-plugin/plugin.json +++ b/plugins/agent-portability-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "agent-portability-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Maintainer skills for Socket-owned agent skill portability, Codex plugin surfaces, and host adapter guidance.", "author": { "name": "Gale", diff --git a/plugins/agent-portability-skills/pyproject.toml b/plugins/agent-portability-skills/pyproject.toml index 38869798b..0dce95546 100644 --- a/plugins/agent-portability-skills/pyproject.toml +++ b/plugins/agent-portability-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agent-portability-skills-maintenance" -version = "8.1.0" +version = "8.2.0" description = "Maintainer-only Python tooling baseline for Agent Portability Skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/agent-portability-skills/uv.lock b/plugins/agent-portability-skills/uv.lock index 1fbadb01d..74824599e 100644 --- a/plugins/agent-portability-skills/uv.lock +++ b/plugins/agent-portability-skills/uv.lock @@ -8,7 +8,7 @@ resolution-markers = [ [[package]] name = "agent-portability-skills-maintenance" -version = "8.1.0" +version = "8.2.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/codex-utilities/.codex-plugin/plugin.json b/plugins/agentdeck/.codex-plugin/plugin.json similarity index 56% rename from plugins/codex-utilities/.codex-plugin/plugin.json rename to plugins/agentdeck/.codex-plugin/plugin.json index 6d0fec967..23de2b513 100644 --- a/plugins/codex-utilities/.codex-plugin/plugin.json +++ b/plugins/agentdeck/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { - "name": "codex-utilities", - "version": "8.1.0", + "name": "agentdeck", + "version": "8.2.0", "description": "Local Codex runtime utilities for thread, hook, and app-server workflows.", "author": { "name": "Gale", @@ -9,9 +9,9 @@ }, "hooks": "./hooks/hooks.json", "interface": { - "displayName": "Codex Utilities", + "displayName": "AgentDeck", "shortDescription": "Local Codex runtime helpers for hooks and thread utilities.", - "longDescription": "Codex Utilities collects small local Codex runtime helpers that do not belong to a language-specific skill pack. Its first utility captures SessionStart hook payloads so thread naming automation can be designed against real Codex app data.", + "longDescription": "AgentDeck collects small local Codex runtime helpers that do not belong to a language-specific skill pack. Its first utility captures SessionStart hook payloads so thread naming automation can be designed against real Codex app data.", "developerName": "Gale", "category": "Developer Tools", "capabilities": [ @@ -20,7 +20,7 @@ ], "defaultPrompt": "Help me inspect local Codex runtime utility behavior.", "brandColor": "#A78BFA", - "composerIcon": "./assets/codex-utilities-icon.svg", - "logo": "./assets/codex-utilities-icon.svg" + "composerIcon": "./assets/agentdeck-icon.svg", + "logo": "./assets/agentdeck-icon.svg" } } diff --git a/plugins/codex-utilities/AGENTS.md b/plugins/agentdeck/AGENTS.md similarity index 71% rename from plugins/codex-utilities/AGENTS.md rename to plugins/agentdeck/AGENTS.md index d3c88749c..bc78439e7 100644 --- a/plugins/codex-utilities/AGENTS.md +++ b/plugins/agentdeck/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md -Use this file for durable guidance inside the Codex Utilities Socket plugin. +Use this file for durable guidance inside the AgentDeck Socket plugin. ## Scope @@ -15,7 +15,7 @@ Use this file for durable guidance inside the Codex Utilities Socket plugin. - `rename` mode is the default because Codex GUI hook settings already provide the operator-facing enable/disable toggle for this behavior. - `capture` and `dry-run` modes are explicit test levers for thread-title - prefixing, enabled with `CODEX_UTILITIES_THREAD_TITLE_MODE`. + prefixing, enabled with `AGENTDECK_THREAD_TITLE_MODE`. - `Stop` is the only hook event that may prefix generated titles. By default, prefix only on the second `Stop` for a thread because the first `Stop` can run before Codex's generated title exists or before Codex's title writer has @@ -27,18 +27,18 @@ Use this file for durable guidance inside the Codex Utilities Socket plugin. - Keep the desktop bridge MCP and skill plan in `docs/desktop-bridge-mcp-skill-plan.md`. - The MCP and skill belong in this plugin because they are local Codex runtime utilities. -- The signed macOS runtime belongs in the separate `UtilitiesForCodex` app repository, not inside this plugin payload. -- Do not bundle a `.app` inside `codex-utilities`; the plugin should detect and talk to the installed app through a local transport. +- The signed macOS runtime belongs in the separate `AgentDeck` app repository, not inside this plugin payload. +- Do not bundle a `.app` inside `agentdeck`; the plugin should detect and talk to the installed app through a local transport. - Codex GUI restart coordination should follow the same split: the installed app owns pending restart requests, waiting, cancellation, status, and final quit/reopen execution; this plugin owns the MCP request/cancel/status tools and the agent-facing skill policy. -- Do not implement `when-idle` by polling Codex process state alone. Treat automatic waiting as blocked until `UtilitiesForCodex` has a supported GUI thread-status source outside the current assistant turn. +- Do not implement `when-idle` by polling Codex process state alone. Treat automatic waiting as blocked until `AgentDeck` has a supported GUI thread-status source outside the current assistant turn. ## Runtime Data -- Default runtime payload path: `~/.codex/codex-utilities/hooks/thread-title-payloads.jsonl` -- Thread title decisions are recorded in `~/.codex/codex-utilities/hooks/thread-title-decisions.jsonl` -- Per-thread rename state is recorded in `~/.codex/codex-utilities/hooks/thread-title-state.json` -- Post-tool-use summaries are recorded in `~/.codex/codex-utilities/hooks/tool-use-events.jsonl` -- Override with `CODEX_UTILITIES_DATA_DIR` when testing. +- Default runtime payload path: `~/.codex/agentdeck/hooks/thread-title-payloads.jsonl` +- Thread title decisions are recorded in `~/.codex/agentdeck/hooks/thread-title-decisions.jsonl` +- Per-thread rename state is recorded in `~/.codex/agentdeck/hooks/thread-title-state.json` +- Post-tool-use summaries are recorded in `~/.codex/agentdeck/hooks/tool-use-events.jsonl` +- Override with `AGENTDECK_DATA_DIR` when testing. - Do not store captured hook payloads in the Socket repository. ## Thread Naming Direction diff --git a/plugins/codex-utilities/assets/codex-utilities-icon.svg b/plugins/agentdeck/assets/agentdeck-icon.svg similarity index 96% rename from plugins/codex-utilities/assets/codex-utilities-icon.svg rename to plugins/agentdeck/assets/agentdeck-icon.svg index ea328e9c8..065987576 100644 --- a/plugins/codex-utilities/assets/codex-utilities-icon.svg +++ b/plugins/agentdeck/assets/agentdeck-icon.svg @@ -1,4 +1,4 @@ - + diff --git a/plugins/codex-utilities/docs/agent-configuration-sync-plan.md b/plugins/agentdeck/docs/agent-configuration-sync-plan.md similarity index 90% rename from plugins/codex-utilities/docs/agent-configuration-sync-plan.md rename to plugins/agentdeck/docs/agent-configuration-sync-plan.md index 5bf3c4198..1684e77f0 100644 --- a/plugins/codex-utilities/docs/agent-configuration-sync-plan.md +++ b/plugins/agentdeck/docs/agent-configuration-sync-plan.md @@ -1,12 +1,12 @@ -# UtilitiesForCodex Agent Configuration Sync Plan +# AgentDeck Agent Configuration Sync Plan ## Working Name -`UtilitiesForCodex` is the app and helper home for Codex-connected utilities that need a stable macOS app, local helper, permission surface, or long-lived runtime identity. +`AgentDeck` is the app and helper home for Codex-connected utilities that need a stable macOS app, local helper, permission surface, or long-lived runtime identity. -The Socket `codex-utilities` plugin is the Codex-facing connection point. The plugin should own the agent-facing docs, skills, MCP shims, hooks, and policy. The app should own the installed macOS runtime, durable local config manager, permission prompts, helper endpoints, and operator-facing UI. +The Socket `agentdeck` plugin is the Codex-facing connection point. The plugin should own the agent-facing docs, skills, MCP shims, hooks, and policy. The app should own the installed macOS runtime, durable local config manager, permission prompts, helper endpoints, and operator-facing UI. -This plan was originally drafted under the temporary name `Agent Concord`. That name described this specific feature: keep local coding agents in agreement across separate host environments without flattening their differences. The feature should now be treated as one capability inside the broader `UtilitiesForCodex` app. +This plan was originally drafted under the temporary name `Agent Concord`. That name described this specific feature: keep local coding agents in agreement across separate host environments without flattening their differences. The feature should now be treated as one capability inside the broader `AgentDeck` app. Name/context notes: @@ -53,7 +53,7 @@ Xcode Claude: ## Product Thesis -UtilitiesForCodex should include a macOS utility surface for inspecting, diffing, and syncing local agent guidance/config across multiple agent hosts. +AgentDeck should include a macOS utility surface for inspecting, diffing, and syncing local agent guidance/config across multiple agent hosts. The app exists because agent hosts are no longer a single dot-directory. A developer can have normal Codex, Codex inside Xcode, Claude inside Xcode, Codex desktop app state, CLI state, plugins, skills, MCP servers, sandbox rules, and per-project guidance. These surfaces drift independently, and raw copy/symlink sync is too risky because bundled agents may lag normal CLI versions and reject newer keys. @@ -228,12 +228,12 @@ Possible future probe: ## Socket Plugin Relationship -The Socket `codex-utilities` plugin should keep a copy of this plan because it owns the Codex-facing connection point. +The Socket `agentdeck` plugin should keep a copy of this plan because it owns the Codex-facing connection point. The split should stay clear: -- `UtilitiesForCodex` owns discovery, diff rendering, backups, writes, local validation, and any macOS permission/helper behavior. -- `socket/plugins/codex-utilities` owns skill guidance, MCP shims, hook wiring, plugin metadata, and agent policy. +- `AgentDeck` owns discovery, diff rendering, backups, writes, local validation, and any macOS permission/helper behavior. +- `socket/plugins/agentdeck` owns skill guidance, MCP shims, hook wiring, plugin metadata, and agent policy. - The plugin may expose status and request tools, but it should not directly rewrite agent homes unless that behavior is explicitly routed through the installed app or a reviewed local helper contract. This mirrors the desktop bridge split already planned for the same app/plugin pair. diff --git a/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md b/plugins/agentdeck/docs/desktop-bridge-mcp-skill-plan.md similarity index 80% rename from plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md rename to plugins/agentdeck/docs/desktop-bridge-mcp-skill-plan.md index d6a26d467..754f1dd42 100644 --- a/plugins/codex-utilities/docs/desktop-bridge-mcp-skill-plan.md +++ b/plugins/agentdeck/docs/desktop-bridge-mcp-skill-plan.md @@ -2,20 +2,20 @@ ## Summary -`codex-utilities` should own the agent-facing MCP and skill surfaces for a future desktop automation bridge, while the separate `Utilities for Codex` macOS app owns the stable installed runtime. +`agentdeck` should own the agent-facing MCP and skill surfaces for a future desktop automation bridge, while the separate `AgentDeck` macOS app owns the stable installed runtime. The plugin should feel familiar to agents trained on first-party Computer Use: a small set of explicit UI-action tools, a read-first app-state tool, and a clear confirmation policy. It should not ship or cache the signed macOS app bundle. ## Repository Split -- `gaelic-ghost/UtilitiesForCodex`: stable macOS app, signing identity, permission flow, local transport endpoint, Socket installer/status UI, and runtime diagnostics. -- `socket/plugins/codex-utilities`: MCP shim, skill guidance, confirmation policy, install/troubleshooting docs, and lightweight plugin metadata. +- `gaelic-ghost/AgentDeck`: stable macOS app, signing identity, permission flow, local transport endpoint, Socket installer/status UI, and runtime diagnostics. +- `socket/plugins/agentdeck`: MCP shim, skill guidance, confirmation policy, install/troubleshooting docs, and lightweight plugin metadata. This split keeps the macOS trust boundary stable while preserving a hot-swappable agent-facing plugin adapter. ## Why This Belongs Here -`codex-utilities` is already the Socket plugin for local Codex runtime utilities that are not language-specific, app-specific, or repository-maintenance workflows. A desktop bridge for Codex is a local Codex runtime utility. +`agentdeck` is already the Socket plugin for local Codex runtime utilities that are not language-specific, app-specific, or repository-maintenance workflows. A desktop bridge for Codex is a local Codex runtime utility. It does not belong in: @@ -26,7 +26,7 @@ It does not belong in: ## Planned MCP Surface -The initial MCP server should be a stdio adapter that talks to the installed `Utilities for Codex` app over a local transport. Unix domain sockets are the preferred first transport to evaluate. +The initial MCP server should be a stdio adapter that talks to the installed `AgentDeck` app over a local transport. Unix domain sockets are the preferred first transport to evaluate. Planned tools: @@ -47,7 +47,7 @@ Codex GUI restart tools can ship as their own small surface after the app expose ## Planned Skill Surface -Add a `desktop-bridge` skill under `plugins/codex-utilities/skills/desktop-bridge/`. +Add a `desktop-bridge` skill under `plugins/agentdeck/skills/desktop-bridge/`. The skill should tell agents: @@ -61,7 +61,7 @@ The skill should tell agents: The skill should mirror the useful shape of first-party Computer Use without copying its app-bundle packaging model. -Add a separate `codex-gui-restart` skill under `plugins/codex-utilities/skills/codex-gui-restart/`. +Add a separate `codex-gui-restart` skill under `plugins/agentdeck/skills/codex-gui-restart/`. That skill should tell agents: @@ -70,7 +70,7 @@ That skill should tell agents: - Exclude the requesting thread from the set of other active threads. - Use `if-idle` when the user wants a restart only if no other threads are active. - Use `when-idle` only when the user explicitly wants the app to wait for other active threads. -- Treat `when-idle` as blocked unless `UtilitiesForCodex` reports that it has a supported app-side thread-status source. +- Treat `when-idle` as blocked unless `AgentDeck` reports that it has a supported app-side thread-status source. - Report the scheduled restart status before ending the assistant turn. - Do not use restart tools as a generic cache refresh, plugin update, or troubleshooting step without user intent. @@ -107,12 +107,12 @@ The restart coordinator should fail closed when it cannot confirm idleness from ## Codex GUI Restart Plan -The restart workflow belongs in `codex-utilities` because it is a local Codex runtime utility. It is not an Apple development workflow, a general productivity workflow, or a repo-maintenance skill. +The restart workflow belongs in `agentdeck` because it is a local Codex runtime utility. It is not an Apple development workflow, a general productivity workflow, or a repo-maintenance skill. The app/plugin split should be: -- `UtilitiesForCodex`: owns pending restart requests, cancellation, status, waiting behavior, and final macOS quit/reopen execution. -- `codex-utilities` MCP shim: exposes request, cancel, and status tools that talk to the app over the local transport. +- `AgentDeck`: owns pending restart requests, cancellation, status, waiting behavior, and final macOS quit/reopen execution. +- `agentdeck` MCP shim: exposes request, cancel, and status tools that talk to the app over the local transport. - `codex-gui-restart` skill: tells agents when it is safe to call those tools and how to report the result. The first restart implementation should support `if-idle` before `when-idle`. @@ -154,12 +154,12 @@ Open questions: ### Slice 1: Plan and App Baseline - Add this plan. -- Keep `codex-utilities` metadata hook-only until a real MCP server exists. -- Bootstrap `UtilitiesForCodex` as the separate macOS runtime app. +- Keep `agentdeck` metadata hook-only until a real MCP server exists. +- Bootstrap `AgentDeck` as the separate macOS runtime app. ### Slice 2: Bridge Status MCP -- Add a small MCP server under `plugins/codex-utilities/mcp/desktop-bridge/`. +- Add a small MCP server under `plugins/agentdeck/mcp/desktop-bridge/`. - Implement `get_bridge_status()` only. - Return useful missing-app and missing-transport diagnostics. - Add plugin metadata only when the server is runnable. @@ -182,13 +182,13 @@ Open questions: ### Slice 6: Codex GUI Restart Tools -- Add restart request, cancellation, and status tools once `UtilitiesForCodex` exposes the coordinator endpoint. +- Add restart request, cancellation, and status tools once `AgentDeck` exposes the coordinator endpoint. - Implement `if-idle` first using assistant-provided observed thread state. - Return blocked diagnostics for `when-idle` until a supported app-side thread-status source exists. - Add `skills/codex-gui-restart/SKILL.md` with the explicit user-intent, active-thread inspection, and final-status reporting rules. ## Current Decision -Plan the MCP and skill inside `codex-utilities`, but keep the actual app runtime in the public `gaelic-ghost/UtilitiesForCodex` repository. +Plan the MCP and skill inside `agentdeck`, but keep the actual app runtime in the public `gaelic-ghost/AgentDeck` repository. -For Codex GUI restart coordination, keep the waiting and restart execution in `UtilitiesForCodex`; keep the agent-facing request/cancel/status tools and operational skill in `codex-utilities`. Do not claim automatic `when-idle` support until the installed app has a supported thread-status source outside the current assistant turn. +For Codex GUI restart coordination, keep the waiting and restart execution in `AgentDeck`; keep the agent-facing request/cancel/status tools and operational skill in `agentdeck`. Do not claim automatic `when-idle` support until the installed app has a supported thread-status source outside the current assistant turn. diff --git a/plugins/codex-utilities/docs/thread-title-hooks.md b/plugins/agentdeck/docs/thread-title-hooks.md similarity index 83% rename from plugins/codex-utilities/docs/thread-title-hooks.md rename to plugins/agentdeck/docs/thread-title-hooks.md index d4495597e..07ed4ee60 100644 --- a/plugins/codex-utilities/docs/thread-title-hooks.md +++ b/plugins/agentdeck/docs/thread-title-hooks.md @@ -1,13 +1,13 @@ # Codex Thread Title Hook Notes -Codex Utilities provides `SessionStart` and `Stop` hooks for prefixing generated +AgentDeck provides `SessionStart` and `Stop` hooks for prefixing generated thread titles with the project directory name, plus a `PostToolUse` diagnostic hook for timing research. By default, a trusted and enabled hook renames project threads; disable the hook in Codex GUI settings to turn the behavior off. ## Name -The plugin is named `codex-utilities` because this work is about Codex runtime +The plugin is named `agentdeck` because this work is about Codex runtime behavior rather than a language, framework, app, or repository-maintenance domain. It follows the Socket convention of hyphen-case plugin IDs with a reader-facing display name in plugin metadata. @@ -28,32 +28,32 @@ Codex GUI and trusting the plugin hooks. The script appends stdin to: ```text -~/.codex/codex-utilities/hooks/thread-title-payloads.jsonl +~/.codex/agentdeck/hooks/thread-title-payloads.jsonl ``` It also writes structured hook decisions to: ```text -~/.codex/codex-utilities/hooks/thread-title-decisions.jsonl +~/.codex/agentdeck/hooks/thread-title-decisions.jsonl ``` Per-thread rename state is written to: ```text -~/.codex/codex-utilities/hooks/thread-title-state.json +~/.codex/agentdeck/hooks/thread-title-state.json ``` Post-tool-use summaries are written to: ```text -~/.codex/codex-utilities/hooks/tool-use-events.jsonl +~/.codex/agentdeck/hooks/tool-use-events.jsonl ``` -Set `CODEX_UTILITIES_DATA_DIR` to redirect these paths during tests. +Set `AGENTDECK_DATA_DIR` to redirect these paths during tests. ## Thread Title Modes -`CODEX_UTILITIES_THREAD_TITLE_MODE` controls the title behavior: +`AGENTDECK_THREAD_TITLE_MODE` controls the title behavior: - `rename` is the default. It uses the `Stop` hook to read the generated title and then call App Server `thread/name/set` once per thread. @@ -68,12 +68,12 @@ that hook fires. The second `Stop` reads the current generated title with App Server `thread/read`, prefixes it, and records per-thread state so later turns do not keep rewriting the title. -`CODEX_UTILITIES_THREAD_TITLE_MIN_STOP_COUNT` controls the Stop count threshold. +`AGENTDECK_THREAD_TITLE_MIN_STOP_COUNT` controls the Stop count threshold. The default is `2`. Set it to `1` only when deliberately testing first-turn renames. The prefix is the last path component of `cwd`, truncated to -`CODEX_UTILITIES_THREAD_TITLE_MAX_PREFIX_LENGTH` characters. The default maximum +`AGENTDECK_THREAD_TITLE_MAX_PREFIX_LENGTH` characters. The default maximum is `48`. The generated title is preserved after the prefix: ```text @@ -88,9 +88,9 @@ the default Codex chat root: ``` the hook skips prefixing by default so projectless chats keep Codex's generated -title. Override the root with `CODEX_UTILITIES_PROJECTLESS_ROOT`. To opt into a +title. Override the root with `AGENTDECK_PROJECTLESS_ROOT`. To opt into a shared projectless prefix such as `Chat`, set -`CODEX_UTILITIES_PROJECTLESS_THREAD_PREFIX`. +`AGENTDECK_PROJECTLESS_THREAD_PREFIX`. The thread id candidate is read from `thread_id`, `threadId`, `session_id`, then `sessionId`. Current Codex hook docs describe `session_id`. @@ -102,7 +102,7 @@ A live projectless thread created after trusting the plugin hook produced this { "session_id": "019e9e4e-e0c5-7591-ac1d-51c09ef83faa", "transcript_path": "~/.codex/sessions/2026/06/06/rollout-2026-06-06T15-00-30-019e9e4e-e0c5-7591-ac1d-51c09ef83faa.jsonl", - "cwd": "~/Documents/Codex/2026-06-06/codex-utilities-projectless-hook-test", + "cwd": "~/Documents/Codex/2026-06-06/agentdeck-projectless-hook-test", "hook_event_name": "SessionStart", "model": "gpt-5.5", "permission_mode": "default", @@ -133,13 +133,13 @@ The hook's rename mode starts a short-lived App Server JSONL stdio process: codex app-server ``` -Override the command with `CODEX_UTILITIES_APP_SERVER_COMMAND`. The hook sends +Override the command with `AGENTDECK_APP_SERVER_COMMAND`. The hook sends `initialize`, `initialized`, `thread/read`, and `thread/name/set` over stdio. This path works with the regular CLI install and does not require the managed app-server daemon or the standalone Codex installer. -`CODEX_UTILITIES_THREAD_TITLE_POLL_ATTEMPTS` and -`CODEX_UTILITIES_THREAD_TITLE_POLL_DELAY_MS` control the bounded wait for Codex's +`AGENTDECK_THREAD_TITLE_POLL_ATTEMPTS` and +`AGENTDECK_THREAD_TITLE_POLL_DELAY_MS` control the bounded wait for Codex's generated title during the `Stop` hook. If the title is still missing when the poll expires, the hook skips the rename and can try again on a later `Stop`. @@ -181,14 +181,14 @@ Before testing, confirm the active Codex config uses the current feature keys: `features.plugin_hooks` are not required and should not appear in operator guidance. -An installed `codex-utilities@socket` 6.16.0 probe initially did not expose the +An installed `agentdeck@socket` 6.16.0 probe initially did not expose the plugin-bundled `SessionStart` hook until the Codex GUI was restarted. After the restart, the hook appeared in settings, was trusted, and captured real `SessionStart` payloads. 1. Install or refresh the Socket marketplace plugin locally. 2. Confirm the hook source is visible in Codex hook settings or `/hooks`. -3. Trust the `codex-utilities` `SessionStart`, `Stop`, and `PostToolUse` hooks +3. Trust the `agentdeck` `SessionStart`, `Stop`, and `PostToolUse` hooks if they appear. 4. Start a new thread in a known working directory. 5. Confirm `thread-title-decisions.jsonl` records `SessionStart` and `Stop` @@ -198,7 +198,7 @@ restart, the hook appeared in settings, was trusted, and captured real second `Stop` event. 8. Inspect `tool-use-events.jsonl` to see whether title generation appears as a hook-visible tool event. -9. Use `CODEX_UTILITIES_THREAD_TITLE_MODE=capture` or `dry-run` only when +9. Use `AGENTDECK_THREAD_TITLE_MODE=capture` or `dry-run` only when debugging the hook without mutating thread metadata. 10. Keep the model-mediated prefix route as a comparison path if direct App Server renaming loses too much of Codex's generated-title quality. diff --git a/plugins/codex-utilities/hooks/capture-session-start.sh b/plugins/agentdeck/hooks/capture-session-start.sh similarity index 100% rename from plugins/codex-utilities/hooks/capture-session-start.sh rename to plugins/agentdeck/hooks/capture-session-start.sh diff --git a/plugins/codex-utilities/hooks/hooks.json b/plugins/agentdeck/hooks/hooks.json similarity index 77% rename from plugins/codex-utilities/hooks/hooks.json rename to plugins/agentdeck/hooks/hooks.json index a38ca8035..c9e00c05b 100644 --- a/plugins/codex-utilities/hooks/hooks.json +++ b/plugins/agentdeck/hooks/hooks.json @@ -7,7 +7,7 @@ { "type": "command", "command": "sh ${PLUGIN_ROOT}/hooks/run-thread-title-hook.sh", - "statusMessage": "Running Codex Utilities SessionStart hook", + "statusMessage": "Running AgentDeck SessionStart hook", "timeout": 10 } ] @@ -19,7 +19,7 @@ { "type": "command", "command": "sh ${PLUGIN_ROOT}/hooks/run-thread-title-hook.sh", - "statusMessage": "Running Codex Utilities Stop hook", + "statusMessage": "Running AgentDeck Stop hook", "timeout": 10 } ] @@ -31,7 +31,7 @@ { "type": "command", "command": "sh ${PLUGIN_ROOT}/hooks/run-thread-title-hook.sh", - "statusMessage": "Logging Codex Utilities tool-use hook", + "statusMessage": "Logging AgentDeck tool-use hook", "timeout": 10 } ] diff --git a/plugins/codex-utilities/hooks/run-thread-title-hook.sh b/plugins/agentdeck/hooks/run-thread-title-hook.sh similarity index 100% rename from plugins/codex-utilities/hooks/run-thread-title-hook.sh rename to plugins/agentdeck/hooks/run-thread-title-hook.sh diff --git a/plugins/codex-utilities/scripts/session-start-hook.mjs b/plugins/agentdeck/scripts/session-start-hook.mjs similarity index 95% rename from plugins/codex-utilities/scripts/session-start-hook.mjs rename to plugins/agentdeck/scripts/session-start-hook.mjs index b002bff2e..f596d8ee6 100644 --- a/plugins/codex-utilities/scripts/session-start-hook.mjs +++ b/plugins/agentdeck/scripts/session-start-hook.mjs @@ -194,38 +194,38 @@ function toolUseSummaryFromPayload(payload, config) { function readConfig() { const dataDir = - process.env.CODEX_UTILITIES_DATA_DIR ?? - path.join(os.homedir(), ".codex", "codex-utilities", "hooks"); - const mode = modeFromEnv(process.env.CODEX_UTILITIES_THREAD_TITLE_MODE); + process.env.AGENTDECK_DATA_DIR ?? + path.join(os.homedir(), ".codex", "agentdeck", "hooks"); + const mode = modeFromEnv(process.env.AGENTDECK_THREAD_TITLE_MODE); const maxPrefixLength = positiveIntegerFromEnv( - process.env.CODEX_UTILITIES_THREAD_TITLE_MAX_PREFIX_LENGTH, + process.env.AGENTDECK_THREAD_TITLE_MAX_PREFIX_LENGTH, 48, ); const projectlessRoot = - process.env.CODEX_UTILITIES_PROJECTLESS_ROOT ?? + process.env.AGENTDECK_PROJECTLESS_ROOT ?? path.join(os.homedir(), "Documents", "Codex"); const projectlessThreadPrefix = optionalTrimmedStringFromEnv( - process.env.CODEX_UTILITIES_PROJECTLESS_THREAD_PREFIX, + process.env.AGENTDECK_PROJECTLESS_THREAD_PREFIX, ); const timeoutMs = positiveIntegerFromEnv( - process.env.CODEX_UTILITIES_APP_SERVER_TIMEOUT_MS, + process.env.AGENTDECK_APP_SERVER_TIMEOUT_MS, 2500, ); const titlePollAttempts = positiveIntegerFromEnv( - process.env.CODEX_UTILITIES_THREAD_TITLE_POLL_ATTEMPTS, + process.env.AGENTDECK_THREAD_TITLE_POLL_ATTEMPTS, 4, ); const titlePollDelayMs = positiveIntegerFromEnv( - process.env.CODEX_UTILITIES_THREAD_TITLE_POLL_DELAY_MS, + process.env.AGENTDECK_THREAD_TITLE_POLL_DELAY_MS, 500, ); const minStopCountBeforeRename = positiveIntegerFromEnv( - process.env.CODEX_UTILITIES_THREAD_TITLE_MIN_STOP_COUNT, + process.env.AGENTDECK_THREAD_TITLE_MIN_STOP_COUNT, 2, ); return { - appServerCommand: process.env.CODEX_UTILITIES_APP_SERVER_COMMAND ?? "codex", + appServerCommand: process.env.AGENTDECK_APP_SERVER_COMMAND ?? "codex", appServerArgs: ["app-server"], dataDir, decisionLogPath: path.join(dataDir, "thread-title-decisions.jsonl"), @@ -385,8 +385,8 @@ async function withAppServerClient(config, callback) { await client.start(); await client.request("initialize", { clientInfo: { - name: "codex_utilities_hook", - title: "Codex Utilities Hook", + name: "agentdeck_hook", + title: "AgentDeck Hook", version: config.pluginVersion, }, capabilities: { diff --git a/plugins/android-dev-skills/.codex-plugin/plugin.json b/plugins/android-dev-skills/.codex-plugin/plugin.json index d31f1db2a..17df5a23a 100644 --- a/plugins/android-dev-skills/.codex-plugin/plugin.json +++ b/plugins/android-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "android-dev-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Android, Kotlin, Java, Gradle, Android Gradle Plugin, testing, lint, UI implementation, and release-readiness workflow skills.", "author": { "name": "Gale", diff --git a/plugins/apple-dev-skills/.codex-plugin/plugin.json b/plugins/apple-dev-skills/.codex-plugin/plugin.json index 5be3eb533..e75325dc6 100644 --- a/plugins/apple-dev-skills/.codex-plugin/plugin.json +++ b/plugins/apple-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "apple-dev-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Apple development workflows for Codex, including media and audio repair, Xcode coding intelligence, SwiftUI animation and architecture, Core Animation, Apple typography, SF Symbols, AppKit architecture, Icon Composer app icons, Safari extensions, DeviceCheck/App Attest, Swift OpenAPI clients, and DocC authoring guidance.", "author": { "name": "Gale", diff --git a/plugins/apple-dev-skills/pyproject.toml b/plugins/apple-dev-skills/pyproject.toml index 27b1eba50..b00417cd3 100644 --- a/plugins/apple-dev-skills/pyproject.toml +++ b/plugins/apple-dev-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "apple-dev-skills-maintainer" -version = "8.1.0" +version = "8.2.0" description = "Maintainer tooling for the apple-dev-skills repository" requires-python = ">=3.10" dependencies = [] diff --git a/plugins/apple-dev-skills/uv.lock b/plugins/apple-dev-skills/uv.lock index 27e80ca39..6409322b1 100644 --- a/plugins/apple-dev-skills/uv.lock +++ b/plugins/apple-dev-skills/uv.lock @@ -4,7 +4,7 @@ requires-python = ">=3.10" [[package]] name = "apple-dev-skills-maintainer" -version = "8.1.0" +version = "8.2.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/cardhop-app/.codex-plugin/plugin.json b/plugins/cardhop-app/.codex-plugin/plugin.json index e4ea545a9..49eca954c 100644 --- a/plugins/cardhop-app/.codex-plugin/plugin.json +++ b/plugins/cardhop-app/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cardhop-app", - "version": "8.1.0", + "version": "8.2.0", "description": "Cardhop.app workflow guidance plus a bundled local MCP server for contact capture and updates on macOS.", "author": { "name": "Gale", diff --git a/plugins/cardhop-app/mcp/pyproject.toml b/plugins/cardhop-app/mcp/pyproject.toml index 1b9a22a18..ad37cdc29 100644 --- a/plugins/cardhop-app/mcp/pyproject.toml +++ b/plugins/cardhop-app/mcp/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "cardhop-app-mcp" -version = "8.1.0" +version = "8.2.0" requires-python = ">=3.13" dependencies = [ "fastmcp>=3.0.2", diff --git a/plugins/cardhop-app/mcp/uv.lock b/plugins/cardhop-app/mcp/uv.lock index 532a36e96..30f4d85f9 100644 --- a/plugins/cardhop-app/mcp/uv.lock +++ b/plugins/cardhop-app/mcp/uv.lock @@ -138,7 +138,7 @@ wheels = [ [[package]] name = "cardhop-app-mcp" -version = "8.1.0" +version = "8.2.0" source = { virtual = "." } dependencies = [ { name = "fastmcp" }, diff --git a/plugins/cloud-deployment-skills/.codex-plugin/plugin.json b/plugins/cloud-deployment-skills/.codex-plugin/plugin.json index b8579e8b1..03eb5d35d 100644 --- a/plugins/cloud-deployment-skills/.codex-plugin/plugin.json +++ b/plugins/cloud-deployment-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "cloud-deployment-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Codex skills for routing cloud deployment work through official provider plugins, MCP servers, CLIs, and Socket-owned deployment guidance.", "author": { "name": "Gale", diff --git a/plugins/cloud-inference-skills/.agents/skills/cloud-inference-routing-workflow b/plugins/cloud-inference-skills/.agents/skills/cloud-inference-routing-workflow new file mode 120000 index 000000000..eaf18b46c --- /dev/null +++ b/plugins/cloud-inference-skills/.agents/skills/cloud-inference-routing-workflow @@ -0,0 +1 @@ +../../skills/cloud-inference-routing-workflow \ No newline at end of file diff --git a/plugins/cloud-inference-skills/.agents/skills/companion-clis b/plugins/cloud-inference-skills/.agents/skills/companion-clis new file mode 120000 index 000000000..21d9cbad8 --- /dev/null +++ b/plugins/cloud-inference-skills/.agents/skills/companion-clis @@ -0,0 +1 @@ +../../skills/companion-clis \ No newline at end of file diff --git a/plugins/cloud-inference-skills/.agents/skills/flash b/plugins/cloud-inference-skills/.agents/skills/flash new file mode 120000 index 000000000..1fa58d9f3 --- /dev/null +++ b/plugins/cloud-inference-skills/.agents/skills/flash @@ -0,0 +1 @@ +../../skills/flash \ No newline at end of file diff --git a/plugins/cloud-inference-skills/.agents/skills/runpodctl b/plugins/cloud-inference-skills/.agents/skills/runpodctl new file mode 120000 index 000000000..29adabfdf --- /dev/null +++ b/plugins/cloud-inference-skills/.agents/skills/runpodctl @@ -0,0 +1 @@ +../../skills/runpodctl \ No newline at end of file diff --git a/plugins/cloud-inference-skills/.codex-plugin/plugin.json b/plugins/cloud-inference-skills/.codex-plugin/plugin.json new file mode 100644 index 000000000..b332620c9 --- /dev/null +++ b/plugins/cloud-inference-skills/.codex-plugin/plugin.json @@ -0,0 +1,50 @@ +{ + "name": "cloud-inference-skills", + "version": "8.2.0", + "description": "Cloud AI inference workflow skills for routing model serving, training, conversion, and GPU infrastructure work across Runpod, Hugging Face, AWS, Vast.ai, CoreWeave, and similar providers.", + "author": { + "name": "Gale", + "email": "mail@galewilliams.com", + "url": "https://github.com/gaelic-ghost" + }, + "homepage": "https://github.com/gaelic-ghost/socket/tree/main/plugins/cloud-inference-skills", + "repository": "https://github.com/gaelic-ghost/socket", + "license": "Apache-2.0", + "keywords": [ + "codex", + "plugin", + "skills", + "cloud", + "inference", + "gpu", + "runpod", + "hugging-face", + "aws", + "lambda", + "vast-ai", + "coreweave", + "mcp" + ], + "skills": "./skills/", + "mcpServers": "./.mcp.json", + "interface": { + "displayName": "Cloud Inference Skills", + "shortDescription": "Cloud GPU inference and training routing guidance for Codex.", + "longDescription": "Guide Codex agents through cloud AI inference, training, model conversion, endpoint deployment, and GPU infrastructure decisions. The first slice favors Runpod, Hugging Face, AWS, Vast.ai, and CoreWeave, bundles Runpod's official MCP server configuration, includes a project-scoped upstream Runpod skill mirror, and routes Hugging Face and AWS work through their first-party Codex plugins and CLIs when those are already the stronger maintained surface.", + "developerName": "Gale", + "category": "Developer Tools", + "capabilities": [ + "Read", + "Write" + ], + "websiteURL": "https://github.com/gaelic-ghost/socket/tree/main/plugins/cloud-inference-skills", + "defaultPrompt": [ + "Choose the right cloud GPU inference or training path for this model and budget.", + "Route this Runpod, Hugging Face, AWS, Vast.ai, or CoreWeave inference task through the safest available official tool, MCP server, CLI, or Socket guidance.", + "Help me decide between quick managed inference, cheap flexible GPU infrastructure, and providers I already know." + ], + "brandColor": "#D946EF", + "composerIcon": "./assets/cloud-inference-icon.svg", + "logo": "./assets/cloud-inference-icon.svg" + } +} diff --git a/plugins/cloud-inference-skills/.mcp.json b/plugins/cloud-inference-skills/.mcp.json new file mode 100644 index 000000000..d33870f97 --- /dev/null +++ b/plugins/cloud-inference-skills/.mcp.json @@ -0,0 +1,16 @@ +{ + "mcpServers": { + "runpod": { + "command": "npx", + "args": [ + "-y", + "@runpod/mcp-server@latest" + ], + "note": "Registers Runpod's official API MCP server for Pods, Serverless endpoints, templates, network volumes, and registries. The server requires RUNPOD_API_KEY in the Codex MCP environment; keep the key out of git and confirm account, resource, and cost boundaries before mutation." + }, + "runpod-docs": { + "url": "https://docs.runpod.io/mcp", + "note": "Registers Runpod's official unauthenticated documentation MCP server for Runpod feature, guide, and code-example lookup." + } + } +} diff --git a/plugins/cloud-inference-skills/AGENTS.md b/plugins/cloud-inference-skills/AGENTS.md new file mode 100644 index 000000000..67b741fcc --- /dev/null +++ b/plugins/cloud-inference-skills/AGENTS.md @@ -0,0 +1,26 @@ +# AGENTS.md + +This file is the Cloud Inference Skills child-repo override for work done from `socket`. Follow the root `socket` guidance for general git, docs, release, branch, dependency-provenance, and maintainer workflow rules. + +## Scope + +- `cloud-inference-skills` is a monorepo-owned Socket child and the canonical source of truth for shipped cloud AI inference, training, conversion, and GPU infrastructure routing skills. +- Root [`skills/`](./skills/) is the authored workflow surface. +- The repo root is the Codex plugin root through [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json). +- Keep this plugin focused on provider selection, official-tool routing, inference readiness, GPU cost boundaries, model artifact handling, and cross-provider handoffs. +- Keep application implementation in the owning stack plugins such as `python-skills`, `server-side-swift`, `web-dev-skills`, `rust-skills`, `server-side-jvm`, and `cloud-deployment-skills`. + +## Local Rules + +- Match the `socket` shared semantic version exactly; use the Socket root release workflow for version inventory and bumps. +- Prefer official provider plugins, MCP servers, CLIs, SDKs, and docs before adding Socket-authored setup guidance. +- Treat Runpod, Hugging Face, and AWS as preferred familiar surfaces when they fit the requested inference or training job. +- For Runpod work, use the bundled Runpod MCP config when resource management or docs lookup benefits from MCP, and treat `skills/companion-clis`, `skills/flash`, and `skills/runpodctl` as upstream Runpod skills tracked by `skills-lock.json`. +- Keep `.agents/skills` as a symlink discovery mirror of the exported root `skills/` directories. +- Do not hand-edit the upstream Runpod skill mirror. Refresh it with `npx skills update` or reinstall with `npx skills add runpod/skills` from this plugin root, then review the diff and security notes before committing. +- For Hugging Face work, prefer the installed Hugging Face Codex plugin and official `huggingface_hub` CLI before adding Socket-owned API or repo-management guidance. +- For AWS work, prefer the official AWS Agent Toolkit and AWS CLI or SDK surfaces before adding Socket-owned AWS guidance. Treat AWS Lambda inference as a fit only for small, latency-tolerant CPU or accelerator-backed workloads; route GPU or large-model serving to SageMaker, Bedrock, ECS/EKS, Batch, or another provider unless current AWS docs and project constraints support Lambda. +- For Vast.ai and CoreWeave work, keep the first pass routing-oriented unless the task has concrete account, image, scheduler, storage, networking, and teardown requirements. +- Treat provider credentials, account configuration, API mutation, billing, model weights, private datasets, generated artifacts, and production endpoints as high-impact operations. Verify the account, region, resource, image, model license boundary, expected cost, and cleanup path before taking action. +- Do not commit API keys, cloud profiles, `.env` files, model weights, private datasets, generated model artifacts, cloud state, or local cache paths. +- Use repo-local files, checked-out provider config, provider CLIs, provider MCP servers, and official provider documentation before making claims about current inference behavior. diff --git a/plugins/cloud-inference-skills/assets/cloud-inference-icon.svg b/plugins/cloud-inference-skills/assets/cloud-inference-icon.svg new file mode 100644 index 000000000..4f3f7216d --- /dev/null +++ b/plugins/cloud-inference-skills/assets/cloud-inference-icon.svg @@ -0,0 +1,40 @@ + + Cloud Inference Skills icon + Neon cloud GPU badge with a circuit core and inference beam. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/plugins/cloud-inference-skills/skills-lock.json b/plugins/cloud-inference-skills/skills-lock.json new file mode 100644 index 000000000..fff1608d0 --- /dev/null +++ b/plugins/cloud-inference-skills/skills-lock.json @@ -0,0 +1,23 @@ +{ + "version": 1, + "skills": { + "companion-clis": { + "source": "runpod/skills", + "sourceType": "github", + "skillPath": "companion-clis/SKILL.md", + "computedHash": "3d0ef187d4888a0c7e7b35861a939877dbf1dde577f440ca9c8fe7c04773934c" + }, + "flash": { + "source": "runpod/skills", + "sourceType": "github", + "skillPath": "flash/SKILL.md", + "computedHash": "4f52fd8434d1ddff088b8923a1bc744dcb3d2e06f74509e2ad0336ad9128a947" + }, + "runpodctl": { + "source": "runpod/skills", + "sourceType": "github", + "skillPath": "runpodctl/SKILL.md", + "computedHash": "1a9b6033b13915fc75bc66c77b3ff14e6633b267d5ca8056bff8c3509efbfc06" + } + } +} diff --git a/plugins/cloud-inference-skills/skills/cloud-inference-routing-workflow/SKILL.md b/plugins/cloud-inference-skills/skills/cloud-inference-routing-workflow/SKILL.md new file mode 100644 index 000000000..88bb5f142 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/cloud-inference-routing-workflow/SKILL.md @@ -0,0 +1,123 @@ +--- +name: cloud-inference-routing-workflow +description: Choose the right cloud AI inference, model training, model conversion, or GPU infrastructure path before implementation. Use when Codex works with Runpod, Hugging Face, AWS, AWS Lambda inference, Vast.ai, CoreWeave, GPU Pods, Serverless GPU endpoints, model weights, vLLM, TGI, SGLang, custom containers, LoRA/adapters, dataset upload, model conversion, cheap GPU rentals, or managed inference endpoints. +--- + +# Cloud Inference Routing Workflow + +## Purpose + +Choose the smallest correct cloud AI inference path before changing provider resources, spending GPU budget, moving model weights, or deploying endpoints. + +The practical decision is whether the agent should use an official provider plugin, provider MCP server, provider CLI, SDK, managed inference endpoint, rented GPU instance, cluster platform, or a stack-owned implementation workflow. + +## Source Check + +Use repo-local model code, Dockerfiles, provider configs, checked-out scripts, installed provider plugins, installed provider CLIs, bundled MCP servers, and official provider documentation before making claims about current behavior. + +Preferred official sources: + +- Runpod docs and bundled MCP servers for Runpod Pods, Serverless, Flash, templates, volumes, registries, and docs lookup. +- Hugging Face plugin and `huggingface_hub` CLI for Hub repos, models, datasets, Spaces, Inference Endpoints, jobs, and papers. +- AWS Agent Toolkit, AWS CLI, AWS SDKs, and AWS docs for Lambda, SageMaker, Bedrock, ECS, EKS, Batch, IAM, billing, and observability. +- Vast.ai docs and CLI for low-cost rented GPU instances. +- CoreWeave docs for Kubernetes-backed GPU infrastructure, clusters, storage, networking, and observability. + +Translate documentation into the concrete project decision it changes. + +## Routing Workflow + +1. Inspect the workload: + - task: inference endpoint, batch inference, fine-tuning, full training, eval, model conversion, quantization, benchmark, notebook, or one-off GPU shell + - model family, parameter count, precision, context length, adapters, tokenizer, and required runtime + - expected VRAM, CPU RAM, disk, network, container image, driver, CUDA, and startup time + - latency, throughput, concurrency, cold-start tolerance, uptime, privacy, and cleanup needs + - artifact flow: model weights, private datasets, outputs, logs, checkpoints, and caches +2. Choose the provider lane: + - quick managed inference + - quick custom endpoint + - cheap flexible GPU box + - training or conversion workspace + - Kubernetes or production cluster + - existing provider familiarity +3. Prefer familiar first-party paths when they fit: + - Runpod for fast GPU Pods, Serverless endpoints, Flash, cheap/flexible experiments, templates, and resource management through MCP. + - Hugging Face for model and dataset repos, conversion/publishing workflows, Inference Endpoints, Spaces, jobs, and Hub-native collaboration. + - AWS when the project already uses AWS accounts, IAM, S3, CloudWatch, Lambda, SageMaker, Bedrock, ECS, EKS, or Batch. +4. Route to official tools: + - Use `runpod` MCP for Runpod resource mutations and `runpod-docs` MCP for docs lookup when available. + - Use the upstream Runpod skills under the exported `skills/` tree for Runpod `flash`, `runpodctl`, and companion CLI details. Refresh those skills with `npx skills update` or `npx skills add runpod/skills` instead of hand-editing them. + - Use the Hugging Face Codex plugin and Hugging Face CLI for Hub, model, dataset, Space, endpoint, or job work when available. + - Use the AWS Agent Toolkit and AWS CLI or SDKs for AWS inference work when available. + - Use provider CLIs or docs for Vast.ai and CoreWeave until a provider-owned agent surface is available or a concrete repeated Socket workflow justifies a new slice. +5. Confirm boundaries before mutation: + - provider account, project, region, org, namespace, and budget + - API key or profile source + - model and dataset license or private-use boundary + - exact resources to create, update, stop, delete, or scale + - expected hourly cost, storage cost, bandwidth cost, idle behavior, and teardown path +6. Choose validation: + - read-only docs, list, or pricing query for planning + - local smoke test or CPU fallback before GPU spend + - minimal GPU probe before full training or endpoint deployment + - endpoint health, latency, throughput, logs, and cost check after deployment + - cleanup verification for stopped Pods, terminated instances, deleted endpoints, detached volumes, and lingering storage + +## Provider Fit + +### Runpod + +Use Runpod first when Gale wants quick and easy GPU access, cheap/flexible infrastructure, Serverless endpoints, GPU Pods, Flash, templates, network volumes, or direct resource management from an agent. + +Use `runpod-docs` MCP for docs questions. Use `runpod` MCP for resource operations after confirming `RUNPOD_API_KEY`, account, resource name, GPU type, cost, and cleanup. + +Use the installed upstream Runpod skills for details: + +- `skills/flash` for `runpod-flash` SDK and CLI workflows. +- `skills/runpodctl` for Runpod CLI workflows. +- `skills/companion-clis` for Hugging Face, GitHub, Docker, and AWS CLI support commonly needed around Runpod deployments. + +### Hugging Face + +Use Hugging Face first when the work is model or dataset centered: Hub repos, checkpoints, safetensors, GGUF or Core ML conversion artifacts, datasets, evals, Spaces, Inference Endpoints, or sharing/publishing. + +Prefer the installed Hugging Face Codex plugin and official CLI. Do not reimplement Hub auth, repo management, or endpoint setup in Socket unless a small routing note removes real ambiguity. + +### AWS And Lambda + +Use AWS first when the project already depends on AWS IAM, S3, CloudWatch, Lambda, SageMaker, Bedrock, ECS, EKS, or Batch. + +Treat Lambda inference as a narrow fit: small models, lightweight CPU inference, short-lived request handlers, or calls out to Bedrock/SageMaker/hosted endpoints. For large GPU models, training, conversions, or long warmup services, route toward SageMaker, Bedrock, ECS/EKS GPU infrastructure, Batch, or another GPU provider rather than assuming Lambda is the right runtime. + +### Vast.ai + +Use Vast.ai when cost and flexibility matter more than managed endpoint ergonomics, especially for one-off training, conversion, experimentation, benchmarks, or shell access on rented GPUs. + +Require stronger cleanup and artifact handling: rented instances, volumes, SSH keys, exposed ports, docker images, and checkpoint transfers are the work. + +### CoreWeave + +Use CoreWeave when the job is cluster-shaped: Kubernetes, production GPU services, larger training, persistent storage, network policy, observability, or enterprise-grade GPU infrastructure. + +Do not route a quick experiment to CoreWeave unless the project already has CoreWeave cluster access or the user explicitly wants that platform. + +## Output Shape + +Return: + +1. `Workload`: inference endpoint, batch job, training, conversion, eval, benchmark, or exploration. +2. `Provider`: Runpod, Hugging Face, AWS, Vast.ai, CoreWeave, multi-provider, or undecided. +3. `Primary surface`: official plugin, MCP server, provider CLI, SDK, stack skill, or user decision needed. +4. `Credential boundary`: API key, profile, org, account, region, and whether credentials are required for the next step. +5. `Cost boundary`: expected GPU, storage, bandwidth, idle, and teardown concerns. +6. `Mutation boundary`: read-only, local-only, create endpoint, create instance, train, scale, stop, delete, or blocked. +7. `Validation path`: exact commands, MCP checks, or provider-console checks before and after mutation. +8. `Next handoff`: provider plugin, provider docs, stack skill, Runpod MCP, Hugging Face plugin, AWS Agent Toolkit, or Socket backlog item. + +## Guardrails + +- Do not move model weights, upload datasets, create endpoints, create GPU instances, scale resources, or delete resources without confirming account, credential, cost, and cleanup boundaries. +- Do not commit API keys, cloud profiles, `.env` files, model weights, private datasets, generated model artifacts, or local cache paths. +- Do not duplicate Hugging Face or AWS plugin capabilities in Socket while those first-party plugins are installed and fit the task. +- Do not treat an MCP server as better than an HTTP API, CLI, or official plugin unless it improves agent safety, discovery, or resource control for the requested work. +- Do not claim training, inference quality, latency, throughput, hardware availability, or provider pricing without live evidence from the provider, a command, or a current docs check. diff --git a/plugins/cloud-inference-skills/skills/companion-clis/SKILL.md b/plugins/cloud-inference-skills/skills/companion-clis/SKILL.md new file mode 100644 index 000000000..c5527fd1f --- /dev/null +++ b/plugins/cloud-inference-skills/skills/companion-clis/SKILL.md @@ -0,0 +1,422 @@ +--- +name: companion-clis +description: Companion CLIs for Runpod workflows — HuggingFace, GitHub, Docker, and AWS. +allowed-tools: Bash(hf:*), Bash(gh:*), Bash(docker:*), Bash(aws:*), Bash(ssh-keygen:*), Bash(ssh-add:*), Bash(ssh-agent:*) +compatibility: Linux, macOS, Windows +metadata: + author: runpod + version: "1.0" +license: Apache-2.0 +--- + +# Companion CLIs + +Four CLIs commonly needed alongside Runpod: HuggingFace (`hf`), GitHub (`gh`), Docker (`docker`), and AWS (`aws`). Each requires credentials before use. + +## Windows: Install WSL2 First + +If you are on Windows, install WSL2 (Windows Subsystem for Linux) before proceeding. WSL2 gives you a native Linux environment on Windows, which all these CLIs are designed for. Run in PowerShell as Administrator, then restart: + +```powershell +wsl --install +``` + +This installs WSL2 with Ubuntu by default. After restarting, open the Ubuntu app to complete setup (create a Linux username and password). From that point on, follow the **Linux** instructions throughout this skill. + +## HuggingFace CLI + +The HuggingFace CLI (`hf`) is used to download models from the Hub to your local machine so they are cached and available when you build and run the Docker container. For example, to deploy `openai/gpt-oss-20b` to a Runpod serverless endpoint: download the model locally first, build a Docker image that includes or mounts it, validate the container locally, then push the image to Docker Hub for Runpod to pull. + +### Install + +```bash +# macOS / Linux (standalone installer — recommended) +curl -LsSf https://hf.co/cli/install.sh | bash + +# macOS (Homebrew) +brew install hf + +# Windows (WSL2): use the Linux standalone installer above +``` + +> **Note:** `pip install huggingface_hub` installs the older Python CLI (`huggingface-cli`), which uses different command syntax. The commands below are for the standalone `hf` CLI. + +### Credentials + +Get a token at https://huggingface.co/settings/tokens. Use **write** access for uploading; **read** access is sufficient for downloading public or gated models. + +```bash +# Option 1: interactive login (saves token to ~/.cache/huggingface/token, optionally to git credential store) +hf auth login + +# Option 2: non-interactive (pass token directly, useful in scripts and pod start commands) +hf auth login --token $HF_TOKEN --add-to-git-credential + +# Option 3: environment variable (takes precedence over saved token; to revert, unset the variable) +export HF_TOKEN=hf_... +``` + +```bash +hf auth whoami # confirm auth and org memberships +hf auth logout # delete all locally stored tokens +``` + +### Key Commands + +```bash +# Download a model to a local directory (use --local-dir to control where it lands) +hf download openai/gpt-oss-20b --local-dir ./models/gpt-oss-20b +hf download meta-llama/Llama-3.1-8B --local-dir ./models/llama-3.1-8b + +# Download a single file from a model repo +hf download openai/gpt-oss-20b config.json --local-dir ./models/gpt-oss-20b + +# Download with glob filters (e.g. only safetensors weights, skip fp16 variants) +hf download stabilityai/stable-diffusion-xl-base-1.0 \ + --include "*.safetensors" --exclude "*.fp16.*" \ + --local-dir ./models/sdxl + +# Download a specific revision (commit hash, branch, or tag — append --revision REF) +hf download openai/gpt-oss-20b --revision v1.0 --local-dir ./models/gpt-oss-20b +``` + +### Troubleshooting + +```bash +# Increase download timeout on slow connections (default: 10s) +export HF_HUB_DOWNLOAD_TIMEOUT=30 +``` + +--- + +## GitHub CLI + +The GitHub CLI (`gh`) is used to manage repositories for Runpod serverless workers. This includes cloning repos into local Docker containers for testing, versioning source code so changes can be tracked and shared with teammates or collaborators, and creating GitHub releases that publish listings to the Runpod Hub. The Hub indexes releases — not commits — so every deployment update requires a new release. + +### Install + +```bash +# macOS +brew install gh + +# Linux (Debian/Ubuntu) +(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \ + && sudo mkdir -p -m 755 /etc/apt/keyrings \ + && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \ + && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \ + && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \ + && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \ + | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \ + && sudo apt update && sudo apt install gh -y + +# Linux (Alpine) +apk add github-cli + +# Windows (WSL2): use the Linux (Debian/Ubuntu) installer above +``` + +### SSH Keys + +An SSH key identifies your machine as authentic to remote services. Generate one key and register the public key with each service that requires it — GitHub (via `gh`) and HuggingFace (via browser). + +**Generate a key** + +```bash +ssh-keygen -t ed25519 -C "your_email@example.com" +# Saves to ~/.ssh/id_ed25519 (private) and ~/.ssh/id_ed25519.pub (public) +# Press Enter to accept the default path; set a passphrase or leave blank +``` + +**Add the key to the SSH agent** + +```bash +# macOS +eval "$(ssh-agent -s)" +ssh-add --apple-use-keychain ~/.ssh/id_ed25519 + +# macOS — also add to ~/.ssh/config so the key loads automatically on login. +# Create the file if it doesn't exist, and add these lines: +# +# Host * +# AddKeysToAgent yes +# UseKeychain yes +# IdentityFile ~/.ssh/id_ed25519 + +# Linux +eval "$(ssh-agent -s)" +ssh-add ~/.ssh/id_ed25519 + +# Windows (WSL2): use the Linux instructions above +``` + +### Credentials + +```bash +# Interactive login — when prompted, select SSH as the git protocol +gh auth login + +# Verify auth +gh auth status +``` + +**Register the public key with each service** + +```bash +# GitHub — upload via gh CLI (requires auth above to be completed first) +gh ssh-key add ~/.ssh/id_ed25519.pub --title "my-machine" + +# HuggingFace — paste contents of public key manually in browser +cat ~/.ssh/id_ed25519.pub # copy this output +# Then add at https://huggingface.co/settings/keys +``` + +### Key Commands + +```bash +# Repositories +gh repo create my-worker --public # create a new public repo (required for Hub) +gh repo clone owner/repo # clone a repository over SSH +gh repo clone owner/repo -- --depth 1 # shallow clone +gh repo view owner/repo # view repo details and URL + +# Releases — the Runpod Hub indexes releases, not commits +# Every update to a Hub listing requires a new GitHub release +gh release create v1.0.0 --title "v1.0.0" --notes "Initial release" # create a release +gh release create v1.0.1 --title "v1.0.1" --notes "Update model tag" # update Hub listing +gh release list # list all releases +gh release view v1.0.0 # view release details +``` + +#### Runpod Hub repository structure + +A Hub-compatible repository requires these files (in root or `.runpod/` directory): + +``` +handler.py # serverless worker implementation +Dockerfile # container definition +README.md # documentation shown on Hub listing +.runpod/ + hub.json # Hub metadata: title, description, category, GPU config, env vars + tests.json # test cases run after each release +``` + +To publish: go to https://console.runpod.io → Hub → Add your repo → enter the GitHub repository URL. + +--- + +## Docker + +Docker is used to build and validate container images locally before pushing to Docker Hub. Runpod uses Docker Hub as its default image registry — serverless endpoints, pods, and templates all reference images by their Docker Hub tag. Once an image is pushed, Runpod workers pull it automatically when the endpoint or pod is started. + +### Install + +**macOS:** Download Docker Desktop from https://docs.docker.com/desktop/setup/install/mac-install/ +- Choose the **Apple Silicon** installer for M-series Macs, or **Intel Chip** for older Macs +- Open the DMG, drag Docker to Applications, and launch it + +**Windows:** Download Docker Desktop from https://docs.docker.com/desktop/setup/install/windows-install/ +- Requires WSL 2 — if you followed the WSL2 setup above, Docker Desktop will detect it automatically +- After installation, `docker` commands work inside your WSL2 terminal without extra configuration +- Run the installer and follow the setup wizard + +**Linux:** See https://docs.docker.com/engine/install/ for distro-specific instructions + +```bash +# Linux convenience script (Ubuntu/Debian) +curl -fsSL https://get.docker.com | sh +sudo usermod -aG docker $USER # allow non-root usage (re-login after) +``` + +### Credentials + +Docker Hub authentication uses a personal access token (PAT), not your account password. + +1. Go to https://app.docker.com → Avatar (top right) → Account Settings → Personal Access Tokens +2. Click **Generate new token** — give it a descriptive name, set an expiration, and choose **Read & Write** access +3. Copy the token immediately — it is shown only once + +```bash +docker login -u DOCKERHUB_USERNAME +# When prompted for a password, paste your personal access token +``` + +Credentials are saved to `~/.docker/config.json` after a successful login. + +### Tagging + +> **Always use explicit semantic version tags. Never rely on `latest`.** + +The `latest` tag does not automatically point to the newest image — it only reflects the last build that was pushed without an explicit tag. If you push `v1.0.0` and then push `v1.0.1` with an explicit tag, `latest` still points to `v1.0.0`. Runpod workers pinned to `latest` will silently pull the wrong version. + +Use a tag that uniquely identifies the build: `v1.0.0`, `v1.0.1`, etc. + +```bash +# Correct: explicit semantic version tag +docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 . +docker push myorg/myimage:v1.0.0 + +# Wrong: latest tag is ambiguous and unreliable +docker build -t myorg/myimage:latest . +``` + +### Docker Hub + +Docker Hub is the registry Runpod pulls images from. After pushing, images are visible at https://hub.docker.com/repositories/ and referenceable in Runpod as `username/image:tag`. + +Images on Docker Hub can be public (anyone can pull) or private (requires credentials). For private images, register your Docker Hub credentials in Runpod once and they become available to any template: + +1. Go to https://console.runpod.io/user/settings → **Container Registry Settings** +2. Add your Docker Hub username and personal access token (the same PAT used for `docker login`) +3. When creating or editing a template, select the saved credential from the dropdown + +> Runpod currently only supports `docker login` type credentials for container registry authentication. + +### Key Commands + +```bash +# Build for Runpod (always --platform=linux/amd64 — pods run on x86 Linux) +docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 . +docker build --platform=linux/amd64 -t myorg/myimage:v1.0.0 -f Dockerfile.prod . # specify Dockerfile + +# Tag an existing image before pushing (does not duplicate image data) +docker tag myorg/myimage:v1.0.0 myorg/myimage:v1.0.1 + +# Push to Docker Hub (image becomes available to Runpod as myorg/myimage:v1.0.0) +docker push myorg/myimage:v1.0.0 + +# Run locally for validation +docker run --rm -it myorg/myimage:v1.0.0 bash +docker run --rm --gpus all myorg/myimage:v1.0.0 bash # with GPU (requires nvidia-container-toolkit) +docker run --rm -p 8080:80 -e API_KEY=secret myorg/myimage:v1.0.0 # port mapping + env vars + +# Debug a running container +docker exec -it CONTAINER_ID /bin/bash + +# Inspect +docker images # list local images +docker ps -a # list all containers (including stopped) +docker logs CONTAINER_ID # view container output +docker logs -f CONTAINER_ID # follow logs in real time + +# Cleanup +docker rmi myorg/myimage:v1.0.0 # remove an image +docker rm CONTAINER_ID # remove a stopped container +``` + +--- + +## AWS CLI + +The AWS CLI is used to access Runpod storage over the S3 protocol. Any Runpod product that can mount a Network Volume — pods, clusters, and serverless endpoints — can have its storage accessed this way. The bucket name is the network volume ID. + +### Install + +```bash +# macOS +brew install awscli + +# Linux +curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip +unzip awscliv2.zip && sudo ./aws/install +``` + +### Credentials + +Runpod uses its own S3-compatible API, not AWS. You need a Runpod user ID and S3 API key — not an AWS account. + +- **Access key** (`AWS_ACCESS_KEY_ID`): your Runpod user ID — found in the console under Settings > S3 API Keys, in the key description (format: `user_...`) +- **Secret key** (`AWS_SECRET_ACCESS_KEY`): an S3 API key — generate one at Settings > S3 API Keys > Create. Shown only once; save it immediately (format: `rps_...`) + +```bash +# Option 1: interactive configure (writes ~/.aws/credentials and ~/.aws/config) +# When prompted: enter user ID as access key, S3 API key as secret. +# Press Enter to skip region and output format — region is always passed per-command, not stored in config. +aws configure + +aws configure list # verify stored credentials + +# Option 2: environment variables (override config files) +export AWS_ACCESS_KEY_ID=user_... +export AWS_SECRET_ACCESS_KEY=rps_... + +# To stop using env vars and fall back to config file: +unset AWS_ACCESS_KEY_ID +unset AWS_SECRET_ACCESS_KEY +``` + +### Region and Endpoint + +The `--region` flag on every command is the Runpod datacenter ID where the network volume lives — not an AWS region. The `--endpoint-url` is derived from the same datacenter ID. + +Every command requires both flags: +``` +--region DATACENTER --endpoint-url https://s3api-DATACENTER.runpod.io/ +``` + +**Tip:** Each network volume on the storage page at https://console.runpod.io/user/storage/ shows a pre-filled example `aws s3 ls` command with the correct `--region` and `--endpoint-url` already substituted. Use this to confirm the exact values for a given volume. + +Datacenter IDs by region: + +| Region | Datacenter IDs | +|--------|---------------| +| EU | CZ-1, RO-1, IS-1, NO-1 | +| US | CA-2, GA-2, IL-1, KS-2, MD-1, MO-1, MO-2, NC-1, NC-2, NE-1, WA-1 | + +### Key Commands + +Replace `DATACENTER` with the datacenter ID of your network volume (e.g. `CA-2`) and `NETWORK_VOLUME_ID` with the volume ID (used as the S3 bucket name). + +```bash +# List files in a volume +aws s3 ls \ + --region DATACENTER \ + --endpoint-url https://s3api-DATACENTER.runpod.io/ \ + s3://NETWORK_VOLUME_ID/ + +# List a subdirectory +aws s3 ls \ + --region DATACENTER \ + --endpoint-url https://s3api-DATACENTER.runpod.io/ \ + s3://NETWORK_VOLUME_ID/my-folder/ + +# Upload a file +aws s3 cp local-file.txt \ + --region DATACENTER \ + --endpoint-url https://s3api-DATACENTER.runpod.io/ \ + s3://NETWORK_VOLUME_ID/ + +# Download a file +aws s3 cp \ + --region DATACENTER \ + --endpoint-url https://s3api-DATACENTER.runpod.io/ \ + s3://NETWORK_VOLUME_ID/remote-file.txt ./ + +# Delete a file +aws s3 rm \ + --region DATACENTER \ + --endpoint-url https://s3api-DATACENTER.runpod.io/ \ + s3://NETWORK_VOLUME_ID/remote-file.txt + +# Sync a local directory to a volume +aws s3 sync local-dir/ \ + --region DATACENTER \ + --endpoint-url https://s3api-DATACENTER.runpod.io/ \ + s3://NETWORK_VOLUME_ID/remote-dir/ +``` + +Path mapping: `/workspace/my-folder/file.txt` on a pod = `s3://NETWORK_VOLUME_ID/my-folder/file.txt` via S3. + +### Troubleshooting + +```bash +# Retry on timeout (large transfers) +export AWS_RETRY_MODE=standard +export AWS_MAX_ATTEMPTS=10 + +# Extend read timeout for large files (seconds) +aws s3 cp large-file.zip \ + --region DATACENTER \ + --endpoint-url https://s3api-DATACENTER.runpod.io/ \ + --cli-read-timeout 7200 \ + s3://NETWORK_VOLUME_ID/ +``` diff --git a/plugins/cloud-inference-skills/skills/flash/SKILL.md b/plugins/cloud-inference-skills/skills/flash/SKILL.md new file mode 100644 index 000000000..501354834 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/flash/SKILL.md @@ -0,0 +1,381 @@ +--- +name: flash +description: runpod-flash SDK and CLI for deploying AI workloads on Runpod serverless GPUs/CPUs. +user-invocable: true +--- + +# Runpod Flash + +Write code locally, iterate with `flash dev` — it runs your functions on remote Runpod GPUs/CPUs with hot-reload and live worker logs — then `flash deploy` to ship. `Endpoint` handles provisioning. + +## Setup + +```bash +# install the CLI — requires Python 3.10-3.13 +uv tool install runpod-flash +pip install runpod-flash + +# auth option 1: browser-based login (saves token locally) +flash login +# headless: print URL instead of opening a browser +flash login --no-open +# max seconds to wait for browser auth (default 600) +flash login --timeout 300 + +# auth option 2: API key via environment variable +export RUNPOD_API_KEY=your_key + +# scaffold a new project in ./my-project (writes AGENTS.md + CLAUDE.md) +flash init my-project +# scaffold in the current directory +flash init . +# overwrite existing files (-f) +flash init my-project --force +# update the CLI to the latest version +flash update +# pin a specific version (-V also works) +flash update --version 1.16.0 +``` + +`flash init` writes `AGENTS.md` (+ a `CLAUDE.md` symlink). To add them to an existing project: `python -c "from runpod_flash.rules import install_agent_files; from pathlib import Path; install_agent_files(Path.cwd())"`. + +## CLI + +`flash dev` is the canonical dev-server command (`flash run` still works as a hidden alias). + +```bash +# local server at :8888, but functions run on REMOTE GPU/CPU workers; +# hot-reloads on save and streams the worker's logs live to your terminal +flash dev +# same, but pre-provision endpoints (no cold start on first call) +flash dev --auto-provision +# custom port/host; --reload/--no-reload toggles autoreload +flash dev --port 9000 --host 0.0.0.0 +# build + deploy (auto-selects env if only one) +flash deploy +# build + deploy to "staging" environment +flash deploy --env staging +# deploy a specific app to an environment +flash deploy --app my-app --env prod +# build + launch local preview in Docker +flash deploy --preview +# build flags below also apply to deploy +flash deploy --no-deps --python-version 3.11 +# list deployment environments +flash env list +# create "staging" environment +flash env create staging +# show environment details + resources +flash env get staging +# delete environment + tear down resources +flash env delete staging +# list flash apps in your account +flash app list +# create a flash app +flash app create my-app +# show an app's environments + builds +flash app get my-app +# delete an app and all its resources +flash app delete my-app +# list all active endpoints +flash undeploy list +# remove a specific endpoint +flash undeploy my-endpoint +# remove all endpoints (--interactive/-i to pick, --force/-f to skip prompts) +flash undeploy --all +# remove endpoints whose code no longer exists locally +flash undeploy --cleanup-stale + +# build-only (no deploy) — mainly for debugging the artifact; `flash deploy` builds for you +# package the artifact without deploying (1500MB limit; torch auto-excluded) +flash build +# build flags: --no-deps, --exclude pkg1,pkg2, --output name.tar.gz, --python-version 3.11 +flash build --no-deps +``` + +## Dev vs Deploy + +- `flash dev` — **iterate.** Local server at `:8888`, but your decorated functions + execute on **remote GPU/CPU workers**. Hot-reloads on save and **streams the worker's + logs live** to the terminal. No build/upload/deploy wait — use this the whole time you + develop. +- `flash deploy` — **ship.** Builds an artifact and deploys a stable endpoint. Slow + (build + upload + provision); only do this once the code works under `flash dev`. + +`flash dev` ships **only the function body** to the worker, so a `NameError` for a +module-level name surfaces immediately here. `flash deploy` imports the whole module and +can mask that bug (see Gotcha #1). Develop against `flash dev` and you catch it first. + +## Autonomous Dev Loop + +`flash dev` is a long-running server — run it in the background (don't block on it), +capture its output, and drive it over HTTP. The captured log is the remote worker's live +stream (cold start, model load, `print`s, tracebacks) — read it to debug. + +```bash +flash dev > /tmp/flash-dev.log 2>&1 & # background; never run it blocking +until grep -q "flash dev localhost:" /tmp/flash-dev.log; do sleep 2; done # wait for startup +URL=$(grep -o "localhost:[0-9]*" /tmp/flash-dev.log | head -1) # actual port (8888 bumps if taken) +curl -s "$URL/main/predict" -d '{"data": {...}}' # dispatches to the remote worker +``` + +- **Read the real URL from the log** — flash auto-bumps the port if 8888 is in use, and + prints `✓ flash dev localhost:` plus the route table. +- **Routes are namespaced by file**: `main.py`'s `/predict` is served at `/main/predict`. +- A handler typed `def predict(data: dict)` expects the arg as a top-level field — send + `{"data": {...}}`, not the bare object (otherwise 422). +- Edit a handler and save — hot-reload re-syncs the body; just re-send the request, no + redeploy. Add `--auto-provision` to skip the first-call cold start. `kill %1` when done. + +## Endpoint: Three Modes + +### Mode 1: Your Code (Queue-Based Decorator) + +One function = one endpoint with its own workers. + +```python +from runpod_flash import Endpoint, GpuGroup + +@Endpoint(name="my-worker", gpu=GpuGroup.AMPERE_80, workers=5, dependencies=["torch"]) +async def compute(data): + import torch # MUST import inside function (cloudpickle) + return {"sum": torch.tensor(data, device="cuda").sum().item()} + +result = await compute([1, 2, 3]) +``` + +### Mode 2: Your Code (Load-Balanced Routes) + +Multiple HTTP routes share one pool of workers. + +```python +from runpod_flash import Endpoint, GpuGroup + +api = Endpoint(name="my-api", gpu=GpuGroup.ADA_24, workers=(1, 5), dependencies=["torch"]) + +@api.post("/predict") +async def predict(data: list[float]): + import torch + return {"result": torch.tensor(data, device="cuda").sum().item()} + +@api.get("/health") +async def health(): + return {"status": "ok"} +``` + +### Mode 3: External Image (Client) + +Deploy a pre-built Docker image and call it via HTTP. + +```python +from runpod_flash import Endpoint, GpuGroup, PodTemplate + +server = Endpoint( + name="my-server", + image="my-org/my-image:latest", + gpu=GpuGroup.AMPERE_80, + workers=1, + env={"HF_TOKEN": "xxx"}, + template=PodTemplate(containerDiskInGb=100), +) + +# LB-style +result = await server.post("/v1/completions", {"prompt": "hello"}) +models = await server.get("/v1/models") + +# QB-style +job = await server.run({"prompt": "hello"}) # optional: webhook="https://..." for completion callback +await job.wait() +print(job.output) +``` + +Connect to an existing endpoint by ID (no provisioning): + +```python +ep = Endpoint(id="abc123") +job = await ep.runsync({"prompt": "hello"}) # runsync wraps this as {"input": {"prompt": "hello"}} +print(job.output) +``` + +## How Mode Is Determined + +| Parameters | Mode | +|-----------|------| +| `name=` only | Decorator (your code) | +| `image=` set | Client (deploys image, then HTTP calls) | +| `id=` set | Client (connects to existing, no provisioning) | + +## Endpoint Constructor + +```python +Endpoint( + name="endpoint-name", # required (unless id= set) + id=None, # connect to existing endpoint + gpu=GpuGroup.AMPERE_80, # GpuGroup tier, GpuType model, or list of either (default: GpuGroup.ANY) + cpu=CpuInstanceType.CPU5C_4_8, # CPU type (mutually exclusive with gpu) + workers=5, # shorthand for (0, 5) + workers=(1, 5), # explicit (min, max) + max_concurrency=1, # concurrent requests per worker (default 1) + idle_timeout=60, # seconds before scale-down (default: 60) + dependencies=["torch"], # pip packages for remote exec + system_dependencies=["ffmpeg"], # apt-get packages + image="org/image:tag", # pre-built Docker image (client mode) + env={"KEY": "val"}, # environment variables + volume=NetworkVolume(...), # persistent storage + datacenter=DataCenter.US_CA_2, # DataCenter | list | str (default: None) + gpu_count=1, # GPUs per worker + template=PodTemplate(containerDiskInGb=100), + flashboot=True, # fast cold starts + accelerate_downloads=True, # speed up model/file downloads (default True) + min_cuda_version=CudaVersion.V12_8, # minimum CUDA version (default 12.8) + scaler_type=ServerlessScalerType.QUEUE_DELAY, # default unset; or REQUEST_COUNT + scaler_value=4, # scaler threshold (default 4) + execution_timeout_ms=0, # max execution time (0 = unlimited) +) +``` + +- `gpu=` and `cpu=` are mutually exclusive +- `gpu=` accepts a `GpuGroup`, a `GpuType`, or a list of either (see GPU Types below) +- `workers=5` means `(0, 5)`. Default is `(0, 1)` +- `max_concurrency` -- requests handled concurrently per worker (default 1). Raise it for I/O-bound LB routes so one worker serves multiple requests +- `idle_timeout` default is **60 seconds** +- `flashboot=True` (default) -- enables fast cold starts via snapshot restore +- `gpu_count` -- GPUs per worker (default 1), use >1 for multi-GPU models +- `datacenter` -- a `DataCenter` enum, list, or string; defaults to `None` (unset) +- `scaler_type` -- defaults to `QUEUE_DELAY` for queue-based endpoints and `REQUEST_COUNT` for load-balanced endpoints; pass `ServerlessScalerType.QUEUE_DELAY` or `REQUEST_COUNT` to override +- `DataCenter`, `CudaVersion`, and `ServerlessScalerType` are importable from `runpod_flash` + +### NetworkVolume + +```python +NetworkVolume(name="my-vol", size=100) # size in GB, default 100 +``` + +### PodTemplate + +```python +PodTemplate( + containerDiskInGb=64, # container disk size (default 64) + dockerArgs="", # extra docker arguments + ports="", # exposed ports + startScript="", # script to run on start +) +``` + +## EndpointJob + +Returned by `ep.run()` and `ep.runsync()` in client mode. + +```python +job = await ep.run({"data": [1, 2, 3]}) +await job.wait(timeout=120) # poll until done +print(job.id, job.output, job.error, job.done) +await job.cancel() +``` + +## GPU Types + +`gpu=` accepts a `GpuGroup` (a supply pool by VRAM tier), a `GpuType` (a pinned GPU model), or a list of either. `GpuGroup` picks the cheapest available GPU within a tier; `GpuType` pins a specific model. + +### GpuGroup (supply pool) + +| Enum | GPU | VRAM | +|------|-----|------| +| `ANY` | any | varies | +| `AMPERE_16` | RTX A4000 / A4500 / RTX 4000 Ada / RTX 2000 Ada | 16GB | +| `AMPERE_24` | RTX A5000 / L4 / RTX 3090 | 24GB | +| `AMPERE_48` | A40 / RTX A6000 | 48GB | +| `AMPERE_80` | A100 (PCIe / SXM4) | 80GB | +| `ADA_24` | RTX 4090 | 24GB | +| `ADA_32_PRO` | RTX 5090 | 32GB | +| `ADA_48_PRO` | RTX 6000 Ada / L40 / L40S | 48GB | +| `ADA_80_PRO` | H100 PCIe (80GB) / H100 HBM3 (80GB) / H100 NVL (94GB) | 80GB+ | +| `HOPPER_141` | H200 | 141GB | +| `BLACKWELL_96` | RTX PRO 6000 Blackwell | 96GB | +| `BLACKWELL_180` | B200 | 180GB | + +### GpuType (pinned model) + +Pin an exact GPU model. Members include `NVIDIA_GEFORCE_RTX_4090`, `NVIDIA_GEFORCE_RTX_5090`, `NVIDIA_RTX_6000_ADA_GENERATION`, `NVIDIA_H100_80GB_HBM3`, `NVIDIA_A100_80GB_PCIe`, `NVIDIA_A100_SXM4_80GB`, `NVIDIA_H200`, `NVIDIA_B200`, the `NVIDIA_RTX_PRO_6000_BLACKWELL_*` editions (Server / Workstation / Max-Q), and the Ampere/Ada RTX A-series models (`NVIDIA_RTX_A4000`, `A4500`, `A5000`, `A6000`, `NVIDIA_L4`, `NVIDIA_A40`, `NVIDIA_GEFORCE_RTX_3090`, `NVIDIA_RTX_4000_ADA_GENERATION`, `NVIDIA_RTX_2000_ADA_GENERATION`). + +```python +from runpod_flash import Endpoint, GpuType + +@Endpoint(name="pinned", gpu=GpuType.NVIDIA_GEFORCE_RTX_4090, dependencies=["torch"]) +async def report_gpu(data): + import torch + return {"gpu": torch.cuda.get_device_name(0)} +``` + +## CPU Types (CpuInstanceType) + +| Enum | vCPU | RAM | Max Disk | Type | +|------|------|-----|----------|------| +| `CPU3G_1_4` | 1 | 4GB | 10GB | General | +| `CPU3G_2_8` | 2 | 8GB | 20GB | General | +| `CPU3G_4_16` | 4 | 16GB | 40GB | General | +| `CPU3G_8_32` | 8 | 32GB | 80GB | General | +| `CPU3C_1_2` | 1 | 2GB | 10GB | Compute | +| `CPU3C_2_4` | 2 | 4GB | 20GB | Compute | +| `CPU3C_4_8` | 4 | 8GB | 40GB | Compute | +| `CPU3C_8_16` | 8 | 16GB | 80GB | Compute | +| `CPU5C_1_2` | 1 | 2GB | 15GB | Compute (5th gen) | +| `CPU5C_2_4` | 2 | 4GB | 30GB | Compute (5th gen) | +| `CPU5C_4_8` | 4 | 8GB | 60GB | Compute (5th gen) | +| `CPU5C_8_16` | 8 | 16GB | 120GB | Compute (5th gen) | + +```python +from runpod_flash import Endpoint, CpuInstanceType + +@Endpoint(name="cpu-work", cpu=CpuInstanceType.CPU5C_4_8, workers=5, dependencies=["pandas"]) +async def process(data): + import pandas as pd + return pd.DataFrame(data).describe().to_dict() +``` + +## Common Patterns + +### CPU + GPU Pipeline + +```python +from runpod_flash import Endpoint, GpuGroup, CpuInstanceType + +@Endpoint(name="preprocess", cpu=CpuInstanceType.CPU5C_4_8, workers=5, dependencies=["pandas"]) +async def preprocess(raw): + import pandas as pd + return pd.DataFrame(raw).to_dict("records") + +@Endpoint(name="infer", gpu=GpuGroup.AMPERE_80, workers=5, dependencies=["torch"]) +async def infer(clean): + import torch + t = torch.tensor([[v for v in r.values()] for r in clean], device="cuda") + return {"predictions": t.mean(dim=1).tolist()} + +async def pipeline(data): + return await infer(await preprocess(data)) +``` + +### Parallel Execution + +```python +import asyncio +results = await asyncio.gather(compute(a), compute(b), compute(c)) +``` + +## Gotchas + +1. **Only the function body ships to the worker** -- most common error. Put imports *and* any module-level constants/helpers the function uses *inside* the decorated body. `flash deploy` imports the whole module so module globals happen to work; `flash dev` ships just the body, so a module-level name raises `NameError`. A handler that works deployed can break under dev — fix it by moving everything inside. +2. **Forgetting await** -- all decorated functions and client methods need `await`. +3. **Missing dependencies** -- must list in `dependencies=[]`. +4. **gpu/cpu are exclusive** -- pick one per Endpoint. +5. **idle_timeout is seconds** -- default 60s, not minutes. +6. **10MB payload limit** -- pass URLs, not large objects. +7. **Client vs decorator** -- `image=`/`id=` = client. Otherwise = decorator. +8. **Auto GPU switching requires workers >= 5** -- pass a list of GPU types (e.g. `gpu=[GpuGroup.ADA_24, GpuGroup.AMPERE_80]`) and set `workers=5` or higher. The platform only auto-switches GPU types based on supply when max workers is at least 5. +9. **`runsync` timeout is 60s** -- cold starts can exceed 60s. Use `ep.runsync(data, timeout=120)` for first requests or use `ep.run()` + `job.wait()` instead. + +## Resources + +- Flash source: https://github.com/runpod/flash +- Runnable examples: https://github.com/runpod/flash-examples +- Docs: https://docs.runpod.io diff --git a/plugins/cloud-inference-skills/skills/flash/evals/client-external-image.eval.md b/plugins/cloud-inference-skills/skills/flash/evals/client-external-image.eval.md new file mode 100644 index 000000000..8d2f85016 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/flash/evals/client-external-image.eval.md @@ -0,0 +1,23 @@ +# Deploy a prebuilt vLLM image and call it over HTTP + +## Prompt + +I have a prebuilt Docker image `myorg/vllm-server:latest` that serves an +OpenAI-compatible API on an A100. Using runpod-flash, deploy it to a Runpod +serverless GPU endpoint and send a completion request to `/v1/completions`. + +## Expected behavior + +The agent should: + +1. Create an `Endpoint` with `image="myorg/vllm-server:latest"` (client mode) plus `name=`, `gpu=GpuGroup.AMPERE_80` +2. Recognize that `image=` means client mode (deploys the image, then calls it via HTTP) — no decorated function +3. Call the deployed endpoint with `await server.post("/v1/completions", {...})` + +## Assertions + +- Creates an `Endpoint(name=..., image="myorg/vllm-server:latest", gpu=GpuGroup.AMPERE_80, ...)` +- Does NOT wrap a Python function in a decorator (client mode, not decorator mode) +- Calls the endpoint with `await .post("/v1/completions", )` +- Uses `await` on the HTTP call +- Does NOT set `id=` together with `image=` (mutually exclusive) diff --git a/plugins/cloud-inference-skills/skills/flash/evals/connect-existing-endpoint.eval.md b/plugins/cloud-inference-skills/skills/flash/evals/connect-existing-endpoint.eval.md new file mode 100644 index 000000000..6f3b9412b --- /dev/null +++ b/plugins/cloud-inference-skills/skills/flash/evals/connect-existing-endpoint.eval.md @@ -0,0 +1,23 @@ +# Call an existing Runpod endpoint by ID + +## Prompt + +I already have a Runpod serverless endpoint with ID `abc123xyz`. Using +runpod-flash, send it a synchronous job `{"prompt": "hello"}` and print the +output. The first request may cold-start and take longer than a minute. + +## Expected behavior + +The agent should: + +1. Create `Endpoint(id="abc123xyz")` — connects to the existing endpoint, no provisioning +2. Submit the job with `runsync`, raising the timeout above the 60s default to survive cold start +3. Print `job.output` + +## Assertions + +- Creates `Endpoint(id="abc123xyz")` (no `name=`, `gpu=`, or `image=` needed) +- Uses `await ep.runsync({"prompt": "hello"}, timeout=...)` with a timeout > 60 (e.g. 120) OR uses `await ep.run(...)` + `await job.wait()` to avoid the 60s cap +- Accesses the result via `job.output` +- Uses `await` on the call +- Does NOT pass `id=` together with `image=` (`id=` + `name=` is legal and harmless) diff --git a/plugins/cloud-inference-skills/skills/flash/evals/cpu-gpu-pipeline.eval.md b/plugins/cloud-inference-skills/skills/flash/evals/cpu-gpu-pipeline.eval.md new file mode 100644 index 000000000..9a36bcd21 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/flash/evals/cpu-gpu-pipeline.eval.md @@ -0,0 +1,25 @@ +# Build a CPU-preprocess then GPU-inference pipeline + +## Prompt + +Using runpod-flash, build a two-stage pipeline: a CPU stage that cleans raw data +with pandas, then a GPU stage that runs inference with torch. The CPU stage +should use a compute CPU instance and the GPU stage an A100. Wire them together. + +## Expected behavior + +The agent should: + +1. Define a CPU `@Endpoint(cpu=CpuInstanceType., dependencies=["pandas"])` function +2. Define a GPU `@Endpoint(gpu=GpuGroup.AMPERE_80, dependencies=["torch"])` function +3. Import `pandas`/`torch` inside the respective functions +4. Chain them: `await infer(await preprocess(raw))` + +## Assertions + +- CPU stage uses `cpu=CpuInstanceType.` and does NOT set `gpu=` +- GPU stage uses `gpu=GpuGroup.AMPERE_80` and does NOT set `cpu=` +- `pandas` listed in the CPU stage `dependencies`, `torch` in the GPU stage `dependencies` +- Imports are inside each decorated function +- Stages are chained with `await` (the GPU call awaits the result of the CPU call) +- Does NOT put `gpu=` and `cpu=` on the same Endpoint diff --git a/plugins/cloud-inference-skills/skills/flash/evals/dev-loop-iteration.eval.md b/plugins/cloud-inference-skills/skills/flash/evals/dev-loop-iteration.eval.md new file mode 100644 index 000000000..d931517c4 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/flash/evals/dev-loop-iteration.eval.md @@ -0,0 +1,59 @@ +# Iterate on a flash GPU handler against a live remote worker + +> **LIVE eval.** This runs against real Runpod infrastructure — it provisions a real +> worker and incurs cost. It is graded on what actually happened at runtime, not on what +> the agent says it would do. + +## Setup + +- Requires `RUNPOD_API_KEY` in the environment (flash CLI authenticated, v1.17.0+). +- Copy the fixture to a scratch dir so the graded fix does not mutate the committed + fixture: `cp -r flash/evals/fixtures/dev-loop /tmp/dev-loop-eval && cd /tmp/dev-loop-eval` + (or `git checkout flash/evals/fixtures/dev-loop` afterward). +- The fixture's `/predict` handler references a module-level `VOL` constant, which does not + ship to the remote worker — it fails at runtime until moved into the function body. + +## Prompt + +Use the runpod-flash project in this directory (an image-to-3D style endpoint). The +`/predict` route fails when it actually runs on a worker. Iterate against a **real** remote +worker: start the dev loop, send a request, read the worker's logs, fix whatever is broken, +and confirm a successful JSON response. I don't want to re-deploy on every change. + +## Expected behavior + +The agent should actually execute (not merely describe) the following: + +1. Recommend and use `flash dev` (not repeated `flash deploy`) for the loop, and run it as a + **background** process so it does not block the session. +2. Determine the dev server's **actual** URL from its startup log rather than assuming + `localhost:8888` (flash bumps the port if 8888 is taken). +3. Send a real request to the correct **file-namespaced** route (`main.py` → `/main/predict`), + which provisions and dispatches to the remote worker. +4. Read the captured dev-server log to observe the **real** error from the worker. +5. Diagnose it: only the function body ships, so module-level `VOL` is undefined remotely. + Fix by moving `VOL` inside the handler and rely on hot-reload (no redeploy). +6. Re-send the request and confirm a real successful response. +7. Undeploy everything it provisioned. + +## Assertions + +- Runs `flash dev` as a background / non-blocking process (does NOT run it as a plain + blocking command and hang) +- Determines the actual host:port from the dev-server output (does NOT hardcode `8888` when + it was bumped) +- Sends the request to the file-namespaced route (`/main/predict`), not the bare `/predict` +- Observes the **verbatim** runtime error `NameError: name 'VOL' is not defined` in the + worker's streamed logs (it is reported from the live run, not guessed) +- Fixes the bug by moving `VOL` into the function body and re-tests via hot-reload, without + running `flash deploy` +- Obtains a real **HTTP 200** whose body contains `"ok": true` (e.g. + `{"ok":true,"vol":"/runpod-volume/models","echo":...}`) +- Runs `flash undeploy --all --force` (or equivalent) and confirms no endpoints remain + +## Cleanup + +- `flash undeploy --all --force` must report the provisioned endpoint deleted, and + `flash undeploy list` must show no endpoints. +- The agent must only stop processes/ports it started. +- Restore the fixture if it was edited in place: `git checkout flash/evals/fixtures/dev-loop`. diff --git a/plugins/cloud-inference-skills/skills/flash/evals/fixtures/dev-loop/main.py b/plugins/cloud-inference-skills/skills/flash/evals/fixtures/dev-loop/main.py new file mode 100644 index 000000000..4b0986a65 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/flash/evals/fixtures/dev-loop/main.py @@ -0,0 +1,21 @@ +from runpod_flash import Endpoint, GpuGroup + +# BUG (intentional — do NOT "pre-fix" this): a module-level constant referenced +# inside the handler. Under `flash dev` only the function body ships to the +# remote worker, so this raises `NameError: name 'VOL' is not defined` remotely +# until it is moved inside predict(). `flash deploy` imports the whole module and +# masks the bug; `flash dev` surfaces it. The eval's job is to reproduce, observe +# in the live worker logs, and fix it. +VOL = "/runpod-volume/models" + +api = Endpoint(name="dev-loop-eval", gpu=GpuGroup.AMPERE_16, workers=(0, 1), dependencies=[]) + + +@api.post("/predict") +async def predict(data: dict): + return {"ok": True, "vol": VOL, "echo": data} + + +@api.get("/health") +async def health(): + return {"status": "ok"} diff --git a/plugins/cloud-inference-skills/skills/flash/evals/lb-multi-route-api.eval.md b/plugins/cloud-inference-skills/skills/flash/evals/lb-multi-route-api.eval.md new file mode 100644 index 000000000..4c4c87648 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/flash/evals/lb-multi-route-api.eval.md @@ -0,0 +1,25 @@ +# Serve multiple HTTP routes from one pool of GPU workers + +## Prompt + +Using runpod-flash, I want a single GPU endpoint that exposes two HTTP routes: +`POST /predict` for inference and `GET /health` for a health check, sharing the +same pool of workers (1 to 5). Write the code. + +## Expected behavior + +The agent should: + +1. Create an `Endpoint` INSTANCE (not a decorator on a function): `api = Endpoint(name=..., gpu=..., workers=(1, 5), ...)` +2. Register routes with `@api.post("/predict")` and `@api.get("/health")` +3. Put heavy imports inside the route handlers +4. Make handlers `async def` + +## Assertions + +- Creates an `Endpoint(...)` instance assigned to a variable (load-balanced mode) +- Uses `@.post("/predict")` and `@.get("/health")` to register routes +- Uses `workers=(1, 5)` (explicit min/max tuple), NOT `workers=5` +- Does NOT define each route as its own separate `@Endpoint(name=...)` decorator (that would be separate endpoints, not shared workers) +- Route handlers are `async def` +- Heavy/GPU imports are inside the handler functions diff --git a/plugins/cloud-inference-skills/skills/flash/evals/qb-gpu-function.eval.md b/plugins/cloud-inference-skills/skills/flash/evals/qb-gpu-function.eval.md new file mode 100644 index 000000000..e18e89f1e --- /dev/null +++ b/plugins/cloud-inference-skills/skills/flash/evals/qb-gpu-function.eval.md @@ -0,0 +1,26 @@ +# Run a GPU function on Runpod serverless + +## Prompt + +I have a Python function that runs a PyTorch model on a GPU. I want to run it on +Runpod serverless using runpod-flash, with up to 5 workers. Write the code. + +## Expected behavior + +The agent should: + +1. Import `Endpoint` and `GpuGroup` from `runpod_flash` +2. Decorate the function with `@Endpoint(name=..., gpu=GpuGroup., workers=5, dependencies=["torch"])` +3. Put the `import torch` (and any other deps) INSIDE the decorated function +4. Make the function `async def` +5. Call it with `await` + +## Assertions + +- Uses `@Endpoint(...)` as a decorator with a `name=` (queue-based mode) +- Sets `gpu=` to a `GpuGroup` member and `workers` to 5 +- Lists `torch` in `dependencies=[...]` +- The `import torch` statement is INSIDE the function body, not at module top level +- The function is `async def` and is invoked with `await` +- Does NOT use the deprecated `@remote` decorator +- Does NOT set both `gpu=` and `cpu=` diff --git a/plugins/cloud-inference-skills/skills/runpodctl/SKILL.md b/plugins/cloud-inference-skills/skills/runpodctl/SKILL.md new file mode 100644 index 000000000..2c3d714f7 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/runpodctl/SKILL.md @@ -0,0 +1,260 @@ +--- +name: runpodctl +description: Runpod CLI to manage your GPU workloads. +allowed-tools: Bash(runpodctl:*) +compatibility: Linux, macOS +metadata: + author: runpod + version: "2.3" +license: Apache-2.0 +--- + +# Runpodctl + +Manage GPU pods, serverless endpoints, templates, volumes, and models. + +## Install + +```bash +# Any platform (official installer) +curl -sSL https://cli.runpod.net | bash + +# macOS (Homebrew) +brew install runpod/runpodctl/runpodctl + +# macOS (manual — universal binary) +mkdir -p ~/.local/bin && curl -sL https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-darwin-all.tar.gz | tar xz -C ~/.local/bin + +# Linux +mkdir -p ~/.local/bin && curl -sL https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-linux-amd64.tar.gz | tar xz -C ~/.local/bin + +# Windows (PowerShell) +Invoke-WebRequest -Uri https://github.com/runpod/runpodctl/releases/latest/download/runpodctl-windows-amd64.zip -OutFile runpodctl.zip; Expand-Archive runpodctl.zip -DestinationPath $env:LOCALAPPDATA\runpodctl; [Environment]::SetEnvironmentVariable('Path', $env:Path + ";$env:LOCALAPPDATA\runpodctl", 'User') +``` + +Ensure `~/.local/bin` is on your `PATH` (add `export PATH="$HOME/.local/bin:$PATH"` to `~/.bashrc` or `~/.zshrc`). + +## Quick start + +```bash +runpodctl doctor # First time setup (API key + SSH) +runpodctl --help # See current top-level commands +runpodctl pod create --help # Inspect exact current flags before creating +runpodctl gpu list # See available GPUs +runpodctl hub search vllm # Find a hub repo +runpodctl serverless create --hub-id --name "my-vllm" # Deploy from hub +runpodctl template search pytorch # Find a template +runpodctl pod create --template-id runpod-torch-v21 --gpu-id "NVIDIA GeForce RTX 4090" # Create from template +runpodctl pod list # List your pods +``` + +API key: https://runpod.io/console/user/settings + +## Live Help Is Authoritative + +Live `runpodctl --help` output is authoritative for exact flags, aliases, and command syntax. Use this skill for workflows, decision rules, safety notes, and common examples. + +```bash +runpodctl --help +runpodctl --help +runpodctl --help +``` + +Before using unfamiliar commands, inspect live help first. Do not rely on this skill as an exhaustive flag reference. + +## Decision Rules + +- Use Hub when the user wants a known deployable app or worker such as vLLM, ComfyUI, Whisper, or a Runpod-maintained repo. +- Use templates when the user already has a template ID, wants reusable image/config defaults, or needs lower-level control than Hub. +- Use direct pod creation with `--image` when the user has a specific Docker image and does not need a saved template. +- Use serverless for request/response inference APIs and scalable workers; use pods for interactive work, notebooks, training, debugging, or long-lived sessions. +- Use CPU pods for preprocessing, file movement, lightweight scripts, and non-CUDA work. Use GPU pods when CUDA, model inference, training, or GPU memory is required. +- Do not pass GPU flags when creating CPU pods. Check `runpodctl pod create --help` for the current valid flag set. +- For SSH, prefer `runpodctl pod get ` or `runpodctl ssh info ` to retrieve connection details. Do not use deprecated interactive SSH commands. +- Network volumes are location-sensitive. Check datacenter availability before attaching volumes, and use `send` / `receive` or S3-compatible storage for migrations. +- Clean up paid resources after tests: delete serverless endpoints, pods, and temporary volumes created for validation. + +## Commands + +### Pods + +```bash +runpodctl pod list # List running pods (default, like docker ps) +runpodctl pod list --all # List all pods including exited +runpodctl pod list --status exited # Filter by status (RUNNING, EXITED, etc.) +runpodctl pod list --since 24h # Pods created within last 24 hours +runpodctl pod list --created-after 2025-01-15 # Pods created after date +runpodctl pod get # Get pod details (includes SSH info) +runpodctl pod create --template-id runpod-torch-v21 --gpu-id "NVIDIA GeForce RTX 4090" # Create from template +runpodctl pod create --image "runpod/pytorch:1.0.3-cu1281-torch291-ubuntu2404" --gpu-id "NVIDIA GeForce RTX 4090" # Create with image +runpodctl pod create --compute-type cpu --image ubuntu:22.04 # Create CPU pod +runpodctl pod start # Start stopped pod +runpodctl pod stop # Stop running pod +runpodctl pod restart # Restart pod +runpodctl pod reset # Reset pod +runpodctl pod update --name "new" # Update pod +runpodctl pod delete # Delete pod (aliases: rm, remove) +``` + +For exact pod flags, run `runpodctl pod --help`. + +### Hub + +Browse and search the Runpod Hub — a curated marketplace of deployable repos. + +```bash +runpodctl hub list # Top 10 by stars +runpodctl hub list --type SERVERLESS # Only serverless repos +runpodctl hub list --type POD # Only pod repos +runpodctl hub list --category ai --limit 20 # Filter by category +runpodctl hub list --order-by deploys # Order by deploys +runpodctl hub list --owner runpod-workers # Filter by repo owner +runpodctl hub search vllm # Search for "vllm" +runpodctl hub search whisper --type SERVERLESS # Search serverless repos +runpodctl hub get # Get by listing id +runpodctl hub get runpod-workers/worker-vllm # Get by owner/name +``` + +For exact Hub flags, run `runpodctl hub --help`. + +### Serverless (alias: sls) + +```bash +runpodctl serverless list # List all endpoints +runpodctl serverless get # Get endpoint details +runpodctl serverless create --name "x" --template-id "tpl_abc" # Create from template +runpodctl serverless create --name "x" --hub-id # Create from hub repo +runpodctl serverless create --hub-id --env MODEL_NAME=my-model # Override hub env defaults +runpodctl serverless create --template-id --gpu-id "NVIDIA GeForce RTX 4090" --model-reference https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct:main # Attach & cache a HF model (template or hub, GPU only) +runpodctl serverless create --hub-id --gpu-id "NVIDIA GeForce RTX 4090" --model-reference https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct:main # Attach a model on a hub deploy +runpodctl serverless update --workers-max 5 # Update endpoint +runpodctl serverless delete # Delete endpoint +``` + +**Create from hub:** `--hub-id` resolves the hub listing, extracts the build image and config (GPU IDs, container disk, env vars), creates an inline template, and deploys. Accepts both SERVERLESS and POD listing types. GPU IDs and env var defaults from the hub config are included automatically; override with `--gpu-id` and `--env`. + +**Model cache (`--model-reference`):** Attach a Hugging Face model to the endpoint by full URL with a ref, e.g. `https://huggingface.co/Qwen/Qwen2.5-0.5B-Instruct:main` (the trailing `:main` is the branch/tag/revision). Runpod caches the model on the host in the default Hugging Face cache directory (`/runpod-volume/huggingface-cache/hub/`), so the worker loads it directly — no need to bake the model into the image or attach a network volume. The flag is repeatable, so you can attach multiple models, and uses the standard HF cache path, so anything that already reads the Hugging Face cache (Transformers, vLLM, etc.) picks it up automatically. Works with both `--template-id` and `--hub-id`, but only with `--compute-type GPU`. Requires runpodctl v2.4.0+. + +For exact serverless flags, run `runpodctl serverless --help`. + +### Templates (alias: tpl) + +```bash +runpodctl template list # Official + community (first 10) +runpodctl template list --type official # All official templates +runpodctl template list --type community # Community templates (first 10) +runpodctl template list --type user # Your own templates +runpodctl template list --all # Everything including user +runpodctl template list --limit 50 # Show 50 templates +runpodctl template search pytorch # Search for "pytorch" templates +runpodctl template search comfyui --limit 5 # Search, limit to 5 results +runpodctl template search vllm --type official # Search only official +runpodctl template get # Get template details (includes README, env, ports) +runpodctl template create --name "x" --image "img" # Create template +runpodctl template create --name "x" --image "img" --serverless # Create serverless template +runpodctl template update --name "new" # Update template +runpodctl template delete # Delete template +``` + +For exact template flags, run `runpodctl template --help`. + +### Network Volumes (alias: nv) + +```bash +runpodctl network-volume list # List all volumes +runpodctl network-volume get # Get volume details +runpodctl network-volume create --name "x" --size 100 --data-center-id "US-GA-1" # Create volume +runpodctl network-volume update --name "new" # Update volume +runpodctl network-volume delete # Delete volume +``` + +For exact network volume flags, run `runpodctl network-volume --help`. + +### Models + +```bash +runpodctl model list # List your models +runpodctl model list --all # List all models +runpodctl model list --name "llama" # Filter by name +runpodctl model list --provider "meta" # Filter by provider +runpodctl model add --name "my-model" --model-path ./model # Add model +runpodctl model remove --name "my-model" # Remove model +``` + +For exact model flags, run `runpodctl model --help`. + +### Registry (alias: reg) + +```bash +runpodctl registry list # List registry auths +runpodctl registry get # Get registry auth +runpodctl registry create --name "x" --username "u" --password "p" # Create registry auth +runpodctl registry delete # Delete registry auth +``` + +For exact registry flags, run `runpodctl registry --help`. + +### Info + +```bash +runpodctl user # Account info and balance (alias: me) +runpodctl gpu list # List available GPUs +runpodctl gpu list --include-unavailable # Include unavailable GPUs +runpodctl datacenter list # List datacenters (alias: dc) +runpodctl billing pods # Pod billing history +runpodctl billing serverless # Serverless billing history +runpodctl billing network-volume # Volume billing history +``` + +For exact info and billing flags, run `runpodctl --help` or `runpodctl billing --help`. + +### SSH + +```bash +runpodctl ssh info # Get SSH info (command + key, does not connect) +runpodctl ssh list-keys # List SSH keys +runpodctl ssh add-key # Add SSH key +runpodctl ssh remove-key --name # Remove key by name +runpodctl ssh remove-key --fingerprint # Remove key by fingerprint +``` + +**Remove-key:** if multiple keys share a name, use `--fingerprint` to disambiguate. + +**Agent note:** `ssh info` returns connection details, not an interactive session. If interactive SSH is not available, execute commands remotely via `ssh user@host "command"`. + +### File Transfer + +```bash +runpodctl send # Send files (outputs code) +runpodctl receive # Receive files using code +``` + +### Utilities + +```bash +runpodctl doctor # Diagnose and fix CLI issues +runpodctl update # Update CLI +runpodctl version # Show version +runpodctl completion # Auto-detect shell and install completion +``` + +## URLs + +### Pod URLs + +Access exposed ports on your pod: + +``` +https://-.proxy.runpod.net +``` + +Example: `https://abc123xyz-8888.proxy.runpod.net` + +### Serverless URLs + +``` +https://api.runpod.ai/v2//run # Async request +https://api.runpod.ai/v2//runsync # Sync request +https://api.runpod.ai/v2//health # Health check +https://api.runpod.ai/v2//status/ # Job status +``` diff --git a/plugins/cloud-inference-skills/skills/runpodctl/evals/cpu-pod-create.eval.md b/plugins/cloud-inference-skills/skills/runpodctl/evals/cpu-pod-create.eval.md new file mode 100644 index 000000000..b975c4d2a --- /dev/null +++ b/plugins/cloud-inference-skills/skills/runpodctl/evals/cpu-pod-create.eval.md @@ -0,0 +1,19 @@ +# Create a CPU-only pod + +## Prompt + +Create a CPU-only pod for lightweight file preprocessing using the image +`ubuntu:22.04`. Give me the exact command. + +## Expected behavior + +The agent should: + +1. Use `runpodctl pod create` with `--compute-type cpu` +2. Pass `--image ubuntu:22.04` +3. NOT pass any GPU flags (`--gpu-id`, `--gpu-count`) — they don't belong on a CPU pod + +## Assertions + +- Runs `runpodctl pod create --compute-type cpu --image ubuntu:22.04` +- Does NOT include `--gpu-id` or `--gpu-count` diff --git a/plugins/cloud-inference-skills/skills/runpodctl/evals/hub-deploy-serverless.eval.md b/plugins/cloud-inference-skills/skills/runpodctl/evals/hub-deploy-serverless.eval.md new file mode 100644 index 000000000..6cae768a5 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/runpodctl/evals/hub-deploy-serverless.eval.md @@ -0,0 +1,31 @@ +# Deploy a vLLM serverless worker from the Runpod Hub + +## Prompt + +Deploy the vLLM serverless worker from the Runpod Hub. Use an available GPU, and +have it scale from 0 up to 2 workers. Give me the exact command(s). + +## Expected behavior + +The agent should: + +1. Find the hub listing id with `runpodctl hub search vllm` +2. Create the endpoint with `runpodctl serverless create --hub-id --workers-min 0 --workers-max 2` +3. Handle the GPU correctly (this is the easy thing to get wrong): + - Preferably omit `--gpu-id` and let the hub config's default GPU apply, OR + - If specifying `--gpu-id`, use a GPU **pool ID** (e.g. `AMPERE_48`, `ADA_24`, `HOPPER_141`) — NOT a display name like `"NVIDIA A40"` from `runpodctl gpu list`. On the `--hub-id` path the API rejects display names with `Invalid GPU Pool ID`. + +## Assertions + +- Finds the hub id via `runpodctl hub search vllm` (does not invent one) +- Runs `runpodctl serverless create --hub-id ...` +- Sets `--workers-min 0` and `--workers-max 2` +- If `--gpu-id` is passed at all, its value is a GPU pool ID (e.g. `AMPERE_48`), NOT a `gpu list` display name like `"NVIDIA A40"` +- Does NOT pass a `gpu list` display name to `--gpu-id` on the hub path + +## Notes + +This encodes the gotcha found via live testing and tracked upstream as +runpod/runpodctl#287: `serverless create --gpu-id` on the `--hub-id` path requires +GPU pool IDs, while `gpu list` (and the `--help` text) surface display names. Until +that is reconciled, the safe answer is to omit `--gpu-id` or use a pool ID. diff --git a/plugins/cloud-inference-skills/skills/runpodctl/evals/image-to-template-to-serverless.eval.md b/plugins/cloud-inference-skills/skills/runpodctl/evals/image-to-template-to-serverless.eval.md new file mode 100644 index 000000000..186204589 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/runpodctl/evals/image-to-template-to-serverless.eval.md @@ -0,0 +1,29 @@ +# Run a custom image as a serverless endpoint (template first) + +## Prompt + +I have my own custom Docker image `myrepo/infer:latest`. I want to run it as a +Runpod serverless endpoint that scales from 0 to 3 workers on an A40 GPU. Give me +the exact commands. + +## Expected behavior + +The agent should: + +1. Recognize that serverless endpoints are created from a `--template-id` or `--hub-id`, NOT directly from a raw image +2. First create a serverless template: `runpodctl template create --name ... --image myrepo/infer:latest --serverless` +3. Then create the endpoint from that template id: `runpodctl serverless create --template-id --workers-min 0 --workers-max 3 ...` +4. Order the two steps correctly (template before endpoint) + +## Assertions + +- Step 1 creates a template with `runpodctl template create --image myrepo/infer:latest --serverless` +- Step 2 creates the endpoint with `runpodctl serverless create --template-id ` +- Sets `--workers-min 0` and `--workers-max 3` +- Does NOT attempt `runpodctl serverless create --image ...` (no `--image` flag exists on serverless create) + +## Notes + +The template-id path is more lenient about `--gpu-id` than the hub path (it accepts +display names like `"NVIDIA A40"`), but see hub-deploy-serverless.eval.md and +runpod/runpodctl#287 for the pool-id inconsistency. diff --git a/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-auto-terminate.eval.md b/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-auto-terminate.eval.md new file mode 100644 index 000000000..9891ffdb4 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-auto-terminate.eval.md @@ -0,0 +1,22 @@ +# Create a pod that auto-terminates at a datetime + +## Prompt + +Create a GPU pod from the Docker image `myorg/trainer:latest` that automatically +terminates itself at 2026-07-01T00:00:00Z. Give me the exact command. + +## Expected behavior + +The agent should: + +1. Use `runpodctl pod create` with `--image myorg/trainer:latest` +2. Use the `--terminate-after` flag with the given datetime +3. Choose `--terminate-after` (deletes the pod) over `--stop-after` (only stops it), since the user asked for termination +4. Recognize this flag exists rather than declaring it impossible + +## Assertions + +- Runs `runpodctl pod create --image myorg/trainer:latest ...` +- Uses `--terminate-after 2026-07-01T00:00:00Z` +- Does NOT use `--stop-after` for this request +- Does NOT claim auto-termination is unsupported diff --git a/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-from-template-with-volume.eval.md b/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-from-template-with-volume.eval.md new file mode 100644 index 000000000..cb96ddb48 --- /dev/null +++ b/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-from-template-with-volume.eval.md @@ -0,0 +1,22 @@ +# Create a pod from a template with a network volume + +## Prompt + +Create a GPU pod named `trainer` from template id `tmpl-1`, and attach the network +volume with id `nv-9`. Give me the exact command. + +## Expected behavior + +The agent should: + +1. Use `runpodctl pod create` with `--template-id tmpl-1` +2. Set `--name trainer` +3. Attach the volume with `--network-volume-id nv-9` +4. Not need any extra GPU flag, since GPU is the default compute type + +## Assertions + +- Runs `runpodctl pod create ...` +- Uses `--template-id tmpl-1` +- Uses `--name trainer` +- Uses `--network-volume-id nv-9` diff --git a/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-ssh-connect.eval.md b/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-ssh-connect.eval.md new file mode 100644 index 000000000..ffcb9174a --- /dev/null +++ b/plugins/cloud-inference-skills/skills/runpodctl/evals/pod-ssh-connect.eval.md @@ -0,0 +1,20 @@ +# Get SSH connection details for a running pod + +## Prompt + +I have a running pod with id `pod-xyz`. I want to SSH into it to debug a process +interactively. What runpodctl command(s) should I use to get connected? + +## Expected behavior + +The agent should: + +1. Retrieve connection details with `runpodctl ssh info pod-xyz` (or `runpodctl pod get pod-xyz`) +2. Connect using the SSH command/key those return +3. NOT use any deprecated interactive SSH subcommand to open the session + +## Assertions + +- Uses `runpodctl ssh info pod-xyz` or `runpodctl pod get pod-xyz` to obtain host/port/key +- Does NOT rely on a deprecated interactive `runpodctl ssh`/`exec` session command +- Final guidance results in a usable `ssh ...` connection to the pod diff --git a/plugins/cloud-inference-skills/skills/runpodctl/evals/serverless-autoscale-by-requests.eval.md b/plugins/cloud-inference-skills/skills/runpodctl/evals/serverless-autoscale-by-requests.eval.md new file mode 100644 index 000000000..d2c9b326a --- /dev/null +++ b/plugins/cloud-inference-skills/skills/runpodctl/evals/serverless-autoscale-by-requests.eval.md @@ -0,0 +1,21 @@ +# Update a serverless endpoint to autoscale by pending requests + +## Prompt + +Update my serverless endpoint `ep-abc123` so it autoscales based on the number of +pending requests, triggering when there are 4 pending. Give me the exact command. + +## Expected behavior + +The agent should: + +1. Identify that `runpodctl serverless update ` is the right command +2. Use the v2.3 autoscaler flags `--scale-by requests` and `--scale-threshold 4` +3. NOT use the older `--scaler-type` / `--scaler-value` flags (removed in v2.3) or values like `REQUEST_COUNT` / `QUEUE_DELAY` + +## Assertions + +- Runs `runpodctl serverless update ep-abc123 ...` +- Sets `--scale-by requests` (strategy = pending request count) +- Sets `--scale-threshold 4` +- Does NOT use `--scaler-type`, `--scaler-value`, `REQUEST_COUNT`, or `QUEUE_DELAY` diff --git a/plugins/dotnet-skills/.codex-plugin/plugin.json b/plugins/dotnet-skills/.codex-plugin/plugin.json index b4c7c8843..491946cf9 100644 --- a/plugins/dotnet-skills/.codex-plugin/plugin.json +++ b/plugins/dotnet-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "dotnet-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Codex skills for choosing, bootstrapping, building, testing, packaging, diagnosing, and maintaining .NET projects with F# and C# as equal first-party languages.", "author": { "name": "Gale", diff --git a/plugins/game-dev-skills/.codex-plugin/plugin.json b/plugins/game-dev-skills/.codex-plugin/plugin.json index 11cb53ab5..5d51c81b7 100644 --- a/plugins/game-dev-skills/.codex-plugin/plugin.json +++ b/plugins/game-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "game-dev-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Apple platform game development workflow skills for SpriteKit, SceneKit, GameplayKit, controller input, haptics, profiling, and game-stack routing.", "author": { "name": "Gale", diff --git a/plugins/network-protocol-skills/.codex-plugin/plugin.json b/plugins/network-protocol-skills/.codex-plugin/plugin.json index d3c95aea8..b0c75c25e 100644 --- a/plugins/network-protocol-skills/.codex-plugin/plugin.json +++ b/plugins/network-protocol-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "network-protocol-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Codex skills for choosing, planning, implementing, and diagnosing modern application transports and real-time networking protocols, including QUIC, HTTP/3, WebRTC, Media over QUIC, WebTransport-adjacent handoffs, protocol maturity checks, and stack-specific implementation routing.", "author": { "name": "Gale", diff --git a/plugins/productivity-skills/.codex-plugin/plugin.json b/plugins/productivity-skills/.codex-plugin/plugin.json index d20d135b0..4da91e63b 100644 --- a/plugins/productivity-skills/.codex-plugin/plugin.json +++ b/plugins/productivity-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "productivity-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Broadly useful productivity workflows for Codex.", "author": { "name": "Gale", diff --git a/plugins/productivity-skills/pyproject.toml b/plugins/productivity-skills/pyproject.toml index f980d996d..dcc7bb570 100644 --- a/plugins/productivity-skills/pyproject.toml +++ b/plugins/productivity-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "productivity-skills-maintenance" -version = "8.1.0" +version = "8.2.0" description = "Maintainer-only Python tooling baseline for productivity-skills." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/productivity-skills/uv.lock b/plugins/productivity-skills/uv.lock index 5a7d8d235..86dfb601b 100644 --- a/plugins/productivity-skills/uv.lock +++ b/plugins/productivity-skills/uv.lock @@ -228,7 +228,7 @@ wheels = [ [[package]] name = "productivity-skills-maintenance" -version = "8.1.0" +version = "8.2.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/python-skills/.codex-plugin/plugin.json b/plugins/python-skills/.codex-plugin/plugin.json index 54bfb2a06..23dc1712c 100644 --- a/plugins/python-skills/.codex-plugin/plugin.json +++ b/plugins/python-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "python-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Bundled Python-focused Codex skills for uv bootstrapping, project implementation, diagnostics, packaging, tooling, CI, upgrades, FastAPI, FastMCP, and pytest workflows.", "author": { "name": "Gale", diff --git a/plugins/python-skills/pyproject.toml b/plugins/python-skills/pyproject.toml index 66a50947b..fc54cfb2e 100644 --- a/plugins/python-skills/pyproject.toml +++ b/plugins/python-skills/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "python-skills-maintainer" -version = "8.1.0" +version = "8.2.0" description = "Maintainer tooling for the python-skills repository" requires-python = ">=3.11" dependencies = [] diff --git a/plugins/python-skills/uv.lock b/plugins/python-skills/uv.lock index 23d917693..19119db70 100644 --- a/plugins/python-skills/uv.lock +++ b/plugins/python-skills/uv.lock @@ -251,7 +251,7 @@ wheels = [ [[package]] name = "python-skills-maintainer" -version = "8.1.0" +version = "8.2.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/reverse-engineering-skills/.codex-plugin/plugin.json b/plugins/reverse-engineering-skills/.codex-plugin/plugin.json index 71502f0c3..0b380b589 100644 --- a/plugins/reverse-engineering-skills/.codex-plugin/plugin.json +++ b/plugins/reverse-engineering-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "reverse-engineering-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Workflow skills for reverse engineering, decompilation, disassembly, symbol, and artifact-analysis tasks.", "skills": "./skills/", "author": { diff --git a/plugins/rust-skills/.codex-plugin/plugin.json b/plugins/rust-skills/.codex-plugin/plugin.json index c22626479..ef7840c5c 100644 --- a/plugins/rust-skills/.codex-plugin/plugin.json +++ b/plugins/rust-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "rust-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Rust, Cargo, rustup, crate, workspace, CLI, library, package, CI, testing, linting, and formatting workflow skills.", "skills": "./skills/", "author": { diff --git a/plugins/server-side-jvm/.codex-plugin/plugin.json b/plugins/server-side-jvm/.codex-plugin/plugin.json index eaa1ab6e0..5003f02d4 100644 --- a/plugins/server-side-jvm/.codex-plugin/plugin.json +++ b/plugins/server-side-jvm/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "server-side-jvm", - "version": "8.1.0", + "version": "8.2.0", "description": "Codex skills for choosing, building, testing, and maintaining server-side JVM backend projects with Java and Scala as equal first-party languages and future Clojure support planned.", "author": { "name": "Gale", diff --git a/plugins/server-side-swift/.codex-plugin/plugin.json b/plugins/server-side-swift/.codex-plugin/plugin.json index 9777fed12..101e7b3d7 100644 --- a/plugins/server-side-swift/.codex-plugin/plugin.json +++ b/plugins/server-side-swift/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "server-side-swift", - "version": "8.1.0", + "version": "8.2.0", "description": "Codex skills for bootstrapping, syncing, building, running, containerizing, deploying, and maintaining server-side Swift services, including Vapor, Hummingbird, hb, persistence, Swift OpenAPI, RPC-fit decisions, SwiftNIO, observability, auth, app sync, Docker, Apple Containerization, Fly.io, and SwiftPM-first workflows.", "author": { "name": "Gale", diff --git a/plugins/spotify/.codex-plugin/plugin.json b/plugins/spotify/.codex-plugin/plugin.json index cfc23ab17..33e359ffe 100644 --- a/plugins/spotify/.codex-plugin/plugin.json +++ b/plugins/spotify/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "spotify", - "version": "8.1.0", + "version": "8.2.0", "description": "Placeholder plugin repository for future Spotify-focused Codex workflows.", "author": { "name": "Gale", diff --git a/plugins/swift-lang/.codex-plugin/plugin.json b/plugins/swift-lang/.codex-plugin/plugin.json index 0234d332b..a737d7fc5 100644 --- a/plugins/swift-lang/.codex-plugin/plugin.json +++ b/plugins/swift-lang/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "swift-lang", - "version": "8.1.0", + "version": "8.2.0", "description": "Shared Swift language skills for API style, error handling, functional pipelines, formatting, source organization, and modernization cleanup.", "skills": "./skills/", "author": { diff --git a/plugins/swiftasb-skills/.codex-plugin/plugin.json b/plugins/swiftasb-skills/.codex-plugin/plugin.json index 30d167841..850804ed3 100644 --- a/plugins/swiftasb-skills/.codex-plugin/plugin.json +++ b/plugins/swiftasb-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "swiftasb-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Codex skills for explaining SwiftASB and building SwiftUI, AppKit, and Swift package integrations on top of it.", "author": { "name": "Gale", diff --git a/plugins/things-app/.codex-plugin/plugin.json b/plugins/things-app/.codex-plugin/plugin.json index 8c318b1a2..36a582326 100644 --- a/plugins/things-app/.codex-plugin/plugin.json +++ b/plugins/things-app/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "things-app", - "version": "8.1.0", + "version": "8.2.0", "description": "Things.app skills and a bundled local MCP server for reminders, planning digests, and structured task workflows.", "author": { "name": "Gale", diff --git a/plugins/things-app/mcp/pyproject.toml b/plugins/things-app/mcp/pyproject.toml index 3b903345f..31fd93cec 100644 --- a/plugins/things-app/mcp/pyproject.toml +++ b/plugins/things-app/mcp/pyproject.toml @@ -7,7 +7,7 @@ packages = ["app"] [project] name = "things-mcp" -version = "8.1.0" +version = "8.2.0" requires-python = ">=3.13" dependencies = [ "fastmcp>=3.0.2", diff --git a/plugins/things-app/mcp/uv.lock b/plugins/things-app/mcp/uv.lock index 6e7b8d001..344983825 100644 --- a/plugins/things-app/mcp/uv.lock +++ b/plugins/things-app/mcp/uv.lock @@ -1241,7 +1241,7 @@ wheels = [ [[package]] name = "things-mcp" -version = "8.1.0" +version = "8.2.0" source = { editable = "." } dependencies = [ { name = "fastmcp" }, diff --git a/plugins/things-app/pyproject.toml b/plugins/things-app/pyproject.toml index d759ec707..aec36a6e1 100644 --- a/plugins/things-app/pyproject.toml +++ b/plugins/things-app/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "things-app-maintenance" -version = "8.1.0" +version = "8.2.0" description = "Maintainer-only Python tooling baseline for things-app skills and plugin packaging." requires-python = ">=3.11" dependencies = [] diff --git a/plugins/things-app/uv.lock b/plugins/things-app/uv.lock index 974571605..6e298e0ca 100644 --- a/plugins/things-app/uv.lock +++ b/plugins/things-app/uv.lock @@ -120,7 +120,7 @@ wheels = [ [[package]] name = "things-app-maintenance" -version = "8.1.0" +version = "8.2.0" source = { virtual = "." } [package.dev-dependencies] diff --git a/plugins/web-dev-skills/.codex-plugin/plugin.json b/plugins/web-dev-skills/.codex-plugin/plugin.json index 8c887a831..f05f3e20f 100644 --- a/plugins/web-dev-skills/.codex-plugin/plugin.json +++ b/plugins/web-dev-skills/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "web-dev-skills", - "version": "8.1.0", + "version": "8.2.0", "description": "Codex skills for focused web and Expo native-boundary workflows.", "author": { "name": "Gale", diff --git a/pyproject.toml b/pyproject.toml index 05540ba39..7052e2058 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "socket-maintenance" -version = "8.1.0" +version = "8.2.0" description = "Root uv tooling baseline for the socket superproject." requires-python = ">=3.11" dependencies = [] diff --git a/uv.lock b/uv.lock index 7343208d3..fda81b1b1 100644 --- a/uv.lock +++ b/uv.lock @@ -286,7 +286,7 @@ wheels = [ [[package]] name = "socket-maintenance" -version = "8.1.0" +version = "8.2.0" source = { virtual = "." } [package.dev-dependencies]