@karowanorg/orc-core 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License (0BSD)
+
+Copyright (c) 2026 Kyle Rowan
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @karowanorg/orc-core
+
+The orc engine: deterministic QuickJS event loop, journaled leaves, replay/resume, supervisor, contracts.
+
+Part of orc - model-authored promise-native agent programs with deterministic replay, live monitoring, and pluggable harnesses. See the orc repository README for the full picture.

package/dist/canonical.d.ts

@@ -0,0 +1,11 @@
+import type { Json } from "./contracts.js";
+/**
+ * Canonical JSON: sorted object keys, no whitespace. One rule used for
+ * journal digests, result content-addressing, and spec hashing.
+ * Numbers pass through JS semantics; integers beyond 2^53 are a pinned design
+ * decision (host-side only — programs receive f64 like any JSON consumer).
+ */
+export declare function canonicalJson(value: Json): string;
+export declare function sha256Hex(data: string | Buffer): string;
+export declare function digestJson(value: Json): string;
+export declare function boundString(s: string, maxBytes: number): string;

package/dist/canonical.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+/**
+ * Canonical JSON: sorted object keys, no whitespace. One rule used for
+ * journal digests, result content-addressing, and spec hashing.
+ * Numbers pass through JS semantics; integers beyond 2^53 are a pinned design
+ * decision (host-side only — programs receive f64 like any JSON consumer).
+ */
+export function canonicalJson(value) {
+    return stringify(value, 0, new WeakSet());
+}
+const MAX_JSON_DEPTH = 256;
+function stringify(v, depth, ancestors) {
+    if (depth > MAX_JSON_DEPTH)
+        throw new TypeError(`JSON nesting exceeds ${MAX_JSON_DEPTH}`);
+    if (v === null || typeof v === "boolean")
+        return JSON.stringify(v);
+    if (typeof v === "number") {
+        if (!Number.isFinite(v))
+            throw new TypeError("JSON numbers must be finite");
+        return JSON.stringify(v);
+    }
+    if (typeof v === "string")
+        return JSON.stringify(v);
+    if (typeof v !== "object")
+        throw new TypeError(`unsupported JSON value: ${typeof v}`);
+    if (ancestors.has(v))
+        throw new TypeError("JSON value contains a cycle");
+    ancestors.add(v);
+    try {
+        if (Array.isArray(v)) {
+            const items = [];
+            for (let i = 0; i < v.length; i++) {
+                const descriptor = Object.getOwnPropertyDescriptor(v, i);
+                if (!descriptor)
+                    throw new TypeError("JSON arrays cannot be sparse");
+                if (!("value" in descriptor))
+                    throw new TypeError("JSON properties cannot be accessors");
+                items.push(stringify(descriptor.value, depth + 1, ancestors));
+            }
+            return `[${items.join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(v);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("JSON objects must be plain objects");
+        }
+        const keys = Object.keys(v).sort();
+        return `{${keys
+            .map((k) => {
+            const descriptor = Object.getOwnPropertyDescriptor(v, k);
+            if (!("value" in descriptor))
+                throw new TypeError("JSON properties cannot be accessors");
+            return `${JSON.stringify(k)}:${stringify(descriptor.value, depth + 1, ancestors)}`;
+        })
+            .join(",")}}`;
+    }
+    finally {
+        ancestors.delete(v);
+    }
+}
+export function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+export function digestJson(value) {
+    return sha256Hex(canonicalJson(value));
+}
+export function boundString(s, maxBytes) {
+    const buf = Buffer.from(s, "utf8");
+    if (buf.byteLength <= maxBytes)
+        return s;
+    return buf.subarray(0, maxBytes).toString("utf8") + `…(truncated ${buf.byteLength - maxBytes} bytes)`;
+}

package/dist/compile.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compile a .orc.ts / .ts / .js program into a frozen single-file bundle.
+ * The emitted bytes are the pinned program: sha256(bundle) goes in the manifest
+ * and every execution (live or replay) runs exactly these bytes.
+ *
+ * Programs may use `import type` freely (erased); runtime imports are rejected
+ * (the sandbox has no module loader).
+ */
+export declare function compileProgram(entryPath: string): Promise<{
+    bundle: string;
+    sha256: string;
+}>;

package/dist/compile.js

@@ -0,0 +1,27 @@
+import { build } from "esbuild";
+import * as fs from "node:fs";
+import { sha256Hex } from "./canonical.js";
+/**
+ * Compile a .orc.ts / .ts / .js program into a frozen single-file bundle.
+ * The emitted bytes are the pinned program: sha256(bundle) goes in the manifest
+ * and every execution (live or replay) runs exactly these bytes.
+ *
+ * Programs may use `import type` freely (erased); runtime imports are rejected
+ * (the sandbox has no module loader).
+ */
+export async function compileProgram(entryPath) {
+    if (!fs.existsSync(entryPath))
+        throw new Error(`program not found: ${entryPath}`);
+    const result = await build({
+        entryPoints: [entryPath],
+        bundle: true,
+        format: "iife",
+        globalName: "__orc_mod",
+        platform: "neutral",
+        target: "es2020",
+        write: false,
+        logLevel: "silent",
+    });
+    const bundle = result.outputFiles[0].text;
+    return { bundle, sha256: sha256Hex(bundle) };
+}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+import type { ExtensionLeaf, Harness } from "./contracts.js";
+import type { ModelRate } from "./cost.js";
+/**
+ * Optional config. Zero config is the default: built-ins (claude, codex) are
+ * discovered natively; there is deliberately NO ambient plugin scanning —
+ * registering a custom harness or extension is an explicit config entry.
+ */
+export interface OrcConfig {
+    /** Custom harnesses: Harness objects, or { exec } NDJSON executables. */
+    harnesses?: Array<Harness | {
+        exec: string;
+        name?: string;
+    }>;
+    defaultHarness?: string;
+    extensions?: ExtensionLeaf[];
+    /** Per-model USD/1M rate overrides for cost estimation (codex). */
+    costRates?: Record<string, ModelRate>;
+}
+/** Identity helper with types — `defineLeaf({...})` in orc.config.js. */
+export declare function defineLeaf(leaf: ExtensionLeaf): ExtensionLeaf;
+export declare function loadConfig(cwd: string): Promise<OrcConfig>;
+/**
+ * Caller-affinity default harness: an orchestration launched from a claude
+ * session defaults to claude leaves; from codex, codex. Resolution order is
+ * per-call harness → launch flag → config.defaultHarness → caller affinity →
+ * codex → any available. `mcpClientName` lets the MCP head pass clientInfo.
+ */
+export declare function callerAffinity(mcpClientName?: string): string | undefined;

package/dist/config.js

@@ -0,0 +1,42 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { orcHome } from "./rundir.js";
+/** Identity helper with types — `defineLeaf({...})` in orc.config.js. */
+export function defineLeaf(leaf) {
+    return leaf;
+}
+const CONFIG_BASENAMES = ["orc.config.js", "orc.config.mjs", "orc.config.json"];
+export async function loadConfig(cwd) {
+    for (const dir of [cwd, orcHome()]) {
+        for (const base of CONFIG_BASENAMES) {
+            const file = path.join(dir, base);
+            if (!fs.existsSync(file))
+                continue;
+            if (base.endsWith(".json")) {
+                return JSON.parse(fs.readFileSync(file, "utf8"));
+            }
+            const mod = (await import(pathToFileURL(file).href));
+            return mod.default ?? {};
+        }
+    }
+    return {};
+}
+/**
+ * Caller-affinity default harness: an orchestration launched from a claude
+ * session defaults to claude leaves; from codex, codex. Resolution order is
+ * per-call harness → launch flag → config.defaultHarness → caller affinity →
+ * codex → any available. `mcpClientName` lets the MCP head pass clientInfo.
+ */
+export function callerAffinity(mcpClientName) {
+    const name = (mcpClientName ?? "").toLowerCase();
+    if (name.includes("claude"))
+        return "claude";
+    if (name.includes("codex"))
+        return "codex";
+    if (process.env.CLAUDECODE || process.env.CLAUDE_CODE_ENTRYPOINT)
+        return "claude";
+    if (process.env.CODEX_SANDBOX || process.env.CODEX_HOME || process.env.CODEX_CI)
+        return "codex";
+    return undefined;
+}

package/dist/contracts.d.ts

@@ -0,0 +1,405 @@
+/**
+ * Shared contracts for orc.
+ * Everything here is consumed by core, executors, harnesses, ops, and ui.
+ */
+import type { Readable, Writable } from "node:stream";
+export type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+export type ApprovalMode = "manual" | "accept-edits" | "auto" | "bypass";
+export interface ApprovalRequest {
+    id: string;
+    runId: string;
+    seq: number;
+    toolName: string;
+    input: Json;
+    requestedAtMs: number;
+}
+export interface ApprovalDecision {
+    behavior: "allow" | "deny";
+    message?: string;
+}
+export interface SpawnOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    stdin?: "pipe" | "ignore";
+}
+export interface Proc {
+    stdin: Writable | null;
+    stdout: Readable;
+    stderr: Readable;
+    /** Resolves with the exit code (or -1 on signal kill). Never rejects. */
+    exited: Promise<number>;
+    /** SIGTERM the process group, grace, then SIGKILL. Idempotent. */
+    kill(): void;
+    pid: number | undefined;
+}
+export interface Executor {
+    /** undefined for local; the ssh destination string otherwise (e.g. "build@ci-box"). */
+    readonly host: string | undefined;
+    spawn(cmd: string[], opts?: SpawnOptions): Proc;
+    /** Run a command to completion, capturing output. */
+    run(cmd: string[], opts?: SpawnOptions & {
+        timeoutMs?: number;
+    }): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    exists(path: string): Promise<boolean>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string): Promise<void>;
+}
+/** One model and the reasoning efforts THAT model supports (per-model). */
+export interface ModelCapability {
+    id: string;
+    displayName?: string;
+    /** Reasoning efforts valid for this model — empty if it takes no effort param. */
+    reasoningEfforts: string[];
+    default?: boolean;
+}
+export interface HarnessCapabilities {
+    available: boolean;
+    version?: string;
+    /** Discovered natively, never hardcoded; each model carries its own efforts. */
+    models: ModelCapability[];
+    approvalModes: ApprovalMode[];
+    structuredOutput: boolean;
+    sessions: boolean;
+    detail?: string;
+}
+export interface LeafRequest {
+    runId: string;
+    seq: number;
+    id?: string;
+    prompt: string;
+    system: string;
+    brief: string;
+    schema?: Json;
+    model?: string;
+    reasoningEffort?: string;
+    readOnly: boolean;
+    cwd: string;
+    host?: string;
+    approvalMode: ApprovalMode;
+    sessionId?: string;
+    idleTimeoutMs?: number | false;
+    /**
+     * Filesystem confinement for WRITE leaves. Default false: a write leaf is an
+     * unconfined subagent that can write wherever the caller can (builds write to
+     * caches outside the workspace). When true, writes are confined to `cwd` plus
+     * `sandboxDirs` (override dirs, e.g. cache roots). Read-only leaves deny the
+     * built-in command/file mutation paths regardless — that's the readOnly
+     * contract, not sandboxing. Configured hooks and MCP tools are not disabled,
+     * so this is not a global side-effect sandbox.
+     */
+    sandbox?: boolean;
+    sandboxDirs?: string[];
+}
+export type HarnessEvent = {
+    kind: "tool-call-open";
+    id: string;
+    name: string;
+    input?: Json;
+    atMs: number;
+} | {
+    kind: "tool-call-close";
+    id: string;
+    status: "ok" | "error";
+    result?: Json;
+    atMs: number;
+} | {
+    kind: "text";
+    delta: string;
+    atMs: number;
+} | {
+    kind: "usage";
+    tokensIn?: number;
+    tokensOut?: number;
+    costUsd?: number;
+    costEstimated?: boolean;
+} | {
+    kind: "model";
+    model?: string;
+    reasoningEffort?: string;
+} | {
+    kind: "session";
+    sessionId: string;
+} | {
+    kind: "denied";
+    toolName: string;
+    reason: string;
+    atMs: number;
+} | {
+    kind: "result";
+    output: Json;
+} | {
+    kind: "error";
+    message: string;
+};
+export interface HarnessContext {
+    executor: Executor;
+    requestApproval(req: Omit<ApprovalRequest, "id" | "requestedAtMs">): Promise<ApprovalDecision>;
+    signal: AbortSignal;
+    log(message: string): void;
+}
+export interface Harness {
+    readonly name: string;
+    discover(ctx: {
+        executor: Executor;
+    }): Promise<HarnessCapabilities>;
+    invoke(req: LeafRequest, ctx: HarnessContext): AsyncIterable<HarnessEvent>;
+    /**
+     * Optional static check of a leaf's structured-output JSON Schema against
+     * whatever the harness enforces at runtime (e.g. OpenAI/codex strict mode).
+     * Returns human-readable problems so `orc validate` can reject a schema the
+     * model would otherwise fail on at invocation time. Empty/undefined = no
+     * harness-specific restriction.
+     */
+    lintOutputSchema?(schema: Json): string[];
+}
+export interface ExtensionLeaf {
+    name: string;
+    inputSchema?: Json;
+    readOnly: boolean;
+    execute(payload: Json, ctx: HarnessContext): Promise<Json>;
+}
+export interface ThunkSpec {
+    kind: "agent" | `ext:${string}`;
+    prompt?: string;
+    payload?: Json;
+    id?: string;
+    harness?: string;
+    model?: string;
+    reasoningEffort?: string;
+    schema?: Json;
+    readOnly: boolean;
+    cwd?: string;
+    host?: string;
+    phase?: string;
+    idleTimeoutMs?: number | false;
+    groupId?: string;
+}
+export interface CallRecord {
+    t: "call";
+    seq: number;
+    kind: ThunkSpec["kind"];
+    id?: string;
+    phase?: string;
+    readOnly: boolean;
+    /** sha256 of the canonical ThunkSpec — replay verifies this. */
+    specDigest: string;
+}
+export interface CompletionRecord {
+    t: "done";
+    seq: number;
+    status: "ok" | "error";
+    /** sha256 of the canonical result body in results/<sha>.json (ok only). */
+    resultSha?: string;
+    sizeBytes?: number;
+    error?: string;
+    attempt: number;
+}
+/** Durable start of one leaf attempt, written before the harness is invoked. */
+export interface AttemptRecord {
+    t: "attempt";
+    seq: number;
+    attempt: number;
+    atMs: number;
+}
+/**
+ * Latest cumulative cost reported for one attempt. Multiple records may be
+ * written; replay keeps the last value for each (seq, attempt) pair.
+ */
+export interface CostRecord {
+    t: "cost";
+    seq: number;
+    attempt: number;
+    costUsd: number;
+    costEstimated: boolean;
+    atMs: number;
+}
+export interface FinishRecord {
+    t: "finish";
+    status: "completed" | "failed" | "cancelled";
+    resultSha?: string;
+    error?: string;
+    /** Number of control records consumed by the ownership epoch that finished. */
+    controlOffset?: number;
+    /** Leaf whose delivered error directly became the program's terminal error. */
+    errorSeq?: number;
+}
+/**
+ * Fail-forward resume marker (append-only — history is never rewritten):
+ * completion records for these seqs written BEFORE this marker are void for
+ * replay; the seqs re-dispatch with a fresh attempt.
+ */
+export interface RetryRecord {
+    t: "retry";
+    seqs: number[];
+    atMs: number;
+}
+export type JournalRecord = CallRecord | AttemptRecord | CostRecord | CompletionRecord | FinishRecord | RetryRecord;
+export interface ToolCallTrace {
+    id: string;
+    name: string;
+    input?: Json;
+    result?: Json;
+    startMs?: number;
+    endMs?: number;
+    status: "running" | "ok" | "error";
+}
+export interface LeafTraceRecord {
+    t: "leaf";
+    seq: number;
+    attempt: number;
+    rev: number;
+    status: "running" | "ok" | "error";
+    id?: string;
+    phase?: string;
+    kind: string;
+    harness?: string;
+    model?: string;
+    reasoningEffort?: string;
+    host?: string;
+    cwd?: string;
+    readOnly: boolean;
+    startMs: number;
+    endMs?: number;
+    prompt?: string;
+    brief?: string;
+    output?: Json;
+    error?: string;
+    sessionId?: string;
+    toolCalls?: ToolCallTrace[];
+    tokensIn?: number;
+    tokensOut?: number;
+    costUsd?: number;
+    costEstimated?: boolean;
+    reoriented?: boolean;
+}
+export interface RunEventRecord {
+    t: "event";
+    atMs: number;
+    event: {
+        kind: "log";
+        message: string;
+    } | {
+        kind: "phase";
+        name: string;
+    } | {
+        kind: "approval-requested";
+        approval: ApprovalRequest;
+    } | {
+        kind: "approval-resolved";
+        approvalId: string;
+        decision: ApprovalDecision;
+        by: string;
+    } | {
+        kind: "denied";
+        seq: number;
+        toolName: string;
+        reason: string;
+    };
+}
+/**
+ * A harness's own stderr/tracing line, attributed to one leaf. Kept OUT of the
+ * run's event feed (which carries only the orchestration narrative) and shown
+ * in the leaf's drawer under a collapsed "Harness log" section, deduped.
+ */
+export interface HarnessLogRecord {
+    t: "hlog";
+    seq: number;
+    atMs: number;
+    message: string;
+}
+export type TraceRecord = LeafTraceRecord | RunEventRecord | HarnessLogRecord;
+export interface RunManifest {
+    runId: string;
+    name?: string;
+    programPath: string;
+    programSha256: string;
+    cwd: string;
+    host?: string;
+    brief: string;
+    allowWrites: boolean;
+    approvalMode: ApprovalMode;
+    sandbox: boolean;
+    sandboxDirs: string[];
+    maxParallel: number;
+    idleTimeoutMs: number | false;
+    /** Reactive USD cap: the run fails once observed estimated cost exceeds this. */
+    budgetUsd?: number;
+    defaultHarness: string;
+    createdAtMs: number;
+    orcVersion: string;
+}
+export type RunState = "running" | "completed" | "failed" | "cancelled";
+export interface LeafStatus {
+    seq: number;
+    id?: string;
+    phase?: string;
+    kind: string;
+    status: "pending" | "running" | "ok" | "error";
+    readOnly: boolean;
+    harness?: string;
+    host?: string;
+    startMs?: number;
+    endMs?: number;
+    error?: string;
+    resultSha?: string;
+    attempt?: number;
+}
+export interface RunStatus {
+    runId: string;
+    state: RunState;
+    totalCalls: number;
+    ok: number;
+    failed: number;
+    running: number;
+    approvalsPending: number;
+    leaves: LeafStatus[];
+    resultSha?: string;
+    error?: string;
+    startedAtMs: number;
+    endedAtMs?: number;
+    approvalMode: ApprovalMode;
+    allowWrites: boolean;
+}
+export type ControlMessage = {
+    t: "cancel";
+    atMs: number;
+} | {
+    t: "approval";
+    approvalId: string;
+    decision: ApprovalDecision;
+    by: string;
+    atMs: number;
+};
+export interface Policy {
+    maxCommands: number;
+    maxParallel: number;
+    maxPromptBytes: number;
+    maxResultBytes: number;
+    maxErrorBytes: number;
+    stepBudgetPerTurn: number;
+    memoryLimitBytes: number;
+    maxStackBytes: number;
+    readOnlyRetries: number;
+}
+export declare const DEFAULT_POLICY: Policy;
+export declare class DivergenceError extends Error {
+    readonly detail: {
+        seq?: number;
+        expected?: string;
+        got?: string;
+    };
+    constructor(message: string, detail: {
+        seq?: number;
+        expected?: string;
+        got?: string;
+    });
+}
+export declare class PolicyError extends Error {
+    constructor(message: string);
+}

package/dist/contracts.js

@@ -0,0 +1,28 @@
+export const DEFAULT_POLICY = {
+    maxCommands: 128,
+    maxParallel: 8,
+    maxPromptBytes: 1 << 20,
+    maxResultBytes: 1 << 20,
+    maxErrorBytes: 4096,
+    stepBudgetPerTurn: 100_000,
+    memoryLimitBytes: 64 << 20,
+    maxStackBytes: 1 << 20,
+    readOnlyRetries: 2,
+};
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class DivergenceError extends Error {
+    detail;
+    constructor(message, detail) {
+        super(`replay divergence: ${message}`);
+        this.detail = detail;
+        this.name = "DivergenceError";
+    }
+}
+export class PolicyError extends Error {
+    constructor(message) {
+        super(`policy violation: ${message}`);
+        this.name = "PolicyError";
+    }
+}

package/dist/cost.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cost estimation for harnesses that report tokens but not dollars.
+ *
+ * Claude's Agent SDK returns an exact `total_cost_usd`; codex's app-server
+ * reports only token counts. For codex, orc estimates cost from a per-model
+ * rate table (USD per 1M tokens). Rates are ESTIMATES — the number is marked
+ * `estimated: true` so the UI can render it as "~$… est" rather than implying a
+ * billed figure. Override via config (`costRates`) or `ORC_COST_RATES` (JSON).
+ *
+ * If a model has no rate, cost is omitted (never fabricated as zero).
+ */
+export interface ModelRate {
+    /** USD per 1M input (prompt) tokens. */
+    inputPer1M: number;
+    /** USD per 1M output (completion) tokens. */
+    outputPer1M: number;
+    /** USD per 1M cached input tokens (defaults to inputPer1M when absent). */
+    cachedInputPer1M?: number;
+}
+export interface TokenBreakdown {
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+}
+/**
+ * Default list-price ESTIMATES for the gpt-5.x families, keyed by longest
+ * matching prefix. These are editable placeholders — real billing depends on
+ * your account/agreement. Override with config `costRates` or ORC_COST_RATES.
+ */
+export declare const DEFAULT_COST_RATES: Record<string, ModelRate>;
+export declare function loadCostRates(override?: Record<string, ModelRate>): Record<string, ModelRate>;
+/** Longest-prefix match so "gpt-5.6-sol" resolves to the "gpt-5.6" rate. */
+export declare function rateForModel(rates: Record<string, ModelRate>, model: string | undefined): ModelRate | undefined;
+export declare function estimateCostUsd(rates: Record<string, ModelRate>, model: string | undefined, tokens: TokenBreakdown): number | undefined;