hilos-agent 0.11.12 → 0.11.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hilos-agent",
-  "version": "0.11.12",
+  "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/acp-session.mjs

@@ -19,6 +19,7 @@
 import { spawn } from "node:child_process";
 import { createAcpEventMapper } from "./agent-events.mjs";
 import { resolveHilosPermissionReply } from "./permission-gate.mjs";
+import { abortError, isObject, raceWithAbort } from "./util.mjs";
 
 const DEFAULT_TIMEOUT_MS = 30 * 60_000;
 const DEFAULT_POLL_MS = 1_000;
@@ -26,35 +27,6 @@ const SHUTDOWN_GRACE_MS = 750;
 const PROTOCOL_VERSION = 1;
 const MAX_LINE_BYTES = 4 * 1024 * 1024;
 
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function abortError(reason = "cancelled") {
-  const error = new Error(String(reason || "cancelled"));
-  error.name = "AbortError";
-  return error;
-}
-
-function raceWithAbort(promise, signal) {
-  if (!signal) return promise;
-  if (signal.aborted) return Promise.reject(abortError(signal.reason));
-  return new Promise((resolve, reject) => {
-    const onAbort = () => reject(abortError(signal.reason));
-    signal.addEventListener("abort", onAbort, { once: true });
-    Promise.resolve(promise).then(
-      (value) => {
-        signal.removeEventListener("abort", onAbort);
-        resolve(value);
-      },
-      (error) => {
-        signal.removeEventListener("abort", onAbort);
-        reject(error);
-      },
-    );
-  });
-}
-
 /**
  * Choose the agent's option id for a hilos reply ("once"|"always"|"reject").
  * Matches on the ACP option `kind` first (allow_once / allow_always /

package/src/agent-events.mjs

@@ -16,16 +16,16 @@
 //     stripped, length capped) — a chatty CLI can echo a `Bearer …` header.
 //
 // Claude shapes here MATCH `lib/hosted-worklog.ts` / `lib/hosted-agent.ts`
-// (`formatClaudeEvent`, `parseStreamResult`) so ticket 0274 can swap the daemon's
-// hand-rolled `lastLine` capture (see handler.mjs onData ~:787) for this parser
-// with zero behavior change. NOTHING imports this yet except the test — wiring is
-// 0274.
+// (`formatClaudeEvent`, `parseStreamResult`) so the daemon and the hosted path
+// render the same run from the same shapes (0274).
+
+import { COMMAND_LABEL_MAX, truncate } from "./util.mjs";
 
 /**
  * @typedef {object} AgentEvent
  * A normalized, render-ready step. Exactly one of these per meaningful thing the
  * coding agent did. Small on purpose — the LiveRunCard maps `t` to a label.
- * @property {'phase'|'edit'|'run'|'read'|'think'|'note'|'session'|'result'|'usage'|'websearch'|'webfetch'|'subagent'} t
+ * @property {'edit'|'run'|'read'|'think'|'note'|'session'|'result'|'usage'|'websearch'|'webfetch'|'subagent'} t
  *   - 'session' → { sessionId }        the CLI's resumable session id (init only)
  *   - 'edit'    → { path }             wrote/edited a file
  *   - 'read'    → { path }             read a file
@@ -44,9 +44,6 @@
  *                                      reported it (0787). Never a step — the
  *                                      ring and the activity fold skip it; it
  *                                      rides home on the report instead.
- *   - 'phase'   → { name }             reserved lifecycle marker (unused by v1
- *                                       parsers; kept so 0274 can add start/end
- *                                       phases without widening the type)
  * @property {string} [sessionId]
  * @property {string} [path]
  * @property {string} [cmd]
@@ -95,7 +92,7 @@ export function sanitizeText(value) {
   if (typeof value !== "string") return "";
   let out = value;
   for (const re of SECRET_PATTERNS) out = out.replace(re, REDACTED);
-  if (out.length > MAX_LEN) out = out.slice(0, MAX_LEN - 1) + "…";
+  out = truncate(out, MAX_LEN);
   return out;
 }
 
@@ -269,7 +266,7 @@ function webPhrase(value) {
   // would render.
   const clean = sanitizeText(raw);
   if (!clean) return "";
-  return clean.length > WEB_LABEL_MAX ? clean.slice(0, WEB_LABEL_MAX - 1) + "…" : clean;
+  return truncate(clean, WEB_LABEL_MAX);
 }
 
 /**
@@ -879,7 +876,7 @@ function normalizeVendor(vendor) {
 // --- Streaming parsers -----------------------------------------------------
 
 /**
- * The daemon pushes raw stdout chunks (see handler.mjs onData ~:787) that can
+ * The daemon pushes raw stdout chunks (handler.mjs `handleCliData`) that can
  * split a JSON object mid-line. A structured parser buffers the partial tail and
  * only parses COMPLETE lines; flush() drains a trailing unterminated line.
  * @param {(line: string) => AgentEvent[]} parseLine
@@ -913,7 +910,7 @@ function makeLineBufferedParser(parseLine) {
  * Fallback for any vendor with no structured stream (cursor graduated to a
  * real parser in 0573). There's nothing to parse, so we only remember the last
  * non-empty line seen — matching exactly what the daemon does today
- * (handler.mjs onData) so we NEVER regress below it — and emit at most one
+ * (handler.mjs `handleCliData`) so we NEVER regress below it — and emit at most one
  * sparse note on flush.
  */
 function makeTextTailParser() {
@@ -964,13 +961,13 @@ function describeRun(cmd) {
   const c = String(cmd || "").trim();
   if (!c) return "Running a command";
   if (/\b(test|tests)\b|vitest|jest|pytest|\bgo test\b/i.test(c)) return "Running tests";
-  const short = c.length > 60 ? c.slice(0, 59) + "…" : c;
+  const short = truncate(c, COMMAND_LABEL_MAX);
   return `Running ${short}`;
 }
 
 /**
  * One AgentEvent → a human step label, or null for events that aren't shown as
- * steps (session/phase are metadata). Pure.
+ * steps (session events are metadata). Pure.
  * @param {AgentEvent} event
  * @returns {string | null}
  */
@@ -993,7 +990,7 @@ export function stepLabel(event) {
     case "result":
       return event.ok ? "Done" : "Finished with errors";
     default:
-      return null; // session / phase / unknown → not a step
+      return null; // session / unknown → not a step
   }
 }
 
@@ -1081,7 +1078,7 @@ function activitySentence(row) {
  * truth a CLI stream carries, so "done" is the sequential-execution inference:
  * a new action starting settles the one in flight. `settle("failed")` is for a
  * dying run — leaving "Editing…" forever is the dishonesty this feed exists to
- * avoid. session/phase events are metadata, not rows (same as stepLabel).
+ * avoid. session events are metadata, not rows (same as stepLabel).
  * @param {number} [limit]
  */
 export function createActivityFold(limit = MAX_ACTIVITY) {
@@ -1151,7 +1148,7 @@ export function createActivityFold(limit = MAX_ACTIVITY) {
         });
         return;
       default:
-        return; // session / phase / unknown — metadata, not activity
+        return; // session / unknown — metadata, not activity
     }
   }
 

package/src/agent-result.mjs

@@ -0,0 +1,56 @@
+// 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 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.",
+  "- 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");
+
+export const AGENT_CODE_RESULT_RULE = [
+  AGENT_REPLY_STYLE_RULE,
+  "When the coding turn finishes, return one fenced hilos-result JSON object with three string fields:",
+  '{"summary":"The short result for the teammate.","prTitle":"A short title describing the actual problem fixed","prDescription":"The problem, resulting behavior, and relevant verification."}',
+  "Write summary for someone who may never open the code. Do not repeat the PR title, request, branch, file counts, or tool history. Include material limitations.",
+  "Write prTitle and prDescription as the pull request itself for a reviewer opening it cold. Title: under 60 characters, no trailing period or request echo. Description: usually 1-2 short paragraphs; only actual checks. No transcript, preamble, boilerplate, or attribution footer; hilos adds credit.",
+  "If you create or update the PR yourself, use those same title and description fields on GitHub. Describe the entire final PR change, including prior work on an iteration. Preserve text a person edited.",
+  "Return empty PR fields when there is no code change. A VISUAL_PREVIEW: /route line may follow the fence.",
+].join("\n");
+
+/** Keep complete artifacts, never half a sentence, Markdown link, or JSON object. */
+export function retainAgentResult(value) {
+  return typeof value === "string" && value.length <= 32_000 ? value.trim() : "";
+}
+
+/** @returns {{ summary: string, prTitle: string, prDescription: string } | null} */
+export function readAgentResult(value) {
+  const text = retainAgentResult(value);
+  const fenced = /```hilos-result\s*\n([\s\S]*?)\n```/.exec(text);
+  const candidate = fenced?.[1] ?? (text.startsWith("{") ? text : null);
+  if (!candidate) return null;
+  try {
+    const result = JSON.parse(candidate);
+    if (!result || typeof result !== "object" || typeof result.summary !== "string" ||
+        typeof result.prTitle !== "string" || typeof result.prDescription !== "string") return null;
+    return {
+      summary: result.summary.trim(),
+      prTitle: result.prTitle.trim(),
+      prDescription: result.prDescription.trim(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Legacy prose remains readable; an invalid machine envelope never enters chat. */
+export function agentResultText(value) {
+  const text = retainAgentResult(value);
+  const result = readAgentResult(text);
+  if (result) return result.summary;
+  if (text.includes("```hilos-result") || /^\s*\{\s*"(?:summary|prTitle|prDescription)"/.test(text)) return "";
+  return text.replace(/^\s*VISUAL_PREVIEW:.*$/gm, "").trim();
+}

package/src/child-mcp.mjs

@@ -147,7 +147,7 @@ export function childMcpPlanned({ cfg, vendor, bindingClaim, env } = {}) {
 }
 
 /** The `mcpServers` fragment for a claude `--mcp-config` JSON. */
-export function childMcpServers(url) {
+function childMcpServers(url) {
   return { [CHILD_MCP_SERVER]: { type: "http", url } };
 }
 
@@ -159,7 +159,7 @@ export function childMcpServers(url) {
  * config file instead — claude takes `--mcp-config` more than once, but one
  * file the run owns end-to-end is one file to delete.
  */
-export function writeChildMcpConfig(url, { dir = os.tmpdir() } = {}) {
+function writeChildMcpConfig(url, { dir = os.tmpdir() } = {}) {
   const configPath = path.join(
     dir,
     `hilos-child-mcp-${process.pid}-${randomBytes(6).toString("hex")}.json`,

package/src/claude-permissions.mjs

@@ -38,6 +38,7 @@ import {
   DEFAULT_PERMISSION_TIMEOUT_MS,
   resolveHilosPermissionReply,
 } from "./permission-gate.mjs";
+import { isObject } from "./util.mjs";
 
 /** The MCP server key and tool name the daemon serves. Together they form the
  *  `mcp__<server>__<tool>` identifier claude's flag takes. */
@@ -54,10 +55,6 @@ const DEFAULT_SESSION_ID_WAIT_MS = 10_000;
 /** Tool names whose input names a file rather than a command. */
 const FILE_INPUT_KEYS = ["file_path", "path", "notebook_path"];
 
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Shape claude's permission-prompt payload into the SAME vendor-neutral request
  * the opencode/ACP card flow already produces, so the card, its audit row, and
@@ -184,9 +181,6 @@ export function claudePermissionArgs({
   ];
 }
 
-/** The flags to strip when a CLI turns out not to know them (compat retry). */
-export const CLAUDE_PERMISSION_FLAGS = ["--mcp-config", "--permission-prompt-tool"];
-
 /**
  * Serve the permission tool on loopback for the life of one run.
  *
@@ -209,8 +203,7 @@ export const CLAUDE_PERMISSION_FLAGS = ["--mcp-config", "--permission-prompt-too
  *   allowedTools?: string,
  * }} options
  * @returns {Promise<{ configPath: string, toolId: string, url: string, port: number,
- *   args: string[], setSessionId: (value: string) => void, pending: () => number,
- *   close: () => Promise<void> }>}
+ *   args: string[], close: () => Promise<void> }>}
  */
 export async function startClaudePermissionServer({
   requestPermission,
@@ -235,7 +228,6 @@ export async function startClaudePermissionServer({
   }
   const token = randomBytes(24).toString("hex");
   let seq = 0;
-  let inflight = 0;
   let currentSessionId = String(sessionId || "");
   // hilos's server REJECTS a permission request with an empty vendorSessionId,
   // so a fresh run (no session to resume) must not ask with one — every card
@@ -373,33 +365,25 @@ export async function startClaudePermissionServer({
         sessionId: await sessionIdForAsk(),
         fallbackId: String(++seq),
       });
-      inflight++;
-      let outcome = "transport-error";
-      // Set only when a workspace RULE refused this ask (0813); a person's
-      // rejection leaves these alone and keeps the human wording. Provenance is
-      // tracked apart from the reason because a rule may carry no reason.
-      let byPolicy = false;
-      let policyReason = null;
-      let decisionReply = "reject";
-      try {
-        const resolved = await resolveHilosPermissionReply({
-          request,
-          requestPermission,
-          getPermissionDecision,
-          signal,
-          timeoutMs,
-          pollIntervalMs,
-          log,
-          label: "claude permission",
-          localAllow,
-        });
-        decisionReply = resolved.reply;
-        outcome = resolved.outcome;
-        byPolicy = resolved.byPolicy === true;
-        policyReason = resolved.policyReason ?? null;
-      } finally {
-        inflight--;
-      }
+      const resolved = await resolveHilosPermissionReply({
+        request,
+        requestPermission,
+        getPermissionDecision,
+        signal,
+        timeoutMs,
+        pollIntervalMs,
+        log,
+        label: "claude permission",
+        localAllow,
+      });
+      const decisionReply = resolved.reply;
+      const outcome = resolved.outcome;
+      // byPolicy is set only when a workspace RULE refused this ask (0813); a
+      // person's rejection leaves it false and keeps the human wording.
+      // Provenance is tracked apart from the reason because a rule may carry no
+      // reason.
+      const byPolicy = resolved.byPolicy === true;
+      const policyReason = resolved.policyReason ?? null;
       // A rejection is never an MCP error: an isError result makes claude retry
       // or improvise around the block. A plain deny result is the refusal the
       // CLI is built to respect.
@@ -452,11 +436,6 @@ export async function startClaudePermissionServer({
     url,
     port,
     args: claudePermissionArgs({ configPath, allowedTools }),
-    /** Let the caller stamp the CLI's real session id onto later cards. */
-    setSessionId(value) {
-      if (typeof value === "string" && value) currentSessionId = value;
-    },
-    pending: () => inflight,
     async close() {
       try {
         fs.unlinkSync(configPath);

package/src/cli.mjs

@@ -6,6 +6,7 @@
 // logs a periodic "still working…" heartbeat so the run visibly stays alive.
 
 import { spawn } from "node:child_process";
+import { truncate } from "./util.mjs";
 
 /**
  * Let the daemon finish its existing abort/cleanup path before exiting.
@@ -150,8 +151,7 @@ export function fmtElapsed(ms) {
 
 /** Collapse to one trimmed, length-capped line (for a heartbeat's "Latest:" tail). */
 export function oneLine(s, max = 140) {
-  const t = String(s || "").replace(/\s+/g, " ").trim();
-  return t.length > max ? t.slice(0, max - 1) + "…" : t;
+  return truncate(String(s || "").replace(/\s+/g, " ").trim(), max);
 }
 
 /**

package/src/codex-mcp-session.mjs

@@ -58,6 +58,7 @@ import {
   DEFAULT_PERMISSION_TIMEOUT_MS,
   resolveHilosPermissionReply,
 } from "./permission-gate.mjs";
+import { isObject } from "./util.mjs";
 
 // Codex 0.153.4 accepts on-request/never on its MCP tool. `untrusted`
 // is rejected before a turn starts. Keep the workspace sandbox and route its
@@ -65,16 +66,6 @@ import {
 const DEFAULT_TIMEOUT_MS = 30 * 60_000;
 const SHUTDOWN_GRACE_MS = 750;
 
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function abortError(reason = "cancelled") {
-  const error = new Error(String(reason || "cancelled"));
-  error.name = "AbortError";
-  return error;
-}
-
 /**
  * Render codex's argv-array command as the one line a human decides about.
  * Codex wraps shell work as ["/bin/zsh","-lc","<the real command>"]; showing