@openshain/core 0.1.1 → 0.3.1

package/dist/work/events.js

@@ -0,0 +1,360 @@
+import { z } from "zod";
+import { OpenshainError } from "../errors.js";
+export const TOOL_REJECTION_CODES = [
+    "schema_mismatch",
+    "unknown_tool",
+    "not_allowed",
+    "reserved_path",
+    "outside_workspace",
+    "invalid_path",
+    "limit_reached",
+];
+// ---------------------------------------------------------------------------
+// File-side schemas (snake_case). These are the on-disk contract.
+// ---------------------------------------------------------------------------
+// Payload schemas are loose: a field added by a newer runtime must not make an
+// older runtime refuse the log. Only the envelope is strict; envelope changes bump `v`.
+const textPart = z.looseObject({ type: z.literal("text"), text: z.string() });
+const toolCallPart = z.looseObject({
+    type: z.literal("tool_call"),
+    id: z.string(),
+    name: z.string(),
+    input: z.unknown(),
+});
+const opaquePart = z.looseObject({
+    type: z.literal("opaque"),
+    provider: z.string(),
+    data: z.unknown(),
+});
+const jsonPart = z.looseObject({ type: z.literal("json"), value: z.unknown() });
+const artifact = z.looseObject({
+    path: z.string(),
+    sha256: z.string(),
+    missing: z.literal(true).optional(),
+    claimed: z.literal(true).optional(),
+});
+const modelUsageFile = z.looseObject({
+    input_tokens: z.int().nonnegative(),
+    output_tokens: z.int().nonnegative(),
+    cached_input_tokens: z.int().nonnegative().optional(),
+    cache_write_tokens: z.int().nonnegative().optional(),
+    reasoning_tokens: z.int().nonnegative().optional(),
+});
+export const payloadFileSchemas = {
+    "work.created": z.looseObject({
+        objective: z.string(),
+        principal: z.string(),
+        profession: z.string(),
+        type: z.string(),
+        parent: z.string().optional(),
+        agent_name: z.string().optional(),
+    }),
+    "work.status_changed": z.looseObject({ from: z.string(), to: z.string(), reason: z.string() }),
+    "model.requested": z.looseObject({
+        provider: z.string(),
+        model: z.string(),
+        message_count: z.int().nonnegative(),
+        tool_names: z.array(z.string()),
+    }),
+    "model.completed": z.looseObject({
+        stop_reason: z.enum(["end_turn", "tool_call", "max_tokens", "refusal", "other"]),
+        content: z.array(z.discriminatedUnion("type", [textPart, toolCallPart, opaquePart])),
+        raw: z.unknown().optional(),
+    }),
+    "model.failed": z.looseObject({ code: z.string(), message: z.string() }),
+    "tool.called": z.looseObject({
+        call_id: z.string(),
+        provider: z.string(),
+        name: z.string(),
+        input: z.unknown(),
+    }),
+    "tool.completed": z.looseObject({
+        call_id: z.string(),
+        content: z.array(z.discriminatedUnion("type", [textPart, jsonPart])),
+        is_error: z.boolean(),
+        observation: z.looseObject({ source: z.string(), retrieved_at: z.iso.datetime() }).optional(),
+        after: z.array(artifact).optional(),
+    }),
+    "tool.rejected": z.looseObject({
+        call_id: z.string(),
+        name: z.string(),
+        code: z.enum(TOOL_REJECTION_CODES),
+        reason: z.string(),
+    }),
+    "human.input_requested": z.looseObject({ call_id: z.string(), question: z.string() }),
+    "human.input_provided": z.looseObject({ call_id: z.string(), answer: z.string() }),
+    "human.message": z.looseObject({ text: z.string() }),
+    "prompt.expanded": z.looseObject({ name: z.string(), source: z.string(), text: z.string() }),
+    "usage.recorded": z.discriminatedUnion("kind", [
+        z.looseObject({
+            kind: z.literal("model_inference"),
+            provider: z.string(),
+            model: z.string(),
+            usage: modelUsageFile,
+        }),
+        z.looseObject({
+            kind: z.literal("tool_execution"),
+            provider: z.string(),
+            usage: z.looseObject({ duration_ms: z.int().nonnegative() }),
+        }),
+    ]),
+    "evidence.recorded": z.looseObject({
+        claim: z.string(),
+        refs: z.array(z.string()),
+        artifacts: z.array(artifact),
+    }),
+    "work.completed": z.looseObject({ summary: z.string() }),
+    "work.failed": z.looseObject({ reason: z.string(), detail: z.string() }),
+};
+export const EventFileSchema = z.strictObject({
+    v: z.literal(1),
+    id: z.string(),
+    work_id: z.string(),
+    seq: z.int().positive(),
+    type: z.string(),
+    occurred_at: z.iso.datetime(),
+    recorded_at: z.iso.datetime(),
+    payload: z.unknown(),
+});
+// ---------------------------------------------------------------------------
+// Mapping. The only place where snake_case and camelCase meet.
+// ---------------------------------------------------------------------------
+export function eventToFile(event) {
+    const payload = isKnownType(event.type)
+        ? payloadToFile(event.type, event.payload)
+        : event.payload;
+    return {
+        v: event.v,
+        id: event.id,
+        work_id: event.workId,
+        seq: event.seq,
+        type: event.type,
+        occurred_at: event.occurredAt,
+        recorded_at: event.recordedAt,
+        payload: canonical(payload),
+    };
+}
+const DATA_KEYS = new Set(["input", "data", "value", "raw"]);
+/**
+ * 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 function canonical(value, insideData = false, seen = new WeakSet()) {
+    if (value === undefined)
+        return insideData ? null : undefined;
+    if (value === null || typeof value !== "object")
+        return value;
+    if (seen.has(value)) {
+        throw new OpenshainError("invalid_event", "a value that refers to itself cannot be recorded");
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((item) => canonical(item, insideData, seen) ?? null);
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const inner = insideData || DATA_KEYS.has(key);
+            const item = canonical(value[key], inner, seen);
+            if (item !== undefined)
+                define(out, key, item);
+            else if (inner)
+                define(out, key, null);
+        }
+        return out;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+/** Sets an own property even for a key such as `__proto__`, which plain assignment would treat as the prototype. */
+function define(target, key, item) {
+    Object.defineProperty(target, key, {
+        value: item,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+export function eventFromFile(input) {
+    const parsed = EventFileSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new OpenshainError("corrupt_log", `event envelope: ${describeIssues(parsed.error)}`);
+    }
+    const file = parsed.data;
+    const envelope = {
+        v: file.v,
+        id: file.id,
+        workId: file.work_id,
+        seq: file.seq,
+        occurredAt: file.occurred_at,
+        recordedAt: file.recorded_at,
+    };
+    if (!isKnownType(file.type)) {
+        return { ...envelope, type: file.type, payload: file.payload };
+    }
+    const payload = payloadFileSchemas[file.type].safeParse(file.payload);
+    if (!payload.success) {
+        throw new OpenshainError("corrupt_log", `${file.type} payload: ${describeIssues(payload.error)}`);
+    }
+    return {
+        ...envelope,
+        type: file.type,
+        payload: payloadFromFile(file.type, payload.data),
+    };
+}
+/**
+ * Validates a payload given in the file form (snake_case, as in spec/schemas/events.v1.json) and
+ * returns it in the in-memory form. For events a client hands the runtime to record.
+ */
+export function parsePayloadFile(type, payload) {
+    const parsed = payloadFileSchemas[type].safeParse(payload);
+    if (!parsed.success) {
+        throw new OpenshainError("invalid_event", `${type} payload: ${describeIssues(parsed.error)}`);
+    }
+    return payloadFromFile(type, parsed.data);
+}
+export function isKnownEventType(type) {
+    return isKnownType(type);
+}
+function isKnownType(type) {
+    return Object.hasOwn(payloadFileSchemas, type);
+}
+function describeIssues(error) {
+    return error.issues
+        .map((issue) => (issue.path.length ? `${issue.path.map(String).join(".")}: ` : "") + issue.message)
+        .join("; ");
+}
+function usageToFile(usage) {
+    const out = {
+        input_tokens: usage.inputTokens,
+        output_tokens: usage.outputTokens,
+    };
+    if (usage.cachedInputTokens !== undefined)
+        out.cached_input_tokens = usage.cachedInputTokens;
+    if (usage.cacheWriteTokens !== undefined)
+        out.cache_write_tokens = usage.cacheWriteTokens;
+    if (usage.reasoningTokens !== undefined)
+        out.reasoning_tokens = usage.reasoningTokens;
+    return out;
+}
+function usageFromFile(usage) {
+    const out = { inputTokens: usage.input_tokens, outputTokens: usage.output_tokens };
+    if (usage.cached_input_tokens !== undefined)
+        out.cachedInputTokens = usage.cached_input_tokens;
+    if (usage.cache_write_tokens !== undefined)
+        out.cacheWriteTokens = usage.cache_write_tokens;
+    if (usage.reasoning_tokens !== undefined)
+        out.reasoningTokens = usage.reasoning_tokens;
+    return out;
+}
+/**
+ * Event types whose field names differ between code and file. Every other
+ * payload uses the same names on both sides and needs no codec.
+ */
+const codecs = {
+    "work.created": {
+        // Only agent_name changes its name; every other field, known or not, passes through.
+        toFile: ({ agentName, ...rest }) => ({
+            ...rest,
+            ...(agentName !== undefined && { agent_name: agentName }),
+        }),
+        fromFile: ({ agent_name, parent, ...rest }) => ({
+            ...rest,
+            ...(parent !== undefined && { parent }),
+            ...(agent_name !== undefined && { agentName: agent_name }),
+        }),
+    },
+    "model.requested": {
+        toFile: (p) => ({
+            provider: p.provider,
+            model: p.model,
+            message_count: p.messageCount,
+            tool_names: p.toolNames,
+        }),
+        fromFile: (p) => ({
+            provider: p.provider,
+            model: p.model,
+            messageCount: p.message_count,
+            toolNames: p.tool_names,
+        }),
+    },
+    "model.completed": {
+        toFile: (p) => {
+            const out = { stop_reason: p.stopReason, content: p.content };
+            if (p.raw !== undefined)
+                out.raw = p.raw;
+            return out;
+        },
+        fromFile: (p) => {
+            const out = {
+                stopReason: p.stop_reason,
+                content: p.content,
+            };
+            if (p.raw !== undefined)
+                out.raw = p.raw;
+            return out;
+        },
+    },
+    "tool.called": {
+        toFile: (p) => ({ call_id: p.callId, provider: p.provider, name: p.name, input: p.input }),
+        fromFile: (p) => ({ callId: p.call_id, provider: p.provider, name: p.name, input: p.input }),
+    },
+    "tool.completed": {
+        toFile: (p) => {
+            const out = {
+                call_id: p.callId,
+                content: p.content,
+                is_error: p.isError,
+            };
+            if (p.observation) {
+                out.observation = { source: p.observation.source, retrieved_at: p.observation.retrievedAt };
+            }
+            if (p.after)
+                out.after = p.after;
+            return out;
+        },
+        fromFile: (p) => {
+            const out = {
+                callId: p.call_id,
+                content: p.content,
+                isError: p.is_error,
+            };
+            if (p.observation) {
+                out.observation = { source: p.observation.source, retrievedAt: p.observation.retrieved_at };
+            }
+            if (p.after)
+                out.after = p.after.map((a) => ({ path: a.path, sha256: a.sha256 }));
+            return out;
+        },
+    },
+    "tool.rejected": {
+        toFile: (p) => ({ call_id: p.callId, name: p.name, code: p.code, reason: p.reason }),
+        fromFile: (p) => ({ callId: p.call_id, name: p.name, code: p.code, reason: p.reason }),
+    },
+    "human.input_requested": {
+        toFile: (p) => ({ call_id: p.callId, question: p.question }),
+        fromFile: (p) => ({ callId: p.call_id, question: p.question }),
+    },
+    "human.input_provided": {
+        toFile: (p) => ({ call_id: p.callId, answer: p.answer }),
+        fromFile: (p) => ({ callId: p.call_id, answer: p.answer }),
+    },
+    "usage.recorded": {
+        toFile: (p) => p.kind === "tool_execution"
+            ? { kind: p.kind, provider: p.provider, usage: { duration_ms: p.usage.durationMs } }
+            : { kind: p.kind, provider: p.provider, model: p.model, usage: usageToFile(p.usage) },
+        fromFile: (p) => p.kind === "tool_execution"
+            ? { kind: p.kind, provider: p.provider, usage: { durationMs: p.usage.duration_ms } }
+            : { kind: p.kind, provider: p.provider, model: p.model, usage: usageFromFile(p.usage) },
+    },
+};
+function payloadToFile(type, payload) {
+    const codec = codecs[type];
+    return codec ? codec.toFile(payload) : payload;
+}
+function payloadFromFile(type, payload) {
+    const codec = codecs[type];
+    return codec ? codec.fromFile(payload) : payload;
+}

package/dist/work/history.d.ts

@@ -0,0 +1,38 @@
+import type { AnyEvent } from "./events.ts";
+/** Why a client gives up on a work, as recorded in `work.failed`. */
+export type FailureReason = "limit_reached" | "model_refusal" | "model_error";
+/**
+ * Counts the tool calls of a work the way the limits do: every call the runtime started, plus
+ * every rejection that never became a call. A rejection of a started call is not a second call.
+ */
+export declare function countToolCalls(events: readonly AnyEvent[]): number;
+export interface PendingQuestion {
+    callId: string;
+    question: string;
+}
+/**
+ * The questions of the work that have no answer yet, oldest first. Call ids of questions are
+ * minted by the runtime, so the whole log is searched: a client recording its own model turns
+ * must not hide a question.
+ */
+export declare function pendingQuestions(events: readonly AnyEvent[]): PendingQuestion[];
+export interface HistoryCall {
+    callId: string;
+    name: string;
+    /** The path the call named, when its input had one. */
+    path?: string;
+    /** Present once the call has a result; absent while it is still open. */
+    isError?: boolean;
+    rejected?: string;
+}
+export interface WorkHistory {
+    calls: HistoryCall[];
+    /** Calls that were started but have no result: the work stopped while they ran. */
+    unfinished: HistoryCall[];
+    pending: PendingQuestion[];
+    toolCalls: number;
+    /** Model calls recorded on the work, for a client that counts them against a limit. */
+    modelCalls: number;
+}
+/** What a client needs to pick a work up where it stopped. Built from the log alone. */
+export declare function workHistory(events: readonly AnyEvent[]): WorkHistory;

package/dist/work/history.js

@@ -0,0 +1,70 @@
+/**
+ * Counts the tool calls of a work the way the limits do: every call the runtime started, plus
+ * every rejection that never became a call. A rejection of a started call is not a second call.
+ */
+export function countToolCalls(events) {
+    let count = 0;
+    let started = new Set();
+    for (const event of events) {
+        if (event.type === "model.completed")
+            started = new Set();
+        else if (event.type === "tool.called") {
+            started.add(event.payload.callId);
+            count += 1;
+        }
+        else if (event.type === "tool.rejected") {
+            if (!started.has(event.payload.callId))
+                count += 1;
+        }
+    }
+    return count;
+}
+/**
+ * The questions of the work that have no answer yet, oldest first. Call ids of questions are
+ * minted by the runtime, so the whole log is searched: a client recording its own model turns
+ * must not hide a question.
+ */
+export function pendingQuestions(events) {
+    const answered = new Set(events
+        .filter((e) => e.type === "human.input_provided")
+        .map((e) => e.payload.callId));
+    return events
+        .filter((e) => e.type === "human.input_requested")
+        .filter((e) => !answered.has(e.payload.callId))
+        .map((e) => ({ callId: e.payload.callId, question: e.payload.question }));
+}
+/** What a client needs to pick a work up where it stopped. Built from the log alone. */
+export function workHistory(events) {
+    const calls = [];
+    const byId = new Map();
+    for (const event of events) {
+        if (event.type === "tool.called") {
+            const { callId, name, input } = event.payload;
+            const path = input?.path;
+            const call = { callId, name, ...(typeof path === "string" && { path }) };
+            calls.push(call);
+            byId.set(callId, call);
+        }
+        else if (event.type === "tool.completed") {
+            const { callId, isError } = event.payload;
+            const call = byId.get(callId);
+            if (call)
+                call.isError = isError;
+        }
+        else if (event.type === "tool.rejected") {
+            const { callId, name, code } = event.payload;
+            const call = byId.get(callId);
+            if (call)
+                call.rejected = code;
+            else
+                calls.push({ callId, name, rejected: code });
+        }
+    }
+    return {
+        calls,
+        unfinished: calls.filter((c) => c.isError === undefined && c.rejected === undefined),
+        pending: pendingQuestions(events),
+        toolCalls: countToolCalls(events),
+        modelCalls: events.filter((e) => e.type === "model.requested").length,
+    };
+}

package/dist/work/lock.d.ts

@@ -0,0 +1,13 @@
+export declare const LOCK_FILE_NAME = "lock";
+export interface Lock {
+    release(): Promise<void>;
+}
+/**
+ * Takes the single-writer lock of a work directory. A lock left behind by a
+ * process that no longer exists, or one that cannot be read, is taken over.
+ * Release only removes the file while it still records this holder.
+ *
+ * Known limit: liveness is judged by pid. A pid reused by an unrelated process
+ * keeps the lock held until that process ends or the file is removed by hand.
+ */
+export declare function acquireLock(dir: string): Promise<Lock>;

package/dist/work/lock.js

@@ -0,0 +1,80 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { OpenshainError } from "../errors.js";
+export const LOCK_FILE_NAME = "lock";
+/**
+ * Takes the single-writer lock of a work directory. A lock left behind by a
+ * process that no longer exists, or one that cannot be read, is taken over.
+ * Release only removes the file while it still records this holder.
+ *
+ * Known limit: liveness is judged by pid. A pid reused by an unrelated process
+ * keeps the lock held until that process ends or the file is removed by hand.
+ */
+export async function acquireLock(dir) {
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch (cause) {
+        throw new OpenshainError("invalid_path", `cannot create the work directory ${dir}`, { cause });
+    }
+    const path = join(dir, LOCK_FILE_NAME);
+    const holder = { pid: process.pid, startedAt: new Date().toISOString() };
+    const content = JSON.stringify({ pid: holder.pid, started_at: holder.startedAt });
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            await writeFile(path, content, { flag: "wx" });
+            return lockHandle(path, holder);
+        }
+        catch (err) {
+            if (err.code !== "EEXIST") {
+                throw new OpenshainError("invalid_path", `cannot write the lock file ${path}`, {
+                    cause: err,
+                });
+            }
+        }
+        const current = await readHolder(path);
+        if (current && isAlive(current.pid)) {
+            throw new OpenshainError("lock_held", `${dir} is locked by process ${current.pid} since ${current.startedAt}`);
+        }
+        await rm(path, { force: true });
+    }
+    throw new OpenshainError("lock_held", `${dir}: could not take the lock`);
+}
+async function readHolder(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (typeof parsed.pid !== "number")
+            return undefined;
+        return { pid: parsed.pid, startedAt: String(parsed.started_at ?? "unknown") };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Only real process ids count. 0 and negatives address process groups and would always "exist". */
+function isAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+function lockHandle(path, holder) {
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            const current = await readHolder(path);
+            if (current && (current.pid !== holder.pid || current.startedAt !== holder.startedAt)) {
+                return; // someone else holds it now; not ours to remove
+            }
+            await rm(path, { force: true });
+        },
+    };
+}

package/dist/work/projection.d.ts

@@ -0,0 +1,31 @@
+import type { Config } from "../config/schema.ts";
+import type { ModelMessage } from "../model/types.ts";
+import type { ToolDefinition } from "../tool/types.ts";
+import { type AnyEvent } from "./events.ts";
+export interface ProjectionInput {
+    events: readonly AnyEvent[];
+    config: Pick<Config, "company" | "principal" | "profession">;
+    /** Tool definitions the model may call. Already filtered by the allow lists. */
+    tools: ToolDefinition[];
+    /** Opaque parts are returned only to the provider that produced them. */
+    providerId: string;
+    budget: {
+        modelCallsLeft: number;
+        toolCallsLeft: number;
+    };
+}
+export interface Projection {
+    system: string;
+    messages: ModelMessage[];
+    tools: ToolDefinition[];
+    budget: {
+        modelCallsLeft: number;
+        toolCallsLeft: number;
+    };
+}
+/**
+ * What the model sees. Built from the event log alone, in order, and therefore
+ * the same bytes every time for the same events. Nothing is rewritten: the
+ * budget line is a user message of its own at the end.
+ */
+export declare function buildProjection(input: ProjectionInput): Projection;