chainlesschain 0.166.5 → 0.166.7

package/src/lib/agent-ipc-flow-control.js

@@ -0,0 +1,200 @@
+export const AGENT_IPC_DEFAULT_LIMITS = Object.freeze({
+  maxAgents: 64,
+  maxPendingInteractions: 128,
+  maxPendingInteractionsPerAgent: 16,
+  maxPendingAgentRequests: 256,
+  maxPendingAgentRequestsPerAgent: 32,
+  maxStdoutLineBytes: 1024 * 1024,
+  maxStderrChunkBytes: 64 * 1024,
+  maxStdinFrameBytes: 1024 * 1024,
+  maxStdinQueueMessages: 128,
+  maxStdinQueueBytes: 4 * 1024 * 1024,
+  interactionTimeoutMs: 5 * 60 * 1000,
+  maxInteractionTimeoutMs: 10 * 60 * 1000,
+  agentRequestTimeoutMs: 30 * 1000,
+  maxAgentRequestTimeoutMs: 2 * 60 * 1000,
+  agentInitTimeoutMs: 10 * 1000,
+  maxAgentInitTimeoutMs: 2 * 60 * 1000,
+  agentHeartbeatMs: 30 * 1000,
+  maxAgentHeartbeatMs: 2 * 60 * 1000,
+  overloadRetryAfterMs: 1000,
+});
+
+export function positiveInteger(value, fallback, name) {
+  const candidate = value ?? fallback;
+  if (!Number.isSafeInteger(candidate) || candidate <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return candidate;
+}
+
+export function boundedTimeout(value, fallback, maximum) {
+  const normalized = positiveInteger(value, fallback, "timeoutMs");
+  return Math.min(normalized, maximum);
+}
+
+export function overloadError(resource, limit, retryAfterMs) {
+  const error = new Error(
+    `Agent IPC overloaded: ${resource} reached its limit of ${limit}`,
+  );
+  error.code = "OVERLOADED";
+  error.retryAfterMs = retryAfterMs;
+  error.data = {
+    resource,
+    limit,
+    retry_after_ms: retryAfterMs,
+  };
+  return error;
+}
+
+export function normalizeAgentIPCLimits(limits = {}) {
+  const normalized = {};
+  for (const [name, fallback] of Object.entries(AGENT_IPC_DEFAULT_LIMITS)) {
+    normalized[name] = positiveInteger(limits[name], fallback, name);
+  }
+  return Object.freeze(normalized);
+}
+
+/**
+ * A bounded JSONL writer for one child stdin stream. The first write that
+ * returns false marks the transport blocked; later frames enter an explicit
+ * message/byte-capped queue until Node emits drain.
+ */
+export function createBoundedStdinWriter({
+  child,
+  agentId,
+  limits,
+  onOverload,
+}) {
+  const queue = [];
+  let queuedBytes = 0;
+  let blocked = false;
+  let closed = false;
+
+  const cleanupListeners = () => {
+    child.stdin.off?.("drain", flush);
+    child.stdin.off?.("error", handleError);
+    child.stdin.off?.("close", handleClose);
+  };
+
+  const fail = (error) => {
+    if (closed) return;
+    closed = true;
+    blocked = false;
+    queue.length = 0;
+    queuedBytes = 0;
+    cleanupListeners();
+    queueMicrotask(() => onOverload(error));
+  };
+
+  const writePayload = (payload) => {
+    if (closed) {
+      throw new Error(`Agent ${agentId} stdin transport is closed`);
+    }
+    if (child.stdin.destroyed || child.stdin.writableEnded) {
+      const error = new Error(`Agent ${agentId} stdin is not writable`);
+      fail(error);
+      throw error;
+    }
+    const bytes = Buffer.byteLength(payload);
+    if (bytes > limits.maxStdinFrameBytes) {
+      const error = overloadError(
+        "stdin_frame_bytes",
+        limits.maxStdinFrameBytes,
+        limits.overloadRetryAfterMs,
+      );
+      fail(error);
+      throw error;
+    }
+
+    if (blocked || queue.length > 0) {
+      if (
+        queue.length >= limits.maxStdinQueueMessages ||
+        queuedBytes + bytes > limits.maxStdinQueueBytes
+      ) {
+        const resource =
+          queue.length >= limits.maxStdinQueueMessages
+            ? "stdin_queue_messages"
+            : "stdin_queue_bytes";
+        const limit =
+          resource === "stdin_queue_messages"
+            ? limits.maxStdinQueueMessages
+            : limits.maxStdinQueueBytes;
+        const error = overloadError(
+          resource,
+          limit,
+          limits.overloadRetryAfterMs,
+        );
+        fail(error);
+        throw error;
+      }
+      queue.push({ payload, bytes });
+      queuedBytes += bytes;
+      return true;
+    }
+
+    try {
+      blocked = child.stdin.write(payload) === false;
+    } catch (error) {
+      fail(error);
+      throw error;
+    }
+    return true;
+  };
+
+  const flush = () => {
+    if (closed) return;
+    blocked = false;
+    while (queue.length > 0 && !blocked) {
+      const entry = queue.shift();
+      queuedBytes -= entry.bytes;
+      try {
+        blocked = child.stdin.write(entry.payload) === false;
+      } catch (error) {
+        fail(error);
+        return;
+      }
+    }
+  };
+
+  const handleError = (error) => {
+    if (!closed) fail(error);
+  };
+
+  const handleClose = () => {
+    if (
+      !closed &&
+      child.exitCode === null &&
+      (child.signalCode === null || child.signalCode === undefined)
+    ) {
+      fail(new Error(`Agent ${agentId} stdin closed before process exit`));
+    }
+  };
+
+  child.stdin.on?.("drain", flush);
+  child.stdin.on?.("error", handleError);
+  child.stdin.on?.("close", handleClose);
+
+  return {
+    write(message) {
+      const payload = `${JSON.stringify(message)}\n`;
+      return writePayload(payload);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      blocked = false;
+      queue.length = 0;
+      queuedBytes = 0;
+      cleanupListeners();
+    },
+    status() {
+      return {
+        blocked,
+        closed,
+        queuedMessages: queue.length,
+        queuedBytes,
+      };
+    },
+  };
+}

package/src/lib/agent-team/task-lease.js

@@ -325,6 +325,7 @@ export class TaskLeaseRegistry {
       attempts: t.metadata?.attempts || 0,
       lease: lease ? { ...lease } : null,
       assignee: t.assignee,
+      createdBy: t.createdBy ?? null,
       rev: t.rev,
       // Full metadata is exposed so executors can read user payload
       // (e.g. a task's shell `command` or agent `prompt`) — it carries the
@@ -1465,6 +1466,320 @@ export class TaskLeaseRegistry {
     return { ok: true, priorStatus };
   }
 
+  /**
+   * Repair the compatibility task view from a terminal canonical Graph node.
+   * This exceptional path may correct a fail-closed recovery cancellation when
+   * the immutable Graph ledger proves that the effect/attempt already settled.
+   */
+  applyCanonicalTaskProjection(
+    key,
+    {
+      runId,
+      nodeId,
+      graphStatus,
+      authorityGeneration,
+      eventHead,
+      revisionDigest,
+      evidence = null,
+      now = this._now(),
+    } = {},
+  ) {
+    const terminalStatus =
+      graphStatus === "succeeded"
+        ? TASK_STATUS.COMPLETED
+        : ["failed", "blocked", "cancelled"].includes(graphStatus)
+          ? TASK_STATUS.CANCELLED
+          : null;
+    if (!terminalStatus) {
+      return { ok: false, reason: "graph_not_terminal" };
+    }
+    if (
+      !SAFE_HANDOFF_ID_PATTERN.test(String(runId || "")) ||
+      !SAFE_HANDOFF_ID_PATTERN.test(String(nodeId || "")) ||
+      !Number.isSafeInteger(Number(authorityGeneration)) ||
+      Number(authorityGeneration) < 1 ||
+      !SHA256_PATTERN.test(String(eventHead || "")) ||
+      !SHA256_PATTERN.test(String(revisionDigest || ""))
+    ) {
+      return { ok: false, reason: "invalid_graph_binding" };
+    }
+    let cleanEvidence;
+    try {
+      cleanEvidence = cloneValue(evidence);
+    } catch {
+      return { ok: false, reason: "invalid_graph_evidence" };
+    }
+    const binding = {
+      schema: "chainlesschain.team-graph-task-projection/v1",
+      runId: String(runId),
+      nodeId: String(nodeId),
+      graphStatus,
+      authorityGeneration: Number(authorityGeneration),
+      eventHead: String(eventHead),
+      revisionDigest: String(revisionDigest),
+      evidence: cleanEvidence,
+    };
+    const projectionDigest = digestValue(binding);
+    const id = this._byKey.get(key);
+    const task = id ? this._tasks.get(id) : null;
+    if (!task) return { ok: false, reason: "not_found" };
+    const prior = task.metadata?.canonicalGraphProjection || null;
+    if (prior?.projectionDigest === projectionDigest) {
+      return {
+        ok: true,
+        idempotent: true,
+        status: task.status,
+        projectionDigest,
+      };
+    }
+    if (
+      prior &&
+      (prior.runId !== binding.runId ||
+        prior.nodeId !== binding.nodeId ||
+        prior.revisionDigest !== binding.revisionDigest ||
+        prior.graphStatus !== binding.graphStatus)
+    ) {
+      return { ok: false, reason: "graph_projection_conflict" };
+    }
+    const snapshot = this._tasks.snapshot();
+    const stored = snapshot.tasks.find((candidate) => candidate.id === task.id);
+    if (!stored || stored.rev !== task.rev) {
+      return { ok: false, reason: "concurrent" };
+    }
+    const projectedAt = Number.isFinite(Number(now))
+      ? Number(now)
+      : this._now();
+    const metadata = {
+      ...stored.metadata,
+      lease: null,
+      canonicalGraphProjection: {
+        ...binding,
+        projectionDigest,
+        projectedAt,
+      },
+    };
+    delete metadata.adjudication;
+    if (terminalStatus === TASK_STATUS.COMPLETED) {
+      metadata.result = {
+        canonicalGraph: true,
+        terminalEvidence: cleanEvidence,
+      };
+      delete metadata.lastError;
+    } else {
+      metadata.lastError = `canonical Graph node settled ${graphStatus}`;
+    }
+    stored.status = terminalStatus;
+    stored.assignee = null;
+    stored.updatedAt = projectedAt;
+    stored.rev += 1;
+    stored.metadata = metadata;
+    stored.history = [
+      ...(stored.history || []),
+      {
+        ts: projectedAt,
+        actor: "graph-kernel",
+        action: "canonical-projection-repaired",
+        changes: ["status", "assignee", "metadata"],
+        graphStatus,
+        projectionDigest,
+      },
+    ];
+    this._tasks = SharedTaskList.restore(snapshot, { now: this._now });
+    this._rebuildIndexes();
+    if (terminalStatus === TASK_STATUS.COMPLETED) {
+      for (const dependent of this._dependentsByKey.get(key) || []) {
+        this._enqueueIfReady(dependent, projectedAt);
+      }
+    }
+    return { ok: true, status: terminalStatus, projectionDigest };
+  }
+
+  applyCanonicalHandoffProjection(
+    key,
+    { handoff: source, targetLease = null, now = this._now() } = {},
+  ) {
+    if (!source || typeof source !== "object") {
+      return { ok: false, reason: "invalid_handoff_projection" };
+    }
+    const id = normalizedHandoffId(source.id, () => null);
+    const fromHolder = normalizedHolder(source.fromHolder);
+    const toHolder = normalizedHolder(source.toHolder);
+    const revisionDigest = normalizedDigest(source.revisionDigest);
+    const authorityDigest = normalizedDigest(source.authorityDigest);
+    const artifactIds = normalizedArtifactIds(source.artifactIds);
+    const status = String(source.status || "");
+    const ttlMs = Number(source.ttlMs);
+    if (
+      !id ||
+      !fromHolder ||
+      !toHolder ||
+      fromHolder === toHolder ||
+      !revisionDigest ||
+      !authorityDigest ||
+      !artifactIds ||
+      !TEAM_CUSTODY_HANDOFF_STATUSES.includes(status) ||
+      !Number.isSafeInteger(ttlMs) ||
+      ttlMs <= 0 ||
+      ttlMs > MAX_HANDOFF_TTL_MS ||
+      source.taskKey !== key ||
+      typeof source.fromLeaseId !== "string" ||
+      source.fromLeaseId.length === 0 ||
+      !["string", "number"].includes(typeof source.fromFence)
+    ) {
+      return { ok: false, reason: "invalid_handoff_projection" };
+    }
+    let preconditions;
+    let summary;
+    try {
+      preconditions = cloneValue(source.preconditions);
+      summary = cloneValue(source.summary);
+    } catch {
+      return { ok: false, reason: "invalid_handoff_projection" };
+    }
+    const idempotencyKey = normalizedHandoffId(
+      source.idempotencyKey,
+      () => null,
+    );
+    if (!idempotencyKey) {
+      return { ok: false, reason: "invalid_handoff_projection" };
+    }
+    const binding = {
+      schema: TEAM_CUSTODY_HANDOFF_SCHEMA,
+      id,
+      taskKey: key,
+      fromHolder,
+      fromLeaseId: source.fromLeaseId,
+      fromFence: source.fromFence,
+      toHolder,
+      revisionDigest,
+      authorityDigest,
+      artifactIds,
+      preconditions,
+      summary,
+      idempotencyKey,
+      ttlMs,
+    };
+    const bindingDigest = digestValue(binding);
+    if (source.bindingDigest && source.bindingDigest !== bindingDigest) {
+      return { ok: false, reason: "handoff_binding_conflict" };
+    }
+    let cleanTargetLease = null;
+    if (status === "committed") {
+      try {
+        cleanTargetLease = cloneValue(targetLease || source.targetLease);
+      } catch {
+        return { ok: false, reason: "invalid_target_lease" };
+      }
+      if (
+        !cleanTargetLease ||
+        cleanTargetLease.holder !== toHolder ||
+        typeof cleanTargetLease.leaseId !== "string" ||
+        cleanTargetLease.leaseId.length === 0 ||
+        !Number.isFinite(Number(cleanTargetLease.expiresAt))
+      ) {
+        return { ok: false, reason: "invalid_target_lease" };
+      }
+    }
+    const taskId = this._byKey.get(key);
+    const task = taskId ? this._tasks.get(taskId) : null;
+    if (!task) return { ok: false, reason: "not_found" };
+    const history = handoffHistory(task);
+    const existing = history.find((entry) => entry.id === id);
+    if (existing && existing.bindingDigest !== bindingDigest) {
+      return { ok: false, reason: "handoff_binding_conflict" };
+    }
+    if (existing && existing.status !== status) {
+      const transitions = {
+        offered: new Set([
+          "accepted",
+          "rejected",
+          "committed",
+          "revoked",
+          "expired",
+        ]),
+        accepted: new Set(["committed", "revoked", "expired"]),
+      };
+      if (!transitions[existing.status]?.has(status)) {
+        return { ok: false, reason: "handoff_projection_regressed" };
+      }
+    }
+    if (existing?.status === status) {
+      return { ok: true, idempotent: true, handoff: cloneValue(existing) };
+    }
+    const projectedAt = Number.isFinite(Number(now))
+      ? Number(now)
+      : this._now();
+    const projected = {
+      ...(existing || binding),
+      ...binding,
+      bindingDigest,
+      expiresAtMs: Number(source.expiresAtMs),
+      status,
+      offeredAt: Number(source.offeredAt),
+      acceptedAt: source.acceptedAt == null ? null : Number(source.acceptedAt),
+      rejectedAt: source.rejectedAt == null ? null : Number(source.rejectedAt),
+      committedAt:
+        source.committedAt == null ? null : Number(source.committedAt),
+      revokedAt: source.revokedAt == null ? null : Number(source.revokedAt),
+      expiredAt: source.expiredAt == null ? null : Number(source.expiredAt),
+      targetStartedAt: existing?.targetStartedAt ?? null,
+      targetSettledAt: existing?.targetSettledAt ?? null,
+      targetSettlement: existing?.targetSettlement ?? null,
+      reason:
+        source.reason == null ? null : String(source.reason).slice(0, 1024),
+      acceptedByAttempt: existing?.acceptedByAttempt ?? null,
+      targetLease:
+        status === "committed"
+          ? cloneValue(existing?.targetLease || cleanTargetLease)
+          : null,
+      canonicalProjectedAt: projectedAt,
+      updatedAt: Number(source.updatedAt) || projectedAt,
+    };
+    if (existing) {
+      history[history.indexOf(existing)] = projected;
+    } else {
+      history.push(projected);
+      while (history.length > MAX_HANDOFF_HISTORY) history.shift();
+    }
+    const snapshot = this._tasks.snapshot();
+    const stored = snapshot.tasks.find((candidate) => candidate.id === task.id);
+    if (!stored || stored.rev !== task.rev) {
+      return { ok: false, reason: "concurrent" };
+    }
+    stored.rev += 1;
+    stored.updatedAt = projectedAt;
+    stored.metadata = { ...stored.metadata, custodyHandoffs: history };
+    if (
+      status === "committed" &&
+      ![TASK_STATUS.COMPLETED, TASK_STATUS.CANCELLED].includes(stored.status)
+    ) {
+      stored.status = TASK_STATUS.IN_PROGRESS;
+      stored.assignee = toHolder;
+      stored.metadata.lease = cloneValue(projected.targetLease);
+    } else if (
+      status === "expired" &&
+      stored.metadata?.lease?.leaseId === binding.fromLeaseId
+    ) {
+      stored.status = TASK_STATUS.PENDING;
+      stored.assignee = null;
+      stored.metadata.lease = null;
+    }
+    stored.history = [
+      ...(stored.history || []),
+      {
+        ts: projectedAt,
+        actor: "graph-kernel",
+        action: "canonical-handoff-projected",
+        changes: ["status", "assignee", "metadata"],
+        handoffId: id,
+        handoffStatus: status,
+      },
+    ];
+    this._tasks = SharedTaskList.restore(snapshot, { now: this._now });
+    this._rebuildIndexes();
+    return { ok: true, handoff: cloneValue(projected) };
+  }
+
   /** Bind a pending adjudication to its immutable durable case evidence. */
   bindAdjudicationCase(key, { caseId, registryDigest, sideEffectDigest } = {}) {
     const id = this._byKey.get(key);

package/src/lib/agent-team/team-agent-stream.js

@@ -7,6 +7,7 @@
  * are never copied into parser state or returned to callers.
  */
 
+import { createHash } from "node:crypto";
 import { TextDecoder } from "node:util";
 
 export const DEFAULT_TEAM_AGENT_MAX_LINE_BYTES = 1024 * 1024;
@@ -96,6 +97,7 @@ export class TeamAgentStreamParser {
   #tokenUsageEvents = 0;
   #usageByIdentity = new Map();
   #sawTerminalResult = false;
+  #terminalResultDigest = null;
   #finished = false;
   #failed = null;
   #finalSummary = null;
@@ -204,6 +206,16 @@ export class TeamAgentStreamParser {
     return this.#copyLiveSummary();
   }
 
+  /**
+   * Return an immutable digest of the exact terminal result record without
+   * retaining or exposing its prompt/result body.
+   */
+  terminalEvidence() {
+    return this.#terminalResultDigest
+      ? Object.freeze({ outputDigest: this.#terminalResultDigest })
+      : null;
+  }
+
   #copyLiveSummary() {
     return {
       provider: this.#provider,
@@ -291,6 +303,9 @@ export class TeamAgentStreamParser {
     }
     if (line.trim() === "") return;
 
+    const lineDigest = `sha256:${createHash("sha256")
+      .update(line, "utf8")
+      .digest("hex")}`;
     let event;
     try {
       event = JSON.parse(line);
@@ -345,6 +360,7 @@ export class TeamAgentStreamParser {
 
     if (event.type === "result") {
       this.#sawTerminalResult = true;
+      this.#terminalResultDigest = lineDigest;
       this.#lastResultProvider =
         typeof event.provider === "string" ? event.provider : this.#provider;
       this.#lastResultModel =