@openshain/core 0.1.0 → 0.2.0

package/dist/config/load.d.ts

@@ -0,0 +1,10 @@
+import { type Config } from "./schema.ts";
+export declare const CONFIG_FILE_NAME = "openshain.yaml";
+export interface ParseConfigOptions {
+    /** Provider ids the runtime can construct. When given, other names are rejected. */
+    modelProviders?: readonly string[];
+    /** Name used in error messages. Defaults to openshain.yaml. */
+    fileName?: string;
+}
+export declare function loadConfig(workspaceRoot: string, options?: Omit<ParseConfigOptions, "fileName">): Promise<Config>;
+export declare function parseConfig(text: string, options?: ParseConfigOptions): Config;

package/dist/config/load.js

@@ -0,0 +1,66 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isNode, LineCounter, parseDocument } from "yaml";
+import { OpenshainError } from "../errors.js";
+import { ConfigFileSchema, toConfig } from "./schema.js";
+export const CONFIG_FILE_NAME = "openshain.yaml";
+export async function loadConfig(workspaceRoot, options = {}) {
+    const fileName = join(workspaceRoot, CONFIG_FILE_NAME);
+    let text;
+    try {
+        text = await readFile(fileName, "utf8");
+    }
+    catch (cause) {
+        throw new OpenshainError("config", `${CONFIG_FILE_NAME} not found in ${workspaceRoot}`, {
+            cause,
+        });
+    }
+    return parseConfig(text, { ...options, fileName });
+}
+export function parseConfig(text, options = {}) {
+    const fileName = options.fileName ?? CONFIG_FILE_NAME;
+    const lineCounter = new LineCounter();
+    let doc;
+    let data;
+    try {
+        doc = parseDocument(text, { lineCounter });
+        data = doc.errors.length > 0 ? undefined : doc.toJS();
+    }
+    catch (cause) {
+        // yaml refuses resource-exhaustion documents (alias bombs) with a plain error
+        throw new OpenshainError("config", `${fileName}: ${cause.message}`, { cause });
+    }
+    if (doc.errors.length > 0) {
+        const lines = doc.errors.map((error) => {
+            const pos = error.linePos?.[0] ?? { line: 0, col: 0 };
+            return `${fileName}:${pos.line}:${pos.col} ${firstLine(error.message)}`;
+        });
+        throw new OpenshainError("config", lines.join("\n"));
+    }
+    const locate = (path) => {
+        for (let i = path.length; i >= 0; i--) {
+            const node = i === 0 ? doc.contents : doc.getIn(path.slice(0, i), true);
+            if (isNode(node) && node.range)
+                return lineCounter.linePos(node.range[0]);
+        }
+        return { line: 1, col: 1 };
+    };
+    const problem = (path, message) => {
+        const { line, col } = locate(path);
+        const where = path.length === 0 ? "<root>" : path.map(String).join(".");
+        return `${fileName}:${line}:${col} ${where}: ${message}`;
+    };
+    const result = ConfigFileSchema.safeParse(data);
+    if (!result.success) {
+        const problems = result.error.issues.map((issue) => problem(issue.path, issue.message));
+        throw new OpenshainError("config", problems.join("\n"));
+    }
+    const known = options.modelProviders;
+    if (known && !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);
+}
+function firstLine(message) {
+    return message.split("\n", 1)[0] ?? message;
+}

package/dist/config/schema.d.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+/** Shape of openshain.yaml as written on disk (snake_case). */
+/** The languages the product has words and names for. */
+export declare const LANGUAGES: readonly ["ja", "en"];
+export type Language = (typeof LANGUAGES)[number];
+export declare const ConfigFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    company: z.ZodObject<{
+        name: z.ZodString;
+        language: z.ZodDefault<z.ZodEnum<{
+            en: "en";
+            ja: "ja";
+        }>>;
+    }, z.core.$strict>;
+    principal: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>;
+    profession: z.ZodObject<{
+        id: z.ZodString;
+        instructions: z.ZodString;
+    }, z.core.$strict>;
+    model: 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>;
+    tools: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        provider: z.ZodOptional<z.ZodString>;
+        module: z.ZodOptional<z.ZodString>;
+        allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    limits: z.ZodPrefault<z.ZodObject<{
+        max_model_calls: z.ZodDefault<z.ZodInt>;
+        max_tool_calls: z.ZodDefault<z.ZodInt>;
+        max_output_tokens: z.ZodDefault<z.ZodInt>;
+    }, z.core.$strict>>;
+    debug: z.ZodPrefault<z.ZodObject<{
+        persist_raw: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ConfigFile = z.infer<typeof ConfigFileSchema>;
+export type ToolProviderRef = {
+    provider: string;
+    allow: readonly string[] | undefined;
+} | {
+    module: string;
+    allow: readonly string[] | undefined;
+};
+/** Configuration as used in code (camelCase). */
+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;
+    };
+    tools: ToolProviderRef[];
+    limits: {
+        maxModelCalls: number;
+        maxToolCalls: number;
+        maxOutputTokens: number;
+    };
+    debug: {
+        persistRaw: boolean;
+    };
+}
+export declare function toConfig(file: ConfigFile): Config;

package/dist/config/schema.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+const identifier = z
+    .string()
+    .regex(/^[a-z][a-z0-9_-]*$/, "use lowercase letters, digits, _ or -, starting with a letter");
+const envVarName = z
+    .string()
+    .regex(/^[A-Z][A-Z0-9_]*$/, "environment variable names are UPPER_SNAKE_CASE");
+const toolName = z
+    .string()
+    .regex(/^[a-z][a-z0-9_]*$/, "tool names use lowercase letters, digits and _");
+// One strict object instead of a union: zod reports union failures at the union
+// itself, which would hide the exact line of a bad `allow` entry.
+const toolProviderRef = z
+    .strictObject({
+    provider: identifier.optional(),
+    module: z.string().min(1).optional(),
+    allow: z.array(toolName).optional(),
+})
+    .refine((entry) => (entry.provider === undefined) !== (entry.module === undefined), {
+    message: "name exactly one of provider or module",
+});
+/** Hosts that stay on this machine, where an API key may travel without TLS. */
+function isLoopback(hostname) {
+    return (hostname === "localhost" ||
+        hostname.endsWith(".localhost") ||
+        /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname) ||
+        hostname === "[::1]" ||
+        hostname === "::1");
+}
+/** Shape of openshain.yaml as written on disk (snake_case). */
+/** The languages the product has words and names for. */
+export const LANGUAGES = ["ja", "en"];
+export const ConfigFileSchema = z.strictObject({
+    version: z.literal(1),
+    company: z.strictObject({
+        name: z.string().min(1).max(200),
+        language: z.enum(LANGUAGES).default("ja"),
+    }),
+    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(),
+    }),
+    tools: z.array(toolProviderRef).default([{ provider: "standard" }]),
+    limits: z
+        .strictObject({
+        max_model_calls: z.int().positive().default(30),
+        max_tool_calls: z.int().positive().default(100),
+        max_output_tokens: z.int().positive().default(16000),
+    })
+        .prefault({}),
+    debug: z.strictObject({ persist_raw: z.boolean().default(false) }).prefault({}),
+});
+export function toConfig(file) {
+    return {
+        version: file.version,
+        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,
+        },
+        tools: file.tools.map(toToolProviderRef),
+        limits: {
+            maxModelCalls: file.limits.max_model_calls,
+            maxToolCalls: file.limits.max_tool_calls,
+            maxOutputTokens: file.limits.max_output_tokens,
+        },
+        debug: { persistRaw: file.debug.persist_raw },
+    };
+}
+function toToolProviderRef(entry) {
+    if (entry.provider !== undefined)
+        return { provider: entry.provider, allow: entry.allow };
+    if (entry.module !== undefined)
+        return { module: entry.module, allow: entry.allow };
+    throw new Error("unreachable: the schema requires provider or module");
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+export declare const ERROR_CODES: readonly ["auth", "network", "rate_limit", "invalid_response", "config", "corrupt_log", "invalid_transition", "duplicate_tool", "invalid_id", "invalid_tool", "invalid_path", "lock_held", "not_found", "reserved_path", "outside_workspace", "concurrent_write", "invalid_event"];
+export type ErrorCode = (typeof ERROR_CODES)[number];
+export declare class OpenshainError extends Error {
+    readonly name = "OpenshainError";
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function isOpenshainError(value: unknown): value is OpenshainError;

package/dist/errors.js

@@ -0,0 +1,30 @@
+export const ERROR_CODES = [
+    "auth",
+    "network",
+    "rate_limit",
+    "invalid_response",
+    "config",
+    "corrupt_log",
+    "invalid_transition",
+    "duplicate_tool",
+    "invalid_id",
+    "invalid_tool",
+    "invalid_path",
+    "lock_held",
+    "not_found",
+    "reserved_path",
+    "outside_workspace",
+    "concurrent_write",
+    "invalid_event",
+];
+export class OpenshainError extends Error {
+    name = "OpenshainError";
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+export function isOpenshainError(value) {
+    return value instanceof OpenshainError;
+}

package/dist/ids.d.ts

@@ -0,0 +1,11 @@
+declare const brand: unique symbol;
+type Brand<T, Name extends string> = T & {
+    readonly [brand]: Name;
+};
+export type WorkId = Brand<string, "WorkId">;
+export type EventId = Brand<string, "EventId">;
+export declare function newWorkId(): WorkId;
+export declare function newEventId(): EventId;
+export declare function parseWorkId(value: string): WorkId;
+export declare function parseEventId(value: string): EventId;
+export {};

package/dist/ids.js

@@ -0,0 +1,21 @@
+import { OpenshainError } from "./errors.js";
+import { uuidv7 } from "./uuid.js";
+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() {
+    return `work_${uuidv7()}`;
+}
+export function newEventId() {
+    return `evt_${uuidv7()}`;
+}
+export function parseWorkId(value) {
+    return parseId(value, "work_");
+}
+export function parseEventId(value) {
+    return parseId(value, "evt_");
+}
+function parseId(value, prefix) {
+    if (!value.startsWith(prefix) || !UUID_V7.test(value.slice(prefix.length))) {
+        throw new OpenshainError("invalid_id", `expected ${prefix}<uuid v7>, got "${value}"`);
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export { CONFIG_FILE_NAME, loadConfig, type ParseConfigOptions, parseConfig, } from "./config/load.ts";
+export type { Config, 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 { 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";
+export { ASK_USER_TOOL_NAME, type JsonSchema, RESERVED_TOOL_NAMES, TOOL_NAME_PATTERN, type ToolCall, type ToolContext, type ToolDefinition, type ToolEffect, type ToolProvider, 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 { 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 { 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";
+export { isTerminal, reduceWork, SESSION_WORK_TYPE, transition, WORK_STATUSES, type Work, type WorkFile, WorkFileSchema, WorkStatus, workToFile, } from "./work/work.ts";

package/dist/index.js

@@ -0,0 +1,20 @@
+// @openshain/core: Contracts (provider interfaces), fundamental objects, and the work runtime
+export { CONFIG_FILE_NAME, loadConfig, parseConfig, } from "./config/load.js";
+export { LANGUAGES } from "./config/schema.js";
+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 { loadToolModule } from "./tool/load-module.js";
+export { RESERVED_PATHS, resolveWorkspacePath } from "./tool/paths.js";
+export { ToolRegistry, } from "./tool/registry.js";
+export { ASK_USER_TOOL_NAME, RESERVED_TOOL_NAMES, TOOL_NAME_PATTERN, } from "./tool/types.js";
+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 { 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";
+export { isTerminal, reduceWork, SESSION_WORK_TYPE, transition, WORK_STATUSES, WorkFileSchema, WorkStatus, workToFile, } from "./work/work.js";

package/dist/model/types.d.ts

@@ -0,0 +1,57 @@
+import type { ToolDefinition } from "../tool/types.ts";
+import type { AssistantPart, ModelUsage, StopReason } from "../work/events.ts";
+export type UserPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_result";
+    callId: string;
+    content: string;
+    isError?: boolean;
+};
+export type ModelMessage = {
+    role: "user";
+    content: UserPart[];
+} | {
+    role: "assistant";
+    content: AssistantPart[];
+};
+export interface ModelRequest {
+    system?: string;
+    messages: ModelMessage[];
+    tools?: ToolDefinition[];
+    maxOutputTokens?: number;
+    /** Passed to the provider as is. The contract does not interpret it. */
+    providerOptions?: Record<string, unknown>;
+    /** How many model and tool calls the work may still make. Providers may ignore it. */
+    budget?: {
+        modelCallsLeft: number;
+        toolCallsLeft: number;
+    };
+    /** How many leading messages will be sent unchanged next turn. A provider may anchor a prompt cache after them. */
+    stableMessages?: number;
+}
+export interface ModelResponse {
+    message: {
+        role: "assistant";
+        content: AssistantPart[];
+    };
+    stopReason: StopReason;
+    usage: ModelUsage;
+    /** The provider's native response, for debugging only. Not persisted by default. */
+    raw?: unknown;
+}
+export interface ModelDescription {
+    /** For display and error messages. The id the log records is ModelProvider.id. */
+    provider: string;
+    model: string;
+    capabilities: {
+        tools: boolean;
+    };
+}
+export interface ModelProvider {
+    /** Recorded in the log and used to route opaque parts back. Stable across the provider's models. */
+    readonly id: string;
+    describe(): ModelDescription;
+    generate(request: ModelRequest, signal?: AbortSignal): Promise<ModelResponse>;
+}

package/dist/runtime.d.ts

@@ -0,0 +1,46 @@
+import type { Config } from "./config/schema.ts";
+import type { ModelProvider } from "./model/types.ts";
+import type { HiddenTool } from "./tool/registry.ts";
+import { ToolRegistry } from "./tool/registry.ts";
+import type { ToolCall, ToolDefinition, ToolProvider, ToolResult } from "./tool/types.ts";
+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>;
+    /** Tool providers by the id used in openshain.yaml. Modules are loaded from the config directly. */
+    tools: Record<string, () => ToolProvider>;
+}
+export interface CreateRuntimeOptions {
+    workspaceRoot: string;
+    providers: RuntimeProviders;
+}
+/** What the outside world learns about a registered tool. Calls go through runtime.tools.call. */
+export interface ToolSummary {
+    definition: ToolDefinition;
+    providerId: string;
+}
+/** Longer tool output is cut here so that one tool cannot flood the model's context. */
+export declare const MAX_TOOL_TEXT_CHARS = 50000;
+export interface Runtime {
+    readonly workspaceRoot: string;
+    readonly config: Config;
+    readonly model: ModelProvider;
+    readonly works: WorkStore;
+    readonly tools: {
+        list(): ToolSummary[];
+        /** Tools the providers offer but the allow lists in the config left out. */
+        hidden(): HiddenTool[];
+        /** Validates, runs and records one tool call for the given work. Never throws for a tool's own failure. */
+        call(work: WorkHandle, call: ToolCall): Promise<ToolResult>;
+    };
+}
+/** Builds a runtime for one workspace from its config and the providers the caller knows. */
+export declare function createRuntime(options: CreateRuntimeOptions): Promise<Runtime>;
+/** The tool call pipeline on its own: authorize, validate, run, record. For callers that need no model, such as the MCP server. */
+export declare function createToolCaller(input: {
+    registry: ToolRegistry;
+    config: Config;
+    workspaceRoot: string;
+}): (work: WorkHandle, call: ToolCall) => Promise<ToolResult>;
+/** Registers the tool providers the config names: the caller's factories by id, and modules from the workspace. Needs no model. */
+export declare function createToolRegistry(workspaceRoot: string, config: Config, tools: RuntimeProviders["tools"]): Promise<ToolRegistry>;

package/dist/runtime.js

@@ -0,0 +1,144 @@
+import { loadConfig } from "./config/load.js";
+import { isOpenshainError, OpenshainError } from "./errors.js";
+import { loadToolModule } from "./tool/load-module.js";
+import { ToolRegistry } from "./tool/registry.js";
+import { TOOL_REJECTION_CODES } from "./work/events.js";
+import { WorkStore } from "./work/store.js";
+/** Longer tool output is cut here so that one tool cannot flood the model's context. */
+export const MAX_TOOL_TEXT_CHARS = 50_000;
+/** Builds a runtime for one workspace from its config and the providers the caller knows. */
+export async function createRuntime(options) {
+    const { workspaceRoot, providers } = options;
+    const config = await loadConfig(workspaceRoot, { modelProviders: Object.keys(providers.models) });
+    const modelFactory = Object.hasOwn(providers.models, config.model.provider)
+        ? providers.models[config.model.provider]
+        : undefined;
+    if (!modelFactory) {
+        throw new OpenshainError("config", `unknown model provider "${config.model.provider}"`);
+    }
+    const model = modelFactory(config.model);
+    const description = model.describe();
+    if (!description.capabilities.tools) {
+        throw new OpenshainError("config", `model ${description.provider}/${description.model} cannot call tools; openshain needs a model with tool support`);
+    }
+    const registry = await createToolRegistry(workspaceRoot, config, providers.tools);
+    const works = new WorkStore(workspaceRoot);
+    return {
+        workspaceRoot,
+        config,
+        model,
+        works,
+        tools: {
+            list: () => registry.list().map(({ definition, providerId }) => ({ definition, providerId })),
+            hidden: () => registry.hiddenTools(),
+            call: createToolCaller({ registry, config, workspaceRoot }),
+        },
+    };
+}
+/** The tool call pipeline on its own: authorize, validate, run, record. For callers that need no model, such as the MCP server. */
+export function createToolCaller(input) {
+    return (work, call) => callTool({ ...input, work, call });
+}
+/** Registers the tool providers the config names: the caller's factories by id, and modules from the workspace. Needs no model. */
+export async function createToolRegistry(workspaceRoot, config, tools) {
+    const registry = new ToolRegistry();
+    for (const entry of config.tools) {
+        const registerOptions = entry.allow ? { allow: entry.allow } : {};
+        if ("provider" in entry) {
+            const factory = Object.hasOwn(tools, entry.provider) ? tools[entry.provider] : undefined;
+            if (!factory) {
+                throw new OpenshainError("config", `unknown tool provider "${entry.provider}"; known providers: ${Object.keys(tools).join(", ")}`);
+            }
+            await registry.register(factory(), registerOptions);
+        }
+        else {
+            await registry.register(await loadToolModule(workspaceRoot, entry.module), registerOptions);
+        }
+    }
+    return registry;
+}
+/**
+ * The one place that allows or refuses a call before it runs. At this stage it knows only
+ * the allow lists; a later authority engine plugs in here.
+ */
+function authorize(registry, call) {
+    const tool = registry.get(call.name);
+    if (tool)
+        return { ok: true, tool };
+    return registry.isHidden(call.name)
+        ? {
+            ok: false,
+            code: "not_allowed",
+            reason: `tool "${call.name}" is not allowed in this workspace`,
+        }
+        : { ok: false, code: "unknown_tool", reason: `unknown tool "${call.name}"` };
+}
+async function callTool(input) {
+    const { registry, config, workspaceRoot, work, call } = input;
+    const reject = async (code, reason) => {
+        await work.append({
+            type: "tool.rejected",
+            payload: { callId: call.id, name: call.name, code, reason },
+        });
+        return { content: [{ type: "text", text: reason }], isError: true };
+    };
+    const decision = authorize(registry, call);
+    if (!decision.ok)
+        return reject(decision.code, decision.reason);
+    const { tool } = decision;
+    const validation = tool.validate(call.input);
+    if (!validation.ok) {
+        return reject("schema_mismatch", `input does not match the schema of ${call.name}: ${validation.reason}`);
+    }
+    await work.append({
+        type: "tool.called",
+        payload: { callId: call.id, provider: tool.providerId, name: call.name, input: call.input },
+    });
+    const started = performance.now();
+    let result;
+    try {
+        result = await tool.provider.call(call, {
+            workId: work.id,
+            principalId: config.principal.id,
+            workspaceRoot,
+        });
+    }
+    catch (err) {
+        if (isOpenshainError(err) && isRejectionCode(err.code))
+            return reject(err.code, err.message);
+        const message = err instanceof Error ? err.message : String(err);
+        result = { content: [{ type: "text", text: message }], isError: true };
+    }
+    const durationMs = Math.max(0, Math.round(performance.now() - started));
+    result = { ...result, content: result.content.map(capContent) };
+    await work.append({
+        type: "tool.completed",
+        payload: {
+            callId: call.id,
+            content: result.content,
+            isError: result.isError ?? false,
+            ...(result.observation && { observation: result.observation }),
+            ...(result.after && { after: result.after }),
+        },
+    });
+    await work.append({
+        type: "usage.recorded",
+        payload: { kind: "tool_execution", provider: tool.providerId, usage: { durationMs } },
+    });
+    return result;
+}
+function isRejectionCode(code) {
+    return TOOL_REJECTION_CODES.includes(code);
+}
+/** Cuts a content part down to MAX_TOOL_TEXT_CHARS and says so at the end. */
+function capContent(part) {
+    const text = part.type === "text" ? part.text : JSON.stringify(part.value);
+    const chars = [...text];
+    if (chars.length <= MAX_TOOL_TEXT_CHARS)
+        return part;
+    const cut = chars.length - MAX_TOOL_TEXT_CHARS;
+    return {
+        type: "text",
+        text: `${chars.slice(0, MAX_TOOL_TEXT_CHARS).join("")}\n…[${cut} characters cut by the runtime]`,
+    };
+}

package/dist/schemas.d.ts

@@ -0,0 +1,9 @@
+import type { JsonSchema } from "./tool/types.ts";
+export type SchemaName = "config.v1" | "events.v1" | "work.v1";
+/**
+ * The JSON Schemas (draft 2020-12) of the files openshain reads and writes, derived from the zod
+ * schemas that validate them. `spec/schemas/` holds this output; `bun run schemas` regenerates it.
+ * Conditions zod expresses as refinements, such as "provider or module, not both", have no JSON
+ * Schema form and are absent here.
+ */
+export declare function jsonSchemas(): Record<SchemaName, JsonSchema>;