hilos-agent 0.11.13 → 0.11.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.13",
+  "version": "0.11.14",
   "description": "Run your own coding agent (Claude Code, Codex, Cursor, OpenCode, Hermes, or any command) as a teammate in a hilos room. The checkout and credentials stay local; changes go to your configured Git remote as a PR for human review, and bounded progress and reports go to hilos.",
   "type": "module",
   "bin": {

package/src/agent-result.mjs

@@ -1,10 +1,12 @@
 // 1298 — one writing contract and final-result envelope for hosted and local runs.
 export const AGENT_REPLY_STYLE_RULE = [
   "How to write the reply:",
-  "- Lead with the answer or outcome. Never restate the request.",
+  "- Lead with the answer or concrete outcome, in words a teammate outside the code can use. Never restate the request.",
   "- Default to 1-3 short sentences, or at most three short bullets for separate outcomes.",
-  "- Include useful links once. No preamble, headings, sign-off, process narration, or routine test/file lists.",
-  "- Keep blockers, material limitations, and a needed next step visible. Never claim checks, deployment, or merging without evidence.",
+  "- For instructions, put the action or command first and number sequential steps. For choices, recommend one first, then give the requested alternatives with short trade-offs.",
+  "- Include useful links once. Omit facts that do not change the answer or next decision: routine checks, file counts, and process history. No preamble, headings on short replies, sign-off, recap, or tangents.",
+  "- Keep blockers, material limitations, and real uncertainty visible. State errors plainly. Never invent causes, time estimates, checks, deployment, or merging.",
+  "- When blocked on a person, ask for the one missing decision: 'Which inbox should receive the form?' Otherwise, do not add a question. Do authorized work yourself; do not hand it back or ask permission again. When done, stop; no follow-up offers.",
   "- Give requested documents, plans, code, research, and explanations the detail they need; keep their introduction short. Put code and commands in fenced blocks.",
   "The room's voice may shape tone, but only a person's request for detail expands this default. Clarity beats a word limit.",
 ].join("\n");

package/src/coding-transport.mjs

@@ -0,0 +1,440 @@
+import { minimalEnv, scrubHilosEnv } from "./cli.mjs";
+import { commandArgv } from "./argv.mjs";
+import { webToolEnv, attachTarget, detectVendor } from "./progress-emitter.mjs";
+import { shouldGateClaudePermissions } from "./claude-permissions.mjs";
+import { shouldGateCodexPermissions, codexMcpTransportUnavailable, codexSandboxFromArgs } from "./codex-mcp-session.mjs";
+import { childMcpArgs, codexChildMcpArgs } from "./child-mcp.mjs";
+import { repoEditAllowance } from "./permission-gate.mjs";
+
+/**
+ * The environment for a coding/chat CLI run. runCli always strips HILOS_* on top
+ * of whatever this returns; here we additionally honor `codingEnv: "minimal"`
+ * (strict isolation — only what the tool needs to reach its own model provider).
+ * Returns undefined for the default "inherit" mode so runCli falls back to the
+ * scrubbed process.env.
+ */
+export function codingChildEnv(cfg) {
+  return cfg?.codingEnv === "minimal"
+    ? minimalEnv(process.env, cfg.codingEnvAllow)
+    : undefined;
+}
+
+/** Add only the selected CLI's public-web enablement to its already-isolated
+ * child environment. Today this changes OpenCode only; keeping it shared makes
+ * argv, ACP, HTTP, gated, and conversational runs follow one contract. */
+export function codingChildWebEnv(cfg, vendor) {
+  return webToolEnv(vendor, codingChildEnv(cfg), {
+    enabled: cfg?.webSearch !== false,
+  });
+}
+
+/**
+ * Bind one OpenCode HTTP session to hilos's vendor-neutral permission tools.
+ * Both repo and direct-folder runs use this exact callback contract so neither
+ * path can accidentally become the ungated exception.
+ */
+function openCodePermissionCallbacks({
+  tool,
+  channelId,
+  threadRoot,
+  runId = null,
+  provider = "opencode",
+  // 0866 — when the server's get_permission_decision supports a long-poll
+  // hold, each read blocks up to this many ms and answers the moment a human
+  // decides, instead of the gate discovering the decision on its next 1s poll.
+  // Tests may use 0 for an immediate decision fixture.
+  decisionWaitMs = 0,
+  // 1256 — the checkout this run edits; an edit under it is allowed on the
+  // daemon without a card (the pull request is the gate). Empty means "no
+  // local allowance": every ask still reaches the room.
+  repoRoot = "",
+  gateRepoEdits = false,
+}) {
+  return {
+    localAllow: (request) => repoEditAllowance(request, { repoRoot, gateRepoEdits }),
+    requestPermission: async (request) => {
+      const detail =
+        request.metadata && typeof request.metadata === "object"
+          ? request.metadata
+          : {};
+      const title = [
+        detail.title,
+        detail.description,
+        detail.command,
+        request.resources?.[0],
+      ].find((value) => typeof value === "string" && value.trim());
+      return tool("request_permission", {
+        channelId,
+        threadRootId: threadRoot,
+        ...(runId ? { runId } : {}),
+        provider,
+        vendorSessionId: request.sessionId,
+        vendorRequestId: request.vendorRequestId,
+        action: request.action,
+        title: title || `${request.action} permission`,
+        resources: request.resources,
+        suggestedSave: request.suggestedSave,
+        metadata: detail,
+        ...(request.source ? { source: request.source } : {}),
+      });
+    },
+    getPermissionDecision: async (handle, { request, failClosed = false }) => {
+      const requestId =
+        handle &&
+        typeof handle === "object" &&
+        typeof handle.requestId === "string"
+          ? handle.requestId
+          : null;
+      if (!requestId) {
+        throw new Error(
+          "hilos returned a pending permission without a request id",
+        );
+      }
+      return tool("get_permission_decision", {
+        requestId,
+        provider,
+        vendorSessionId: request.sessionId,
+        vendorRequestId: request.vendorRequestId,
+        ...(failClosed ? { failClosed: true } : {}),
+        // Never on a failClosed settlement — that call exists to act NOW.
+        ...(decisionWaitMs > 0 && !failClosed ? { waitMs: decisionWaitMs } : {}),
+      });
+    },
+  };
+}
+
+/** The local HTTP bridge can own only a local OpenCode server. An explicit
+ * `--attach` remains on OpenCode's CLI responder, which rejects unanswered asks
+ * fail closed; taking over a remote server requires a separate authenticated
+ * transport contract. Shared by repo and direct-folder runs. */
+export function shouldUseRuntimePermissionBridge({
+  vendor,
+  runtimePermissions,
+  codeArgs,
+  codingCmd,
+}) {
+  return (
+    vendor === "opencode" &&
+    runtimePermissions === true &&
+    !codeArgs.includes("--auto") &&
+    attachTarget(codingCmd) === null
+  );
+}
+
+/** ACP transport (0759; slice 1 opencode, slice 2 cursor). Only runs the
+ * workspace already gates with runtime permissions qualify, and only when the
+ * vendor's own auto-allow escape hatches are absent — over ACP, hilos must be
+ * the one answering asks, so a run configured to never ask has nothing to gate
+ * here.
+ *
+ * 0778 removed two limits that were never about correctness. `acpTransport`
+ * now defaults ON (config.mjs) for the vendors whose adapter is proven, and a
+ * RESUMED run no longer disqualifies: both live vendors advertise ACP's
+ * `loadSession` capability, so acp-session.mjs resumes the session and keeps
+ * raising cards. Setting `acpTransport: false` still opts a workspace out. */
+export function shouldUseAcpTransport({
+  vendor,
+  acpTransport,
+  runtimePermissions,
+  codeArgs,
+  codingCmd,
+}) {
+  if (acpTransport !== true) return false;
+  if (runtimePermissions !== true) return false;
+  if (vendor === "opencode") {
+    return shouldUseRuntimePermissionBridge({
+      vendor,
+      runtimePermissions,
+      codeArgs,
+      codingCmd,
+    });
+  }
+  if (vendor === "cursor") {
+    // -f/--force is cursor's "allow everything" switch — the exact analog of
+    // opencode's --auto.
+    return !codeArgs.includes("-f") && !codeArgs.includes("--force");
+  }
+  return false;
+}
+
+/**
+ * The env a gated claude run gets (0777).
+ *
+ * A permission card can legitimately wait on a person for minutes — a 150s wait
+ * was verified live — so the CLI's own MCP tool timeout must not cut the ask
+ * short before hilos's run deadline does. Everything else about the env is
+ * unchanged (runCli still strips HILOS_* itself).
+ */
+function claudeGateEnv(cfg) {
+  const base = codingChildEnv(cfg) || process.env;
+  const budget = Math.max(60_000, Number(cfg?.runTimeoutMs) || 0) + 60_000;
+  return { ...base, MCP_TOOL_TIMEOUT: String(budget) };
+}
+
+/**
+ * Run claude_code through its permission-prompt seam (0777).
+ *
+ * Deliberately NOT a new transport: the ordinary argv run is untouched — same
+ * runCli, same resume args, same streaming — and the gate is two extra flags
+ * plus a loopback MCP server that lives exactly as long as the run. The prompt
+ * stays the final argument.
+ */
+async function runClaudeGatedCli({
+  deps,
+  cfg,
+  onGateDropped,
+  cmd,
+  codeArgs,
+  prompt,
+  cwd,
+  signal,
+  onData,
+  permissionCallbacks,
+  sessionId = "",
+  resolveSessionId,
+  beforeSpawn,
+  childMcp = null,
+  log = console,
+}) {
+  const server = await deps.startClaudePermissionServer({
+    ...permissionCallbacks,
+    // 1255 — one config file for the run: the gate's permission server and the
+    // run's own hilos seat, plus the allow entry that keeps the agent's room
+    // tools off the permission card.
+    ...(childMcp ? { extraServers: childMcp.servers, allowedTools: childMcp.allowedTools } : {}),
+    sessionId,
+    // A FRESH run has no session id to hand over: claude reveals its own in the
+    // init frame of its stream, which the progress emitter is already folding.
+    // Pulling from that snapshot means an ask carries the CLI's real session id
+    // without a second parser — and hilos rejects an empty one outright.
+    resolveSessionId,
+    timeoutMs: cfg.runTimeoutMs,
+    signal,
+    log,
+  });
+  try {
+    return await deps.runCli({
+      cmd,
+      args: [...codeArgs, ...server.args, prompt],
+      cwd,
+      timeoutMs: cfg.runTimeoutMs,
+      label: "coding",
+      signal,
+      env: claudeGateEnv(cfg),
+      onData,
+      beforeSpawn,
+      // 0785 — a CLI that rejects the gate flags is retried without them. This
+      // fires BEFORE that ungated retry is spawned, so the room hears about the
+      // downgrade first rather than after the fact.
+      onPermissionGateDropped: onGateDropped,
+    });
+  } finally {
+    try {
+      await server.close();
+    } catch {
+      /* tearing the gate down must never fail a finished run */
+    }
+  }
+}
+
+/**
+ * Will this codex run take the gated transport (0785)?
+ *
+ * Answerable before the run's argv exists, because the only input that can
+ * change the answer is the operator's OWN command — every flag the daemon
+ * appends later (model, dir, image, resume, stream) is ours and none of them is
+ * the bypass tier. Which matters because the PROMPT is written before the
+ * transport is chosen, and what the prompt may claim about images depends on it.
+ */
+export function codexRunIsGated(cfg, testCapabilities) {
+  return shouldGateCodexPermissions({
+    vendor: detectVendor(cfg?.codingCmd),
+    runtimePermissions: testCapabilities?.runtimePermissions,
+    codeArgs: commandArgv(String(cfg?.codingCmd || "")).slice(1),
+  });
+}
+
+/**
+ * Run codex through its gated transport, with an honest fallback (0785).
+ *
+ * A granted workspace ALWAYS gets `codex mcp-server` — that is what the grant
+ * means, and it is the only codex transport that can ask (`codex exec` has no
+ * approval channel at any flag combination, see codex-mcp-session.mjs). The one
+ * thing the grant can't conjure is the subcommand itself: a codex old enough
+ * not to have it never answers the MCP handshake, and before this the run just
+ * failed. Now it degrades to the plain exec argv — the ungated run every codex
+ * did before 0777, never worse.
+ *
+ * Two rules make that degrade safe. It happens ONLY on positive evidence that
+ * the subcommand is absent (codexMcpTransportUnavailable — every other
+ * pre-handshake failure is returned as the failed run it is, because a wrongly
+ * failed run is recoverable and a wrongly ungated one is not). And the room is
+ * told BEFORE the ungated child is spawned, so the warning arrives while the
+ * run can still be stopped.
+ *
+ * The exec argv is the run's real one (model, images, resume, stream flags),
+ * so the fallback is the same run the ungated lane would have made.
+ */
+async function runCodexGatedSession({
+  deps,
+  cfg,
+  onGateDropped,
+  cmd,
+  codeArgs,
+  prompt,
+  cwd,
+  model,
+  resumeThreadId = null,
+  signal,
+  onData,
+  onEvent,
+  beforeSpawn,
+  permissionCallbacks,
+  childMcp = null,
+}) {
+  // 1255 — `codex mcp-server` takes the same global `-c` overrides `codex exec`
+  // does (verified on codex-cli 0.153.4: `codex mcp-server --help` lists
+  // `-c, --config <key=value>`), so the seat reaches both codex transports
+  // through one argv fragment.
+  const childMcpConfig = childMcp ? codexChildMcpArgs(childMcp.url) : [];
+  if (typeof beforeSpawn === "function" && (await beforeSpawn()) === false) {
+    return {
+      status: null,
+      stdout: "",
+      stderr: "",
+      aborted: true,
+      authorityLost: true,
+      error: new Error("execution authority lost before spawn"),
+    };
+  }
+  const run = await deps.runCodexMcpSession({
+    cmd,
+    ...(childMcpConfig.length ? { serverArgs: ["mcp-server", ...childMcpConfig] } : {}),
+    cwd,
+    prompt,
+    sandbox: codexSandboxFromArgs(codeArgs),
+    // 0785 — the resolved tier (0783) or a hand-pinned id. The gated transport
+    // took the account default before this, so a preset was silently ignored
+    // exactly where the operator was most likely to have set one.
+    model: model || null,
+    webSearch: cfg.webSearch !== false,
+    resumeThreadId,
+    timeoutMs: cfg.runTimeoutMs,
+    signal,
+    env: scrubHilosEnv(codingChildEnv(cfg) || process.env),
+    onData,
+    onEvent,
+    beforeSpawn,
+    ...permissionCallbacks,
+  });
+  if (!codexMcpTransportUnavailable(run)) return run;
+  console.log(
+    "  code → this codex has no `mcp-server`; running WITHOUT the hilos permission gate",
+  );
+  // Warn FIRST — before a single ungated command can run.
+  if (typeof onGateDropped === "function") {
+    try {
+      await onGateDropped();
+    } catch {
+      /* telling the room must never break the run */
+    }
+  }
+  const fallback = await deps.runCli({
+    cmd,
+    args: [...codeArgs, ...childMcpConfig, prompt],
+    cwd,
+    timeoutMs: cfg.runTimeoutMs,
+    label: "coding",
+    signal,
+    env: codingChildEnv(cfg),
+    onData,
+    beforeSpawn,
+  });
+  return { ...fallback, permissionGateDropped: true };
+}
+
+/**
+ * One turn on the repo/folder transport ladder (1290). childMcp opens the
+ * turn's seat after its transport is known; it closes before onSettle runs,
+ * including on startup failure. Resume ids and the spawn/settlement hooks are
+ * the repo lane's explicit additions; permissionCallbacks supplies room context.
+ *
+ * @param {{
+ *   deps: any, cfg: any, cmd: string, model?: string | null,
+ *   runtimePermissions?: boolean, vendor: string, codeArgs: string[],
+ *   cwd: string, prompt: string, permissionCallbacks: any,
+ *   childMcp: (options: { standaloneConfig: boolean }) => Promise<any>,
+ *   onData: any, onEvent?: any, signal?: AbortSignal,
+ *   beforeSpawn?: () => boolean | Promise<boolean>,
+ *   resume?: { sessionId: string | null }, runId?: string | null,
+ *   onSettle?: (run: any) => void | Promise<void>,
+ *   onGateDropped: () => void | Promise<void>,
+ *   resolveSessionId?: () => string | null,
+ * }} options
+ */
+export async function runCodingTransport({
+  deps, cfg, cmd, model, runtimePermissions,
+  vendor, codeArgs, cwd, prompt, permissionCallbacks, childMcp,
+  onData, onEvent, signal, beforeSpawn, resume, runId,
+  onSettle, onGateDropped, resolveSessionId,
+}) {
+  let seat = null;
+  let run;
+  try {
+    const useAcpTransport = shouldUseAcpTransport({
+      vendor, acpTransport: cfg.acpTransport, runtimePermissions,
+      codeArgs, codingCmd: cfg.codingCmd,
+    });
+    const useRuntimePermissionBridge = !useAcpTransport && shouldUseRuntimePermissionBridge({
+      vendor, runtimePermissions, codeArgs, codingCmd: cfg.codingCmd,
+    });
+    const gateCodexPermissions = !useAcpTransport && !useRuntimePermissionBridge &&
+      shouldGateCodexPermissions({ vendor, runtimePermissions, codeArgs });
+    const gateClaudePermissions = !useAcpTransport && !useRuntimePermissionBridge && !gateCodexPermissions &&
+      shouldGateClaudePermissions({ vendor, runtimePermissions, codeArgs });
+    seat = await childMcp({ standaloneConfig: vendor === "claude_code" && !gateClaudePermissions });
+    const callbacks = (extra = {}) => openCodePermissionCallbacks({ ...permissionCallbacks, runId, ...extra });
+    if (useAcpTransport) {
+      run = await deps.runAcpSession({
+        cmd, vendor, cwd, prompt,
+        ...(resume ? { resumeSessionId: resume.sessionId } : {}),
+        timeoutMs: cfg.runTimeoutMs, signal,
+        env: scrubHilosEnv(codingChildWebEnv(cfg, vendor) || process.env),
+        onData, onEvent, beforeSpawn,
+        ...callbacks({ provider: vendor }),
+      });
+    } else if (useRuntimePermissionBridge) {
+      run = await deps.runOpenCodeHttpSession({
+        cmd, args: codeArgs, cwd, prompt, timeoutMs: cfg.runTimeoutMs, signal,
+        env: scrubHilosEnv(codingChildWebEnv(cfg, vendor) || process.env),
+        onData, beforeSpawn, ...callbacks(),
+      });
+    } else if (gateCodexPermissions) {
+      run = await runCodexGatedSession({
+        deps, cfg, onGateDropped, cmd, codeArgs, cwd, prompt, model,
+        ...(resume ? { resumeThreadId: resume.sessionId } : {}),
+        signal, onData, onEvent, beforeSpawn, childMcp: seat,
+        permissionCallbacks: callbacks({ provider: vendor, repoRoot: cwd, gateRepoEdits: cfg.gateRepoEdits === true }),
+      });
+    } else if (gateClaudePermissions) {
+      run = await runClaudeGatedCli({
+        deps, cfg, onGateDropped, cmd, codeArgs, cwd, prompt,
+        ...(resume ? { sessionId: resume.sessionId ?? "" } : {}),
+        signal, onData, beforeSpawn, resolveSessionId, childMcp: seat,
+        permissionCallbacks: callbacks({ provider: vendor, repoRoot: cwd, gateRepoEdits: cfg.gateRepoEdits === true }),
+      });
+    } else {
+      run = await deps.runCli({
+        cmd, args: [...codeArgs, ...childMcpArgs(vendor, seat), prompt],
+        cwd, timeoutMs: cfg.runTimeoutMs, label: "coding", signal,
+        env: codingChildWebEnv(cfg, vendor), onData, beforeSpawn,
+      });
+    }
+    // 0785 backstop; the callback's run-scoped latch keeps this notice singular.
+    if (run?.permissionGateDropped) await onGateDropped();
+    return run;
+  } finally {
+    try { await seat?.close(); } catch { /* teardown must never fail a finished run */ }
+    await onSettle?.(run);
+  }
+}