opencode-swarm 7.192.4 → 7.194.0

package/dist/host/v2/session-client.d.ts

@@ -0,0 +1,77 @@
+/**
+ * v2 session client shim — issue #3169 Phase 2.
+ *
+ * A narrow `OpencodeClient` subset implementing exactly the v1 session surface
+ * Epic's dispatch paths use (`session.create/prompt/abort/delete` plus `get`,
+ * which verified teardown requires), backed by the v2 host's `ctx.session`
+ * domain. Installed as the synthetic v1 PluginInput's `client` field by
+ * `setup.ts`, it flows through the shared init core's single client write site
+ * into `swarmState.opencodeClient` and every init-path `ctx.client` consumer —
+ * the tracking issue's Decision 2 (a client subset instead of v2 branches
+ * spread through consumers).
+ *
+ * Translation contract (per the issue §4 gap table and the Phase 0 live
+ * findings on @opencode/cli 2.0.26):
+ *
+ *   - `create({body:{parentID,title}, query:{directory}})` validates placement
+ *     BEFORE creating anything: v2 child sessions inherit the parent's
+ *     directory and ignore the requested one (Phase 0 C1 catch), so a divergent
+ *     or unverifiable placement fails closed with a typed `{data: null,
+ *     error}` result — routing worktree isolation to its existing degradation
+ *     path instead of silently running a "lane" session in the project root.
+ *     A passing precheck mints a placeholder id; the real v2 session is
+ *     created at PROMPT time, when the v1 prompt body supplies the create-time
+ *     options (agent/model/permissions) the published `SessionCreateInput`
+ *     expects (issue R2: one session per dispatch contains the per-session
+ *     shift).
+ *   - `prompt({path:{id}, body:{agent,model?,system?,tools,parts}, signal?})`
+ *     emulates the v1 BLOCKING call: real create (carrying agent/model and the
+ *     read-only denial map as `effect:'deny'` permissions) → one sessionID-
+ *     scoped `context` hook that replaces `event.system` (fence-aware: parts
+ *     carrying the `<swarm_system_directive` provenance fence survive, per
+ *     #2526) and deletes denied keys from `event.tools` → `prompt` → bounded
+ *     `wait` → `context()` translated into the v1 `{data:{info,parts}}`
+ *     envelope so `dispatchEphemeralAgent` and `readProviderMessageError`
+ *     work unchanged. A prompt addressed to a non-placeholder (real) session
+ *     id takes a direct path without re-creating — the pr-event-delivery wake
+ *     prompt shape.
+ *   - Provider failures are EVENT-SOURCED on v2 (Phase 0 C4: no error text in
+ *     `context()`), so the event pump records `session.error` /
+ *     `session.execution.failed` payloads here (`recordV2SessionErrorFromEnvelope`,
+ *     called pump-side beside `seedSessionIdentityFromEnvelope`) and the
+ *     translation surfaces them as the v1 `info.error` shape. A failed outcome
+ *     without recorded detail yields a bounded `provider.unknown` error
+ *     instead of a silent empty success.
+ *   - `abort` maps to `interrupt`, `delete` to `remove`, `get` to the v2 get
+ *     (unresolved placeholders read as `{data: null}` — never prompted means
+ *     gone, satisfying `teardownEphemeralSessionVerified`).
+ *
+ * Deferred-work marker: NONE. The unverified live-host behaviors this design
+ * rests on are recorded as deferrals in the trace (context-hook firing for
+ * plugin-created sessions, permission vocabulary honor, `context()` entry
+ * shapes, `wait` on failed prompts, `get(parent).location` availability) with
+ * the owning follow-up on #3169.
+ *
+ * C6 await convention: every `await` lives inside a `deferredV2Session*`
+ * function declaration or `const deferredV2SessionX = async (` binding — the
+ * dual-shape-parity scan's function tracker does not recognize object-literal
+ * method properties, so the client object's methods never await directly.
+ */
+import type { OpencodeClient } from '@opencode-ai/sdk';
+import type { V2EventEnvelope, V2PluginContext, V2SessionPermission } from './types';
+/**
+ * Record a `session.error` / `session.execution.failed` envelope's error
+ * payload for the shim's result translation. SYNC by contract — the event pump
+ * calls it inline in its iteration loop. Accepts the same dual payload dialect
+ * `mapV2EventToV1` accepts (live `data`, SDK `properties`).
+ */
+export declare function recordV2SessionErrorFromEnvelope(envelope: V2EventEnvelope): void;
+/** Drop all shim-held state (v2 cleanup path; bounded residue documented in the trace). */
+export declare function clearV2SessionClientState(): void;
+/**
+ * Map a v1 read-only denial map onto v2 create-time permission entries.
+ * Fail-closed shape: only `effect: 'deny'` entries are ever produced.
+ */
+export declare function readOnlyToolsToV2Permissions(tools: Readonly<Record<string, false>> | undefined): V2SessionPermission[];
+/** Feature-detect the full surface the shim requires (types.ts host-tolerance contract). */
+export declare function createV2SessionClient(ctx: V2PluginContext): OpencodeClient | undefined;

package/dist/host/v2/types.d.ts

@@ -1,17 +1,31 @@
 /**
  * Vendored structural types for the OpenCode 2 plugin API.
  *
- * Provenance: distilled from `@opencode/plugin@2.0.20`
- * `dist/promise/{plugin,registration,tool,session,command,agent,event,storage,app,options}.d.ts`
- * and `@opencode/schema@2.0.20` `dist/{tool,agent,location}.d.ts`,
- * `@opencode/ai` `dist/schema/messages.d.ts` (fetched 2026-09-30, issue #3004).
+ * Provenance: distilled from `@opencode/plugin@2.0.26`
+ * `dist/promise/{plugin,registration,tool,session,worktree,command,agent,event,storage,app,options}.d.ts`
+ * and `@opencode/schema@2.0.26` `dist/{tool,agent,location}.d.ts`,
+ * `@opencode/client@2.0.26` `dist/promise/generated/{client,types}.d.ts`,
+ * `@opencode/ai` `dist/schema/messages.d.ts` (fetched 2026-10-09, issues #3004 / #3169).
  * Structural only — deliberately no runtime dependency on `@opencode/plugin`.
  *
- * Drift guard: DEFERRED to the #2910 follow-up PR (a check-host-contract v2 digest leg over this corpus, plus the dual-host CI lane); until it lands, type truth rests on this provenance pin and the live-host smoke. See docs/host/v2-hook-inventory.md for the full v1-to-v2 map.
+ * Flattening note: the client's Effect-generated input types express optional fields as
+ * `{ field: Body["field"] }` records; they are vendored here as plain optional fields of the
+ * same types (e.g. `SessionCreateInput` is all-optional in the published form).
+ *
+ * Drift guard: DEFERRED to the #2910 follow-up PR (a check-host-contract v2 digest leg over this corpus, plus the dual-host CI lane); until it lands, type truth rests on this provenance pin (now 2.0.26) and the live-host smoke. See docs/host/v2-hook-inventory.md for the full v1-to-v2 map.
+ *
+ * Host-tolerance contract for the session/worktree method surface (issue #3169):
+ * the members below are REQUIRED to mirror the published `SessionDomain`/`WorktreeDomain`.
+ * Since Phase 2 the session-client shim (`src/host/v2/session-client.ts`) is the call
+ * site — it feature-detects every member it consumes, including `hook` (`typeof
+ * ctx.session.create === 'function'`), and returns `undefined` when any is missing, so
+ * requiredness stays type-level only and a 2.0.2x host lacking a member must never crash
+ * the adapter.
  *
  * Only the surfaces this adapter consumes are typed. Unknown fields are
  * intentionally left off; the adapter never relies on their absence.
- * Upstream: @opencode/plugin@2.0.20 and @opencode/schema@2.0.20 (MIT, sst/opencode).
+ * Upstream: @opencode/plugin@2.0.26, @opencode/schema@2.0.26 and
+ * @opencode/client@2.0.26 (MIT, sst/opencode).
  */
 /** v2 `App` — host identity (dist/app.d.ts). */
 export interface V2App {
@@ -157,15 +171,244 @@ export interface V2SessionPromptEvent {
     };
     readonly delivery?: string;
 }
-/** v2 `SessionDomain` (only hook used by this adapter). */
+/**
+ * v2 session-call input types (`@opencode/client@2.0.26` generated types, flattened —
+ * see the module header's flattening note). Only the fields with published evidence
+ * are named; the index signature keeps them structural, not exhaustive.
+ */
+/** `Model.Ref` (schema/model.d.ts). */
+export interface V2ModelRef {
+    readonly id: string;
+    readonly providerID: string;
+    readonly variant?: string;
+}
+/** Session permission rule (schema/permission.d.ts shape on create/switch inputs). */
+export interface V2SessionPermission {
+    readonly action: string;
+    readonly resource: string;
+    readonly effect: 'allow' | 'deny' | 'ask';
+}
+/** `SessionCreateInput` — all-optional in the published (Effect-generated) form. */
+export interface V2SessionCreateInput {
+    readonly id?: string | null;
+    readonly parentID?: string | null;
+    readonly title?: string | null;
+    readonly agent?: string | null;
+    readonly model?: V2ModelRef | null;
+    readonly location?: {
+        readonly directory: string;
+    } | null;
+    readonly metadata?: Readonly<Record<string, unknown>> | null;
+    readonly permissions?: ReadonlyArray<V2SessionPermission> | null;
+}
+/**
+ * `SessionPromptInput` (`@opencode/client@2.0.26` generated, flattened):
+ * `sessionID` and `text` are required; `command`/`args` are NOT members of
+ * this input (the command shape is `name` + `text` on `SessionCommandInput` —
+ * the earlier fabricated members were removed in the PR-review feedback pass).
+ * Attachment members are abbreviated structural shapes.
+ */
+export interface V2SessionPromptCallInput {
+    readonly sessionID: string;
+    readonly text: string;
+    readonly id?: string | null;
+    readonly files?: ReadonlyArray<{
+        readonly uri: string;
+        readonly name?: string;
+        readonly description?: string;
+    }>;
+    readonly agents?: ReadonlyArray<{
+        readonly name: string;
+    }>;
+    readonly skills?: ReadonlyArray<{
+        readonly id: string;
+    }>;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly delivery?: 'steer' | 'queue' | null;
+    readonly resume?: boolean | null;
+    [key: string]: unknown;
+}
+/** `SessionSwitchAgentInput`. */
+export interface V2SessionSwitchAgentInput {
+    readonly sessionID: string;
+    readonly agent: string;
+}
+/** `SessionSwitchModelInput`. */
+export interface V2SessionSwitchModelInput {
+    readonly sessionID: string;
+    readonly model: V2ModelRef;
+}
+/** `SessionInterruptInput`. */
+export interface V2SessionInterruptInput {
+    readonly sessionID: string;
+    readonly resume?: boolean;
+}
+/** `SessionInfo` — fields with published evidence; structural, not exhaustive. */
+export interface V2SessionInfo {
+    readonly id: string;
+    readonly parentID?: string;
+    readonly projectID: string;
+    readonly agent?: string;
+    readonly model?: V2ModelRef;
+    readonly title?: string;
+    readonly location: {
+        readonly directory: string;
+        [key: string]: unknown;
+    };
+    readonly time?: {
+        readonly created: number;
+        readonly updated: number;
+        readonly idle?: number;
+    };
+    readonly outcome?: 'succeeded' | 'failed' | 'interrupted';
+    [key: string]: unknown;
+}
+/** `SessionMessageInfo` union member (abbreviated; consumers read type + text). */
+export interface V2SessionMessageInfo {
+    readonly type?: string;
+    [key: string]: unknown;
+}
+/**
+ * v2 `SessionDomain` (dist/promise/session.d.ts 2.0.26): `Pick<SessionApi, "create" | "get" |
+ * "remove" | "switchAgent" | "switchModel" | "prompt" | "generate" | "command" | "compact" |
+ * "synthetic" | "interrupt" | "update" | "move" | "wait" | "context"> & { hook }`.
+ *
+ * `hook` names stay the 2.0.20-era three this adapter registers (context/compaction/prompt;
+ * the published SessionHooks map has grown, but the adapter only registers these).
+ */
 export interface V2SessionDomain {
     readonly hook: (name: 'context' | 'compaction' | 'prompt', callback: (event: never) => Promise<void> | void) => Promise<V2Registration>;
-    readonly prompt?: (sessionID: string, input: {
+    readonly create: (input?: V2SessionCreateInput) => Promise<V2SessionInfo>;
+    readonly get: (input: {
+        readonly sessionID: string;
+    }) => Promise<V2SessionInfo>;
+    readonly remove: (input: {
+        readonly sessionID: string;
+    }) => Promise<void>;
+    readonly switchAgent: (input: V2SessionSwitchAgentInput) => Promise<void>;
+    readonly switchModel: (input: V2SessionSwitchModelInput) => Promise<void>;
+    /** Asynchronous: returns an inbox entry; pair with `wait` (issue #3169 Phase 2). */
+    readonly prompt: (input: V2SessionPromptCallInput) => Promise<unknown>;
+    readonly generate: (input: {
+        readonly sessionID: string;
+        [key: string]: unknown;
+    }) => Promise<{
         text: string;
-    } | {
-        command: string;
-        args?: string;
+    }>;
+    readonly command: (input: {
+        readonly sessionID: string;
+        [key: string]: unknown;
+    }) => Promise<void>;
+    readonly compact: (input: {
+        readonly sessionID: string;
+        [key: string]: unknown;
+    }) => Promise<unknown>;
+    readonly synthetic: (input: {
+        readonly sessionID: string;
+        [key: string]: unknown;
     }) => Promise<unknown>;
+    readonly interrupt: (input: V2SessionInterruptInput) => Promise<unknown>;
+    readonly update: (input: {
+        readonly sessionID: string;
+        [key: string]: unknown;
+    }) => Promise<void>;
+    readonly move: (input: {
+        readonly sessionID: string;
+        [key: string]: unknown;
+    }) => Promise<void>;
+    readonly wait: (input: {
+        readonly sessionID: string;
+    }) => Promise<void>;
+    readonly context: (input: {
+        readonly sessionID: string;
+    }) => Promise<V2SessionMessageInfo[]>;
+}
+/**
+ * v2 worktree types (`@opencode/plugin@2.0.26` + `@opencode/client@2.0.26`).
+ * The host publishes TWO distinct flavors — the client `WorktreeApi` inputs
+ * (project-id keyed) and the plugin `WorktreeDefinition` callback inputs
+ * (source-directory keyed) — and they must not be merged (PR-review feedback
+ * FB-003): a caller against either flavor would compile and then fail
+ * host-side at runtime.
+ */
+/** Client `WorktreeListInput` / `WorktreeRefreshInput` (project-id keyed). */
+export interface V2WorktreeProjectInput {
+    readonly projectID: string;
+}
+/** Client `WorktreeCreateInput`. */
+export interface V2WorktreeCreateInput {
+    readonly projectID: string;
+    readonly from?: string;
+    readonly branch?: string;
+    readonly directory?: string;
+    readonly name?: string;
+    [key: string]: unknown;
+}
+/** Client `WorktreeRemoveInput`. */
+export interface V2WorktreeRemoveInput {
+    readonly projectID: string;
+    readonly directory: string;
+    readonly force: boolean;
+}
+/** Client `WorktreeInfo` (create result; `directory` is the only published member). */
+export interface V2WorktreeInfo {
+    readonly directory: string;
+    [key: string]: unknown;
+}
+/** Plugin `WorktreeCreateInput` (the `../worktree.js` flavor — distinct from the client's). */
+export interface V2PluginWorktreeCreateInput {
+    readonly sourceDirectory: string;
+    readonly directory: string;
+    readonly branch?: string;
+    [key: string]: unknown;
+}
+/** Plugin `WorktreeRemoveInput`. */
+export interface V2PluginWorktreeRemoveInput {
+    readonly directory: string;
+    readonly force: boolean;
+}
+/** Plugin `WorktreeResult` (create return). */
+export interface V2WorktreeResult {
+    readonly directory: string;
+    [key: string]: unknown;
+}
+/**
+ * Plugin `WorktreeEntry` (list item). Only `directory` is published-verified
+ * here; the structural index keeps the remaining fields without inventing shapes.
+ */
+export interface V2WorktreeEntry extends V2WorktreeResult {
+}
+/** Plugin-side `WorktreeDefinition` (registers an implementation via transform). */
+export interface V2WorktreeDefinition {
+    readonly id: string;
+    readonly create: (input: V2PluginWorktreeCreateInput, context: {
+        readonly signal: AbortSignal;
+    }) => Promise<V2WorktreeResult>;
+    readonly remove: (input: V2PluginWorktreeRemoveInput, context: {
+        readonly signal: AbortSignal;
+    }) => Promise<void>;
+    readonly list: (sourceDirectory: string, context: {
+        readonly signal: AbortSignal;
+    }) => Promise<readonly V2WorktreeEntry[]>;
+}
+/** v2 `WorktreeEditor` (dist/promise/worktree.d.ts). */
+export interface V2WorktreeEditor {
+    /** Registers an implementation and selects it as the default. */
+    add(definition: V2WorktreeDefinition): void;
+}
+/**
+ * v2 `WorktreeDomain` (dist/promise/worktree.d.ts 2.0.26): the client
+ * `WorktreeApi` (`list`/`create`/`remove`/`refresh`) plus `transform` and
+ * `reload`. Consumed by no Phase 1 code path; typed so Phase 2+ (issue #3169)
+ * sees the surface with the published requiredness intact.
+ */
+export interface V2WorktreeDomain {
+    readonly list: (input: V2WorktreeProjectInput) => Promise<readonly V2WorktreeInfo[]>;
+    readonly create: (input: V2WorktreeCreateInput) => Promise<V2WorktreeInfo>;
+    readonly remove: (input: V2WorktreeRemoveInput) => Promise<void>;
+    readonly refresh: (input: V2WorktreeProjectInput) => Promise<void>;
+    readonly reload: () => Promise<void>;
+    readonly transform: (callback: (editor: V2WorktreeEditor) => void) => Promise<V2Registration>;
 }
 /** v2 `CommandDefinition` / `CommandEditor` (dist/promise/command.d.ts). */
 export interface V2CommandInvocation {
@@ -253,6 +496,8 @@ export interface V2PluginContext {
     readonly session: V2SessionDomain;
     readonly event: V2EventDomain;
     readonly permission?: V2PermissionDomain;
+    /** Present on 2.0.26 hosts; no Phase 1 code path consumes it (issue #3169). */
+    readonly worktree?: V2WorktreeDomain;
     readonly [key: string]: unknown;
 }
 /** v2 `Cleanup` — the return of `setup`. */