chainlesschain 0.45.63 → 0.45.65

package/src/runtime/coding-agent-policy.cjs

@@ -0,0 +1,354 @@
+"use strict";
+
+const RISK_LEVELS = Object.freeze({
+  LOW: "low",
+  MEDIUM: "medium",
+  HIGH: "high",
+});
+
+const TOOL_CATEGORIES = Object.freeze({
+  READ: "read",
+  SEARCH: "search",
+  ANALYZE: "analyze",
+  WRITE: "write",
+  EXECUTE: "execute",
+  DELETE: "delete",
+  SKILL: "skill",
+  AGENT: "agent",
+});
+
+const TOOL_DECISIONS = Object.freeze({
+  ALLOW: "allow",
+  REQUIRE_PLAN: "require_plan",
+  REQUIRE_CONFIRMATION: "require_confirmation",
+});
+
+const PLAN_APPROVED_STATES = Object.freeze(["approved", "executing", "completed"]);
+
+const READ_ONLY_GIT_SUBCOMMANDS = Object.freeze([
+  "status",
+  "diff",
+  "log",
+  "show",
+  "rev-parse",
+]);
+
+const TOOL_POLICY_METADATA = Object.freeze({
+  read_file: {
+    riskLevel: RISK_LEVELS.LOW,
+    category: TOOL_CATEGORIES.READ,
+    availableInPlanMode: true,
+    planModeBehavior: "allow",
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    approvalFlow: "auto",
+    isReadOnly: true,
+  },
+  list_dir: {
+    riskLevel: RISK_LEVELS.LOW,
+    category: TOOL_CATEGORIES.READ,
+    availableInPlanMode: true,
+    planModeBehavior: "allow",
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    approvalFlow: "auto",
+    isReadOnly: true,
+  },
+  search_files: {
+    riskLevel: RISK_LEVELS.LOW,
+    category: TOOL_CATEGORIES.SEARCH,
+    availableInPlanMode: true,
+    planModeBehavior: "allow",
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    approvalFlow: "auto",
+    isReadOnly: true,
+  },
+  edit_file: {
+    riskLevel: RISK_LEVELS.MEDIUM,
+    category: TOOL_CATEGORIES.WRITE,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: true,
+    requiresConfirmation: false,
+    approvalFlow: "plan",
+    isReadOnly: false,
+  },
+  write_file: {
+    riskLevel: RISK_LEVELS.MEDIUM,
+    category: TOOL_CATEGORIES.WRITE,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: true,
+    requiresConfirmation: false,
+    approvalFlow: "plan",
+    isReadOnly: false,
+  },
+  run_shell: {
+    riskLevel: RISK_LEVELS.HIGH,
+    category: TOOL_CATEGORIES.EXECUTE,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: true,
+    requiresConfirmation: true,
+    approvalFlow: "policy",
+    isReadOnly: false,
+  },
+  git: {
+    riskLevel: RISK_LEVELS.HIGH,
+    category: TOOL_CATEGORIES.EXECUTE,
+    availableInPlanMode: false,
+    planModeBehavior: "readonly-conditional",
+    requiresPlanApproval: true,
+    requiresConfirmation: true,
+    approvalFlow: "policy",
+    isReadOnly: false,
+    readOnlySubcommands: READ_ONLY_GIT_SUBCOMMANDS,
+  },
+  list_skills: {
+    riskLevel: RISK_LEVELS.LOW,
+    category: TOOL_CATEGORIES.SKILL,
+    availableInPlanMode: true,
+    planModeBehavior: "allow",
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    approvalFlow: "auto",
+    isReadOnly: true,
+  },
+  run_skill: {
+    riskLevel: RISK_LEVELS.MEDIUM,
+    category: TOOL_CATEGORIES.SKILL,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: true,
+    requiresConfirmation: false,
+    approvalFlow: "policy",
+    isReadOnly: false,
+  },
+  run_code: {
+    riskLevel: RISK_LEVELS.HIGH,
+    category: TOOL_CATEGORIES.EXECUTE,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: true,
+    requiresConfirmation: true,
+    approvalFlow: "policy",
+    isReadOnly: false,
+  },
+  spawn_sub_agent: {
+    riskLevel: RISK_LEVELS.HIGH,
+    category: TOOL_CATEGORIES.AGENT,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: true,
+    requiresConfirmation: true,
+    approvalFlow: "policy",
+    isReadOnly: false,
+  },
+});
+
+function normalizeGitCommand(command) {
+  const trimmed = String(command || "").trim();
+  if (!trimmed) return "";
+  return trimmed.replace(/^git\s+/i, "").trim();
+}
+
+function isReadOnlyGitCommand(command) {
+  const normalized = normalizeGitCommand(command);
+  if (!normalized) return false;
+  const [subcommand] = normalized.split(/\s+/);
+  return READ_ONLY_GIT_SUBCOMMANDS.includes((subcommand || "").toLowerCase());
+}
+
+function normalizeRiskLevel(value, fallback = RISK_LEVELS.MEDIUM) {
+  if (value === RISK_LEVELS.LOW) return RISK_LEVELS.LOW;
+  if (value === RISK_LEVELS.MEDIUM) return RISK_LEVELS.MEDIUM;
+  if (value === RISK_LEVELS.HIGH) return RISK_LEVELS.HIGH;
+  return fallback;
+}
+
+function clonePolicy(policy) {
+  return JSON.parse(JSON.stringify(policy));
+}
+
+function getToolPolicyMetadata(toolName) {
+  return TOOL_POLICY_METADATA[toolName] || null;
+}
+
+function resolveToolPolicy(toolName, descriptor = null) {
+  const base = clonePolicy(
+    getToolPolicyMetadata(toolName) || {
+      riskLevel: RISK_LEVELS.MEDIUM,
+      category: TOOL_CATEGORIES.EXECUTE,
+      availableInPlanMode: false,
+      planModeBehavior: "blocked",
+      requiresPlanApproval: false,
+      requiresConfirmation: false,
+      approvalFlow: "policy",
+      isReadOnly: false,
+    },
+  );
+
+  if (descriptor?.riskLevel) {
+    base.riskLevel = normalizeRiskLevel(descriptor.riskLevel, base.riskLevel);
+  }
+
+  if (descriptor?.isReadOnly === true) {
+    base.isReadOnly = true;
+    base.riskLevel = RISK_LEVELS.LOW;
+    base.availableInPlanMode = true;
+    base.planModeBehavior = "allow";
+    base.requiresPlanApproval = false;
+    base.requiresConfirmation = false;
+    base.approvalFlow = "auto";
+  }
+
+  return base;
+}
+
+function evaluateToolPolicy(options = {}) {
+  const {
+    toolName,
+    toolDescriptor = null,
+    planModeState = "inactive",
+    confirmed = false,
+    toolArgs = null,
+  } = options;
+
+  if (!toolName) {
+    throw new Error("evaluateToolPolicy requires toolName");
+  }
+
+  const policy = resolveToolPolicy(toolName, toolDescriptor);
+  const readOnlyGitAllowed =
+    toolName === "git" &&
+    policy.planModeBehavior === "readonly-conditional" &&
+    isReadOnlyGitCommand(toolArgs?.command);
+  const planApproved = PLAN_APPROVED_STATES.includes(planModeState);
+
+  if (policy.isReadOnly || policy.riskLevel === RISK_LEVELS.LOW) {
+    return {
+      toolName,
+      allowed: true,
+      decision: TOOL_DECISIONS.ALLOW,
+      requiresPlanApproval: false,
+      requiresConfirmation: false,
+      reason: "Read-only tools are allowed without plan approval.",
+      riskLevel: policy.riskLevel,
+      category: policy.category,
+      planModeState,
+      planModeBehavior: policy.planModeBehavior,
+      readOnlySubcommands: policy.readOnlySubcommands || [],
+    };
+  }
+
+  if (readOnlyGitAllowed) {
+    return {
+      toolName,
+      allowed: true,
+      decision: TOOL_DECISIONS.ALLOW,
+      requiresPlanApproval: false,
+      requiresConfirmation: false,
+      reason: "Read-only git commands are allowed during plan mode.",
+      riskLevel: RISK_LEVELS.LOW,
+      category: TOOL_CATEGORIES.READ,
+      planModeState,
+      planModeBehavior: policy.planModeBehavior,
+      readOnlySubcommands: policy.readOnlySubcommands || [],
+    };
+  }
+
+  if (policy.riskLevel === RISK_LEVELS.MEDIUM) {
+    if (planApproved) {
+      return {
+        toolName,
+        allowed: true,
+        decision: TOOL_DECISIONS.ALLOW,
+        requiresPlanApproval: false,
+        requiresConfirmation: false,
+        reason: "Plan-approved write tool is allowed.",
+        riskLevel: policy.riskLevel,
+        category: policy.category,
+        planModeState,
+        planModeBehavior: policy.planModeBehavior,
+        readOnlySubcommands: policy.readOnlySubcommands || [],
+      };
+    }
+
+    return {
+      toolName,
+      allowed: false,
+      decision: TOOL_DECISIONS.REQUIRE_PLAN,
+      requiresPlanApproval: true,
+      requiresConfirmation: false,
+      reason: "Write tools require an approved plan before execution.",
+      riskLevel: policy.riskLevel,
+      category: policy.category,
+      planModeState,
+      planModeBehavior: policy.planModeBehavior,
+      readOnlySubcommands: policy.readOnlySubcommands || [],
+    };
+  }
+
+  if (!planApproved) {
+    return {
+      toolName,
+      allowed: false,
+      decision: TOOL_DECISIONS.REQUIRE_PLAN,
+      requiresPlanApproval: true,
+      requiresConfirmation: false,
+      reason: "High-risk tools require an approved plan first.",
+      riskLevel: policy.riskLevel,
+      category: policy.category,
+      planModeState,
+      planModeBehavior: policy.planModeBehavior,
+      readOnlySubcommands: policy.readOnlySubcommands || [],
+    };
+  }
+
+  if (policy.requiresConfirmation && !confirmed) {
+    return {
+      toolName,
+      allowed: false,
+      decision: TOOL_DECISIONS.REQUIRE_CONFIRMATION,
+      requiresPlanApproval: false,
+      requiresConfirmation: true,
+      reason: "High-risk tools require an explicit second confirmation.",
+      riskLevel: policy.riskLevel,
+      category: policy.category,
+      planModeState,
+      planModeBehavior: policy.planModeBehavior,
+      readOnlySubcommands: policy.readOnlySubcommands || [],
+    };
+  }
+
+  return {
+    toolName,
+    allowed: true,
+    decision: TOOL_DECISIONS.ALLOW,
+    requiresPlanApproval: false,
+    requiresConfirmation: false,
+    reason: policy.requiresConfirmation
+      ? "High-risk tool confirmed after plan approval."
+      : "Tool allowed after plan approval.",
+    riskLevel: policy.riskLevel,
+    category: policy.category,
+    planModeState,
+    planModeBehavior: policy.planModeBehavior,
+    readOnlySubcommands: policy.readOnlySubcommands || [],
+  };
+}
+
+module.exports = {
+  PLAN_APPROVED_STATES,
+  READ_ONLY_GIT_SUBCOMMANDS,
+  RISK_LEVELS,
+  TOOL_CATEGORIES,
+  TOOL_DECISIONS,
+  TOOL_POLICY_METADATA,
+  evaluateToolPolicy,
+  getToolPolicyMetadata,
+  isReadOnlyGitCommand,
+  normalizeGitCommand,
+  resolveToolPolicy,
+};

package/src/runtime/coding-agent-shell-policy.cjs

@@ -0,0 +1,233 @@
+"use strict";
+
+const SHELL_POLICY_DECISIONS = Object.freeze({
+  ALLOW: "allow",
+  DENY: "deny",
+  WARN: "warn",
+  REROUTE: "reroute",
+});
+
+const BLOCKED_SHELL_RULES = Object.freeze([
+  {
+    id: "git-tool-reroute",
+    decision: SHELL_POLICY_DECISIONS.REROUTE,
+    test: ({ firstToken }) => firstToken === "git",
+    reason:
+      "Use the dedicated git tool instead of run_shell for repository operations.",
+  },
+  {
+    id: "dangerous-delete",
+    decision: SHELL_POLICY_DECISIONS.DENY,
+    test: ({ firstToken }) =>
+      ["rm", "del", "erase", "rmdir", "rd"].includes(firstToken),
+    reason:
+      "Destructive delete commands are blocked by the coding-agent shell policy.",
+  },
+  {
+    id: "dangerous-git-reset",
+    decision: SHELL_POLICY_DECISIONS.DENY,
+    test: ({ firstToken, secondToken }) =>
+      firstToken === "git" && secondToken === "reset",
+    reason:
+      "Potentially destructive git reset operations are blocked by the coding-agent shell policy.",
+  },
+  {
+    id: "dangerous-git-checkout-discard",
+    decision: SHELL_POLICY_DECISIONS.DENY,
+    test: ({ firstToken, tokens }) =>
+      firstToken === "git" &&
+      secondTokenIs(tokens, "checkout") &&
+      tokens.includes("--"),
+    reason:
+      "Discard-style git checkout commands are blocked by the coding-agent shell policy.",
+  },
+  {
+    id: "dangerous-git-clean",
+    decision: SHELL_POLICY_DECISIONS.DENY,
+    test: ({ firstToken, secondToken }) =>
+      firstToken === "git" && secondToken === "clean",
+    reason:
+      "git clean is blocked by the coding-agent shell policy.",
+  },
+  {
+    id: "network-download",
+    decision: SHELL_POLICY_DECISIONS.DENY,
+    test: ({ firstToken }) =>
+      ["curl", "wget", "invoke-webrequest", "iwr"].includes(firstToken),
+    reason:
+      "Network download commands are blocked by the coding-agent shell policy.",
+  },
+  {
+    id: "powershell-encoded-command",
+    decision: SHELL_POLICY_DECISIONS.DENY,
+    test: ({ firstToken, tokens }) =>
+      ["powershell", "powershell.exe", "pwsh", "pwsh.exe"].includes(
+        firstToken,
+      ) &&
+      tokens.some((token) =>
+        ["-encodedcommand", "-enc"].includes(token.toLowerCase()),
+      ),
+    reason:
+      "Encoded PowerShell commands are blocked by the coding-agent shell policy.",
+  },
+]);
+
+const ALLOWLISTED_SHELL_RULES = Object.freeze([
+  {
+    id: "npm-test",
+    test: ({ normalized }) =>
+      /^(npm|npm\.cmd)\s+run\s+test(?::[\w:-]+)?(?:\s|$)/i.test(normalized),
+    reason: "Package test runs are allowlisted verification commands.",
+  },
+  {
+    id: "npm-lint",
+    test: ({ normalized }) =>
+      /^(npm|npm\.cmd)\s+run\s+lint(?:\s|$)/i.test(normalized),
+    reason: "Package lint runs are allowlisted verification commands.",
+  },
+  {
+    id: "npm-build",
+    test: ({ normalized }) =>
+      /^(npm|npm\.cmd)\s+run\s+build(?::[\w:-]+)?(?:\s|$)/i.test(normalized),
+    reason: "Package build runs are allowlisted verification commands.",
+  },
+  {
+    id: "playwright-single-file",
+    test: ({ normalized }) =>
+      /^npx\s+playwright\s+test\s+\S+(?:\s|$)/i.test(normalized),
+    reason: "Single-file Playwright runs are allowlisted verification commands.",
+  },
+  {
+    id: "ripgrep-search",
+    test: ({ firstToken }) => firstToken === "rg",
+    reason: "ripgrep search commands are allowlisted read-style commands.",
+  },
+]);
+
+function secondTokenIs(tokens, value) {
+  return (tokens[1] || "").toLowerCase() === value;
+}
+
+function splitFirstCommandSegment(command) {
+  return String(command || "")
+    .split(/(?:\|\||&&|[|;])/)[0]
+    .trim();
+}
+
+function tokenizeShellCommand(command) {
+  const tokens = [];
+  let current = "";
+  let inDouble = false;
+  let inSingle = false;
+  let escaping = false;
+
+  for (const ch of String(command || "")) {
+    if (escaping) {
+      current += ch;
+      escaping = false;
+      continue;
+    }
+
+    if (ch === "\\" && !inSingle) {
+      escaping = true;
+      continue;
+    }
+
+    if (ch === '"' && !inSingle) {
+      inDouble = !inDouble;
+      continue;
+    }
+
+    if (ch === "'" && !inDouble) {
+      inSingle = !inSingle;
+      continue;
+    }
+
+    if ((ch === " " || ch === "\t") && !inDouble && !inSingle) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += ch;
+  }
+
+  if (current) {
+    tokens.push(current);
+  }
+
+  return tokens;
+}
+
+function normalizeShellCommand(command) {
+  return splitFirstCommandSegment(command).replace(/\s+/g, " ").trim();
+}
+
+function evaluateShellCommandPolicy(command) {
+  const normalized = normalizeShellCommand(command);
+  const tokens = tokenizeShellCommand(normalized);
+  const firstToken = (tokens[0] || "").toLowerCase();
+  const secondToken = (tokens[1] || "").toLowerCase();
+  const context = {
+    command: String(command || ""),
+    normalized,
+    tokens,
+    firstToken,
+    secondToken,
+  };
+
+  if (!normalized) {
+    return {
+      allowed: false,
+      decision: SHELL_POLICY_DECISIONS.DENY,
+      reason: "Shell command is required.",
+      ruleId: "empty-command",
+      normalizedCommand: normalized,
+    };
+  }
+
+  const blockedRule = BLOCKED_SHELL_RULES.find((rule) => rule.test(context));
+  if (blockedRule) {
+    return {
+      allowed: false,
+      decision: blockedRule.decision,
+      reason: blockedRule.reason,
+      ruleId: blockedRule.id,
+      normalizedCommand: normalized,
+    };
+  }
+
+  const allowlistedRule = ALLOWLISTED_SHELL_RULES.find((rule) =>
+    rule.test(context),
+  );
+  if (allowlistedRule) {
+    return {
+      allowed: true,
+      decision: SHELL_POLICY_DECISIONS.ALLOW,
+      reason: allowlistedRule.reason,
+      ruleId: allowlistedRule.id,
+      normalizedCommand: normalized,
+    };
+  }
+
+  return {
+    allowed: true,
+    decision: SHELL_POLICY_DECISIONS.WARN,
+    reason:
+      "Command is not on the preferred verification allowlist, but it is not explicitly blocked.",
+    ruleId: "unclassified-command",
+    normalizedCommand: normalized,
+  };
+}
+
+module.exports = {
+  ALLOWLISTED_SHELL_RULES,
+  BLOCKED_SHELL_RULES,
+  SHELL_POLICY_DECISIONS,
+  evaluateShellCommandPolicy,
+  normalizeShellCommand,
+  splitFirstCommandSegment,
+  tokenizeShellCommand,
+};

package/src/runtime/contracts/session-record.js

@@ -12,8 +12,21 @@ export function createSessionRecord(session = {}, extras = {}) {
     type: session.type || extras.sessionType || null,
     provider: session.provider || extras.provider || null,
     model: session.model || extras.model || null,
+    baseUrl: session.baseUrl || extras.baseUrl || null,
+    enabledToolNames: Array.isArray(extras.enabledToolNames)
+      ? extras.enabledToolNames
+      : Array.isArray(session.enabledToolNames)
+        ? session.enabledToolNames
+        : [],
     projectRoot: session.projectRoot || extras.projectRoot || null,
     baseProjectRoot: session.baseProjectRoot || extras.baseProjectRoot || null,
+    planModeState:
+      extras.planModeState ||
+      session.planManager?.state ||
+      session.planModeState ||
+      null,
+    hasHostManagedToolPolicy:
+      extras.hasHostManagedToolPolicy ?? !!session.hostManagedToolPolicy,
     worktreeIsolation:
       session.worktreeIsolation === true || extras.worktreeIsolation === true,
     worktree:

package/src/runtime/index.js

@@ -11,3 +11,17 @@ export { createSessionRecord } from "./contracts/session-record.js";
 export { createTaskRecord } from "./contracts/task-record.js";
 export { createWorktreeRecord } from "./contracts/worktree-record.js";
 export { createTelemetryRecord } from "./contracts/telemetry-record.js";
+export {
+  CODING_AGENT_MVP_TOOL_NAMES,
+  CODING_AGENT_EXTENSION_TOOL_NAMES,
+  createCodingAgentToolRegistry,
+  getCodingAgentRuntimeDescriptor,
+  getCodingAgentToolContract,
+  getCodingAgentToolContracts,
+  getCodingAgentToolPolicy,
+  isCodingAgentMvpTool,
+  listCodingAgentToolNames,
+  mapCodingAgentToolDefinition,
+} from "./coding-agent-contract.js";
+export { default as codingAgentManagedToolPolicy } from "./coding-agent-managed-tool-policy.cjs";
+export { default as codingAgentShellPolicy } from "./coding-agent-shell-policy.cjs";

package/src/runtime/runtime-events.js

@@ -1,4 +1,31 @@
 import { EventEmitter } from "node:events";
+import { createRequire } from "node:module";
+
+const requireCjs = createRequire(import.meta.url);
+const codingAgentEventsCjs = requireCjs("./coding-agent-events.cjs");
+
+/**
+ * Canonical Coding Agent event protocol — re-exported from the shared CJS
+ * module so the CLI runtime, the Desktop Main process and any future host
+ * all consume from the same source of truth.
+ *
+ * The legacy `RUNTIME_EVENTS` constants below remain for internal runtime
+ * bookkeeping (turn:start, server:start, etc.). They are NOT the wire
+ * protocol — when emitting events that cross the CLI/Desktop boundary,
+ * use `createCodingAgentEvent` and the `CODING_AGENT_EVENT_TYPES` enum.
+ */
+export const {
+  CODING_AGENT_EVENT_VERSION,
+  CODING_AGENT_EVENT_CHANNEL,
+  CODING_AGENT_EVENT_TYPES,
+  LEGACY_TO_UNIFIED_TYPE,
+  CodingAgentSequenceTracker,
+  defaultSequenceTracker,
+  createCodingAgentEvent,
+  wrapLegacyMessage,
+  validateCodingAgentEvent,
+  mapLegacyType,
+} = codingAgentEventsCjs;
 
 export const RUNTIME_EVENTS = {
   RUNTIME_START: "runtime:start",

package/src/tools/index.js

@@ -20,3 +20,15 @@ export {
   listLegacyAgentToolNames,
   getRuntimeToolDescriptor,
 } from "./legacy-agent-tools.js";
+export {
+  CODING_AGENT_MVP_TOOL_NAMES,
+  CODING_AGENT_EXTENSION_TOOL_NAMES,
+  createCodingAgentToolRegistry,
+  getCodingAgentRuntimeDescriptor,
+  getCodingAgentToolContract,
+  getCodingAgentToolContracts,
+  getCodingAgentToolPolicy,
+  isCodingAgentMvpTool,
+  listCodingAgentToolNames,
+  mapCodingAgentToolDefinition,
+} from "../runtime/coding-agent-contract.js";