@openshain/core 0.1.0 → 0.2.0

package/dist/schemas.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { ConfigFileSchema } from "./config/schema.js";
+import { EventFileSchema, payloadFileSchemas } from "./work/events.js";
+import { WorkFileSchema } from "./work/work.js";
+/**
+ * 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() {
+    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() {
+    const known = Object.keys(payloadFileSchemas);
+    const options = Object.entries(payloadFileSchemas).map(([type, payload]) => EventFileSchema.extend({ type: z.literal(type), payload }));
+    const { $schema, oneOf } = toJsonSchema(z.discriminatedUnion("type", options));
+    const unknownType = toJsonSchema(EventFileSchema);
+    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, title, description) {
+    const { $schema, ...rest } = toJsonSchema(schema);
+    return { $schema, title, description, ...rest };
+}
+function toJsonSchema(schema) {
+    // 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" });
+}

package/dist/tool/load-module.d.ts

@@ -0,0 +1,6 @@
+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 declare function loadToolModule(workspaceRoot: string, modulePath: string): Promise<ToolProvider>;

package/dist/tool/load-module.js

@@ -0,0 +1,42 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { pathToFileURL } from "node:url";
+import { OpenshainError } from "../errors.js";
+import { resolveWorkspacePath } from "./paths.js";
+/**
+ * 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, modulePath) {
+    let file;
+    try {
+        file = await resolveWorkspacePath(workspaceRoot, modulePath);
+    }
+    catch (cause) {
+        throw new OpenshainError("config", `tool module "${modulePath}" must be inside the workspace: ${cause.message}`, { cause });
+    }
+    let loaded;
+    try {
+        loaded = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    }
+    catch (cause) {
+        throw new OpenshainError("config", `cannot load tool module "${modulePath}": ${cause.message}`, { cause });
+    }
+    const candidate = loaded.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) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.id === "string" && typeof v.listTools === "function" && typeof v.call === "function");
+}

package/dist/tool/paths.d.ts

@@ -0,0 +1,17 @@
+/** Paths the runtime keeps for itself. Tools may not read or write them. */
+export declare const RESERVED_PATHS: readonly ["openshain.yaml", "work"];
+/**
+ * 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 declare function resolveWorkspacePath(root: string, input: string): Promise<string>;

package/dist/tool/paths.js

@@ -0,0 +1,82 @@
+import { lstat, readlink, realpath } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import { OpenshainError } from "../errors.js";
+/** Paths the runtime keeps for itself. Tools may not read or write them. */
+export const RESERVED_PATHS = ["openshain.yaml", "work"];
+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, input) {
+    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;
+    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, rel, input, hops) {
+    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.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;
+        try {
+            stats = await lstat(candidate);
+        }
+        catch (err) {
+            const code = err.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/dist/tool/registry.d.ts

@@ -0,0 +1,30 @@
+import { type ToolDefinition, type ToolEffect, type ToolProvider } from "./types.ts";
+import { 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 declare class ToolRegistry {
+    private readonly tools;
+    private readonly hidden;
+    register(provider: ToolProvider, options?: RegisterOptions): Promise<void>;
+    /** True for a tool the provider offers but an allow list left out. */
+    isHidden(name: string): boolean;
+    /** Tools that providers offer but allow lists left out. */
+    hiddenTools(): HiddenTool[];
+    list(): RegisteredTool[];
+    get(name: string): RegisteredTool | undefined;
+}

package/dist/tool/registry.js

@@ -0,0 +1,68 @@
+import { OpenshainError } from "../errors.js";
+import { RESERVED_TOOL_NAMES, TOOL_NAME_PATTERN, } from "./types.js";
+import { compileInputValidator } from "./validate.js";
+/** Every tool the runtime can offer, across providers. Names are unique. */
+export class ToolRegistry {
+    tools = new Map();
+    hidden = [];
+    async register(provider, options = {}) {
+        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();
+        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;
+            try {
+                validate = compileInputValidator(definition.inputSchema);
+            }
+            catch (cause) {
+                throw new OpenshainError("invalid_tool", `tool "${name}" from provider "${provider.id}": ${cause.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) {
+        return !this.tools.has(name) && this.hidden.some((h) => h.name === name);
+    }
+    /** Tools that providers offer but allow lists left out. */
+    hiddenTools() {
+        return this.hidden.filter((h) => !this.tools.has(h.name)).map((h) => ({ ...h }));
+    }
+    list() {
+        return [...this.tools.values()];
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+}

package/dist/tool/types.d.ts

@@ -0,0 +1,44 @@
+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 declare const TOOL_NAME_PATTERN: RegExp;
+/** The tool the runtime itself provides. No provider may define it. */
+export declare 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 declare const RESERVED_TOOL_NAMES: readonly string[];
+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>;
+}

package/dist/tool/types.js

@@ -0,0 +1,15 @@
+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 = [
+    ASK_USER_TOOL_NAME,
+    "work_create",
+    "work_select",
+    "work_get",
+    "work_list",
+    "work_complete",
+    "work_fail",
+    "work_run",
+    "work_show",
+];

package/dist/tool/validate.d.ts

@@ -0,0 +1,14 @@
+import type { JsonSchema } from "./types.ts";
+export type InputValidation = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Compiles a tool's input schema once. Unknown keywords are tolerated because
+ * third-party schemas may carry vendor extensions; the schema itself must be
+ * valid, must describe an object, and may not contain a regular expression
+ * that can be made to backtrack catastrophically (the model controls the input).
+ */
+export declare function compileInputValidator(schema: JsonSchema): (input: unknown) => InputValidation;

package/dist/tool/validate.js

@@ -0,0 +1,68 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import safeRegex from "safe-regex2";
+import { OpenshainError } from "../errors.js";
+/**
+ * Compiles a tool's input schema once. Unknown keywords are tolerated because
+ * third-party schemas may carry vendor extensions; the schema itself must be
+ * valid, must describe an object, and may not contain a regular expression
+ * that can be made to backtrack catastrophically (the model controls the input).
+ */
+export function compileInputValidator(schema) {
+    if (schema.type !== "object") {
+        throw new OpenshainError("invalid_tool", 'input schema must have "type": "object"');
+    }
+    const unsafe = findUnsafePattern(schema);
+    if (unsafe !== undefined) {
+        throw new OpenshainError("invalid_tool", `input schema contains a regular expression that can backtrack catastrophically: ${unsafe}`);
+    }
+    const ajv = new Ajv2020({ strict: false, allErrors: true });
+    let validate;
+    try {
+        validate = ajv.compile(schema);
+    }
+    catch (cause) {
+        throw new OpenshainError("invalid_tool", `input schema does not compile: ${cause.message}`, { cause });
+    }
+    return (input) => validate(input) ? { ok: true } : { ok: false, reason: describe(validate.errors ?? []) };
+}
+/** Walks the schema and returns the first `pattern` or `patternProperties` key that is unsafe. */
+function findUnsafePattern(node) {
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            const found = findUnsafePattern(item);
+            if (found !== undefined)
+                return found;
+        }
+        return undefined;
+    }
+    if (node === null || typeof node !== "object")
+        return undefined;
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "pattern" && typeof value === "string" && !safeRegex(value))
+            return value;
+        if (key === "patternProperties" && value !== null && typeof value === "object") {
+            for (const pattern of Object.keys(value)) {
+                if (!safeRegex(pattern))
+                    return pattern;
+            }
+        }
+        const found = findUnsafePattern(value);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function describe(errors) {
+    return errors
+        .map((error) => {
+        const where = error.instancePath || "/";
+        const params = error.params;
+        const detail = error.keyword === "additionalProperties"
+            ? ` (${String(params.additionalProperty)})`
+            : error.keyword === "required"
+                ? ` (${String(params.missingProperty)})`
+                : "";
+        return `${where} ${error.message ?? error.keyword}${detail}`;
+    })
+        .join("; ");
+}

package/dist/uuid.d.ts

@@ -0,0 +1 @@
+export declare function uuidv7(now?: number): string;

package/dist/uuid.js

@@ -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 = Date.now()) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    if (now > lastMs) {
+        lastMs = now;
+        counter = ((bytes[6] & 0x07) << 8) | bytes[7];
+    }
+    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] & 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/dist/work/artifacts.d.ts

@@ -0,0 +1,7 @@
+import type { Artifact } from "./events.ts";
+/**
+ * The artifact as it is now. The runtime computes the hash rather than taking anyone's word.
+ * When the file cannot be read, because a later call moved or deleted it or because nobody
+ * wrote it, the artifact keeps the hash that was reported and is marked missing.
+ */
+export declare function verifyArtifact(root: string, path: string, reported: string): Promise<Artifact>;

package/dist/work/artifacts.js

@@ -0,0 +1,20 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolveWorkspacePath } from "../tool/paths.js";
+/**
+ * The artifact as it is now. The runtime computes the hash rather than taking anyone's word.
+ * When the file cannot be read, because a later call moved or deleted it or because nobody
+ * wrote it, the artifact keeps the hash that was reported and is marked missing.
+ */
+export async function verifyArtifact(root, path, reported) {
+    try {
+        const resolved = await resolveWorkspacePath(root, path);
+        const sha256 = createHash("sha256")
+            .update(await readFile(resolved))
+            .digest("hex");
+        return { path, sha256 };
+    }
+    catch {
+        return { path, sha256: reported, missing: true };
+    }
+}

package/dist/work/event-log.d.ts

@@ -0,0 +1,28 @@
+import { type WorkId } from "../ids.ts";
+import { type AnyEvent, type Event, type EventPayloads, type EventType } from "./events.ts";
+export declare const EVENTS_FILE_NAME = "events.jsonl";
+export interface NewEvent<T extends EventType = EventType> {
+    type: T;
+    payload: EventPayloads[T];
+    /** When the thing happened. Defaults to the time of recording. */
+    occurredAt?: string;
+}
+/**
+ * Append-only log of one work's events. The file is the source of truth.
+ *
+ * Every line is checked on open and on read; a line that cannot be read stops
+ * the reader. Every event is checked on append by reading its own line back
+ * before it is written, so what is written can always be read. A change to the
+ * file by someone else between two operations of this instance is refused.
+ */
+export declare class EventLog {
+    private readonly path;
+    private readonly workId;
+    private nextSeq;
+    private size;
+    private constructor();
+    /** Opens (creating the directory if needed) and checks the existing log end to end. */
+    static open(dir: string, workId: WorkId): Promise<EventLog>;
+    append<T extends EventType>(input: NewEvent<T>): Promise<Event<T>>;
+    read(): Promise<AnyEvent[]>;
+}