opencode-swarm 7.54.0 → 7.55.0

package/dist/background/completion-observer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Background subagent completion OBSERVER (issue #1151, PR 2 Stage A).
+ *
+ * Registers as a swarm `event` hook to watch for the upstream background-completion signal:
+ * a message part with `synthetic === true` whose text is a task envelope with
+ * `state="completed"` or `state="error"`. When such a part correlates to a durable pending
+ * background-delegation record, it is logged (debug-gated) as the empirical confirmation
+ * instrument operators use to verify the runtime signal in a real environment.
+ *
+ * Stage A is strictly READ-ONLY: this observer NEVER advances workflow gates, records gate
+ * evidence, or mutates the durable store. Gate-affecting completion ingestion is Stage B,
+ * gated on runtime confirmation produced by exactly this observer.
+ *
+ * The `synthetic` flag is the trust gate (set by OpenCode, not the model/user). Non-synthetic
+ * text that merely looks like an envelope is ignored. The observer is fail-open: any error is
+ * swallowed so it can never block event delivery or plugin load (Invariant 1/10).
+ */
+interface ObserverConfig {
+    enabled: boolean;
+}
+/**
+ * Build the Stage A completion observer. Returns an `event` handler suitable for the
+ * OpenCode plugin `event` hook. No-op (cheap early return) when the feature is disabled.
+ */
+export declare function createBackgroundCompletionObserver(opts: {
+    config: ObserverConfig;
+    directory: string;
+}): {
+    event: (input: {
+        event: unknown;
+    }) => Promise<void>;
+};
+export {};

package/dist/background/pending-delegations.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Durable pending background-delegation store (issue #1151, PR 2 Stage A).
+ *
+ * Append-only JSONL event log under project-root `.swarm/background-delegations.jsonl`.
+ * Each line is a full record snapshot; readers fold to the latest snapshot per
+ * `correlationId`. This tracks background swarm `Task` dispatches so a later (Stage B)
+ * trusted completion can be correlated to a real dispatch. The stale sweep bounds the
+ * number of permanently-running (unresolved) entries by transitioning them to `stale`, so
+ * the folded in-memory view stays bounded by distinct correlationIds. Note: the on-disk
+ * log itself is append-only and is NOT compacted in Stage A — each dispatch leaves a small,
+ * fixed number of lines; on-disk compaction of dropped/stale records is a future stage.
+ *
+ * Stage A scope: dispatch records a `pending` snapshot and the stale sweep records
+ * `stale` snapshots. There is NO gate advancement and NO completion mutation here — the
+ * completion observer (Stage A) is read-only. Gate-affecting completion ingestion is
+ * Stage B, gated on runtime confirmation of the upstream completion signal.
+ *
+ * Concurrency: all writes (append, sweep) run under a single project-scoped lock via
+ * `withEvidenceLock`, so concurrent dispatches/sweeps cannot interleave appends. Reads are
+ * lock-free (line-oriented; partial trailing lines are skipped defensively).
+ *
+ * Containment: the path is validated with `validateSwarmPath`, so it can never escape
+ * `.swarm/` (Invariant 4).
+ */
+export declare const BACKGROUND_DELEGATIONS_FILE = "background-delegations.jsonl";
+export type BackgroundDelegationStatus = 'pending' | 'completed' | 'error' | 'stale';
+export interface BackgroundDelegationRecord {
+    schemaVersion: 1;
+    /** Subagent session id from the dispatch envelope — the correlation key. */
+    correlationId: string;
+    /** Structured jobId from dispatch metadata when available, else null. */
+    jobId: string | null;
+    /** Subagent session id (== correlationId; kept explicit for clarity/forward-compat). */
+    subagentSessionId: string;
+    /** Parent (dispatching) session id. */
+    parentSessionId: string;
+    /** Tool callID of the dispatching Task call. */
+    callID: string;
+    /** Canonical swarm role (e.g. "reviewer", "test_engineer"). */
+    normalizedAgent: string;
+    /** Raw, possibly swarm-prefixed agent name (e.g. "mega_reviewer"). */
+    swarmPrefixedAgent: string;
+    /** Plan/evidence task id resolved at dispatch, or null. */
+    planTaskId: string | null;
+    evidenceTaskId: string | null;
+    status: BackgroundDelegationStatus;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Read and fold the store to the latest snapshot per correlationId. Lock-free and
+ * defensive: a missing file yields an empty list, and malformed/partial lines are skipped
+ * (never throws). Records are returned in first-seen correlationId order.
+ *
+ * Cost: O(lines on disk) per call — a full read + parse + fold with no in-memory cache.
+ * This is intentionally simple and acceptable at Stage A volumes (a swarm has few concurrent
+ * background delegations, and the on-disk log is small). If sustained high-throughput
+ * background load ever makes this hot, a future stage should add a stat-invalidated in-memory
+ * cache and/or JSONL compaction (the same future-compaction work noted in the module header).
+ */
+export declare function readDelegations(directory: string): BackgroundDelegationRecord[];
+/** Returns the folded record for a correlationId, or null. Lock-free read. */
+export declare function findByCorrelationId(directory: string, correlationId: string): BackgroundDelegationRecord | null;
+export interface RecordPendingInput {
+    correlationId: string;
+    jobId: string | null;
+    subagentSessionId: string;
+    parentSessionId: string;
+    callID: string;
+    normalizedAgent: string;
+    swarmPrefixedAgent: string;
+    planTaskId: string | null;
+    evidenceTaskId: string | null;
+}
+/**
+ * Record a `pending` background delegation. Runs the stale sweep first (lazy maintenance,
+ * no plugin-init cost), then appends the pending snapshot — all under one lock acquisition
+ * so concurrent dispatches cannot interleave. Best-effort: returns null on lock timeout or
+ * write failure (Stage A has no gate effects, so a missed record is non-fatal).
+ */
+export declare function recordPendingDelegation(directory: string, input: RecordPendingInput, options?: {
+    staleTimeoutMs?: number;
+}): Promise<BackgroundDelegationRecord | null>;
+/**
+ * Public stale sweep: acquires the store lock and marks overdue pendings as `stale`.
+ * Best-effort; returns the number swept (0 on lock timeout / error).
+ */
+export declare function sweepStaleDelegations(directory: string, timeoutMs: number): Promise<number>;

package/dist/background/task-envelope.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Background subagent task-envelope parsing (issue #1151, PR 2 Stage A).
+ *
+ * OpenCode background subagents (v1.16.2) render task dispatch/completion as a stable
+ * XML-ish envelope via the upstream `renderOutput`:
+ *
+ *   <task id="<subagentSessionID>" state="running|completed|error">
+ *   <summary>...</summary>
+ *   <task_result>...</task_result>   (or <task_error> for state="error")
+ *   </task>
+ *
+ * - The dispatch tool result carries `state="running"` and the subagent session id.
+ * - The deferred completion arrives as a synthetic parent message part whose text is the
+ *   same envelope with `state="completed"` or `state="error"`.
+ *
+ * These parsers are intentionally pure and defensive — they never throw — so they can be
+ * used both at dispatch (tool.execute.after output) and at completion observation time.
+ */
+export type TaskEnvelopeState = 'running' | 'completed' | 'error';
+export interface TaskEnvelope {
+    /** The subagent session id from `<task id="...">` — the cross-event correlation key. */
+    sessionId: string;
+    state: TaskEnvelopeState;
+}
+/**
+ * Parse a task envelope from arbitrary text. Returns null when the text does not contain
+ * a well-formed opening `<task id="..." state="...">` tag. Never throws.
+ */
+export declare function parseTaskEnvelope(text: unknown): TaskEnvelope | null;
+/**
+ * Extract the subagent session id and (optional) jobId from a background `Task` dispatch
+ * result (the `tool.execute.after` output object `{ title, output, metadata }`).
+ *
+ * - `subagentSessionId` is parsed from the rendered `output` envelope `<task id="...">`.
+ * - `jobId` is read defensively from `metadata.jobId` (the installed plugin SDK types this
+ *   field as `any`; upstream sets `{ background: true, jobId }`). Absent → null.
+ *
+ * Both are best-effort; either may be null.
+ */
+export declare function extractDispatchIds(output: unknown): {
+    subagentSessionId: string | null;
+    jobId: string | null;
+};

package/dist/cli/index.js

@@ -52,7 +52,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.54.0",
+    version: "7.55.0",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -17302,7 +17302,9 @@ var init_schema = __esm(() => {
     delegation_tracker: exports_external.boolean().default(false),
     agent_awareness_max_chars: exports_external.number().min(50).max(2000).default(300),
     delegation_gate: exports_external.boolean().default(true),
-    delegation_max_chars: exports_external.number().min(500).max(20000).default(4000)
+    delegation_max_chars: exports_external.number().min(500).max(20000).default(4000),
+    background_subagents: exports_external.boolean().default(false),
+    background_pending_timeout_minutes: exports_external.number().int().min(1).max(1440).default(30)
   });
   ScoringWeightsSchema = exports_external.object({
     phase: exports_external.number().min(0).max(5).default(1),

package/dist/config/schema.d.ts

@@ -93,6 +93,8 @@ export declare const HooksConfigSchema: z.ZodObject<{
     agent_awareness_max_chars: z.ZodDefault<z.ZodNumber>;
     delegation_gate: z.ZodDefault<z.ZodBoolean>;
     delegation_max_chars: z.ZodDefault<z.ZodNumber>;
+    background_subagents: z.ZodDefault<z.ZodBoolean>;
+    background_pending_timeout_minutes: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export type HooksConfig = z.infer<typeof HooksConfigSchema>;
 export declare const ScoringWeightsSchema: z.ZodObject<{
@@ -958,6 +960,8 @@ export declare const PluginConfigSchema: z.ZodObject<{
         agent_awareness_max_chars: z.ZodDefault<z.ZodNumber>;
         delegation_gate: z.ZodDefault<z.ZodBoolean>;
         delegation_max_chars: z.ZodDefault<z.ZodNumber>;
+        background_subagents: z.ZodDefault<z.ZodBoolean>;
+        background_pending_timeout_minutes: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     gates: z.ZodOptional<z.ZodObject<{
         syntax_check: z.ZodDefault<z.ZodObject<{