blun-king-cli 9.1.567 → 9.1.570

package/agent-spine-plugin/src/lib/lesson-recall-session.js

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { replaceFileWithRetry } from "./filesystem-retry.js";
+import { withOwnedFileLock } from "./owned-file-lock.js";
+import { projectStateDir } from "./paths.js";
+
+const SCHEMA = "agentspine.lesson-recall-sessions/v1";
+const AUTHORITY = "context-only";
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_.@/-]{0,127}$/;
+const MAX_BYTES = 1024 * 1024;
+const MAX_SESSIONS = 128;
+const MAX_PATHS = 8;
+const TTL_MS = 24 * 60 * 60 * 1000;
+
+function boundedId(value) {
+  return typeof value === "string" && ID_RE.test(value) ? value : null;
+}
+
+function time(value = new Date()) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (!Number.isFinite(date.getTime())) throw new Error("lesson recall timestamp is invalid");
+  return date;
+}
+
+function suppliedScope(input) {
+  const value = input.agent_spine_scope && typeof input.agent_spine_scope === "object"
+    ? input.agent_spine_scope : input;
+  return {
+    entityId: boundedId(value.entity_id ?? value.entityId),
+    projectId: boundedId(value.project_id ?? value.projectId),
+    groupId: boundedId(value.group_id ?? value.groupId),
+    taskId: boundedId(value.task_id ?? value.taskId ?? value.currentTaskId)
+  };
+}
+
+function sessionId(input) {
+  return boundedId(input.session_id ?? input.sessionId);
+}
+
+function emptyState(root) {
+  return { schema: SCHEMA, root, sessions: [], authority: AUTHORITY };
+}
+
+function validPath(item) {
+  return item && typeof item.path === "string" && item.path.length > 0 && item.path.length <= 512
+    && !item.path.startsWith("/") && !item.path.startsWith("../") && !item.path.includes("/../")
+    && /^[a-f0-9]{64}$/.test(item.sha256 || "");
+}
+
+function validSession(item) {
+  return item && boundedId(item.sessionId) && item.host === "claude"
+    && [item.entityId, item.projectId, item.groupId, item.taskId].every((value) => value === null || boundedId(value))
+    && Array.isArray(item.paths) && item.paths.length <= MAX_PATHS && item.paths.every(validPath)
+    && Number.isFinite(new Date(item.updatedAt).getTime())
+    && Number.isFinite(new Date(item.expiresAt).getTime())
+    && item.authority === AUTHORITY;
+}
+
+function normalizeState(value, root) {
+  if (!value || value.schema !== SCHEMA || value.root !== root || value.authority !== AUTHORITY
+    || !Array.isArray(value.sessions) || value.sessions.length > MAX_SESSIONS
+    || value.sessions.some((item) => !validSession(item))) {
+    throw new Error("lesson recall session state is invalid");
+  }
+  return value;
+}
+
+async function pathsFor(root) {
+  const directory = await projectStateDir(root);
+  return { path: join(directory, "lesson-recall-sessions.json"),
+    lockPath: join(directory, "lesson-recall-sessions.lock") };
+}
+
+async function readState(path, root) {
+  try {
+    const metadata = await stat(path);
+    if (metadata.size > MAX_BYTES) throw new Error("lesson recall session state exceeds 1 MiB");
+    return normalizeState(JSON.parse(await readFile(path, "utf8")), root);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return emptyState(root);
+  }
+}
+
+async function saveState(state, path, assertOwned) {
+  const content = `${JSON.stringify(state, null, 2)}\n`;
+  if (Buffer.byteLength(content) > MAX_BYTES) throw new Error("lesson recall session state exceeds 1 MiB");
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, content, { mode: 0o600 });
+  try {
+    await replaceFileWithRetry(temporary, path, { beforeAttempt: assertOwned });
+  } catch (error) {
+    await unlink(temporary).catch((cleanupError) => {
+      if (cleanupError.code !== "ENOENT") error.cleanupError = cleanupError;
+    });
+    throw error;
+  }
+}
+
+function sameScope(record, input) {
+  const scope = suppliedScope(input);
+  return record.sessionId === sessionId(input) && record.host === "claude"
+    && record.entityId === scope.entityId && record.projectId === scope.projectId
+    && record.groupId === scope.groupId && record.taskId === scope.taskId;
+}
+
+export function hookMemoryQuery(input) {
+  for (const key of ["prompt", "user_prompt", "message", "input"]) {
+    if (typeof input[key] === "string" && input[key].trim()) return input[key].slice(0, 16384);
+  }
+  const tool = typeof input.tool_name === "string" ? input.tool_name : "";
+  const values = [];
+  const visit = (value, key = "", depth = 0) => {
+    if (depth > 4 || values.length >= 32) return;
+    if (typeof value === "string" && /(?:path|file|target|cmd|command|pattern|query)/i.test(key)) {
+      values.push(value.slice(0, 2048));
+      return;
+    }
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      for (const item of value.slice(0, 16)) visit(item, key, depth + 1);
+      return;
+    }
+    for (const [name, item] of Object.entries(value).slice(0, 32)) visit(item, name, depth + 1);
+  };
+  visit(input.tool_input ?? input.tool_args ?? {});
+  return [tool, ...values].filter(Boolean).join(" ");
+}
+
+export async function loadLessonRecallSelection({ root, input, now = new Date() }) {
+  const session = sessionId(input);
+  const scope = suppliedScope(input);
+  if (!session) return { status: "no-session", paths: [], authority: AUTHORITY };
+  if (scope.groupId) return { status: "group-suppressed", paths: [], authority: AUTHORITY };
+  const { path } = await pathsFor(root);
+  const state = await readState(path, root);
+  const timestamp = time(now);
+  const record = state.sessions.find((item) => sameScope(item, input)
+    && new Date(item.expiresAt).getTime() >= timestamp.getTime());
+  return record
+    ? { status: "restored", paths: record.paths.map((item) => item.path), updatedAt: record.updatedAt,
+      expiresAt: record.expiresAt, authority: AUTHORITY }
+    : { status: "empty", paths: [], authority: AUTHORITY };
+}
+
+export async function rememberLessonRecallSelection({ root, input, sources, now = new Date() }) {
+  const session = sessionId(input);
+  const scope = suppliedScope(input);
+  if (!session) return { status: "no-session", paths: [], authority: AUTHORITY };
+  if (scope.groupId) return { status: "group-suppressed", paths: [], authority: AUTHORITY };
+  const selected = sources.filter((item) => item.relativePath !== "MEMORY.md").slice(0, MAX_PATHS)
+    .map((item) => ({ path: item.relativePath, sha256: item.snapshot.metadata.sha256 }));
+  if (!selected.length) return { status: "empty", paths: [], authority: AUTHORITY };
+  const timestamp = time(now);
+  const updatedAt = timestamp.toISOString();
+  const expiresAt = new Date(timestamp.getTime() + TTL_MS).toISOString();
+  const names = await pathsFor(root);
+  return withOwnedFileLock(names.lockPath, async ({ assertOwned }) => {
+    const state = await readState(names.path, root);
+    state.sessions = state.sessions.filter((item) => new Date(item.expiresAt).getTime() >= timestamp.getTime()
+      && !sameScope(item, input));
+    state.sessions.push({ sessionId: session, host: "claude", ...scope, paths: selected,
+      updatedAt, expiresAt, authority: AUTHORITY });
+    state.sessions.sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    state.sessions = state.sessions.slice(0, MAX_SESSIONS);
+    await saveState(state, names.path, assertOwned);
+    return { status: "recorded", paths: selected.map((item) => item.path), updatedAt, expiresAt,
+      authority: AUTHORITY };
+  });
+}

package/agent-spine-plugin/src/lib/mcp-autonomy-tools.js

@@ -0,0 +1,37 @@
+const scope = {
+  registrationId: { type: "string" }, tenantId: { type: "string" },
+  groupId: { anyOf: [{ type: "string" }, { type: "null" }] }
+};
+
+export const autonomyTools = [
+  {
+    name: "project_portfolio",
+    description: "Return a bounded, exact-scope overview of explicitly registered projects and at most one deduplicated proactive notice. Context only; grants no authority.",
+    inputSchema: { type: "object", additionalProperties: false, required: ["tenantId"],
+      properties: { root: { type: "string" }, tenantId: scope.tenantId, groupId: scope.groupId,
+        markPresented: { type: "boolean" }, now: { type: "string" } } }
+  },
+  {
+    name: "record_project_observation",
+    description: "Record one evidence-classified project observation for an existing exact-scope registration. It may create a context-only notice, never authority.",
+    inputSchema: { type: "object", additionalProperties: false,
+      required: ["registrationId", "tenantId", "kind", "evidenceClass", "summary", "sourceDigest"],
+      properties: { root: { type: "string" }, ...scope,
+        kind: { type: "string", enum: ["ci", "error", "idea", "goal", "state"] },
+        status: { type: "string", enum: ["open", "passed", "failed", "resolved", "unknown"] },
+        evidenceClass: { type: "string", enum: ["objective", "user-feedback", "model-suggestion"] },
+        summary: { type: "string", maxLength: 500 }, sourceDigest: { type: "string", pattern: "^[a-f0-9]{64}$" },
+        observedAt: { type: "string" }, expiresAt: { anyOf: [{ type: "string" }, { type: "null" }] } } }
+  },
+  {
+    name: "evaluate_autonomy_action",
+    description: "Evaluate an action against the configured autonomy level and any separately required exact execution grant. This gate never grants a capability.",
+    inputSchema: { type: "object", additionalProperties: false,
+      required: ["registrationId", "tenantId", "action"],
+      properties: { root: { type: "string" }, ...scope,
+        action: { type: "string", enum: ["observe", "advise", "execute", "publish"] },
+        capability: { anyOf: [{ type: "string" }, { type: "null" }] }, actorId: { type: "string" },
+        jobId: { type: "string" }, taskId: { type: "string" }, targetId: { type: "string" },
+        projectId: { type: "string" }, host: { type: "string", enum: ["claude", "codex"] }, now: { type: "string" } } }
+  }
+];

package/agent-spine-plugin/src/lib/mcp-delivery-completion.js

@@ -0,0 +1,124 @@
+import { inspectPremortemState, verifyPremortemBeforeWrite,
+  verifyPremortemStop } from "./delivery-premortem.js";
+import { verifyDeliveryAgentUse } from "./delivery-agent-usage.js";
+import { verifyDeliveryStop } from "./delivery-verification.js";
+import { normalizePremortemBinding } from "./delivery-premortem-binding.js";
+import { hasSecretShapedText } from "./delivery-premortem-closure.js";
+import { canonicalPremortem } from "./delivery-premortem-codec.js";
+import { withActiveDeliveryAssignment } from "./delivery-assignment.js";
+
+const DIGEST = { type: "string", pattern: "^[a-f0-9]{64}$" };
+const ID = { type: "string", minLength: 1, maxLength: 512 };
+const OPTIONAL_ID = { anyOf: [ID, { type: "null" }] };
+const CATEGORIES = ["baseline-environment", "contract-tests", "delivery-path"];
+const BINDING_FIELDS = ["host", "sessionId", "projectId", "entityId", "groupId",
+  "taskId", "assignmentId", "goalId", "goalStepId", "queueId", "gatewayAttempt",
+  "planDefinitionsDigest"];
+
+export const deliveryCompletionTool = {
+  name: "complete_delivery",
+  description: "Store structured completion checks for an ordinary assignment after observed post-write tests. Stop still rechecks all gates. No permissions, tests, goal outcomes, or host identity are created.",
+  inputSchema: {
+    type: "object", additionalProperties: false,
+    required: ["root", "requirementId", "binding", "artifactDigest", "lastWriteDigest", "checks"],
+    properties: {
+      root: ID,
+      requirementId: { type: "string", pattern: "^premortem-requirement:[a-f0-9]{64}:[a-f0-9]{64}$" },
+      binding: {
+        type: "object", additionalProperties: false,
+        required: ["host", "sessionId", "projectId", "assignmentId"],
+        properties: Object.fromEntries(BINDING_FIELDS.map(key => [key,
+          key === "gatewayAttempt" ? { anyOf: [{ type: "integer", minimum: 1 }, { type: "null" }] }
+            : ["host", "sessionId", "projectId", "assignmentId"].includes(key) ? ID : OPTIONAL_ID]))
+      },
+      artifactDigest: DIGEST, lastWriteDigest: DIGEST,
+      checks: {
+        type: "array", minItems: 3, maxItems: 3,
+        items: { type: "object", additionalProperties: false,
+          required: ["category", "checkId", "status", "result"],
+          properties: {
+            category: { type: "string", enum: CATEGORIES }, checkId: ID,
+            status: { const: "PASS" }, result: { type: "string", minLength: 1, maxLength: 1024 }
+          } }
+      }
+    }
+  }
+};
+
+function reject(status, reason) {
+  return { status, blocked: true, reason, authority: "context-only" };
+}
+
+function strictKeys(value, keys) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).every(key => keys.includes(key));
+}
+
+function closureMessage(args) {
+  if (![args.artifactDigest, args.lastWriteDigest].every(value =>
+    typeof value === "string" && /^[a-f0-9]{64}$/.test(value))) throw new Error("completion digests are invalid");
+  if (!Array.isArray(args.checks) || args.checks.length !== 3) throw new Error("completion requires three checks");
+  const lines = args.checks.map(check => {
+    if (!strictKeys(check, ["category", "checkId", "status", "result"])
+      || !CATEGORIES.includes(check.category) || check.status !== "PASS"
+      || !/^check-[a-f0-9]{20}$/.test(check.checkId || "")
+      || typeof check.result !== "string" || !check.result.trim() || check.result.length > 1024
+      || /[\0\r\n]/.test(check.result) || hasSecretShapedText(check.result)) {
+      throw new Error("completion check is invalid or contains secret-shaped content");
+    }
+    return `- ${check.category} ${check.checkId}: PASS — ${check.result.trim()}`;
+  });
+  return [`Premortem closure sha256 ${args.artifactDigest}`,
+    `Premortem latest write sha256 ${args.lastWriteDigest}`, ...lines].join("\n");
+}
+
+export async function completeDelivery(args) {
+  try {
+    if (!strictKeys(args, ["root", "requirementId", "binding", "artifactDigest", "lastWriteDigest", "checks"])
+      || typeof args.root !== "string" || !args.root
+      || !strictKeys(args.binding, BINDING_FIELDS)) throw new Error("completion requires exact bound arguments");
+    const message = closureMessage(args);
+    const binding = normalizePremortemBinding(args.binding);
+    return await withActiveDeliveryAssignment({ root: args.root, binding },
+      assertOwned => completeBoundDelivery(args, binding, message, assertOwned));
+  } catch (error) {
+    return reject("invalid-completion", String(error.message).slice(0, 400));
+  }
+}
+
+async function completeBoundDelivery(args, binding, message, assertOwned) {
+  const current = await inspectPremortemState({ root: args.root, requirementId: args.requirementId });
+  if (current.blocked || current.status === "degraded") return current;
+  if (!current.hasWrite || !binding.assignmentId
+    || canonicalPremortem(binding) !== canonicalPremortem(current.binding)) {
+    return reject("foreign-completion", "Completion requires the exact written assignment binding.");
+  }
+  // Goal verification has a distinct task/queue lane. Preserve its existing
+  // checkpoint and outcome route until a host supplies that verified lane.
+  if (binding.goalId || binding.queueId) {
+    return reject("goal-completion-required", "Use the existing goal checkpoint and outcome completion route.");
+  }
+  const usage = await verifyDeliveryAgentUse({ root: args.root, requirementId: args.requirementId });
+  if (usage.blocked || usage.status !== "verified") return usage;
+  const prepared = await verifyPremortemBeforeWrite({ root: args.root, binding });
+  if (prepared.blocked || prepared.status !== "verified") return prepared;
+  if (prepared.digest !== args.artifactDigest) return reject("stale", "Completion artifact digest is stale.");
+  const verificationArgs = { root: args.root, host: binding.host, sessionId: binding.sessionId,
+    scope: { ...binding, currentTaskId: binding.taskId } };
+  const before = await verifyDeliveryStop(verificationArgs);
+  if (before.blocked) return before;
+  if (before.status !== "verified") return reject("untested", "No observed successful post-write test is available.");
+  await assertOwned();
+  const closed = await verifyPremortemStop({ root: args.root, binding, message,
+    testStateDigest: before.stateDigest });
+  if (closed.blocked || closed.status !== "closed") return closed;
+  const after = await verifyDeliveryStop(verificationArgs);
+  if (after.blocked) return after;
+  if (after.status !== "verified" || after.stateDigest !== before.stateDigest) {
+    return reject("changed", "Test evidence changed during completion; recheck the latest write before Stop.");
+  }
+  return { status: "recorded", blocked: false, requirementId: args.requirementId,
+    closure: closed.closure, testStateDigest: before.stateDigest,
+    instruction: "Finish with a normal user-facing summary. Stop rechecks all delivery gates.",
+    authority: "context-only" };
+}

package/agent-spine-plugin/src/lib/mcp-delivery-tools.js

@@ -0,0 +1,45 @@
+const requirementId = {
+  type: "string",
+  pattern: "^premortem-requirement:[a-f0-9]{64}:[a-f0-9]{64}$"
+};
+
+export const sessionBriefingTool = {
+  name: "session_briefing",
+  description: "Assemble one byte-budgeted, privacy-filtered session packet across native sources, relationships, accepted learning, reviewed shared memory, tasks, and optional attention cues. With requirementId, the actual MCP call becomes delivery preflight stage 1. Read-only and context-only.",
+  inputSchema: {
+    type: "object", additionalProperties: false,
+    properties: {
+      root: { type: "string" }, cwd: { type: "string" },
+      host: { type: "string", enum: ["codex", "claude", "generic"] },
+      entityId: { anyOf: [{ type: "string" }, { type: "null" }] },
+      userId: { anyOf: [{ type: "string" }, { type: "null" }] },
+      tenantId: { anyOf: [{ type: "string" }, { type: "null" }] },
+      groupId: { anyOf: [{ type: "string" }, { type: "null" }] },
+      projectId: { anyOf: [{ type: "string" }, { type: "null" }] },
+      currentTaskId: { anyOf: [{ type: "string" }, { type: "null" }] },
+      includePrivate: { type: "boolean" }, focusActive: { type: "boolean" },
+      includeSourceContent: { type: "boolean" },
+      maxBytes: { type: "integer", minimum: 4096, maximum: 262144 },
+      now: { type: "string" }, requirementId
+    }
+  }
+};
+
+export const deliveryKnowledgeTool = {
+  name: "delivery_knowledge_query",
+  description: "Query exact target fingerprints, indexed contracts, recent-error terms, and the scoped AgentSpine context for one delivery. With its hook-issued requirement this actual MCP call becomes preflight stage 2 and grants no authority.",
+  inputSchema: {
+    type: "object", additionalProperties: false,
+    required: ["root", "requirementId", "targetPaths", "contractPaths", "recentErrorTerms"],
+    properties: {
+      root: { type: "string", minLength: 1 }, requirementId,
+      targetPaths: { type: "array", minItems: 1, maxItems: 32,
+        items: { type: "string", minLength: 1, maxLength: 512 } },
+      contractPaths: { type: "array", minItems: 1, maxItems: 8,
+        items: { type: "string", minLength: 1, maxLength: 512 } },
+      recentErrorTerms: { type: "array", minItems: 1, maxItems: 16,
+        items: { type: "string", minLength: 1, maxLength: 512 } },
+      maxBytes: { type: "integer", minimum: 4096, maximum: 262144 }
+    }
+  }
+};

package/agent-spine-plugin/src/lib/mcp-premortem.js

@@ -0,0 +1,68 @@
+const failure = {
+  type: "string",
+  minLength: 29,
+  maxLength: 500,
+  pattern: "^this delivery fails because\\s+\\S"
+};
+
+const check = { type: "string", minLength: 1, maxLength: 500 };
+
+function premortemItem(category) {
+  return {
+    type: "object",
+    additionalProperties: false,
+    required: ["category", "failure", "check"],
+    properties: {
+      category: { const: category },
+      failure,
+      check
+    }
+  };
+}
+
+export const deliveryPremortemTool = {
+  name: "record_delivery_premortem",
+  description: "Record the three required, context-only delivery failure checks before the first write. This audited receipt grants no permissions or tool access.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    required: ["root", "requirementId", "items"],
+    properties: {
+      root: { type: "string", minLength: 1 },
+      requirementId: {
+        type: "string",
+        pattern: "^premortem-requirement:[a-f0-9]{64}:[a-f0-9]{64}$"
+      },
+      items: {
+        type: "array",
+        minItems: 3,
+        maxItems: 3,
+        items: {
+          oneOf: [
+            premortemItem("baseline-environment"),
+            premortemItem("contract-tests"),
+            premortemItem("delivery-path")
+          ]
+        }
+      }
+    }
+  }
+};
+
+export const deliveryPremortemRecoveryTool = {
+  name: "recover_delivery_premortem",
+  description: "Create a fresh assignment-bound requirement from a preserved legacy conflict. The predecessor, rejection history, and all checks remain immutable; this grants no authority.",
+  inputSchema: {
+    type: "object",
+    additionalProperties: false,
+    required: ["root", "predecessorRequirementId"],
+    properties: {
+      root: { type: "string", minLength: 1 },
+      predecessorRequirementId: {
+        type: "string",
+        pattern: "^premortem-requirement:[a-f0-9]{64}:[a-f0-9]{64}$"
+      },
+      taskId: { anyOf: [{ type: "string", minLength: 1, maxLength: 512 }, { type: "null" }] }
+    }
+  }
+};