@karowanorg/orc-sdk 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-sdk
+
+Embedded TypeScript SDK for orc: launch, watch, and collect runs in-process.
+
+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/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @karowanorg/orc-sdk — the embedded TypeScript SDK. Types are inferred from the zod-first
+ * operation registry; the Orc class is a thin ergonomic layer over the same op
+ * handlers the CLI and MCP call.
+ */
+import { z } from "zod";
+import { launch as launchOp, validate as validateOp, type OpContext } from "@karowanorg/orc-ops";
+import { type Json, type RunStatus } from "@karowanorg/orc-core";
+export type LaunchInput = z.input<typeof launchOp.input>;
+export type ValidateInput = z.input<typeof validateOp.input>;
+export type RunEvent = {
+    kind: "status";
+    status: RunStatus;
+} | {
+    kind: "approval-requested";
+    approvalId: string;
+    toolName: string;
+    input: Json;
+    respond(d: {
+        behavior: "allow" | "deny";
+        message?: string;
+    }): Promise<void>;
+} | {
+    kind: "done";
+    status: RunStatus;
+};
+export declare class OrcRun {
+    private readonly orc;
+    readonly runId: string;
+    constructor(orc: Orc, runId: string);
+    status(): Promise<RunStatus>;
+    wait(timeoutSeconds?: number): Promise<RunStatus>;
+    /** Typed event stream: status ticks, answerable approvals, terminal done. */
+    watch(pollMs?: number): AsyncIterable<RunEvent>;
+    result(): Promise<Json>;
+    cancel(): Promise<void>;
+}
+export declare class Orc {
+    private readonly opts;
+    private context?;
+    constructor(opts?: {
+        defaultHarness?: string;
+        cwd?: string;
+    });
+    /** @internal */
+    ctx(): Promise<OpContext>;
+    launch(input: LaunchInput): Promise<OrcRun & {
+        info: Awaited<ReturnType<typeof launchOp.handler>>;
+    }>;
+    validate(input: ValidateInput): Promise<Awaited<ReturnType<typeof validateOp.handler>>>;
+    resume(runId: string, wait?: boolean): Promise<OrcRun>;
+    capabilities(host?: string): Promise<unknown>;
+    run(runId: string): OrcRun;
+    status(runId: string): Promise<RunStatus>;
+    approvals(runId: string): Promise<import("@karowanorg/orc-core").ApprovalRequest[]>;
+}

package/dist/index.js

@@ -0,0 +1,101 @@
+import { buildRegistry, launch as launchOp, status as statusOp, wait as waitOp, getResult as getResultOp, resume as resumeOp, cancel as cancelOp, capabilities as capabilitiesOp, respondApproval as respondOp, listApprovals as listApprovalsOp, validate as validateOp, } from "@karowanorg/orc-ops";
+import { readTraces, openApprovals, statusForRun } from "@karowanorg/orc-core";
+export class OrcRun {
+    orc;
+    runId;
+    constructor(orc, runId) {
+        this.orc = orc;
+        this.runId = runId;
+    }
+    async status() {
+        return statusForRun(this.runId);
+    }
+    async wait(timeoutSeconds = 300) {
+        const input = waitOp.input.parse({ runId: this.runId, timeoutSeconds });
+        const ctx = await this.orc.ctx();
+        return (await waitOp.handler(input, ctx)).status;
+    }
+    /** Typed event stream: status ticks, answerable approvals, terminal done. */
+    async *watch(pollMs = 1000) {
+        const ctx = await this.orc.ctx();
+        const seenApprovals = new Set();
+        for (;;) {
+            const s = statusForRun(this.runId);
+            for (const approval of openApprovals(readTraces(this.runId))) {
+                if (!seenApprovals.has(approval.id)) {
+                    seenApprovals.add(approval.id);
+                    yield {
+                        kind: "approval-requested",
+                        approvalId: approval.id,
+                        toolName: approval.toolName,
+                        input: approval.input,
+                        respond: async (d) => {
+                            await respondOp.handler({ runId: this.runId, approvalId: approval.id, behavior: d.behavior, message: d.message }, ctx);
+                        },
+                    };
+                }
+            }
+            if (s.state !== "running") {
+                yield { kind: "done", status: s };
+                return;
+            }
+            yield { kind: "status", status: s };
+            await new Promise((r) => setTimeout(r, pollMs));
+        }
+    }
+    async result() {
+        const ctx = await this.orc.ctx();
+        const res = await getResultOp.handler({ runId: this.runId }, ctx);
+        return res.body;
+    }
+    async cancel() {
+        const ctx = await this.orc.ctx();
+        await cancelOp.handler({ runId: this.runId }, ctx);
+    }
+}
+export class Orc {
+    opts;
+    context;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    /** @internal */
+    async ctx() {
+        this.context ??= {
+            registry: await buildRegistry({ cwd: this.opts.cwd, defaultHarness: this.opts.defaultHarness }),
+            registryCwd: this.opts.cwd,
+        };
+        return this.context;
+    }
+    async launch(input) {
+        const ctx = await this.ctx();
+        const info = await launchOp.handler(launchOp.input.parse(input), ctx);
+        const run = new OrcRun(this, info.runId);
+        run.info = info;
+        return run;
+    }
+    async validate(input) {
+        const ctx = await this.ctx();
+        return validateOp.handler(validateOp.input.parse(input), ctx);
+    }
+    async resume(runId, wait = false) {
+        const ctx = await this.ctx();
+        await resumeOp.handler(resumeOp.input.parse({ runId, wait }), ctx);
+        return new OrcRun(this, runId);
+    }
+    async capabilities(host) {
+        const ctx = await this.ctx();
+        return capabilitiesOp.handler({ host, refresh: false }, ctx);
+    }
+    run(runId) {
+        return new OrcRun(this, runId);
+    }
+    async status(runId) {
+        const ctx = await this.ctx();
+        return statusOp.handler({ runId }, ctx);
+    }
+    async approvals(runId) {
+        const ctx = await this.ctx();
+        return listApprovalsOp.handler({ runId }, ctx);
+    }
+}

package/dist/program.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @karowanorg/orc-sdk/program — type-only surface for program authors. Import with
+ * `import type` (runtime imports are rejected by the sandbox).
+ */
+export type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+export interface AgentOptions {
+    /** Optional trace label — makes waterfall rows read semantically. */
+    id?: string;
+    /** "claude" | "codex" | a config-registered harness. Default: caller affinity. */
+    harness?: string;
+    model?: string;
+    reasoningEffort?: string;
+    /** JSON Schema for structured output. */
+    schema?: Json;
+    /** Default true. false requires the run's allow-writes grant (fail-closed). */
+    readOnly?: boolean;
+    /** Plain path on the leaf's host. Defaults to the run cwd. */
+    cwd?: string;
+    /** SSH destination (separate field — never a URI). Defaults to the run host. */
+    host?: string;
+    /** Output-idle watchdog for this call, ms; false disables. */
+    idleTimeout?: number | false;
+    phase?: string;
+}
+export interface ParallelSpec extends AgentOptions {
+    prompt: string;
+}
+export type Settled<T> = {
+    status: "ok";
+    value: T;
+} | {
+    status: "error";
+    error: string;
+};
+export interface OrcApi {
+    agent(prompt: string, opts?: AgentOptions): Promise<Json>;
+    /**
+     * Independent fan-out: every lane runs to completion (one failing lane never
+     * cancels the others) and comes back as a per-lane settled outcome, in order.
+     * For fail-fast, use Promise.all over agent() instead.
+     */
+    parallel(specs: ParallelSpec[]): Promise<Settled<Json>[]>;
+    /** Labels every call made inside fn for the waterfall. */
+    phase<T>(name: string, fn: () => T | Promise<T>): Promise<T>;
+    log(message: string): void;
+    /** Envelope helper: collect a failing lane without sinking the run. */
+    settle<T>(p: Promise<T>): Promise<Settled<T>>;
+    /** Config-registered extension leaves — journaled exactly like agent(). */
+    ext: Record<string, (payload?: Json) => Promise<Json>>;
+}
+export type Program = (api: OrcApi) => Promise<Json>;

package/dist/program.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@karowanorg/orc-sdk",
+  "version": "0.1.0",
+  "license": "0BSD",
+  "type": "module",
+  "main": "dist/index.js",
+  "dependencies": {
+    "@karowanorg/orc-ops": "^0.1.0",
+    "@karowanorg/orc-core": "^0.1.0",
+    "zod": "^4.1.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./program": {
+      "types": "./dist/program.d.ts",
+      "default": "./dist/program.js"
+    }
+  },
+  "description": "Embedded TypeScript SDK for orc: launch, watch, and collect runs in-process.",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}