chainlesschain 0.162.188 → 0.162.189

package/src/lib/managed-checkpoint-render.js

@@ -0,0 +1,60 @@
+const MANAGED_EVENT_TYPES = new Set([
+  "managed-checkpoint",
+  "managed-checkpoint-settled",
+  "managed-checkpoint-error",
+]);
+
+function token(value, maxLength = 96) {
+  if (value == null) return null;
+  const normalized = String(value)
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/[^\p{L}\p{N}._:/@+-]+/gu, "_")
+    .slice(0, maxLength);
+  return normalized || null;
+}
+
+function shortDigest(value) {
+  const normalized = token(value, 96);
+  if (!normalized) return null;
+  return normalized.length > 24 ? `${normalized.slice(0, 24)}...` : normalized;
+}
+
+/**
+ * Render only bounded checkpoint metadata. Tool arguments, file contents,
+ * arbitrary event fields and raw failure messages are intentionally omitted.
+ */
+export function formatManagedCheckpointEvent(event) {
+  if (!event || !MANAGED_EVENT_TYPES.has(event.type)) return null;
+
+  const parts = ["[managed checkpoint]"];
+  if (event.type === "managed-checkpoint-error") {
+    parts.push(
+      event.recovery_required === true
+        ? "recovery required"
+        : event.phase === "prepare"
+          ? "preparation blocked"
+          : "settlement failed",
+    );
+  } else {
+    parts.push(token(event.phase, 32) || "status");
+  }
+
+  const tool = token(event.tool, 96);
+  const coverage = token(event.coverage, 16);
+  const fileCoverage = token(event.file_coverage, 16);
+  const reason = token(event.reason, 128);
+  const code = token(event.code, 96);
+  const transactionId = token(event.transaction_id, 96);
+  const checkpointId = token(event.id || event.checkpoint_id, 96);
+  const evidenceDigest = shortDigest(event.evidence_digest);
+
+  if (tool) parts.push(`tool=${tool}`);
+  if (coverage) parts.push(`coverage=${coverage}`);
+  if (fileCoverage) parts.push(`files=${fileCoverage}`);
+  if (reason) parts.push(`reason=${reason}`);
+  if (code) parts.push(`code=${code}`);
+  if (transactionId) parts.push(`transaction=${transactionId}`);
+  if (checkpointId) parts.push(`checkpoint=${checkpointId}`);
+  if (evidenceDigest) parts.push(`evidence=${evidenceDigest}`);
+  return `  ${parts.join(" ")}`;
+}

package/src/lib/managed-tool-checkpoint.js

@@ -0,0 +1,194 @@
+/**
+ * Agent tool adapter for Process Broker workspace transactions.
+ *
+ * This module deliberately keeps policy separate from the transaction engine:
+ * callers opt in, provide the trusted workspace root, and decide whether they
+ * can assert an exclusive-writer contract. Unknown/background/external-host
+ * writers are reported as coverage=none instead of being wrapped in a
+ * misleading "recoverable" checkpoint.
+ */
+
+import { WORKSPACE_TRANSACTION_COVERAGE } from "./process-execution-broker/workspace-transaction.js";
+
+export const MANAGED_TOOL_CHECKPOINT_ERROR = Object.freeze({
+  INVALID_ARGUMENT: "MANAGED_TOOL_CHECKPOINT_INVALID_ARGUMENT",
+  SETTLEMENT_FAILED: "MANAGED_TOOL_CHECKPOINT_SETTLEMENT_FAILED",
+});
+
+const DIRECT_FILE_ONLY_TOOLS = new Set([
+  "write_file",
+  "edit_file",
+  "edit_file_hashed",
+  "delete_file",
+  "move_file",
+  "notebook_edit",
+]);
+
+const DEFAULT_READ_ONLY_TOOLS = new Set([
+  "read_file",
+  "search_files",
+  "code_intelligence",
+  "list_dir",
+  "list_skills",
+  "search_sessions",
+]);
+
+function checkpointError(code, message, details = {}, cause = null) {
+  const error = new Error(message, cause ? { cause } : undefined);
+  error.name = "ManagedToolCheckpointError";
+  error.code = code;
+  Object.assign(error, details);
+  return error;
+}
+
+function boundedBinding(value, fallback) {
+  const text =
+    typeof value === "string" && value.trim() ? value.trim() : fallback;
+  return text.slice(0, 256);
+}
+
+function isBackgroundTool(toolName, toolArgs = {}) {
+  if (toolName === "run_shell") return toolArgs.run_in_background === true;
+  if (toolName === "spawn_sub_agent") {
+    return (
+      toolArgs.run_in_background === true ||
+      toolArgs.background === true ||
+      toolArgs.mode === "background"
+    );
+  }
+  return false;
+}
+
+function skippedCheckpoint(reason, toolName) {
+  return Object.freeze({
+    skipped: true,
+    toolName,
+    coverage: WORKSPACE_TRANSACTION_COVERAGE.NONE,
+    fileCoverage: WORKSPACE_TRANSACTION_COVERAGE.NONE,
+    reason,
+  });
+}
+
+/**
+ * Prepare one managed checkpoint before a mutating agent tool call.
+ *
+ * A returned `skipped:true` result is an intentional coverage decision, not an
+ * error. Transaction preparation errors throw and must block strict callers
+ * before the tool is allowed to mutate the workspace.
+ */
+export function beginManagedToolCheckpoint(options = {}) {
+  if (options.enabled !== true) return null;
+  const toolName = boundedBinding(options.toolName, "unknown-tool");
+  const readOnly =
+    options.readOnly === true ||
+    (options.readOnly !== false && DEFAULT_READ_ONLY_TOOLS.has(toolName));
+  if (readOnly) return null;
+  if (
+    typeof options.unmanagedWriterReason === "string" &&
+    options.unmanagedWriterReason.trim()
+  ) {
+    return skippedCheckpoint(
+      options.unmanagedWriterReason.trim().slice(0, 256),
+      toolName,
+    );
+  }
+  if (isBackgroundTool(toolName, options.toolArgs)) {
+    return skippedCheckpoint("background_writer_not_quiescent", toolName);
+  }
+  if (options.externalToolExecutor) {
+    return skippedCheckpoint("external_writer_lifetime_unmanaged", toolName);
+  }
+  if (
+    !options.broker ||
+    typeof options.broker.beginWorkspaceTransaction !== "function"
+  ) {
+    throw checkpointError(
+      MANAGED_TOOL_CHECKPOINT_ERROR.INVALID_ARGUMENT,
+      "managed tool checkpoint requires a Process Broker transaction API",
+    );
+  }
+  if (
+    typeof options.workspaceRoot !== "string" ||
+    !options.workspaceRoot.trim()
+  ) {
+    throw checkpointError(
+      MANAGED_TOOL_CHECKPOINT_ERROR.INVALID_ARGUMENT,
+      "managed tool checkpoint requires a trusted workspace root",
+    );
+  }
+
+  const coverageTarget =
+    options.coverageTarget || WORKSPACE_TRANSACTION_COVERAGE.PARTIAL;
+  const writerIsolation =
+    options.writerIsolation === "exclusive-workspace"
+      ? "exclusive-workspace"
+      : "unknown";
+  const transaction = options.broker.beginWorkspaceTransaction({
+    ...(options.stateDir ? { stateDir: options.stateDir } : {}),
+    ...(options.id ? { id: options.id } : {}),
+    runId: boundedBinding(options.runId, "agent-run"),
+    taskKey: boundedBinding(options.taskKey, `tool-${toolName}`),
+    workspaceRoot: options.workspaceRoot,
+    coverageTarget,
+    writerIsolation,
+    externalSideEffects:
+      options.externalSideEffects === undefined
+        ? !DIRECT_FILE_ONLY_TOOLS.has(toolName)
+        : options.externalSideEffects !== false,
+    exclusions: Array.isArray(options.exclusions) ? options.exclusions : [],
+    limits: options.limits || {},
+  });
+
+  return {
+    skipped: false,
+    toolName,
+    transaction,
+    transactionId: transaction.id,
+    checkpointId: transaction.checkpointId,
+    prepared: transaction.snapshot(),
+  };
+}
+
+/**
+ * Commit a successful tool checkpoint or roll it back after a failed tool.
+ * Settlement errors retain the durable transaction snapshot for adjudication.
+ */
+export function settleManagedToolCheckpoint(handle, { success, reason } = {}) {
+  if (!handle) return null;
+  if (handle.skipped) return { ...handle };
+  if (!handle.transaction) {
+    throw checkpointError(
+      MANAGED_TOOL_CHECKPOINT_ERROR.INVALID_ARGUMENT,
+      "managed tool checkpoint handle has no transaction",
+    );
+  }
+  try {
+    const evidence =
+      success === true
+        ? handle.transaction.accept()
+        : handle.transaction.rollback({
+            reason: boundedBinding(reason, "agent tool failed"),
+          });
+    return {
+      skipped: false,
+      toolName: handle.toolName,
+      transactionId: handle.transactionId,
+      checkpointId: handle.checkpointId,
+      evidence,
+      coverage: evidence.coverage,
+      fileCoverage: evidence.fileCoverage,
+    };
+  } catch (cause) {
+    throw checkpointError(
+      MANAGED_TOOL_CHECKPOINT_ERROR.SETTLEMENT_FAILED,
+      `managed checkpoint could not ${success === true ? "commit" : "roll back"}: ${cause.message}`,
+      {
+        transactionId: handle.transactionId,
+        checkpointId: handle.checkpointId,
+        transaction: handle.transaction.snapshot(),
+        settlement: success === true ? "commit" : "rollback",
+      },
+      cause,
+    );
+  }
+}