@rudderhq/agent-runtime-codex-local 0.1.0-canary.0

package/skills/rudder-create-agent/references/api-reference.md

@@ -0,0 +1,172 @@
+# Rudder Create Agent API Reference
+
+Internal/debug reference for the bundled `rudder-create-agent` skill.
+
+- Normal runtime execution should follow the CLI-first workflow in `../SKILL.md`.
+- The canonical command catalog lives in `cli-reference.md`.
+- Keep this document for route-level debugging, compatibility work, and payload-shape inspection.
+
+## CLI-to-API Mapping
+
+| CLI command | Primary route |
+| --- | --- |
+| `rudder agent config index` | `GET /llms/agent-configuration.txt` |
+| `rudder agent config doc <agentRuntimeType>` | `GET /llms/agent-configuration/:agentRuntimeType.txt` |
+| `rudder agent icons` | `GET /llms/agent-icons.txt` |
+| `rudder agent config list --org-id <orgId>` | `GET /api/orgs/:orgId/agent-configurations` |
+| `rudder agent config get <agentId>` | `GET /api/agents/:agentId/configuration` |
+| `rudder agent hire --org-id <orgId> --payload <json>` | `POST /api/orgs/:orgId/agent-hires` |
+| `rudder approval get <approvalId>` | `GET /api/approvals/:approvalId` |
+| `rudder approval comment <approvalId> --body <text>` | `POST /api/approvals/:approvalId/comments` |
+| `rudder approval resubmit <approvalId> [--payload <json>]` | `POST /api/approvals/:approvalId/resubmit` |
+| `rudder approval issues <approvalId>` | `GET /api/approvals/:approvalId/issues` |
+
+## Reflection Endpoints
+
+- `GET /llms/agent-configuration.txt`
+- `GET /llms/agent-configuration/:agentRuntimeType.txt`
+- `GET /llms/agent-icons.txt`
+
+Auth:
+
+- board access, or
+- same-org agent auth with `canCreateAgents=true`
+
+These endpoints return plain text. The CLI wraps them directly.
+
+## Configuration Snapshots
+
+- `GET /api/orgs/:orgId/agent-configurations`
+- `GET /api/agents/:agentId/configuration`
+
+These responses are redacted snapshots for comparison and reuse.
+
+Representative shape:
+
+```json
+{
+  "id": "uuid",
+  "orgId": "uuid",
+  "name": "CTO",
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "status": "idle",
+  "reportsTo": "uuid-or-null",
+  "agentRuntimeType": "codex_local",
+  "agentRuntimeConfig": {
+    "cwd": "/absolute/path",
+    "model": "o4-mini"
+  },
+  "runtimeConfig": {
+    "heartbeat": {
+      "enabled": true,
+      "intervalSec": 300,
+      "wakeOnDemand": true
+    }
+  },
+  "permissions": {
+    "canCreateAgents": true
+  },
+  "updatedAt": "2026-04-19T12:00:00.000Z"
+}
+```
+
+## `POST /api/orgs/:orgId/agent-hires`
+
+Canonical hire route used by `rudder agent hire`.
+
+Request body:
+
+```json
+{
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "icon": "crown",
+  "reportsTo": "uuid-or-null",
+  "capabilities": "Owns architecture and engineering execution",
+  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
+  "agentRuntimeType": "codex_local",
+  "agentRuntimeConfig": {
+    "cwd": "/absolute/path",
+    "model": "o4-mini",
+    "promptTemplate": "You are CTO..."
+  },
+  "runtimeConfig": {
+    "heartbeat": {
+      "enabled": true,
+      "intervalSec": 300,
+      "wakeOnDemand": true
+    }
+  },
+  "budgetMonthlyCents": 0,
+  "sourceIssueId": "uuid-or-null",
+  "sourceIssueIds": ["uuid-1", "uuid-2"]
+}
+```
+
+Response when approval is required:
+
+```json
+{
+  "agent": {
+    "id": "uuid",
+    "status": "pending_approval"
+  },
+  "approval": {
+    "id": "uuid",
+    "type": "hire_agent",
+    "status": "pending",
+    "payload": {
+      "desiredSkills": ["vercel-labs/agent-browser/agent-browser"]
+    }
+  }
+}
+```
+
+Response when approval is not required:
+
+```json
+{
+  "agent": {
+    "id": "uuid",
+    "status": "idle"
+  },
+  "approval": null
+}
+```
+
+Important notes:
+
+- `name` is optional; if omitted or blank, Rudder assigns a distinct first name automatically
+- `desiredSkills` accepts organization skill ids, canonical keys, or a unique slug; the server resolves and stores canonical organization skill keys
+- `sourceIssueId` and `sourceIssueIds` are the canonical way to link the hire back to originating issues
+- this route is preferred over creating `hire_agent` approvals manually because it preserves the organization's approval policy
+
+## Approval Lifecycle
+
+Relevant routes:
+
+- `GET /api/approvals/:approvalId`
+- `POST /api/approvals/:approvalId/comments`
+- `POST /api/approvals/:approvalId/resubmit`
+- `GET /api/approvals/:approvalId/issues`
+
+Statuses:
+
+- `pending`
+- `revision_requested`
+- `approved`
+- `rejected`
+- `cancelled`
+
+For hire approvals:
+
+- approved: linked agent transitions `pending_approval -> idle`
+- rejected: linked agent is terminated
+
+## Safety Notes
+
+- Config read APIs redact obvious secrets.
+- `pending_approval` agents cannot run heartbeats, receive assignments, or create keys.
+- All hire and approval actions are logged in activity for auditability.
+- Use markdown in issue and approval comments and include links to the approval, agent, and source issue.

package/skills/rudder-create-agent/references/cli-reference.md

@@ -0,0 +1,126 @@
+# Rudder Create Agent CLI Reference
+
+Canonical CLI contract for the bundled `rudder-create-agent` skill. Prefer these commands over direct `/api` calls.
+
+## Defaults
+
+- All commands support `--json`.
+- `--org-id` defaults to `RUDDER_ORG_ID` when relevant.
+- Mutating commands attach `RUDDER_RUN_ID` automatically when available.
+- `agent config index`, `agent config doc`, and `agent icons` print plain text by default. With `--json`, they emit that text as a JSON string.
+
+## Core CLI Surface
+
+### Identity and discovery
+
+```sh
+rudder agent me --json
+rudder agent list --org-id "$RUDDER_ORG_ID" --json
+rudder agent get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
+rudder agent config index
+rudder agent config doc "<agent-runtime-type>"
+rudder agent config list --org-id "$RUDDER_ORG_ID" --json
+rudder agent config get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
+rudder agent icons
+```
+
+Use these in order:
+
+1. `agent me` to verify auth and org context
+2. `agent config index` to discover installed runtimes
+3. `agent config doc` to read one runtime's required fields and examples
+4. `agent list` plus `agent config list/get` to reuse proven patterns from related agents
+5. `agent icons` to choose an allowed `icon`
+
+### Organization skills
+
+```sh
+rudder skill list --org-id "$RUDDER_ORG_ID" --json
+rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
+rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
+rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
+rudder skill scan-local --org-id "$RUDDER_ORG_ID" --roots "<csv>" --json
+rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --project-ids "<csv>" --workspace-ids "<csv>" --json
+```
+
+Use these before hiring when the new role needs `desiredSkills`.
+
+`desiredSkills` accepts:
+
+- exact organization skill key
+- exact organization skill id
+- exact slug when it is unique in the organization
+
+### Canonical hire flow
+
+```sh
+rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
+  "role": "cto",
+  "title": "Chief Technology Officer",
+  "icon": "crown",
+  "reportsTo": "<ceo-agent-id>",
+  "capabilities": "Owns technical roadmap, architecture, staffing, execution",
+  "desiredSkills": ["vercel-labs/agent-browser/agent-browser"],
+  "agentRuntimeType": "codex_local",
+  "agentRuntimeConfig": {"cwd": "/abs/path/to/repo", "model": "o4-mini"},
+  "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true}},
+  "sourceIssueId": "<issue-id>"
+}' --json
+```
+
+Canonical semantics:
+
+- this wraps `POST /api/orgs/:orgId/agent-hires`
+- if the organization does not require board approval, the response contains `approval: null` and the agent is created directly
+- if the organization requires board approval, the response contains both `agent` and `approval`, and the new agent stays `pending_approval`
+
+Do not use `rudder approval create --type hire_agent` as a replacement for `agent hire` during normal skill execution. That is a lower-level compatibility surface and does not preserve the canonical direct-create behavior.
+
+### Approval follow-up
+
+```sh
+rudder approval get "<approval-id>" --json
+rudder approval comment "<approval-id>" --body "<markdown>" --json
+rudder approval resubmit "<approval-id>" --payload '{"...":"..."}' --json
+rudder approval issues "<approval-id>" --json
+```
+
+Notes:
+
+- `approval comment` should use markdown and link the approval, pending agent, and source issue when available
+- `approval resubmit` is only for a revision-requested approval; update the payload instead of creating a second hire
+- if the run wakes with `RUDDER_APPROVAL_ID`, treat that approval as the first task
+
+## Payload Notes
+
+The `agent hire` payload accepts the same shape as the hire API, including:
+
+- `name` optional; blank or omitted means Rudder assigns a distinct first name
+- `role`
+- `title`
+- `icon`
+- `reportsTo`
+- `capabilities`
+- `desiredSkills`
+- `agentRuntimeType`
+- `agentRuntimeConfig`
+- `runtimeConfig`
+- `budgetMonthlyCents`
+- `metadata`
+- `sourceIssueId`
+- `sourceIssueIds`
+
+Issue linkage rule:
+
+- prefer `sourceIssueId` or `sourceIssueIds` inside the hire payload
+- use `approval issues` to inspect the resulting approval links after the server creates them
+
+## Related Commands
+
+Post-hire adjustments use the normal agent and skill surfaces:
+
+```sh
+rudder agent get "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
+rudder agent skills sync "<agent-id>" --desired-skills "<csv>" --json
+rudder agent local-cli "<agent-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --json
+```

package/skills/rudder-create-plugin/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rudder-create-plugin
+description: Create new Rudder plugins with the current alpha SDK/runtime. Use when scaffolding a plugin package, adding a new example plugin, or updating plugin authoring docs. Covers the supported worker/UI surface, route conventions, scaffold flow, and verification steps.
+  Create new Rudder plugins with the current alpha SDK/runtime. Use when
+  scaffolding a plugin package, adding a new example plugin, or updating plugin
+  authoring docs. Covers the supported worker/UI surface, route conventions,
+  scaffold flow, and verification steps.
+allowed-tools: 
+disable: true
+---
+
+# Create a Rudder Plugin
+
+Use this skill when the task is to create, scaffold, or document a Rudder plugin.
+
+## 1. Ground rules
+
+Read these first when needed:
+
+1. `doc/plugins/PLUGIN_AUTHORING_GUIDE.md`
+2. `packages/plugins/sdk/README.md`
+3. `doc/plugins/PLUGIN_SPEC.md` only for future-looking context
+
+Current runtime assumptions:
+
+- plugin workers are trusted code
+- plugin UI is trusted same-origin host code
+- worker APIs are capability-gated
+- plugin UI is not sandboxed by manifest capabilities
+- no host-provided shared plugin UI component kit yet
+- `ctx.assets` is not supported in the current runtime
+
+## 2. Preferred workflow
+
+Use the scaffold package instead of hand-writing the boilerplate:
+
+```bash
+pnpm --filter @rudderhq/create-rudder-plugin build
+node packages/plugins/create-rudder-plugin/dist/index.js <npm-package-name> --output <target-dir>
+```
+
+For a plugin that lives outside the Rudder repo, pass `--sdk-path` and let the scaffold snapshot the local SDK/shared packages into `.rudder-sdk/`:
+
+```bash
+pnpm --filter @rudderhq/create-rudder-plugin build
+node packages/plugins/create-rudder-plugin/dist/index.js @acme/plugin-name \
+  --output /absolute/path/to/plugin-repos \
+  --sdk-path /absolute/path/to/rudder/packages/plugins/sdk
+```
+
+Recommended target inside this repo:
+
+- `packages/plugins/examples/` for example plugins
+- another `packages/plugins/<name>/` folder if it is becoming a real package
+
+## 3. After scaffolding
+
+Check and adjust:
+
+- `src/manifest.ts`
+- `src/worker.ts`
+- `src/ui/index.tsx`
+- `tests/plugin.spec.ts`
+- `package.json`
+
+Make sure the plugin:
+
+- declares only supported capabilities
+- does not use `ctx.assets`
+- does not import host UI component stubs
+- keeps UI self-contained
+- uses `routePath` only on `page` slots
+- is installed into Rudder from an absolute local path during development
+
+## 4. If the plugin should appear in the app
+
+For bundled example/discoverable behavior, update the relevant host wiring:
+
+- bundled example list in `server/src/routes/plugins.ts`
+- any docs that list in-repo examples
+
+Only do this if the user wants the plugin surfaced as a bundled example.
+
+## 5. Verification
+
+Always run:
+
+```bash
+pnpm --filter <plugin-package> typecheck
+pnpm --filter <plugin-package> test
+pnpm --filter <plugin-package> build
+```
+
+If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
+
+## 6. Documentation expectations
+
+When authoring or updating plugin docs:
+
+- distinguish current implementation from future spec ideas
+- be explicit about the trusted-code model
+- do not promise host UI components or asset APIs
+- prefer npm-package deployment guidance over repo-local workflows for production