feat(console): inject prompts, MCP, tools, and credentials into a running session

[duyet]

Implements a first slice of #346 (part of #347): operators can intervene in a live session without mutating the agent record or restarting.

What this slice does

• Inspector Inject tab (between Sandbox and Artifacts/Files) with four independent sections: system-prompt append, MCP mount, tool toggles, host→credential bind.
• Canonical write: POST /v1/sessions/:id/injections with one command. PATCH /v1/sessions/:id/tools is a thin alias (enabled/disabled or enabled_tools/disabled_tools).
• Read: GET /v1/sessions/:id/injections returns the overlay (never tokens).
• Prompt appends and tool overrides apply on the next turn. MCP mounts and credential binds apply on the next proxy/outbound call.
• session.config_updated is an audit event (prompt body omitted; credential detail is host + credential_id only). Crash recovery does not replay it.

Design deviation from the issue (intentional)

The issue asked for injections that are not persisted (ephemeral to the running SessionDO). This slice stores the overlay on the session row at metadata._oma_injections so:

1. Main-worker MCP/outbound resolvers can see it without a DO round-trip.
2. It survives DO hibernation.
3. GET /v1/sessions still strips the key so caller metadata stays caller-owned.

It remains session-scoped (not copied onto the agent). Creating a new session of the same agent does not inherit the overlay. Clients cannot clobber it via session create/update metadata.

Credentials

• Overlay, events, GET bodies, and the Console tab never carry tokens.
• Injected credential_id must already belong to the session’s vault_ids (422 otherwise).
• Outbound resolver: overlay host map wins, then only within session vaults.

Out of scope (this PR)

• Tablet/mobile bottom-sheet (desktop right-rail only).
• Node oma-vault sidecar overlay (CF outbound + Node MCP proxy are covered).
• CLI rewrite, chore: release main #358, chore: version packages #400.
• Environment/package injection, env-var credential injection, undo stack.

Rebase

Rebased onto latest main to clear conflicts with:

• #447 (output_file / Artifacts tab) — Inspector now has both Inject and Artifacts.
• #445 (session secret store) — kept SessionSecretService import alongside injection overlay types.
• #446 (Analytics dashboard) — verify-oma keeps both console-analytics and console-inject.
• #449 / #450 / #453 — kept overlay helpers on SessionDO next to the AnyRouter import.

Verification

• pnpm typecheck — pass (post-rebase)
• Overlay + route + outbound: 36 passed (route tests 13/13 after fix(sessions): persist env_secret values to the session secret store #445)
• InjectPanel + Artifacts inspector tests — 5 passed
• verify-oma drive console-inject: inject-gate pass (signed-out /sessions/sess_fake → /login). Inject tab/sections skipped — no invented auth secrets. Panel behavior is covered by component tests.

  

Summary by Sourcery

Enable operators to inject prompts, MCP servers, tool overrides, and vault credential bindings into running sessions through a session-scoped overlay.

New Features:

• Add a Console session Inspector Inject tab for appending system prompts, mounting MCP servers, toggling tools, and binding vault credentials on live sessions.
• Add session injection APIs, including overlay reads, canonical command writes, and a tool-toggle PATCH alias.
• Apply session-scoped prompt, MCP, tool, and credential overlays across Cloudflare and Node runtimes without mutating agent records or restarting sessions.

Bug Fixes:

• Prevent session metadata updates and public session responses from exposing or overwriting the internal injection overlay.
• Ensure injected credentials are restricted to the session’s vaults and that tokens are excluded from overlays, audit events, API responses, and the Console.

Enhancements:

• Record operator injection changes as non-replayed session.config_updated audit events and display them in the session event stream.
• Make injected MCP mounts and outbound credential bindings take effect on subsequent proxy calls while prompt and tool changes apply on the next turn.

CI:

• Extend verify-oma with authenticated-route coverage and feature documentation for the Console Inject tab.

Documentation:

• Document runtime injection APIs and the session-scoped credential and MCP behavior in project and API documentation.

Tests:

• Add API-type, session-route, Console component, MCP proxy, and outbound credential tests covering injection behavior and secret redaction.

[sourcery-ai]

Sorry @duyet, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 4 days and 23 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Team

Run ID: 8acb2e45-8a1d-4e3a-bd68-ae66b61a75fd

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sourcery-ai]

Reviewer's Guide

This slice adds session-scoped operator injections through a metadata-backed overlay and typed API commands, projects them into the next runtime turn or live MCP/outbound resolution without mutating agent records, exposes safe controls in the Console Inspector, emits audit-only events, and includes API, integration, UI, and verification coverage.

Sequence diagram for session injection and runtime application

sequenceDiagram
    actor Operator
    participant Console as Console InjectPanel
    participant API as Session API
    participant Session as Session row
    participant Runtime as Session runtime
    participant Proxy as MCP or outbound proxy

    Operator->>Console: Select injection action
    Console->>API: POST /v1/sessions/:id/injections
    API->>API: injectionCommandSchema.parse()
    API->>Session: applyInjectionCommand()
    API->>Session: Update metadata._oma_injections
    API->>Runtime: recordConfigUpdated()
    API-->>Console: SessionInjectionOverlay

    alt Prompt or tools injection
        Runtime->>Session: overlayFromMetadata()
        Runtime->>Runtime: applyOverlayToAgent()
        Runtime->>Runtime: injectionReminders()
        Runtime-->>Runtime: Apply on next turn
    else MCP or credential injection
        Proxy->>Session: Read overlay on outbound call
        Proxy->>Proxy: pickMcpServer() or credentialIdForHost()
        Proxy-->>Proxy: Apply immediately
    end

Loading

File-Level Changes

Change	Details	Files
Added a canonical session-injection overlay model and command reducer with safe parsing, normalization, limits, agent projection, and audit-event generation.	Defined prompt, MCP, tool, and credential injection schemas. Stored and parsed overlays under session metadata while stripping them from public metadata. Added overlay merge, next-turn reminder, tool override, MCP precedence, and host credential helpers. Added coverage for validation, reducer behavior, metadata isolation, and secret-free events.	packages/api-types/src/session-injections.ts packages/api-types/src/session-injections.test.ts packages/api-types/src/index.ts packages/api-types/src/types.ts
Exposed authenticated session injection APIs with a canonical POST command endpoint and tool-toggle PATCH alias.	Added GET and POST injection routes with session lookup, overlay updates, and 422 vault-membership checks. Added PATCH /tools support for both enabled/disabled payload naming conventions. Persisted overlays without allowing normal session metadata writes to clobber them. Recorded observational session.config_updated events through both Cloudflare and Node routers.	packages/http-routes/src/sessions/index.ts packages/http-routes/src/sessions/injections.test.ts packages/session-runtime/src/router.ts apps/main/src/lib/cf-session-router.ts apps/main-node/src/lib/node-session-router.ts apps/agent/src/runtime/session-do.ts
Applied session overlays to runtime agent configuration and live outbound integrations.	Applied prompt appends and tool overrides when preparing the next agent turn. Merged injected MCP servers into runtime configuration with overlay precedence. Made Cloudflare and Node MCP proxies re-read overlays for immediate mounts and credential pins. Made outbound host credential resolution prefer valid overlay bindings within session vaults.	apps/agent/src/runtime/session-do.ts apps/main-node/src/index.ts apps/main-node/src/mcp-proxy.ts apps/main/src/routes/mcp-proxy.ts apps/main-node/test/mcp-proxy.test.ts test/unit/cap-cli-outbound.test.ts
Added the Console Inspector Inject tab for live operator controls and secret-safe overlay display.	Added independent prompt, MCP, tool, and credential sections with one-command writes. Loaded credentials by display name and ID while excluding tokens from rendered content. Rendered config-updated audit events in the session timeline. Added component coverage for prompt POSTs, tool PATCHes, and token non-disclosure.	apps/console/src/pages/session-detail/InjectPanel.tsx apps/console/src/pages/session-detail/InjectPanel.test.tsx apps/console/src/pages/session-detail/Inspector.tsx apps/console/src/pages/SessionDetail.tsx
Documented the runtime-injection API, security behavior, and browser verification path.	Documented endpoints, timing semantics, session scope, and credential constraints. Added the console-inject verification feature and auth-gated browser drive. Updated MCP and vault documentation with overlay precedence and token-handling guarantees.	AGENTS.md docs/api-reference.md docs/mcp-servers.md docs/vaults-and-credentials.md .cursor/skills/verify-oma/SKILL.md .cursor/skills/verify-oma/control-oma.mjs .cursor/skills/verify-oma/features/README.md .cursor/skills/verify-oma/features/console-inject.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.