opencode-swarm 7.188.2 → 7.188.4

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

@@ -0,0 +1,30 @@
+/**
+ * v2 guidance delivery — the session `context` hook (issue #3004 / #2910, R1
+ * in ADR-0003).
+ *
+ * Transport mapping (docs/host/v2-hook-inventory.md row 6/7):
+ *
+ *   - The v1 MESSAGES transform chain runs first against a translated view of
+ *     `event.messages`. On v1 its guidance injections ride USER-role carrier
+ *     messages (`swarm-guidance:*` ids, fenced text) because the v1 host drops
+ *     role:'system' entries (#2526). The v2 host renders `event.system`
+ *     natively, so those carriers are RE-HOMED here into `event.system` as
+ *     text parts and removed from the message list — each guidance unit has
+ *     exactly one destination.
+ *   - The v1 SYSTEM transform chain then runs with a translated input and its
+ *     (unfenced) strings are appended as further `event.system` text parts —
+ *     exactly what the v1 system surface receives.
+ *
+ * `event.agent` is an Agent.Info-shaped object on v2; it is normalized to a
+ * name before any v1 agent comparison (frozen C4 header requirement).
+ *
+ * Part-kind mapping (R10): text parts map 1:1; non-text content kinds
+ * (media, tool-call, tool-result, reasoning, step-start, compaction, effort)
+ * are preserved untouched on their message — the v1 chain's steps only read
+ * and write `type === 'text'` parts.
+ */
+import type { V1HooksSubset, V2PluginContext, V2Registration, V2SessionContextEvent } from './types';
+/** The v2 context hook body. */
+export declare function onV2ContextEvent(event: V2SessionContextEvent, hooks: V1HooksSubset, directory: string): Promise<void>;
+/** Register the context hook on the v2 session domain. */
+export declare function registerV2ContextHook(ctx: V2PluginContext, hooks: V1HooksSubset, directory: string, registrations: V2Registration[]): Promise<void>;

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

@@ -0,0 +1,31 @@
+/**
+ * v2 lifecycle hook adapters — tool execute.before/after, session compaction,
+ * session prompt (issue #3004 / #2910).
+ *
+ * Each adapter wraps the SAME v1 handler functions with payload translation:
+ *
+ *   - `tool.execute.before`: v2 `{tool, sessionID, agent, messageID, id,
+ *     input}` → v1 `{tool, sessionID, callID, agent}` + mutable output
+ *     `{args}`; the v1 chain's `output.args` mutation is applied back onto
+ *     `event.input` in place.
+ *   - `tool.execute.after`: v1 `{title, output, metadata}` mutable output is
+ *     fed a best-effort translation of the v2 completed/error result.
+ *     (v2 has no title surface; the translation targets the fields the v1
+ *     toolAfter chain reads.)
+ *   - `compaction`: translated session/model identity; the v1 customizer's
+ *     directive output has no v1→v2 mapping yet — the turn-generation advance
+ *     and the customizer still run (inventory row).
+ *   - `prompt`: the v1 `chat.message` chain (model fallback preflight,
+ *     delegation ledger, cache-cohort seeding) runs against a translated
+ *     envelope. The #2989 chat-boundary model override writes
+ *     `output.message.model`, which the v2 SessionPrompt has no field for —
+ *     v1-only for now (inventory row).
+ *
+ * Denial semantics: a v1 hook throw propagates as the v2 hook error
+ * (fail-closed preserved; documented v2 delta in the inventory).
+ */
+import type { V1HooksSubset, V2PluginContext, V2Registration } from './types';
+/** Register the tool hooks (execute.before/after). */
+export declare function registerV2ToolHooks(ctx: V2PluginContext, hooks: V1HooksSubset, directory: string, registrations: V2Registration[]): Promise<void>;
+/** Register the compaction + prompt session hooks. */
+export declare function registerV2SessionHooks(ctx: V2PluginContext, hooks: V1HooksSubset, directory: string, registrations: V2Registration[]): Promise<void>;

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

@@ -0,0 +1,61 @@
+/**
+ * OpenCode 2 (v2 plugin API) setup entrypoint — issue #3004 / #2910.
+ *
+ * The v2 host validates the plugin's default export against
+ * `{ id, setup | effect }` (sst/opencode v2 line, packages/core/src/plugin/
+ * module.ts). The v1 `server()` path stays byte-stable for OpenCode 1 hosts;
+ * this module is what `setup(ctx)` runs on OpenCode 2 hosts.
+ *
+ * Architecture (ADR-0003): the adapter reuses the SAME initialization core and
+ * the SAME v1 hook set — it only TRANSLATES registration surfaces:
+ *
+ *   - tools: `hooks.tool` map → `ctx.tool.transform(editor.add)` (one source,
+ *     `buildPluginToolObject`; no parallel name list — enforced by
+ *     scripts/check-tool-registration.ts);
+ *   - agents + commands: the v1 `config` hook is invoked against a synthetic
+ *     `opencodeConfig` object, making the config hook itself the shared
+ *     builder (auto-select promotions and the command table are reused
+ *     verbatim — zero extraction from src/index.ts);
+ *   - guidance: the v1 messages/system transform chains run against a
+ *     translated session event; the #2526 USER-role guidance carriers the
+ *     messages chain materializes are re-homed into `event.system` (v2 renders
+ *     system natively — the user→system transport delta is recorded in
+ *     docs/host/v2-hook-inventory.md);
+ *   - lifecycle: tool execute.before/after, compaction, prompt hooks and the
+ *     event subscription are wired with payload translation; `setup` returns
+ *     a single Cleanup that disposes every Registration and runs the v1
+ *     dispose teardown.
+ *
+ * Init boundedness (AGENTS.md invariant 1): every `await` in src/host/** is
+ * either on the same physical line as a `withTimeout(` call or inside a
+ * function named deferred-…/cleanup-… (the frozen C6 source-scan convention).
+ * The shared initialization wrapper (`deps.runInit`) is injected by
+ * src/index.ts so no module cycle is created and the FATAL-fail surface stays
+ * with the v1 wrapper.
+ */
+import type { V1HooksSubset, V2PluginContext } from './types';
+/** Dependencies injected from src/index.ts (avoids an index↔host cycle). */
+export interface V2SetupDependencies {
+    /** The shared server-initialization wrapper (begin-interval → init core → schedule deferred → end-interval). */
+    runInit: (input: unknown) => Promise<V1HooksSubset>;
+}
+/** Normalize a v2 agent reference (Agent.Info object or bare string) to a name. */
+export declare function normalizeV2AgentRef(agent: unknown): string | undefined;
+/**
+ * Register the plugin on an OpenCode 2 host. Throws propagate to the v2 host
+ * (which skips the plugin) after a FATAL stderr line from the shared wrapper —
+ * the same posture the v1 server() path has (issue #675).
+ */
+export declare function openCodeSwarmV2Setup(ctx: V2PluginContext, deps: V2SetupDependencies): Promise<() => Promise<void>>;
+/**
+ * Seed the v1 session state a translated hook event implies. Shared by the
+ * guidance/prompt/tool-hook adapters so the v1 chain sees the same session
+ * identity the v1 host would have seeded via chat.message.
+ */
+export declare function seedV1SessionState(sessionID: string | undefined, agentRef: unknown, directory: string): string | undefined;
+/**
+ * Convert a v1 zod args shape into the JSON-schema-ish `input` value the v2
+ * tool editor accepts. Cached per tool at registration time (transforms must
+ * be synchronous and cheap).
+ */
+export declare function v2ToolInputSchema(args: unknown): unknown;

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

@@ -0,0 +1,41 @@
+/**
+ * v2 tool registration — issue #3004 / #2910.
+ *
+ * Registers every tool from the SAME map the v1 host receives
+ * (`hooks.tool`, built by `buildPluginToolObject` from `TOOL_MANIFEST` — the
+ * single source; scripts/check-tool-registration.ts enforces that no parallel
+ * name list exists here).
+ *
+ * The execute adapter synthesizes the FULL v1 `ToolContext` (AGENTS.md
+ * invariant 4: `.swarm/` must resolve against the project root captured at
+ * setup, never `process.cwd()`): `directory`/`worktree` are injected, the v2
+ * `signal` becomes the v1 `abort`, `progress` bridges v1 `metadata({title?,
+ * metadata?})`, and `ask` bridges to the v2 permission domain when available
+ * and fails closed otherwise.
+ *
+ * Result mapping: v1 `string | {title?, output, metadata?, attachments?}` →
+ * v2 `{content, metadata}` (v2 has no title/attachment surface — inventory
+ * row in docs/host/v2-hook-inventory.md).
+ */
+import type { V1HooksSubset, V2PluginContext, V2Registration, V2ToolContext } from './types';
+interface V1ToolContextShape {
+    sessionID: string;
+    messageID: string;
+    agent: string;
+    directory: string;
+    worktree: string;
+    abort: AbortSignal;
+    metadata: (input: {
+        title?: string;
+        metadata?: Record<string, unknown>;
+    }) => void;
+    ask: (input: unknown) => Promise<void>;
+}
+/** Synthesize the v1 ToolContext the plugin's tools expect (R2 in ADR-0003). */
+declare function synthesizeV1ToolContext(context: V2ToolContext, projectRoot: string, permissionBridge: ((input: unknown) => Promise<void>) | undefined): V1ToolContextShape;
+/** Register all v1 tools on the v2 tool domain. */
+export declare function registerV2Tools(ctx: V2PluginContext, hooks: V1HooksSubset, projectRoot: string, registrations: V2Registration[]): Promise<void>;
+export declare const _internals: {
+    synthesizeV1ToolContext: typeof synthesizeV1ToolContext;
+};
+export {};

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

@@ -0,0 +1,291 @@
+/**
+ * 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).
+ * 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.
+ *
+ * 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).
+ */
+/** v2 `App` — host identity (dist/app.d.ts). */
+export interface V2App {
+    readonly name: string;
+    readonly version: string;
+    readonly channel: string;
+}
+/** v2 `Location.Info` — project anchor (dist/location.d.ts). */
+export interface V2Location {
+    readonly directory: string;
+    readonly workspaceID?: string;
+    readonly project?: {
+        readonly id?: string;
+        readonly directory?: string;
+        readonly canonical?: string;
+    };
+}
+/** v2 `PluginOptions` (dist/options.d.ts). */
+export type V2PluginOptions = Readonly<Record<string, unknown>>;
+/** v2 `Registration` (dist/promise/registration.d.ts). */
+export interface V2Registration {
+    readonly dispose: () => Promise<void>;
+}
+/** v2 `Tool.Result` content parts (schema/tool.d.ts). */
+export type V2ToolContent = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'file';
+    readonly uri: string;
+    readonly mime: string;
+    readonly name?: string;
+};
+/** v2 `Tool.Result` (schema/tool.d.ts). */
+export interface V2ToolResult {
+    readonly output?: unknown;
+    readonly content?: string | ReadonlyArray<V2ToolContent>;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** v2 tool `ToolContext` (dist/promise/tool.d.ts). */
+export interface V2ToolContext {
+    readonly sessionID: string;
+    readonly agent: unknown;
+    readonly messageID: string;
+    readonly id: string;
+    readonly signal: AbortSignal;
+    readonly progress: (update: Readonly<Record<string, unknown>>) => Promise<void>;
+}
+/** v2 `Tool.Info` shape accepted by `ToolEditor.add` (dist/promise/tool.d.ts). */
+export interface V2ToolInfo {
+    readonly name: string;
+    readonly description: string;
+    readonly input: unknown;
+    readonly execute: (input: unknown, context: V2ToolContext) => Promise<V2ToolResult>;
+}
+/** v2 `ToolEditor` (dist/promise/tool.d.ts). */
+export interface V2ToolEditor {
+    add(tool: V2ToolInfo): void;
+    list(): Array<V2ToolInfo & {
+        readonly id: string;
+    }>;
+    get(id: string): (V2ToolInfo & {
+        readonly id: string;
+    }) | undefined;
+    update(id: string, update: (tool: unknown) => void): void;
+    remove(id: string): void;
+    namespace(namespace: {
+        readonly name: string;
+        readonly description: string;
+    }): void;
+}
+/** v2 `ToolDomain` (dist/promise/tool.d.ts) — hook payloads inline. */
+export interface V2ToolDomain {
+    readonly transform: (callback: (editor: V2ToolEditor) => void) => Promise<V2Registration>;
+    readonly reload: () => Promise<void>;
+    readonly hook: (name: 'execute.before' | 'execute.after', callback: (input: V2ToolHookInput) => Promise<void> | void) => Promise<V2Registration>;
+}
+export interface V2ToolHookInput {
+    readonly tool: string;
+    readonly sessionID: string;
+    readonly agent: unknown;
+    readonly messageID: string;
+    readonly id: string;
+    input?: unknown;
+    readonly status?: 'completed' | 'error';
+    readonly result?: V2ToolResult;
+    readonly error?: {
+        message?: string;
+        [key: string]: unknown;
+    };
+}
+/** v2 text part on the system surface (`SystemPart`, @opencode/ai messages.d.ts). */
+export interface V2SystemPart {
+    type: 'text';
+    text: string;
+    cache?: unknown;
+    metadata?: Record<string, unknown>;
+}
+/** v2 `Message` (abbreviated to the text-relevant surface). */
+export interface V2Message {
+    id?: string;
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: Array<{
+        type: string;
+        text?: string;
+        [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+}
+/** v2 `SessionContext` event (dist/promise/session.d.ts; DeepMutable in place). */
+export interface V2SessionContextEvent {
+    readonly sessionID: string;
+    readonly agent: unknown;
+    readonly model?: {
+        id?: string;
+        providerID?: string;
+        [key: string]: unknown;
+    };
+    system: V2SystemPart[];
+    messages: V2Message[];
+    options: Record<string, unknown>;
+    tools: Record<string, {
+        description: string;
+        input: unknown;
+    }>;
+}
+/** v2 `SessionCompaction` event (extends SessionContext + settable result). */
+export interface V2SessionCompactionEvent extends V2SessionContextEvent {
+    result?: {
+        summary: string;
+        [key: string]: unknown;
+    };
+}
+/** v2 `SessionPrompt` event (dist/promise/session.d.ts). */
+export interface V2SessionPromptEvent {
+    readonly sessionID: string;
+    readonly messageID: string;
+    prompt: {
+        text: string;
+        files?: unknown[];
+        agents?: unknown[];
+        skills?: unknown[];
+    };
+    readonly delivery?: string;
+}
+/** v2 `SessionDomain` (only hook used by this adapter). */
+export interface V2SessionDomain {
+    readonly hook: (name: 'context' | 'compaction' | 'prompt', callback: (event: never) => Promise<void> | void) => Promise<V2Registration>;
+    readonly prompt?: (sessionID: string, input: {
+        text: string;
+    } | {
+        command: string;
+        args?: string;
+    }) => Promise<unknown>;
+}
+/** v2 `CommandDefinition` / `CommandEditor` (dist/promise/command.d.ts). */
+export interface V2CommandInvocation {
+    readonly sessionID: string;
+    readonly prompt: {
+        text: string;
+        [key: string]: unknown;
+    };
+    readonly delivery?: string;
+}
+export interface V2CommandDefinition {
+    readonly name: string;
+    readonly description?: string;
+    readonly execute: (input: V2CommandInvocation) => Promise<void>;
+}
+export interface V2CommandDomain {
+    readonly transform: (callback: (editor: {
+        add(definition: V2CommandDefinition): void;
+    }) => void) => Promise<V2Registration>;
+    readonly reload: () => Promise<void>;
+}
+/** v2 `Agent.Info` (schema/agent.d.ts; only fields this adapter writes). */
+export interface V2AgentInfo {
+    id: string;
+    name: string;
+    mode: 'subagent' | 'primary' | 'all';
+    hidden: boolean;
+    request: {
+        settings: Record<string, unknown>;
+        headers: Record<string, string>;
+        body: Record<string, unknown>;
+    };
+    system?: string;
+    description?: string;
+    model?: {
+        id: string;
+        providerID: string;
+        variant?: string;
+    };
+    permissions?: Array<{
+        action: string;
+        resource: string;
+        effect: 'allow' | 'deny' | 'ask';
+    }>;
+}
+/** v2 `AgentEditor` (dist/promise/agent.d.ts). */
+export interface V2AgentEditor {
+    list(): V2AgentInfo[];
+    get(id: string): V2AgentInfo | undefined;
+    default(id: string | undefined): void;
+    update(id: string, update: (agent: V2AgentInfo) => void): void;
+    remove(id: string): void;
+}
+/** v2 `AgentDomain`. */
+export interface V2AgentDomain {
+    readonly transform: (callback: (editor: V2AgentEditor) => void) => Promise<V2Registration>;
+    readonly reload: () => Promise<void>;
+}
+/** v2 `EventDomain.subscribe` — async iterable of host events. */
+export interface V2EventEnvelope {
+    readonly type?: string;
+    readonly [key: string]: unknown;
+}
+export interface V2EventDomain {
+    readonly subscribe?: (...args: unknown[]) => AsyncIterable<V2EventEnvelope> | Promise<AsyncIterable<V2EventEnvelope>>;
+}
+/** v2 `PermissionDomain` (only used for the v1 ask() bridge, best-effort). */
+export interface V2PermissionDomain {
+    readonly reply?: (input: unknown) => Promise<unknown>;
+    readonly list?: () => Promise<unknown[]>;
+    readonly hook?: (name: 'evaluate', callback: (input: unknown) => Promise<void> | void) => Promise<V2Registration>;
+}
+/**
+ * v2 `Context` (dist/promise/plugin.d.ts) — only the domains this adapter
+ * touches; everything else stays reachable through the index signature so a
+ * superset host context is accepted.
+ */
+export interface V2PluginContext {
+    readonly app: V2App;
+    readonly location: V2Location;
+    readonly options: V2PluginOptions;
+    readonly tool: V2ToolDomain;
+    readonly agent: V2AgentDomain;
+    readonly command: V2CommandDomain;
+    readonly session: V2SessionDomain;
+    readonly event: V2EventDomain;
+    readonly permission?: V2PermissionDomain;
+    readonly [key: string]: unknown;
+}
+/** v2 `Cleanup` — the return of `setup`. */
+export type V2Cleanup = () => Promise<void> | void;
+/** The v1-shaped hooks object the adapter consumes (structural subset). */
+export interface V1HooksSubset {
+    name?: string;
+    tool?: Record<string, {
+        description?: string;
+        args?: unknown;
+        execute?: (args: unknown, ctx: unknown) => Promise<unknown>;
+    }>;
+    agent?: Record<string, unknown>;
+    config?: (opencodeConfig: Record<string, unknown>) => Promise<void>;
+    event?: (input: {
+        event: {
+            type?: string;
+            properties?: Record<string, unknown>;
+        };
+    }) => Promise<void>;
+    dispose?: () => Promise<void>;
+    'command.execute.before'?: (input: unknown, output: unknown) => Promise<void>;
+    'tool.execute.before'?: (input: unknown, output: unknown) => Promise<unknown> | Promise<void>;
+    'tool.execute.after'?: (input: unknown, output: unknown) => Promise<unknown> | Promise<void>;
+    'chat.message'?: (input: unknown, output: unknown) => Promise<unknown> | Promise<void>;
+    'experimental.chat.messages.transform'?: (input: unknown, output: {
+        messages: unknown[];
+    }) => Promise<void>;
+    'experimental.chat.system.transform'?: (input: {
+        sessionID?: string;
+        model?: unknown;
+    }, output: {
+        system: string[];
+    }) => Promise<void>;
+    'experimental.session.compacting'?: (input: unknown, output: unknown) => Promise<void>;
+}

package/dist/index.d.ts

@@ -86,6 +86,7 @@ type PendingCostCorrection = {
 declare const _default: {
     id: "opencode-swarm";
     server: Plugin;
+    setup: (ctx: unknown) => Promise<() => Promise<void>>;
 };
 export default _default;
 export type { AgentDefinition } from './agents';