chainlesschain 0.166.7 → 0.166.10

package/src/lib/app-server/graph-runtime.js

@@ -6,6 +6,11 @@ import {
 import { createGraphAuthorityBinding } from "../graph-kernel/authority.js";
 import { GraphEventStore } from "../graph-kernel/event-store.js";
 import { GraphKernel } from "../graph-kernel/runtime.js";
+import {
+  diffGraphTrace,
+  locateBlockedRoot,
+  reduceGraphTrace,
+} from "../graph-kernel/trace-reducer.js";
 
 const TERMINAL = new Set([
   "succeeded",
@@ -19,6 +24,10 @@ const TERMINAL = new Set([
   "compensation_failed",
 ]);
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const DEFAULT_HISTORY_EVENT_LIMIT = 1_000;
+const MAX_HISTORY_EVENT_LIMIT = 2_000;
+const DEFAULT_HISTORY_SNAPSHOT_LIMIT = 200;
+const MAX_HISTORY_SNAPSHOT_LIMIT = 200;
 
 function runtimeError(code, message, details = {}) {
   const error = new Error(message);
@@ -73,6 +82,51 @@ function nodeInput(inputs, nodeId) {
   return { prompt: "" };
 }
 
+function boundedInteger(value, fallback, { min = 0, max } = {}) {
+  if (value === undefined || value === null) return fallback;
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < min || number > max) {
+    throw runtimeError(
+      "CC_GRAPH_HISTORY_RANGE_INVALID",
+      `Graph history range must be an integer between ${min} and ${max}`,
+    );
+  }
+  return number;
+}
+
+function debuggerProjection(projection) {
+  return Object.freeze({
+    ...projection,
+    timeline: Object.freeze(
+      (projection.timeline || []).map((event) =>
+        Object.freeze({
+          seq: event.seq,
+          timestamp: event.timestamp,
+          type: event.type,
+          hash: event.hash,
+        }),
+      ),
+    ),
+    effects: Object.freeze(
+      (projection.effects || []).map((effect) =>
+        Object.freeze({
+          id: effect.id,
+          nodeId: effect.nodeId ?? null,
+          attemptId: effect.attemptId ?? null,
+          status: effect.status,
+          iterationPath: Object.freeze([...(effect.iterationPath || [])]),
+          receiptDigest: DIGEST.test(
+            String(effect.receipt?.receiptDigest || ""),
+          )
+            ? effect.receipt.receiptDigest
+            : null,
+          compensationEffectId: effect.compensationEffectId ?? null,
+        }),
+      ),
+    ),
+  });
+}
+
 /**
  * Host-owned Graph executor used by fixed App Server capabilities. GraphKernel
  * owns ready/attempt/effect/terminal state; the injected executor owns only a
@@ -85,6 +139,7 @@ export class AppServerGraphRuntime {
       ? new GraphEventStore({ rolloutStore })
       : new GraphEventStore(),
     executeNode,
+    requestHumanTask = null,
     now = Date.now,
     createId = randomUUID,
     onEvent = null,
@@ -96,6 +151,8 @@ export class AppServerGraphRuntime {
     this.eventStore = eventStore;
     this.rolloutStore = eventStore.rolloutStore;
     this.executeNode = executeNode;
+    this.requestHumanTask =
+      typeof requestHumanTask === "function" ? requestHumanTask : null;
     this.now = now;
     this.createId = createId;
     this.onEvent = typeof onEvent === "function" ? onEvent : null;
@@ -161,6 +218,9 @@ export class AppServerGraphRuntime {
       persistence: "durable",
       isolated: true,
       terminalEvidence: true,
+      durableHumanTasks: true,
+      humanTaskQuorum: true,
+      humanTaskSeparationOfDuties: true,
       authorityModes: Object.freeze(["shadow", "canonical"]),
       featureGated: true,
     });
@@ -206,7 +266,8 @@ export class AppServerGraphRuntime {
     const compiled = compileGraphDefinition(definition);
     const id = String(runId);
     const request = {
-      definition: compiled.definition,
+      definition:
+        compiled.definitionMigration?.backupDefinition || compiled.definition,
       inputs: { ...inputs },
       originSurface,
       agentCapacity: Math.max(1, Number(agentCapacity) || 1),
@@ -323,11 +384,23 @@ export class AppServerGraphRuntime {
         this._emit(runId, "graph/run-settled", { projection: status });
         return status;
       }
+      const pendingHumanTask = kernel
+        .humanTasks(runId)
+        .find((task) => ["open", "claimed"].includes(task.status));
+      if (pendingHumanTask) {
+        if (!this.requestHumanTask) return status;
+        await this._requestHumanTaskDecision(entry, pendingHumanTask);
+        continue;
+      }
       const next = kernel
         .readyNodes(runId)
         .find((candidate) => candidate.dispatch !== "subgraph");
       if (!next) return status;
-      await this._executeAttempt(entry, next.nodeId);
+      if (entry.compiled.nodes[next.nodeId]?.kind === "human") {
+        await this._executeHumanTask(entry, next.nodeId);
+      } else {
+        await this._executeAttempt(entry, next.nodeId);
+      }
     }
     throw runtimeError(
       "CC_GRAPH_DRIVE_LIMIT",
@@ -335,6 +408,157 @@ export class AppServerGraphRuntime {
     );
   }
 
+  async _executeHumanTask(entry, nodeId) {
+    const { kernel } = entry;
+    const runId = entry.runId;
+    const node = entry.compiled.nodes[nodeId];
+    if (node.effectClass !== "none") {
+      throw runtimeError(
+        "CC_GRAPH_HUMAN_TASK_EFFECT_UNSUPPORTED",
+        "HumanTask nodes must use effectClass=none; approved effects belong to a dependent task node",
+      );
+    }
+    const attempt = kernel.assignNode(runId, nodeId, "app-server-agent", {
+      ttlMs: this.writerLeaseTtlMs,
+      leaseId: `app-server-human-attempt:${this.createId()}`,
+      grant: { executor: "durable_human_task", originSurface: "desktop" },
+    });
+    const quorum =
+      node.join === "quorum" ? Math.max(1, Number(node.quorum) || 1) : 1;
+    const task = kernel.createHumanTask(runId, {
+      humanTaskId: `app-server-human-task:${this.createId()}`,
+      attemptId: attempt.id,
+      leaseId: attempt.leaseId,
+      fence: attempt.fence,
+      operation: nodeInput(entry.inputs, nodeId),
+      nonce: `app-server-human-nonce:${this.createId()}`,
+      ttlMs: this.writerLeaseTtlMs,
+      quorum,
+      // Product quorum is intentionally fail-closed: one identity can never
+      // contribute more than one vote to a multi-review HumanTask.
+      separationOfDuties: quorum > 1,
+    });
+    this._emit(runId, "graph/human-task-requested", {
+      nodeId,
+      humanTaskId: task.id,
+      quorum: task.quorum,
+      separationOfDuties: task.separationOfDuties,
+    });
+    if (!this.requestHumanTask) {
+      return kernel.getRun(runId);
+    }
+    return this._requestHumanTaskDecision(entry, task);
+  }
+
+  async _requestHumanTaskDecision(entry, task) {
+    const { kernel, runId } = entry;
+    const response = await this.requestHumanTask({ task });
+    if (!response || typeof response !== "object" || Array.isArray(response)) {
+      throw runtimeError(
+        "CC_GRAPH_HUMAN_DECISION_INVALID",
+        "HumanTask client returned no structured decision",
+      );
+    }
+    for (const [field, expected] of [
+      ["humanTaskId", task.id],
+      ["runId", runId],
+      ["revisionDigest", task.revisionDigest],
+      ["operationDigest", task.operationDigest],
+      ["nonce", task.nonce],
+    ]) {
+      if (response[field] !== expected) {
+        throw runtimeError(
+          "CC_GRAPH_HUMAN_TASK_BINDING_MISMATCH",
+          `HumanTask client response does not match ${field}`,
+        );
+      }
+    }
+    const actorId = String(response.actorId || "").trim();
+    if (!actorId) {
+      throw runtimeError(
+        "CC_GRAPH_HUMAN_DECISION_INVALID",
+        "HumanTask client response requires an authenticated actorId",
+      );
+    }
+    if (
+      task.separationOfDuties === true &&
+      task.decisions.some((entry) => entry.actorId === actorId)
+    ) {
+      throw runtimeError(
+        "CC_GRAPH_HUMAN_SEPARATION_OF_DUTIES",
+        "HumanTask requires a different authenticated actor",
+      );
+    }
+    const claim = kernel.claimHumanTask(runId, task.id, actorId, {
+      claimLeaseId: `app-server-human-claim:${this.createId()}`,
+      ttlMs: Math.min(this.writerLeaseTtlMs, 5 * 60 * 1000),
+    });
+    const decided = kernel.decideHumanTask(runId, task.id, {
+      actorId,
+      claimLeaseId: claim.claimLeaseId,
+      revisionDigest: response.revisionDigest,
+      operationDigest: response.operationDigest,
+      nonce: response.nonce,
+      decision: response.decision,
+    });
+    this._emit(runId, "graph/human-task-decided", {
+      nodeId: decided.nodeId,
+      humanTaskId: decided.id,
+      actorId,
+      status: decided.status,
+      acceptedDecisions: decided.decisions.filter((entry) =>
+        ["acceptOnce", "acceptForTurn", "acceptForSession"].includes(
+          entry.decision.kind,
+        ),
+      ).length,
+      quorum: decided.quorum,
+    });
+    if (
+      decided.status !== "decided" ||
+      ["decline", "cancel"].includes(decided.decision?.kind)
+    ) {
+      return kernel.getRun(runId);
+    }
+    const settlement = kernel.assignNode(
+      runId,
+      decided.nodeId,
+      "app-server-agent",
+      {
+        ttlMs: this.writerLeaseTtlMs,
+        leaseId: `app-server-human-settlement:${this.createId()}`,
+        grant: {
+          executor: "durable_human_task_decision",
+          humanTaskId: decided.id,
+        },
+      },
+    );
+    const settled = kernel.settleAttempt(runId, {
+      attemptId: settlement.id,
+      leaseId: settlement.leaseId,
+      fence: settlement.fence,
+      outcome: "succeeded",
+      evidence: {
+        outputDigest: graphDigest(
+          {
+            humanTaskId: decided.id,
+            revisionDigest: decided.revisionDigest,
+            operationDigest: decided.operationDigest,
+            decisions: decided.decisions,
+          },
+          "cc.app-server.human-task-settlement/v1",
+        ),
+      },
+      usage: { turns: 0, tokens: 0, costUsd: 0, wallMs: 0 },
+    });
+    this._emit(runId, "graph/node-settled", {
+      nodeId: decided.nodeId,
+      attemptId: settlement.id,
+      outcome: "succeeded",
+      humanTaskId: decided.id,
+    });
+    return settled;
+  }
+
   async _executeAttempt(entry, nodeId) {
     const { kernel } = entry;
     const runId = entry.runId;
@@ -451,6 +675,106 @@ export class AppServerGraphRuntime {
     return entry.kernel.getRun(id);
   }
 
+  humanTasks(runId) {
+    const id = String(runId);
+    const entry = this.runs.get(id) || this._recover(id);
+    return entry.kernel.humanTasks(id);
+  }
+
+  history(
+    runId,
+    {
+      afterSeq = 0,
+      limit = DEFAULT_HISTORY_EVENT_LIMIT,
+      snapshotLimit = DEFAULT_HISTORY_SNAPSHOT_LIMIT,
+    } = {},
+  ) {
+    const id = String(runId);
+    const cursor = boundedInteger(afterSeq, 0, {
+      min: 0,
+      max: Number.MAX_SAFE_INTEGER,
+    });
+    const eventLimit = boundedInteger(limit, DEFAULT_HISTORY_EVENT_LIMIT, {
+      min: 1,
+      max: MAX_HISTORY_EVENT_LIMIT,
+    });
+    const projectionLimit = boundedInteger(
+      snapshotLimit,
+      DEFAULT_HISTORY_SNAPSHOT_LIMIT,
+      { min: 1, max: MAX_HISTORY_SNAPSHOT_LIMIT },
+    );
+    const head = this.eventStore.head(id);
+    const effectiveCursor =
+      cursor === 0 && head.seq > eventLimit ? head.seq - eventLimit : cursor;
+    const selected = this.eventStore.read(id, {
+      afterSeq: effectiveCursor,
+      limit: eventLimit + 1,
+    });
+    const hasMore = selected.length > eventLimit;
+    const events = selected.slice(0, eventLimit);
+    const stateEvents = events.filter(
+      (event) => event.payload?.state?.version === 1,
+    );
+    if (stateEvents.length === 0) {
+      throw runtimeError(
+        "CC_GRAPH_TRACE_STATE_MISSING",
+        `Graph history has no runtime snapshot after sequence ${effectiveCursor}: ${id}`,
+      );
+    }
+    const snapshotEvents = stateEvents.slice(-projectionLimit);
+    const snapshots = snapshotEvents.map((event) => {
+      const through = events.filter((candidate) => candidate.seq <= event.seq);
+      return Object.freeze({
+        seq: event.seq,
+        timestamp: event.timestamp,
+        type: event.type,
+        hash: event.hash,
+        projection: debuggerProjection(reduceGraphTrace(through)),
+      });
+    });
+    const diffs = snapshots
+      .slice(1)
+      .map((snapshot, index) =>
+        diffGraphTrace(snapshots[index].projection, snapshot.projection),
+      );
+    const current = snapshots.at(-1).projection;
+    const blockedRoots = Object.freeze(
+      current.taskGraph.nodes
+        .filter((node) => node.blockedRoot)
+        .map((node) =>
+          Object.freeze({
+            nodeId: node.id,
+            ...locateBlockedRoot(current, node.id),
+          }),
+        ),
+    );
+    return Object.freeze({
+      schema: "chainlesschain.graph-debug-history/v1",
+      runId: id,
+      requestedAfterSeq: cursor,
+      afterSeq: effectiveCursor,
+      nextAfterSeq: events.at(-1)?.seq || effectiveCursor,
+      hasMore,
+      truncatedBefore: effectiveCursor > cursor,
+      truncatedSnapshots: stateEvents.length > projectionLimit,
+      eventCount: events.length,
+      events: Object.freeze(
+        events.map((event) =>
+          Object.freeze({
+            seq: event.seq,
+            timestamp: event.timestamp,
+            type: event.type,
+            hash: event.hash,
+          }),
+        ),
+      ),
+      snapshots: Object.freeze(snapshots),
+      diffs: Object.freeze(diffs),
+      blockedRoots,
+      current,
+    });
+  }
+
   _recover(runId) {
     let events;
     try {

package/src/lib/app-server/server.js

@@ -132,6 +132,7 @@ export class CcAppServer {
         now,
         createId,
         executeNode: (context) => this._executeGraphNode(context),
+        requestHumanTask: (context) => this._requestHumanTask(context),
         onEvent: (event) => {
           void this._notify("graph/event", event).catch(() => {});
         },
@@ -295,6 +296,7 @@ export class CcAppServer {
       "graph/compile": () => this._graphCompile(message.params),
       "graph/run": () => this._graphRun(message.params),
       "graph/status": () => this._graphStatus(message.params),
+      "graph/history": () => this._graphHistory(message.params),
       "graph/cancel": () => this._graphCancel(message.params),
       "graph/reconcile": () => this._graphReconcile(message.params),
     };
@@ -360,6 +362,17 @@ export class CcAppServer {
       definitionId: compiled.definitionId,
       revision: compiled.revision,
       revisionDigest: compiled.revisionDigest,
+      migratedFrom: compiled.migratedFrom,
+      definitionMigration: compiled.definitionMigration
+        ? {
+            schema: compiled.definitionMigration.schema,
+            fromVersion: compiled.definitionMigration.fromVersion,
+            toVersion: compiled.definitionMigration.toVersion,
+            revisionDigest: compiled.definitionMigration.revisionDigest,
+            rollbackDigest: compiled.definitionMigration.rollbackDigest,
+            backupAvailable: true,
+          }
+        : null,
       topologicalOrder: [...compiled.topologicalOrder],
     };
   }
@@ -387,6 +400,15 @@ export class CcAppServer {
     return this.graphRuntime.status(requiredString(params.runId, "runId"));
   }
 
+  _graphHistory(rawParams) {
+    const params = requireObject(rawParams);
+    return this.graphRuntime.history(requiredString(params.runId, "runId"), {
+      afterSeq: params.afterSeq,
+      limit: params.limit,
+      snapshotLimit: params.snapshotLimit,
+    });
+  }
+
   _graphCancel(rawParams) {
     const params = requireObject(rawParams);
     return this.graphRuntime.cancel(
@@ -909,6 +931,44 @@ export class CcAppServer {
     return result;
   }
 
+  async _requestHumanTask({ task }) {
+    const result = await this._requestClient("humanTask/decide", { task });
+    const response = requireObject(result, "humanTask decision");
+    const validation = validateApprovalDecision(response.decision);
+    const bindings = [
+      ["humanTaskId", task.id],
+      ["runId", task.runId],
+      ["revisionDigest", task.revisionDigest],
+      ["operationDigest", task.operationDigest],
+      ["nonce", task.nonce],
+    ];
+    if (
+      !validation.ok ||
+      typeof response.actorId !== "string" ||
+      !/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,159}$/u.test(response.actorId) ||
+      Object.keys(response).some(
+        (field) =>
+          ![
+            "humanTaskId",
+            "runId",
+            "revisionDigest",
+            "operationDigest",
+            "nonce",
+            "actorId",
+            "decision",
+          ].includes(field),
+      ) ||
+      bindings.some(([field, expected]) => response[field] !== expected)
+    ) {
+      throw new JsonRpcError(
+        JSON_RPC_ERROR.INVALID_PARAMS,
+        "client returned an invalid or stale HumanTask decision",
+        { errors: validation.errors },
+      );
+    }
+    return response;
+  }
+
   async _completeTurn(turn, status, result) {
     if (TERMINAL_TURN_STATUSES.has(turn.status)) return;
     if (turn.assistantStarted) {

package/src/lib/approval-grant-ledger.js

@@ -46,6 +46,14 @@ function permissionKey(permission) {
   return `${permission.capability}\0${permission.scope}`;
 }
 
+function grantId(sessionId, lifetime, permission) {
+  return `grant_${createHash("sha256")
+    .update(
+      `${String(sessionId)}\0${String(lifetime)}\0${permissionKey(permission)}`,
+    )
+    .digest("hex")}`;
+}
+
 function livePermission(permission, now) {
   const validation = validateAppServerDefinition("PermissionGrant", permission);
   if (!validation.ok) return false;
@@ -102,6 +110,67 @@ export class ApprovalGrantLedger {
     return false;
   }
 
+  listGrants() {
+    const now = this.now();
+    const grants = [];
+    for (const [lifetime, entries] of [
+      ["turn", this.turnGrants],
+      ["session", this.sessionGrants],
+    ]) {
+      for (const [key, entry] of entries) {
+        if (!livePermission(entry.permission, now)) {
+          entries.delete(key);
+          continue;
+        }
+        grants.push(
+          Object.freeze({
+            grantId: grantId(this.sessionId, lifetime, entry.permission),
+            lifetime,
+            permission: Object.freeze({ ...entry.permission }),
+            binding: entry.binding,
+            grantedAt: entry.grantedAt,
+            ...(lifetime === "turn" ? { turnId: this.turnId } : {}),
+          }),
+        );
+      }
+    }
+    return Object.freeze(grants);
+  }
+
+  revoke(grantIdValue) {
+    const requestedId = String(grantIdValue || "");
+    for (const [lifetime, entries] of [
+      ["turn", this.turnGrants],
+      ["session", this.sessionGrants],
+    ]) {
+      for (const [key, entry] of entries) {
+        if (
+          grantId(this.sessionId, lifetime, entry.permission) !== requestedId
+        ) {
+          continue;
+        }
+        entries.delete(key);
+        if (lifetime === "session") this.revision += 1;
+        return Object.freeze({
+          revoked: true,
+          persistedScope: lifetime === "session",
+          grant: Object.freeze({
+            grantId: requestedId,
+            lifetime,
+            permission: Object.freeze({ ...entry.permission }),
+            binding: entry.binding,
+            grantedAt: entry.grantedAt,
+          }),
+        });
+      }
+    }
+    return Object.freeze({
+      revoked: false,
+      persistedScope: false,
+      grant: null,
+    });
+  }
+
   applyDecision(decision, requiredPermission, binding) {
     if (
       decision?.kind !== "acceptForTurn" &&

package/src/lib/codex-app-server-adapter.js

@@ -2,6 +2,11 @@ import { EventEmitter } from "node:events";
 
 export const CODEX_APP_SERVER_PROTOCOL = "codex-app-server-experimental-v1";
 export const CODEX_APP_SERVER_FEATURE_FLAG = "CC_EXPERIMENTAL_CODEX_APP_SERVER";
+export const CODEX_APP_SERVER_COMPATIBILITY_MATRIX = Object.freeze([
+  Object.freeze({ version: "0.149.0" }),
+  Object.freeze({ version: "0.150.0" }),
+  Object.freeze({ version: "0.150.1" }),
+]);
 
 function adapterError(code, message, details = {}) {
   const error = new Error(message);
@@ -12,30 +17,16 @@ function adapterError(code, message, details = {}) {
 }
 
 function parseVersion(value) {
-  const match = String(value || "").match(/(\d+)\.(\d+)\.(\d+)/u);
-  return match ? match.slice(1).map(Number) : null;
-}
-
-function compareVersion(left, right) {
-  for (let index = 0; index < 3; index += 1) {
-    if (left[index] !== right[index]) return left[index] - right[index];
-  }
-  return 0;
+  const match = String(value || "")
+    .trim()
+    .match(/^(?:codex(?:-cli)?\s+)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u);
+  return match ? match.slice(1).map(Number).join(".") : null;
 }
 
 export function isCodexAppServerVersionCompatible(version, matrix = []) {
   const parsed = parseVersion(version);
   if (!parsed || !Array.isArray(matrix) || matrix.length === 0) return false;
-  return matrix.some((range) => {
-    const minimum = parseVersion(range.min);
-    const maximum = parseVersion(range.maxExclusive);
-    return (
-      minimum &&
-      maximum &&
-      compareVersion(parsed, minimum) >= 0 &&
-      compareVersion(parsed, maximum) < 0
-    );
-  });
+  return matrix.some((entry) => parseVersion(entry?.version) === parsed);
 }
 
 function projectNotification(notification) {
@@ -103,7 +94,7 @@ export class CodexAppServerAdapter extends EventEmitter {
     client,
     fallback,
     upstreamVersion,
-    compatibilityMatrix = [],
+    compatibilityMatrix = CODEX_APP_SERVER_COMPATIBILITY_MATRIX,
     enabled = process.env[CODEX_APP_SERVER_FEATURE_FLAG] === "1",
     timeoutMs = 120_000,
   } = {}) {