blun-king-cli 9.1.566 → 9.1.569

package/agent-spine-plugin/src/lib/world-model.js

@@ -0,0 +1,278 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { replaceFileWithRetry } from "./filesystem-retry.js";
+import { withOwnedFileLock } from "./owned-file-lock.js";
+import { canonicalPath, projectStateDir } from "./paths.js";
+
+const SCHEMA = "agentspine.world-model/v1";
+const ASSERTION_SCHEMA = "agentspine.world-assertion/v1";
+const MAX_STATE_BYTES = 5 * 1024 * 1024;
+const MAX_VALUE_BYTES = 8192;
+const EVIDENCE_KINDS = new Set([
+  "objective-measurement", "explicit-user-feedback", "model-suggestion"
+]);
+const PRIVACY = new Set(["private", "shared", "group"]);
+const STABLE_ID = /^[a-z][a-z0-9-]{0,31}:[A-Za-z0-9][A-Za-z0-9._/-]{0,190}$/;
+const PREDICATE = /^[a-z][a-z0-9.-]{0,127}$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+const FORBIDDEN = /(^|[-_.])(permissions?|rights?|authori[sz]ation|credentials?|secrets?|tokens?|api[-_]?keys?|delegation|tool[-_]?access|production[-_]?access|payments?|spending)([-_.]|$)/i;
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function canonicalValue(value, path = "value") {
+  if (value === null || ["string", "boolean"].includes(typeof value)) return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`${path} numbers must be finite`);
+    return value;
+  }
+  if (Array.isArray(value)) return value.map((item, index) => canonicalValue(item, `${path}[${index}]`));
+  if (!value || typeof value !== "object" || Object.getPrototypeOf(value) !== Object.prototype) {
+    throw new Error(`${path} must be JSON data`);
+  }
+  const result = {};
+  for (const key of Object.keys(value).sort()) {
+    if (FORBIDDEN.test(key)) throw new Error(`${path}.${key} is authority data and cannot enter the world model`);
+    result[key] = canonicalValue(value[key], `${path}.${key}`);
+  }
+  return result;
+}
+
+function exactTime(value, field, fallback = null) {
+  if ((value === null || value === undefined) && fallback !== null) return fallback;
+  if (typeof value !== "string" || !value) throw new Error(`${field} is required`);
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime()) || date.toISOString() !== value) {
+    throw new Error(`${field} must be an exact ISO timestamp`);
+  }
+  return value;
+}
+
+function stableId(value, field) {
+  if (typeof value !== "string" || !STABLE_ID.test(value)) throw new Error(`${field} must be a stable namespaced id`);
+  return value;
+}
+
+function optionalStableId(value, field) {
+  return value === null || value === undefined ? null : stableId(value, field);
+}
+
+function emptyModel(root) {
+  return { schema: SCHEMA, root, revision: 0, assertions: [], events: [], authority: "context-only" };
+}
+
+function validateStoredAssertion(assertion, validKnowledgeFields) {
+  if (!assertion || assertion.schema !== ASSERTION_SCHEMA || assertion.authority !== "context-only") return false;
+  if (!STABLE_ID.test(assertion.id || "") || !STABLE_ID.test(assertion.subjectId || "")) return false;
+  if (!PREDICATE.test(assertion.predicate || "") || FORBIDDEN.test(assertion.predicate)
+    || !EVIDENCE_KINDS.has(assertion.evidenceKind)) return false;
+  if (!PRIVACY.has(assertion.privacy) || !DIGEST.test(assertion.evidenceDigest || "")) return false;
+  if ((assertion.privacy === "group") !== Boolean(assertion.groupId)
+    || (assertion.groupId && !STABLE_ID.test(assertion.groupId))
+    || (assertion.projectId && !STABLE_ID.test(assertion.projectId))
+    || !STABLE_ID.test(assertion.evidenceId || "") || !Array.isArray(assertion.supersedes)
+    || assertion.supersedes.some((item) => !STABLE_ID.test(item))) return false;
+  if (!validKnowledgeFields(assertion)) return false;
+  try {
+    if (exactTime(assertion.observedAt, "observedAt") !== assertion.observedAt) return false;
+    if (assertion.expiresAt) exactTime(assertion.expiresAt, "expiresAt");
+    const value = canonicalValue(assertion.value);
+    if (sha256(JSON.stringify(value)) !== assertion.valueDigest) return false;
+  } catch {
+    return false;
+  }
+  return assertion.status === (assertion.evidenceKind === "model-suggestion" ? "proposed" : "established");
+}
+
+function normalizeModel(value, root, validKnowledgeFields) {
+  if (!value || value.schema !== SCHEMA || value.root !== root || value.authority !== "context-only"
+    || !Number.isInteger(value.revision) || value.revision < 0 || !Array.isArray(value.assertions)
+    || !Array.isArray(value.events) || value.assertions.some((item) => !validateStoredAssertion(item, validKnowledgeFields))
+    || value.events.some((item) => !item || item.authority !== "context-only")) {
+    throw new Error("world model state is invalid");
+  }
+  return value;
+}
+
+async function stateNames(root) {
+  const canonicalRoot = await canonicalPath(root);
+  const directory = await projectStateDir(canonicalRoot);
+  const path = join(directory, "world-model.json");
+  return { root: canonicalRoot, path, lockPath: `${path}.lock` };
+}
+
+async function readModel(names) {
+  try {
+    const metadata = await stat(names.path);
+    if (metadata.size > MAX_STATE_BYTES) throw new Error("world model exceeds the 5 MiB read limit");
+    const { validKnowledgeFields } = await import("./world-knowledge.js");
+    return normalizeModel(JSON.parse(await readFile(names.path, "utf8")), names.root, validKnowledgeFields);
+  } catch (error) {
+    if (error.code === "ENOENT") return emptyModel(names.root);
+    if (error instanceof SyntaxError) throw new Error("world model state is not valid JSON");
+    throw error;
+  }
+}
+
+async function writeModel(model, names, assertOwned) {
+  const content = `${JSON.stringify(model, null, 2)}\n`;
+  if (Buffer.byteLength(content) > MAX_STATE_BYTES) throw new Error("world model exceeds 5 MiB");
+  const temporary = `${names.path}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(temporary, content, { mode: 0o600 });
+  await replaceFileWithRetry(temporary, names.path, { beforeAttempt: assertOwned });
+}
+
+function assertionInput(input, now, normalizeKnowledgeFields) {
+  const id = stableId(input.id, "id");
+  const subjectId = stableId(input.subjectId, "subjectId");
+  if (typeof input.predicate !== "string" || !PREDICATE.test(input.predicate)) {
+    throw new Error("predicate must be a lowercase dotted key");
+  }
+  if (FORBIDDEN.test(input.predicate)) throw new Error("authority predicates cannot enter the world model");
+  if (!EVIDENCE_KINDS.has(input.evidenceKind)) throw new Error("unsupported evidenceKind");
+  const evidenceId = stableId(input.evidenceId, "evidenceId");
+  if (!DIGEST.test(input.evidenceDigest || "")) throw new Error("evidenceDigest must be a lowercase SHA-256 digest");
+  const observedAt = exactTime(input.observedAt, "observedAt");
+  const nowTime = new Date(now).getTime();
+  if (new Date(observedAt).getTime() > nowTime) throw new Error("observedAt cannot be in the future");
+  const expiresAt = input.expiresAt === null || input.expiresAt === undefined
+    ? null : exactTime(input.expiresAt, "expiresAt");
+  if (expiresAt && new Date(expiresAt).getTime() <= new Date(observedAt).getTime()) {
+    throw new Error("expiresAt must be after observedAt");
+  }
+  const privacy = input.privacy || "private";
+  if (!PRIVACY.has(privacy)) throw new Error("unsupported privacy");
+  const groupId = optionalStableId(input.groupId, "groupId");
+  if ((privacy === "group") !== Boolean(groupId)) throw new Error("group privacy requires exactly one groupId");
+  const value = canonicalValue(input.value);
+  if (Buffer.byteLength(JSON.stringify(value)) > MAX_VALUE_BYTES) throw new Error("value exceeds 8 KiB");
+  const supersedes = [...new Set((input.supersedes || []).map((item) => stableId(item, "supersedes")))].sort();
+  const knowledge = normalizeKnowledgeFields(input, input.evidenceKind, value);
+  return {
+    schema: ASSERTION_SCHEMA, id, subjectId, predicate: input.predicate, value,
+    valueDigest: sha256(JSON.stringify(value)), evidenceKind: input.evidenceKind,
+    evidenceId, evidenceDigest: input.evidenceDigest, observedAt, expiresAt,
+    projectId: optionalStableId(input.projectId, "projectId"), groupId, privacy,
+    supersedes, reason: typeof input.reason === "string" ? input.reason.trim().slice(0, 500) : "",
+    status: input.evidenceKind === "model-suggestion" ? "proposed" : "established",
+    recordedAt: new Date(now).toISOString(), authority: "context-only",
+    ...(knowledge.knowledgeKind ? knowledge : {})
+  };
+}
+
+function assertionDigest(assertion) {
+  const { recordedAt: _recordedAt, ...material } = assertion;
+  return sha256(JSON.stringify(material));
+}
+
+export async function recordWorldAssertion(input = {}) {
+  const now = input.now || new Date();
+  const { normalizeKnowledgeFields } = await import("./world-knowledge.js");
+  const candidate = assertionInput(input, now, normalizeKnowledgeFields);
+  const names = await stateNames(input.root || process.cwd());
+  return withOwnedFileLock(names.lockPath, async ({ assertOwned }) => {
+    const model = await readModel(names);
+    const existing = model.assertions.find((item) => item.id === candidate.id);
+    if (existing) {
+      if (assertionDigest(existing) !== assertionDigest(candidate)) throw new Error(`world assertion id is already used: ${candidate.id}`);
+      return { status: "duplicate", assertion: structuredClone(existing), revision: model.revision, authority: "context-only" };
+    }
+    for (const id of candidate.supersedes) {
+      const previous = model.assertions.find((item) => item.id === id);
+      if (!previous) throw new Error(`superseded assertion does not exist: ${id}`);
+      if (previous.subjectId !== candidate.subjectId || previous.predicate !== candidate.predicate) {
+        throw new Error("supersession must keep the same subject and predicate");
+      }
+      if (candidate.status !== "established") throw new Error("model suggestions cannot supersede established context");
+    }
+    model.revision += 1;
+    model.assertions.push(candidate);
+    model.events.push({ kind: candidate.supersedes.length ? "resolved" : "recorded", assertionId: candidate.id,
+      supersedes: candidate.supersedes, at: candidate.recordedAt, authority: "context-only" });
+    await writeModel(model, names, assertOwned);
+    return { status: "recorded", assertion: structuredClone(candidate), revision: model.revision, authority: "context-only" };
+  });
+}
+
+function visible(assertion, { includePrivate, groupId, projectId }) {
+  if (assertion.privacy === "private" && (!includePrivate || groupId)) return false;
+  if (assertion.privacy === "group" && assertion.groupId !== groupId) return false;
+  return assertion.projectId === null || assertion.projectId === projectId;
+}
+
+function publicAssertion(assertion) {
+  return structuredClone(assertion);
+}
+
+export async function worldContext({
+  root = process.cwd(), subjectId = null, projectId = null, groupId = null,
+  includePrivate = false, includeKnowledgeHistory = false, continuationTaskId = null,
+  maxItems = 100, now = new Date()
+} = {}) {
+  if (groupId !== null && includePrivate) throw new Error("private world context cannot be assembled for a group audience");
+  if (!Number.isInteger(maxItems) || maxItems < 1 || maxItems > 500) throw new Error("maxItems must be between 1 and 500");
+  subjectId = optionalStableId(subjectId, "subjectId");
+  projectId = optionalStableId(projectId, "projectId");
+  groupId = optionalStableId(groupId, "groupId");
+  continuationTaskId = optionalStableId(continuationTaskId, "continuationTaskId");
+  const names = await stateNames(root);
+  const model = await readModel(names);
+  const { structuredKnowledgeView } = await import("./world-knowledge.js");
+  const cutoff = new Date(now).getTime();
+  if (!Number.isFinite(cutoff)) throw new Error("now is invalid");
+  const candidates = model.assertions.filter((item) => visible(item, { includePrivate, groupId, projectId })
+    && (!subjectId || item.subjectId === subjectId));
+  const stale = candidates.filter((item) => item.expiresAt && new Date(item.expiresAt).getTime() <= cutoff);
+  const current = candidates.filter((item) => !item.expiresAt || new Date(item.expiresAt).getTime() > cutoff);
+  const superseded = new Set(current.flatMap((item) => item.status === "established" ? item.supersedes : []));
+  const active = current.filter((item) => !superseded.has(item.id));
+  const proposals = active.filter((item) => item.status === "proposed");
+  const established = active.filter((item) => item.status === "established");
+  const buckets = new Map();
+  for (const item of established) {
+    const key = `${item.subjectId}\0${item.predicate}`;
+    if (!buckets.has(key)) buckets.set(key, []);
+    buckets.get(key).push(item);
+  }
+  const facts = [];
+  const conflicts = [];
+  const conflictAssertions = [];
+  for (const assertions of buckets.values()) {
+    const values = new Set(assertions.map((item) => item.valueDigest));
+    if (values.size > 1) {
+      conflictAssertions.push(assertions);
+      conflicts.push({ subjectId: assertions[0].subjectId, predicate: assertions[0].predicate,
+        assertions: assertions.map(publicAssertion), authority: "context-only" });
+      continue;
+    }
+    const newest = [...assertions].sort((a, b) => b.observedAt.localeCompare(a.observedAt))[0];
+    facts.push({ subjectId: newest.subjectId, predicate: newest.predicate, value: structuredClone(newest.value),
+      assertionIds: assertions.map((item) => item.id).sort(), evidenceKinds: [...new Set(assertions.map((item) => item.evidenceKind))].sort(),
+      latestObservedAt: newest.observedAt, expiresAt: newest.expiresAt, privacy: newest.privacy,
+      groupId: newest.groupId, projectId: newest.projectId, authority: "context-only" });
+  }
+  const order = (left, right) => left.subjectId.localeCompare(right.subjectId) || left.predicate.localeCompare(right.predicate);
+  facts.sort(order); conflicts.sort(order); proposals.sort(order); stale.sort(order);
+  const knowledge = structuredKnowledgeView({
+    candidates, stale, active, supersededIds: superseded, conflictAssertions,
+    includeHistory: Boolean(includeKnowledgeHistory), continuationTaskId, maxItems
+  });
+  return {
+    schema: "agentspine.world-context/v1", root: names.root, revision: model.revision,
+    facts: facts.slice(0, maxItems), conflicts: conflicts.slice(0, maxItems),
+    proposals: proposals.slice(0, maxItems).map(publicAssertion), stale: stale.slice(0, maxItems).map(publicAssertion),
+    knowledge,
+    omitted: { facts: Math.max(0, facts.length - maxItems), conflicts: Math.max(0, conflicts.length - maxItems),
+      proposals: Math.max(0, proposals.length - maxItems), stale: Math.max(0, stale.length - maxItems) },
+    uncertainty: { requiresResolution: conflicts.length > 0, conflicts: conflicts.length,
+      proposals: proposals.length, stale: stale.length },
+    authority: "context-only",
+    note: "Only unexpired, non-conflicting measured or explicitly user-confirmed assertions are facts. Model suggestions remain proposals and grant no authority."
+  };
+}
+
+export async function worldModelStatePath(root = process.cwd()) {
+  return (await stateNames(root)).path;
+}

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

@@ -1,24 +1,12 @@
 import { VERSION } from "./version.js";
 import { isMainModule } from "./lib/runtime.js";
-import { scanAndSave, verifyCatalog } from "./lib/catalog.js";
-import { readDocument, resolveContext } from "./lib/context.js";
-import { sessionBriefing } from "./lib/briefing.js";
-import { runAudit } from "./lib/audit.js";
-import {
-  attentionContext, configureAttention, deleteAttention,
-  recordActivity, resolveAttention, upsertAttention
-} from "./lib/attention.js";
-import {
-  addLearningEvidence, configureLearning, deleteLearning, evaluateLearning,
-  learningContext, learningOutcomeStatus, proposeLearning, reviewLearning, rollbackLearning
-} from "./lib/learning.js";
-import { checkDelegation, createTask, taskContext, updateTask } from "./lib/coordination.js";
-import { sharedContext } from "./lib/sharing.js";
-import { resolveGoalKnowledgeGap } from "./lib/gateway-runtime.js";
-import {
-  annotateDocument, linkDocuments, linkEntities,
-  relationshipContext, upsertEntity
-} from "./lib/graph.js";
+import { deliveryPremortemRecoveryTool, deliveryPremortemTool } from "./lib/mcp-premortem.js";
+import { deliveryKnowledgeTool, sessionBriefingTool } from "./lib/mcp-delivery-tools.js";
+import { worldModelTools } from "./lib/mcp-world-tools.js";
+import { sessionTimelineTools } from "./lib/mcp-timeline-tools.js";
+import { startMcpProtocol } from "./lib/mcp-runtime.js";
+import { deliveryCompletionTool } from "./lib/mcp-delivery-completion.js";
+import { autonomyTools } from "./lib/mcp-autonomy-tools.js";
 
 const tools = [
   {
@@ -38,34 +26,19 @@ const tools = [
       }
     }
   },
-  {
-    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. 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" }
-      }
-    }
-  },
+  sessionBriefingTool,
+  deliveryKnowledgeTool,
+  ...worldModelTools,
+  ...sessionTimelineTools,
+  ...autonomyTools,
   {
     name: "read_document",
-    description: "Read an indexed Markdown source byte range with its SHA-256 provenance.",
+    description: "Read a bounded host-indexed Markdown source byte range with verified SHA-256 provenance; no broad home scan.",
     inputSchema: {
       type: "object", required: ["path"],
       properties: {
         root: { type: "string" }, path: { type: "string" },
+        host: { type: "string", enum: ["codex", "claude", "generic"] },
         offset: { type: "integer", minimum: 0 }, length: { type: "integer", minimum: 1, maximum: 1048576 }
       }
     }
@@ -464,132 +437,18 @@ const tools = [
       }
     }
   },
-  {
-    name: "goal_clarify",
-    description: "Resolve one exact open knowledge gap for a dependency-bound goal-plan step. This binds context only and grants no authority.",
-    inputSchema: {
-      type: "object", additionalProperties: false,
-      required: ["goalId", "gapId", "answer", "confirmLocalGoal"],
-      properties: {
-        root: { type: "string" }, goalId: { type: "string" }, gapId: { type: "string" },
-        answer: { type: "string", maxLength: 2000 },
-        answerSource: { type: "string", enum: ["owner-input", "objective-observation"] },
-        sourceDigest: { anyOf: [{ type: "string", pattern: "^[a-f0-9]{64}$" }, { type: "null" }] },
-        confirmLocalGoal: { type: "boolean", const: true }
-      }
-    }
-  },
   {
     name: "audit",
     description: "Run AgentSpine's ten deterministic quality gates for discovery, hierarchy, links, authority, privacy, budget, and source preservation.",
     inputSchema: { type: "object", properties: { root: { type: "string" } } }
-  }
+  },
+  deliveryPremortemTool,
+  deliveryCompletionTool,
+  deliveryPremortemRecoveryTool
 ];
 
-function textResult(value, isError = false) {
-  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], isError };
-}
-
-async function callTool(name, args = {}) {
-  const root = args.root || process.cwd();
-  if (name === "scan") return textResult(await scanAndSave(root));
-  if (name === "resolve_context") return textResult(await resolveContext({
-    root,
-    cwd: args.cwd || root,
-    host: args.host || "generic",
-    maxBytes: args.maxBytes ?? 65536,
-    includeContent: args.includeContent ?? true
-  }));
-  if (name === "session_briefing") return textResult(await sessionBriefing({ ...args, root }));
-  if (name === "read_document") return textResult(await readDocument({
-    root, path: args.path, offset: args.offset ?? 0, length: args.length ?? 65536
-  }));
-  if (name === "verify") return textResult(await verifyCatalog(root));
-  if (name === "link_documents") return textResult(await linkDocuments({ ...args, root }));
-  if (name === "annotate_document") return textResult(await annotateDocument({ ...args, root }));
-  if (name === "upsert_entity") return textResult(await upsertEntity({ ...args, root }));
-  if (name === "link_entities") return textResult(await linkEntities({ ...args, root }));
-  if (name === "relationship_context") return textResult(await relationshipContext({ ...args, root }));
-  if (name === "upsert_attention") return textResult(await upsertAttention({ ...args, root }));
-  if (name === "record_activity") return textResult(await recordActivity({ ...args, root }));
-  if (name === "attention_context") return textResult(await attentionContext({ ...args, root }));
-  if (name === "resolve_attention") return textResult(await resolveAttention({ ...args, root }));
-  if (name === "configure_attention") return textResult(await configureAttention({ ...args, root }));
-  if (name === "delete_attention") return textResult(await deleteAttention({ ...args, root }));
-  if (name === "propose_learning") return textResult(await proposeLearning({ ...args, root }));
-  if (name === "add_learning_evidence") return textResult(await addLearningEvidence({ ...args, root }));
-  if (name === "review_learning") return textResult(await reviewLearning({ ...args, root }));
-  if (name === "learning_context") return textResult(await learningContext({ ...args, root }));
-  if (name === "learning_outcome_status") return textResult(await learningOutcomeStatus({ ...args, root }));
-  if (name === "evaluate_learning") return textResult(await evaluateLearning({ ...args, root }));
-  if (name === "rollback_learning") return textResult(await rollbackLearning({ ...args, root }));
-  if (name === "configure_learning") return textResult(await configureLearning({ ...args, root }));
-  if (name === "delete_learning") return textResult(await deleteLearning({ ...args, root }));
-  if (name === "check_delegation") return textResult(await checkDelegation({ ...args, root }));
-  if (name === "create_task") return textResult(await createTask({ ...args, root }));
-  if (name === "update_task") return textResult(await updateTask({ ...args, root }));
-  if (name === "task_context") return textResult(await taskContext({ ...args, root }));
-  if (name === "shared_context") return textResult(await sharedContext({ ...args, root }));
-  if (name === "goal_clarify") return textResult(await resolveGoalKnowledgeGap({
-    root,
-    goalId: args.goalId,
-    gapId: args.gapId,
-    answer: args.answer,
-    answerSource: args.answerSource || "owner-input",
-    sourceDigest: args.sourceDigest || null,
-    confirmation: args.confirmLocalGoal === true ? "local-owner-confirmed" : null
-  }));
-  if (name === "audit") return textResult(await runAudit(root));
-  throw new Error(`Unknown tool: ${name}`);
-}
-
-async function dispatch(message) {
-  const { id, method, params = {} } = message;
-  if (method === "initialize") {
-    return {
-      jsonrpc: "2.0", id,
-      result: {
-        protocolVersion: params.protocolVersion || "2025-06-18",
-        capabilities: { tools: { listChanged: false } },
-        serverInfo: { name: "agent-spine", version: VERSION }
-      }
-    };
-  }
-  if (method === "ping") return { jsonrpc: "2.0", id, result: {} };
-  if (method === "tools/list") return { jsonrpc: "2.0", id, result: { tools } };
-  if (method === "tools/call") {
-    try {
-      return { jsonrpc: "2.0", id, result: await callTool(params.name, params.arguments) };
-    } catch (error) {
-      return { jsonrpc: "2.0", id, result: textResult({ error: error.message }, true) };
-    }
-  }
-  if (method?.startsWith("notifications/")) return null;
-  return { jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${method}` } };
-}
-
-export function startMcpServer(input = process.stdin, output = process.stdout) {
-  input.setEncoding("utf8");
-  let buffer = "";
-  let queue = Promise.resolve();
-  input.on("data", (chunk) => {
-    buffer += chunk;
-    let newline;
-    while ((newline = buffer.indexOf("\n")) >= 0) {
-      const line = buffer.slice(0, newline).trim();
-      buffer = buffer.slice(newline + 1);
-      if (!line) continue;
-      queue = queue.then(async () => {
-        let response;
-        try {
-          response = await dispatch(JSON.parse(line));
-        } catch (error) {
-          response = { jsonrpc: "2.0", id: null, error: { code: -32700, message: error.message } };
-        }
-        if (response) output.write(`${JSON.stringify(response)}\n`);
-      });
-    }
-  });
+export function startMcpServer(input = process.stdin, output = process.stdout, { environment = process.env } = {}) {
+  return startMcpProtocol({ input, output, tools, version: VERSION, environment });
 }
 
 if (isMainModule(import.meta.url)) {

package/agent-spine-plugin/src/version.js

@@ -1 +1 @@
-export const VERSION = "0.59.1";
+export const VERSION = "0.73.0";

package/agent-spine-plugin/src/worker.js

@@ -5,11 +5,12 @@ import { lstat, realpath } from "node:fs/promises";
 import { isAbsolute, join, resolve } from "node:path";
 import {
   claimGatewayWork, completeGatewayRun, deliverPrepared, executionAttemptForStep,
-  failGatewayRun, loadGatewayRuntime, reconcileGateway, updateGatewayHealth
+  failGatewayRun, loadGatewayRuntime, markGatewayHostStarted, reconcileGateway, updateGatewayHealth
 } from "./lib/gateway-runtime.js";
 import { createTelegramAdapter } from "./lib/telegram-adapter.js";
 import { acknowledgeChannelDelivery, loadChannelRuntime } from "./lib/channel-runtime.js";
 import { loadPersonaRuntime, syncPersonaRosterFromEnvironment } from "./lib/persona-runtime.js";
+import { selfHelpPolicyForWorkItem } from "./lib/knowledge-evidence.js";
 import { isMainModule } from "./lib/runtime.js";
 
 const MAX_FRAME = 64 * 1024;
@@ -105,11 +106,20 @@ async function hostWorkItem(root, item) {
     goal: goal ? structuredClone(goal) : null,
     goalStep: goalStep ? { ...structuredClone(goalStep),
       ...(executionAttempt === null ? {} : { executionAttempt }) } : null,
+    selfHelpPolicy: goalStep ? selfHelpPolicyForWorkItem(goalStep) : null,
     hostEnvironment: {
       AGENTSPINE_GATEWAY_CONTEXT: "agentspine.gateway-start/v1",
       AGENTSPINE_ENTITY_ID: item.agentId,
       AGENTSPINE_PROJECT_ID: item.projectId,
+      AGENTSPINE_HOST: identity.host,
+      AGENTSPINE_GATEWAY_QUEUE_ID: item.queueId,
+      AGENTSPINE_GATEWAY_ATTEMPT: String(item.attempts),
       ...(item.groupId === null ? {} : { AGENTSPINE_GROUP_ID: item.groupId }),
+      ...(goalStep ? {
+        AGENTSPINE_GOAL_ID: goal.goalId,
+        AGENTSPINE_GOAL_STEP_ID: goalStep.stepId,
+        AGENTSPINE_PLAN_DEFINITIONS_DIGEST: goal.plan.definitionsDigest
+      } : {}),
       ...(event ? {
         AGENTSPINE_CHANNEL_EVENT_ID: event.eventId,
         AGENTSPINE_CHANNEL_PROVIDER: event.provider
@@ -151,22 +161,29 @@ export async function runWorkerTick({ root = process.cwd(), workerId = "gateway-
     return { status: delivery.outbox.status, processed: true, outboxId: delivery.outbox.outboxId,
       recoveredDelivery: true };
   }
-  const claim = await claimGatewayWork({ root, workerId, now });
+  const claim = await claimGatewayWork({ root, workerId, executionMode: "host-effect", now });
   if (!claim.item) return { status: claim.reason, processed: false };
+  await markGatewayHostStarted({ root, queueId: claim.item.queueId, workerId,
+    claimedAt: claim.item.lease.claimedAt, attempt: claim.item.attempts, now });
   let result;
   try { result = await hostRunner(await hostWorkItem(root, claim.item), { env }); }
   catch (error) {
     const failed = await failGatewayRun({ root, queueId: claim.item.queueId, workerId,
+      claimedAt: claim.item.lease.claimedAt, attempt: claim.item.attempts,
       error: "Host runtime unavailable: " + String(error.message).slice(0, 400), now });
     return { status: failed.item.status, processed: true, queueId: failed.item.queueId, retryAt: failed.item.availableAt };
   }
-  const completed = await completeGatewayRun({ root, queueId: claim.item.queueId, workerId, result, now });
+  const completed = await completeGatewayRun({ root, queueId: claim.item.queueId, workerId,
+    claimedAt: claim.item.lease.claimedAt, attempt: claim.item.attempts, result, now });
   if (!completed.outbox) return {
     status: completed.clarification ? "needs-clarification"
-      : completed.exploration ? "exploring" : completed.item.status,
+      : completed.exploration ? "exploring" : completed.selfHelp ? "self-help-resolved"
+        : completed.selfHelpRequired ? "self-help-required" : completed.item.status,
     processed: true, queueId: completed.item.queueId,
     ...(completed.clarification ? { clarification: completed.clarification } : {}),
-    ...(completed.exploration ? { exploration: completed.exploration } : {})
+    ...(completed.exploration ? { exploration: completed.exploration } : {}),
+    ...(completed.selfHelp ? { selfHelp: completed.selfHelp } : {}),
+    ...(completed.selfHelpRequired ? { selfHelpRequired: completed.selfHelpRequired } : {})
   };
   const delivery = await deliverPrepared({ root, outboxId: completed.outbox.outboxId,
     adapter: deliveryAdapter, now });

package/bin/agent-resume-snapshot.cjs

@@ -94,7 +94,7 @@ function createAgentResumeSnapshot(agent) {
     goal: agent.goal.state ?? null,
     turn: {
       turnId: agent.turn.turnId,
-      telegramDeliveryIdentities: agent.turn.telegramDeliveryLedger.snapshot(),
+      telegramDeliveryIdentities: agent.turn.telegramDeliveryLedger?.snapshot?.() ?? [],
     },
     microCompaction: { cutoff: agent.microCompaction.cutoff },
   };
@@ -211,7 +211,7 @@ function restoreAgentResumeSnapshot(agent, snapshot) {
     agent.turn.turnId = Number.isInteger(snapshot.turn.turnId) ? snapshot.turn.turnId : -1;
     agent.turn.activeTurn = 'resuming';
     agent.turn.steerBuffer.length = 0;
-    agent.turn.telegramDeliveryLedger.restore(snapshot.turn.telegramDeliveryIdentities);
+    agent.turn.telegramDeliveryLedger?.restore?.(snapshot.turn.telegramDeliveryIdentities);
     agent.microCompaction.cutoff = Number.isInteger(snapshot.microCompaction?.cutoff)
       ? Math.max(0, Math.min(snapshot.context.history.length, snapshot.microCompaction.cutoff))
       : 0;