agent-hitch 0.1.0 → 0.2.0

package/dist/src/trajectories/projector.js

@@ -0,0 +1,385 @@
+/**
+ * Projector that turns normalized Hitch adapter events (and plain-text output
+ * for `minimal` fidelity) into a canonical DSH-compatible trajectory
+ * (spec §5.4, §5.5). It owns the turn/step bracket state machine and the
+ * tool-call pairing invariant.
+ */
+import { randomUUID } from "node:crypto";
+const EVENT_TYPE_KEYS = new Set([
+    "turn/start", "turn/end", "step/start", "step/end",
+    "user/message", "assistant/chunk", "assistant/message",
+    "tool/call", "tool/result",
+]);
+export class TrajectoryProjector {
+    header;
+    events = [];
+    fidelity;
+    prompt;
+    modelSource;
+    seq = 0;
+    // DSH's current persistence format numbers turns from one. A zero turn is
+    // reserved for an older pre-react-loop envelope and is rejected on load.
+    turn = 1;
+    step = 1;
+    stepOpen = false;
+    promptRecorded = false;
+    requestHeaderRecorded = false;
+    turnOpen = false;
+    assistantOpen = false;
+    assistantText = "";
+    assistantUsage;
+    lastAssistantEvent;
+    openCalls = new Map();
+    finalOutput = "";
+    providerSessionId;
+    finalized = false;
+    constructor(options) {
+        this.fidelity = options.fidelity;
+        this.prompt = options.prompt;
+        this.modelSource = parseModelSource(options.model);
+        this.header = {
+            type: "session",
+            version: 0,
+            id: options.runId,
+            createdAt: Date.now(),
+            cwd: options.cwd,
+            delegationDepth: 0,
+            ...(options.agentPreset ? { agentPreset: options.agentPreset } : {}),
+        };
+    }
+    get sessionId() {
+        return this.header.id;
+    }
+    get sessionHeader() {
+        return this.header;
+    }
+    get eventCount() {
+        return this.events.length;
+    }
+    /** Feed one normalized Hitch event into the projector. */
+    feed(event) {
+        if (this.finalized)
+            throw new Error("cannot feed a finalized trajectory");
+        switch (event.type) {
+            case "session.created":
+                this.providerSessionId ||= event.session_id;
+                this.ensureSessionOpen();
+                break;
+            case "message.delta":
+                this.advanceAfterCompletedStep();
+                this.ensureStepOpen();
+                this.assistantOpen = true;
+                this.assistantText += event.text;
+                break;
+            case "message.completed":
+                this.advanceAfterCompletedStep();
+                this.ensureStepOpen();
+                this.assistantOpen = true;
+                // A completed message is the authoritative final text for the step:
+                // it replaces any deltas accumulated so far (the original engine
+                // overwrote `finalMessage` on `message.completed`).
+                this.assistantText = event.text;
+                this.closeAssistantMessage();
+                break;
+            case "tool.started":
+                this.ensureStepOpen();
+                this.openCalls.set(event.call_id, { callId: event.call_id, name: event.name });
+                this.append({
+                    type: "tool/call",
+                    data: {
+                        turn: this.turn,
+                        step: this.step,
+                        callId: event.call_id,
+                        name: event.name,
+                        arguments: event.input === undefined ? "{}" : JSON.stringify(event.input),
+                    },
+                });
+                break;
+            case "tool.completed": {
+                const open = this.openCalls.get(event.call_id);
+                if (!open) {
+                    // A result without a recorded call cannot be paired; record it as a
+                    // namespaced informational event rather than fabricating a call.
+                    this.append({
+                        type: "hitch/unpaired-tool-result",
+                        data: { call_id: event.call_id, status: event.status, output: event.output ?? null },
+                        ignorable: true,
+                    });
+                    break;
+                }
+                this.openCalls.delete(event.call_id);
+                const isError = event.status !== "succeeded";
+                this.append({
+                    type: "tool/result",
+                    data: {
+                        turn: this.turn,
+                        step: this.step,
+                        message: {
+                            id: randomUUID(),
+                            role: "user",
+                            content: [{
+                                    type: "tool-result",
+                                    toolCallId: event.call_id,
+                                    content: [{ type: "text", text: toolResultText(event.output) }],
+                                    isError,
+                                }],
+                            source: { kind: "tool", callId: event.call_id },
+                        },
+                        ...(isError ? { error: { name: open.name, code: "tool_failed" } } : {}),
+                    },
+                    surfaceOp: "append",
+                });
+                break;
+            }
+            case "usage.updated":
+                const usage = normalizeUsage(event.usage);
+                if (!usage)
+                    break;
+                if (this.assistantOpen) {
+                    this.assistantUsage = usage;
+                }
+                else if (this.lastAssistantEvent && this.lastAssistantEvent.type === "assistant/message") {
+                    // Some adapters (Pi, OpenCode) emit usage after `message.completed`
+                    // closed the assistant message. Attach it to the just-closed
+                    // assistant/message so the canonical record carries the accounting.
+                    const data = this.lastAssistantEvent.data;
+                    if (!("usage" in data))
+                        data.usage = usage;
+                }
+                break;
+            case "diagnostic":
+                this.append({
+                    type: "hitch/diagnostic",
+                    data: { level: event.level, message: event.message },
+                    ignorable: true,
+                });
+                break;
+            case "provider.event":
+                this.append({
+                    type: "hitch/provider-event",
+                    data: { provider_type: event.provider_type, native: event.native },
+                    ignorable: true,
+                });
+                break;
+            default:
+                this.append({
+                    type: "hitch/unknown-event",
+                    data: { native: event },
+                    ignorable: true,
+                });
+        }
+    }
+    /** Feed raw plain-text output (minimal fidelity). */
+    feedText(text) {
+        this.ensureStepOpen();
+        this.assistantOpen = true;
+        this.assistantText += text;
+    }
+    /**
+     * Close the trajectory. `status` selects the terminal turn reason.
+     * Returns the finalized projection.
+     */
+    finalize(status) {
+        if (this.finalized)
+            return this.project();
+        this.finalized = true;
+        // A timeout/cancellation/crash with no recorded work still gets a valid
+        // terminal boundary (spec §5.4): open and close the session so the log is
+        // structurally complete even when nothing was emitted.
+        if (this.events.length === 0 && status !== "succeeded")
+            this.ensureSessionOpen();
+        if (this.assistantOpen && this.assistantText)
+            this.closeAssistantMessage(true);
+        if (this.stepOpen) {
+            // A successful run may not end with open tool calls: the harness claimed
+            // to finish cleanly, so an unpaired call is evidence of a broken
+            // trajectory, not an interruption. Only failed/timed_out/cancelled runs
+            // may synthesize unknown-outcome results for interrupted calls (spec
+            // §5.4: a completed run has no open call).
+            if (status === "succeeded" && this.openCalls.size > 0) {
+                const open = [...this.openCalls.values()].map((call) => call.callId).join(", ");
+                throw new Error(`trajectory finalization failed: run succeeded with open tool calls: ${open}`);
+            }
+            for (const open of [...this.openCalls.values()]) {
+                this.openCalls.delete(open.callId);
+                this.append({
+                    type: "tool/result",
+                    data: {
+                        turn: this.turn,
+                        step: this.step,
+                        message: {
+                            id: randomUUID(),
+                            role: "user",
+                            content: [{
+                                    type: "tool-result",
+                                    toolCallId: open.callId,
+                                    content: [{ type: "text", text: `tool call interrupted: ${open.name} outcome unknown` }],
+                                    isError: true,
+                                }],
+                            source: { kind: "tool", callId: open.callId },
+                        },
+                        error: { name: open.name, code: "TOOL_OUTCOME_UNKNOWN" },
+                    },
+                    surfaceOp: "append",
+                });
+            }
+            this.append({ type: "step/end", data: { turn: this.turn, step: this.step } });
+            this.stepOpen = false;
+        }
+        if (this.turnOpen) {
+            this.append({
+                type: "turn/end",
+                data: { turn: this.turn, reason: terminalReason(status) },
+            });
+            this.turnOpen = false;
+        }
+        return this.project();
+    }
+    ensureSessionOpen() {
+        if (this.turnOpen)
+            return;
+        this.turnOpen = true;
+        this.append({
+            type: "turn/start",
+            data: { turn: this.turn },
+        });
+    }
+    appendPrompt() {
+        if (this.promptRecorded)
+            return;
+        this.append({
+            type: "user/message",
+            data: {
+                id: randomUUID(),
+                role: "user",
+                content: [{ type: "text", text: this.prompt }],
+                source: { kind: "user" },
+            },
+            surfaceOp: "append",
+        });
+        this.promptRecorded = true;
+    }
+    ensureStepOpen() {
+        this.ensureSessionOpen();
+        if (this.stepOpen)
+            return;
+        this.stepOpen = true;
+        this.append({ type: "step/start", data: { turn: this.turn, step: this.step } });
+        this.appendPrompt();
+        if (!this.requestHeaderRecorded) {
+            this.append({
+                type: "request/header",
+                data: {
+                    header: { config: { ...this.modelSource } },
+                    reason: "initial",
+                },
+            });
+            this.requestHeaderRecorded = true;
+        }
+    }
+    /** A new model reply after a completed reply starts the next DSH react step. */
+    advanceAfterCompletedStep() {
+        if (!this.stepOpen || this.assistantOpen || !this.lastAssistantEvent || this.openCalls.size > 0)
+            return;
+        this.append({ type: "step/end", data: { turn: this.turn, step: this.step } });
+        this.step += 1;
+        this.stepOpen = false;
+        this.lastAssistantEvent = undefined;
+    }
+    closeAssistantMessage(interrupted = false) {
+        if (!this.assistantOpen)
+            return;
+        const text = this.assistantText;
+        if (text)
+            this.finalOutput = text;
+        this.lastAssistantEvent = this.append({
+            type: "assistant/message",
+            data: {
+                turn: this.turn,
+                step: this.step,
+                message: {
+                    id: randomUUID(),
+                    role: "assistant",
+                    content: [{ type: "text", text }],
+                    source: { kind: "model", ...this.modelSource },
+                },
+                ...(this.assistantUsage ? { usage: this.assistantUsage } : {}),
+                ...(interrupted ? { interrupted: true } : {}),
+            },
+            sourceEventSeqs: [],
+            surfaceOp: "append",
+        });
+        this.assistantOpen = false;
+        this.assistantText = "";
+        this.assistantUsage = undefined;
+    }
+    append(event) {
+        const framed = {
+            ...event,
+            seq: this.seq,
+            time: Date.now(),
+        };
+        this.seq += 1;
+        this.events.push(framed);
+        return framed;
+    }
+    project() {
+        const result = {
+            header: { ...this.header },
+            events: [...this.events],
+            finalOutput: this.finalOutput,
+            fidelity: this.fidelity,
+        };
+        if (this.providerSessionId)
+            result.providerSessionId = this.providerSessionId;
+        return result;
+    }
+}
+function parseModelSource(model) {
+    const separator = model.indexOf("/");
+    if (separator > 0 && separator < model.length - 1) {
+        return { provider: model.slice(0, separator), model: model.slice(separator + 1) };
+    }
+    return { provider: "hitch", model: model || "unknown" };
+}
+/** Convert native harness accounting into the canonical DSH usage envelope. */
+function normalizeUsage(usage) {
+    const cache = usage.cache && typeof usage.cache === "object" ? usage.cache : {};
+    const number = (...values) => {
+        for (const value of values)
+            if (typeof value === "number" && Number.isFinite(value))
+                return value;
+        return 0;
+    };
+    const input = number(usage.inputTokens, usage.uncachedInputTokens, usage.input_tokens, usage.input);
+    const output = number(usage.outputTokens, usage.output_tokens, usage.output);
+    const cacheRead = number(usage.cacheReadTokens, usage.cached_input_tokens, usage.cacheRead, cache.read);
+    const cacheWrite = number(usage.cacheWriteTokens, usage.cache_write_input_tokens, usage.cacheWrite, cache.write);
+    return { inputTokens: input, outputTokens: output, cacheReadTokens: cacheRead, cacheWriteTokens: cacheWrite };
+}
+function toolResultText(output) {
+    if (typeof output === "string")
+        return output;
+    if (output === undefined || output === null)
+        return "";
+    try {
+        return JSON.stringify(output);
+    }
+    catch {
+        return String(output);
+    }
+}
+function terminalReason(status) {
+    switch (status) {
+        case "succeeded":
+            return { kind: "completed" };
+        case "cancelled":
+            return { kind: "aborted", reason: { kind: "user" } };
+        case "timed_out":
+            return { kind: "aborted", reason: { kind: "hook", reason: "timeout" } };
+        case "failed":
+            return { kind: "error", error: { message: "agent process failed", code: "UNKNOWN" } };
+    }
+}
+export { EVENT_TYPE_KEYS };
+//# sourceMappingURL=projector.js.map

package/dist/src/trajectories/projector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projector.js","sourceRoot":"","sources":["../../../src/trajectories/projector.ts"],"names":[],"mappings":"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"}

package/dist/src/trajectories/store.js

@@ -0,0 +1,281 @@
+/**
+ * Canonical trajectory store: per-run DSH-compatible persistence root
+ * (spec §5.2). One persistence root per run prevents collisions when two
+ * providers reuse a native session id while retaining the DSH
+ * project/session directory shape.
+ */
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { readFile, readdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { ensureDir, readJSON } from "../fs.js";
+import { eventLine, headerLine, logPath, parseEventLine, parseHeaderLine } from "./format.js";
+import { TRAJECTORY_FORMAT } from "./contract.js";
+/**
+ * Append-only writer for one canonical trajectory. The first logical line is
+ * the immutable session header; every following line is one `SessionEvent`
+ * JSON object. `seq` starts at 0 and remains contiguous. Writes are
+ * serialized through a promise chain so failures surface on `close()`.
+ */
+export class TrajectoryWriter {
+    target;
+    stream;
+    pending = Promise.resolve();
+    nextSeq = 0;
+    closed = false;
+    streamError;
+    constructor(target, stream) {
+        this.target = target;
+        this.stream = stream;
+        stream.on("error", (error) => { this.streamError ||= error; });
+    }
+    static async open(options) {
+        const target = trajectoryLogPath(options.runDirectory, options.cwd, options.sessionId);
+        await ensureDir(path.dirname(target));
+        const writer = new TrajectoryWriter(target, createWriteStream(target, { flags: "ax", mode: 0o600 }));
+        await writer.enqueue(headerLine(options.header));
+        return writer;
+    }
+    get path() {
+        return this.target;
+    }
+    /** Append one event; `seq` must continue the log. */
+    append(event) {
+        if (this.closed)
+            throw new Error("trajectory writer is closed");
+        if (event.seq !== this.nextSeq) {
+            throw new Error(`trajectory seq must be contiguous: expected ${this.nextSeq}, got ${event.seq}`);
+        }
+        this.nextSeq += 1;
+        this.enqueue(eventLine(event));
+    }
+    enqueue(line) {
+        const operation = this.pending.then(() => new Promise((resolve, reject) => {
+            this.stream.write(line, (error) => error ? reject(error) : resolve());
+        }));
+        this.pending = operation.catch(() => { });
+        return operation;
+    }
+    async flush() {
+        await this.pending;
+    }
+    /** Close the writer; resolves with the canonical trajectory path. */
+    async close() {
+        if (this.closed) {
+            await this.pending;
+            return this.target;
+        }
+        this.closed = true;
+        let failure;
+        try {
+            await this.pending;
+        }
+        catch (error) {
+            failure = error;
+        }
+        try {
+            await closeStream(this.stream);
+        }
+        catch (error) {
+            failure ||= error;
+        }
+        failure ||= this.streamError;
+        if (failure)
+            throw failure;
+        return this.target;
+    }
+}
+function closeStream(stream) {
+    return new Promise((resolve, reject) => {
+        stream.once("error", reject);
+        stream.end(resolve);
+    });
+}
+/** The `trajectory/--<normalized-cwd>--/<encoded-session-id>/session.jsonl` path under a run directory. */
+export function trajectoryLogPath(runDirectory, cwd, sessionId) {
+    return logPath(path.join(runDirectory, "trajectory"), cwd, sessionId);
+}
+export function trajectoryRefPath(runDirectory) {
+    return path.join(runDirectory, "trajectory.ref.json");
+}
+export function trajectoryRef(runId, sessionId, fidelity, trajectoryPath, sha256, providerSessionId) {
+    const ref = {
+        schema_version: "1",
+        run_id: runId,
+        session_id: sessionId,
+        format: TRAJECTORY_FORMAT,
+        fidelity,
+        path: trajectoryPath,
+        sha256: sha256,
+    };
+    if (providerSessionId !== undefined)
+        ref.provider_session_id = providerSessionId;
+    return ref;
+}
+/**
+ * Read and validate a canonical trajectory. Validates header identity, the
+ * declared file set, contiguous sequence numbers, and relational invariants.
+ */
+export async function readTrajectory(file) {
+    const content = await readFile(file, "utf8");
+    const sha256 = `sha256:${createHash("sha256").update(content).digest("hex")}`;
+    const lines = content.split(/\r?\n/);
+    const nonEmpty = lines.filter((line) => line.length > 0);
+    if (nonEmpty.length === 0)
+        throw new Error(`trajectory is empty: ${file}`);
+    const header = parseHeaderLine(JSON.parse(nonEmpty[0]));
+    const events = [];
+    for (let i = 1; i < nonEmpty.length; i += 1) {
+        const parsed = parseEventLine(JSON.parse(nonEmpty[i]));
+        if (parsed.seq !== i - 1) {
+            throw new Error(`trajectory seq must be contiguous: expected ${i - 1}, got ${parsed.seq}`);
+        }
+        events.push(parsed);
+    }
+    validateTrajectoryInvariants(header, events);
+    return { header, events, sha256 };
+}
+/** Validate the required relational invariants of a canonical trajectory (spec §5.4). */
+export function validateTrajectoryInvariants(header, events) {
+    const knownTypes = new Set([
+        "turn/start", "turn/end", "step/start", "step/end",
+        "request/header", "user/message", "assistant/chunk", "assistant/message",
+        "tool/call", "tool/result",
+    ]);
+    let turnOpen = false;
+    let stepOpen = false;
+    let openTurn = null;
+    let openStep = null;
+    const openCalls = new Set();
+    let seq = 0;
+    for (const event of events) {
+        if (event.seq !== seq)
+            throw new Error(`trajectory seq must be contiguous: expected ${seq}, got ${event.seq}`);
+        seq += 1;
+        const data = (event.data || {});
+        switch (event.type) {
+            case "turn/start": {
+                if (turnOpen)
+                    throw new Error(`nested turn/start at seq ${event.seq}`);
+                turnOpen = true;
+                openTurn = data.turn;
+                break;
+            }
+            case "turn/end": {
+                if (!turnOpen)
+                    throw new Error(`turn/end without turn/start at seq ${event.seq}`);
+                if (stepOpen)
+                    throw new Error(`turn/end with open step at seq ${event.seq}`);
+                turnOpen = false;
+                openTurn = null;
+                break;
+            }
+            case "step/start": {
+                if (!turnOpen)
+                    throw new Error(`step/start outside a turn at seq ${event.seq}`);
+                if (stepOpen)
+                    throw new Error(`nested step/start at seq ${event.seq}`);
+                stepOpen = true;
+                openStep = { turn: data.turn, step: data.step };
+                break;
+            }
+            case "step/end": {
+                if (!stepOpen)
+                    throw new Error(`step/end without step/start at seq ${event.seq}`);
+                if (openCalls.size > 0)
+                    throw new Error(`step/end with open tool calls at seq ${event.seq}`);
+                stepOpen = false;
+                openStep = null;
+                break;
+            }
+            case "tool/call": {
+                if (!stepOpen)
+                    throw new Error(`tool/call outside a step at seq ${event.seq}`);
+                const callId = data.callId;
+                if (openCalls.has(callId))
+                    throw new Error(`duplicate tool call ${callId} at seq ${event.seq}`);
+                openCalls.add(callId);
+                break;
+            }
+            case "tool/result": {
+                const message = (data.message || {});
+                const source = (message.source || {});
+                const content = Array.isArray(message.content) ? message.content : [];
+                const callId = (source.callId ?? content[0]?.toolCallId);
+                if (!callId || !openCalls.has(callId)) {
+                    throw new Error(`tool/result without a matching open tool call at seq ${event.seq}`);
+                }
+                openCalls.delete(callId);
+                break;
+            }
+            default:
+                if (!knownTypes.has(event.type) && !event.ignorable) {
+                    throw new Error(`unknown required event type ${event.type} at seq ${event.seq}`);
+                }
+        }
+    }
+    if (turnOpen)
+        throw new Error("trajectory ends with an open turn");
+    if (stepOpen)
+        throw new Error("trajectory ends with an open step");
+    if (openCalls.size > 0)
+        throw new Error("trajectory ends with open tool calls");
+    if (openTurn !== null)
+        throw new Error("trajectory ends with an open turn bracket");
+    if (openStep !== null)
+        throw new Error("trajectory ends with an open step bracket");
+}
+/** Locate the canonical trajectory for a run from its `trajectory.ref.json`. */
+export async function loadTrajectoryRef(runDirectory) {
+    const ref = await readJSON(trajectoryRefPath(runDirectory), null);
+    if (!ref || ref.schema_version !== "1")
+        return null;
+    return ref;
+}
+export async function removeTrajectory(runDirectory) {
+    await rm(path.join(runDirectory, "trajectory"), { recursive: true, force: true });
+}
+/** Compute the SHA-256 digest of an existing trajectory file. */
+export async function trajectoryFileSha256(file) {
+    const content = await readFile(file, "utf8");
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+export async function listTrajectorySessions(runDirectory) {
+    const root = path.join(runDirectory, "trajectory");
+    let projects;
+    try {
+        projects = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const sessions = [];
+    for (const project of projects) {
+        if (!project.isDirectory())
+            continue;
+        let entries;
+        try {
+            entries = await readdir(path.join(root, project.name), { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const candidate = path.join(root, project.name, entry.name, "session.jsonl");
+            try {
+                await stat(candidate);
+                sessions.push(candidate);
+            }
+            catch {
+                // Not a session directory.
+            }
+        }
+    }
+    return sessions.sort();
+}
+export { TRAJECTORY_FORMAT };
+//# sourceMappingURL=store.js.map