@openshain/core 0.2.0 → 0.3.1

package/dist/config/load.js

@@ -56,7 +56,7 @@ export function parseConfig(text, options = {}) {
         throw new OpenshainError("config", problems.join("\n"));
     }
     const known = options.modelProviders;
-    if (known && !known.includes(result.data.model.provider)) {
+    if (known && result.data.model && !known.includes(result.data.model.provider)) {
         throw new OpenshainError("config", problem(["model", "provider"], `unknown provider "${result.data.model.provider}"; known providers: ${known.length > 0 ? known.join(", ") : "none"}`));
     }
     return toConfig(result.data);

package/dist/config/schema.d.ts

@@ -20,13 +20,13 @@ export declare const ConfigFileSchema: z.ZodObject<{
         id: z.ZodString;
         instructions: z.ZodString;
     }, z.core.$strict>;
-    model: z.ZodObject<{
+    model: z.ZodOptional<z.ZodObject<{
         provider: z.ZodString;
         model: z.ZodString;
         api_key_env: z.ZodString;
         base_url: z.ZodOptional<z.ZodURL>;
         options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strict>;
+    }, z.core.$strict>>;
     tools: z.ZodDefault<z.ZodArray<z.ZodObject<{
         provider: z.ZodOptional<z.ZodString>;
         module: z.ZodOptional<z.ZodString>;
@@ -50,6 +50,14 @@ export type ToolProviderRef = {
     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: {
@@ -64,13 +72,8 @@ export interface Config {
         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;

package/dist/config/schema.js

@@ -38,7 +38,8 @@ 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({
+    model: z
+        .strictObject({
         provider: identifier,
         model: z.string().min(1).max(200),
         api_key_env: envVarName,
@@ -50,11 +51,12 @@ export const ConfigFileSchema = z.strictObject({
         }, "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));
+            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({
@@ -71,13 +73,15 @@ export function toConfig(file) {
         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/dist/index.d.ts

@@ -1,11 +1,12 @@
 export { CONFIG_FILE_NAME, loadConfig, 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 { type EventId, newEventId, newWorkId, parseEventId, parseWorkId, type WorkId, } from "./ids.ts";
 export type { ModelDescription, ModelMessage, ModelProvider, ModelRequest, ModelResponse, UserPart, } from "./model/types.ts";
 export { type CreateRuntimeOptions, createRuntime, createToolCaller, createToolRegistry, MAX_TOOL_TEXT_CHARS, type Runtime, type RuntimeProviders, 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 { type HiddenTool, type RegisteredTool, type RegisterOptions, ToolRegistry, } from "./tool/registry.ts";
@@ -14,7 +15,8 @@ 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 { type AnyEvent, type Artifact, type AssistantPart, canonical, type Event, type EventFile, EventFileSchema, type EventPayloads, type EventType, eventFromFile, eventToFile, type ModelUsage, payloadFileSchemas, type StopReason, TOOL_REJECTION_CODES, type ToolContent, type ToolRejectionCode, type UnknownEvent, } from "./work/events.ts";
+export { type AnyEvent, type Artifact, type AssistantPart, canonical, type Event, type EventFile, EventFileSchema, type EventPayloads, type EventType, eventFromFile, eventToFile, isKnownEventType, type ModelUsage, parsePayloadFile, payloadFileSchemas, type StopReason, TOOL_REJECTION_CODES, type ToolContent, 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 { type CreateWorkInput, type ListResult, WORK_DIR_NAME, WORK_FILE_NAME, type WorkHandle, WorkStore, } from "./work/store.ts";

package/dist/index.js

@@ -5,6 +5,7 @@ export { ERROR_CODES, isOpenshainError, OpenshainError } from "./errors.js";
 export { newEventId, newWorkId, parseEventId, parseWorkId, } from "./ids.js";
 export { createRuntime, createToolCaller, createToolRegistry, MAX_TOOL_TEXT_CHARS, } from "./runtime.js";
 export { jsonSchemas } from "./schemas.js";
+export { ASK_USER, RUNTIME_PROVIDER_ID } from "./tool/ask-user.js";
 export { loadToolModule } from "./tool/load-module.js";
 export { RESERVED_PATHS, resolveWorkspacePath } from "./tool/paths.js";
 export { ToolRegistry, } from "./tool/registry.js";
@@ -13,7 +14,8 @@ export { compileInputValidator } from "./tool/validate.js";
 export { uuidv7 } from "./uuid.js";
 export { verifyArtifact } from "./work/artifacts.js";
 export { EVENTS_FILE_NAME, EventLog } from "./work/event-log.js";
-export { canonical, EventFileSchema, eventFromFile, eventToFile, payloadFileSchemas, TOOL_REJECTION_CODES, } from "./work/events.js";
+export { canonical, EventFileSchema, eventFromFile, eventToFile, isKnownEventType, parsePayloadFile, payloadFileSchemas, TOOL_REJECTION_CODES, } from "./work/events.js";
+export { countToolCalls, pendingQuestions, workHistory, } from "./work/history.js";
 export { acquireLock, LOCK_FILE_NAME } from "./work/lock.js";
 export { buildProjection } from "./work/projection.js";
 export { WORK_DIR_NAME, WORK_FILE_NAME, WorkStore, } from "./work/store.js";

package/dist/runtime.d.ts

@@ -1,4 +1,4 @@
-import type { Config } from "./config/schema.ts";
+import type { Config, ModelConfig } from "./config/schema.ts";
 import type { ModelProvider } from "./model/types.ts";
 import type { HiddenTool } from "./tool/registry.ts";
 import { ToolRegistry } from "./tool/registry.ts";
@@ -6,7 +6,7 @@ import type { ToolCall, ToolDefinition, ToolProvider, ToolResult } from "./tool/
 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>;
 }

package/dist/runtime.js

@@ -10,6 +10,9 @@ export const MAX_TOOL_TEXT_CHARS = 50_000;
 export async function createRuntime(options) {
     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/dist/tool/ask-user.d.ts

@@ -0,0 +1,5 @@
+import { type ToolDefinition } from "./types.ts";
+/** The provider id the runtime records for the tools it runs itself. */
+export declare const RUNTIME_PROVIDER_ID = "runtime";
+/** The one tool the runtime itself provides: stop and ask the person. */
+export declare const ASK_USER: Readonly<ToolDefinition>;

package/dist/tool/ask-user.js

@@ -0,0 +1,22 @@
+import { ASK_USER_TOOL_NAME } from "./types.js";
+/** 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 = 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/dist/tool/types.js

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

package/dist/work/events.d.ts

@@ -43,7 +43,7 @@ export interface ModelUsage {
     /** The part of outputTokens spent on reasoning. */
     reasoningTokens?: number;
 }
-export declare const TOOL_REJECTION_CODES: readonly ["schema_mismatch", "unknown_tool", "not_allowed", "reserved_path", "outside_workspace", "invalid_path"];
+export declare const TOOL_REJECTION_CODES: readonly ["schema_mismatch", "unknown_tool", "not_allowed", "reserved_path", "outside_workspace", "invalid_path", "limit_reached"];
 export type ToolRejectionCode = (typeof TOOL_REJECTION_CODES)[number];
 export interface EventPayloads {
     "work.created": {
@@ -110,6 +110,12 @@ export interface EventPayloads {
     "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;
@@ -233,6 +239,7 @@ export declare const payloadFileSchemas: {
         name: z.ZodString;
         code: z.ZodEnum<{
             invalid_path: "invalid_path";
+            limit_reached: "limit_reached";
             not_allowed: "not_allowed";
             outside_workspace: "outside_workspace";
             reserved_path: "reserved_path";
@@ -252,6 +259,11 @@ export declare const payloadFileSchemas: {
     "human.message": z.ZodObject<{
         text: z.ZodString;
     }, z.core.$loose>;
+    "prompt.expanded": z.ZodObject<{
+        name: z.ZodString;
+        source: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$loose>;
     "usage.recorded": z.ZodDiscriminatedUnion<[z.ZodObject<{
         kind: z.ZodLiteral<"model_inference">;
         provider: z.ZodString;
@@ -308,4 +320,10 @@ export declare function eventToFile(event: AnyEvent): EventFile;
  */
 export declare function canonical(value: unknown, insideData?: boolean, seen?: WeakSet<object>): unknown;
 export declare function eventFromFile(input: unknown): AnyEvent;
+/**
+ * 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 declare function parsePayloadFile<T extends EventType>(type: T, payload: unknown): EventPayloads[T];
+export declare function isKnownEventType(type: string): type is EventType;
 export {};

package/dist/work/events.js

@@ -7,6 +7,7 @@ export const TOOL_REJECTION_CODES = [
     "reserved_path",
     "outside_workspace",
     "invalid_path",
+    "limit_reached",
 ];
 // ---------------------------------------------------------------------------
 // File-side schemas (snake_case). These are the on-disk contract.
@@ -83,6 +84,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"),
@@ -202,6 +204,20 @@ export function eventFromFile(input) {
         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);
 }

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/projection.js

@@ -39,6 +39,9 @@ export function buildProjection(input) {
             case "human.message":
                 pushUserPart({ type: "text", text: event.payload.text });
                 break;
+            case "prompt.expanded":
+                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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openshain/core",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Contracts (provider interfaces), fundamental objects, and the work runtime",
   "keywords": [
     "openshain",

package/src/config/load.ts

@@ -70,7 +70,7 @@ export function parseConfig(text: string, options: ParseConfigOptions = {}): Con
   }
 
   const known = options.modelProviders;
-  if (known && !known.includes(result.data.model.provider)) {
+  if (known && result.data.model && !known.includes(result.data.model.provider)) {
     throw new OpenshainError(
       "config",
       problem(

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/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 {
@@ -71,7 +72,9 @@ export {
   type EventType,
   eventFromFile,
   eventToFile,
+  isKnownEventType,
   type ModelUsage,
+  parsePayloadFile,
   payloadFileSchemas,
   type StopReason,
   TOOL_REJECTION_CODES,
@@ -79,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/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

@@ -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)