feat(server,web,mobile): let plugins add context to the turns you send

[saphid]

Stacked on #16062 (and #15010). Review only the top commit: 98939ce.

Rebased 2026-10-10 onto #15010's current head (1fe8efd69a, on main 57b3780). Run context enrichment and its tests import the ID allocator, notification and provider failure helpers from @t3tools/provider-core, where main moved them, and type the allocator as IdAllocatorV2["Service"]. The thread stream and work-log presentation tests keep main's new compact-snapshot and live-thought cases beside the plugin context cases. On mobile, the expanded-row helper no longer splits the doc comment of formatItemFullDetail. Main moved the host process references into a HostProcess module (#17641), so the context enrichment test provides the process arguments through HostProcess.Arguments. Main now shows a T3 Code notice's own detail when a mobile activity row is expanded (#17723). The mobile expanded-row helper keeps that case beside the plugin context case: file reads first, then notices, then plugin context, then the generic detail. GPT-6.1 Sol (high) reviewed this port: SHIP. Captures below were taken at the revisions they name. At this head (98939ce7e9) these pass: focused tests (34 files, 716 tests), typecheck (@t3tools/mobile, t3, @t3tools/web, @t3tools/client-runtime, @t3tools/contracts), lint and fmt on the changed files, knip, lint:mobile.

iOS: this PR's mobile surfaces were also captured on an iPhone 17 Pro simulator (iOS 26.5), at the top-of-stack head 5ec8b17, which contains this PR: light-context-expanded. These are after-only captures; the before/after comparison below is on Android.

Problem

A plugin cannot give the agent context. Teams keep conventions, codenames, ticket notes and runbooks in places the agent cannot see, and the only way to supply them today is to paste them into every message. Plugins can already react to finished runs, offer tools and show statuses, but none of that reaches the prompt of the turn the user is sending.

Why this qualifies

This is the proposal route in CONTRIBUTING, and no maintainer has agreed to it yet. It needs two approvals:

• The OV2 owner must approve how enrichment is recorded in orchestration: the plugin_context dynamic_tool item convention (including one overflow record keyed plugins), recording before any plugin code runs under the thread's command lock, the wire projection keeping those items' output, the interrupt closing a running record, and the rule that only turns the history pager counts are enriched. Nothing in the pager, wire schema or history selection changes.
• The plugin-system approval on #6837, like the plugin PRs below it.

It stacks on the plugin notifications PR for ordering, and depends on the plugin host and event delivery PRs lower in the stack (the reserved t3.* handler names and PluginCatalog.invoke). If the answer is no, we close it; nothing above it in the stack depends on it except the approvals PR, which touches the same plugin child guard. Previous PR in this stack: feat(server,web,mobile): let plugins send notifications (#16062).

Fix

• Author side (pluginTransforms.ts): capability transforms; manifest transforms: { enrich: { timeoutSeconds? } } (1–10 s, default 5), which needs the capability and "proposedApi": true or the plugin is refused at add. The plugin registers t3.transform.enrich, the one host-called name besides t3.tool.*; it receives { environmentId, projectId, threadId, runId, cwd, message: { text ≤ 16,000, truncated } } and answers { context: [{ title ≤ 100, text ≤ 6,000 }] } (≤ 4 entries, ≤ 8 KiB) or null.
• When: in the provider-turn start effect, after the run is confirmed starting and before the provider session opens. Only for turns the history pager counts (isThreadHistoryUserTurn, the pager's own predicate, imported), minus / commands: steering (including steering that restarts a run), notifications and every agent/server wake are never enriched.
• Recording: one guarded batch commits a running record per called plugin before any plugin code runs, under the thread's command lock (so Stop either sees and closes the records, or commits first and nothing is recorded or called); plugin calls run concurrently outside the lock; a second guarded batch saves each outcome before the provider starts. At most 4 plugins are called, in catalogue order; one more record says how many were not. At most 8 KiB of context is kept per run. A retried or replayed start reuses saved records and never calls a plugin twice.
• Fail open: deadline, error, crash, oversize, malformed answer, disable mid-call or past the run's budget → a failed record with a reason (≤ 300 chars); the turn goes on without it.
• Provider text: <plugin-context plugin="id" title="…">…</plugin-context> blocks ahead of the typed text, composed once in ProviderTurnStartService. The saved user message is unchanged.
• Clients: the records are existing dynamic_tool items, so every client already decodes them. A shared pluginContextInspection (client-runtime) drives the web/desktop inspector and the mobile expanded detail: "From <plugin (id)>" and the context, or "Not added" and the reason, instead of the input JSON. The plugin details capability list now explains transforms: it reads your messages and can add context to them before they reach the agent (before this PR the server refused the capability, so the list showed it by name only).
• Docs: docs/user/plugins.md gains a "Context" section. No internals doc.

Size: 35 files, +2744 / −67; 1,878 of the added lines are tests and fixtures.

Evidence

Environment: macOS arm64; this PR on top of the plugin notifications PR.

How to exercise it: isolated vp run dev; add the test fixture plugin (apps/server/src/plugins/testFixtures/contextPlugin, copied to a temp directory), approve and enable it; on a Claude thread send What is the project codename? Reply with only the codename.

Environment for the captures: isolated vp run dev with fresh state at the parent and at this PR (an earlier revision with an identical patch); the environment is labelled "Proof server". Web in headless Chromium; the built desktop app (vp run build:desktop, isolated profile) rendering the same threads; the Android app on an emulator; one vp run dev --share pass from a fresh browser over the non-loopback HTTPS origin. Turns used Claude Opus 5.5. The plugin is the layer's context test fixture, with its deadline raised to 10 s so Stop can be pressed by hand; for the overflow case, five copies with distinct ids.

Observed

	Before (parent)	After (this PR)
Add the plugin	"this server does not support transforms."	review explains transforms
"What is the project codename?"	no row; the agent finds no codename	"Added context from Context fixture" → "From Context fixture (test.context)", the context, reply PERIWINKLE-42; the bubble keeps the typed text

After	light	dark
[fail]: not added, with the reason; the reply still arrives
[wait] + Stop: "The run was interrupted before the plugin answered.", no spinner
Five plugins: four rows + "Context from 1 more plugin not added" ("At most 4 plugins add context to one run; 1 more was not called.")
Desktop (built app)
Android

• Disable → the next turn has no row and the agent cannot find the codename; re-enable → the row returns: video,
• Videos: send → row → expand → reply, wait + Stop, desktop, Android, before.
• Remote (--share): the enriched row renders and expands, and disable/re-enable behaves the same over the remote origin: video
• The prompt Claude received (read from its session transcript) begins with <plugin-context plugin="test.context" title="Project codename">The project codename is PERIWINKLE-42.</plugin-context> followed by the typed text.

Checks at this head (6bc32c0b3d), re-run 2026-10-05 (CI=true vp test run …, all exit 0):

• server: src/plugins plus RunContextEnrichment, ProviderTurnStartService, runtimeLayer, WireProjection, ThreadStream: 26 files, 368 tests pass. They cover record-before-call and reuse on every retry with zero re-invocations; a cut-off call recorded as not added; fail-open mixes; the cap with 1,000 eligible plugins (records and batches constant); the run budget in UTF-8 bytes; Stop holding the real thread lock between read and commit (no records, no call); stale runs writing nothing; eligibility equal to the pager predicate for every intent × actor; steering restarts and wakes not enriched; context sent verbatim to the provider and reused on a session-open retry; the real orchestrator closing a running record on interrupt; the wire keeping these items' output; the snapshot staying well inside its byte budget with maximal answers. With real plugin processes: eligibility (consent, capability-only, disabled), manifest refusals, the input the plugin sees, fail-open answers, the declared deadline (TestClock), disable mid-call, a stale generation refused, five enabled plugins → four answers in catalogue order plus one overflow record and exactly four blocks in the provider text, and disable → no record and plain provider text → re-enable → enriched again at the new generation.
• contracts pluginTransforms, plugin, pluginCatalog (18); client-runtime work-log/presentation, state/pluginContributions (105); web MessagesTimeline.test.tsx (74; mounted timeline, row clicked, inspector text read: context and reason shown, input not shown); mobile threadActivity.test.ts (79; expanded detail for completed, failed and interrupted records).
• Recorded on an earlier revision with an identical patch: on the parent, the new server and contracts suites do not load (new modules); the wire, interrupt, inspector (web, mobile, client-runtime) tests fail on their assertions. Mutations: removing the 4-plugin cap fails the overflow test; ignoring the enabled state fails the disable/re-enable test.
• vp run --filter typecheck for contracts, t3, client-runtime, web and mobile; vp lint --report-unused-disable-directives and vp fmt --check on the touched files (26 warnings, all on unchanged lines, the same 26 at the parent); vp run knip:check; vp run lint:mobile; web build; vp run build:desktop; node scripts/release-smoke.ts. All pass.

Surfaces

• Entry points: the turn the user sends (composer, queued turn). Steering, / commands and server-started turns are deliberately not enriched. The way out is disabling or removing the plugin in Settings > Plugins; it takes effect from the next turn.
• Clients: web and desktop (V2ItemInspector and the timeline's fallback body), mobile (expanded row detail and copy text, iOS and Android). All clients already render the rows as integration tool rows.
• Providers: the start service composes the text once; every adapter reads it. Claude: receives the blocks (live-proved during development); its adapter-buffered wakes are not enriched. Codex: receives them on turn/start; background-command wakes and native restart resumes are not enriched. Cursor: receives them; no continuations. Grok (ACP): receives them; post-settle continuations send no prompt and are not enriched. OpenCode (v1 and 2): receives them; OpenCode 2 continuation wakes are not enriched. Antigravity: receives them; no continuations. Pi: receives them through its prompt payload; no continuations. Only Claude was run live; the others are by code reading plus the server-side gate tests.
• Contracts: additive: one schema module, one optional manifest field, one forward-compatible catalogue field. Old client + new server: rows render as generic tool rows (no context shown). New client + old server: no rows; a plugin declaring transforms is refused at add.
• Reverse states: disable/remove stops enrichment from the next turn and fails an in-flight call; re-enable resumes it under a new generation; Stop closes a running record.
• Connection modes: server-side; records travel inside the existing snapshot and stream budget, unchanged across local, remote/relay and tunnel.
• Docs: new "Context" section in docs/user/plugins.md.

Not verified

• iOS was not run. The remote pass used --share; relay/T3 Connect was not exercised. Android was captured after the change only: before this PR no plugin can declare transforms, so there is no row to show.
• The desktop captures render the threads from the isolated dev server added as an environment in the built app; the built app's own bundled server ran no provider turn (it had no provider login in the isolated profile).
• Live provider proof: Claude only (the captures above). The other six providers are by code reading plus the server-side gate tests.
• A slow plugin delays the turn: enrichment runs before the provider session opens, bounded by the 10 s plugin deadline.
• Plugin context text is not escaped inside its block (plugins are consented, trusted code); a plugin could close the tag.
• Context is not replayed into a context handoff after a provider switch. The overflow record counts plugins not called but does not name them.

Claude Opus 5.5 (build), GPT-6.1 Sol (review) and GPT-6 Astra (captures) via T3 Code
🤖 Generated with Claude Code

[macroscopeapp]

Macroscope has since reviewed this pull request. An earlier review was skipped by a cost limit; a review has now completed, so that notice no longer applies.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This is a large, cross-cutting plugin platform that adds production child processes, persistence, RPC/MCP surfaces, client workflows, and plugin-controlled context before provider turns. It also enables new capability defaults and broadens a static-analysis exception, so the change requires human review.

^{You can add or adjust custom eligibility rules. Learn more.}

[saphid]

Review requested

Date (UTC)	Reviewer	Where
2026-10-06	Julius	Discord DM

_{Logged so this PR shows when a maintainer was asked to review it.}