@openshain/core 0.1.1 → 0.3.1

package/src/config/schema.ts

@@ -46,23 +46,27 @@ export const ConfigFileSchema = z.strictObject({
   }),
   principal: z.strictObject({ id: identifier, name: z.string().min(1).max(200) }),
   profession: z.strictObject({ id: identifier, instructions: z.string().min(1).max(100_000) }),
-  model: z.strictObject({
-    provider: identifier,
-    model: z.string().min(1).max(200),
-    api_key_env: envVarName,
-    base_url: z
-      .url()
-      .refine((value) => {
-        const url = new URL(value);
-        return url.username === "" && url.password === "";
-      }, "base_url must not carry credentials; use api_key_env")
-      .refine((value) => {
-        const url = new URL(value);
-        return url.protocol === "https:" || (url.protocol === "http:" && isLoopback(url.hostname));
-      }, "base_url must use https unless it points at this machine (localhost, 127.0.0.0/8, ::1)")
-      .optional(),
-    options: z.record(z.string(), z.unknown()).optional(),
-  }),
+  model: z
+    .strictObject({
+      provider: identifier,
+      model: z.string().min(1).max(200),
+      api_key_env: envVarName,
+      base_url: z
+        .url()
+        .refine((value) => {
+          const url = new URL(value);
+          return url.username === "" && url.password === "";
+        }, "base_url must not carry credentials; use api_key_env")
+        .refine((value) => {
+          const url = new URL(value);
+          return (
+            url.protocol === "https:" || (url.protocol === "http:" && isLoopback(url.hostname))
+          );
+        }, "base_url must use https unless it points at this machine (localhost, 127.0.0.0/8, ::1)")
+        .optional(),
+      options: z.record(z.string(), z.unknown()).optional(),
+    })
+    .optional(),
   tools: z.array(toolProviderRef).default([{ provider: "standard" }]),
   limits: z
     .strictObject({
@@ -81,18 +85,22 @@ export type ToolProviderRef =
   | { module: string; allow: readonly string[] | undefined };
 
 /** Configuration as used in code (camelCase). */
+/** The model section of openshain.yaml, as the model providers take it. */
+export interface ModelConfig {
+  provider: string;
+  model: string;
+  apiKeyEnv: string;
+  baseUrl: string | undefined;
+  options: Record<string, unknown> | undefined;
+}
+
 export interface Config {
   version: 1;
   company: { name: string; language: Language };
   principal: { id: string; name: string };
   profession: { id: string; instructions: string };
-  model: {
-    provider: string;
-    model: string;
-    apiKeyEnv: string;
-    baseUrl: string | undefined;
-    options: Record<string, unknown> | undefined;
-  };
+  /** The model the interactive CLI runs on. Absent when the workspace is used from other agents only. */
+  model?: ModelConfig;
   tools: ToolProviderRef[];
   limits: { maxModelCalls: number; maxToolCalls: number; maxOutputTokens: number };
   debug: { persistRaw: boolean };
@@ -104,13 +112,15 @@ export function toConfig(file: ConfigFile): Config {
     company: { name: file.company.name, language: file.company.language },
     principal: { id: file.principal.id, name: file.principal.name },
     profession: { id: file.profession.id, instructions: file.profession.instructions },
-    model: {
-      provider: file.model.provider,
-      model: file.model.model,
-      apiKeyEnv: file.model.api_key_env,
-      baseUrl: file.model.base_url,
-      options: file.model.options,
-    },
+    ...(file.model && {
+      model: {
+        provider: file.model.provider,
+        model: file.model.model,
+        apiKeyEnv: file.model.api_key_env,
+        baseUrl: file.model.base_url,
+        options: file.model.options,
+      },
+    }),
     tools: file.tools.map(toToolProviderRef),
     limits: {
       maxModelCalls: file.limits.max_model_calls,

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

@@ -5,7 +5,7 @@ export {
   type ParseConfigOptions,
   parseConfig,
 } from "./config/load.ts";
-export type { Config, ToolProviderRef } from "./config/schema.ts";
+export type { Config, ModelConfig, ToolProviderRef } from "./config/schema.ts";
 export { LANGUAGES, type Language } from "./config/schema.ts";
 export { ERROR_CODES, type ErrorCode, isOpenshainError, OpenshainError } from "./errors.ts";
 export {
@@ -35,6 +35,7 @@ export {
   type ToolSummary,
 } from "./runtime.ts";
 export { jsonSchemas, type SchemaName } from "./schemas.ts";
+export { ASK_USER, RUNTIME_PROVIDER_ID } from "./tool/ask-user.ts";
 export { loadToolModule } from "./tool/load-module.ts";
 export { RESERVED_PATHS, resolveWorkspacePath } from "./tool/paths.ts";
 export {
@@ -56,6 +57,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 {
@@ -70,7 +72,9 @@ export {
   type EventType,
   eventFromFile,
   eventToFile,
+  isKnownEventType,
   type ModelUsage,
+  parsePayloadFile,
   payloadFileSchemas,
   type StopReason,
   TOOL_REJECTION_CODES,
@@ -78,6 +82,15 @@ export {
   type ToolRejectionCode,
   type UnknownEvent,
 } from "./work/events.ts";
+export {
+  countToolCalls,
+  type FailureReason,
+  type HistoryCall,
+  type PendingQuestion,
+  pendingQuestions,
+  type WorkHistory,
+  workHistory,
+} from "./work/history.ts";
 export { acquireLock, LOCK_FILE_NAME, type Lock } from "./work/lock.ts";
 export { buildProjection, type Projection, type ProjectionInput } from "./work/projection.ts";
 export {

package/src/runtime.ts

@@ -1,5 +1,5 @@
 import { loadConfig } from "./config/load.ts";
-import type { Config } from "./config/schema.ts";
+import type { Config, ModelConfig } from "./config/schema.ts";
 import { isOpenshainError, OpenshainError } from "./errors.ts";
 import type { ModelProvider } from "./model/types.ts";
 import { loadToolModule } from "./tool/load-module.ts";
@@ -12,7 +12,7 @@ import { type WorkHandle, WorkStore } from "./work/store.ts";
 
 export interface RuntimeProviders {
   /** Model providers by the id used in openshain.yaml. */
-  models: Record<string, (model: Config["model"]) => ModelProvider>;
+  models: Record<string, (model: ModelConfig) => ModelProvider>;
   /** Tool providers by the id used in openshain.yaml. Modules are loaded from the config directly. */
   tools: Record<string, () => ToolProvider>;
 }
@@ -50,6 +50,12 @@ export async function createRuntime(options: CreateRuntimeOptions): Promise<Runt
   const { workspaceRoot, providers } = options;
   const config = await loadConfig(workspaceRoot, { modelProviders: Object.keys(providers.models) });
 
+  if (!config.model) {
+    throw new OpenshainError(
+      "config",
+      "this needs a model: add a model section to openshain.yaml (only the interactive CLI needs one)",
+    );
+  }
   const modelFactory = Object.hasOwn(providers.models, config.model.provider)
     ? providers.models[config.model.provider]
     : undefined;

package/src/tool/ask-user.ts

@@ -0,0 +1,25 @@
+import { ASK_USER_TOOL_NAME, type ToolDefinition } from "./types.ts";
+
+/** The provider id the runtime records for the tools it runs itself. */
+export const RUNTIME_PROVIDER_ID = "runtime";
+
+/** The one tool the runtime itself provides: stop and ask the person. */
+export const ASK_USER: Readonly<ToolDefinition> = Object.freeze({
+  name: ASK_USER_TOOL_NAME,
+  description:
+    "Ask the person you work for a question when you cannot proceed without their answer. Use it sparingly; prefer the workspace over guessing. The work waits until the answer is recorded with work_answer.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      question: {
+        type: "string",
+        minLength: 1,
+        maxLength: 10_000,
+        description: "The question, in the person's language.",
+      },
+    },
+    required: ["question"],
+    additionalProperties: false,
+  },
+  effect: "observe",
+});

package/src/tool/types.ts

@@ -20,6 +20,8 @@ export const RESERVED_TOOL_NAMES: readonly string[] = [
   "work_list",
   "work_complete",
   "work_fail",
+  "work_answer",
+  "work_record",
   "work_run",
   "work_show",
 ];

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/events.ts

@@ -41,6 +41,7 @@ export const TOOL_REJECTION_CODES = [
   "reserved_path",
   "outside_workspace",
   "invalid_path",
+  "limit_reached",
 ] as const;
 
 export type ToolRejectionCode = (typeof TOOL_REJECTION_CODES)[number];
@@ -73,6 +74,8 @@ export interface EventPayloads {
   "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 };
+  /** A prompt command expanded for the model: its name, where it came from, and the text handed over. */
+  "prompt.expanded": { name: string; source: string; text: string };
   "usage.recorded":
     | { kind: "model_inference"; provider: string; model: string; usage: ModelUsage }
     | { kind: "tool_execution"; provider: string; usage: { durationMs: number } };
@@ -179,6 +182,7 @@ export const payloadFileSchemas = {
   "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"),
@@ -309,6 +313,22 @@ export function eventFromFile(input: unknown): AnyEvent {
   } as Event;
 }
 
+/**
+ * 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<T extends EventType>(type: T, payload: unknown): EventPayloads[T] {
+  const parsed = payloadFileSchemas[type].safeParse(payload);
+  if (!parsed.success) {
+    throw new OpenshainError("invalid_event", `${type} payload: ${describeIssues(parsed.error)}`);
+  }
+  return payloadFromFile(type, parsed.data as FilePayload<T>);
+}
+
+export function isKnownEventType(type: string): type is EventType {
+  return isKnownType(type);
+}
+
 function isKnownType(type: string): type is EventType {
   return Object.hasOwn(payloadFileSchemas, type);
 }

package/src/work/history.ts

@@ -0,0 +1,96 @@
+import type { AnyEvent, Event } 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 function countToolCalls(events: readonly AnyEvent[]): number {
+  let count = 0;
+  let started = new Set<string>();
+  for (const event of events) {
+    if (event.type === "model.completed") started = new Set();
+    else if (event.type === "tool.called") {
+      started.add((event as Event<"tool.called">).payload.callId);
+      count += 1;
+    } else if (event.type === "tool.rejected") {
+      if (!started.has((event as Event<"tool.rejected">).payload.callId)) count += 1;
+    }
+  }
+  return count;
+}
+
+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 function pendingQuestions(events: readonly AnyEvent[]): PendingQuestion[] {
+  const answered = new Set(
+    events
+      .filter((e): e is Event<"human.input_provided"> => e.type === "human.input_provided")
+      .map((e) => e.payload.callId),
+  );
+  return events
+    .filter((e): e is Event<"human.input_requested"> => e.type === "human.input_requested")
+    .filter((e) => !answered.has(e.payload.callId))
+    .map((e) => ({ callId: e.payload.callId, question: e.payload.question }));
+}
+
+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 function workHistory(events: readonly AnyEvent[]): WorkHistory {
+  const calls: HistoryCall[] = [];
+  const byId = new Map<string, HistoryCall>();
+  for (const event of events) {
+    if (event.type === "tool.called") {
+      const { callId, name, input } = (event as Event<"tool.called">).payload;
+      const path = (input as { path?: unknown } | null)?.path;
+      const call: HistoryCall = { callId, name, ...(typeof path === "string" && { path }) };
+      calls.push(call);
+      byId.set(callId, call);
+    } else if (event.type === "tool.completed") {
+      const { callId, isError } = (event as Event<"tool.completed">).payload;
+      const call = byId.get(callId);
+      if (call) call.isError = isError;
+    } else if (event.type === "tool.rejected") {
+      const { callId, name, code } = (event as Event<"tool.rejected">).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/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[] = [];
@@ -61,6 +61,9 @@ export function buildProjection(input: ProjectionInput): Projection {
       case "human.message":
         pushUserPart({ type: "text", text: (event as Event<"human.message">).payload.text });
         break;
+      case "prompt.expanded":
+        pushUserPart({ type: "text", text: (event as Event<"prompt.expanded">).payload.text });
+        break;
       case "model.completed": {
         const content = (event as Event<"model.completed">).payload.content
           .filter((part) => part.type !== "opaque" || part.provider === input.providerId)