@openshain/core 0.1.1 → 0.2.0

package/dist/work/events.js

@@ -0,0 +1,344 @@
+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",
+];
+// ---------------------------------------------------------------------------
+// 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() }),
+    "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),
+    };
+}
+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/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;

package/dist/work/projection.js

@@ -0,0 +1,130 @@
+import { OpenshainError } from "../errors.js";
+import { canonical } from "./events.js";
+import { SESSION_WORK_TYPE } from "./work.js";
+/**
+ * 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 function buildProjection(input) {
+    const { config } = input;
+    const first = input.events[0];
+    const agentName = first?.type === "work.created" ? first.payload.agentName : undefined;
+    const system = [
+        config.profession.instructions.trim(),
+        `この会社は ${config.company.name}。`,
+        `依頼する人は ${config.principal.name}(${config.principal.id})。あなたはこの人の代理として働き、この人と話す。あなた自身は ${config.principal.name} ではなく、この会社で働く社員エージェントで、名乗るならそう名乗る。`,
+        ...(agentName
+            ? [`あなたの名前は ${agentName}。名乗るときはこの名前と、社員エージェントであることを言う。`]
+            : []),
+        "件数、合計、検索の結果は Tool が返した値をそのまま使い、自分で数えたり合計したりしない。各ターンの最後に Runtime が「残り model 呼び出し N 回、Tool 呼び出し M 回」という 1 行を user message として追加する。これは残量の通知で、返事は要らない。依頼が終わったら、何をしたかを要約して終える。",
+    ].join("\n\n");
+    const messages = [];
+    const pushUserPart = (part) => {
+        const last = messages.at(-1);
+        if (last?.role === "user")
+            last.content.push(part);
+        else
+            messages.push({ role: "user", content: [part] });
+    };
+    for (const event of input.events) {
+        switch (event.type) {
+            case "work.created": {
+                // A session's objective is a label; the conversation starts with what the person says.
+                const { objective, type } = event.payload;
+                if (type !== SESSION_WORK_TYPE)
+                    pushUserPart({ type: "text", text: objective });
+                break;
+            }
+            case "human.message":
+                pushUserPart({ type: "text", text: event.payload.text });
+                break;
+            case "model.completed": {
+                const content = event.payload.content
+                    .filter((part) => part.type !== "opaque" || part.provider === input.providerId)
+                    .map((part) => canonical(part));
+                if (content.length > 0)
+                    messages.push({ role: "assistant", content });
+                break;
+            }
+            case "tool.completed": {
+                const { payload } = event;
+                pushUserPart({
+                    type: "tool_result",
+                    callId: payload.callId,
+                    content: renderContent(payload.content),
+                    isError: payload.isError,
+                });
+                break;
+            }
+            case "tool.rejected": {
+                const { payload } = event;
+                pushUserPart({
+                    type: "tool_result",
+                    callId: payload.callId,
+                    content: payload.reason,
+                    isError: true,
+                });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    checkToolPairs(messages);
+    // The budget is a message of its own, so the messages before it keep their bytes from turn to
+    // turn and a provider's prompt cache can cover them.
+    messages.push({
+        role: "user",
+        content: [
+            {
+                type: "text",
+                text: `残り model 呼び出し ${input.budget.modelCallsLeft} 回、Tool 呼び出し ${input.budget.toolCallsLeft} 回`,
+            },
+        ],
+    });
+    return { system, messages, tools: input.tools, budget: { ...input.budget } };
+}
+/**
+ * Every tool_result must answer a tool_call in the assistant message right
+ * before it, and every tool_call must be answered before the conversation goes
+ * on. Providers reject anything else, so the log is treated as corrupt.
+ */
+function checkToolPairs(messages) {
+    for (let i = 0; i < messages.length; i++) {
+        const message = messages[i];
+        if (!message)
+            continue;
+        if (message.role === "assistant") {
+            const calls = message.content.filter((p) => p.type === "tool_call").map((p) => p.id);
+            if (calls.length === 0)
+                continue;
+            const next = messages[i + 1];
+            const answered = new Set(next?.role === "user"
+                ? next.content.filter((p) => p.type === "tool_result").map((p) => p.callId)
+                : []);
+            const missing = calls.filter((id) => !answered.has(id));
+            if (missing.length > 0) {
+                throw new OpenshainError("corrupt_log", `tool calls without a result before the conversation continues: ${missing.join(", ")}`);
+            }
+        }
+        else {
+            const results = message.content.filter((p) => p.type === "tool_result").map((p) => p.callId);
+            if (results.length === 0)
+                continue;
+            const previous = messages[i - 1];
+            const known = new Set(previous?.role === "assistant"
+                ? previous.content.filter((p) => p.type === "tool_call").map((p) => p.id)
+                : []);
+            const orphans = results.filter((id) => !known.has(id));
+            if (orphans.length > 0) {
+                throw new OpenshainError("corrupt_log", `tool results that answer no call in the preceding assistant message: ${orphans.join(", ")}`);
+            }
+        }
+    }
+}
+function renderContent(content) {
+    return content
+        .map((part) => (part.type === "text" ? part.text : JSON.stringify(part.value)))
+        .join("\n");
+}

package/dist/work/store.d.ts

@@ -0,0 +1,58 @@
+import { OpenshainError } from "../errors.ts";
+import { type WorkId } from "../ids.ts";
+import { type NewEvent } from "./event-log.ts";
+import type { AnyEvent, Event, EventType } from "./events.ts";
+import { type Work, type WorkStatus } from "./work.ts";
+export declare const WORK_DIR_NAME = "work";
+export declare const WORK_FILE_NAME = "work.json";
+export interface CreateWorkInput {
+    objective: string;
+    principal: string;
+    profession: string;
+    /** Kind of work, for example "request" or "month_end_close". Defaults to "request". */
+    type?: string;
+    /** The work this one is started from, such as a session. */
+    parent?: string;
+    /** The name the model goes by in this work. */
+    agentName?: string;
+}
+export interface ListResult {
+    works: Work[];
+    /** Work directories that could not be read. Reported, never hidden. */
+    problems: {
+        id: string;
+        error: OpenshainError;
+    }[];
+}
+/**
+ * Write access to one work. Holds the work's lock from open() until close(),
+ * so there is exactly one writer at a time.
+ */
+export interface WorkHandle {
+    readonly id: WorkId;
+    current(): Promise<Work>;
+    events(): Promise<AnyEvent[]>;
+    append<T extends EventType>(event: NewEvent<T>): Promise<Event<T>>;
+    /** Records a status change after checking it is allowed. Completion and failure go through their own events. */
+    transition(to: WorkStatus, reason: string): Promise<Event<"work.status_changed">>;
+    close(): Promise<void>;
+}
+/** Works of one workspace, stored under work/<id>/. Reads need no lock; writes go through a handle. */
+export declare class WorkStore {
+    private readonly root;
+    constructor(root: string);
+    create(input: CreateWorkInput): Promise<Work>;
+    get(id: WorkId): Promise<Work>;
+    list(): Promise<ListResult>;
+    events(id: WorkId): Promise<AnyEvent[]>;
+    /** Takes the work's lock. Call close() when done, or use append()/transition() for a single write. */
+    open(id: WorkId): Promise<WorkHandle>;
+    /** Opens, appends one event, refreshes work.json and closes. */
+    append<T extends EventType>(id: WorkId, event: NewEvent<T>): Promise<Event<T>>;
+    /** Opens, records one status change and closes. */
+    transition(id: WorkId, to: WorkStatus, reason: string): Promise<Event<"work.status_changed">>;
+    private handle;
+    private dir;
+    private existingDir;
+    private snapshot;
+}