@gempack/squad-mcp 0.8.2 → 0.10.1

package/dist/runs/store.d.ts

@@ -0,0 +1,328 @@
+import { z } from "zod";
+/**
+ * SQUAD RUNS STORE — telemetry journal for skill invocations. As of v0.10.0
+ * the legitimate writers are the squad skill (`/squad:implement` and
+ * `/squad:review`, invocations `implement | review | task`) and the debug
+ * skill (`/squad:debug`, invocation `debug`). Each writer follows the same
+ * two-phase contract: one row at start (`in_flight`) and one at end
+ * (`completed | aborted`), paired by id. Mirrored line-for-line after
+ * `src/learning/store.ts` — same lock + quarantine + mtime cache + atomic-
+ * append-under-PIPE_BUF discipline.
+ *
+ * Plan v4 (cycle 2 advisory consensus) explicit decisions:
+ *
+ *  - NO multi-row partial fallback. If `JSON.stringify(record)` exceeds
+ *    MAX_RECORD_BYTES the store rejects with `RECORD_TOO_LARGE` rather
+ *    than splitting into continuation rows. Five advisors converged on
+ *    "splitting erodes the one-row-per-record JSONL invariant and
+ *    reopens parsing ambiguities"; rejection puts the burden on the
+ *    caller to cap their `mode_warning.message` (already capped 512B)
+ *    or shorten their inputs.
+ *
+ *  - File mode 0o600 (user-only), directory mode 0o700. The journal
+ *    contains commit refs and prompt-length signals that can leak
+ *    business context (branch names like `feat/acme-acquisition`); on
+ *    shared workstations world-readable 0o644 would expose them to
+ *    co-tenants.
+ *
+ *  - Single-writer contract: the squad skill (`skills/squad/SKILL.md`)
+ *    AND the debug skill (`skills/debug/SKILL.md`) are the only legitimate
+ *    callers of `appendRun`. `apply_consolidation_rules` and other server-
+ *    side code MUST NOT emit terminal rows; doing so breaks the two-phase
+ *    `(in_flight, completed)` pair-by-id invariant.
+ */
+/**
+ * Hard cap per JSONL entry so a single line fits in POSIX PIPE_BUF
+ * (4096 bytes) and `fs.appendFile` remains atomic w.r.t. concurrent
+ * appenders. Length includes serialised JSON + trailing newline.
+ *
+ * Realistic finalization row with 9 agents + capped mode_warning.message
+ * lands around 1.5-2 KB — well under the limit. Oversize is a hard error,
+ * not a soft truncation (see RECORD_TOO_LARGE in errors.ts).
+ */
+export declare const MAX_RECORD_BYTES = 4000;
+/**
+ * Default location for the JSONL file, relative to workspace_root.
+ * Defaults are gitignored at the v0.9.0 release — the journal contains
+ * local-only operational telemetry; users opting into team-wide sharing
+ * remove `.squad/runs.jsonl` from their `.gitignore` deliberately.
+ */
+export declare const DEFAULT_RUNS_PATH = ".squad/runs.jsonl";
+/**
+ * Severity tally compacted into a single sortable number. The cycle-1
+ * design carried `{ Blocker, Major, Minor, Suggestion }` per agent
+ * (~30 bytes / agent of JSON overhead); cycle 2 architects + dev flagged
+ * this as PIPE_BUF-budget waste on 9-agent runs. Collapsed to one number
+ * with positional digits: B*1000 + M*100 + m*10 + s. Inverse decode in
+ * aggregate.ts. Safe up to 9 of each severity per agent (more than that
+ * is itself a signal something went sideways).
+ */
+declare function severityScore(counts: {
+    Blocker: number;
+    Major: number;
+    Minor: number;
+    Suggestion: number;
+}): number;
+/** Inverse of `severityScore`. Used by aggregate.ts. */
+export declare function decodeSeverityScore(n: number): {
+    Blocker: number;
+    Major: number;
+    Minor: number;
+    Suggestion: number;
+};
+/** Public re-export so callers can build records without re-implementing the encoding. */
+export { severityScore };
+/**
+ * Canonical tuple of accepted journal invocations. Single source of truth.
+ *
+ * Why a tuple, not just a Zod enum: the same set is consumed by FIVE call
+ * sites — this store's `InvocationEnum`, the tool boundary at
+ * `src/tools/record-run.ts`, the filter schema at `src/tools/list-runs.ts`,
+ * the Record literal in the aggregate output type, and the `invocation_counts`
+ * initialiser in `src/runs/aggregate.ts`. Exporting one tuple makes "add a
+ * new invocation" a single-line change instead of five-sites-must-stay-in-
+ * sync. Pattern parallels `AGENT_NAMES_TUPLE` in `src/config/ownership-matrix.ts`.
+ *
+ * `as const` (readonly tuple) is what Zod's `z.enum` requires.
+ */
+export declare const INVOCATION_VALUES: readonly ["implement", "review", "task", "question", "brainstorm", "debug"];
+declare const InvocationEnum: z.ZodEnum<["implement", "review", "task", "question", "brainstorm", "debug"]>;
+declare const StatusEnum: z.ZodEnum<["in_flight", "completed", "aborted"]>;
+declare const WorkTypeEnum: z.ZodEnum<["Feature", "Bug Fix", "Refactor", "Performance", "Security", "Business Rule"]>;
+declare const VerdictEnum: z.ZodEnum<["APPROVED", "CHANGES_REQUIRED", "REJECTED"]>;
+declare const GitRefSchema: z.ZodNullable<z.ZodObject<{
+    kind: z.ZodEnum<["head", "diff_base", "pr_head"]>;
+    value: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    kind: "head" | "diff_base" | "pr_head";
+}, {
+    value: string;
+    kind: "head" | "diff_base" | "pr_head";
+}>>;
+/**
+ * Per-agent dispatch metrics captured by the squad skill orchestrator.
+ *
+ *  - `batch_duration_ms` (renamed from `duration_ms` in v0.9.0): wall-clock
+ *    from this agent's Task() dispatch to its result. Note that advisors in
+ *    a parallel batch overlap; this is "round-trip latency for this dispatch"
+ *    not "exclusive time spent on this agent's work". Reflected in the
+ *    /squad:stats output label.
+ *
+ *  - `prompt_chars` / `response_chars` (renamed from input/output_chars in
+ *    v0.9.0): orchestrator-visible character counts of the dispatch prompt
+ *    and the agent's returned string. EXCLUDES the agent's own internal
+ *    tool_use roundtrips (file reads, sub-dispatches like code-explorer).
+ *    For agents that read heavily, the recorded chars are a substantial
+ *    underestimate — documented in `est_tokens_method` and rendered in the
+ *    stats panel disclaimer.
+ *
+ *  - `severity_score`: encoded findings tally (see severityScore()).
+ */
+declare const AgentMetricsSchema: z.ZodObject<{
+    name: z.ZodEnum<[import("../config/ownership-matrix.js").AgentName, ...import("../config/ownership-matrix.js").AgentName[]]>;
+    model: z.ZodEnum<["haiku", "sonnet", "opus", "inherit"]>;
+    score: z.ZodNullable<z.ZodNumber>;
+    severity_score: z.ZodNullable<z.ZodNumber>;
+    batch_duration_ms: z.ZodNumber;
+    prompt_chars: z.ZodNumber;
+    response_chars: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: import("../config/ownership-matrix.js").AgentName;
+    score: number | null;
+    model: "haiku" | "inherit" | "sonnet" | "opus";
+    severity_score: number | null;
+    batch_duration_ms: number;
+    prompt_chars: number;
+    response_chars: number;
+}, {
+    name: import("../config/ownership-matrix.js").AgentName;
+    score: number | null;
+    model: "haiku" | "inherit" | "sonnet" | "opus";
+    severity_score: number | null;
+    batch_duration_ms: number;
+    prompt_chars: number;
+    response_chars: number;
+}>;
+/**
+ * RunRecord schema_version 1. PUBLIC STABLE CONTRACT from v0.9.0 — readers
+ * (the `list_runs` MCP tool, the `/squad:stats` skill) key on
+ * `schema_version` and quarantine unknown versions rather than failing.
+ *
+ * Discriminated by `status`:
+ *  - `in_flight` rows carry only the Phase-1-known fields (skill knows what
+ *    it's about to do; verdict/scores are still pending).
+ *  - `completed | aborted` rows carry full metrics + verdict.
+ *
+ * For ergonomics under Zod we keep finalisation fields optional on the base
+ * schema rather than splitting into two schemas; the writer validates the
+ * appropriate subset at the call site (`appendRun` vs `finalizeRun`).
+ */
+declare const runRecordSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    id: z.ZodEffects<z.ZodString, string, string>;
+    status: z.ZodEnum<["in_flight", "completed", "aborted"]>;
+    started_at: z.ZodEffects<z.ZodString, string, string>;
+    completed_at: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    duration_ms: z.ZodOptional<z.ZodNumber>;
+    invocation: z.ZodEnum<["implement", "review", "task", "question", "brainstorm", "debug"]>;
+    mode: z.ZodEnum<["quick", "normal", "deep"]>;
+    mode_source: z.ZodEnum<["user", "auto"]>;
+    work_type: z.ZodOptional<z.ZodEnum<["Feature", "Bug Fix", "Refactor", "Performance", "Security", "Business Rule"]>>;
+    git_ref: z.ZodNullable<z.ZodObject<{
+        kind: z.ZodEnum<["head", "diff_base", "pr_head"]>;
+        value: z.ZodEffects<z.ZodString, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        kind: "head" | "diff_base" | "pr_head";
+    }, {
+        value: string;
+        kind: "head" | "diff_base" | "pr_head";
+    }>>;
+    files_count: z.ZodNumber;
+    agents: z.ZodArray<z.ZodObject<{
+        name: z.ZodEnum<[import("../config/ownership-matrix.js").AgentName, ...import("../config/ownership-matrix.js").AgentName[]]>;
+        model: z.ZodEnum<["haiku", "sonnet", "opus", "inherit"]>;
+        score: z.ZodNullable<z.ZodNumber>;
+        severity_score: z.ZodNullable<z.ZodNumber>;
+        batch_duration_ms: z.ZodNumber;
+        prompt_chars: z.ZodNumber;
+        response_chars: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        name: import("../config/ownership-matrix.js").AgentName;
+        score: number | null;
+        model: "haiku" | "inherit" | "sonnet" | "opus";
+        severity_score: number | null;
+        batch_duration_ms: number;
+        prompt_chars: number;
+        response_chars: number;
+    }, {
+        name: import("../config/ownership-matrix.js").AgentName;
+        score: number | null;
+        model: "haiku" | "inherit" | "sonnet" | "opus";
+        severity_score: number | null;
+        batch_duration_ms: number;
+        prompt_chars: number;
+        response_chars: number;
+    }>, "many">;
+    verdict: z.ZodOptional<z.ZodNullable<z.ZodEnum<["APPROVED", "CHANGES_REQUIRED", "REJECTED"]>>>;
+    weighted_score: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    est_tokens_method: z.ZodLiteral<"chars-div-3.5">;
+    mode_warning: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        code: z.ZodEffects<z.ZodString, string, string>;
+        message: z.ZodEffects<z.ZodString, string, string>;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+    }, {
+        code: string;
+        message: string;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    files_count: number;
+    status: "aborted" | "in_flight" | "completed";
+    agents: {
+        name: import("../config/ownership-matrix.js").AgentName;
+        score: number | null;
+        model: "haiku" | "inherit" | "sonnet" | "opus";
+        severity_score: number | null;
+        batch_duration_ms: number;
+        prompt_chars: number;
+        response_chars: number;
+    }[];
+    mode: "quick" | "normal" | "deep";
+    id: string;
+    invocation: "debug" | "review" | "task" | "implement" | "question" | "brainstorm";
+    schema_version: 1;
+    started_at: string;
+    mode_source: "user" | "auto";
+    git_ref: {
+        value: string;
+        kind: "head" | "diff_base" | "pr_head";
+    } | null;
+    est_tokens_method: "chars-div-3.5";
+    work_type?: "Feature" | "Bug Fix" | "Refactor" | "Performance" | "Security" | "Business Rule" | undefined;
+    duration_ms?: number | undefined;
+    weighted_score?: number | null | undefined;
+    completed_at?: string | undefined;
+    verdict?: "APPROVED" | "CHANGES_REQUIRED" | "REJECTED" | null | undefined;
+    mode_warning?: {
+        code: string;
+        message: string;
+    } | null | undefined;
+}, {
+    files_count: number;
+    status: "aborted" | "in_flight" | "completed";
+    agents: {
+        name: import("../config/ownership-matrix.js").AgentName;
+        score: number | null;
+        model: "haiku" | "inherit" | "sonnet" | "opus";
+        severity_score: number | null;
+        batch_duration_ms: number;
+        prompt_chars: number;
+        response_chars: number;
+    }[];
+    mode: "quick" | "normal" | "deep";
+    id: string;
+    invocation: "debug" | "review" | "task" | "implement" | "question" | "brainstorm";
+    schema_version: 1;
+    started_at: string;
+    mode_source: "user" | "auto";
+    git_ref: {
+        value: string;
+        kind: "head" | "diff_base" | "pr_head";
+    } | null;
+    est_tokens_method: "chars-div-3.5";
+    work_type?: "Feature" | "Bug Fix" | "Refactor" | "Performance" | "Security" | "Business Rule" | undefined;
+    duration_ms?: number | undefined;
+    weighted_score?: number | null | undefined;
+    completed_at?: string | undefined;
+    verdict?: "APPROVED" | "CHANGES_REQUIRED" | "REJECTED" | null | undefined;
+    mode_warning?: {
+        code: string;
+        message: string;
+    } | null | undefined;
+}>;
+export type RunRecord = z.infer<typeof runRecordSchema>;
+export type AgentMetrics = z.infer<typeof AgentMetricsSchema>;
+export type GitRef = z.infer<typeof GitRefSchema>;
+export type RunStatus = z.infer<typeof StatusEnum>;
+export type RunInvocation = z.infer<typeof InvocationEnum>;
+export type RunVerdict = z.infer<typeof VerdictEnum>;
+export { runRecordSchema, WorkTypeEnum };
+/** Test-only: clear the per-process cache. Production code MUST NOT call this. */
+export declare function __resetRunsStoreCacheForTests(): void;
+/**
+ * Generate a fresh run id. Date.now() base36 prefix + 6 chars from
+ * [a-z0-9] (36^6 = 2.18B unique values per millisecond — collision
+ * chance is effectively zero across realistic concurrent writers in
+ * the same ms).
+ */
+export declare function generateRunId(): string;
+/**
+ * Read all run records from the JSONL file. Returns `[]` if the file does
+ * not exist (fresh repo, first run). Corrupt lines are quarantined to a
+ * timestamped sibling file and logged once; the surviving entries return
+ * in append order.
+ *
+ * Unknown `schema_version` rows are quarantined too — readers must NEVER
+ * silently include rows they don't understand. The quarantine file is
+ * `.squad/runs.jsonl.corrupt-<ts>.jsonl` alongside the source.
+ */
+export declare function readRuns(workspaceRoot: string, options?: {
+    configuredPath?: string;
+}): Promise<RunRecord[]>;
+/**
+ * Append one RunRecord. Validates against Zod, then enforces
+ * MAX_RECORD_BYTES (post-serialisation) before acquiring the file lock.
+ * Oversize records throw `RECORD_TOO_LARGE` — no silent split, no soft
+ * truncation. The caller (the squad skill) is responsible for keeping
+ * `mode_warning.message` capped and the agent list short enough that
+ * realistic records stay well under the cap.
+ */
+export declare function appendRun(workspaceRoot: string, record: RunRecord, options?: {
+    configuredPath?: string;
+}): Promise<{
+    filePath: string;
+    record: RunRecord;
+}>;