@rudderhq/agent-runtime-opencode-local 0.5.0 → 0.5.1

package/skills/rudder-docs/references/plugin-authoring.md

@@ -0,0 +1,116 @@
+# Plugin Authoring
+
+Use this workflow for a Rudder Plugin source question or an explicit request to
+scaffold, develop, or verify a Plugin. Reading authoring guidance is read-only.
+Only an explicit user request to scaffold or modify a package authorizes writes,
+and those writes must stay inside the requested repository or target directory.
+
+The current fact sources are
+`doc/engineering/PLUGIN_AUTHORING_GUIDE.md` and
+`packages/plugins/sdk/README.md`. Use
+`doc/engineering/PLUGIN_RUNTIME_CONTRACT.md` only to understand the implemented
+runtime boundary, and label future ideas as non-current.
+
+## Section Map
+
+- [Confirm scope and package layout](#confirm-scope-and-package-layout)
+- [Scaffold from the current package](#scaffold-from-the-current-package)
+- [Implement within current boundaries](#implement-within-current-boundaries)
+- [Wire a bundled example only when requested](#wire-a-bundled-example-only-when-requested)
+- [Verify the package and host](#verify-the-package-and-host)
+
+## Confirm Scope And Package Layout
+
+Before writing, determine whether the Plugin is:
+
+- a repository-local example under `packages/plugins/examples/`;
+- another Rudder monorepo package under `packages/plugins/`; or
+- an external npm package in an absolute target directory.
+
+Repository-local examples are a development workflow. For deployable Plugins,
+prefer an npm package installed from a public or private npm-compatible
+registry. GitHub installs are not a first-class path today.
+
+Treat both Plugin workers and Plugin UI as trusted code. Plugin UI runs as
+same-origin JavaScript and is not sandboxed by manifest capabilities.
+Worker-side host APIs are capability-gated. Keep these boundaries visible when
+reviewing third-party code or selecting capabilities.
+
+## Scaffold From The Current Package
+
+Use `create-rudder-plugin` instead of hand-writing boilerplate. In a Rudder
+checkout, first build the scaffold package, then run its generated CLI for the
+requested npm package name and output root. `--output` names the parent
+directory; the CLI appends the package basename, and that destination must not
+already exist. Verify the exact commands in
+the current authoring guide before execution.
+
+For a repository-local package, the scaffold uses `workspace:*` for
+`@rudderhq/plugin-sdk`. For an external package, pass `--sdk-path` pointing to
+the checkout's `packages/plugins/sdk`; the scaffold snapshots the SDK/shared
+packages into `.rudder-sdk/` so the Plugin can build and test before an npm
+publication exists.
+
+The generated package should include:
+
+- `src/manifest.ts`;
+- `src/worker.ts`;
+- `src/ui/index.tsx` when UI is used;
+- `tests/plugin.spec.ts`;
+- `package.json` and current build configuration.
+
+Scaffold only under the explicit output root and confirm the derived package
+directory before execution. Do not install the generated Plugin into a running
+Rudder instance unless the user also requested that host mutation.
+
+## Implement Within Current Boundaries
+
+Review the manifest, worker, UI, and tests together:
+
+- Declare only capabilities used by the worker-side host APIs.
+- Keep tool names Plugin-namespaced; they must not shadow core or other Plugin
+  tools.
+- Keep UI self-contained. Rudder does not provide a shared Plugin React
+  component kit yet.
+- Do not use `ctx.assets`; it is not supported in the current runtime.
+- Use `routePath` only for a `page` slot. It must be one lowercase slug and may
+  not collide with a reserved host route or another installed Plugin page.
+- Use the SDK's declared worker, UI, testing, bundler, and dev-server surfaces
+  rather than undocumented application internals.
+- Treat jobs and webhooks as namespaced external execution surfaces and keep
+  their capabilities, ownership, logs, and failure evidence explicit.
+
+Local development installs must use an absolute filesystem path. The server
+can watch a local-path Plugin and restart its worker after rebuilds, but that
+does not make a repo-local checkout a production deployment artifact.
+
+## Wire A Bundled Example Only When Requested
+
+Only if the user explicitly asks for bundled example or discoverable host
+wiring, update the host's bundled-example list and the documentation that
+enumerates in-repo examples. A request to scaffold or develop a Plugin alone
+does not authorize changing `server/src/routes/plugins.ts` or other host
+registration surfaces.
+
+If host runtime, SDK, capability validation, static UI serving, or lifecycle
+code changes, follow the repository's Plugin engineering and Product Logic
+rules in addition to the package workflow.
+
+## Verify The Package And Host
+
+At minimum, run the generated or existing Plugin package's:
+
+- `typecheck`;
+- `test`; and
+- `build`.
+
+Use the package scripts or the monorepo's `pnpm --filter <plugin-package>`
+forms. For a new scaffold, execute them in a temporary or explicitly requested
+target and confirm that its worker, manifest, UI bundle, and
+`tests/plugin.spec.ts` compile against the selected SDK layout.
+
+When host or SDK code changed, also run the relevant host integration tests,
+repository typecheck, test suite, and build. If the user asked to install the
+Plugin, verify the real host from its absolute local path and surface worker
+health, logs, route behavior, and capability failures. Package creation alone
+is not evidence that a Plugin is installed or active in Rudder.

package/skills/rudder-docs/references/source-map.md

@@ -25,6 +25,30 @@ two pages. Prefer the user's language when equivalent official pages exist.
 Public docs own published user guidance; a local `docs/` checkout is useful
 when the live site is unavailable or the task is editing the public site.
 
+Use these routes for governance and operational evidence questions:
+
+| User topic | English | 简体中文 |
+| --- | --- | --- |
+| Approvals, budgets, cost, and activity | `https://docs.rudderhq.dev/reference/approvals-budgets-activity` | `https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity` |
+| Run evidence and Run detail | `https://docs.rudderhq.dev/concepts/agents` | `https://docs.rudderhq.dev/zh/concepts/agents` |
+| Dashboard summary | `https://docs.rudderhq.dev/concepts/overview` | `https://docs.rudderhq.dev/zh/concepts/overview` |
+| Calendar source and history | `https://docs.rudderhq.dev/concepts/calendar` | `https://docs.rudderhq.dev/zh/concepts/calendar` |
+| Human attention, Inbox, and Messenger | `https://docs.rudderhq.dev/concepts/chat-messenger` | `https://docs.rudderhq.dev/zh/concepts/chat-messenger` |
+
+The approvals reference includes stable `#approvals`, `#budgets-and-cost`, and
+`#activity` anchors for narrow retrieval. Legacy public URLs are compatibility
+entries only. Cite the canonical routes in new answers.
+
+Other lookup pages are similarly narrow:
+
+| User topic | English | 简体中文 |
+| --- | --- | --- |
+| Issue states | `https://docs.rudderhq.dev/reference/issue-statuses` | `https://docs.rudderhq.dev/zh/reference/issue-statuses` |
+| Runtime choices and readiness | `https://docs.rudderhq.dev/reference/runtime-types` | `https://docs.rudderhq.dev/zh/reference/runtime-types` |
+| Workspace and file placement | `https://docs.rudderhq.dev/reference/workspace-boundaries` | `https://docs.rudderhq.dev/zh/reference/workspace-boundaries` |
+| Automation result destinations | `https://docs.rudderhq.dev/reference/automation-output-routing` | `https://docs.rudderhq.dev/zh/reference/automation-output-routing` |
+| Deployment trust, credentials, Browser, and platform behavior | `https://docs.rudderhq.dev/reference/permissions-and-platforms` | `https://docs.rudderhq.dev/zh/reference/permissions-and-platforms` |
+
 ## Product Logic Registry
 
 - Entry point: `doc/product/README.md`
@@ -50,7 +74,7 @@ Common domain routes include:
 - Chat, Messenger, comments, and integrations:
   `doc/product/domains/collaboration/`
 - approvals, budgets, costs, and activity:
-  `doc/product/domains/control-plane/`
+  `doc/product/domains/governance-and-visibility/`
 - reviews, feedback, and learning:
   `doc/product/domains/review-feedback-learning/`
 - automations: `doc/product/domains/automations/`
@@ -114,7 +138,7 @@ Within this package:
 
 - `cli-reference.md` preserves the typed capability and CLI fallback catalog;
 - `api-reference.md` preserves internal/debug compatibility endpoints;
-- `control-plane-practices.md` preserves conditional operating semantics; and
+- `operating-practices.md` preserves conditional operating semantics; and
 - `organization-skills.md` preserves organization skill workflows.
 
 Use only the relevant section. These references are version-adjacent fallback

package/skills/visualize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: visualize
-description: "Create safe inline visual explanations in Rudder Chat. Use when asked for a chart, plot, diagram, timeline, comparison, static map, simulator, scenario view, or compact visual that materially improves understanding. Prefer Mermaid for static node-and-edge structures; use Rudder's HTML/SVG/CSS artifact path only when thread-scoped output is available. Rudder visuals are declarative and scriptless: convert simulator requests to static scenarios or disclosure-based comparisons and never rely on JavaScript, network access, or external assets."
-compatibility: "Rudder Chat inline visual capture. HTML artifacts require a thread-scoped visualization directory exposed by the current runtime."
+description: "Create safe inline visual explanations in Rudder Chat. Use when asked for a chart, plot, diagram, timeline, comparison, static map, simulator, scenario view, or compact visual that materially improves understanding. Prefer Mermaid for static node-and-edge structures; use Rudder's runtime-neutral HTML/SVG/CSS message envelope for custom geometry. Rudder visuals are declarative and scriptless: convert simulator requests to static scenarios or disclosure-based comparisons and never rely on JavaScript, network access, or external assets."
+compatibility: "Rudder Chat v1 inline visual message protocol. Provider-neutral and filesystem-independent; outside Rudder Chat, fall back to Mermaid, Markdown, or prose."
 ---
 
 # Visualize
@@ -16,38 +16,40 @@ access, so design for a useful first render with declarative HTML, SVG, and CSS.
    a static structure or flow. Do not create an HTML artifact for that case.
 2. Use an inline visual for charts, timelines, comparisons, spatial layouts,
    static scenario views, or compact reports that benefit from custom geometry.
-3. Create an HTML artifact only when the current run exposes a writable,
-   thread-scoped visualization directory ending in
-   `visualizations/YYYY/MM/DD/<thread-id>`. Use the exact directory from the
-   runtime's writable roots. Never infer, scan for, or create another thread's
-   directory.
-4. If that directory is unavailable, fall back to Mermaid, Markdown tables, or
-   concise prose. Do not emit a directive that Rudder cannot resolve.
-
-## File And Directive
-
-- Choose a concise ASCII lowercase-hyphenated title and write
-  `<title>.html` inside the current thread-scoped visualization directory.
+3. Use the v1 message envelope only in Rudder Chat. It is a Rudder protocol,
+   independent of Codex, Claude, Gemini, Cursor, OpenCode, Pi, Hermes, process,
+   HTTP, or gateway filesystem conventions.
+4. Outside Rudder Chat, fall back to Mermaid, Markdown tables, or concise prose.
+   Do not emit a Rudder envelope on a surface that cannot render it.
+
+## Message Envelope
+
 - Write only an HTML fragment. Do not include a doctype or `html`, `head`, or
   `body` elements.
-- Keep every fragment under 2 MiB and emit at most three visuals in one
-  assistant message.
+- Keep every fragment at or below 64 KiB UTF-8, all fragments together at or
+  below 128 KiB, and the complete visual-bearing final reply at or below
+  256 KiB. Emit at most three visuals in one assistant message.
 - Give the fragment one top-level markup root, `<div id="widget">`. Bounded
   `<style>` blocks may precede that root.
 - Put any custom CSS in bounded `<style>` elements. Inline `style` attributes
   are removed.
-- Read the file back before replying. Fix escaped markup such as literal `\"`
+- Check the fragment before replying. Fix escaped markup such as literal `\"`
   or `\n`, missing labels, clipped content, and malformed SVG.
-- Add this exact directive on its own line where the visual should render:
+- Put this exact opening marker on its own line where the visual should render,
+  then the fragment, then the exact closing marker on its own line:
 
 ```text
-::codex-inline-vis{file="<title>.html"}
+:::rudder-inline-visual:v1
+<style>#widget .series { color: var(--viz-series-1); }</style>
+<div id="widget">...</div>
+:::rudder-inline-visual:end
 ```
 
-Use only the `file` attribute. The value must be a basename ending in `.html`;
-paths, separators, traversal, extra attributes, and alternate quoting are
-rejected. Keep any necessary explanation outside the fragment and do not add a
-second Markdown link to the file.
+The markers must have no indentation, attributes, or trailing text. Keep any
+necessary explanation outside the envelope. Never emit
+`::codex-inline-vis{...}`, `::rudder-inline-vis{...}`, a file path, an iframe,
+or a second link to source HTML; Rudder owns capture, trusted placement,
+persistence, sandboxing, and rendering.
 
 ## Rudder Safety Boundary
 
@@ -120,13 +122,13 @@ not as data or copy to repeat.
 
 Before replying:
 
-1. Confirm the file is in the exact current-thread visualization directory,
-   uses an allowed basename, is below 2 MiB, and the message has no more than
-   three directives.
+1. Confirm each envelope uses the exact v1 markers, satisfies the 64/128/256 KiB
+   limits, and the message has no more than three visuals.
 2. Confirm the fragment contains no scripts, handlers, URLs, external assets,
    active controls, document-level elements, or unsupported embeds.
 3. Confirm SVG view boxes, labels, referenced IDs, table semantics, and CSS
    selectors are valid.
 4. Check both narrow and wide layout when a preview path is available. If not,
    keep the geometry responsive and the composition conservative.
-5. Emit the directive only after the file is complete and readable.
+5. Emit the envelope only after the fragment is complete and valid. Never leave
+   an opening marker unterminated.

package/skills/visualize/references/runtime-contract.md

@@ -2,8 +2,9 @@
 
 Read this reference when producing a Rudder inline visual. The runtime is
 scriptless, sanitized, isolated from Rudder state, and has no network access.
-Every fragment must be under 2 MiB, and one assistant message may reference at
-most three fragments.
+Every fragment must be at or below 64 KiB UTF-8, all fragment bodies together
+must be at or below 128 KiB, the complete visual-bearing final reply must be at
+or below 256 KiB, and one assistant message may contain at most three fragments.
 
 ## Output Envelope
 
@@ -12,16 +13,25 @@ Write a fragment with one top-level markup root, `<div id="widget">`. Bounded
 `head`, or `body`; Rudder extracts and sanitizes the CSS before it sanitizes the
 markup.
 
-The assistant message must place this exact directive on its own line:
+The final Rudder Chat message places the fragment inside this exact v1 envelope:
 
 ```text
-::codex-inline-vis{file="<title>.html"}
+:::rudder-inline-visual:v1
+<style>#widget .series { color: var(--viz-series-1); }</style>
+<div id="widget">...</div>
+:::rudder-inline-visual:end
 ```
 
-Only a current-run file from the exact thread-scoped visualization directory is
-eligible for capture. Rudder rejects absolute paths, separators, traversal,
-symlink escapes, missing files, stale files, oversized files, malformed
-directives, unknown attributes, and duplicate attributes.
+Both marker lines must be unindented, exact, and free of trailing text. Rudder
+rejects nested, empty, unterminated, excessive, and oversized envelopes. It
+buffers the fragment during streaming, publishes it only after a successful
+complete result, and replaces it with a Server-owned trusted placement. The
+Agent never writes a provider visualization directory, file directive,
+attachment id, canonical placement, iframe, or source link.
+
+The v1 authoring protocol is the same for every conforming Rudder Agent Runtime.
+Legacy `::codex-inline-vis{file="..."}` input remains readable during migration,
+but new output must never emit it.
 
 ## Preserved Markup
 

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

@@ -1,185 +0,0 @@
----
-name: rudder-create-agent
-description: Create new agents in Rudder through the `rudder` CLI with governance-aware hiring. Use when you need to inspect adapter configuration options, compare existing agent configs, draft a new agent prompt/config, and submit a hire request.
----
-
-# Rudder Create Agent Skill
-
-Use this skill when you are asked to hire or create an agent in Rudder.
-
-## Preconditions
-
-You need either:
-
-- board access, or
-- agent permission `canCreateAgents=true` in your org
-
-If you do not have this permission, escalate to your CEO or board.
-
-This workflow is **CLI-first**.
-
-- Use `rudder ... --json` for structured reads and mutations.
-- Use `references/cli-reference.md` as the canonical command catalog for this skill.
-- Treat `references/api-reference.md` as internal/debug/compatibility documentation, not the normal runtime interface.
-- Do not create agent directories, instruction files, or org metadata manually as a fallback.
-- If CLI auth is unavailable in a heartbeat run, stop and report the auth problem instead of mutating the filesystem.
-
-## Workflow
-
-1. Confirm identity and organization context.
-
-```sh
-rudder agent me --json
-```
-
-If this returns `{"error":"Agent authentication required"}`, treat it as a run-auth failure:
-
-- do not ask for `RUDDER_API_KEY` inside the heartbeat
-- do not fall back to manual filesystem creation
-- stop and report that injected agent authentication is missing or invalid for this run
-
-2. Discover available adapter configuration docs for this Rudder instance.
-
-```sh
-rudder agent config index
-```
-
-3. Read adapter-specific docs for the runtime you plan to use.
-
-```sh
-rudder agent config doc codex_local
-rudder agent config doc claude_local
-```
-
-4. Compare existing agents and redacted configurations in your organization.
-
-```sh
-rudder agent list --org-id "$RUDDER_ORG_ID" --json
-rudder agent config list --org-id "$RUDDER_ORG_ID" --json
-rudder agent config get "<agent-id>" --json
-```
-
-5. If the role needs organization skills on day one, inspect or import them before hiring.
-
-```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
-```
-
-6. Draft the hire payload.
-
-Required thinking:
-
-- role / title / optional `name`
-- `name` is optional; if omitted, Rudder assigns a distinct personal name automatically
-- omit `icon` for normal hires; Rudder assigns a DiceBear Notionists avatar automatically
-- only set `icon` when preserving an explicit DiceBear avatar reference or an uploaded `asset:<uuid>` image avatar reference provided by the board/UI
-- reporting line (`reportsTo`)
-- adapter type
-- optional `desiredSkills` from the organization skill library
-- adapter and runtime config aligned to this environment
-- capabilities
-- structured role/persona instructions for the new agent (`promptTemplate` when the CLI payload is the available surface; Rudder materializes this as `SOUL.md`)
-- source issue linkage (`sourceIssueId` or `sourceIssueIds`) when this hire came from an issue
-
-`role` is a fixed Rudder enum, not a free-form job title. Use one of:
-`ceo`, `cto`, `cmo`, `cfo`, `engineer`, `designer`, `pm`, `qa`, `devops`, `researcher`, `general`.
-Put specialization in `title`, `capabilities`, and `promptTemplate`. For example, a Founding Engineer hire should use
-`"role": "engineer"` and `"title": "Founding Engineer"`, not `"role": "founding_engineer"`.
-
-Do not copy Rudder's shared filesystem, memory, language, or safety contract into the hire prompt. Rudder injects that operating contract from runtime code for supported local runtimes. The hire-specific prompt should only define the new agent's role, identity, scope, tone, and durable responsibilities.
-
-Draft `promptTemplate` as a durable SOUL document, not a one-line command. Use these sections when the role is not trivial:
-
-- Opening: one sentence that captures who the agent is
-- Mission: the outcome this agent owns
-- Responsibilities: durable duties and ownership boundaries
-- Boundaries: what the agent should not do or should escalate
-- Decision Principles: role-specific judgment rules
-- Voice: how the agent should communicate
-- Continuity: what should become memory or explicit instruction updates over time
-
-7. Submit the canonical hire request.
-
-```sh
-rudder agent hire --org-id "$RUDDER_ORG_ID" --payload '{
-  "role": "cto",
-  "title": "Chief Technology Officer",
-  "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",
-    "promptTemplate": "# SOUL.md -- CTO Persona\n\nYou are the CTO.\n\n## Mission\nOwn technical strategy, architecture, engineering execution, and quality bars.\n\n## Responsibilities\n- Set technical direction and execution standards.\n- Review architecture and staffing trade-offs.\n- Keep delivery risks visible and actionable.\n\n## Boundaries\n- Do not approve risky shortcuts without naming the trade-off.\n- Escalate product or budget ambiguity instead of guessing.\n\n## Decision Principles\n- Prefer simple architectures with explicit trade-offs.\n- Treat reliability, developer velocity, and product learning as linked constraints.\n\n## Voice\nDirect, specific, and evidence-led.\n\n## Continuity\nPreserve durable technical standards, repeated failure patterns, and long-running architecture decisions in memory or explicit instructions."
-  },
-  "runtimeConfig": {"heartbeat": {"enabled": true, "intervalSec": 300, "wakeOnDemand": true, "maxConcurrentRuns": 3}},
-  "sourceIssueId": "<issue-id>"
-}' --json
-```
-
-`agent hire` is the canonical surface because it preserves the real server behavior:
-
-- if the organization does not require approval, it creates the agent directly and returns `"approval": null`
-- if the organization requires approval, it creates the agent in `pending_approval` and returns both `agent` and `approval`
-
-Do **not** substitute `rudder approval create --type hire_agent` for this step unless you are doing low-level debugging. That bypasses the canonical direct-create vs pending-approval behavior.
-
-8. Handle governance state.
-
-If the hire response includes `approval`, monitor and discuss on the approval thread:
-
-```sh
-rudder approval get "<approval-id>" --json
-cat > /tmp/rudder-approval-comment.md <<'EOF'
-## CTO hire request submitted
-
-- Approval: [<approval-id>](/<prefix>/messenger/approvals/<approval-id>)
-- Pending agent: [<agent-ref>](/<prefix>/agents/<agent-url-key-or-id>)
-- Source issue: [<issue-ref>](/<prefix>/issues/<issue-identifier-or-id>)
-
-Updated prompt and adapter config per board feedback.
-EOF
-rudder approval comment "<approval-id>" --body-file /tmp/rudder-approval-comment.md --json
-rudder approval resubmit "<approval-id>" --payload '{"title":"Revised title","agentRuntimeConfig":{"cwd":"/abs/path/to/repo","model":"o4-mini"}}' --json
-rudder approval issues "<approval-id>" --json
-```
-
-When the board approves, you may be woken with `RUDDER_APPROVAL_ID`:
-
-```sh
-rudder approval get "$RUDDER_APPROVAL_ID" --json
-rudder approval issues "$RUDDER_APPROVAL_ID" --json
-```
-
-For each linked issue, either:
-
-- close it if the approval resolved the request, or
-- comment in markdown with links to the approval and next actions
-
-## Quality Bar
-
-Before sending a hire request:
-
-- if the role needs skills, make sure they already exist in the org library or import them first using the Rudder org-skills workflow
-- reuse proven config patterns from related agents where possible
-- omit `icon` for normal hires so the server generates the default DiceBear Notionists avatar
-- avoid secrets in plain text unless required by adapter behavior
-- ensure the reporting line is correct and in-org
-- ensure the prompt is role-specific, operationally scoped, and structured enough to become the agent's durable `SOUL.md`
-- include mission, responsibilities, boundaries, decision principles, voice, and continuity when the role has ongoing authority
-- prefer `sourceIssueId` or `sourceIssueIds` in the hire payload instead of manual approval linking
-- if board requests revision, update the payload and resubmit through the approval flow
-- do not report success unless `rudder agent hire` itself succeeded and you can cite the returned `agent.id` or `approval.id`
-- creating local directories or instruction files is not evidence that an agent exists in Rudder
-
-For canonical command syntax and examples, read:
-`references/cli-reference.md`
-
-For low-level route shapes and underlying compatibility endpoints, read:
-`references/api-reference.md`