@openshain/core 0.1.0 → 0.2.0

package/dist/work/event-log.js

@@ -0,0 +1,140 @@
+import { appendFile, mkdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { OpenshainError } from "../errors.js";
+import { newEventId } from "../ids.js";
+import { eventFromFile, eventToFile, } from "./events.js";
+export const EVENTS_FILE_NAME = "events.jsonl";
+/** Appends to one file are serialized within the process, so two instances cannot interleave the size check and the write. */
+const appendQueues = new Map();
+function serialized(path, task) {
+    const previous = appendQueues.get(path) ?? Promise.resolve();
+    const run = previous.then(task, task);
+    const settled = run
+        .catch(() => undefined)
+        .then(() => {
+        if (appendQueues.get(path) === settled)
+            appendQueues.delete(path);
+    });
+    appendQueues.set(path, settled);
+    return run;
+}
+/**
+ * Append-only log of one work's events. The file is the source of truth.
+ *
+ * Every line is checked on open and on read; a line that cannot be read stops
+ * the reader. Every event is checked on append by reading its own line back
+ * before it is written, so what is written can always be read. A change to the
+ * file by someone else between two operations of this instance is refused.
+ */
+export class EventLog {
+    path;
+    workId;
+    nextSeq;
+    size;
+    constructor(path, workId, nextSeq, size) {
+        this.path = path;
+        this.workId = workId;
+        this.nextSeq = nextSeq;
+        this.size = size;
+    }
+    /** Opens (creating the directory if needed) and checks the existing log end to end. */
+    static async open(dir, workId) {
+        await mkdir(dir, { recursive: true });
+        const path = join(dir, EVENTS_FILE_NAME);
+        const { events, size } = await readAll(path, workId);
+        const last = events.at(-1);
+        return new EventLog(path, workId, (last?.seq ?? 0) + 1, size);
+    }
+    async append(input) {
+        const now = new Date().toISOString();
+        const event = {
+            v: 1,
+            id: newEventId(),
+            workId: this.workId,
+            seq: this.nextSeq,
+            type: input.type,
+            occurredAt: input.occurredAt ?? now,
+            recordedAt: now,
+            payload: input.payload,
+        };
+        let line;
+        try {
+            line = `${JSON.stringify(eventToFile(event))}\n`;
+            eventFromFile(JSON.parse(line));
+        }
+        catch (cause) {
+            throw new OpenshainError("invalid_event", `${input.type} event cannot be read back once written: ${cause.message}`, { cause });
+        }
+        await serialized(this.path, async () => {
+            const current = await fileSize(this.path);
+            if (current !== this.size) {
+                throw new OpenshainError("concurrent_write", `${this.path} changed since it was opened (expected ${this.size} bytes, found ${current}); another writer is active`);
+            }
+            await appendFile(this.path, line, "utf8");
+            this.size += Buffer.byteLength(line, "utf8");
+            this.nextSeq += 1;
+        });
+        return event;
+    }
+    async read() {
+        return (await readAll(this.path, this.workId)).events;
+    }
+}
+async function fileSize(path) {
+    try {
+        return (await stat(path)).size;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return 0;
+        throw err;
+    }
+}
+async function readAll(path, workId) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { events: [], size: 0 };
+        throw err;
+    }
+    const corrupt = (detail, cause) => new OpenshainError("corrupt_log", `${path}: ${detail}`, { cause });
+    if (text.length > 0 && !text.endsWith("\n")) {
+        throw corrupt("does not end with a newline; the last write did not complete");
+    }
+    const events = [];
+    const lines = text.split("\n");
+    lines.forEach((line, index) => {
+        const lineNo = index + 1;
+        if (line === "") {
+            if (index === lines.length - 1)
+                return; // trailing newline
+            throw corrupt(`line ${lineNo} is empty`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (cause) {
+            throw corrupt(`line ${lineNo} is not valid JSON`, cause);
+        }
+        let event;
+        try {
+            event = eventFromFile(parsed);
+        }
+        catch (cause) {
+            throw corrupt(`line ${lineNo} is not a valid event: ${cause.message}`, cause);
+        }
+        if (event.workId !== workId) {
+            throw corrupt(`line ${lineNo} belongs to ${event.workId}, expected ${workId}`);
+        }
+        const expectedSeq = events.length + 1;
+        if (event.seq !== expectedSeq) {
+            throw corrupt(`line ${lineNo} has seq ${event.seq}, expected ${expectedSeq}`);
+        }
+        events.push(event);
+    });
+    return { events, size: Buffer.byteLength(text, "utf8") };
+}

package/dist/work/events.d.ts

@@ -0,0 +1,311 @@
+import { z } from "zod";
+import type { EventId, WorkId } from "../ids.ts";
+export type StopReason = "end_turn" | "tool_call" | "max_tokens" | "refusal" | "other";
+export type AssistantPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "opaque";
+    provider: string;
+    data: unknown;
+};
+export type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "json";
+    value: unknown;
+};
+/**
+ * A file a work produced. `missing` means the runtime could not read it when the work ended; the
+ * hash is then the tool's report. `claimed` means an agent named it but no tool of this work wrote
+ * it; the hash is the runtime's, but nothing in the record ties the file to this work's calls.
+ */
+export type Artifact = {
+    path: string;
+    sha256: string;
+    missing?: true;
+    claimed?: true;
+};
+export interface ModelUsage {
+    /** Every input token, including the ones read from or written to a prompt cache. */
+    inputTokens: number;
+    outputTokens: number;
+    /** The part of inputTokens served from a prompt cache. */
+    cachedInputTokens?: number;
+    /** The part of inputTokens written to a prompt cache. */
+    cacheWriteTokens?: number;
+    /** The part of outputTokens spent on reasoning. */
+    reasoningTokens?: number;
+}
+export declare const TOOL_REJECTION_CODES: readonly ["schema_mismatch", "unknown_tool", "not_allowed", "reserved_path", "outside_workspace", "invalid_path"];
+export type ToolRejectionCode = (typeof TOOL_REJECTION_CODES)[number];
+export interface EventPayloads {
+    "work.created": {
+        objective: string;
+        principal: string;
+        profession: string;
+        type: string;
+        /** The work this one was started from, such as the session that asked for it. */
+        parent?: string;
+        /** The name the model goes by in this work. A session picks it; the works it starts carry the same one. */
+        agentName?: string;
+    };
+    "work.status_changed": {
+        from: string;
+        to: string;
+        reason: string;
+    };
+    "model.requested": {
+        provider: string;
+        model: string;
+        messageCount: number;
+        toolNames: string[];
+    };
+    "model.completed": {
+        stopReason: StopReason;
+        content: AssistantPart[];
+        raw?: unknown;
+    };
+    "model.failed": {
+        code: string;
+        message: string;
+    };
+    "tool.called": {
+        callId: string;
+        provider: string;
+        name: string;
+        input: unknown;
+    };
+    "tool.completed": {
+        callId: string;
+        content: ToolContent[];
+        isError: boolean;
+        observation?: {
+            source: string;
+            retrievedAt: string;
+        };
+        after?: Artifact[];
+    };
+    "tool.rejected": {
+        callId: string;
+        name: string;
+        code: ToolRejectionCode;
+        reason: string;
+    };
+    "human.input_requested": {
+        callId: string;
+        question: string;
+    };
+    "human.input_provided": {
+        callId: string;
+        answer: string;
+    };
+    /** What the person said in a session. Becomes a user message in the projection. */
+    "human.message": {
+        text: string;
+    };
+    "usage.recorded": {
+        kind: "model_inference";
+        provider: string;
+        model: string;
+        usage: ModelUsage;
+    } | {
+        kind: "tool_execution";
+        provider: string;
+        usage: {
+            durationMs: number;
+        };
+    };
+    "evidence.recorded": {
+        claim: string;
+        refs: string[];
+        artifacts: Artifact[];
+    };
+    "work.completed": {
+        summary: string;
+    };
+    "work.failed": {
+        reason: string;
+        detail: string;
+    };
+}
+export type EventType = keyof EventPayloads;
+interface Envelope {
+    v: 1;
+    id: EventId;
+    workId: WorkId;
+    seq: number;
+    occurredAt: string;
+    recordedAt: string;
+}
+export type Event<T extends EventType = EventType> = T extends EventType ? Envelope & {
+    type: T;
+    payload: EventPayloads[T];
+} : never;
+/** An event whose type this version of the runtime does not know. Kept, not validated. */
+export type UnknownEvent = Envelope & {
+    type: string;
+    payload: unknown;
+};
+export type AnyEvent = Event | UnknownEvent;
+export declare const payloadFileSchemas: {
+    "work.created": z.ZodObject<{
+        objective: z.ZodString;
+        principal: z.ZodString;
+        profession: z.ZodString;
+        type: z.ZodString;
+        parent: z.ZodOptional<z.ZodString>;
+        agent_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    "work.status_changed": z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$loose>;
+    "model.requested": z.ZodObject<{
+        provider: z.ZodString;
+        model: z.ZodString;
+        message_count: z.ZodInt;
+        tool_names: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>;
+    "model.completed": z.ZodObject<{
+        stop_reason: z.ZodEnum<{
+            end_turn: "end_turn";
+            max_tokens: "max_tokens";
+            other: "other";
+            refusal: "refusal";
+            tool_call: "tool_call";
+        }>;
+        content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"tool_call">;
+            id: z.ZodString;
+            name: z.ZodString;
+            input: z.ZodUnknown;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"opaque">;
+            provider: z.ZodString;
+            data: z.ZodUnknown;
+        }, z.core.$loose>], "type">>;
+        raw: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$loose>;
+    "model.failed": z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$loose>;
+    "tool.called": z.ZodObject<{
+        call_id: z.ZodString;
+        provider: z.ZodString;
+        name: z.ZodString;
+        input: z.ZodUnknown;
+    }, z.core.$loose>;
+    "tool.completed": z.ZodObject<{
+        call_id: z.ZodString;
+        content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"json">;
+            value: z.ZodUnknown;
+        }, z.core.$loose>], "type">>;
+        is_error: z.ZodBoolean;
+        observation: z.ZodOptional<z.ZodObject<{
+            source: z.ZodString;
+            retrieved_at: z.ZodISODateTime;
+        }, z.core.$loose>>;
+        after: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+            missing: z.ZodOptional<z.ZodLiteral<true>>;
+            claimed: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$loose>>>;
+    }, z.core.$loose>;
+    "tool.rejected": z.ZodObject<{
+        call_id: z.ZodString;
+        name: z.ZodString;
+        code: z.ZodEnum<{
+            invalid_path: "invalid_path";
+            not_allowed: "not_allowed";
+            outside_workspace: "outside_workspace";
+            reserved_path: "reserved_path";
+            schema_mismatch: "schema_mismatch";
+            unknown_tool: "unknown_tool";
+        }>;
+        reason: z.ZodString;
+    }, z.core.$loose>;
+    "human.input_requested": z.ZodObject<{
+        call_id: z.ZodString;
+        question: z.ZodString;
+    }, z.core.$loose>;
+    "human.input_provided": z.ZodObject<{
+        call_id: z.ZodString;
+        answer: z.ZodString;
+    }, z.core.$loose>;
+    "human.message": z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$loose>;
+    "usage.recorded": z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"model_inference">;
+        provider: z.ZodString;
+        model: z.ZodString;
+        usage: z.ZodObject<{
+            input_tokens: z.ZodInt;
+            output_tokens: z.ZodInt;
+            cached_input_tokens: z.ZodOptional<z.ZodInt>;
+            cache_write_tokens: z.ZodOptional<z.ZodInt>;
+            reasoning_tokens: z.ZodOptional<z.ZodInt>;
+        }, z.core.$loose>;
+    }, z.core.$loose>, z.ZodObject<{
+        kind: z.ZodLiteral<"tool_execution">;
+        provider: z.ZodString;
+        usage: z.ZodObject<{
+            duration_ms: z.ZodInt;
+        }, z.core.$loose>;
+    }, z.core.$loose>], "kind">;
+    "evidence.recorded": z.ZodObject<{
+        claim: z.ZodString;
+        refs: z.ZodArray<z.ZodString>;
+        artifacts: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            sha256: z.ZodString;
+            missing: z.ZodOptional<z.ZodLiteral<true>>;
+            claimed: z.ZodOptional<z.ZodLiteral<true>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    "work.completed": z.ZodObject<{
+        summary: z.ZodString;
+    }, z.core.$loose>;
+    "work.failed": z.ZodObject<{
+        reason: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$loose>;
+};
+export declare const EventFileSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    id: z.ZodString;
+    work_id: z.ZodString;
+    seq: z.ZodInt;
+    type: z.ZodString;
+    occurred_at: z.ZodISODateTime;
+    recorded_at: z.ZodISODateTime;
+    payload: z.ZodUnknown;
+}, z.core.$strict>;
+export type EventFile = z.infer<typeof EventFileSchema>;
+export declare function eventToFile(event: AnyEvent): EventFile;
+/**
+ * Canonical JSON form: object keys sorted recursively so that equal data is
+ * written as equal bytes. Inside the free-form fields (`input`, `data`, `value`,
+ * `raw`) `undefined` becomes `null`, because JSON has no `undefined` and a
+ * dropped key would make the line unreadable.
+ */
+export declare function canonical(value: unknown, insideData?: boolean, seen?: WeakSet<object>): unknown;
+export declare function eventFromFile(input: unknown): AnyEvent;
+export {};