opencode-swarm 7.182.0 → 7.183.0

package/dist/observability/catalog.d.ts

@@ -1,7 +1,7 @@
 /**
  * The event catalog (issue #2029).
  *
- * Exactly 64 entries, matching the `TelemetryEvent` union at
+ * Exactly 65 entries, matching the `TelemetryEvent` union at
  * `src/telemetry.ts:20-172`. Thirty-eight predate the #2029 contract; the 39th is
  * `agent_conflict_detected` (previously emitted through a force-cast past the
  * type system), the 40th is `close_archive_result` (issue #2030 — the
@@ -89,7 +89,7 @@ export interface CatalogEntry {
     /**
      * Whether an event of this kind must carry `trace.parentSpanId`.
      *
-     * `false` for all 64 entries today, and that is a truthful statement about
+     * `false` for all 65 entries today, and that is a truthful statement about
      * the current system rather than a placeholder: no producer supplies a
      * parent span, so `createObservation` never sets one. Setting this to `true`
      * for a kind whose producer cannot supply a parent would make every

package/dist/observability/envelope.d.ts

@@ -136,6 +136,8 @@ export declare const WorkflowIdsSchema: z.ZodObject<{
     hostSessionId: z.ZodOptional<z.ZodString>;
     swarmSessionId: z.ZodOptional<z.ZodString>;
     taskId: z.ZodOptional<z.ZodString>;
+    callId: z.ZodOptional<z.ZodString>;
+    invocationId: z.ZodOptional<z.ZodString>;
     phaseId: z.ZodOptional<z.ZodString>;
     laneId: z.ZodOptional<z.ZodString>;
     batchId: z.ZodOptional<z.ZodString>;
@@ -329,6 +331,8 @@ export declare const ObservabilityEventSchema: z.ZodObject<{
         hostSessionId: z.ZodOptional<z.ZodString>;
         swarmSessionId: z.ZodOptional<z.ZodString>;
         taskId: z.ZodOptional<z.ZodString>;
+        callId: z.ZodOptional<z.ZodString>;
+        invocationId: z.ZodOptional<z.ZodString>;
         phaseId: z.ZodOptional<z.ZodString>;
         laneId: z.ZodOptional<z.ZodString>;
         batchId: z.ZodOptional<z.ZodString>;

package/dist/services/execution-attempt.d.ts

@@ -0,0 +1,80 @@
+/** Closed attempt/outcome record-class vocabulary (issue #2676 AC1). */
+export type ExecutionAttemptClass = 'denial' | 'attempt' | 'result' | 'duplicate' | 'late' | 'cancelled' | 'provider_failed';
+export declare const EXECUTION_ATTEMPT_CLASSES: readonly ExecutionAttemptClass[];
+/** Terminal disposition of the attempt, when the producer reported one. */
+export type ExecutionAttemptOutcomeStatus = 'success' | 'failure' | 'partial' | 'unknown';
+/** The frozen per-attempt cost axes (issue #2676 AC2). */
+export declare const TASK_ATTEMPT_COST_AXES: readonly ["latencyMs", "inputTokens", "outputTokens", "cacheReadTokens", "estimatedCostUsd", "billedCostUsd"];
+export type TaskAttemptCostAxis = (typeof TASK_ATTEMPT_COST_AXES)[number];
+/** Caller-held cost facts. An absent key means the producer did not hold it. */
+export interface TaskAttemptCostInput {
+    taskId?: string;
+    attemptId?: string;
+    latencyMs?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    estimatedCostUsd?: number;
+    billedCostUsd?: number;
+}
+/**
+ * The built cost record: every axis is `number | null`, `null` meaning the
+ * producer did not hold the value, with `unavailable` listing exactly the
+ * axes that are null. Zero is a legal KNOWN value (zero tokens used) and is
+ * never produced as a fallback for a missing input.
+ */
+export interface TaskAttemptCost extends Record<TaskAttemptCostAxis, number | null> {
+    taskId?: string;
+    attemptId?: string;
+    unavailable: readonly string[];
+}
+/** A known axis value must be finite and non-negative to count as held. */
+declare function knownCostValue(value: number | undefined): number | null;
+/**
+ * Build the per-attempt cost record. Caller-omitted (or invalid) axes are
+ * strictly `null` AND listed in `unavailable`; known axes pass through
+ * verbatim and never appear in `unavailable`.
+ */
+export declare function buildTaskAttemptCost(partial: TaskAttemptCostInput): TaskAttemptCost;
+/** Recorder input. `sessionID`/`callID` are the Stage A casing aliases. */
+export interface ExecutionAttemptInput {
+    sessionId?: string;
+    /** Stage A casing alias for {@link sessionId}; normalized before emit. */
+    sessionID?: string;
+    taskId?: string;
+    callId?: string;
+    /** Stage A casing alias for {@link callId}; normalized before emit. */
+    callID?: string;
+    invocationId?: string;
+    /**
+     * Monotonic generation cursor for the (task, call) pair. REQUIRED for
+     * class `late` — it is the cursor the record was late against. A `late`
+     * caller that cannot supply it is refused fail-open with a warn, never
+     * silently downgraded.
+     */
+    generation?: number;
+    retryIndex?: number;
+    laneId?: string;
+    knowledgeTraceId?: string;
+    attemptClass: ExecutionAttemptClass;
+    outcomeStatus?: ExecutionAttemptOutcomeStatus;
+    /**
+     * Identity (record_id / event id) of the already-committed record this
+     * one duplicates. REQUIRED for class `duplicate`; never synthesized — a
+     * duplicate caller holding no original identity is refused fail-open.
+     */
+    duplicateOf?: string;
+    cost?: TaskAttemptCostInput;
+}
+/** Sanitize an identifier for emission: printable, bounded (Stage A pattern). */
+declare function boundedId(value: string | undefined): string | undefined;
+/**
+ * Record ONE execution attempt as an `execution_attempt_recorded` telemetry
+ * event. Fail-open: invalid input logs a warn and returns without emitting.
+ */
+export declare function recordExecutionAttempt(input: ExecutionAttemptInput): void;
+export declare const _internals: {
+    boundedId: typeof boundedId;
+    knownCostValue: typeof knownCostValue;
+};
+export {};

package/dist/services/task-cohort.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Task-attempt cohort snapshot and qualification (issue #2676 / Workstream D16).
+ *
+ * A causal-rate claim over task attempts requires a stable cohort: a snapshot
+ * of the live population taken at a recorded instant (so later mutation cannot
+ * change a reported denominator), captured provenance manifests for the
+ * trigger / WAL / event / host-status sources (stats + bounded digests, never
+ * content parsing), configuration/version strata, and an uncertainty channel
+ * that is present whenever sample size or cost fields are incomplete. Reports
+ * that cannot meet the contract stay explicitly unqualified and render as
+ * descriptive operational counts (the boundary documented in
+ * docs/execution-attempt-tracing.md).
+ *
+ * The mutable-population rule: `snapshotTaskAttemptCohort` deep-copies the
+ * population it is handed; every later mutation of the caller's array (or of
+ * a nested field of a captured record) is invisible to the snapshot and to
+ * every report built from it.
+ *
+ * Durability: when `directory` is provided, the snapshot persists ONE frozen
+ * manifest JSON under `.swarm/observability/cohorts/` (FIFO-bounded to the
+ * latest 20 files; write failures are warn-logged and never propagate). This
+ * is the only filesystem side effect, and it is registered in the retention
+ * registry (row `observability-cohorts`).
+ */
+/** Number of frozen cohort manifests retained on disk (FIFO). */
+export declare const COHORT_MANIFEST_RETENTION = 20;
+/** Sample size below which a cohort always reports a sample-size uncertainty. */
+export declare const COHORT_SAMPLE_SIZE_THRESHOLD = 30;
+/** The provenance manifest sources captured before a cohort is reported. */
+export type CohortManifestSource = 'trigger' | 'wal' | 'event' | 'host_status';
+export interface CohortManifestEntry {
+    source: CohortManifestSource;
+    status: 'captured' | 'unavailable';
+    capturedAt: string;
+    sizeBytes?: number;
+    digest?: string;
+}
+/** One population record (a folded execution-attempt row or equivalent). */
+export interface TaskAttemptPopulationRecord {
+    taskId?: string;
+    attemptClass?: string;
+    outcomeStatus?: string;
+    cost?: unknown;
+    [key: string]: unknown;
+}
+export interface TaskAttemptCohortStrata {
+    pluginVersion?: string;
+    runtime?: string;
+    configHash?: string;
+}
+export interface TaskAttemptCohortSnapshot {
+    tasks: readonly TaskAttemptPopulationRecord[];
+    capturedAt: string;
+    count: number;
+    strata: TaskAttemptCohortStrata;
+    manifests: readonly CohortManifestEntry[];
+}
+export interface TaskCohortReport {
+    denominator: number;
+    capturedAt: string;
+    perClassCounts: Record<string, number>;
+    /** Sum over records that HELD the axis (unknown axes contribute nothing). */
+    costTotalsKnown: Record<string, number>;
+    /** Per axis: how many captured records did not hold the value. */
+    costUnavailableCounts: Record<string, number>;
+    strata: TaskAttemptCohortStrata;
+    /** Non-empty whenever sample size or cost fields are incomplete. */
+    uncertainty: string[];
+    qualification: {
+        qualified: boolean;
+        reasons: string[];
+    };
+}
+declare function deepCopyRecord(record: TaskAttemptPopulationRecord): TaskAttemptPopulationRecord;
+declare function captureFileManifest(source: CohortManifestSource, filePath: string, capturedAt: string): CohortManifestEntry;
+/** Minimal shape of `process.versions` this module derives a label from. */
+export type RuntimeVersions = {
+    bun?: string;
+    node?: string;
+};
+/**
+ * Derive the honest runtime label from the host's version table. Bun also
+ * defines `process.versions.node`, so the branch must test bun PRESENCE —
+ * never string truthiness (a `.trim()`-based `||` fallback yields the bare,
+ * version-less "bun" under Node, which sha256-hashes into a poisoned
+ * host-status digest).
+ */
+export declare function deriveRuntimeLabel(versions: RuntimeVersions): string;
+declare function captureHostStatusManifest(capturedAt: string, strata: TaskAttemptCohortStrata): CohortManifestEntry;
+declare function manifestFileName(capturedAt: string, manifests: readonly CohortManifestEntry[]): string;
+declare function persistSnapshotManifest(directory: string, snapshot: TaskAttemptCohortSnapshot): void;
+/**
+ * Snapshot the live task-attempt population. The population is DEEP-copied:
+ * later mutation of the caller's array or of nested record fields cannot
+ * change this snapshot or any report built from it. Provenance manifests for
+ * the trigger / WAL / event stores are captured BEFORE the population copy is
+ * returned, so the reported cohort metric is bound to the population state
+ * the manifests describe. When `directory` is provided the snapshot is
+ * persisted as a frozen manifest under `.swarm/observability/cohorts/`.
+ */
+export declare function snapshotTaskAttemptCohort(input: {
+    tasks: TaskAttemptPopulationRecord[];
+    directory?: string;
+    strata?: TaskAttemptCohortStrata;
+    now?: Date;
+}): TaskAttemptCohortSnapshot;
+/**
+ * Build the cohort report from a snapshot. The denominator is the SNAPSHOT's
+ * captured count — never a live recount. Uncertainty entries are present
+ * whenever the sample is below threshold, any cost axis is unavailable on any
+ * record, or any record lacks an outcome; qualification is false with
+ * enumerated reasons when the cohort cannot support a causal-rate claim.
+ */
+export declare function buildTaskCohortReport(snapshot: TaskAttemptCohortSnapshot): TaskCohortReport;
+export declare const _internals: {
+    captureFileManifest: typeof captureFileManifest;
+    captureHostStatusManifest: typeof captureHostStatusManifest;
+    deriveRuntimeLabel: typeof deriveRuntimeLabel;
+    manifestFileName: typeof manifestFileName;
+    persistSnapshotManifest: typeof persistSnapshotManifest;
+    deepCopyRecord: typeof deepCopyRecord;
+};
+export {};

package/dist/telemetry.d.ts

@@ -41,7 +41,7 @@ export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activa
  * `prm_hard_stop` TRIGGER emitted by `src/prm/escalation.ts`. A trigger with
  * no matching delivery means the containment never reached the agent.
  */
- | 'prm_hard_stop_delivered' | 'agent_conflict_detected' | 'close_archive_result' | 'knowledge_receipt_transition' | 'knowledge_maintenance' | 'residue_health' | 'context_telemetry_health' | 'skill_usage_health' | 'core_events_health' | 'shell_audit_health' | 'trajectory_health' | 'learning_health_alarm' | 'pr_subscription_health' | 'council_attempt' | 'council_round_transition' | 'council_attempt_unscoped' | 'context_source_attribution' | 'verdict_row_pipe_recovery' | 'training_vault_health';
+ | 'prm_hard_stop_delivered' | 'agent_conflict_detected' | 'close_archive_result' | 'knowledge_receipt_transition' | 'knowledge_maintenance' | 'residue_health' | 'context_telemetry_health' | 'skill_usage_health' | 'core_events_health' | 'shell_audit_health' | 'trajectory_health' | 'learning_health_alarm' | 'pr_subscription_health' | 'execution_attempt_recorded' | 'council_attempt' | 'council_round_transition' | 'council_attempt_unscoped' | 'context_source_attribution' | 'verdict_row_pipe_recovery' | 'training_vault_health';
 /** Stable classification for how a reviewer-gate decision was established. */
 export type ReviewerGateEvidenceKind = 'genuine' | 'fallback' | 'data_quality' | 'block';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.182.0",
+	"version": "7.183.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",