@webpresso/agent-kit 3.1.26 → 3.1.30

package/dist/esm/cli/commands/dash/plan-once-membership.js

@@ -0,0 +1,151 @@
+/**
+ * Durable plan-once membership (expected host set for a planId).
+ *
+ * Labels alone are not N-of-N SSOT: a host that never creates a run disappears
+ * from registry-only views. Membership is written on confirm (not cancel) and
+ * is a plan-record sidecar — not a second run-registry.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { planOnceRunLabel } from "#cli/commands/dash/plan-once-label.js";
+import { planOnceHostSchema, } from "#cli/commands/dash/plan-once-schema.js";
+import { getSurfacePathAsync, withLock } from "#paths/state-root.js";
+import { writeJsonFileAtomic } from "#shared-utils/write-json-file.js";
+export const PLAN_MEMBERSHIP_SCHEMA_VERSION = 1;
+const MEMBERSHIP_SURFACE = "dash/plan-once-memberships.json";
+export const planMembershipHostSchema = z
+    .object({
+    host: planOnceHostSchema,
+    workdir: z.string().min(1),
+    /** Expected run label: plan-once:<planId>:<label|host> */
+    label: z.string().min(1),
+})
+    .strict();
+export const planMembershipSchema = z
+    .object({
+    schemaVersion: z.literal(PLAN_MEMBERSHIP_SCHEMA_VERSION),
+    planId: z.string().uuid(),
+    hosts: z.array(planMembershipHostSchema).min(1),
+    confirmedAt: z.string().datetime(),
+})
+    .strict();
+export const planMembershipStoreSchema = z
+    .object({
+    version: z.literal(1),
+    plans: z.record(z.string(), planMembershipSchema),
+})
+    .strict();
+function emptyStore() {
+    return { version: 1, plans: {} };
+}
+/** Pure: build immutable membership from a confirmed multi-host plan. */
+export function buildPlanMembership(plan, confirmedAt = new Date().toISOString()) {
+    const hosts = plan.hosts.map((entry) => ({
+        host: entry.host,
+        workdir: entry.workdir,
+        label: planOnceRunLabel(plan.planId, entry),
+    }));
+    return planMembershipSchema.parse({
+        schemaVersion: PLAN_MEMBERSHIP_SCHEMA_VERSION,
+        planId: plan.planId,
+        hosts,
+        confirmedAt,
+    });
+}
+async function membershipPath(cwd) {
+    return getSurfacePathAsync(MEMBERSHIP_SURFACE, "repo", cwd);
+}
+function corruptCopyPath(path) {
+    return `${path}.corrupt-${new Date().toISOString().replaceAll(":", "-")}-${randomUUID()}`;
+}
+function preserveStore(path) {
+    if (!existsSync(path))
+        return undefined;
+    const preservedPath = corruptCopyPath(path);
+    try {
+        copyFileSync(path, preservedPath);
+        return preservedPath;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read membership store. Missing file → empty (ok).
+ * Corrupt/unreadable file → ok:false with quarantine path; never treat as empty
+ * for write merge (would wipe sibling plan memberships).
+ */
+function readStoreFromPath(path) {
+    if (!existsSync(path))
+        return { ok: true, store: emptyStore() };
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        const parsed = planMembershipStoreSchema.safeParse(raw);
+        if (parsed.success)
+            return { ok: true, store: parsed.data };
+        const preservedPath = preserveStore(path);
+        return {
+            ok: false,
+            reason: "plan membership store failed schema validation",
+            ...(preservedPath ? { preservedPath } : {}),
+        };
+    }
+    catch (error) {
+        const preservedPath = preserveStore(path);
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : "plan membership store unreadable",
+            ...(preservedPath ? { preservedPath } : {}),
+        };
+    }
+}
+function storeForRead(path) {
+    const read = readStoreFromPath(path);
+    // Projection reads fail closed to empty (no memberships) without wiping disk.
+    return read.ok ? read.store : emptyStore();
+}
+/** Persist membership for a planId (idempotent overwrite for same planId). */
+export async function writePlanMembership(membership, options = {}) {
+    const validated = planMembershipSchema.parse(membership);
+    const path = await membershipPath(options.cwd);
+    return withLock("repo", () => {
+        const read = readStoreFromPath(path);
+        if (!read.ok) {
+            const preserved = read.preservedPath ? ` (preserved ${read.preservedPath})` : "";
+            throw new Error(`Refusing to write plan membership: store corrupt — ${read.reason}${preserved}`);
+        }
+        const next = {
+            version: 1,
+            plans: { ...read.store.plans, [validated.planId]: validated },
+        };
+        mkdirSync(dirname(path), { recursive: true });
+        writeJsonFileAtomic(path, planMembershipStoreSchema.parse(next));
+        return validated;
+    }, options.cwd);
+}
+/** Read membership for planId, or null if absent. */
+export async function readPlanMembership(planId, options = {}) {
+    const path = await membershipPath(options.cwd);
+    return withLock("repo", () => {
+        const store = storeForRead(path);
+        return store.plans[planId] ?? null;
+    }, options.cwd);
+}
+/** List all durable plan memberships (operator / merge projection scan). */
+export async function listPlanMemberships(options = {}) {
+    const path = await membershipPath(options.cwd);
+    return withLock("repo", () => {
+        const store = storeForRead(path);
+        return Object.values(store.plans);
+    }, options.cwd);
+}
+/** Test helper: clear membership store file content via rewrite empty. */
+export async function clearPlanMembershipStoreForTests(options) {
+    const path = await membershipPath(options.cwd);
+    await withLock("repo", () => {
+        mkdirSync(dirname(path), { recursive: true });
+        writeJsonFileAtomic(path, emptyStore());
+    }, options.cwd);
+}

package/dist/esm/cli/commands/dash/plan-once-merge.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Merge-set projection: membership (expected hosts) + registry runs → rollup.
+ * Pure given membership + run observations — no second run store.
+ *
+ * Operator surface: summary + per-host matrix only. Git/PR auto-merge is out of
+ * scope (no silent git merge of host work).
+ */
+import { z } from "zod";
+import { type FanOutAttentionProjection } from "#cli/commands/dash/plan-once-attention.js";
+import { type PlanMembership } from "#cli/commands/dash/plan-once-membership.js";
+export declare const MERGE_ROLLUPS: readonly ["all-ok", "partial", "all-failed", "incomplete"];
+export type MergeRollup = (typeof MERGE_ROLLUPS)[number];
+/** Rollups that should occupy the attention strip (all-ok does not). */
+export declare const MERGE_ATTENTION_ROLLUPS: readonly ["incomplete", "partial", "all-failed"];
+export declare const mergeRollupSchema: z.ZodEnum<{
+    "all-failed": "all-failed";
+    "all-ok": "all-ok";
+    incomplete: "incomplete";
+    partial: "partial";
+}>;
+export declare const mergeHostStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    missing: "missing";
+    ok: "ok";
+    unknown: "unknown";
+}>;
+export declare const mergeHostObservationSchema: z.ZodObject<{
+    host: z.ZodString;
+    workdir: z.ZodString;
+    expectedLabel: z.ZodString;
+    runId: z.ZodNullable<z.ZodString>;
+    state: z.ZodNullable<z.ZodString>;
+    error: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        failed: "failed";
+        missing: "missing";
+        ok: "ok";
+        unknown: "unknown";
+    }>;
+}, z.core.$strict>;
+export type MergeHostObservation = z.infer<typeof mergeHostObservationSchema>;
+export type MergeSetProjection = {
+    readonly planId: string;
+    readonly expectedCount: number;
+    readonly observedCount: number;
+    readonly missingCount: number;
+    readonly failedCount: number;
+    readonly okCount: number;
+    readonly rollup: MergeRollup;
+    readonly hosts: readonly MergeHostObservation[];
+    readonly attention: FanOutAttentionProjection;
+};
+/** Serializable subset of merge projection (attention omitted). */
+export declare const mergeSetCoreSchema: z.ZodObject<{
+    planId: z.ZodString;
+    expectedCount: z.ZodNumber;
+    observedCount: z.ZodNumber;
+    missingCount: z.ZodNumber;
+    failedCount: z.ZodNumber;
+    okCount: z.ZodNumber;
+    rollup: z.ZodEnum<{
+        "all-failed": "all-failed";
+        "all-ok": "all-ok";
+        incomplete: "incomplete";
+        partial: "partial";
+    }>;
+    hosts: z.ZodArray<z.ZodObject<{
+        host: z.ZodString;
+        workdir: z.ZodString;
+        expectedLabel: z.ZodString;
+        runId: z.ZodNullable<z.ZodString>;
+        state: z.ZodNullable<z.ZodString>;
+        error: z.ZodNullable<z.ZodString>;
+        status: z.ZodEnum<{
+            failed: "failed";
+            missing: "missing";
+            ok: "ok";
+            unknown: "unknown";
+        }>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type MergeRunRow = {
+    readonly id: string;
+    readonly provider: string;
+    readonly state: string;
+    readonly error?: string | null;
+    readonly label?: string | null;
+    /** ISO timestamp when present — used to prefer newest re-apply label match. */
+    readonly updatedAt?: string | null;
+};
+/**
+ * Project merge set from durable membership + registry-visible runs.
+ * Missing expected host → incomplete (never all-ok).
+ */
+export declare function projectMergeSet(input: {
+    readonly membership: PlanMembership;
+    readonly runs: readonly MergeRunRow[];
+    readonly now?: string;
+}): MergeSetProjection;
+export type ProjectMergeSetForPlanResult = {
+    readonly ok: true;
+    readonly projection: MergeSetProjection;
+} | {
+    readonly ok: false;
+    readonly error: "membership-missing";
+    readonly planId: string;
+};
+/**
+ * planId → load durable membership + readDashRuns → merge projection.
+ * Uses run-registry only (no second run store). Missing membership fails closed.
+ * Includes archived runs so archived hosts do not look missing after cleanup.
+ */
+export declare function projectMergeSetForPlan(planId: string, options?: {
+    readonly cwd?: string;
+    readonly now?: string;
+}): Promise<ProjectMergeSetForPlanResult>;
+/** Project merge sets for every durable membership under the state root. */
+export declare function projectAllMergeSets(options?: {
+    readonly cwd?: string;
+    readonly now?: string;
+}): Promise<readonly MergeSetProjection[]>;
+/** One-line operator rollup for HUD/attention strip. */
+export declare function formatMergeSetSummary(projection: MergeSetProjection): string;
+/** Per-host matrix lines for operator surface. */
+export declare function formatMergeSetMatrix(projection: MergeSetProjection): readonly string[];
+export type MergeOperatorSurface = {
+    readonly summary: string;
+    readonly matrix: readonly string[];
+    /**
+     * Explicit scope boundary: this surface is status/summary only.
+     * Silent git/PR auto-merge of host worktrees remains out of scope.
+     */
+    readonly scopeNote: string;
+};
+/** Operator-visible merge surface (HUD/browser). No silent git merge. */
+export declare function formatMergeOperatorSurface(projection: MergeSetProjection): MergeOperatorSurface;
+/** Pick the highest-severity merge projection for a single attention line. */
+export declare function pickPrimaryMergeProjection(projections: readonly MergeSetProjection[]): MergeSetProjection | null;
+/**
+ * Attention-strip line for the worst non-ok merge set.
+ * all-ok is omitted so generic per-run attention remains visible.
+ */
+export declare function formatPrimaryMergeAttentionLine(projections: readonly MergeSetProjection[]): string | null;

package/dist/esm/cli/commands/dash/plan-once-merge.js

@@ -0,0 +1,238 @@
+/**
+ * Merge-set projection: membership (expected hosts) + registry runs → rollup.
+ * Pure given membership + run observations — no second run store.
+ *
+ * Operator surface: summary + per-host matrix only. Git/PR auto-merge is out of
+ * scope (no silent git merge of host work).
+ */
+import { z } from "zod";
+import { projectFanOutAttention, } from "#cli/commands/dash/plan-once-attention.js";
+import { readPlanMembership, listPlanMemberships, } from "#cli/commands/dash/plan-once-membership.js";
+import { readDashRuns } from "#cli/commands/dash/run-registry.js";
+export const MERGE_ROLLUPS = ["all-ok", "partial", "all-failed", "incomplete"];
+/** Rollups that should occupy the attention strip (all-ok does not). */
+export const MERGE_ATTENTION_ROLLUPS = ["incomplete", "partial", "all-failed"];
+export const mergeRollupSchema = z.enum(MERGE_ROLLUPS);
+export const mergeHostStatusSchema = z.enum(["ok", "failed", "missing", "unknown"]);
+export const mergeHostObservationSchema = z
+    .object({
+    host: z.string().min(1),
+    workdir: z.string().min(1),
+    expectedLabel: z.string().min(1),
+    runId: z.string().nullable(),
+    state: z.string().nullable(),
+    error: z.string().nullable(),
+    status: mergeHostStatusSchema,
+})
+    .strict();
+/** Serializable subset of merge projection (attention omitted). */
+export const mergeSetCoreSchema = z
+    .object({
+    planId: z.string().uuid(),
+    expectedCount: z.number().int().nonnegative(),
+    observedCount: z.number().int().nonnegative(),
+    missingCount: z.number().int().nonnegative(),
+    failedCount: z.number().int().nonnegative(),
+    okCount: z.number().int().nonnegative(),
+    rollup: mergeRollupSchema,
+    hosts: z.array(mergeHostObservationSchema),
+})
+    .strict();
+function matchRun(expected, runs) {
+    // Exact label only — substring/prefix matching can join the wrong host when
+    // labels share prefixes and would undercount missing hosts as observed.
+    const matches = runs.filter((r) => r.label === expected.label);
+    if (matches.length === 0)
+        return undefined;
+    if (matches.length === 1)
+        return matches[0];
+    // Prefer newest when re-apply leaves multiple rows with the same label.
+    return matches.reduce((best, row) => {
+        const bestTs = best.updatedAt ?? "";
+        const rowTs = row.updatedAt ?? "";
+        return rowTs >= bestTs ? row : best;
+    });
+}
+function hostStatus(run) {
+    if (!run)
+        return "missing";
+    const state = run.state.toLowerCase();
+    if (state === "failed" || state === "error")
+        return "failed";
+    if (state === "unknown" || state === "stale")
+        return "unknown";
+    if (state === "running" ||
+        state === "starting" ||
+        state === "completed" ||
+        state === "idle" ||
+        state === "waiting" ||
+        state === "detached" ||
+        state === "stopped" ||
+        state === "archived") {
+        return "ok";
+    }
+    // Unrecognized durable state: fail-closed as unknown (not green)
+    return "unknown";
+}
+/**
+ * Project merge set from durable membership + registry-visible runs.
+ * Missing expected host → incomplete (never all-ok).
+ */
+export function projectMergeSet(input) {
+    const hosts = input.membership.hosts.map((expected) => {
+        const run = matchRun(expected, input.runs);
+        const status = hostStatus(run);
+        return {
+            host: expected.host,
+            workdir: expected.workdir,
+            expectedLabel: expected.label,
+            runId: run?.id ?? null,
+            state: run?.state ?? null,
+            error: run?.error ?? null,
+            status,
+        };
+    });
+    const missingCount = hosts.filter((h) => h.status === "missing").length;
+    const failedCount = hosts.filter((h) => h.status === "failed" || h.status === "unknown").length;
+    const okCount = hosts.filter((h) => h.status === "ok").length;
+    const observedCount = hosts.filter((h) => h.runId !== null).length;
+    let rollup;
+    if (missingCount > 0) {
+        rollup = "incomplete";
+    }
+    else if (failedCount === hosts.length && hosts.length > 0) {
+        rollup = "all-failed";
+    }
+    else if (failedCount > 0) {
+        rollup = "partial";
+    }
+    else {
+        rollup = "all-ok";
+    }
+    const attentionRuns = hosts
+        .filter((h) => h.runId)
+        .map((h) => ({
+        runId: h.runId,
+        provider: h.host,
+        state: h.state ?? "unknown",
+        error: h.error,
+    }));
+    const attention = projectFanOutAttention({
+        planId: input.membership.planId,
+        runs: attentionRuns,
+        now: input.now,
+    });
+    return {
+        planId: input.membership.planId,
+        expectedCount: hosts.length,
+        observedCount,
+        missingCount,
+        failedCount,
+        okCount,
+        rollup,
+        hosts,
+        attention,
+    };
+}
+function toMergeRunRows(runs) {
+    return runs.map((r) => ({
+        id: r.id,
+        provider: r.provider,
+        state: r.state,
+        error: r.error,
+        label: r.label,
+        updatedAt: r.updatedAt,
+    }));
+}
+/**
+ * planId → load durable membership + readDashRuns → merge projection.
+ * Uses run-registry only (no second run store). Missing membership fails closed.
+ * Includes archived runs so archived hosts do not look missing after cleanup.
+ */
+export async function projectMergeSetForPlan(planId, options = {}) {
+    const membership = await readPlanMembership(planId, { cwd: options.cwd });
+    if (!membership) {
+        return { ok: false, error: "membership-missing", planId };
+    }
+    const { runs } = await readDashRuns({ cwd: options.cwd, includeArchived: true });
+    const projection = projectMergeSet({
+        membership,
+        runs: toMergeRunRows(runs),
+        now: options.now,
+    });
+    return { ok: true, projection };
+}
+/** Project merge sets for every durable membership under the state root. */
+export async function projectAllMergeSets(options = {}) {
+    const memberships = await listPlanMemberships({ cwd: options.cwd });
+    if (memberships.length === 0)
+        return [];
+    // includeArchived: archived plan-once hosts are still N-of-N observations.
+    const { runs } = await readDashRuns({ cwd: options.cwd, includeArchived: true });
+    const rows = toMergeRunRows(runs);
+    return memberships.map((membership) => projectMergeSet({ membership, runs: rows, now: options.now }));
+}
+/** One-line operator rollup for HUD/attention strip. */
+export function formatMergeSetSummary(projection) {
+    const short = projection.planId.slice(0, 8);
+    const base = `merge ${short} · ${projection.rollup} · ${projection.okCount}/${projection.expectedCount} ok`;
+    // "all-ok" means every expected host is observed and non-failed — not that
+    // every host is terminal (running/starting still map to ok for N-of-N).
+    if (projection.rollup === "all-ok")
+        return `${base} · all observed · none failed`;
+    if (projection.missingCount > 0) {
+        const missing = projection.hosts
+            .filter((h) => h.status === "missing")
+            .map((h) => h.host)
+            .join(",");
+        return `${base} · missing ${missing}`;
+    }
+    if (projection.failedCount > 0) {
+        const failed = projection.hosts
+            .filter((h) => h.status === "failed" || h.status === "unknown")
+            .map((h) => `${h.host}:${h.error ?? h.state ?? h.status}`)
+            .join("; ");
+        return `${base} · ${failed}`;
+    }
+    return base;
+}
+/** Per-host matrix lines for operator surface. */
+export function formatMergeSetMatrix(projection) {
+    return projection.hosts.map((h) => {
+        const state = h.state ?? "—";
+        const err = h.error ? ` · ${h.error}` : "";
+        return `${h.host} · ${h.status} · ${state}${err}`;
+    });
+}
+/** Operator-visible merge surface (HUD/browser). No silent git merge. */
+export function formatMergeOperatorSurface(projection) {
+    return {
+        summary: formatMergeSetSummary(projection),
+        matrix: formatMergeSetMatrix(projection),
+        scopeNote: "git/PR auto-merge out of scope — status/summary only",
+    };
+}
+const ROLLUP_SEVERITY = {
+    incomplete: 4,
+    "all-failed": 3,
+    partial: 2,
+    "all-ok": 1,
+};
+/** Pick the highest-severity merge projection for a single attention line. */
+export function pickPrimaryMergeProjection(projections) {
+    if (projections.length === 0)
+        return null;
+    return [...projections].sort((a, b) => ROLLUP_SEVERITY[b.rollup] - ROLLUP_SEVERITY[a.rollup])[0];
+}
+/**
+ * Attention-strip line for the worst non-ok merge set.
+ * all-ok is omitted so generic per-run attention remains visible.
+ */
+export function formatPrimaryMergeAttentionLine(projections) {
+    const primary = pickPrimaryMergeProjection(projections);
+    if (!primary)
+        return null;
+    if (primary.rollup === "all-ok")
+        return null;
+    return formatMergeSetSummary(primary);
+}

package/dist/esm/cli/commands/dash/plan-once-schema.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { type DashProvider } from "#cli/commands/dash/provider-capabilities.js";
+/** Bump only with a coordinated migration; validators reject unknown versions. */
+export declare const PLAN_ONCE_SCHEMA_VERSION: 1;
+/** Agent hosts only — never fleet (fleet is a registry-derived provider, not a launch host). */
+export declare const PLAN_ONCE_HOSTS: readonly ["claude", "codex", "grok", "opencode"];
+export type PlanOnceHost = DashProvider;
+export declare const planOnceHostSchema: z.ZodEnum<{
+    claude: "claude";
+    codex: "codex";
+    grok: "grok";
+    opencode: "opencode";
+}>;
+export declare const planOnceHostEntrySchema: z.ZodObject<{
+    host: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        grok: "grok";
+        opencode: "opencode";
+    }>;
+    workdir: z.ZodString;
+    brief: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type PlanOnceHostEntry = z.infer<typeof planOnceHostEntrySchema>;
+export declare const multiHostPlanProposalSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    planId: z.ZodString;
+    hosts: z.ZodArray<z.ZodObject<{
+        host: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            grok: "grok";
+            opencode: "opencode";
+        }>;
+        workdir: z.ZodString;
+        brief: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        extraArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    proposedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type MultiHostPlanProposal = z.infer<typeof multiHostPlanProposalSchema>;
+export declare const planOnceDecisionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"confirm">;
+    planId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"cancel">;
+    planId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type PlanOnceDecision = z.infer<typeof planOnceDecisionSchema>;
+export type PlanOnceValidationIssue = {
+    readonly code: "schema" | "bad-schema-version" | "empty-hosts" | "unknown-host" | "bad-workdir" | "plan-id";
+    readonly message: string;
+    readonly path?: string;
+};
+export type PlanOnceParseResult = {
+    readonly ok: true;
+    readonly plan: MultiHostPlanProposal;
+} | {
+    readonly ok: false;
+    readonly issues: readonly PlanOnceValidationIssue[];
+};
+/** Parse + structural validate an untrusted plan proposal. */
+export declare function parseMultiHostPlanProposal(input: unknown): PlanOnceParseResult;
+export declare function parsePlanOnceDecision(input: unknown): {
+    readonly ok: true;
+    readonly decision: PlanOnceDecision;
+} | {
+    readonly ok: false;
+    readonly issues: readonly PlanOnceValidationIssue[];
+};