@openshain/core 0.1.0

package/src/work/projection.ts

@@ -0,0 +1,162 @@
+import type { Config } from "../config/schema.ts";
+import { OpenshainError } from "../errors.ts";
+import type { ModelMessage, UserPart } from "../model/types.ts";
+import type { ToolDefinition } from "../tool/types.ts";
+import type { AssistantPart } from "./events.ts";
+import { type AnyEvent, canonical, type Event, type ToolContent } from "./events.ts";
+import { SESSION_WORK_TYPE } from "./work.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 function buildProjection(input: ProjectionInput): Projection {
+  const { config } = input;
+  const first = input.events[0];
+  const agentName =
+    first?.type === "work.created" ? (first as Event<"work.created">).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: ModelMessage[] = [];
+  const pushUserPart = (part: UserPart) => {
+    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 as Event<"work.created">).payload;
+        if (type !== SESSION_WORK_TYPE) pushUserPart({ type: "text", text: objective });
+        break;
+      }
+      case "human.message":
+        pushUserPart({ type: "text", text: (event as Event<"human.message">).payload.text });
+        break;
+      case "model.completed": {
+        const content = (event as Event<"model.completed">).payload.content
+          .filter((part) => part.type !== "opaque" || part.provider === input.providerId)
+          .map((part) => canonical(part) as AssistantPart);
+        if (content.length > 0) messages.push({ role: "assistant", content });
+        break;
+      }
+      case "tool.completed": {
+        const { payload } = event as Event<"tool.completed">;
+        pushUserPart({
+          type: "tool_result",
+          callId: payload.callId,
+          content: renderContent(payload.content),
+          isError: payload.isError,
+        });
+        break;
+      }
+      case "tool.rejected": {
+        const { payload } = event as Event<"tool.rejected">;
+        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: ModelMessage[]): void {
+  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: ToolContent[]): string {
+  return content
+    .map((part) => (part.type === "text" ? part.text : JSON.stringify(part.value)))
+    .join("\n");
+}

package/src/work/store.ts

@@ -0,0 +1,216 @@
+import { readdir, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isOpenshainError, OpenshainError } from "../errors.ts";
+import { newWorkId, parseWorkId, type WorkId } from "../ids.ts";
+import { EventLog, type NewEvent } from "./event-log.ts";
+import type { AnyEvent, Event, EventType } from "./events.ts";
+import { acquireLock, type Lock } from "./lock.ts";
+import { reduceWork, transition, type Work, type WorkStatus, workToFile } from "./work.ts";
+
+export const WORK_DIR_NAME = "work";
+export 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 class WorkStore {
+  constructor(private readonly root: string) {}
+
+  async create(input: CreateWorkInput): Promise<Work> {
+    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: WorkId): Promise<Work> {
+    return reduceWork(await this.events(id));
+  }
+
+  async list(): Promise<ListResult> {
+    let names: string[];
+    try {
+      names = await readdir(join(this.root, WORK_DIR_NAME));
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return { works: [], problems: [] };
+      throw err;
+    }
+    const result: ListResult = { works: [], problems: [] };
+    for (const name of names.sort()) {
+      let id: WorkId;
+      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: WorkId): Promise<AnyEvent[]> {
+    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: WorkId): Promise<WorkHandle> {
+    const dir = await this.existingDir(id);
+    const lock = await acquireLock(dir);
+    let log: EventLog;
+    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<T extends EventType>(id: WorkId, event: NewEvent<T>): Promise<Event<T>> {
+    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: WorkId,
+    to: WorkStatus,
+    reason: string,
+  ): Promise<Event<"work.status_changed">> {
+    const handle = await this.open(id);
+    try {
+      return await handle.transition(to, reason);
+    } finally {
+      await handle.close();
+    }
+  }
+
+  private handle(id: WorkId, log: EventLog, lock: Lock): WorkHandle {
+    const store = this;
+    let open = true;
+    const assertOpen = () => {
+      if (!open) throw new OpenshainError("lock_held", `work ${id} handle is closed`);
+    };
+    const handle: WorkHandle = {
+      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;
+  }
+
+  private dir(id: WorkId): string {
+    return join(this.root, WORK_DIR_NAME, parseWorkId(id));
+  }
+
+  private async existingDir(id: WorkId): Promise<string> {
+    const dir = this.dir(id);
+    try {
+      await stat(dir);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new OpenshainError("not_found", `work ${id} does not exist in ${this.root}`);
+      }
+      throw err;
+    }
+    return dir;
+  }
+
+  private async snapshot(id: WorkId, events: AnyEvent[]): Promise<Work> {
+    const work = reduceWork(events);
+    await writeFile(
+      join(this.dir(id), WORK_FILE_NAME),
+      `${JSON.stringify(workToFile(work), null, 2)}\n`,
+      "utf8",
+    );
+    return work;
+  }
+}

package/src/work/work.ts

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { OpenshainError } from "../errors.ts";
+import type { WorkId } from "../ids.ts";
+import type { AnyEvent, Artifact, Event } from "./events.ts";
+
+export const WORK_STATUSES = [
+  "queued",
+  "in_progress",
+  "waiting_input",
+  "waiting_approval",
+  "waiting_external",
+  "completed",
+  "failed",
+  "cancelled",
+] as const;
+
+export const WorkStatus = z.enum(WORK_STATUSES);
+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 const SESSION_WORK_TYPE = "session";
+
+const allowed: Record<WorkStatus, readonly WorkStatus[]> = {
+  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: WorkStatus, to: WorkStatus): void {
+  if (!allowed[from].includes(to)) {
+    throw new OpenshainError("invalid_transition", `cannot move work from ${from} to ${to}`);
+  }
+}
+
+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 function reduceWork(events: readonly AnyEvent[]): Work {
+  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 as Event<"work.created">;
+  const work: 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: Artifact[] = [];
+
+  for (const event of events.slice(1)) {
+    switch (event.type) {
+      case "work.status_changed": {
+        const { payload } = event as Event<"work.status_changed">;
+        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 as Event<"evidence.recorded">).payload.artifacts;
+        break;
+      case "work.completed":
+        move(work, "completed", event.occurredAt);
+        work.outcome = { summary: (event as Event<"work.completed">).payload.summary, artifacts };
+        break;
+      case "work.failed": {
+        const { payload } = event as Event<"work.failed">;
+        move(work, "failed", event.occurredAt);
+        work.failure = { reason: payload.reason, detail: payload.detail };
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return work;
+}
+
+export function isTerminal(status: WorkStatus): boolean {
+  return status === "completed" || status === "failed" || status === "cancelled";
+}
+
+function move(work: Work, to: WorkStatus, at: string): void {
+  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 type WorkFile = z.infer<typeof WorkFileSchema>;
+
+export function workToFile(work: Work): WorkFile {
+  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 }),
+  };
+}