@openshain/core 0.1.0

package/src/model/types.ts

@@ -0,0 +1,45 @@
+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/src/runtime.ts

@@ -0,0 +1,214 @@
+import { loadConfig } from "./config/load.ts";
+import type { Config } from "./config/schema.ts";
+import { isOpenshainError, OpenshainError } from "./errors.ts";
+import type { ModelProvider } from "./model/types.ts";
+import { loadToolModule } from "./tool/load-module.ts";
+import type { HiddenTool } from "./tool/registry.ts";
+import { type RegisteredTool, ToolRegistry } from "./tool/registry.ts";
+import type { ToolCall, ToolDefinition, ToolProvider, ToolResult } from "./tool/types.ts";
+import type { ToolContent } from "./work/events.ts";
+import { TOOL_REJECTION_CODES, type ToolRejectionCode } from "./work/events.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 const MAX_TOOL_TEXT_CHARS = 50_000;
+
+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 async function createRuntime(options: CreateRuntimeOptions): Promise<Runtime> {
+  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: {
+  registry: ToolRegistry;
+  config: Config;
+  workspaceRoot: string;
+}): (work: WorkHandle, call: ToolCall) => Promise<ToolResult> {
+  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: string,
+  config: Config,
+  tools: RuntimeProviders["tools"],
+): Promise<ToolRegistry> {
+  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: ToolRegistry,
+  call: ToolCall,
+): { ok: true; tool: RegisteredTool } | { ok: false; code: ToolRejectionCode; reason: string } {
+  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: {
+  registry: ToolRegistry;
+  config: Config;
+  workspaceRoot: string;
+  work: WorkHandle;
+  call: ToolCall;
+}): Promise<ToolResult> {
+  const { registry, config, workspaceRoot, work, call } = input;
+  const reject = async (code: ToolRejectionCode, reason: string): Promise<ToolResult> => {
+    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: ToolResult;
+  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: string): code is ToolRejectionCode {
+  return (TOOL_REJECTION_CODES as readonly string[]).includes(code);
+}
+
+/** Cuts a content part down to MAX_TOOL_TEXT_CHARS and says so at the end. */
+function capContent(part: ToolContent): ToolContent {
+  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/src/schemas.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { ConfigFileSchema } from "./config/schema.ts";
+import type { JsonSchema } from "./tool/types.ts";
+import { EventFileSchema, payloadFileSchemas } from "./work/events.ts";
+import { WorkFileSchema } from "./work/work.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 function jsonSchemas(): Record<SchemaName, JsonSchema> {
+  return {
+    "config.v1": describe(
+      ConfigFileSchema,
+      "openshain.yaml",
+      "The company workspace manifest as written on disk.",
+    ),
+    "events.v1": eventsSchema(),
+    "work.v1": describe(
+      WorkFileSchema,
+      "work.json",
+      "The state of a work as projected from its event log. Never the source of truth.",
+    ),
+  };
+}
+
+/**
+ * One line of events.jsonl: the strict envelope with the payload of its type. A type this
+ * version does not know is accepted with any payload, as the runtime accepts it, so that a log
+ * written by a newer runtime still validates.
+ */
+function eventsSchema(): JsonSchema {
+  const known = Object.keys(payloadFileSchemas);
+  const options = Object.entries(payloadFileSchemas).map(([type, payload]) =>
+    EventFileSchema.extend({ type: z.literal(type), payload }),
+  ) as unknown as [z.ZodObject, ...z.ZodObject[]];
+  const { $schema, oneOf } = toJsonSchema(z.discriminatedUnion("type", options)) as {
+    $schema: string;
+    oneOf: JsonSchema[];
+  };
+  const unknownType = toJsonSchema(EventFileSchema) as {
+    $schema?: string;
+    properties: Record<string, JsonSchema>;
+  };
+  delete unknownType.$schema;
+  unknownType.properties.type = { type: "string", not: { enum: known } };
+  return {
+    $schema,
+    title: "events.jsonl line",
+    description:
+      "One line of work/<id>/events.jsonl: the envelope, which is strict, and the payload of its type, which may carry fields this version does not know. An unknown type is accepted with any payload.",
+    oneOf: [...oneOf, unknownType],
+  };
+}
+
+function describe(schema: z.ZodType, title: string, description: string): JsonSchema {
+  const { $schema, ...rest } = toJsonSchema(schema);
+  return { $schema, title, description, ...rest };
+}
+
+function toJsonSchema(schema: z.ZodType): JsonSchema {
+  // The input shape: a field with a default is optional in the file, and the reader fills it in.
+  return z.toJSONSchema(schema, { target: "draft-2020-12", io: "input" }) as JsonSchema;
+}

package/src/tool/load-module.ts

@@ -0,0 +1,50 @@
+import { pathToFileURL } from "node:url";
+import { OpenshainError } from "../errors.ts";
+import { resolveWorkspacePath } from "./paths.ts";
+import type { ToolProvider } from "./types.ts";
+
+/**
+ * Loads a third-party tool provider from a module inside the workspace.
+ * The module's default export must be a ToolProvider.
+ */
+export async function loadToolModule(
+  workspaceRoot: string,
+  modulePath: string,
+): Promise<ToolProvider> {
+  let file: string;
+  try {
+    file = await resolveWorkspacePath(workspaceRoot, modulePath);
+  } catch (cause) {
+    throw new OpenshainError(
+      "config",
+      `tool module "${modulePath}" must be inside the workspace: ${(cause as Error).message}`,
+      { cause },
+    );
+  }
+  let loaded: unknown;
+  try {
+    loaded = await import(pathToFileURL(file).href);
+  } catch (cause) {
+    throw new OpenshainError(
+      "config",
+      `cannot load tool module "${modulePath}": ${(cause as Error).message}`,
+      { cause },
+    );
+  }
+  const candidate = (loaded as { default?: unknown }).default;
+  if (!isToolProvider(candidate)) {
+    throw new OpenshainError(
+      "config",
+      `tool module "${modulePath}" must default-export a ToolProvider with id, listTools and call`,
+    );
+  }
+  return candidate;
+}
+
+function isToolProvider(value: unknown): value is ToolProvider {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.id === "string" && typeof v.listTools === "function" && typeof v.call === "function"
+  );
+}

package/src/tool/paths.ts

@@ -0,0 +1,85 @@
+import { lstat, readlink, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { OpenshainError } from "../errors.ts";
+
+/** Paths the runtime keeps for itself. Tools may not read or write them. */
+export const RESERVED_PATHS = ["openshain.yaml", "work"] as const;
+
+const MAX_SYMLINK_HOPS = 32;
+
+/**
+ * Turns a tool-supplied relative path into an absolute path inside the workspace.
+ *
+ * Rejects absolute paths, `..` escapes, the reserved paths, every hidden entry
+ * (a segment starting with `.`, which covers `.git`, `.github`, `.env` and the
+ * like) and symbolic links that lead outside. Links are followed one hop at a
+ * time by reading them, so a link whose target does not exist yet is judged by
+ * where it points, not by what happens to exist. The target itself may not
+ * exist yet. Every failure is an OpenshainError.
+ *
+ * The result is a string: nothing stops the filesystem from changing between
+ * this check and the file operation. Tools that write should open with
+ * O_NOFOLLOW where the platform allows it.
+ */
+export async function resolveWorkspacePath(root: string, input: string): Promise<string> {
+  if (input === "") throw new OpenshainError("invalid_path", 'empty path: ""');
+  if (isAbsolute(input)) {
+    throw new OpenshainError("invalid_path", `absolute paths are not allowed: "${input}"`);
+  }
+  let rootReal: string;
+  try {
+    rootReal = await realpath(root);
+  } catch (cause) {
+    throw new OpenshainError("invalid_path", `workspace root is not accessible: "${root}"`, {
+      cause,
+    });
+  }
+  return walk(rootReal, normalize(input), input, 0);
+}
+
+async function walk(rootReal: string, rel: string, input: string, hops: number): Promise<string> {
+  if (rel === ".." || rel.startsWith(`..${sep}`)) {
+    throw new OpenshainError("outside_workspace", `path escapes the workspace: "${input}"`);
+  }
+  const segments = rel === "." ? [] : rel.split(sep);
+  for (const segment of segments) {
+    if (
+      segment === segments[0] &&
+      (RESERVED_PATHS as readonly string[]).includes(segment.toLowerCase())
+    ) {
+      throw new OpenshainError("reserved_path", `reserved path: "${input}"`);
+    }
+    if (segment.startsWith(".")) {
+      throw new OpenshainError("reserved_path", `hidden paths are reserved: "${input}"`);
+    }
+  }
+
+  let current = rootReal;
+  for (let i = 0; i < segments.length; i++) {
+    const candidate = join(current, segments[i] ?? "");
+    let stats: Awaited<ReturnType<typeof lstat>>;
+    try {
+      stats = await lstat(candidate);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === "ENOENT") return join(candidate, ...segments.slice(i + 1));
+      throw new OpenshainError("invalid_path", `cannot resolve "${input}": ${code ?? "error"}`, {
+        cause: err,
+      });
+    }
+    if (stats.isSymbolicLink()) {
+      if (hops >= MAX_SYMLINK_HOPS) {
+        throw new OpenshainError("invalid_path", `too many symbolic links: "${input}"`);
+      }
+      const target = resolve(dirname(candidate), await readlink(candidate));
+      const rest = segments.slice(i + 1);
+      const next = normalize(join(relative(rootReal, target) || ".", ...rest));
+      return walk(rootReal, next, input, hops + 1);
+    }
+    if (i < segments.length - 1 && !stats.isDirectory()) {
+      throw new OpenshainError("invalid_path", `not a directory: "${input}"`);
+    }
+    current = candidate;
+  }
+  return current;
+}

package/src/tool/registry.ts

@@ -0,0 +1,114 @@
+import { OpenshainError } from "../errors.ts";
+import {
+  RESERVED_TOOL_NAMES,
+  TOOL_NAME_PATTERN,
+  type ToolDefinition,
+  type ToolEffect,
+  type ToolProvider,
+} from "./types.ts";
+import { compileInputValidator, type InputValidation } from "./validate.ts";
+
+export interface RegisteredTool {
+  definition: ToolDefinition;
+  providerId: string;
+  provider: ToolProvider;
+  validate: (input: unknown) => InputValidation;
+}
+
+/** A tool a provider offers that an allow list left out. Not callable; shown so the person knows it exists. */
+export interface HiddenTool {
+  name: string;
+  providerId: string;
+  effect: ToolEffect;
+}
+
+export interface RegisterOptions {
+  /** Only these tools of the provider are registered. Every name must exist. */
+  allow?: readonly string[];
+}
+
+/** Every tool the runtime can offer, across providers. Names are unique. */
+export class ToolRegistry {
+  private readonly tools = new Map<string, RegisteredTool>();
+  private readonly hidden: HiddenTool[] = [];
+
+  async register(provider: ToolProvider, options: RegisterOptions = {}): Promise<void> {
+    const definitions = await provider.listTools();
+    const provided = new Set(definitions.map((d) => d.name));
+    for (const name of options.allow ?? []) {
+      if (!provided.has(name)) {
+        throw new OpenshainError(
+          "config",
+          `provider "${provider.id}" has no tool named "${name}"; it provides: ${[...provided].join(", ")}`,
+        );
+      }
+    }
+    const selected = options.allow
+      ? definitions.filter((d) => options.allow?.includes(d.name))
+      : definitions;
+
+    // Check everything before registering anything, so a bad provider changes nothing.
+    const prepared = new Map<string, RegisteredTool>();
+    for (const definition of selected) {
+      const { name } = definition;
+      if (!TOOL_NAME_PATTERN.test(name)) {
+        throw new OpenshainError(
+          "invalid_tool",
+          `tool name "${name}" from provider "${provider.id}" must match ${TOOL_NAME_PATTERN}`,
+        );
+      }
+      if (RESERVED_TOOL_NAMES.includes(name)) {
+        throw new OpenshainError(
+          "invalid_tool",
+          `tool name "${name}" from provider "${provider.id}" is reserved for the runtime`,
+        );
+      }
+      const existing = this.tools.get(name) ?? prepared.get(name);
+      if (existing) {
+        throw new OpenshainError(
+          "duplicate_tool",
+          `tool "${name}" is provided by both "${existing.providerId}" and "${provider.id}"`,
+        );
+      }
+      let validate: RegisteredTool["validate"];
+      try {
+        validate = compileInputValidator(definition.inputSchema);
+      } catch (cause) {
+        throw new OpenshainError(
+          "invalid_tool",
+          `tool "${name}" from provider "${provider.id}": ${(cause as Error).message}`,
+          { cause },
+        );
+      }
+      prepared.set(name, { definition, providerId: provider.id, provider, validate });
+    }
+    for (const [name, tool] of prepared) this.tools.set(name, tool);
+    for (const definition of definitions) {
+      if (!prepared.has(definition.name)) {
+        this.hidden.push({
+          name: definition.name,
+          providerId: provider.id,
+          effect: definition.effect,
+        });
+      }
+    }
+  }
+
+  /** True for a tool the provider offers but an allow list left out. */
+  isHidden(name: string): boolean {
+    return !this.tools.has(name) && this.hidden.some((h) => h.name === name);
+  }
+
+  /** Tools that providers offer but allow lists left out. */
+  hiddenTools(): HiddenTool[] {
+    return this.hidden.filter((h) => !this.tools.has(h.name)).map((h) => ({ ...h }));
+  }
+
+  list(): RegisteredTool[] {
+    return [...this.tools.values()];
+  }
+
+  get(name: string): RegisteredTool | undefined {
+    return this.tools.get(name);
+  }
+}

package/src/tool/types.ts

@@ -0,0 +1,61 @@
+import type { WorkId } from "../ids.ts";
+import type { Artifact, ToolContent } from "../work/events.ts";
+
+/** A JSON Schema (draft 2020-12) object. Validated by ajv at registration. */
+export type JsonSchema = Record<string, unknown>;
+
+export type ToolEffect = "observe" | "mutate";
+
+export const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+
+/** The tool the runtime itself provides. No provider may define it. */
+export const ASK_USER_TOOL_NAME = "ask_user";
+
+/** Names no provider may use: the runtime's own tool and the MCP server's work tools. */
+export const RESERVED_TOOL_NAMES: readonly string[] = [
+  ASK_USER_TOOL_NAME,
+  "work_create",
+  "work_select",
+  "work_get",
+  "work_list",
+  "work_complete",
+  "work_fail",
+  "work_run",
+  "work_show",
+];
+
+export interface ToolDefinition {
+  /** Unique across all providers. Matches TOOL_NAME_PATTERN. */
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+  effect: ToolEffect;
+}
+
+export interface ToolCall {
+  id: string;
+  name: string;
+  input: unknown;
+}
+
+export interface ToolContext {
+  workId: WorkId;
+  principalId: string;
+  workspaceRoot: string;
+  signal?: AbortSignal;
+}
+
+export interface ToolResult {
+  content: ToolContent[];
+  isError?: boolean;
+  /** Where the observation came from and when it was retrieved. */
+  observation?: { source: string; retrievedAt: string };
+  /** For mutate tools: the files as they are after the call. */
+  after?: Artifact[];
+}
+
+export interface ToolProvider {
+  readonly id: string;
+  listTools(): Promise<ToolDefinition[]>;
+  call(call: ToolCall, ctx: ToolContext): Promise<ToolResult>;
+}