@openshain/core 0.1.0 → 0.2.0

package/dist/work/store.js

@@ -0,0 +1,174 @@
+import { readdir, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isOpenshainError, OpenshainError } from "../errors.js";
+import { newWorkId, parseWorkId } from "../ids.js";
+import { EventLog } from "./event-log.js";
+import { acquireLock } from "./lock.js";
+import { reduceWork, transition, workToFile } from "./work.js";
+export const WORK_DIR_NAME = "work";
+export const WORK_FILE_NAME = "work.json";
+/** Works of one workspace, stored under work/<id>/. Reads need no lock; writes go through a handle. */
+export class WorkStore {
+    root;
+    constructor(root) {
+        this.root = root;
+    }
+    async create(input) {
+        const id = newWorkId();
+        const dir = this.dir(id);
+        const lock = await acquireLock(dir);
+        try {
+            const log = await EventLog.open(dir, id);
+            await log.append({
+                type: "work.created",
+                payload: {
+                    objective: input.objective,
+                    principal: input.principal,
+                    profession: input.profession,
+                    type: input.type ?? "request",
+                    ...(input.parent !== undefined && { parent: input.parent }),
+                    ...(input.agentName !== undefined && { agentName: input.agentName }),
+                },
+            });
+            return await this.snapshot(id, await log.read());
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    async get(id) {
+        return reduceWork(await this.events(id));
+    }
+    async list() {
+        let names;
+        try {
+            names = await readdir(join(this.root, WORK_DIR_NAME));
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return { works: [], problems: [] };
+            throw err;
+        }
+        const result = { works: [], problems: [] };
+        for (const name of names.sort()) {
+            let id;
+            try {
+                id = parseWorkId(name);
+            }
+            catch {
+                continue; // not a work directory
+            }
+            try {
+                result.works.push(await this.get(id));
+            }
+            catch (error) {
+                if (!isOpenshainError(error))
+                    throw error;
+                result.problems.push({ id, error });
+            }
+        }
+        return result;
+    }
+    async events(id) {
+        const dir = await this.existingDir(id);
+        const log = await EventLog.open(dir, id);
+        return log.read();
+    }
+    /** Takes the work's lock. Call close() when done, or use append()/transition() for a single write. */
+    async open(id) {
+        const dir = await this.existingDir(id);
+        const lock = await acquireLock(dir);
+        let log;
+        try {
+            log = await EventLog.open(dir, id);
+        }
+        catch (err) {
+            await lock.release();
+            throw err;
+        }
+        return this.handle(id, log, lock);
+    }
+    /** Opens, appends one event, refreshes work.json and closes. */
+    async append(id, event) {
+        const handle = await this.open(id);
+        try {
+            return await handle.append(event);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    /** Opens, records one status change and closes. */
+    async transition(id, to, reason) {
+        const handle = await this.open(id);
+        try {
+            return await handle.transition(to, reason);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    handle(id, log, lock) {
+        const store = this;
+        let open = true;
+        const assertOpen = () => {
+            if (!open)
+                throw new OpenshainError("lock_held", `work ${id} handle is closed`);
+        };
+        const handle = {
+            id,
+            async current() {
+                return reduceWork(await log.read());
+            },
+            events() {
+                return log.read();
+            },
+            async append(event) {
+                assertOpen();
+                const appended = await log.append(event);
+                await store.snapshot(id, await log.read());
+                return appended;
+            },
+            async transition(to, reason) {
+                assertOpen();
+                if (to === "completed" || to === "failed") {
+                    throw new OpenshainError("invalid_transition", `use work.${to} to move a work to ${to}; status changes cannot end a work`);
+                }
+                const work = reduceWork(await log.read());
+                transition(work.status, to);
+                return handle.append({
+                    type: "work.status_changed",
+                    payload: { from: work.status, to, reason },
+                });
+            },
+            async close() {
+                if (!open)
+                    return;
+                open = false;
+                await lock.release();
+            },
+        };
+        return handle;
+    }
+    dir(id) {
+        return join(this.root, WORK_DIR_NAME, parseWorkId(id));
+    }
+    async existingDir(id) {
+        const dir = this.dir(id);
+        try {
+            await stat(dir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new OpenshainError("not_found", `work ${id} does not exist in ${this.root}`);
+            }
+            throw err;
+        }
+        return dir;
+    }
+    async snapshot(id, events) {
+        const work = reduceWork(events);
+        await writeFile(join(this.dir(id), WORK_FILE_NAME), `${JSON.stringify(workToFile(work), null, 2)}\n`, "utf8");
+        return work;
+    }
+}

package/dist/work/work.d.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+import type { WorkId } from "../ids.ts";
+import type { AnyEvent, Artifact } from "./events.ts";
+export declare const WORK_STATUSES: readonly ["queued", "in_progress", "waiting_input", "waiting_approval", "waiting_external", "completed", "failed", "cancelled"];
+export declare const WorkStatus: z.ZodEnum<{
+    cancelled: "cancelled";
+    completed: "completed";
+    failed: "failed";
+    in_progress: "in_progress";
+    queued: "queued";
+    waiting_approval: "waiting_approval";
+    waiting_external: "waiting_external";
+    waiting_input: "waiting_input";
+}>;
+export type WorkStatus = z.infer<typeof WorkStatus>;
+/**
+ * The type of the work that records a conversation. Only a session opens one: its objective is a
+ * label that stays out of the projection, and it is not run like other works.
+ */
+export declare const SESSION_WORK_TYPE = "session";
+/** Throws invalid_transition unless a work may move from one status to the other. */
+export declare function transition(from: WorkStatus, to: WorkStatus): void;
+export interface Work {
+    id: WorkId;
+    principal: string;
+    profession: string;
+    type: string;
+    objective: string;
+    /** The work this one was started from, if any. */
+    parent?: string;
+    /** The name the model goes by in this work, when a session gave it one. */
+    agentName?: string;
+    status: WorkStatus;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    outcome?: {
+        summary: string;
+        artifacts: Artifact[];
+    };
+    failure?: {
+        reason: string;
+        detail: string;
+    };
+}
+/** Rebuilds the current state of a work from its event log. The log is the truth. */
+export declare function reduceWork(events: readonly AnyEvent[]): Work;
+export declare function isTerminal(status: WorkStatus): boolean;
+/** Shape of work.json. A projection of the event log, never the source of truth. */
+export declare const WorkFileSchema: z.ZodObject<{
+    id: z.ZodString;
+    principal: z.ZodString;
+    profession: z.ZodString;
+    type: z.ZodString;
+    objective: z.ZodString;
+    parent: z.ZodOptional<z.ZodString>;
+    agent_name: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        cancelled: "cancelled";
+        completed: "completed";
+        failed: "failed";
+        in_progress: "in_progress";
+        queued: "queued";
+        waiting_approval: "waiting_approval";
+        waiting_external: "waiting_external";
+        waiting_input: "waiting_input";
+    }>;
+    created_at: z.ZodISODateTime;
+    started_at: z.ZodOptional<z.ZodISODateTime>;
+    completed_at: z.ZodOptional<z.ZodISODateTime>;
+    outcome: z.ZodOptional<z.ZodObject<{
+        summary: 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.$strict>>;
+    }, z.core.$strict>>;
+    failure: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkFile = z.infer<typeof WorkFileSchema>;
+export declare function workToFile(work: Work): WorkFile;

package/dist/work/work.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { OpenshainError } from "../errors.js";
+export const WORK_STATUSES = [
+    "queued",
+    "in_progress",
+    "waiting_input",
+    "waiting_approval",
+    "waiting_external",
+    "completed",
+    "failed",
+    "cancelled",
+];
+export const WorkStatus = z.enum(WORK_STATUSES);
+/**
+ * The type of the work that records a conversation. Only a session opens one: its objective is a
+ * label that stays out of the projection, and it is not run like other works.
+ */
+export const SESSION_WORK_TYPE = "session";
+const allowed = {
+    queued: ["in_progress", "cancelled"],
+    in_progress: [
+        "waiting_input",
+        "waiting_approval",
+        "waiting_external",
+        "completed",
+        "failed",
+        "cancelled",
+    ],
+    waiting_input: ["in_progress", "cancelled", "failed"],
+    waiting_approval: ["in_progress", "cancelled", "failed"],
+    waiting_external: ["in_progress", "cancelled", "failed"],
+    completed: [],
+    failed: [],
+    cancelled: [],
+};
+/** Throws invalid_transition unless a work may move from one status to the other. */
+export function transition(from, to) {
+    if (!allowed[from].includes(to)) {
+        throw new OpenshainError("invalid_transition", `cannot move work from ${from} to ${to}`);
+    }
+}
+/** Rebuilds the current state of a work from its event log. The log is the truth. */
+export function reduceWork(events) {
+    const first = events[0];
+    if (first?.type !== "work.created") {
+        throw new OpenshainError("corrupt_log", "the first event of a work must be work.created");
+    }
+    const created = first;
+    const work = {
+        id: created.workId,
+        principal: created.payload.principal,
+        profession: created.payload.profession,
+        type: created.payload.type,
+        objective: created.payload.objective,
+        ...(created.payload.parent !== undefined && { parent: created.payload.parent }),
+        ...(created.payload.agentName !== undefined && { agentName: created.payload.agentName }),
+        status: "queued",
+        createdAt: created.occurredAt,
+    };
+    let artifacts = [];
+    for (const event of events.slice(1)) {
+        switch (event.type) {
+            case "work.status_changed": {
+                const { payload } = event;
+                const to = WorkStatus.safeParse(payload.to);
+                if (!to.success) {
+                    throw new OpenshainError("corrupt_log", `unknown work status "${payload.to}"`);
+                }
+                if (to.data === "completed" || to.data === "failed") {
+                    throw new OpenshainError("corrupt_log", `work.status_changed may not move a work to ${to.data}; use work.${to.data}`);
+                }
+                if (payload.from !== work.status) {
+                    throw new OpenshainError("corrupt_log", `work.status_changed says the work was ${payload.from} but it was ${work.status}`);
+                }
+                move(work, to.data, event.occurredAt);
+                break;
+            }
+            case "evidence.recorded":
+                if (isTerminal(work.status)) {
+                    throw new OpenshainError("corrupt_log", `evidence recorded after the work ${work.status}`);
+                }
+                artifacts = event.payload.artifacts;
+                break;
+            case "work.completed":
+                move(work, "completed", event.occurredAt);
+                work.outcome = { summary: event.payload.summary, artifacts };
+                break;
+            case "work.failed": {
+                const { payload } = event;
+                move(work, "failed", event.occurredAt);
+                work.failure = { reason: payload.reason, detail: payload.detail };
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return work;
+}
+export function isTerminal(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}
+function move(work, to, at) {
+    transition(work.status, to);
+    work.status = to;
+    if (to === "in_progress" && work.startedAt === undefined)
+        work.startedAt = at;
+    if (isTerminal(to))
+        work.completedAt = at;
+}
+const artifactFile = z.strictObject({
+    path: z.string(),
+    sha256: z.string(),
+    missing: z.literal(true).optional(),
+    claimed: z.literal(true).optional(),
+});
+/** Shape of work.json. A projection of the event log, never the source of truth. */
+export const WorkFileSchema = z.strictObject({
+    id: z.string(),
+    principal: z.string(),
+    profession: z.string(),
+    type: z.string(),
+    objective: z.string(),
+    parent: z.string().optional(),
+    agent_name: z.string().optional(),
+    status: WorkStatus,
+    created_at: z.iso.datetime(),
+    started_at: z.iso.datetime().optional(),
+    completed_at: z.iso.datetime().optional(),
+    outcome: z.strictObject({ summary: z.string(), artifacts: z.array(artifactFile) }).optional(),
+    failure: z.strictObject({ reason: z.string(), detail: z.string() }).optional(),
+});
+export function workToFile(work) {
+    return {
+        id: work.id,
+        principal: work.principal,
+        profession: work.profession,
+        type: work.type,
+        objective: work.objective,
+        ...(work.parent !== undefined && { parent: work.parent }),
+        ...(work.agentName !== undefined && { agent_name: work.agentName }),
+        status: work.status,
+        created_at: work.createdAt,
+        ...(work.startedAt !== undefined && { started_at: work.startedAt }),
+        ...(work.completedAt !== undefined && { completed_at: work.completedAt }),
+        ...(work.outcome && { outcome: work.outcome }),
+        ...(work.failure && { failure: work.failure }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openshain/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Contracts (provider interfaces), fundamental objects, and the work runtime",
   "keywords": [
     "openshain",
@@ -12,7 +12,7 @@
   ],
   "author": "Hiroki Nakatani",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/openshain/openshain",
+  "homepage": "https://openshain.jp",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/openshain/openshain.git",
@@ -21,24 +21,35 @@
   "bugs": "https://github.com/openshain/openshain/issues",
   "type": "module",
   "engines": {
+    "node": ">=22",
     "bun": ">=1.3"
   },
   "files": [
+    "dist",
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
     "README.md",
     "LICENSE"
   ],
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
-  "publishConfig": {
-    "access": "public"
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p tsconfig.build.json",
+    "prepublishOnly": "rm -rf dist && ../../node_modules/.bin/tsc -p tsconfig.build.json"
   },
   "dependencies": {
     "ajv": "8.20.0",
     "safe-regex2": "5.1.1",
     "yaml": "2.9.0",
     "zod": "4.5.4"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/ids.ts

@@ -1,4 +1,5 @@
 import { OpenshainError } from "./errors.ts";
+import { uuidv7 } from "./uuid.ts";
 
 declare const brand: unique symbol;
 type Brand<T, Name extends string> = T & { readonly [brand]: Name };
@@ -9,11 +10,11 @@ export type EventId = Brand<string, "EventId">;
 const UUID_V7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
 export function newWorkId(): WorkId {
-  return `work_${Bun.randomUUIDv7()}` as WorkId;
+  return `work_${uuidv7()}` as WorkId;
 }
 
 export function newEventId(): EventId {
-  return `evt_${Bun.randomUUIDv7()}` as EventId;
+  return `evt_${uuidv7()}` as EventId;
 }
 
 export function parseWorkId(value: string): WorkId {

package/src/index.ts

@@ -56,6 +56,7 @@ export {
   type ToolResult,
 } from "./tool/types.ts";
 export { compileInputValidator, type InputValidation } from "./tool/validate.ts";
+export { uuidv7 } from "./uuid.ts";
 export { verifyArtifact } from "./work/artifacts.ts";
 export { EVENTS_FILE_NAME, EventLog, type NewEvent } from "./work/event-log.ts";
 export {

package/src/uuid.ts

@@ -0,0 +1,33 @@
+/**
+ * UUID v7 (RFC 9562) without a runtime-specific API, so the same code runs on Node and Bun.
+ * Ids made in one process within the same millisecond stay in creation order: the 12 random
+ * bits after the timestamp act as a counter until the clock moves on.
+ */
+let lastMs = 0;
+let counter = 0;
+
+export function uuidv7(now: number = Date.now()): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  if (now > lastMs) {
+    lastMs = now;
+    counter = (((bytes[6] as number) & 0x07) << 8) | (bytes[7] as number);
+  } else {
+    now = lastMs;
+    counter = (counter + 1) & 0x0fff;
+    if (counter === 0) {
+      lastMs = now = lastMs + 1;
+    }
+  }
+  bytes[0] = Math.floor(now / 2 ** 40) & 0xff;
+  bytes[1] = Math.floor(now / 2 ** 32) & 0xff;
+  bytes[2] = (now >>> 24) & 0xff;
+  bytes[3] = (now >>> 16) & 0xff;
+  bytes[4] = (now >>> 8) & 0xff;
+  bytes[5] = now & 0xff;
+  bytes[6] = 0x70 | (counter >>> 8);
+  bytes[7] = counter & 0xff;
+  bytes[8] = ((bytes[8] as number) & 0x3f) | 0x80;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/src/work/projection.ts

@@ -40,7 +40,7 @@ export function buildProjection(input: ProjectionInput): Projection {
     ...(agentName
       ? [`あなたの名前は ${agentName}。名乗るときはこの名前と、社員エージェントであることを言う。`]
       : []),
-    "件数、合計、検索の結果は Tool が返した値をそのまま使い、自分で数えたり足したりしない。各ターンの最後に Runtime が「残り model 呼び出し N 回、Tool 呼び出し M 回」という 1 行を user message として足す。これは残量の通知で、返事は要らない。依頼が終わったら、何をしたかを要約して終える。",
+    "件数、合計、検索の結果は Tool が返した値をそのまま使い、自分で数えたり合計したりしない。各ターンの最後に Runtime が「残り model 呼び出し N 回、Tool 呼び出し M 回」という 1 行を user message として追加する。これは残量の通知で、返事は要らない。依頼が終わったら、何をしたかを要約して終える。",
   ].join("\n\n");
 
   const messages: ModelMessage[] = [];