blun-king-cli 9.1.567 → 9.1.570

package/agent-spine-plugin/src/lib/gateway-knowledge.js

@@ -0,0 +1,129 @@
+import {
+  createKnowledgeGap, createSelfHelpRequirement, createSelfHelpResolution,
+  pendingSelfHelpRequirement
+} from "./knowledge-evidence.js";
+
+function blockKnowledgeLimit({ goal, step, item, runtime, current, appendReceipt }, kind) {
+  const reason = `Goal step reached the bounded limit of 16 ${kind}; local review is required.`;
+  item.status = "blocked"; item.lastError = reason; item.completedAt = current;
+  step.status = "blocked"; step.blocker = reason; step.updatedAt = current;
+  goal.status = "blocked"; goal.blocker = reason; goal.updatedAt = current;
+  appendReceipt(runtime, "self-help-limit-exhausted", item.queueId, current,
+    { goalStepId: step.stepId, limit: 16, category: kind });
+  return null;
+}
+
+function resolvedSelfHelp({ goal, step, item, runtime, current, request,
+  appendReceipt, newGoalQueue, planQueueKey }) {
+  if (!Array.isArray(step.knowledgeGaps)) step.knowledgeGaps = [];
+  if (!Array.isArray(step.selfHelpReports)) step.selfHelpReports = [];
+  const resolved = createSelfHelpResolution({ goal, step, queueId: item.queueId,
+    report: request, agentId: item.agentId, now: current });
+  const existingGap = step.knowledgeGaps.find((gap) => gap.gapId === resolved.gap.gapId);
+  if (existingGap) {
+    goal.blocker = "The host repeated an already resolved self-help question.";
+    step.status = "blocked"; step.blocker = goal.blocker; goal.status = "blocked";
+    appendReceipt(runtime, "self-help-research-regression", item.queueId, current,
+      { goalStepId: step.stepId, reportId: resolved.report.reportId, gapId: existingGap.gapId });
+    return null;
+  }
+  if (step.knowledgeGaps.length >= 16 || step.selfHelpReports.length >= 16) {
+    return blockKnowledgeLimit({ goal, step, item, runtime, current, appendReceipt },
+      "self-help research resolutions");
+  }
+  step.knowledgeGaps.push(resolved.gap); step.selfHelpReports.push(resolved.report);
+  if (resolved.status === "needs-owner-input") {
+    item.status = "blocked"; step.status = "blocked"; step.blocker = resolved.gap.question;
+    goal.status = "blocked"; goal.blocker = resolved.gap.question;
+    appendReceipt(runtime, "self-help-research-exhausted", item.queueId, current,
+      { goalStepId: step.stepId, reportId: resolved.report.reportId, gapId: resolved.gap.gapId });
+    appendReceipt(runtime, "knowledge-gap-opened", item.queueId, current,
+      { goalStepId: step.stepId, gapId: resolved.gap.gapId, requiredEvidence: "owner-input" });
+    return { clarification: structuredClone(resolved.gap), report: structuredClone(resolved.report) };
+  }
+  step.status = "active"; step.blocker = null; goal.status = "active"; goal.blocker = null;
+  goal.nextSafeStep = step.title;
+  const key = planQueueKey(goal.goalId, step.stepId, "self-help", resolved.report.reportDigest.slice(0, 20));
+  let queued = runtime.queue.find((entry) => entry.dedupeKey === key);
+  if (!queued) { queued = newGoalQueue(goal, step, "follow-up", key, current); runtime.queue.push(queued); }
+  appendReceipt(runtime, "self-help-research-resolved", queued.queueId, current,
+    { goalStepId: step.stepId, reportId: resolved.report.reportId, gapId: resolved.gap.gapId });
+  return { report: structuredClone(resolved.report), queueId: queued.queueId };
+}
+
+function requireSelfHelp({ goal, step, item, runtime, current, request,
+  appendReceipt, newGoalQueue, planQueueKey }) {
+  if (!Array.isArray(step.selfHelpRequirements)) step.selfHelpRequirements = [];
+  const pending = pendingSelfHelpRequirement(step);
+  if (pending) {
+    const same = pending.question === request.question?.trim().replace(/\s+/g, " ")
+      && pending.reason === request.reason?.trim().replace(/\s+/g, " ");
+    goal.blocker = same
+      ? "The host repeated a question before completing required repository-first self-help."
+      : "The host changed an objective question before completing required repository-first self-help.";
+    item.status = "blocked"; step.status = "blocked"; step.blocker = goal.blocker; goal.status = "blocked";
+    appendReceipt(runtime, "self-help-requirement-regression", item.queueId, current,
+      { goalStepId: step.stepId, requirementId: pending.requirementId, repeated: same });
+    return null;
+  }
+  if (step.selfHelpRequirements.length >= 16) {
+    return blockKnowledgeLimit({ goal, step, item, runtime, current, appendReceipt },
+      "self-help requirements");
+  }
+  const requirement = createSelfHelpRequirement(goal, step, item.queueId, request, current);
+  step.selfHelpRequirements.push(requirement); item.status = "completed";
+  step.status = "active"; step.blocker = null; goal.status = "active"; goal.blocker = null;
+  goal.nextSafeStep = step.title;
+  const key = planQueueKey(goal.goalId, step.stepId, "self-help-required",
+    requirement.requirementDigest.slice(0, 20));
+  let queued = runtime.queue.find((entry) => entry.dedupeKey === key);
+  if (!queued) { queued = newGoalQueue(goal, step, "follow-up", key, current); runtime.queue.push(queued); }
+  appendReceipt(runtime, "self-help-required", queued.queueId, current,
+    { goalStepId: step.stepId, requirementId: requirement.requirementId });
+  return { requirement: structuredClone(requirement), queueId: queued.queueId };
+}
+
+function openOwnerGap({ goal, step, item, runtime, current, request, appendReceipt }) {
+  const pending = pendingSelfHelpRequirement(step);
+  if (pending) {
+    goal.blocker = "The host asked the owner before completing required repository-first self-help.";
+    item.status = "blocked"; step.status = "blocked"; step.blocker = goal.blocker; goal.status = "blocked";
+    appendReceipt(runtime, "self-help-requirement-regression", item.queueId, current,
+      { goalStepId: step.stepId, requirementId: pending.requirementId, prematureOwnerQuestion: true });
+    return null;
+  }
+  if (!Array.isArray(step.knowledgeGaps)) step.knowledgeGaps = [];
+  const proposed = createKnowledgeGap(goal, step, item.queueId, request, current);
+  const existing = step.knowledgeGaps.find((gap) => gap.gapId === proposed.gapId);
+  if (!existing && step.knowledgeGaps.length >= 16) {
+    return blockKnowledgeLimit({ goal, step, item, runtime, current, appendReceipt }, "knowledge gaps");
+  }
+  if (existing?.status === "resolved") {
+    goal.blocker = "The host repeated an already resolved knowledge gap.";
+    step.status = "blocked"; step.blocker = goal.blocker; goal.status = "blocked";
+    appendReceipt(runtime, "knowledge-gap-regression", item.queueId, current,
+      { goalStepId: step.stepId, gapId: existing.gapId });
+    return null;
+  }
+  const gap = existing || proposed;
+  if (!existing) step.knowledgeGaps.push(gap);
+  goal.blocker = gap.question; step.status = "blocked"; step.blocker = gap.question; goal.status = "blocked";
+  appendReceipt(runtime, "knowledge-gap-opened", item.queueId, current,
+    { goalStepId: step.stepId, gapId: gap.gapId, requiredEvidence: gap.requiredEvidence });
+  return structuredClone(gap);
+}
+
+export function handlePlanKnowledge(options) {
+  const { goal, step, item, runtime, current, selfHelpRequest, knowledgeGapRequest } = options;
+  if (!selfHelpRequest && !knowledgeGapRequest) return null;
+  let result;
+  if (selfHelpRequest) {
+    const handled = resolvedSelfHelp({ ...options, request: selfHelpRequest });
+    result = handled?.clarification ? handled : { selfHelp: handled };
+  }
+  else if (knowledgeGapRequest.requiredEvidence === "objective-observation") {
+    result = { selfHelpRequired: requireSelfHelp({ ...options, request: knowledgeGapRequest }) };
+  } else result = { clarification: openOwnerGap({ ...options, request: knowledgeGapRequest }) };
+  goal.plan.revision += 1;
+  return result;
+}

package/agent-spine-plugin/src/lib/gateway-policy-provenance.js

@@ -0,0 +1,197 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { replaceFileWithRetry } from "./filesystem-retry.js";
+
+const PROVENANCE_SCHEMA = "agentspine.gateway-policy-provenance/v1";
+const REGISTRY_AUTHORITY = "context-only-contract-provenance";
+const POLICY_SCHEMA = "agentspine.gateway-policy/v2";
+const POLICY_BYTES = 8 * 1024 * 1024;
+const PROVENANCE_BYTES = 8 * 1024;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+const PROVENANCE_FILE_DIGEST = Symbol("gateway-policy-provenance-file-digest");
+export const GOAL_PREMORTEM_CONTRACT = "agentspine.goal-premortem/v1";
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+}
+function sha256(value) {
+  return createHash("sha256").update(typeof value === "string" ? value : canonical(value)).digest("hex");
+}
+function exactKeys(value, keys) {
+  return value && canonical(Object.keys(value).sort()) === canonical([...keys].sort());
+}
+function seal(value) {
+  return { ...value, digest: sha256(value) };
+}
+function validSeal(value) {
+  if (!value || !DIGEST_RE.test(value.digest || "")) return false;
+  const material = { ...value };
+  delete material.digest;
+  return value.digest === sha256(material);
+}
+function policyProvenance(root, policySchema, state, previousPolicyDigest, nextPolicyDigest) {
+  return seal({ schema: PROVENANCE_SCHEMA, projectRootDigest: sha256(root), policySchema,
+    contract: GOAL_PREMORTEM_CONTRACT, state, previousPolicyDigest, nextPolicyDigest,
+    authority: REGISTRY_AUTHORITY });
+}
+
+export function validGatewayPolicyProvenance(value, root, policySchema) {
+  return exactKeys(value, ["schema", "projectRootDigest", "policySchema", "contract", "state",
+    "previousPolicyDigest", "nextPolicyDigest", "authority", "digest"])
+    && value.schema === PROVENANCE_SCHEMA && value.projectRootDigest === sha256(root)
+    && value.policySchema === policySchema && value.contract === GOAL_PREMORTEM_CONTRACT
+    && new Set(["prepared", "committed"]).has(value.state)
+    && (value.previousPolicyDigest === null || DIGEST_RE.test(value.previousPolicyDigest || ""))
+    && DIGEST_RE.test(value.nextPolicyDigest || "")
+    && value.authority === REGISTRY_AUTHORITY && validSeal(value);
+}
+
+async function readPolicyProvenance(path) {
+  const provenancePath = join(dirname(path), "gateway-policy-provenance.json");
+  try {
+    const metadata = await stat(provenancePath);
+    if (metadata.size > PROVENANCE_BYTES) throw new Error("gateway policy provenance exceeds 8 KiB");
+    const text = await readFile(provenancePath, "utf8");
+    if (Buffer.byteLength(text) > PROVENANCE_BYTES) throw new Error("gateway policy provenance exceeds 8 KiB");
+    const value = JSON.parse(text);
+    if (value && typeof value === "object") {
+      Object.defineProperty(value, PROVENANCE_FILE_DIGEST, { value: sha256(text) });
+    }
+    return value;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+}
+async function currentGatewayDigest(path) {
+  try { return sha256(await readFile(path, "utf8")); }
+  catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+async function atomicGatewayWrite(path, content, maximum = POLICY_BYTES, guard = {}) {
+  if (Buffer.byteLength(content) > maximum) throw new Error("gateway state exceeds its byte limit");
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, content, { mode: 0o600 });
+    await replaceFileWithRetry(temporary, path, { beforeAttempt: async () => {
+      await guard.assertOwned?.();
+      if (Object.hasOwn(guard, "expectedDigest")
+        && await currentGatewayDigest(path) !== guard.expectedDigest) {
+        throw new Error("gateway state predecessor changed before atomic replace");
+      }
+      await guard.assertRelated?.();
+      await guard.assertOwned?.();
+    } });
+  } finally {
+    await unlink(temporary).catch((error) => { if (error.code !== "ENOENT") throw error; });
+  }
+}
+async function commitObservedPolicyProvenance(path, root, provenance, match, policyDigest, assertOwned) {
+  if (provenance.state !== "prepared" || typeof assertOwned !== "function") return;
+  const provenancePath = join(dirname(path), "gateway-policy-provenance.json");
+  const priorDigest = match === "next" ? provenance.previousPolicyDigest : provenance.nextPolicyDigest;
+  const committed = policyProvenance(root, provenance.policySchema, "committed", priorDigest, policyDigest);
+  const assertObserved = async () => {
+    if (await currentGatewayDigest(path) !== policyDigest) {
+      throw new Error("gateway policy changed before prepared provenance recovery");
+    }
+  };
+  await atomicGatewayWrite(provenancePath, `${JSON.stringify(committed, null, 2)}\n`, PROVENANCE_BYTES, {
+    assertOwned, assertRelated: assertObserved, expectedDigest: provenance[PROVENANCE_FILE_DIGEST]
+  });
+}
+
+export async function readGatewayJson(path, root, normalize, empty, guard = {}) {
+  const policyFile = basename(path) === "gateway-policy.json";
+  for (let attempt = 0; attempt < (policyFile ? 4 : 1); attempt += 1) {
+    const provenance = policyFile ? await readPolicyProvenance(path) : null;
+    let text;
+    try {
+      const metadata = await stat(path);
+      if (metadata.size > POLICY_BYTES) throw new Error("gateway state exceeds 8 MiB");
+      text = await readFile(path, "utf8");
+      if (Buffer.byteLength(text) > POLICY_BYTES) throw new Error("gateway state exceeds 8 MiB");
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const after = policyFile ? await readPolicyProvenance(path) : null;
+      if (canonical(provenance) !== canonical(after)) continue;
+      if (provenance && (!validGatewayPolicyProvenance(provenance, root, POLICY_SCHEMA)
+        || provenance.state !== "prepared" || provenance.previousPolicyDigest !== null)) {
+        throw new Error("gateway policy is missing while provenance exists");
+      }
+      if (provenance && typeof guard.assertOwned === "function") {
+        const value = normalize(empty(root), root, { record: provenance, match: "previous" });
+        await writeGatewayJson(path, value, { assertOwned: guard.assertOwned,
+          afterWrite: guard.afterWrite, expectedDigest: null });
+        return value;
+      }
+      return empty(root);
+    }
+    const after = policyFile ? await readPolicyProvenance(path) : null;
+    if (canonical(provenance) !== canonical(after)) continue;
+    let anchored = null;
+    if (provenance) {
+      if (!validGatewayPolicyProvenance(provenance, root, POLICY_SCHEMA)) {
+        throw new Error("gateway policy provenance is invalid");
+      }
+      const policyDigest = sha256(text);
+      const match = policyDigest === provenance.nextPolicyDigest ? "next"
+        : policyDigest === provenance.previousPolicyDigest ? "previous" : null;
+      if (!match) throw new Error("gateway policy does not match its persisted provenance");
+      anchored = { record: provenance, match };
+    }
+    const parsed = JSON.parse(text);
+    const legacyPolicy = policyFile && parsed?.schema === "agentspine.gateway-policy/v1";
+    const value = normalize(parsed, root, anchored);
+    if (legacyPolicy && typeof guard.assertOwned === "function") {
+      await writeGatewayJson(path, value, { assertOwned: guard.assertOwned,
+        afterWrite: guard.afterWrite, expectedDigest: sha256(text) });
+      return value;
+    }
+    if (anchored) await commitObservedPolicyProvenance(path, root, provenance,
+      anchored.match, sha256(text), guard.assertOwned);
+    return value;
+  }
+  throw new Error("gateway policy changed during bounded provenance read");
+}
+
+export async function writeGatewayJson(path, value, guard = {}) {
+  const content = `${JSON.stringify(value, null, 2)}\n`;
+  if (basename(path) === "gateway-policy.json" && value.schema === POLICY_SCHEMA) {
+    const provenancePath = join(dirname(path), "gateway-policy-provenance.json");
+    const previousPolicyDigest = await currentGatewayDigest(path);
+    if (Object.hasOwn(guard, "expectedDigest") && previousPolicyDigest !== guard.expectedDigest) {
+      throw new Error("gateway state predecessor changed before policy provenance");
+    }
+    const nextPolicyDigest = sha256(content);
+    const prepared = policyProvenance(value.root, value.schema, "prepared",
+      previousPolicyDigest, nextPolicyDigest);
+    const preparedContent = `${JSON.stringify(prepared, null, 2)}\n`;
+    const previousProvenanceDigest = await currentGatewayDigest(provenancePath);
+    const assertPreviousPolicy = async () => {
+      if (await currentGatewayDigest(path) !== previousPolicyDigest) {
+        throw new Error("gateway state predecessor changed before policy provenance");
+      }
+    };
+    await atomicGatewayWrite(provenancePath, preparedContent, PROVENANCE_BYTES,
+      { assertOwned: guard.assertOwned, assertRelated: assertPreviousPolicy,
+        expectedDigest: previousProvenanceDigest });
+    await atomicGatewayWrite(path, content, POLICY_BYTES, guard);
+    const committed = policyProvenance(value.root, value.schema, "committed",
+      previousPolicyDigest, nextPolicyDigest);
+    const assertNextPolicy = async () => {
+      if (await currentGatewayDigest(path) !== nextPolicyDigest) {
+        throw new Error("gateway policy changed before provenance commit");
+      }
+    };
+    await atomicGatewayWrite(provenancePath, `${JSON.stringify(committed, null, 2)}\n`, PROVENANCE_BYTES,
+      { assertOwned: guard.assertOwned, assertRelated: assertNextPolicy,
+        expectedDigest: sha256(preparedContent) });
+    await guard.afterWrite?.(nextPolicyDigest);
+    return;
+  }
+  await atomicGatewayWrite(path, content, POLICY_BYTES, guard);
+  await guard.afterWrite?.(sha256(content));
+}

package/agent-spine-plugin/src/lib/gateway-premortem-disposition.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { finalizeReadOnlyPremortemForGoal } from "./delivery-premortem.js";
+import { validPremortemScopeFinalization,
+  validPremortemScopeFinalizationContext } from "./delivery-premortem-index.js";
+
+const CHECKPOINT_SCHEMA = "agentspine.goal-delivery-checkpoint/v1";
+const OUTCOME_SCHEMA = "agentspine.goal-outcome-receipt/v1";
+const AUTHORITY = "context-only";
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value).sort().map((key) =>
+    `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+}
+
+function sha256(value) {
+  return createHash("sha256").update(typeof value === "string" ? value : canonical(value)).digest("hex");
+}
+
+function seal(value) {
+  return { ...value, digest: sha256(value) };
+}
+
+export function readOnlyDispositionDigest(expected) {
+  return sha256({ status: "read-only", goalId: expected.goalId,
+    goalStepId: expected.goalStepId, queueId: expected.queueId,
+    gatewayAttempt: expected.gatewayAttempt, planDefinitionsDigest: expected.planDefinitionsDigest,
+    projectRootDigest: sha256(expected.root), host: expected.host, projectId: expected.projectId,
+    entityId: expected.entityId, groupId: expected.groupId, taskId: null, authority: AUTHORITY });
+}
+
+export function dispositionAttachments(status, expected, checkpoint, completedAt,
+  reason = status, finalization = null) {
+  const common = { status, queueId: expected.queueId, gatewayAttempt: expected.gatewayAttempt,
+    goalId: expected.goalId, goalStepId: expected.goalStepId,
+    planDefinitionsDigest: expected.planDefinitionsDigest, projectRootDigest: sha256(expected.root),
+    checkpointDigest: sha256(checkpoint ?? null), host: expected.host,
+    projectId: expected.projectId, entityId: expected.entityId, groupId: expected.groupId,
+    scopeFinalizationDigest: finalization?.digest ?? null, diagnosticDigest: sha256(reason),
+    authority: AUTHORITY };
+  const deliveryCheckpoint = seal({ schema: CHECKPOINT_SCHEMA, ...common });
+  const outcomeReceipt = seal({ schema: OUTCOME_SCHEMA, ...common, completedAt,
+    deliveryCheckpointDigest: deliveryCheckpoint.digest });
+  return { deliveryCheckpoint, outcomeReceipt };
+}
+
+export function finalizedReadOnlyAttachments(expected, checkpoint, completedAt, finalization) {
+  if (!validPremortemScopeFinalizationContext(finalization, expected)
+    || finalization.status !== "read-only"
+    || finalization.attachmentDigest !== readOnlyDispositionDigest(expected)) return null;
+  return dispositionAttachments("read-only", expected, checkpoint, completedAt,
+    "host-confirmed-read-only", finalization);
+}
+
+export function validClosedFinalization(expected, attachment, finalization) {
+  return validPremortemScopeFinalizationContext(finalization, expected)
+    && finalization.status === "closed"
+    && finalization.attachmentDigest === attachment.attachmentDigest;
+}
+
+export async function finalizeReadOnlyReview(expected, checkpoint, completedAt, bindings = []) {
+  const dispositionDigest = readOnlyDispositionDigest(expected);
+  const summaryDigests = bindings.map((binding) => binding.digest);
+  const fenced = await finalizeReadOnlyPremortemForGoal({ root: expected.root,
+    goalId: expected.goalId, goalStepId: expected.goalStepId, queueId: expected.queueId,
+    gatewayAttempt: expected.gatewayAttempt, dispositionDigest, context: expected,
+    bindingSummaryDigests: summaryDigests });
+  if (!fenced || fenced.status === "degraded") return { status: "degraded", blocked: false,
+    attachments: dispositionAttachments("degraded-fail-open", expected, checkpoint,
+      completedAt, fenced?.reason) };
+  if (fenced.blocked || fenced.status !== "finalized"
+    || !validPremortemScopeFinalization(fenced.finalization, expected, summaryDigests)
+    || fenced.finalization.attachmentDigest !== dispositionDigest) {
+    return { status: fenced.status || "mismatch", blocked: true,
+      reason: fenced.reason || "Read-only premortem finalization does not match the goal step.",
+      attachments: null };
+  }
+  return { status: "read-only", blocked: false,
+    attachments: dispositionAttachments("read-only", expected, checkpoint, completedAt,
+      "host-confirmed-read-only", fenced.finalization) };
+}