chainlesschain 0.162.158 → 0.162.159

package/src/repl/voice-dictation.js

@@ -0,0 +1,132 @@
+/**
+ * Voice dictation for the agent REPL (gap-2026-07-11 P2#11).
+ *
+ * Claude Code's `/voice` dictates a prompt by speech. cc generalizes it to a
+ * pluggable STT backend with a strict local-first priority so nothing leaves
+ * the box unless the user opts into cloud transcription:
+ *
+ *   local Whisper  >  system STT (OS dictation)  >  cloud (opt-in)
+ *
+ * Two capture modes mirror the upstream UX:
+ *   - hold : push-to-talk — record while a key is held, transcribe on release.
+ *   - tap  : toggle — tap to start, tap again to stop.
+ *
+ * Real audio capture is a host binding (a Whisper binary, an OS dictation API);
+ * it is injected, so on a host with no backend — or a headless/SSH session where
+ * there is no microphone — `/voice` degrades to a clear message instead of
+ * pretending to listen. This module is the pure decision core (mode/command
+ * parse, environment degradation, backend priority, status render).
+ */
+
+export const VOICE_MODES = Object.freeze(["off", "hold", "tap"]);
+export const DEFAULT_VOICE_MODE = "off";
+
+/**
+ * STT backends in priority order. `local` never sends audio off the box;
+ * `cloud` requires explicit opt-in (config voice.allowCloud). Each entry names
+ * the capability probe the host binding fills in.
+ */
+export const STT_BACKENDS = Object.freeze([
+  { id: "whisper-local", kind: "local", label: "local Whisper" },
+  { id: "system-stt", kind: "system", label: "system STT" },
+  { id: "cloud", kind: "cloud", label: "cloud transcription" },
+]);
+
+/**
+ * Parse `/voice [hold|tap|off|status]`. Returns null for non-/voice input,
+ * `{ error }` for a bad arg, else `{ action }`. Bare `/voice` shows status.
+ * Pure.
+ */
+export function parseVoiceCommand(input) {
+  const t = String(input || "").trim();
+  if (t !== "/voice" && !t.startsWith("/voice ")) return null;
+  const arg = t.slice("/voice".length).trim().toLowerCase();
+  if (!arg || arg === "status") return { action: "status" };
+  if (arg === "hold" || arg === "ptt" || arg === "push")
+    return { action: "hold" };
+  if (arg === "tap" || arg === "toggle") return { action: "tap" };
+  if (arg === "off" || arg === "stop" || arg === "0") return { action: "off" };
+  return {
+    error: `Unknown /voice option "${arg}". Use: hold | tap | off | status`,
+  };
+}
+
+/**
+ * Decide whether voice capture is usable in this environment. Headless / SSH /
+ * CI sessions have no local microphone, so dictation degrades. Pure over the
+ * passed env + tty flags.
+ * @returns {{ supported, reason }}
+ */
+export function detectVoiceEnvironment({ env = {}, isTTY = true } = {}) {
+  if (!isTTY) {
+    return {
+      supported: false,
+      reason: "not a TTY — no interactive microphone",
+    };
+  }
+  if (env.SSH_TTY || env.SSH_CONNECTION) {
+    return {
+      supported: false,
+      reason:
+        "remote SSH session — capture audio locally and paste, or use a cloud STT relay",
+    };
+  }
+  if (isTruthy(env.CI)) {
+    return { supported: false, reason: "CI environment — no microphone" };
+  }
+  if (isTruthy(env.CC_NO_VOICE)) {
+    return { supported: false, reason: "disabled via CC_NO_VOICE" };
+  }
+  return { supported: true, reason: "" };
+}
+
+/**
+ * Pick the highest-priority available STT backend. `available` is a map of
+ * backend id → boolean from the host capability probe. Cloud is only eligible
+ * when `allowCloud` is true (config voice.allowCloud). Returns
+ * `{ backend, reason }` or `{ backend: null, reason }`. Pure.
+ */
+export function resolveSttBackend({
+  available = {},
+  allowCloud = false,
+  prefer = null,
+} = {}) {
+  const eligible = STT_BACKENDS.filter((b) => {
+    if (!available[b.id]) return false;
+    if (b.kind === "cloud" && !allowCloud) return false;
+    return true;
+  });
+  if (eligible.length === 0) {
+    return {
+      backend: null,
+      reason:
+        "no STT backend available — install a local Whisper build or enable system dictation (voice.allowCloud for cloud)",
+    };
+  }
+  // Honor an explicit preference if it's eligible; else take the top priority.
+  const chosen =
+    (prefer && eligible.find((b) => b.id === prefer)) || eligible[0];
+  return { backend: chosen, reason: `using ${chosen.label}` };
+}
+
+/** One-line `/voice status`. Pure. */
+export function renderVoiceStatus({ mode = "off", backend = null, env } = {}) {
+  const m = VOICE_MODES.includes(mode) ? mode : "off";
+  if (env && !env.supported) {
+    return `Voice: unavailable — ${env.reason}.`;
+  }
+  if (m === "off") {
+    return "Voice: off. /voice hold (push-to-talk) or /voice tap (toggle).";
+  }
+  const be = backend ? backend.label : "no backend";
+  const how =
+    m === "hold" ? "hold the dictation key to talk" : "tap to start/stop";
+  return `Voice: ${m} — ${how}; ${be}.`;
+}
+
+function isTruthy(v) {
+  const n = String(v == null ? "" : v)
+    .toLowerCase()
+    .trim();
+  return n === "1" || n === "true" || n === "yes" || n === "on";
+}

package/src/runtime/agent-core.js

@@ -1291,6 +1291,38 @@ export async function executeTool(name, args, context = {}) {
     }
   }
 
+  // Session-store write guard (transcript tamper protection): JSONL
+  // transcripts under ~/.chainlesschain/sessions are hash-chained and treated
+  // as an audit surface — an agent editing a transcript rewrites the history
+  // that `cc session verify` and resume trust. Same posture as the
+  // sensitive-file guard: confirm-first, an explicit settings `allow` rule is
+  // the only bypass, headless without a confirmer fails closed.
+  if (
+    (name === "write_file" ||
+      name === "edit_file" ||
+      name === "notebook_edit") &&
+    settingsVerdict.decision !== "allow" &&
+    args?.path
+  ) {
+    const { sessionStorePathReason } =
+      await import("../lib/session-store-guard.js");
+    const storeReason = sessionStorePathReason(args.path, { cwd });
+    if (storeReason) {
+      const ok = await requestInteractivePermission(name, args, context, cwd, {
+        tool: name,
+        args,
+        rule: null,
+        reason: `session store: ${storeReason}`,
+      });
+      if (!ok) {
+        return {
+          error: `[Session Store] Writing "${args.path}" would modify a session transcript (${storeReason}) — denied. Add a settings allow rule to pre-authorize.`,
+          policy: { decision: "ask", via: "session-store-guard" },
+        };
+      }
+    }
+  }
+
   // Destructive-git guard (Claude-Code 2.1.183 parity: "destructive git
   // commands blocked when unintended"). The `git` tool otherwise runs any
   // command unguarded in auto mode — including `reset --hard`, `clean -fd`,
@@ -1438,6 +1470,14 @@ export async function executeTool(name, args, context = {}) {
       parentMessages: context.parentMessages,
       interaction: context.interaction,
       sessionId: context.sessionId || null,
+      // Parent LLM config — documented at toolContext as forwarded to
+      // spawn_sub_agent for provider/key inheritance; without this line it
+      // never actually reached executeToolInner (sub-agents silently fell
+      // back to config defaults and their usage was mis-attributed).
+      llmOptions: context.llmOptions || null,
+      // 用量归因: shared per-run sink for child-loop (sub-agent / isolated
+      // skill) token usage, drained by agentLoop as attributed events.
+      subAgentUsageSink: context.subAgentUsageSink || null,
       hostManagedToolPolicy: context.hostManagedToolPolicy || null,
       externalToolDescriptors: context.externalToolDescriptors || null,
       externalToolExecutors: context.externalToolExecutors || null,
@@ -2074,6 +2114,7 @@ async function executeToolInner(
     settingsHooks = null,
     signal = null,
     backgroundSubAgents = null,
+    subAgentUsageSink = null,
   },
 ) {
   const localToolDescriptor =
@@ -2706,6 +2747,21 @@ async function executeToolInner(
           }
           output = res.stdout ?? "";
         }
+        // PR/session linking (gap-2026-07-11 P1#9): a successful `gh pr …`
+        // (or `git push`) ties this session to the PR it touched. Async and
+        // best-effort — never delays or fails the tool result.
+        if (sessionId) {
+          import("../lib/pr-link-ledger.js")
+            .then((m) =>
+              m.recordFromShellCommand({
+                sessionId,
+                command: args.command,
+                output: String(output || ""),
+                cwd: args.cwd || cwd,
+              }),
+            )
+            .catch(() => {});
+        }
         return attachDescriptor(
           {
             stdout: output.substring(0, 30000),
@@ -2883,6 +2939,7 @@ async function executeToolInner(
           settingsHooks,
           signal,
           backgroundSubAgents,
+          subAgentUsageSink,
         }),
       );
     }
@@ -3221,6 +3278,77 @@ async function executeToolInner(
       }
     }
 
+    case "browser_act": {
+      // Gap-analysis #6: the ACTION side of the Chrome connector.
+      // browser_state stays the read-only default; browser_act explicitly
+      // drives the user's logged-in browser (click/type/press/navigate/
+      // waitForSelector/screenshot/assertText) and is gated like run_code:
+      // HIGH risk through the ApprovalGate (CONFIRM even on the trusted/auto
+      // tier), pre-authorizable only by an explicit settings allow rule
+      // (ruleAllowed). Unlike run_code there is no legacy ungated behavior to
+      // preserve, so the gate applies whenever an ApprovalGate is wired —
+      // headless without a confirmer fails closed. Screenshot paths are
+      // generated inside performActions (never agent-chosen), and each
+      // executed step is audit-logged to ~/.chainlesschain/browser-actions/.
+      try {
+        if (
+          approvalGate &&
+          !ruleAllowed &&
+          typeof approvalGate.decide === "function"
+        ) {
+          const { APPROVAL_RISK, APPROVAL_DECISION } =
+            await import("@chainlesschain/session-core");
+          const summary = Array.isArray(args.actions)
+            ? args.actions
+                .map((a) => a?.type)
+                .filter(Boolean)
+                .slice(0, 10)
+                .join(",")
+            : "";
+          const gate = await approvalGate.decide({
+            sessionId,
+            riskLevel: APPROVAL_RISK.HIGH,
+            tool: "browser_act",
+            args: { actions: summary },
+          });
+          if (gate.decision !== APPROVAL_DECISION.ALLOW) {
+            const tierLabel =
+              typeof gate.policy === "string" ? `"${gate.policy}" ` : "";
+            return attachDescriptor({
+              error: `[ApprovalGate] browser_act denied by the ${tierLabel}approval policy (via ${gate.via}). Retrying won't help — driving the user's browser needs their approval. Tell the user (they can approve it or relax the policy) and continue with other work.`,
+              approval: {
+                decision: gate.decision,
+                via: gate.via,
+                riskLevel: "high",
+                policy: gate.policy,
+              },
+            });
+          }
+        }
+        const { performActions } = await import("../lib/chrome-connector.js");
+        const result = await performActions(args.actions, {
+          port: args.port != null ? Number(args.port) : undefined,
+          cdpUrl: args.cdp_url != null ? String(args.cdp_url) : null,
+          tab: args.tab != null ? Number(args.tab) : undefined,
+          continueOnError: args.continue_on_error === true,
+          sessionId: sessionId ? String(sessionId) : null,
+        });
+        if (!result.ok && result.error) {
+          // Nothing ran (validation / attach failure) — surface as an error.
+          // A step-level failure returns the per-step outcomes instead so the
+          // model can see exactly which step broke.
+          return attachDescriptor({
+            error: `browser_act failed: ${result.error}`,
+          });
+        }
+        return attachDescriptor(result);
+      } catch (err) {
+        return attachDescriptor({
+          error: `browser_act failed: ${err.message}`,
+        });
+      }
+    }
+
     case "search_files": {
       // An explicit directory scopes the search to one root; otherwise span
       // cwd plus any --add-dir roots so cross-package searches find matches.
@@ -3429,13 +3557,46 @@ async function executeToolInner(
       // Check if skill requests isolation (via SKILL.md frontmatter)
       const skillIsolation = match.isolation === true;
       if (skillIsolation) {
+        // 用量归因: an isolated skill runs as a child loop whose real token
+        // usage would otherwise be invisible — forward it into the parent
+        // run's sink tagged origin:"skill" so `cc session usage --by skill`
+        // can break it out. A nested frame passes through unchanged.
+        const skillUsageSink = Array.isArray(subAgentUsageSink)
+          ? subAgentUsageSink
+          : null;
+        let skillSubRef = null;
         // Run skill through isolated sub-agent context
         const subCtx = SubAgentContext.create({
           role: `skill-${args.skill_name}`,
           task: `Execute the "${args.skill_name}" skill with input: ${(args.input || "").substring(0, 200)}`,
           allowedTools: ["read_file", "search_files", "list_dir"],
           cwd,
+          onUsage: skillUsageSink
+            ? (u) => {
+                try {
+                  skillUsageSink.push(
+                    u && u.attribution
+                      ? u
+                      : {
+                          provider: u?.provider ?? null,
+                          model: u?.model ?? null,
+                          usage: u?.usage || null,
+                          attribution: {
+                            origin: "skill",
+                            skill: args.skill_name,
+                            subagentId: skillSubRef?.id || null,
+                            parentSessionId: sessionId || null,
+                            depth: (subAgentDepth || 0) + 1,
+                          },
+                        },
+                  );
+                } catch (_e) {
+                  // usage forwarding is best-effort
+                }
+              }
+            : null,
         });
+        skillSubRef = subCtx;
         try {
           const result = await subCtx.run(args.input);
           return attachDescriptor({
@@ -4020,6 +4181,27 @@ function _backgroundSubAgentResultText(entry) {
   );
 }
 
+/**
+ * Drain the run's attributed child-loop usage sink (spawn_sub_agent /
+ * isolated run_skill — see toolContext.subAgentUsageSink), re-yielding each
+ * record as a regular `token-usage` event that carries its `attribution`
+ * frame. Consumers that ignore `attribution` see ordinary usage events;
+ * attribution-aware consumers (REPL persistence, headless runner) can split
+ * child spend from the main conversation's.
+ */
+function* _drainSubAgentUsage(sink) {
+  while (Array.isArray(sink) && sink.length > 0) {
+    const u = sink.shift();
+    yield {
+      type: "token-usage",
+      provider: u?.provider ?? null,
+      model: u?.model ?? null,
+      usage: u?.usage || {},
+      attribution: u?.attribution || null,
+    };
+  }
+}
+
 async function _executeSpawnSubAgent(args, ctx) {
   // Nesting cap: refuse before any context/registry work.
   const currentDepth = ctx.subAgentDepth || 0;
@@ -4169,6 +4351,40 @@ async function _executeSpawnSubAgent(args, ctx) {
     model: mdModel || parentLlm.model || undefined,
   };
 
+  // 用量归因: forward the child's real token usage into the parent run's sink
+  // (threaded through toolContext) so agentLoop re-yields it as attributed
+  // `token-usage` events. A nested child's already-attributed record passes
+  // through unchanged (deepest frame wins). subCtxRef closes over the created
+  // context so the frame can carry the sub-agent's id.
+  const usageSink = Array.isArray(ctx.subAgentUsageSink)
+    ? ctx.subAgentUsageSink
+    : null;
+  let subCtxRef = null;
+  const onUsage = usageSink
+    ? (u) => {
+        try {
+          usageSink.push(
+            u && u.attribution
+              ? u
+              : {
+                  provider: u?.provider ?? null,
+                  model: u?.model ?? null,
+                  usage: u?.usage || null,
+                  attribution: {
+                    origin: "subagent",
+                    subagentId: subCtxRef?.id || null,
+                    role: subCtxRef?.role || role || null,
+                    parentSessionId,
+                    depth: currentDepth + 1,
+                  },
+                },
+          );
+        } catch (_e) {
+          // usage forwarding is best-effort
+        }
+      }
+    : null;
+
   const subCtx = SubAgentContext.create({
     role,
     task,
@@ -4182,7 +4398,9 @@ async function _executeSpawnSubAgent(args, ctx) {
     // Same shared counter object so the child's own spawns draw from the run's
     // single total-sub-agent pool (breadth cap spans the whole tree).
     subAgentBudget: ctx.subAgentBudget || null,
+    onUsage,
   });
+  subCtxRef = subCtx;
 
   const emit = (type, payload) => {
     if (!interaction || typeof interaction.emit !== "function") return;
@@ -5793,8 +6011,18 @@ export async function* agentLoop(messages, options) {
     // any are still running (it waits, injects, and gives the model one more
     // turn) so a background result can never be silently lost.
     backgroundSubAgents: new Map(),
+    // 用量归因: per-run sink for child-loop (spawn_sub_agent / isolated
+    // run_skill) token usage. Child loops consume their own generator events,
+    // so their real usage never reaches this loop's consumers — the spawn
+    // wiring pushes it here and the loop drains it at iteration boundaries as
+    // `token-usage` events carrying an `attribution` frame. Callers may pass
+    // their own array to observe it directly.
+    subAgentUsageSink: Array.isArray(options.subAgentUsageSink)
+      ? options.subAgentUsageSink
+      : [],
   };
   const backgroundSubAgents = toolContext.backgroundSubAgents;
+  const subAgentUsageSink = toolContext.subAgentUsageSink;
 
   throwIfAborted(signal);
 
@@ -5930,6 +6158,10 @@ export async function* agentLoop(messages, options) {
     budget.consume();
     throwIfAborted(signal);
 
+    // Surface attributed child-loop usage collected since the last boundary
+    // (blocking spawns push during executeTool; background spawns push live).
+    yield* _drainSubAgentUsage(subAgentUsageSink);
+
     // Emit progressive warnings (once per level)
     const level = budget.warningLevel();
     if (
@@ -6504,7 +6736,9 @@ export async function* agentLoop(messages, options) {
     }
   }
 
-  // Budget exhausted — yield exhaustion event + final message
+  // Budget exhausted — flush any child usage the final iteration produced,
+  // then yield exhaustion event + final message
+  yield* _drainSubAgentUsage(subAgentUsageSink);
   yield { type: "iteration-budget-exhausted", budget: budget.toSummary() };
   yield {
     type: "response-complete",
@@ -6559,6 +6793,13 @@ export function formatToolArgs(name, args) {
       return `${args.kind || "other"}: ${(args.title || args.path || "").substring(0, 60)}`;
     case "browser_state":
       return `tab=${args.tab ?? 0} port=${args.port ?? 9222}${args.reload ? " reload" : ""}`;
+    case "browser_act": {
+      const kinds = Array.isArray(args.actions)
+        ? args.actions.map((a) => a?.type).filter(Boolean)
+        : [];
+      const head = kinds.slice(0, 4).join(",");
+      return `${kinds.length} action(s)${head ? `: ${head}` : ""}${kinds.length > 4 ? ",…" : ""} tab=${args.tab ?? 0} port=${args.port ?? 9222}`;
+    }
     case "schedule":
       return args.action === "cron"
         ? `cron ${args.cron || ""}`.trim()

package/src/runtime/coding-agent-contract-shared.cjs

@@ -1058,6 +1058,94 @@ const CODING_AGENT_TOOL_CONTRACTS = Object.freeze([
       tags: ["tool:browser_state", "contract:coding-agent", "tier:extension"],
     },
   },
+  {
+    name: "browser_act",
+    title: "Browser Actions",
+    kind: "browser",
+    tier: "extension",
+    description:
+      "Perform EXPLICIT actions in the user's connected Chrome over loopback CDP: click, type, press, navigate (http/https only), waitForSelector, screenshot (saved to a generated temp path — never a chosen one), assertText. Approval-gated (HIGH risk): use browser_state first to observe; only act when the task genuinely requires driving the browser. Steps run in order and fail fast unless continue_on_error; each returns {ok, action, detail, durationMs} and every executed step is audit-logged under ~/.chainlesschain/browser-actions/. Requires a debuggable Chrome (`cc browse chrome launch`).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        actions: {
+          type: "array",
+          description:
+            "Ordered action steps. Each item: {type: click|type|press|navigate|waitForSelector|screenshot|assertText} plus its fields — click/waitForSelector/assertText need selector; type needs selector+text; press needs key; navigate needs url (http/https); waitForSelector accepts timeout_ms (capped 30000); assertText needs expected (substring); screenshot takes NO path (generated internally).",
+          items: {
+            type: "object",
+            properties: {
+              type: {
+                type: "string",
+                enum: [
+                  "click",
+                  "type",
+                  "press",
+                  "navigate",
+                  "waitForSelector",
+                  "screenshot",
+                  "assertText",
+                ],
+                description: "Action kind",
+              },
+              selector: {
+                type: "string",
+                description:
+                  "CSS selector (click/type/waitForSelector/assertText)",
+              },
+              text: { type: "string", description: "Text to type (type)" },
+              key: {
+                type: "string",
+                description: "Key to press, e.g. Enter (press)",
+              },
+              url: {
+                type: "string",
+                description: "http(s):// URL to open (navigate)",
+              },
+              timeout_ms: {
+                type: "number",
+                description:
+                  "waitForSelector timeout in ms (default 5000, max 30000)",
+              },
+              expected: {
+                type: "string",
+                description: "Expected substring (assertText)",
+              },
+            },
+            required: ["type"],
+          },
+        },
+        cdp_url: {
+          type: "string",
+          description:
+            "CDP endpoint — loopback-only, e.g. http://127.0.0.1:9222 (default port 9222)",
+        },
+        port: {
+          type: "number",
+          description: "CDP port of the debuggable Chrome (default 9222)",
+        },
+        tab: {
+          type: "number",
+          description: "Tab index to act in (default 0)",
+        },
+        continue_on_error: {
+          type: "boolean",
+          description:
+            "Keep executing remaining steps after a failed one (default false: fail fast)",
+        },
+      },
+      required: ["actions"],
+    },
+    ...TOOL_POLICY_METADATA.browser_act,
+    permissions: {
+      level: "elevated",
+      scopes: ["browser:act"],
+    },
+    telemetry: {
+      category: "browser",
+      tags: ["tool:browser_act", "contract:coding-agent", "tier:extension"],
+    },
+  },
 ]);
 
 const CODING_AGENT_MVP_TOOL_NAMES = Object.freeze(

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

@@ -320,6 +320,23 @@ const TOOL_POLICY_METADATA = Object.freeze({
     approvalFlow: "auto",
     isReadOnly: true,
   },
+  // DRIVES the user's connected Chrome over loopback CDP — clicks, typing,
+  // key presses, navigation, screenshots, text assertions. Unlike
+  // browser_state (pure observation, the default) this mutates the page and
+  // acts inside whatever session that browser is logged into, so it carries
+  // the same gating as run_shell/run_code: HIGH risk (the ApprovalGate
+  // CONFIRMs HIGH even on the trusted/auto tier, so auto mode still prompts),
+  // blocked in plan mode, plan approval + explicit confirmation required.
+  browser_act: {
+    riskLevel: RISK_LEVELS.HIGH,
+    category: TOOL_CATEGORIES.EXECUTE,
+    availableInPlanMode: false,
+    planModeBehavior: "blocked",
+    requiresPlanApproval: true,
+    requiresConfirmation: true,
+    approvalFlow: "policy",
+    isReadOnly: false,
+  },
 });
 
 function normalizeGitCommand(command) {