chainlesschain 0.166.2 → 0.166.3

package/src/lib/app-server/cli-agent-kernel-adapter.js

@@ -162,6 +162,7 @@ export class CliAgentKernelAdapter {
             type: "approval",
             id: event.id,
             approve: approvalBoolean(decision),
+            decision,
             binding: event.binding,
           });
         }

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

@@ -53,6 +53,49 @@ export function validateAppServerMessage(value) {
   });
 }
 
+const definitionSchemas = new Map();
+
+/** Validate one canonical $defs value without maintaining a second hand-written union. */
+export function validateAppServerDefinition(name, value) {
+  const definition = APP_SERVER_SCHEMA.$defs?.[name];
+  if (!definition) {
+    return Object.freeze({
+      ok: false,
+      errors: Object.freeze([
+        Object.freeze({
+          path: "#",
+          message: `unknown protocol definition ${String(name)}`,
+        }),
+      ]),
+    });
+  }
+  let definitionSchema = definitionSchemas.get(name);
+  if (!definitionSchema) {
+    definitionSchema = {
+      $schema: APP_SERVER_SCHEMA.$schema,
+      $ref: `#/$defs/${name}`,
+      $defs: APP_SERVER_SCHEMA.$defs,
+    };
+    definitionSchemas.set(name, definitionSchema);
+  }
+  const result = validate(value, definitionSchema);
+  return Object.freeze({
+    ok: result.valid,
+    errors: Object.freeze(
+      result.errors.map((error) =>
+        Object.freeze({
+          path: error.instancePath || error.schemaPath || "#",
+          message: error.message || error.code || "invalid value",
+        }),
+      ),
+    ),
+  });
+}
+
+export function validateApprovalDecision(value) {
+  return validateAppServerDefinition("ApprovalDecision", value);
+}
+
 export function rpcResult(id, result) {
   return { jsonrpc: "2.0", id, result: result ?? null };
 }

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

@@ -12,6 +12,7 @@ import {
   rpcError,
   rpcNotification,
   rpcResult,
+  validateApprovalDecision,
   validateAppServerMessage,
 } from "./protocol.js";
 
@@ -746,28 +747,24 @@ export class CcAppServer {
         ? event.risk
         : "high",
       reason: event.reason || "The Agent Kernel requires approval",
-      requestedPermissions: [],
+      requestedPermissions: Array.isArray(event.requested_permissions)
+        ? event.requested_permissions
+        : [],
     };
   }
 
   async _requestApproval(turn, event) {
     const request = this._approvalRequest(turn, event);
     const result = await this._requestClient("approval/decide", { request });
-    const decision = requireObject(result, "approval decision");
-    const allowed = new Set([
-      "acceptOnce",
-      "acceptForTurn",
-      "acceptForSession",
-      "decline",
-      "cancel",
-    ]);
-    if (!allowed.has(decision.kind)) {
+    const validation = validateApprovalDecision(result);
+    if (!validation.ok) {
       throw new JsonRpcError(
         JSON_RPC_ERROR.INVALID_PARAMS,
         "client returned an invalid approval decision",
+        { errors: validation.errors },
       );
     }
-    return decision;
+    return result;
   }
 
   async _completeTurn(turn, status, result) {

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

@@ -0,0 +1,187 @@
+import { createHash } from "node:crypto";
+import { validateAppServerDefinition } from "./app-server/protocol.js";
+
+export const APPROVAL_GRANTS_EVENT = "approval_grants";
+export const APPROVAL_GRANTS_SCHEMA = "chainlesschain.approval-grants/v1";
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => [key, stableValue(value[key])]),
+  );
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function boundedScope(value) {
+  const serialized = stableJson(value);
+  if (serialized.length <= 1024) return serialized;
+  return `sha256:${createHash("sha256").update(serialized).digest("hex")}`;
+}
+
+function boundedCapability(tool) {
+  const candidate = `tool:${String(tool || "unknown")}`;
+  if (candidate.length <= 128) return candidate;
+  return `tool:sha256:${createHash("sha256").update(candidate).digest("hex")}`;
+}
+
+export function approvalPermissionForContext(ctx = {}, { cwd = null } = {}) {
+  const tool = ctx.tool || ctx.toolName || ctx.name || "unknown";
+  const args =
+    ctx.args ?? (ctx.command != null ? { command: ctx.command } : null);
+  const policy = ctx.rule || ctx.riskLevel || ctx.risk || null;
+  return Object.freeze({
+    capability: boundedCapability(tool),
+    scope: boundedScope({ cwd: cwd || ctx.cwd || null, args, policy }),
+  });
+}
+
+function permissionKey(permission) {
+  return `${permission.capability}\0${permission.scope}`;
+}
+
+function livePermission(permission, now) {
+  const validation = validateAppServerDefinition("PermissionGrant", permission);
+  if (!validation.ok) return false;
+  return !permission.expiresAt || Date.parse(permission.expiresAt) > now;
+}
+
+function samePermission(left, right) {
+  return permissionKey(left) === permissionKey(right);
+}
+
+function normalizePersistedEntry(entry, now) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+  if (!livePermission(entry.permission, now)) return null;
+  if (
+    typeof entry.binding !== "string" ||
+    !entry.binding ||
+    typeof entry.grantedAt !== "string" ||
+    Number.isNaN(Date.parse(entry.grantedAt))
+  ) {
+    return null;
+  }
+  return Object.freeze({
+    permission: Object.freeze({ ...entry.permission }),
+    binding: entry.binding,
+    grantedAt: entry.grantedAt,
+  });
+}
+
+export class ApprovalGrantLedger {
+  constructor({ sessionId, now = () => Date.now() } = {}) {
+    if (!sessionId) throw new TypeError("approval grant sessionId is required");
+    this.sessionId = String(sessionId);
+    this.now = now;
+    this.turnId = null;
+    this.turnGrants = new Map();
+    this.sessionGrants = new Map();
+    this.revision = 0;
+  }
+
+  beginTurn(turnId) {
+    this.turnId = String(turnId);
+    this.turnGrants.clear();
+  }
+
+  allows(permission) {
+    const now = this.now();
+    const key = permissionKey(permission);
+    for (const grants of [this.turnGrants, this.sessionGrants]) {
+      const entry = grants.get(key);
+      if (!entry) continue;
+      if (livePermission(entry.permission, now)) return true;
+      grants.delete(key);
+    }
+    return false;
+  }
+
+  applyDecision(decision, requiredPermission, binding) {
+    if (
+      decision?.kind !== "acceptForTurn" &&
+      decision?.kind !== "acceptForSession"
+    ) {
+      return Object.freeze({
+        decision,
+        granted: Object.freeze([]),
+        persistedScope: false,
+      });
+    }
+    const candidates =
+      decision.permissions === undefined
+        ? [requiredPermission]
+        : decision.permissions;
+    const target =
+      decision.kind === "acceptForSession"
+        ? this.sessionGrants
+        : this.turnGrants;
+    const granted = candidates
+      .filter(
+        (permission) =>
+          livePermission(permission, this.now()) &&
+          samePermission(permission, requiredPermission) &&
+          (target.has(permissionKey(permission)) || target.size < 64),
+      )
+      .slice(0, 1)
+      .map((permission) => Object.freeze({ ...permission }));
+    const grantedAt = new Date(this.now()).toISOString();
+    for (const permission of granted) {
+      target.set(
+        permissionKey(permission),
+        Object.freeze({ permission, binding, grantedAt }),
+      );
+    }
+    if (granted.length) this.revision += 1;
+    return Object.freeze({
+      decision: Object.freeze({ ...decision, permissions: granted }),
+      granted: Object.freeze(granted),
+      persistedScope:
+        decision.kind === "acceptForSession" && granted.length > 0,
+    });
+  }
+
+  toJSON() {
+    return {
+      schema: APPROVAL_GRANTS_SCHEMA,
+      sessionId: this.sessionId,
+      revision: this.revision,
+      grants: [...this.sessionGrants.values()].map((entry) => ({
+        permission: { ...entry.permission },
+        binding: entry.binding,
+        grantedAt: entry.grantedAt,
+      })),
+    };
+  }
+
+  static fromJSON(value, { sessionId, now = () => Date.now() } = {}) {
+    const ledger = new ApprovalGrantLedger({ sessionId, now });
+    if (
+      !value ||
+      typeof value !== "object" ||
+      Array.isArray(value) ||
+      value.schema !== APPROVAL_GRANTS_SCHEMA ||
+      value.sessionId !== ledger.sessionId ||
+      !Number.isSafeInteger(value.revision) ||
+      value.revision < 0 ||
+      !Array.isArray(value.grants) ||
+      value.grants.length > 64
+    ) {
+      throw new TypeError("invalid persisted approval grant ledger");
+    }
+    for (const candidate of value.grants) {
+      const entry = normalizePersistedEntry(candidate, now());
+      if (!entry) {
+        throw new TypeError("invalid persisted approval grant entry");
+      }
+      ledger.sessionGrants.set(permissionKey(entry.permission), entry);
+    }
+    ledger.revision = value.revision;
+    return ledger;
+  }
+}

package/src/lib/session-message-fabric.js

@@ -38,11 +38,15 @@ export const SESSION_MESSAGE_RECEIPT_STATUSES = Object.freeze([
   "full",
   "rate_limited",
   "expired",
+  "read",
+  "processed",
+  "dead_letter",
 ]);
 
 export const SESSION_MESSAGE_FABRIC_LIMITS = Object.freeze({
   maxMessageBytes: 256 * 1024,
   maxPendingPerRecipient: 100,
+  maxPendingBytes: 32 * 1024 * 1024,
   maxReceiptHistory: 5_000,
   maxMessagesPerSenderWindow: 120,
   senderRateWindowMs: 60_000,
@@ -62,9 +66,21 @@ export const SESSION_MESSAGE_FABRIC_ERROR_CODES = Object.freeze({
 });
 
 const PENDING_STATUSES = new Set(["held", "delivered"]);
+const MESSAGE_STATUSES = new Set([
+  "delivered",
+  "held",
+  "refused",
+  "full",
+  "rate_limited",
+  "expired",
+]);
+const PROCESSING_STATUSES = new Set(["read", "processed", "dead_letter"]);
+const TERMINAL_PROCESSING_STATUSES = new Set(["processed", "dead_letter"]);
 const RECEIPT_STATUSES = new Set(SESSION_MESSAGE_RECEIPT_STATUSES);
 const POLICIES = new Set(SESSION_MESSAGE_POLICIES);
 const NAME_PATTERN = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/u;
+// Bounded ids explicitly reject ASCII control characters.
+// eslint-disable-next-line no-control-regex
 const ID_PATTERN = /^[^\u0000-\u001f\u007f]{1,256}$/u;
 const MESSAGE_ID_PATTERN = /^[a-zA-Z0-9._:-]{1,128}$/u;
 
@@ -324,6 +340,11 @@ function updateReceipt(state, message, status, reason, now) {
       updatedAt: now,
       idleNotifiedAt: null,
       readAt: null,
+      processedAt: null,
+      deadLetteredAt: null,
+      deliveryCount: 0,
+      consumerKey: null,
+      recipientAttempt: null,
     };
     state.receipts.push(receipt);
   } else {
@@ -402,6 +423,7 @@ function compactSettledMessages(state) {
   state.messages = state.messages.filter((message) => {
     if (!PENDING_STATUSES.has(message.status)) return false;
     if (message.acknowledgedAt == null) return true;
+    if (message.retainAfterAck === true) return true;
     if (message.notifyWhenIdle !== true) return false;
     const receipt = receiptFor(
       state,
@@ -413,6 +435,30 @@ function compactSettledMessages(state) {
   return state.messages.length !== before;
 }
 
+function trimRetainedSettledMessages(state, limit) {
+  const retained = state.messages
+    .filter(
+      (message) =>
+        message.retainAfterAck === true && message.acknowledgedAt != null,
+    )
+    .sort(
+      (left, right) =>
+        left.acknowledgedAt - right.acknowledgedAt ||
+        left.createdAt - right.createdAt ||
+        left.messageId.localeCompare(right.messageId),
+    );
+  let changed = false;
+  while (retained.length > limit) {
+    const target = retained.shift();
+    const index = state.messages.indexOf(target);
+    if (index >= 0) {
+      state.messages.splice(index, 1);
+      changed = true;
+    }
+  }
+  return changed;
+}
+
 function applyExpectedMessage(state, channel, message, recipient, now) {
   if (recipient.policy === "refuse") {
     updateReceipt(state, message, "refused", "policy_refuse", now);
@@ -556,7 +602,7 @@ function validateState(state) {
       !MESSAGE_ID_PATTERN.test(message?.messageId || "") ||
       !Number.isSafeInteger(message?.sequence) ||
       message.sequence < 1 ||
-      !RECEIPT_STATUSES.has(message?.status) ||
+      !MESSAGE_STATUSES.has(message?.status) ||
       !channelIds.has(message?.channelId) ||
       typeof message?.payloadDigest !== "string"
     ) {
@@ -572,6 +618,13 @@ function validateState(state) {
     ) {
       fail("invalid receipt");
     }
+    if (
+      receipt.deliveryCount != null &&
+      (!Number.isSafeInteger(receipt.deliveryCount) ||
+        receipt.deliveryCount < 0)
+    ) {
+      fail("invalid receipt delivery count");
+    }
   }
   const bucketAuthorities = new Set();
   for (const bucket of state.rateBuckets || []) {
@@ -606,6 +659,7 @@ export class SessionMessageFabric {
       lockTimeoutMs = 10_000,
       maxMessageBytes = SESSION_MESSAGE_FABRIC_LIMITS.maxMessageBytes,
       maxPendingPerRecipient = SESSION_MESSAGE_FABRIC_LIMITS.maxPendingPerRecipient,
+      maxPendingBytes = SESSION_MESSAGE_FABRIC_LIMITS.maxPendingBytes,
       maxReceiptHistory = SESSION_MESSAGE_FABRIC_LIMITS.maxReceiptHistory,
       maxMessagesPerSenderWindow = SESSION_MESSAGE_FABRIC_LIMITS.maxMessagesPerSenderWindow,
       senderRateWindowMs = SESSION_MESSAGE_FABRIC_LIMITS.senderRateWindowMs,
@@ -636,6 +690,10 @@ export class SessionMessageFabric {
         maxPendingPerRecipient,
         SESSION_MESSAGE_FABRIC_LIMITS.maxPendingPerRecipient,
       ),
+      maxPendingBytes: positiveInteger(
+        maxPendingBytes,
+        SESSION_MESSAGE_FABRIC_LIMITS.maxPendingBytes,
+      ),
       maxReceiptHistory: positiveInteger(
         maxReceiptHistory,
         SESSION_MESSAGE_FABRIC_LIMITS.maxReceiptHistory,
@@ -770,6 +828,10 @@ export class SessionMessageFabric {
           );
           const outcome = mutator(state, now) || { value: undefined };
           const compacted = compactSettledMessages(state);
+          const trimmedSettled = trimRetainedSettledMessages(
+            state,
+            this._limits.maxReceiptHistory,
+          );
           const trimmed = trimReceiptHistory(
             state,
             this._limits.maxReceiptHistory,
@@ -778,6 +840,7 @@ export class SessionMessageFabric {
             swept ||
             prunedRateBuckets ||
             compacted ||
+            trimmedSettled ||
             trimmed ||
             outcome.changed === true
           ) {
@@ -985,6 +1048,7 @@ export class SessionMessageFabric {
     sequence = null,
     ttlMs = this._limits.defaultTtlMs,
     notifyWhenIdle = false,
+    retainAfterAck = false,
   } = {}) {
     const id = messageId(requestedMessageId, this._createId);
     const cleanSubject = subject == null ? null : String(subject).slice(0, 512);
@@ -1108,6 +1172,7 @@ export class SessionMessageFabric {
         status: "held",
         reason: "out_of_order",
         notifyWhenIdle: notifyWhenIdle === true,
+        retainAfterAck: retainAfterAck === true,
         createdAt: now,
         updatedAt: now,
         deliveredAt: null,
@@ -1137,10 +1202,17 @@ export class SessionMessageFabric {
           value: clone(receiptFor(state, sender.authorityId, id)),
         };
       }
+      const pendingBytes = state.messages
+        .filter(
+          (entry) =>
+            PENDING_STATUSES.has(entry.status) && entry.acknowledgedAt == null,
+        )
+        .reduce((sum, entry) => sum + (entry.messageBytes || 0), 0);
       if (
         recipient.policy !== "refuse" &&
-        pendingForRecipient(state, recipient).length >=
-          this._limits.maxPendingPerRecipient
+        (pendingForRecipient(state, recipient).length >=
+          this._limits.maxPendingPerRecipient ||
+          pendingBytes + messageBytes > this._limits.maxPendingBytes)
       ) {
         updateReceipt(state, message, "full", "queue_capacity", now);
         return {
@@ -1194,6 +1266,196 @@ export class SessionMessageFabric {
     });
   }
 
+  /**
+   * Deliver an at-least-once batch without retiring it. This is deliberately
+   * separate from `inbox(..., { acknowledge: true })`, whose historical API
+   * means "read and remove". Processing callers must explicitly settle each
+   * message with `acknowledge()`.
+   */
+  receive(selector, { limit = 100, markRead = false } = {}) {
+    const boundedLimit = positiveInteger(limit, 100, 100);
+    return this._transaction((state, now) => {
+      const endpoint = requireEndpoint(state, selector);
+      const messages = pendingForRecipient(state, endpoint)
+        .filter((message) => message.status === "delivered")
+        .sort(
+          (left, right) =>
+            (left.senderAuthority === right.senderAuthority
+              ? left.sequence - right.sequence
+              : left.createdAt - right.createdAt) ||
+            left.senderAuthority.localeCompare(right.senderAuthority),
+        )
+        .slice(0, boundedLimit);
+      for (const message of messages) {
+        const receipt = receiptFor(
+          state,
+          message.senderAuthority,
+          message.messageId,
+        );
+        if (!receipt) continue;
+        receipt.deliveryCount = (receipt.deliveryCount || 0) + 1;
+        receipt.deliveredAt ||= message.deliveredAt || now;
+        if (markRead) {
+          receipt.status = "read";
+          receipt.readAt ||= now;
+        } else if (!PROCESSING_STATUSES.has(receipt.status)) {
+          receipt.status = "delivered";
+        }
+        receipt.updatedAt = now;
+      }
+      return {
+        changed: messages.length > 0,
+        value: clone(
+          messages.map((message) => ({
+            ...message,
+            delivery: receiptFor(
+              state,
+              message.senderAuthority,
+              message.messageId,
+            ),
+          })),
+        ),
+      };
+    });
+  }
+
+  /** Persist read/processed/dead-letter evidence for explicit physical ids. */
+  acknowledge(
+    selector,
+    {
+      messageIds = [],
+      consumerKey,
+      status = "processed",
+      reason = null,
+      recipientAttempt = null,
+    } = {},
+  ) {
+    if (
+      !Array.isArray(messageIds) ||
+      messageIds.length === 0 ||
+      messageIds.length > 100 ||
+      messageIds.some((id) => !MESSAGE_ID_PATTERN.test(String(id || ""))) ||
+      new Set(messageIds.map(String)).size !== messageIds.length
+    ) {
+      throw fabricError(
+        SESSION_MESSAGE_FABRIC_ERROR_CODES.INVALID_ARGUMENT,
+        "messageIds must contain 1-100 unique message identifiers",
+      );
+    }
+    if (!PROCESSING_STATUSES.has(status)) {
+      throw fabricError(
+        SESSION_MESSAGE_FABRIC_ERROR_CODES.INVALID_ARGUMENT,
+        "processing status must be read, processed or dead_letter",
+      );
+    }
+    const safeConsumerKey = boundedId(consumerKey, "consumerKey");
+    const safeAttempt =
+      recipientAttempt == null ? null : jsonBody(recipientAttempt).value;
+    const safeReason = String(reason || "poison_message").slice(0, 1024);
+    const ids = messageIds.map(String);
+    return this._transaction((state, now) => {
+      const endpoint = requireEndpoint(state, selector);
+      const plans = ids.map((id) => {
+        const receipt = state.receipts.find(
+          (candidate) =>
+            candidate.messageId === id &&
+            candidate.recipientAuthority === endpoint.authorityId &&
+            candidate.recipientEpoch === endpoint.epoch,
+        );
+        const message = state.messages.find(
+          (candidate) =>
+            candidate.messageId === id &&
+            candidate.recipientAuthority === endpoint.authorityId &&
+            candidate.recipientEpoch === endpoint.epoch,
+        );
+        if (
+          !receipt ||
+          (!message && !TERMINAL_PROCESSING_STATUSES.has(receipt.status))
+        ) {
+          throw fabricError(
+            SESSION_MESSAGE_FABRIC_ERROR_CODES.INVALID_ARGUMENT,
+            `message is not addressed to the active recipient: ${id}`,
+          );
+        }
+        if (TERMINAL_PROCESSING_STATUSES.has(receipt.status)) {
+          if (receipt.consumerKey !== safeConsumerKey) {
+            throw fabricError(
+              SESSION_MESSAGE_FABRIC_ERROR_CODES.MESSAGE_ID_CONFLICT,
+              `message was settled by another consumer: ${id}`,
+            );
+          }
+          if (receipt.status !== status) {
+            throw fabricError(
+              SESSION_MESSAGE_FABRIC_ERROR_CODES.MESSAGE_ID_CONFLICT,
+              `message already has terminal status ${receipt.status}: ${id}`,
+            );
+          }
+          return { receipt, message, replay: true };
+        }
+        return { receipt, message, replay: false };
+      });
+      const receipts = [];
+      for (const plan of plans) {
+        const { receipt, message, replay } = plan;
+        if (replay) {
+          receipts.push(clone(receipt));
+          continue;
+        }
+        receipt.status = status;
+        receipt.consumerKey = safeConsumerKey;
+        receipt.recipientAttempt = safeAttempt;
+        receipt.updatedAt = now;
+        if (status === "read") receipt.readAt ||= now;
+        if (status === "processed") {
+          receipt.readAt ||= now;
+          receipt.processedAt ||= now;
+          message.acknowledgedAt = now;
+        }
+        if (status === "dead_letter") {
+          receipt.deadLetteredAt ||= now;
+          receipt.reason = safeReason;
+          message.acknowledgedAt = now;
+        }
+        receipts.push(clone(receipt));
+      }
+      return { changed: plans.some((plan) => !plan.replay), value: receipts };
+    });
+  }
+
+  /** Bounded retained history for authoritative adapters and audit reducers. */
+  history() {
+    return this._transaction((state) => ({
+      value: clone(
+        state.messages.sort(
+          (left, right) =>
+            left.createdAt - right.createdAt ||
+            left.messageId.localeCompare(right.messageId),
+        ),
+      ),
+    }));
+  }
+
+  /**
+   * One-revision authority view for host adapters and deterministic reducers.
+   * Unlike a sequence of projection/history/receipt reads, this cannot combine
+   * fields from different concurrent commits.
+   */
+  auditSnapshot() {
+    return this._transaction((state) => ({
+      value: {
+        schema: SESSION_MESSAGE_FABRIC_SCHEMA,
+        version: state.version,
+        authority: "cli",
+        revision: state.revision,
+        digest: state.digest,
+        limits: clone(this._limits),
+        endpoints: clone(state.endpoints),
+        messages: clone(state.messages),
+        receipts: clone(state.receipts),
+      },
+    }));
+  }
+
   receipts(selector) {
     return this._transaction((state) => {
       const endpoint = requireEndpoint(state, selector);