opencode-swarm 7.175.0 → 7.176.0

package/dist/observability/startup-contract.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The startup and first-use latency contract (issue #2670).
+ *
+ * Stage model — every interval the issue names, measured and emitted
+ * SEPARATELY as single-line `STARTUP-CONTRACT <json>` rows on stdout:
+ *
+ *   import         performance.now() at the end of src/index.ts module
+ *                  evaluation (ms since performance.timeOrigin, i.e.
+ *                  process start). The fresh-process harness child's own
+ *                  external import timer additionally includes its
+ *                  node:perf_hooks import and preload; the two values are
+ *                  intentionally not expected to be identical.
+ *   server         server() entry -> resolution (the plugin wrapper in
+ *                  src/index.ts).
+ *   first_turn     time from server resolution until the FIRST
+ *                  experimental.chat.messages.transform invocation
+ *                  settles (success or rejection), once per process.
+ *   first_tool     time from server resolution until the FIRST tool
+ *                  execute settles (success or rejection), once per
+ *                  process, labeled with the tool name.
+ *   readiness      queue_settled: the wrapper-owned post-resolution queue
+ *                  has fully drained (every scheduled task settled),
+ *                  measured from drain scheduling. Optional work NEVER
+ *                  gates manifest delivery (AGENTS.md invariant 1).
+ *   optional_task  per-task outcome rows: task name, `completed|failed`,
+ *                  duration from drain start; failed rows carry a bounded
+ *                  error string (<=200 chars, no stack, single line).
+ *
+ * Emission is gated behind OPENCODE_SWARM_DEBUG=1 exactly like
+ * src/utils/logger.ts — ZERO contract rows appear with the env var unset
+ * (no chat-visible noise, invariant 10; asserted by the frozen acceptance
+ * checks' debug-off probe and the unit suite).
+ *
+ * All collectors are in-memory only: no filesystem writes, no awaits added
+ * to any init path, no new module-load side effects beyond one
+ * performance.now() capture (invariant 1). Per-boot state resets on every
+ * server() entry so repeated boots in one process (tests) stay coherent;
+ * the import mark is captured once per process.
+ *
+ * The advisory counter is a STARTUP-window counter: the window opens at
+ * server entry and closes at queue settle (or at server resolution when no
+ * queue is scheduled) and never re-opens — late-session advisories never
+ * contribute to `queue_settled.advisories`.
+ */
+type PostResolutionTaskLike = () => void | Promise<void>;
+interface StartupContractState {
+    importMarkMs: number | null;
+    serverStartMark: number | null;
+    serverResolvedMark: number | null;
+    serverMs: number | null;
+    queueScheduledAt: number | null;
+    queuePending: number;
+    queueTasks: number;
+    queueCompleted: number;
+    queueFailed: number;
+    queueSettled: boolean;
+    queueSettledMs: number | null;
+    advisoryCount: number;
+    advisoryWindowOpen: boolean;
+    firstTurnDone: boolean;
+    firstToolDone: boolean;
+    firstToolName: string | null;
+    firstTurnMs: number | null;
+    firstToolMs: number | null;
+}
+/** Capture the import-stage mark. Called once at src/index.ts module scope. */
+export declare function markStartupImportComplete(): void;
+/**
+ * Begin the server-interval and open the startup advisory window. Resets
+ * per-boot state (the import mark persists). Called at server() entry.
+ */
+export declare function beginStartupServerInterval(): void;
+/** Resolve the server interval and emit the init row. Called just before the wrapper returns its hooks. */
+export declare function endStartupServerInterval(): void;
+/**
+ * Record that optional tasks were scheduled onto the post-resolution queue:
+ * captures the settle-interval origin. Task and pending counts are owned by
+ * the wrapper (one increment per wrapped task, one decrement per settle), so
+ * late-appended tasks are accounted correctly.
+ */
+export declare function noteQueueScheduled(): void;
+/**
+ * Wrap one post-resolution task so its settle outcome is recorded. Settle
+ * tracking is try/finally-structured: a synchronous throw and an async
+ * rejection both record and re-raise, preserving the drain loop's existing
+ * non-fatal catch semantics (src/index.ts). Tasks appended to the array
+ * after a settle still get outcome rows (bounded late-task behavior).
+ */
+export declare function wrapPostResolutionTask(task: PostResolutionTaskLike): PostResolutionTaskLike;
+/**
+ * Observe the FIRST invocation of a host-facing handler (chat transform or
+ * tool execute) without changing it: returns the handler's own result /
+ * promise untouched and attaches a detached observation that records the
+ * first-use interval when the invocation SETTLES (success or rejection —
+ * an errored first call is still a first use). No extra awaits on the
+ * observed path, no writes to any argument, no rebinding.
+ */
+export declare function withStartupFirstUseTracking<Args extends unknown[], Result>(stage: 'first_turn' | 'first_tool', label: string | undefined, handler: (...args: Args) => Result): (...args: Args) => Result;
+/**
+ * Tool-execute specialization of the first-use observation with a FIXED
+ * two-parameter signature: the plugin's ToolDefinition.execute contract is
+ * `(args, ctx) => ...`, and the registration-convention tests assert
+ * `execute.length >= 2` on tool definitions. The wrapper still returns the
+ * wrapped execute's own result untouched and records the interval when the
+ * invocation settles (success or rejection).
+ */
+export declare function withStartupFirstToolTracking<Args, Result>(name: string, execute: (args: Args, ctx: unknown) => Result): (args: Args, ctx: unknown) => Result;
+/**
+ * Count a startup-window advisory (readiness warning). Called from
+ * warning-buffer's addDeferredWarning; the window opens at server entry
+ * and closes at queue settle (never re-opens), so late-session advisories
+ * never contribute.
+ */
+export declare function noteStartupAdvisory(): void;
+/**
+ * The collected contract state, as a structured report.
+ *
+ * @internal Unit-test seam and future surfaces; not a public API.
+ */
+export declare function buildStartupContractReport(): StartupContractState;
+/**
+ * DI seam for testability (repo convention; see src/utils/logger.ts).
+ * Internal calls route through `_internals` so tests can inject a
+ * deterministic performance clock and capture emissions without
+ * mock.module.
+ */
+export declare const _internals: {
+    performance: {
+        now: () => number;
+    };
+    isDebugEnabled: () => boolean;
+    emitLine: (line: string) => void;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.175.0",
+	"version": "7.176.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",
@@ -112,6 +112,7 @@
 		"prepare": "bun run build",
 		"repro:704": "node scripts/repro-704.mjs",
 		"repro:2669": "node scripts/repro-2669.mjs",
+		"repro:2670": "node scripts/repro-2670.mjs",
 		"repro:1144": "bun scripts/repro-1144.mjs",
 		"repro:1873": "bun build scripts/repro-1873-entry.ts --outdir dist-build-test/repro-1873 --target node --format esm && node scripts/repro-1873.mjs",
 		"repro:2487": "bun build scripts/repro-2487-parity-entry.ts --outdir dist-build-test/repro-2487 --target node --format esm && node scripts/repro-2487-parity.mjs",