harnery 0.0.1 → 0.2.1

package/dist/core/agents/codex-replay.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Codex JSONL → canonical event replay.
+ *
+ * Production codex sessions emit canonical events from each `harn` invocation
+ * via the in-process session-tee middleware (which calls `agent-coord
+ * emit-event` for state.task_set / state.status_checked). But the codex
+ * harness itself doesn't wire agent-hook on preToolUse, so user_prompt.submit
+ * + tool.pre_use + turn.stop aren't emitted live.
+ *
+ * This module parses the Codex JSONL transcript at stop time and emits the
+ * missing canonical events so the verdict has a complete turn-window view.
+ *
+ * Scope: just the events the stop-hook verdict reads: user_prompt.submit,
+ * tool.pre_use (for exec_command function calls), state.status_checked
+ * (when the cmd contains `<bin> agents status`), state.task_set (when the cmd
+ * contains `<bin> agents set-task`), turn.stop (with status_box_present derived
+ * from the last_assistant_message).
+ */
+export interface CodexReplayOpts {
+    coordRoot: string;
+    sessionId: string;
+    instanceId: string;
+    jsonlPath: string;
+    lastAssistantMessage?: string;
+}
+export declare function replayCodexJsonl(opts: CodexReplayOpts): {
+    emitted: number;
+};
+//# sourceMappingURL=codex-replay.d.ts.map

package/dist/core/agents/codex-replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-replay.d.ts","sourceRoot":"","sources":["../../../src/core/agents/codex-replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkBH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAkH3E"}

package/dist/core/agents/codex-replay.js

@@ -0,0 +1,138 @@
+/**
+ * Codex JSONL → canonical event replay.
+ *
+ * Production codex sessions emit canonical events from each `harn` invocation
+ * via the in-process session-tee middleware (which calls `agent-coord
+ * emit-event` for state.task_set / state.status_checked). But the codex
+ * harness itself doesn't wire agent-hook on preToolUse, so user_prompt.submit
+ * + tool.pre_use + turn.stop aren't emitted live.
+ *
+ * This module parses the Codex JSONL transcript at stop time and emits the
+ * missing canonical events so the verdict has a complete turn-window view.
+ *
+ * Scope: just the events the stop-hook verdict reads: user_prompt.submit,
+ * tool.pre_use (for exec_command function calls), state.status_checked
+ * (when the cmd contains `<bin> agents status`), state.task_set (when the cmd
+ * contains `<bin> agents set-task`), turn.stop (with status_box_present derived
+ * from the last_assistant_message).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { emit } from "./events/emit.js";
+const STATUS_BOX_PREFIX = "┌─ agent-";
+export function replayCodexJsonl(opts) {
+    const { coordRoot, sessionId, instanceId, jsonlPath, lastAssistantMessage } = opts;
+    if (!existsSync(jsonlPath))
+        return { emitted: 0 };
+    let raw;
+    try {
+        raw = readFileSync(jsonlPath, "utf8");
+    }
+    catch {
+        return { emitted: 0 };
+    }
+    let emitted = 0;
+    const lines = raw.split("\n");
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const ts = entry.timestamp;
+        const t = entry.type;
+        if (t === "event_msg" && entry.payload?.type === "user_message") {
+            emit(coordRoot, {
+                event_type: "user_prompt.submit",
+                instance_id: instanceId,
+                session_id: sessionId,
+                harness: "codex",
+                ts,
+                data: {
+                    prompt_text: clamp(entry.payload.message ?? "", 4000),
+                },
+            });
+            emitted += 1;
+            continue;
+        }
+        if (t === "response_item" && entry.payload?.type === "function_call") {
+            const name = entry.payload.name ?? "";
+            let cmd = "";
+            if (entry.payload.arguments) {
+                try {
+                    const parsed = JSON.parse(entry.payload.arguments);
+                    cmd = parsed.cmd ?? "";
+                }
+                catch {
+                    /* skip */
+                }
+            }
+            // Emit tool.pre_use for every function call.
+            emit(coordRoot, {
+                event_type: "tool.pre_use",
+                instance_id: instanceId,
+                session_id: sessionId,
+                harness: "codex",
+                ts,
+                data: {
+                    tool_name: name === "exec_command" ? "Bash" : name,
+                    tool_input: JSON.stringify({ command: cmd }),
+                    intent: "",
+                    intent_source: "codex-replay",
+                },
+            });
+            emitted += 1;
+            // Match `<bin> agents status` / `<bin> agents set-task`, bin-agnostic, so
+            // it works for harn or any host CLI that composes harnery (a consumer's own
+            // binary). Wrapped invocations (cd && <bin> ...; PATH=... <bin> ...) pass
+            // because we scan the whole cmd string and anchor on the token before `agents`.
+            if (/(^|\s|;|&&)[\w./-]+\s+agents\s+status(\b|$)/.test(cmd)) {
+                emit(coordRoot, {
+                    event_type: "state.status_checked",
+                    instance_id: instanceId,
+                    session_id: sessionId,
+                    harness: "codex",
+                    ts,
+                    data: { source: "codex-replay" },
+                });
+                emitted += 1;
+            }
+            if (/(^|\s|;|&&)[\w./-]+\s+agents\s+set-task(\b|$)/.test(cmd)) {
+                emit(coordRoot, {
+                    event_type: "state.task_set",
+                    instance_id: instanceId,
+                    session_id: sessionId,
+                    harness: "codex",
+                    ts,
+                    data: { source: "codex-replay" },
+                });
+                emitted += 1;
+            }
+        }
+    }
+    // Finally, emit turn.stop with status_box_present derived from the last
+    // assistant message (codex's stop payload carries the assistant text
+    // directly, unlike CC which only has transcript_path).
+    const boxPresent = !!lastAssistantMessage && lastAssistantMessage.includes(STATUS_BOX_PREFIX);
+    emit(coordRoot, {
+        event_type: "turn.stop",
+        instance_id: instanceId,
+        session_id: sessionId,
+        harness: "codex",
+        data: {
+            status_box_present: boxPresent,
+            tool_call_count: -1,
+            text_length: lastAssistantMessage?.length ?? 0,
+        },
+    });
+    emitted += 1;
+    return { emitted };
+}
+function clamp(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max);
+}

package/dist/core/agents/coord-client.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The coordination helpers.
+ *
+ * Both surfaces (bash hooks + this TS module) write into the same
+ * `.harnery/active/<owner>.json` heartbeat files and `.harnery/pid-map/`
+ * ppid map, so a single coord state can be observed and mutated from
+ * either side without divergence.
+ */
+export interface Heartbeat {
+    instance_id: string;
+    name?: string;
+    kind?: string;
+    session_id: string;
+    agent_id: string;
+    model: string;
+    started_at: string;
+    last_heartbeat: string;
+    files_touched: string[];
+    agent_type?: string;
+    /** Most recent tool name stamped by the PostToolUse hook. Phase 1. */
+    last_tool?: string;
+    /** Short string identifying what the last tool acted on (file path, command head, URL). Phase 1. */
+    last_tool_target?: string;
+    /** Free-form task/intent string set via `harn agents set-task`. Phase 2. */
+    task?: string;
+    /** UTC ISO-8601 timestamp when task was last set/cleared. Used by harnesses without Stop enforcement to compute staleness. 2026-05-24. */
+    task_updated_at?: string | null;
+    /** Auto-generated per-turn summary written by the Stop hook via Haiku. 2026-05-23. */
+    turn_summary?: string | null;
+    /** UTC ISO-8601 timestamp when turn_summary was last refreshed. */
+    turn_summary_updated_at?: string | null;
+    /** Hook client: `claude_code` (default) or `cursor`. Cursor Phase 1. */
+    platform?: string;
+}
+/**
+ * Resolve the monorepo root for coord-state purposes.
+ *
+ * Resolves the coordination root,
+ * including the `--git-common-dir` fallback that strips
+ * `<superproject>/.git/modules/<name>/` to recover the superproject for
+ * submodule worktrees. Without that fallback, a TS coord caller running
+ * inside a `harn worktree add-submodule` checkout would resolve a different
+ * `.harnery/` than the bash hooks and the two layers would silently diverge.
+ */
+export declare function monorepoRoot(): string | null;
+/** Parse owner from a pid-map row (`owner` or `owner\tplatform`). */
+export declare function parsePidmapRowOwner(row: string): string;
+/** Parse platform from a pid-map row; legacy rows default to `claude_code`. */
+export declare function parsePidmapRowPlatform(row: string): string;
+/**
+ * Walk up the ppid chain looking for a pid-map entry. Returns
+ * the resolved instance_id or null.
+ *
+ * Pid-map files are `instance_id` or `instance_id\tplatform` (Cursor Phase 1).
+ * Prefer a row whose platform matches `HARNERY_AGENT_COORD_PLATFORM` (default
+ * `claude_code`); otherwise return the first owner seen on the walk.
+ *
+ * Subagents intentionally do not write pid-map entries; a Bash-tool ppid-walk
+ * from inside a subagent therefore resolves to the *parent's* pid-map entry.
+ * v1 ships this behavior; a real subagent-aware bridge is out of scope.
+ */
+export declare function resolveOwner(): string | null;
+/**
+ * Like `resolveOwner` but also reports which resolution path matched.
+ * Used by `harn agents whoami` to surface the path (`env` / `pidmap`) in
+ * the diagnostic output. Operators trying to debug "why doesn't my
+ * Codex session see itself?" need to know whether `HARNERY_AGENT_COORD_OWNER`
+ * is propagating or the ppid-walk is the load-bearing path.
+ */
+export declare function resolveOwnerWithSource(): {
+    owner: string | null;
+    source: "env" | "pidmap" | "pidmap_fallback" | "none";
+};
+/**
+ * Read and parse a heartbeat file. Returns null if the file is missing,
+ * unreadable, or contains malformed JSON. Does not throw.
+ *
+ * Phase 8 cleanup (2026-05-27): the v1/v2 dual-write bridge is gone; the
+ * projector writes additively-merged heartbeats directly to
+ * `.harnery/active/<id>.json` (the canonical location every reader expects).
+ */
+export declare function readHeartbeat(instanceId: string): Heartbeat | null;
+/**
+ * Render the display form for an instance_id: `agent-<Name>` if the heartbeat
+ * carries a non-empty `.name`, else `agent-<8-char-hex-prefix>`.
+ *
+ * Hex fallback handles three cases cleanly:
+ *  - heartbeat written before this feature shipped (no `name` field)
+ *  - heartbeat pruned but instance_id still appears in older log lines
+ *  - the narrow window between instance_id resolution and heartbeat read
+ */
+export declare function displayName(instanceId: string): string;
+/**
+ * Convenience: resolve self via ppid walk, then render. Returns
+ * `agent-unknown` when the walk fails.
+ */
+export declare function selfDisplayName(): string;
+//# sourceMappingURL=coord-client.d.ts.map

package/dist/core/agents/coord-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coord-client.d.ts","sourceRoot":"","sources":["../../../src/core/agents/coord-client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oGAAoG;IACpG,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0IAA0I;IAC1I,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CA0C5C;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI1D;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,iBAAiB,GAAG,MAAM,CAAC;CACvD,CAgCA;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAKlE;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAIxC"}

package/dist/core/agents/coord-client.js

@@ -0,0 +1,212 @@
+/**
+ * The coordination helpers.
+ *
+ * Both surfaces (bash hooks + this TS module) write into the same
+ * `.harnery/active/<owner>.json` heartbeat files and `.harnery/pid-map/`
+ * ppid map, so a single coord state can be observed and mutated from
+ * either side without divergence.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Resolve the monorepo root for coord-state purposes.
+ *
+ * Resolves the coordination root,
+ * including the `--git-common-dir` fallback that strips
+ * `<superproject>/.git/modules/<name>/` to recover the superproject for
+ * submodule worktrees. Without that fallback, a TS coord caller running
+ * inside a `harn worktree add-submodule` checkout would resolve a different
+ * `.harnery/` than the bash hooks and the two layers would silently diverge.
+ */
+export function monorepoRoot() {
+    // Test-only override (matches bash HARNERY_COORD_ROOT_OVERRIDE). Lets tests
+    // seed `.harnery/pid-map/<pid>` + `.harnery/active/<owner>.json` fixtures
+    // in a tmpdir without needing a real git repo.
+    const rootOverride = process.env.HARNERY_COORD_ROOT_OVERRIDE;
+    if (rootOverride) {
+        return rootOverride;
+    }
+    // 1. Superproject working tree (when running from inside a submodule).
+    const sup = spawnSync("git", ["rev-parse", "--show-superproject-working-tree"], {
+        encoding: "utf8",
+    });
+    if (sup.status === 0 && sup.stdout.trim() !== "") {
+        return sup.stdout.trim();
+    }
+    // 2. --git-common-dir fallback for submodule worktrees. `git worktree add`
+    // inside a submodule produces a worktree whose --show-superproject-working-
+    // tree is empty (the worktree has no submodule relationship of its own),
+    // but --git-common-dir points at <superproject>/.git/modules/<name>/, so
+    // we recover the superproject by stripping that suffix.
+    const common = spawnSync("git", ["rev-parse", "--git-common-dir"], {
+        encoding: "utf8",
+    });
+    if (common.status === 0) {
+        const cd = common.stdout.trim();
+        const idx = cd.indexOf("/.git/modules/");
+        if (idx !== -1) {
+            return cd.substring(0, idx);
+        }
+    }
+    // 3. Top-level fallback (regular checkout).
+    const top = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+        encoding: "utf8",
+    });
+    if (top.status === 0 && top.stdout.trim() !== "") {
+        return top.stdout.trim();
+    }
+    return null;
+}
+/** Parse owner from a pid-map row (`owner` or `owner\tplatform`). */
+export function parsePidmapRowOwner(row) {
+    const trimmed = row.trim();
+    const tab = trimmed.indexOf("\t");
+    return tab >= 0 ? trimmed.slice(0, tab) : trimmed;
+}
+/** Parse platform from a pid-map row; legacy rows default to `claude_code`. */
+export function parsePidmapRowPlatform(row) {
+    const trimmed = row.trim();
+    const tab = trimmed.indexOf("\t");
+    return tab >= 0 ? trimmed.slice(tab + 1).trim() : "claude_code";
+}
+function readPidmapRow(pidmapDir, pid) {
+    const candidate = resolve(pidmapDir, String(pid));
+    if (!existsSync(candidate))
+        return null;
+    try {
+        const row = readFileSync(candidate, "utf8").trim();
+        return row || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk up the ppid chain looking for a pid-map entry. Returns
+ * the resolved instance_id or null.
+ *
+ * Pid-map files are `instance_id` or `instance_id\tplatform` (Cursor Phase 1).
+ * Prefer a row whose platform matches `HARNERY_AGENT_COORD_PLATFORM` (default
+ * `claude_code`); otherwise return the first owner seen on the walk.
+ *
+ * Subagents intentionally do not write pid-map entries; a Bash-tool ppid-walk
+ * from inside a subagent therefore resolves to the *parent's* pid-map entry.
+ * v1 ships this behavior; a real subagent-aware bridge is out of scope.
+ */
+export function resolveOwner() {
+    return resolveOwnerWithSource().owner;
+}
+/**
+ * Like `resolveOwner` but also reports which resolution path matched.
+ * Used by `harn agents whoami` to surface the path (`env` / `pidmap`) in
+ * the diagnostic output. Operators trying to debug "why doesn't my
+ * Codex session see itself?" need to know whether `HARNERY_AGENT_COORD_OWNER`
+ * is propagating or the ppid-walk is the load-bearing path.
+ */
+export function resolveOwnerWithSource() {
+    const envOwner = process.env.HARNERY_AGENT_COORD_OWNER?.trim();
+    if (envOwner) {
+        return { owner: envOwner, source: "env" };
+    }
+    const root = monorepoRoot();
+    if (!root)
+        return { owner: null, source: "none" };
+    const pidmapDir = resolve(root, ".harnery", "pid-map");
+    if (!existsSync(pidmapDir))
+        return { owner: null, source: "none" };
+    const prefer = process.env.HARNERY_AGENT_COORD_PLATFORM?.trim() || "claude_code";
+    let fallbackOwner = null;
+    let pid = process.pid;
+    for (let hop = 0; hop < 20; hop++) {
+        if (pid === null)
+            break;
+        const row = readPidmapRow(pidmapDir, pid);
+        if (row) {
+            const rowOwner = parsePidmapRowOwner(row);
+            const rowPlat = parsePidmapRowPlatform(row);
+            if (rowPlat === prefer) {
+                return { owner: rowOwner || null, source: "pidmap" };
+            }
+            if (!fallbackOwner && rowOwner)
+                fallbackOwner = rowOwner;
+        }
+        pid = readPpid(pid);
+    }
+    return {
+        owner: fallbackOwner,
+        source: fallbackOwner ? "pidmap_fallback" : "none",
+    };
+}
+/**
+ * Read and parse a heartbeat file. Returns null if the file is missing,
+ * unreadable, or contains malformed JSON. Does not throw.
+ *
+ * Phase 8 cleanup (2026-05-27): the v1/v2 dual-write bridge is gone; the
+ * projector writes additively-merged heartbeats directly to
+ * `.harnery/active/<id>.json` (the canonical location every reader expects).
+ */
+export function readHeartbeat(instanceId) {
+    if (!instanceId)
+        return null;
+    const root = monorepoRoot();
+    if (!root)
+        return null;
+    return readJsonHeartbeatFile(resolve(root, ".harnery", "active", `${instanceId}.json`));
+}
+function readJsonHeartbeatFile(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && typeof parsed.instance_id === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Render the display form for an instance_id: `agent-<Name>` if the heartbeat
+ * carries a non-empty `.name`, else `agent-<8-char-hex-prefix>`.
+ *
+ * Hex fallback handles three cases cleanly:
+ *  - heartbeat written before this feature shipped (no `name` field)
+ *  - heartbeat pruned but instance_id still appears in older log lines
+ *  - the narrow window between instance_id resolution and heartbeat read
+ */
+export function displayName(instanceId) {
+    if (!instanceId)
+        return "agent-unknown";
+    const hb = readHeartbeat(instanceId);
+    if (hb && typeof hb.name === "string" && hb.name.length > 0) {
+        return `agent-${hb.name}`;
+    }
+    return `agent-${instanceId.slice(0, 8)}`;
+}
+/**
+ * Convenience: resolve self via ppid walk, then render. Returns
+ * `agent-unknown` when the walk fails.
+ */
+export function selfDisplayName() {
+    const owner = resolveOwner();
+    if (!owner)
+        return "agent-unknown";
+    return displayName(owner);
+}
+function readPpid(pid) {
+    try {
+        const status = readFileSync(`/proc/${pid}/status`, "utf8");
+        const m = status.match(/^PPid:\s+(\d+)/m);
+        if (!m)
+            return null;
+        const parsed = Number.parseInt(m[1], 10);
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/agents/events/consume.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Incremental consumer for the canonical event stream at
+ * `.harnery/events.ndjson`.
+ *
+ * A small `.harnery/.events-cursor` file persists the last-projected event_id;
+ * subsequent runs skip everything up to and including that id and return only
+ * the new tail.
+ *
+ * Read strategy: the global cursor is advanced on every agent's turn.stop, so
+ * it almost always sits within the last few KB of the stream. We exploit that
+ * with a bounded **tail read** (reading only the last `tailBytes` of the file
+ * and locating the cursor there) which turns an O(file-size) read into
+ * O(window). If the cursor is older than the window (a long-idle system, or a
+ * cursor that's been rotated out) we fall back to a full read. The fallback is
+ * always correct, just slower, so undersizing the window can never lose events.
+ *
+ * Idempotency: projectors are idempotent by `event_id`. The
+ * cursor file makes this cheap (we never replay an already-projected event by
+ * accident) and the projector tolerates the rare full-replay (cursor rotated
+ * out) without double-applying.
+ */
+export interface CanonicalEvent {
+    schema_version: number;
+    event_id: string;
+    event_type: string;
+    ts: string;
+    instance_id: string;
+    session_id: string;
+    parent_session_id?: string;
+    turn_id?: string;
+    parent_turn_id?: string;
+    harness: string;
+    source: string;
+    data: Record<string, unknown>;
+}
+export interface ConsumeResult {
+    events: CanonicalEvent[];
+    /** event_id of the last event the caller successfully projected. */
+    lastEventId: string | null;
+    /** Total bytes in the stream file at read time (for diagnostics). */
+    streamBytes: number;
+}
+export interface ConsumeOpts {
+    /** Ignore the cursor and return everything, useful for backfill. */
+    replayAll?: boolean;
+    /**
+     * Tail-window size in bytes for the fast-path read. Defaults to
+     * `HARNERY_AGENT_COORD_TAIL_BYTES` env or 2 MiB. Mainly a test seam; production
+     * callers should leave it unset.
+     */
+    tailBytes?: number;
+}
+/**
+ * Read all events after the persisted cursor, in chronological (file) order.
+ */
+export declare function consumeSince(coordRoot: string, opts?: ConsumeOpts): ConsumeResult;
+export declare function readCursor(coordRoot: string): string | null;
+export declare function writeCursor(coordRoot: string, eventId: string): void;
+//# sourceMappingURL=consume.d.ts.map

package/dist/core/agents/events/consume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consume.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/events/consume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAmBH,MAAM,WAAW,cAAc;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,oEAAoE;IACpE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,aAAa,CA4CrF;AAwDD,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS3D;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAQpE"}