harnery 0.0.1 → 0.2.1

package/dist/core/agents/events/consume.js

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { coordEnv } from "../../../lib/env.js";
+const STREAM_REL = ".harnery/events.ndjson";
+const CURSOR_REL = ".harnery/.events-cursor";
+const DEFAULT_TAIL_BYTES = 2 * 1024 * 1024; // 2 MiB, thousands of events of headroom
+/**
+ * Read all events after the persisted cursor, in chronological (file) order.
+ */
+export function consumeSince(coordRoot, opts = {}) {
+    const streamPath = join(coordRoot, STREAM_REL);
+    if (!existsSync(streamPath)) {
+        return { events: [], lastEventId: null, streamBytes: 0 };
+    }
+    const cursor = opts.replayAll ? null : readCursor(coordRoot);
+    const fileSize = statSync(streamPath).size;
+    const windowBytes = resolveTailBytes(opts.tailBytes);
+    // Tail fast-path: a cursor exists and the file is larger than the window.
+    // Read only the trailing window, drop the (likely partial) first line, and
+    // look for the cursor. A hit returns just the new events without ever
+    // touching the bulk of the file.
+    if (cursor !== null && fileSize > windowBytes) {
+        const tail = readTailUtf8(streamPath, fileSize, windowBytes);
+        const firstNl = tail.indexOf("\n");
+        const usable = firstNl >= 0 ? tail.slice(firstNl + 1) : "";
+        const parsed = eventsAfterCursor(parseLines(usable), cursor);
+        if (parsed.foundCursor) {
+            return {
+                events: parsed.events,
+                lastEventId: parsed.events.at(-1)?.event_id ?? cursor,
+                streamBytes: fileSize,
+            };
+        }
+        // Cursor older than the tail window → fall through to a full read.
+    }
+    // Full read: first run, replayAll, small file, or cursor not found in tail.
+    const all = parseLines(readFileSync(streamPath, "utf8"));
+    const parsed = eventsAfterCursor(all, cursor);
+    if (parsed.foundCursor) {
+        return {
+            events: parsed.events,
+            lastEventId: parsed.events.at(-1)?.event_id ?? cursor,
+            streamBytes: fileSize,
+        };
+    }
+    // The cursor names an event that's been rotated out of the file, so replay
+    // everything (safer than silent state drift; the projector is idempotent by
+    // event_id).
+    return { events: all, lastEventId: null, streamBytes: fileSize };
+}
+function resolveTailBytes(override) {
+    if (override !== undefined && override > 0)
+        return override;
+    const env = coordEnv("AGENT_COORD_TAIL_BYTES");
+    const n = env ? Number(env) : Number.NaN;
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_TAIL_BYTES;
+}
+/** Read the trailing `windowBytes` of a file as UTF-8 without loading the rest. */
+function readTailUtf8(streamPath, fileSize, windowBytes) {
+    const start = Math.max(0, fileSize - windowBytes);
+    const len = fileSize - start;
+    const buf = Buffer.allocUnsafe(len);
+    const fd = openSync(streamPath, "r");
+    try {
+        let read = 0;
+        while (read < len) {
+            const n = readSync(fd, buf, read, len - read, start + read);
+            if (n === 0)
+                break;
+            read += n;
+        }
+        return buf.toString("utf8", 0, read);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function parseLines(raw) {
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            /* skip malformed line */
+        }
+    }
+    return out;
+}
+/**
+ * Events strictly after `cursor` (or all events when `cursor` is null). When a
+ * non-null cursor isn't present in `all`, returns `foundCursor: false` so the
+ * caller can decide between a wider read and a full replay.
+ */
+function eventsAfterCursor(all, cursor) {
+    if (cursor === null)
+        return { events: all, foundCursor: true };
+    const idx = all.findIndex((e) => e.event_id === cursor);
+    if (idx < 0)
+        return { events: [], foundCursor: false };
+    return { events: all.slice(idx + 1), foundCursor: true };
+}
+export function readCursor(coordRoot) {
+    const path = join(coordRoot, CURSOR_REL);
+    if (!existsSync(path))
+        return null;
+    try {
+        const v = readFileSync(path, "utf8").trim();
+        return v.length > 0 ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCursor(coordRoot, eventId) {
+    const path = join(coordRoot, CURSOR_REL);
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, eventId, "utf8");
+    }
+    catch {
+        /* swallow; next run replays */
+    }
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Canonical-event writer for agent-coord. Mirrors the agent-hooks emitter:
+ * both modules write the same envelope shape to the same
+ * `.harnery/events.ndjson` file but stay independent (shared code limited to
+ * event/schema types).
+ *
+ * Phase 4: agent-coord uses this from CLI handlers (state.task_set,
+ * state.status_checked, state.scratch_append, council.*, presence.*).
+ */
+declare const SCHEMA_VERSION: 1;
+export type Harness = "claude-code" | "cursor" | "codex";
+export type Source = "agent-hooks" | "agent-coord" | "user" | "system";
+export interface Envelope {
+    schema_version: typeof SCHEMA_VERSION;
+    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: Harness;
+    source: Source;
+    data: Record<string, unknown>;
+}
+export interface EmitInput {
+    event_type: string;
+    instance_id: string;
+    session_id: string;
+    harness: Harness;
+    source?: Source;
+    parent_session_id?: string;
+    turn_id?: string;
+    parent_turn_id?: string;
+    ts?: string;
+    data: Record<string, unknown>;
+}
+export declare function buildEnvelope(input: EmitInput): Envelope;
+export declare function emit(coordRoot: string, input: EmitInput): Envelope;
+export {};
+//# sourceMappingURL=emit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/events/emit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,QAAA,MAAM,cAAc,EAAG,CAAU,CAAC;AAKlC,MAAM,MAAM,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC;AACzD,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,aAAa,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvE,MAAM,WAAW,QAAQ;IACvB,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,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,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,QAAQ,CAexD;AAED,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,QAAQ,CAwBlE"}

package/dist/core/agents/events/emit.js

@@ -0,0 +1,70 @@
+/**
+ * Canonical-event writer for agent-coord. Mirrors the agent-hooks emitter:
+ * both modules write the same envelope shape to the same
+ * `.harnery/events.ndjson` file but stay independent (shared code limited to
+ * event/schema types).
+ *
+ * Phase 4: agent-coord uses this from CLI handlers (state.task_set,
+ * state.status_checked, state.scratch_append, council.*, presence.*).
+ */
+import { appendFileSync, closeSync, mkdirSync, openSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { ulid } from "./ulid.js";
+const SCHEMA_VERSION = 1;
+const STREAM_FILE = ".harnery/events.ndjson";
+const LOCK_FILE = ".harnery/events.ndjson.lock";
+const MAX_LINE_BYTES = 64 * 1024;
+export function buildEnvelope(input) {
+    return {
+        schema_version: SCHEMA_VERSION,
+        event_id: ulid(),
+        event_type: input.event_type,
+        ts: input.ts ?? new Date().toISOString(),
+        instance_id: input.instance_id,
+        session_id: input.session_id,
+        parent_session_id: input.parent_session_id,
+        turn_id: input.turn_id,
+        parent_turn_id: input.parent_turn_id,
+        harness: input.harness,
+        source: input.source ?? "agent-coord",
+        data: input.data,
+    };
+}
+export function emit(coordRoot, input) {
+    const envelope = buildEnvelope(input);
+    const streamPath = join(coordRoot, STREAM_FILE);
+    const lockPath = join(coordRoot, LOCK_FILE);
+    ensureDir(dirname(streamPath));
+    ensureFile(lockPath);
+    let line = `${JSON.stringify(envelope)}\n`;
+    if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) {
+        line = `${JSON.stringify({
+            ...envelope,
+            data: { __over_size_limit: true, original_bytes: Buffer.byteLength(line, "utf8") },
+        })}\n`;
+    }
+    const lockFd = openSync(lockPath, "r+");
+    try {
+        appendFileSync(streamPath, line, { encoding: "utf8", flag: "a" });
+    }
+    finally {
+        closeSync(lockFd);
+    }
+    return envelope;
+}
+function ensureDir(path) {
+    try {
+        mkdirSync(path, { recursive: true });
+    }
+    catch {
+        /* swallow */
+    }
+}
+function ensureFile(path) {
+    try {
+        closeSync(openSync(path, "a"));
+    }
+    catch {
+        /* swallow */
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Tiny ULID generator. Crockford-base32, 10-char timestamp (48-bit ms epoch)
+ * + 16-char random (80-bit). 26 chars total, monotonically-sortable.
+ *
+ * Intentionally duplicated from the agent-hooks ULID generator: agent-hooks
+ * and agent-coord stay strictly-separated packages, sharing only event/schema
+ * types. The writer side reimplements per-module so neither depends on the
+ * other's runtime code.
+ */
+export declare function ulid(): string;
+//# sourceMappingURL=ulid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ulid.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/events/ulid.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,IAAI,IAAI,MAAM,CAI7B"}

package/dist/core/agents/events/ulid.js

@@ -0,0 +1,47 @@
+/**
+ * Tiny ULID generator. Crockford-base32, 10-char timestamp (48-bit ms epoch)
+ * + 16-char random (80-bit). 26 chars total, monotonically-sortable.
+ *
+ * Intentionally duplicated from the agent-hooks ULID generator: agent-hooks
+ * and agent-coord stay strictly-separated packages, sharing only event/schema
+ * types. The writer side reimplements per-module so neither depends on the
+ * other's runtime code.
+ */
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+export function ulid() {
+    const ts = encodeTime(Date.now());
+    const rnd = encodeRandom();
+    return ts + rnd;
+}
+function encodeTime(ms) {
+    let out = "";
+    let n = BigInt(ms);
+    const base = BigInt(32);
+    for (let i = 0; i < 10; i++) {
+        const mod = Number(n % base);
+        out = ALPHABET[mod] + out;
+        n = n / base;
+    }
+    return out;
+}
+function encodeRandom() {
+    const bytes = new Uint8Array(10);
+    crypto.getRandomValues(bytes);
+    let out = "";
+    let buf = 0n;
+    let bits = 0;
+    for (const b of bytes) {
+        buf = (buf << 8n) | BigInt(b);
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            const idx = Number((buf >> BigInt(bits)) & 0x1fn);
+            out += ALPHABET[idx];
+        }
+    }
+    if (bits > 0) {
+        const idx = Number((buf << BigInt(5 - bits)) & 0x1fn);
+        out += ALPHABET[idx];
+    }
+    return out.slice(0, 16);
+}

package/dist/core/agents/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * agent-coord library public exports.
+ *
+ * `coord-client`: coordination helpers
+ * (Heartbeat reader, owner-resolver via ppid-walk, monorepo-root finder).
+ * Imported by every TS caller that needs to read coord state.
+ *
+ * `canonical-emit`: fire-and-forget client for the canonical event stream;
+ * spawns `bin/agent-coord emit-event` and never blocks the caller.
+ */
+export * from "./canonical-emit.js";
+export * from "./coord-client.js";
+export * from "./session-events.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/agents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/dist/core/agents/index.js

@@ -0,0 +1,13 @@
+/**
+ * agent-coord library public exports.
+ *
+ * `coord-client`: coordination helpers
+ * (Heartbeat reader, owner-resolver via ppid-walk, monorepo-root finder).
+ * Imported by every TS caller that needs to read coord state.
+ *
+ * `canonical-emit`: fire-and-forget client for the canonical event stream;
+ * spawns `bin/agent-coord emit-event` and never blocks the caller.
+ */
+export * from "./canonical-emit.js";
+export * from "./coord-client.js";
+export * from "./session-events.js";

package/dist/core/agents/paths.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Walk up from `start` looking for a directory containing `.harnery/`, so
+ * adapter + legacy code agree on the same monorepo root.
+ */
+export declare function findCoordRoot(start?: string): string | null;
+//# sourceMappingURL=paths.d.ts.map

package/dist/core/agents/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../../src/core/agents/paths.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAQ1E"}

package/dist/core/agents/paths.js

@@ -0,0 +1,17 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+/**
+ * Walk up from `start` looking for a directory containing `.harnery/`, so
+ * adapter + legacy code agree on the same monorepo root.
+ */
+export function findCoordRoot(start = process.cwd()) {
+    let dir = resolve(start);
+    while (true) {
+        if (existsSync(join(dir, ".harnery")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}

package/dist/core/agents/render/prompt-context.d.ts

@@ -0,0 +1,43 @@
+/**
+ * UserPromptSubmit UX renderer. Combines the peer-refresh dedup, the
+ * council-pending hash-dedup, and the Cursor set-task staleness nudge.
+ * agent-hook's user_prompt.submit post-emit handler calls this
+ * and forwards the result as the harness-shaped additionalContext payload.
+ *
+ * Three hash-dedup'd subsections combined into one additionalContext payload:
+ *   1. Peer table: semantically-relevant peer fields hashed; only re-emits
+ *      when peers change (name + instance_id + session_id + kind + started_at
+ *      + sorted(files_touched) + platform, sorted by instance_id).
+ *   2. Council pending: pending open-council IDs hashed; re-emits when the
+ *      ID set changes.
+ *   3. Task staleness nudge (cursor only, since CC enforces via the Stop hook
+ *      transcript scan). Fires when `task` is null or `task_updated_at` is
+ *      older than HARNERY_TASK_STALE_SECONDS (default 1800 = 30 min). Hash-deduped
+ *      against the previous nudge state.
+ *
+ * Hash files live at:
+ *   .harnery/.last-peer-hash.<instance_id>
+ *   .harnery/.last-council-hash.<instance_id>
+ *   .harnery/.last-task-nudge-hash.<instance_id>
+ *
+ * First call always emits (hash files don't exist).
+ */
+export interface PromptContextOpts {
+    coordRoot: string;
+    instanceId: string;
+    sessionId: string;
+    agentName?: string;
+    /** When true, run the task-staleness nudge check (cursor only; CC has the
+     * Stop-hook transcript-scan enforcement). */
+    taskNudge?: boolean;
+}
+/**
+ * Build the combined UserPromptSubmit additionalContext string. Returns "" when
+ * nothing has changed since the last call (so the caller can skip the JSON emit).
+ *
+ * Side effects: updates `.harnery/.last-peer-hash.<id>` and `.harnery/.last-council-hash.<id>`
+ * when their respective sections re-emit (or removes the council hash when no
+ * councils are pending, matching the bash behavior).
+ */
+export declare function renderPromptContext(opts: PromptContextOpts): string;
+//# sourceMappingURL=prompt-context.d.ts.map

package/dist/core/agents/render/prompt-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/prompt-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAgCH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;iDAC6C;IAC7C,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAqBnE"}