opencode-swarm 7.51.6 → 7.52.0

package/dist/context-map/telemetry.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Telemetry recording and persistence for the Context Capsule feature.
+ *
+ * Records capsule telemetry data (token estimates, cache hit/miss counts,
+ * stale summary counts) per delegation. Aggregates telemetry written to
+ * `.swarm/context-telemetry.jsonl` for user inspection.
+ *
+ * All functions are synchronous for simplicity and reliability. The module
+ * uses the `_internals` DI seam pattern so tests can override filesystem
+ * operations without `mock.module` (which leaks across files in Bun's
+ * shared test-runner process).
+ *
+ * State lives exclusively under `.swarm/` (Invariant 4). No `process.cwd()`
+ * usage — every function accepts an explicit `directory` parameter.
+ *
+ * No `bun:` imports — this module is Node-ESM-loadable (Invariant 2).
+ *
+ * See issue #1104, FR-007.
+ */
+import * as fs from 'node:fs';
+/**
+ * A single telemetry record for one capsule delegation.
+ * Written as one JSON line to `.swarm/context-telemetry.jsonl`.
+ */
+export interface TelemetryEntry {
+    /** ISO 8601 timestamp of when the telemetry was recorded */
+    timestamp: string;
+    /** Task ID the capsule was generated for (e.g. "1.1", "2.3") */
+    task_id: string;
+    /** Agent role that received the capsule */
+    agent_role: string;
+    /** Why the capsule was generated */
+    delegation_reason: string;
+    /** Estimated token count of the capsule content */
+    token_estimate: number;
+    /** Number of entries reused from the context map cache */
+    cache_hits: number;
+    /** Number of entries that required fresh computation */
+    cache_misses: number;
+    /** Number of stale entries detected during generation */
+    stale_entries: number;
+    /** Number of files the agent should read directly */
+    recommended_reads: number;
+    /** Number of files whose summaries were sufficient */
+    skipped_reads: number;
+    /** Whether capsule generation succeeded */
+    success: boolean;
+}
+/**
+ * Aggregate statistics computed from all telemetry entries.
+ * Returned by {@link getTelemetrySummary}.
+ */
+export interface TelemetrySummary {
+    /** Total number of capsule delegations recorded */
+    total_delegations: number;
+    /** Sum of all cache hits across entries */
+    total_cache_hits: number;
+    /** Sum of all cache misses across entries */
+    total_cache_misses: number;
+    /** Sum of all stale entries detected across entries */
+    total_stale_entries: number;
+    /** Average estimated token count across entries */
+    avg_token_estimate: number;
+    /** Sum of all recommended reads across entries */
+    total_recommended_reads: number;
+    /** Sum of all skipped reads across entries */
+    total_skipped_reads: number;
+    /** Percentage of successful capsule generations (0–100) */
+    success_rate: number;
+}
+/**
+ * Test-only dependency-injection seam. Production code calls through this
+ * object so tests can replace the underlying implementations without
+ * `mock.module` (which leaks across files in Bun's shared test-runner process).
+ * Mutating this local object is file-scoped and trivially restorable
+ * via `afterEach`.
+ */
+export declare const _internals: {
+    readonly appendFileSync: typeof fs.appendFileSync;
+    readonly readFileSync: typeof fs.readFileSync;
+    readonly existsSync: typeof fs.existsSync;
+    readonly mkdirSync: typeof fs.mkdirSync;
+};
+/**
+ * Append a telemetry entry to `.swarm/context-telemetry.jsonl`.
+ *
+ * Creates the `.swarm/` directory if it does not exist. The entry is
+ * serialized as a single JSON line and appended to the file.
+ *
+ * Returns `true` on success, `false` on any error. Never throws.
+ *
+ * @param entry - The telemetry record to append
+ * @param directory - Project root directory (must contain `.swarm/`)
+ */
+export declare function recordTelemetry(entry: TelemetryEntry, directory: string): boolean;
+/**
+ * Read all telemetry entries from `.swarm/context-telemetry.jsonl`.
+ *
+ * Parses each line as JSON and returns the array of valid entries.
+ * Malformed lines are silently skipped. Returns an empty array if the
+ * file does not exist. Never throws.
+ *
+ * @param directory - Project root directory
+ * @returns Array of parsed telemetry entries (empty if none or on error)
+ */
+export declare function readTelemetry(directory: string): TelemetryEntry[];
+/**
+ * Compute aggregate statistics from all telemetry entries.
+ *
+ * Reads all entries via {@link readTelemetry}, then computes totals
+ * and averages across the dataset.
+ *
+ * Returns a summary with zeroed fields if no entries exist or on error.
+ * Never throws.
+ *
+ * @param directory - Project root directory
+ * @returns Aggregate telemetry summary
+ */
+export declare function getTelemetrySummary(directory: string): TelemetrySummary;

package/dist/council/types.d.ts

@@ -21,6 +21,8 @@ export interface CouncilFinding {
 export interface CouncilMemberVerdict {
     agent: CouncilAgent;
     verdict: CouncilVerdict;
+    /** Optional source round for freshness checks on resubmission. */
+    verdictRound?: number;
     /** Confidence 0.0–1.0 */
     confidence: number;
     findings: CouncilFinding[];

package/dist/hooks/context-capsule-inject.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Context Capsule Injection Hook
+ *
+ * Intercepts architect-to-agent delegations and injects a role-specific
+ * Context Capsule into the delegated agent's system message. The capsule
+ * provides file summaries, read policies, and task context so the agent
+ * can begin work with focused, relevant context.
+ *
+ * This hook is part of the Context Map feature (issue #1104, FR-005).
+ * It is **opt-in** — disabled by default. Enable via config:
+ *
+ *   context_map: { enabled: true }
+ *
+ * Uses the `_internals` DI seam pattern so tests can override external
+ * dependencies without `mock.module` (which leaks across files in Bun's
+ * shared test-runner process).
+ *
+ * All functions accept an explicit `directory` parameter (Invariant 4).
+ * Uses injected directory parameter instead of cwd. Never throws — wraps everything in try/catch.
+ * No `bun:` imports — Node-ESM-loadable (Invariant 2).
+ */
+import type { PluginConfig } from '../config/index.js';
+import { buildCapsule } from '../context-map/capsule-builder.js';
+import { saveCapsule } from '../context-map/capsule-persistence.js';
+import { recordTelemetry } from '../context-map/telemetry.js';
+import type { AgentSessionState } from '../state.js';
+import type { CapsuleDelegationReason } from '../types/context-capsule.js';
+/**
+ * Map session state to a CapsuleDelegationReason.
+ *
+ * Infers the delegation reason from the agent role and task workflow state.
+ * Uses `taskWorkflowStates` to detect whether this is a re-delegation after
+ * a reviewer rejection or test failure. Falls back to 'new_task' for
+ * initial delegations where the task is still at 'idle' or 'coder_delegated'.
+ *
+ * Note: `lastDelegationReason` is not used because the delegation tracker
+ * overwrites it to 'normal_delegation' before this hook runs.
+ * `lastGateFailure` is not used because it tracks automated tool failures,
+ * not agent rejection — its tool name is always the automated tool (diff,
+ * lint, pre_check_batch), never 'reviewer' or 'test_engineer'.
+ */
+declare function resolveCapsuleDelegationReason(session: AgentSessionState | undefined, agentRole: string, taskId: string): CapsuleDelegationReason;
+/**
+ * Extract the task description (goal) from plan.json for a given task ID.
+ *
+ * Reads `.swarm/plan.json` synchronously and searches the phases[].tasks[]
+ * array for a matching task ID. Returns the task description, or '' if not
+ * found or on any error. Never throws.
+ */
+declare function extractTaskGoal(taskId: string, directory: string): string;
+/**
+ * Test-only dependency-injection seam. Production code calls through this
+ * object so tests can replace the underlying implementations without
+ * `mock.module`. Mutating this object is file-scoped and trivially
+ * restorable via `afterEach`.
+ */
+export declare const _internals: {
+    buildCapsule: typeof buildCapsule;
+    recordTelemetry: typeof recordTelemetry;
+    saveCapsule: typeof saveCapsule;
+    getActiveAgent: (sessionID: string) => string | undefined;
+    getSession: (sessionID: string) => AgentSessionState | undefined;
+    getCurrentTaskId: (sessionID: string) => string | null;
+    readScopeFile: (taskId: string, dir: string) => string[];
+    resolveCapsuleDelegationReason: typeof resolveCapsuleDelegationReason;
+    extractTaskGoal: typeof extractTaskGoal;
+};
+/**
+ * Creates the context capsule injection hook.
+ *
+ * When `context_map.enabled === true`, this hook intercepts system message
+ * transforms for delegated agent sessions and injects a role-specific
+ * Context Capsule containing file summaries and read policies.
+ *
+ * When disabled (the default), returns an empty hook object — zero overhead.
+ */
+export declare function createContextCapsuleInjectHook(config: PluginConfig, directory: string): Record<string, unknown>;
+export {};

package/dist/hooks/index.d.ts

@@ -2,6 +2,7 @@ export { createAgentActivityHooks } from './agent-activity';
 export { createCcCommandInterceptHook } from './cc-command-intercept';
 export { createCompactionCustomizerHook } from './compaction-customizer';
 export { createContextBudgetHandler } from './context-budget';
+export { createContextCapsuleInjectHook } from './context-capsule-inject';
 export { createCuratorLLMDelegate } from './curator-llm-factory';
 export { createDelegationGateHook } from './delegation-gate';
 export { createDelegationSanitizerHook } from './delegation-sanitizer';