hilos-agent 0.10.1 → 0.11.2

package/src/local-harness-events.mjs

@@ -0,0 +1,370 @@
+// Local coding-runtime stream -> Harness Event Protocol adapter.
+//
+// This is deliberately a side projection of agent-events.mjs. The current
+// progress card keeps consuming its existing AgentEvent stream unchanged; this
+// module reuses that parser to produce replayable HEP inputs without performing
+// a network, storage, or transcript write. A caller must provide a streamId
+// which is stable for the lifetime of one runtime process. Replaying the same
+// bytes with that id produces the same idempotency keys, independent of chunk
+// boundaries.
+
+import { createHash } from "node:crypto";
+
+import { makeStreamParser } from "./agent-events.mjs";
+
+export const LOCAL_HARNESS_LINE_MAX_CHARS = 256 * 1024;
+export const LOCAL_HARNESS_EVENTS_PER_LINE_MAX = 64;
+
+/**
+ * @typedef {object} LocalHarnessContext
+ * @property {string} runtime Claude Code, Codex, Cursor, or OpenCode vendor id.
+ * @property {string} streamId Stable id for one spawned runtime process. It is
+ *   hashed before it enters an event.
+ * @property {string} actorId Hilos agent UUID which owns the local run.
+ * @property {string} [lane]
+ */
+
+/**
+ * The dependency-free package cannot import the app's TypeScript type, so this
+ * JSDoc shape intentionally mirrors `HarnessEventInput` in lib/harness-events.
+ * @typedef {object} LocalHarnessEventInput
+ * @property {string} type
+ * @property {number} version
+ * @property {string} lane
+ * @property {string} runtime
+ * @property {string} turnId
+ * @property {{type: 'agent', id: string}} actor
+ * @property {string} [summary]
+ * @property {'prose'|'command'} [summaryKind]
+ * @property {Record<string, unknown>} payload
+ * @property {string} idempotencyKey
+ */
+
+/** Canonical HEP runtime slug for the aliases accepted by makeStreamParser. */
+export function normalizeLocalHarnessRuntime(runtime) {
+  const value = String(runtime || "").toLowerCase();
+  if (value === "claude" || value === "claude-code" || value === "claude_code") {
+    return "claude_code";
+  }
+  if (value === "codex" || value === "cursor" || value === "opencode") return value;
+  return "custom";
+}
+
+function runtimeLabel(runtime) {
+  if (runtime === "claude_code") return "Claude Code";
+  if (runtime === "codex") return "Codex";
+  if (runtime === "cursor") return "Cursor";
+  if (runtime === "opencode") return "OpenCode";
+  return "The coding runtime";
+}
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function streamDigest(runtime, streamId) {
+  return digest(`local-hep-v1\0${runtime}\0${String(streamId ?? "")}`);
+}
+
+function eventKey(streamHash, sourcePosition, ordinal, type) {
+  return `local-stream-v1:${digest(
+    `${streamHash}\0${sourcePosition}\0${ordinal}\0${type}`,
+  )}`;
+}
+
+function eventSpec(event, runtime) {
+  const label = runtimeLabel(runtime);
+  switch (event && event.t) {
+    case "session":
+      return {
+        type: "run.phase.changed",
+        summary: `${label} session started.`,
+        summaryKind: "prose",
+        payload: {
+          normalizedKind: "session",
+          phase: "runtime_ready",
+          ...(event.sessionId ? { sessionId: event.sessionId } : {}),
+        },
+      };
+    case "phase":
+      return {
+        type: "run.phase.changed",
+        ...(event.name
+          ? { summary: `${label} entered ${event.name}.`, summaryKind: "prose" }
+          : {}),
+        payload: {
+          normalizedKind: "phase",
+          ...(event.name ? { phase: event.name } : {}),
+        },
+      };
+    case "edit":
+      return {
+        type: "tool.started",
+        summary: event.path ? `Editing ${event.path}` : "Editing files",
+        summaryKind: "prose",
+        payload: {
+          normalizedKind: "edit",
+          tool: "file_edit",
+          ...(event.path ? { path: event.path } : {}),
+        },
+      };
+    case "read":
+      return {
+        type: "tool.started",
+        summary: event.path ? `Reading ${event.path}` : "Reading files",
+        summaryKind: "prose",
+        payload: {
+          normalizedKind: "read",
+          tool: "file_read",
+          ...(event.path ? { path: event.path } : {}),
+        },
+      };
+    case "run":
+      return {
+        type: "tool.started",
+        ...(event.cmd ? { summary: event.cmd, summaryKind: "command" } : {}),
+        payload: {
+          normalizedKind: "run",
+          tool: "shell",
+          ...(event.cmd ? { command: event.cmd } : {}),
+        },
+      };
+    case "websearch":
+      return {
+        type: "tool.started",
+        summary: event.query ? `Searching the web for ${event.query}` : "Searching the web",
+        summaryKind: "prose",
+        payload: {
+          normalizedKind: "websearch",
+          tool: "web_search",
+          ...(event.query ? { query: event.query } : {}),
+        },
+      };
+    case "webfetch":
+      return {
+        type: "tool.started",
+        summary: event.target ? `Reading ${event.target}` : "Reading a web page",
+        summaryKind: "prose",
+        payload: {
+          normalizedKind: "webfetch",
+          tool: "web_fetch",
+          ...(event.target ? { target: event.target } : {}),
+        },
+      };
+    case "subagent":
+      return {
+        type: "child.started",
+        ...(event.text
+          ? { summary: `Started a helper: ${event.text}`, summaryKind: "prose" }
+          : {}),
+        payload: {
+          normalizedKind: "subagent",
+          ...(event.text ? { description: event.text } : {}),
+        },
+      };
+    case "note":
+      if (!event.text) return null;
+      return {
+        type: "note.recorded",
+        summary: event.text,
+        summaryKind: "prose",
+        payload: { normalizedKind: "note", text: event.text },
+      };
+    case "usage":
+      return {
+        type: "usage.updated",
+        summary: `${label} reported token usage.`,
+        summaryKind: "prose",
+        payload: {
+          normalizedKind: "usage",
+          inputTokens: event.inputTokens ?? 0,
+          outputTokens: event.outputTokens ?? 0,
+          cacheReadTokens: event.cacheReadTokens ?? 0,
+          cacheCreationTokens: event.cacheCreationTokens ?? 0,
+          ...(event.costUsd == null ? {} : { costUsd: event.costUsd }),
+          ...(event.model ? { model: event.model } : {}),
+        },
+      };
+    case "result":
+      return {
+        type: "turn.completed",
+        ...(event.summary
+          ? { summary: event.summary, summaryKind: "prose" }
+          : {}),
+        payload: {
+          normalizedKind: "result",
+          ok: event.ok !== false,
+          outcome: event.ok === false ? "failed" : "succeeded",
+        },
+      };
+    default:
+      return null;
+  }
+}
+
+/**
+ * Stateful raw-stream adapter. `push` accepts arbitrary stdout chunks and
+ * `flush` must be called exactly once at process EOF. Neither method throws for
+ * malformed runtime output.
+ *
+ * @param {LocalHarnessContext} context
+ */
+export function createLocalHarnessStreamAdapter(context) {
+  const runtime = normalizeLocalHarnessRuntime(context?.runtime);
+  const parser = makeStreamParser(runtime);
+  const streamHash = streamDigest(runtime, context?.streamId);
+  const turnId = `local_${streamHash.slice(0, 32)}`;
+  const lane = context?.lane || "local";
+  const actorId = String(context?.actorId || "");
+  let buffer = "";
+  let lineNumber = 0;
+  let discardedChars = 0;
+  let discarding = false;
+  let structuredEventNumber = 0;
+  let finished = false;
+
+  const materialize = (events, sourcePosition, sourceLine, sourcePhase = "line") => {
+    const specs = events.map((event) => eventSpec(event, runtime)).filter(Boolean);
+    let bounded = specs;
+    if (specs.length > LOCAL_HARNESS_EVENTS_PER_LINE_MAX) {
+      bounded = [
+        ...specs.slice(0, LOCAL_HARNESS_EVENTS_PER_LINE_MAX - 1),
+        {
+          type: "note.recorded",
+          summary: "Additional runtime events were withheld.",
+          summaryKind: "prose",
+          payload: {
+            withheld: true,
+            reason: "runtime_line_event_limit",
+            omittedEvents: specs.length - (LOCAL_HARNESS_EVENTS_PER_LINE_MAX - 1),
+          },
+        },
+      ];
+    }
+    return bounded.map((spec, ordinal) => ({
+      type: spec.type,
+      version: 1,
+      lane,
+      runtime,
+      turnId,
+      actor: { type: "agent", id: actorId },
+      ...(spec.summary === undefined ? {} : { summary: spec.summary }),
+      ...(spec.summaryKind === undefined ? {} : { summaryKind: spec.summaryKind }),
+      payload: {
+        source: "runtime_stream",
+        sourceLine,
+        sourcePhase,
+        ...spec.payload,
+      },
+      idempotencyKey: eventKey(streamHash, sourcePosition, ordinal, spec.type),
+    }));
+  };
+
+  const tooLarge = (sourceLine, originalCharacters) =>
+    materialize(
+      [
+        {
+          t: "note",
+          text: "A runtime event was too large to inspect.",
+        },
+      ],
+      `line:${sourceLine}:withheld`,
+      sourceLine,
+    ).map((event) => ({
+      ...event,
+      payload: {
+        ...event.payload,
+        withheld: true,
+        reason: "runtime_line_too_large",
+        originalCharacters,
+      },
+    }));
+
+  const consumeLine = (line) => {
+    lineNumber += 1;
+    if (line.length > LOCAL_HARNESS_LINE_MAX_CHARS) {
+      return tooLarge(lineNumber, line.length);
+    }
+    return materialize(parser.push(`${line}\n`), `line:${lineNumber}`, lineNumber);
+  };
+
+  return {
+    /** @param {string} chunk @returns {LocalHarnessEventInput[]} */
+    push(chunk) {
+      if (finished) return [];
+      const input = String(chunk ?? "");
+      const out = [];
+      let start = 0;
+      while (start < input.length) {
+        const newline = input.indexOf("\n", start);
+        const end = newline === -1 ? input.length : newline;
+        const fragment = input.slice(start, end);
+        if (discarding) {
+          discardedChars += fragment.length;
+        } else {
+          buffer += fragment;
+          if (buffer.length > LOCAL_HARNESS_LINE_MAX_CHARS) {
+            discarding = true;
+            discardedChars = buffer.length;
+            buffer = "";
+          }
+        }
+        if (newline === -1) break;
+        if (discarding) {
+          lineNumber += 1;
+          out.push(...tooLarge(lineNumber, discardedChars));
+          discarding = false;
+          discardedChars = 0;
+        } else {
+          out.push(...consumeLine(buffer));
+          buffer = "";
+        }
+        start = newline + 1;
+      }
+      return out;
+    },
+
+    /**
+     * Structured permission transports deliver normalized AgentEvents beside
+     * stdout rather than encoding tool calls into it. Keep those facts in the
+     * same stream with their own deterministic process-local coordinate.
+     * @param {Record<string, unknown>} event
+     * @returns {LocalHarnessEventInput[]}
+     */
+    pushEvent(event) {
+      if (finished) return [];
+      structuredEventNumber += 1;
+      return materialize(
+        [event],
+        `event:${structuredEventNumber}`,
+        lineNumber || 1,
+        "event",
+      );
+    },
+
+    /** @returns {LocalHarnessEventInput[]} */
+    flush() {
+      if (finished) return [];
+      finished = true;
+      const out = [];
+      if (discarding) {
+        lineNumber += 1;
+        out.push(...tooLarge(lineNumber, discardedChars));
+      } else if (buffer.length) {
+        out.push(...consumeLine(buffer));
+      }
+      buffer = "";
+      discarding = false;
+      discardedChars = 0;
+      out.push(
+        ...materialize(
+          parser.flush(),
+          `flush:${lineNumber}`,
+          lineNumber || 1,
+          "flush",
+        ),
+      );
+      return out;
+    },
+  };
+}

package/src/local-harness-transport.mjs

@@ -0,0 +1,157 @@
+// Best-effort local HEP batching. This module owns no MCP client; the daemon
+// injects its existing `tool` function so tests stay offline and older servers
+// simply leave the emitter disabled through tools/list capability detection.
+
+import { createLocalHarnessStreamAdapter } from "./local-harness-events.mjs";
+
+export const LOCAL_HARNESS_APPEND_BATCH_MAX = 64;
+export const LOCAL_HARNESS_OUTSTANDING_MAX = 512;
+export const LOCAL_HARNESS_ATTEMPT_TIMEOUT_MS = 1_000;
+
+/**
+ * @param {{
+ *   tool: (name: string, args: Record<string, unknown>) => Promise<any>|any,
+ *   runId: string,
+ *   runtime: string,
+ *   streamId: string,
+ *   actorId: string,
+ *   lane?: string,
+ *   attemptTimeoutMs?: number,
+ *   setTimer?: (callback: () => void, ms: number) => any,
+ *   clearTimer?: (timer: any) => void,
+ * }} options
+ */
+export function createLocalHarnessEmitter(options) {
+  const adapter = createLocalHarnessStreamAdapter({
+    runtime: options.runtime,
+    streamId: options.streamId,
+    actorId: options.actorId,
+    lane: options.lane ?? "local",
+  });
+  let pending = [];
+  let inflight = Promise.resolve();
+  let scheduled = 0;
+  let finished = false;
+  const attemptTimeoutMs = Math.max(
+    1,
+    Number(options.attemptTimeoutMs) || LOCAL_HARNESS_ATTEMPT_TIMEOUT_MS,
+  );
+  const setTimer = options.setTimer ?? setTimeout;
+  const clearTimer = options.clearTimer ?? clearTimeout;
+  const stats = {
+    accepted: 0,
+    appended: 0,
+    replayed: 0,
+    rejected: 0,
+    dropped: 0,
+    retries: 0,
+  };
+
+  const attempt = async (batch) => {
+    let timer;
+    try {
+      const request = Promise.resolve().then(() =>
+        options.tool("append_run_events", {
+          runId: options.runId,
+          events: batch,
+        }),
+      );
+      const deadline = new Promise((_, reject) => {
+        timer = setTimer(
+          () => reject(new Error("append_run_events timed out")),
+          attemptTimeoutMs,
+        );
+        timer?.unref?.();
+      });
+      return await Promise.race([request, deadline]);
+    } finally {
+      if (timer !== undefined) clearTimer(timer);
+    }
+  };
+
+  const send = (batch) => {
+    scheduled += batch.length;
+    inflight = inflight
+      .then(async () => {
+        let response;
+        try {
+          response = await attempt(batch);
+        } catch {
+          // One immediate lost-response retry. Stable HEP keys make a first
+          // successful append replay instead of duplicating when its response
+          // was the part that disappeared.
+          stats.retries += 1;
+          try {
+            response = await attempt(batch);
+          } catch {
+            stats.rejected += batch.length;
+            return;
+          }
+        }
+        if (!response || response.ok === false) {
+          stats.rejected += batch.length;
+          return;
+        }
+        stats.appended += Number(response.appended) || 0;
+        stats.replayed += Number(response.replayed) || 0;
+        stats.rejected += Number(response.rejected) || 0;
+      })
+      .catch(() => {
+        // No observer failure is allowed to reach the coding process.
+        stats.rejected += batch.length;
+      })
+      .finally(() => {
+        scheduled -= batch.length;
+      });
+  };
+
+  const accept = (events) => {
+    if (!events?.length) return;
+    const available = Math.max(
+      0,
+      LOCAL_HARNESS_OUTSTANDING_MAX - scheduled - pending.length,
+    );
+    const kept = events.slice(0, available);
+    pending.push(...kept);
+    stats.accepted += kept.length;
+    stats.dropped += events.length - kept.length;
+    while (pending.length >= LOCAL_HARNESS_APPEND_BATCH_MAX) {
+      send(pending.splice(0, LOCAL_HARNESS_APPEND_BATCH_MAX));
+    }
+  };
+
+  return {
+    push(chunk) {
+      if (finished) return;
+      try {
+        accept(adapter.push(chunk));
+      } catch {
+        /* parser failure degrades telemetry only */
+      }
+    },
+    pushEvent(event) {
+      if (finished) return;
+      try {
+        accept(adapter.pushEvent(event));
+      } catch {
+        /* parser failure degrades telemetry only */
+      }
+    },
+    async drain() {
+      if (!finished) {
+        finished = true;
+        try {
+          accept(adapter.flush());
+        } catch {
+          /* parser failure degrades telemetry only */
+        }
+        if (pending.length) send(pending.splice(0));
+      }
+      await inflight.catch(() => {});
+      return { ...stats };
+    },
+    stats() {
+      return { ...stats };
+    },
+  };
+}