@op0ai/sdk 0.1.0

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"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"}

package/dist/tool.d.ts

@@ -0,0 +1,43 @@
+import type { z } from "zod";
+import type { Source } from "./source.ts";
+import type { Emitter } from "./agui.ts";
+import type { WideSink } from "./evlog.ts";
+/**
+ * What a tool's `execute` receives: the cord's typed env/bindings, its Source, the AG-UI event emitter (the UI
+ * timeline lane), an optional evlog `wide` sink (the ops+audit lane — Analytics Engine + tamper-evident audit),
+ * and an abort signal. `emit` and `wide` share the run's id, so the two lanes correlate.
+ */
+export interface ToolContext<Env = unknown> {
+    readonly env: Env;
+    readonly source: Source;
+    readonly emit: Emitter;
+    readonly wide?: WideSink;
+    readonly signal?: AbortSignal;
+}
+/** A governed tool. `inputSchema` is the zod schema (function-calling models need its JSON-schema). */
+export interface Tool<Env = unknown> {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: z.ZodType;
+    /** Input is typed at authoring time via {@link defineTool}; erased here so a registry can be heterogeneous. */
+    readonly execute: (args: never, context: ToolContext<Env>) => Promise<unknown>;
+}
+/** A cord's tool registry: a name → Tool map. */
+export type ToolSet<Env = unknown> = Record<string, Tool<Env>>;
+/**
+ * Author a governed tool with full input inference: `execute(args, ctx)` gets `z.infer<Input>`.
+ * The `Env` type param ties the tool to its cord's typed bindings.
+ */
+export declare function defineTool<Input extends z.ZodType, Env = unknown>(spec: {
+    name: string;
+    description: string;
+    input: Input;
+    execute: (args: z.infer<Input>, context: ToolContext<Env>) => Promise<unknown>;
+}): Tool<Env>;
+/** Manifest form of a tool (for cord.json / discovery). */
+export interface ToolManifestEntry {
+    readonly name: string;
+    readonly description: string;
+}
+export declare function toolManifest<Env>(tools: ToolSet<Env>): ToolManifestEntry[];
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,GAAG,GAAG,OAAO;IACxC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,uGAAuG;AACvG,MAAM,WAAW,IAAI,CAAC,GAAG,GAAG,OAAO;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC;IAChC,+GAA+G;IAC/G,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChF;AAED,iDAAiD;AACjD,MAAM,MAAM,OAAO,CAAC,GAAG,GAAG,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,EAAE,IAAI,EAAE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAChF,GAAG,IAAI,CAAC,GAAG,CAAC,CAOZ;AAED,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,iBAAiB,EAAE,CAE1E"}

package/dist/tool.js

@@ -0,0 +1,16 @@
+/**
+ * Author a governed tool with full input inference: `execute(args, ctx)` gets `z.infer<Input>`.
+ * The `Env` type param ties the tool to its cord's typed bindings.
+ */
+export function defineTool(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        inputSchema: spec.input,
+        execute: spec.execute,
+    };
+}
+export function toolManifest(tools) {
+    return Object.values(tools).map((t) => ({ name: t.name, description: t.description }));
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAmCA;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAyC,IAKlE;IACC,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,KAAK;QACvB,OAAO,EAAE,IAAI,CAAC,OAA+B;KAC9C,CAAC;AACJ,CAAC;AAQD,MAAM,UAAU,YAAY,CAAM,KAAmB;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AACzF,CAAC"}

package/dist/usectx.d.ts

@@ -0,0 +1,93 @@
+/** A resolved Source: a flat, posix-relative file view of a target. The cord depends ONLY on this. */
+export interface FileSet {
+    /** does this path exist (file or dir), relative to the target root */
+    exists(path: string): Promise<boolean>;
+    /** utf-8 contents of a file, or null if absent/unreadable */
+    read(path: string): Promise<string | null>;
+    /** every tracked FILE path (recursive, posix-relative); excludes .git / node_modules */
+    paths(): Promise<string[]>;
+}
+/** THE usectx boundary: resolve a target to a FileSet. */
+export type Acquire = (target: string) => Promise<FileSet>;
+/** Build a FileSet from an in-memory path→content map. The non-repo Sources (an evlog trace, an R2 snapshot) resolve to this. */
+export declare function fileSetOf(files: Record<string, string>): FileSet;
+export type TargetKind = "repo" | "url" | "fs" | "evlog" | "r2" | "zip" | "unknown";
+/** Detect a target's kind so the resolver can route it to the right connection (Notion §7 open item, made concrete). */
+export declare function classifyTarget(target: string): TargetKind;
+/** Acquire a PUBLIC repo over HTTPS (Git Trees API + raw contents). 403/404/truncation LOUD-FAIL (never score an empty/partial tree). */
+export declare const acquireGitHub: (token?: string) => Acquire;
+/**
+ * The github connection surface usectx needs from the connections engine (executor). The host implements this
+ * (wired to executor's `github_v3_rest_api` connection — verified live 2026-06-29); @op0-ai/cord stays dep-free.
+ * This is the authed path: 5000/hr, dedicated identity, redaction/audit at the connection.
+ */
+export interface GithubConnection {
+    reposGet(o: {
+        owner: string;
+        repo: string;
+    }): Promise<{
+        default_branch?: string;
+    }>;
+    gitGetTree(o: {
+        owner: string;
+        repo: string;
+        tree_sha: string;
+        recursive: "1";
+    }): Promise<{
+        tree?: Array<{
+            path: string;
+            type: string;
+        }>;
+        truncated?: boolean;
+    }>;
+    reposGetContent(o: {
+        owner: string;
+        repo: string;
+        path: string;
+        ref: string;
+    }): Promise<{
+        content?: string;
+        encoding?: string;
+    } | null>;
+}
+/** Acquire a repo's FileSet through an executor github connection (the authed, by-design path). */
+export declare const acquireExecutor: (conn: GithubConnection) => Acquire;
+/** Acquire a single live URL as a one-file FileSet (path "" or the URL's basename). */
+export declare const acquireHttp: Acquire;
+/** Acquire a local checkout over node:fs (LOCAL/CLI/tests only; lazy import keeps the module Worker-safe). */
+export declare const acquireFs: Acquire;
+/** A custom Source resolver for a target kind (e.g. evlog: / r2: / a registry handle). */
+export type SourceResolver = (target: string) => Promise<FileSet>;
+export interface UsectxConfig {
+    /** authed by-design path; preferred for repos when present */
+    executor?: GithubConnection;
+    /** public HTTPS bootstrap for repos; token lifts the rate limit */
+    github?: {
+        token?: string;
+    };
+    /** allow live-URL acquisition */
+    http?: boolean;
+    /** allow local-fs acquisition (Node/CLI) */
+    fs?: boolean;
+    /** custom resolvers by kind — the non-repo Sources (evlog / r2 / zip / handle) */
+    resolvers?: Partial<Record<TargetKind, SourceResolver>>;
+    /** in-band redaction applied to every read() (scrub secrets/PII before content leaves the boundary) */
+    redact?: (text: string | null, ctx: {
+        target: string;
+        path: string;
+    }) => string | null;
+    /** in-band audit hook fired on each acquire + read (the connection's audit lane) */
+    audit?: (entry: {
+        op: "acquire" | "read";
+        target: string;
+        kind: TargetKind;
+        path?: string;
+    }) => void;
+}
+/**
+ * Build the usectx boundary. `acquire(target)` classifies the target, routes it to the right adapter
+ * (executor preferred for repos, else github; custom resolvers for evlog/r2/zip/url/fs), and wraps the
+ * resulting FileSet with in-band redaction + audit. This is the one acquisition primitive a cord uses.
+ */
+export declare function usectx(config?: UsectxConfig): Acquire;
+//# sourceMappingURL=usectx.d.ts.map

package/dist/usectx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usectx.d.ts","sourceRoot":"","sources":["../src/usectx.ts"],"names":[],"mappings":"AAaA,sGAAsG;AACtG,MAAM,WAAW,OAAO;IACtB,sEAAsE;IACtE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,6DAA6D;IAC7D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3C,wFAAwF;IACxF,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5B;AAED,0DAA0D;AAC1D,MAAM,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAM3D,iIAAiI;AACjI,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAiBhE;AAID,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI,GAAG,OAAO,GAAG,IAAI,GAAG,KAAK,GAAG,SAAS,CAAC;AAEpF,wHAAwH;AACxH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CASzD;AAwBD,yIAAyI;AACzI,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,KAAG,OAiC9C,CAAC;AAIF;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnF,UAAU,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACjK,eAAe,CAAC,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;CACzI;AAED,mGAAmG;AACnG,eAAO,MAAM,eAAe,GAAI,MAAM,gBAAgB,KAAG,OAsBxD,CAAC;AAIF,uFAAuF;AACvF,eAAO,MAAM,WAAW,EAAE,OAMzB,CAAC;AAEF,8GAA8G;AAC9G,eAAO,MAAM,SAAS,EAAE,OAgBvB,CAAC;AAIF,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,mEAAmE;IACnE,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5B,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,kFAAkF;IAClF,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC;IACxD,uGAAuG;IACvG,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,GAAG,IAAI,CAAC;IACvF,oFAAoF;IACpF,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,UAAU,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACtG;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,MAAM,GAAE,YAAiB,GAAG,OAAO,CAiCzD"}

package/dist/usectx.js

@@ -0,0 +1,220 @@
+// usectx.ts — the context-acquisition seam: how a cord ACQUIRES context (the READ-side Source). This is the
+// usectx boundary (Notion: "usectx + the Source contract"). A cord does NOT reach the world directly; it asks
+// usectx for a target, and usectx resolves it via the right connection (auth · rate-limit · redaction · audit
+// in-band). The whole boundary is one function:  acquire(target) => FileSet.
+//
+//   const acquire = usectx({ github: { token }, executor, redact, audit });
+//   const fs = await acquire("github.com/op0ai/op0dotdev");   // → FileSet (exists/read/paths)
+//
+// A repo is one kind of Source; an evlog trace, an R2 snapshot, a zip, a live URL are others behind the SAME
+// seam (custom resolvers). Pure TS, zero static deps (Node fs is loaded lazily so the module stays Worker-safe).
+// Sibling to source.ts: source.ts is the WRITE/commit Source (bidirectionalSource); usectx is the READ/context
+// Source. Pairs with executor as the authed, by-design connection backend (the interim engine toward hosted usectx).
+const norm = (p) => p.replace(/^\.?\/+/, "").replace(/\/+$/, "");
+// ---------- in-memory FileSet (for evlog / R2 / zip Sources + tests) ----------
+/** Build a FileSet from an in-memory path→content map. The non-repo Sources (an evlog trace, an R2 snapshot) resolve to this. */
+export function fileSetOf(files) {
+    const map = new Map(Object.entries(files).map(([k, v]) => [norm(k), v]));
+    return {
+        async exists(p) {
+            const k = norm(p);
+            if (map.has(k))
+                return true;
+            for (const key of map.keys())
+                if (key.startsWith(k + "/"))
+                    return true; // dir
+            return false;
+        },
+        async read(p) {
+            const v = map.get(norm(p));
+            return v ?? null;
+        },
+        async paths() {
+            return [...map.keys()];
+        },
+    };
+}
+/** Detect a target's kind so the resolver can route it to the right connection (Notion §7 open item, made concrete). */
+export function classifyTarget(target) {
+    const t = target.trim();
+    if (t.startsWith("evlog:"))
+        return "evlog";
+    if (t.startsWith("r2:"))
+        return "r2";
+    if (/\.zip($|\?)/i.test(t))
+        return "zip";
+    if (/^git@github\.com:|github\.com[/:]/.test(t) || /^[\w.-]+\/[\w.-]+$/.test(t))
+        return "repo";
+    if (/^https?:\/\//.test(t))
+        return "url";
+    if (/^(\.\/|\/|[a-zA-Z]:\\)/.test(t) || t === ".")
+        return "fs";
+    return "unknown";
+}
+// ---------- github adapter (raw HTTPS — the public, no-auth bootstrap; Worker + Node) ----------
+const parseRepo = (target) => {
+    const m = target.trim().replace(/\.git$/, "").match(/(?:github\.com[/:])?([^/\s]+)\/([^/\s]+)\/?$/);
+    const owner = m?.[1];
+    const repo = m?.[2];
+    if (!owner || !repo)
+        throw new Error(`not a github repo target: ${target}`);
+    return { owner, repo };
+};
+const ghFetch = async (url, headers) => {
+    const r = await fetch(url, { headers });
+    if (r.status === 403 || r.status === 429) {
+        const remaining = r.headers.get("x-ratelimit-remaining");
+        throw new Error(`github ${r.status} for ${url}` +
+            (remaining === "0" ? " — rate limit exhausted; set a token to lift 60→5000/hr (or use executor)" : " (forbidden/auth)"));
+    }
+    return { status: r.status, json: r.ok ? await r.json() : null };
+};
+/** Acquire a PUBLIC repo over HTTPS (Git Trees API + raw contents). 403/404/truncation LOUD-FAIL (never score an empty/partial tree). */
+export const acquireGitHub = (token) => async (target) => {
+    const { owner, repo } = parseRepo(target);
+    const gh = {
+        "user-agent": "op0-cord-usectx",
+        accept: "application/vnd.github+json",
+        ...(token ? { authorization: `Bearer ${token}` } : {}),
+    };
+    const meta = await ghFetch(`https://api.github.com/repos/${owner}/${repo}`, gh);
+    if (meta.status === 404)
+        throw new Error(`github repo not found: ${owner}/${repo}`);
+    const branch = meta.json?.default_branch ?? "main";
+    const treeRes = await ghFetch(`https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`, gh);
+    if (treeRes.status === 404)
+        throw new Error(`github tree not found: ${owner}/${repo}@${branch}`);
+    const tree = treeRes.json ?? { tree: [] };
+    if (tree.truncated === true)
+        throw new Error(`github tree truncated for ${owner}/${repo}@${branch} — needs paged acquisition / a token (use executor)`);
+    const files = new Set(), dirs = new Set();
+    for (const n of tree.tree ?? [])
+        (n.type === "tree" ? dirs : files).add(norm(n.path));
+    const cache = new Map();
+    return {
+        async exists(p) { const k = norm(p); return files.has(k) || dirs.has(k); },
+        async paths() { return [...files]; },
+        async read(p) {
+            const k = norm(p);
+            if (!files.has(k))
+                return null;
+            if (cache.has(k))
+                return cache.get(k) ?? null;
+            const txt = await fetch(`https://raw.githubusercontent.com/${owner}/${repo}/${branch}/${k}`, {
+                headers: { "user-agent": "op0-cord-usectx" },
+            }).then((r) => (r.ok ? r.text() : null));
+            cache.set(k, txt);
+            return txt;
+        },
+    };
+};
+/** Acquire a repo's FileSet through an executor github connection (the authed, by-design path). */
+export const acquireExecutor = (conn) => async (target) => {
+    const { owner, repo } = parseRepo(target);
+    const meta = await conn.reposGet({ owner, repo });
+    const branch = meta.default_branch ?? "main";
+    const treeRes = await conn.gitGetTree({ owner, repo, tree_sha: branch, recursive: "1" });
+    if (treeRes.truncated === true)
+        throw new Error(`github tree truncated for ${owner}/${repo}@${branch} via executor — needs paged acquisition`);
+    const files = new Set(), dirs = new Set();
+    for (const n of treeRes.tree ?? [])
+        (n.type === "tree" ? dirs : files).add(norm(n.path));
+    const cache = new Map();
+    return {
+        async exists(p) { const k = norm(p); return files.has(k) || dirs.has(k); },
+        async paths() { return [...files]; },
+        async read(p) {
+            const k = norm(p);
+            if (!files.has(k))
+                return null;
+            if (cache.has(k))
+                return cache.get(k) ?? null;
+            const r = await conn.reposGetContent({ owner, repo, path: k, ref: branch });
+            const txt = r?.content ? (r.encoding === "base64" ? atob(r.content.replace(/\n/g, "")) : r.content) : null;
+            cache.set(k, txt);
+            return txt;
+        },
+    };
+};
+// ---------- http + fs adapters (a live URL · a local checkout) ----------
+/** Acquire a single live URL as a one-file FileSet (path "" or the URL's basename). */
+export const acquireHttp = async (target) => {
+    const res = await fetch(target, { headers: { "user-agent": "op0-cord-usectx" } });
+    if (!res.ok)
+        throw new Error(`usectx http ${res.status} for ${target}`);
+    const body = await res.text();
+    const name = norm(new URL(target).pathname.split("/").pop() || "index");
+    return fileSetOf({ [name || "index"]: body });
+};
+/** Acquire a local checkout over node:fs (LOCAL/CLI/tests only; lazy import keeps the module Worker-safe). */
+export const acquireFs = async (dir) => {
+    const { existsSync, readFileSync, readdirSync } = await import("node:fs");
+    const { join, relative, sep } = await import("node:path");
+    const IGNORED = /(^|\/)(\.git|node_modules)(\/|$)/;
+    return {
+        async exists(p) { return existsSync(join(dir, p)); },
+        async read(p) { try {
+            return readFileSync(join(dir, p), "utf8");
+        }
+        catch {
+            return null;
+        } },
+        async paths() {
+            try {
+                return readdirSync(dir, { recursive: true, withFileTypes: true })
+                    .filter((d) => d.isFile())
+                    .map((d) => relative(dir, join((d.parentPath ?? d.path), d.name)).split(sep).join("/"))
+                    .filter((p) => !IGNORED.test(p));
+            }
+            catch {
+                return [];
+            }
+        },
+    };
+};
+/**
+ * Build the usectx boundary. `acquire(target)` classifies the target, routes it to the right adapter
+ * (executor preferred for repos, else github; custom resolvers for evlog/r2/zip/url/fs), and wraps the
+ * resulting FileSet with in-band redaction + audit. This is the one acquisition primitive a cord uses.
+ */
+export function usectx(config = {}) {
+    const repoAcquire = config.executor
+        ? acquireExecutor(config.executor)
+        : acquireGitHub(config.github?.token);
+    const pick = (kind, target) => {
+        const custom = config.resolvers?.[kind];
+        if (custom)
+            return custom(target);
+        switch (kind) {
+            case "repo": return repoAcquire(target);
+            case "url":
+                if (config.http)
+                    return acquireHttp(target);
+                break;
+            case "fs":
+                if (config.fs)
+                    return acquireFs(target);
+                break;
+            default: break;
+        }
+        throw new Error(`usectx: no resolver bound for target kind "${kind}" (${target})`);
+    };
+    return async (target) => {
+        const kind = classifyTarget(target);
+        config.audit?.({ op: "acquire", target, kind });
+        const base = await pick(kind, target);
+        if (!config.redact && !config.audit)
+            return base;
+        // wrap read() with redaction + audit; exists/paths pass through
+        return {
+            exists: base.exists.bind(base),
+            paths: base.paths.bind(base),
+            read: async (p) => {
+                config.audit?.({ op: "read", target, kind, path: p });
+                const raw = await base.read(p);
+                return config.redact ? config.redact(raw, { target, path: p }) : raw;
+            },
+        };
+    };
+}
+//# sourceMappingURL=usectx.js.map

package/dist/usectx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usectx.js","sourceRoot":"","sources":["../src/usectx.ts"],"names":[],"mappings":"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"}

package/dist/vault.d.ts

@@ -0,0 +1,21 @@
+export interface Vault {
+    /** Write a deliverable; returns its key + version + content hash (content-addressing → fork lineage). */
+    put(key: string, body: string, meta?: Record<string, unknown>): Promise<{
+        key: string;
+        version: string;
+        hash: string;
+    }>;
+    /** Read a deliverable back (latest version), or null. */
+    get(key: string): Promise<string | null>;
+    /** List keys under a prefix. */
+    list(prefix?: string): Promise<string[]>;
+}
+/** In-memory Vault — the verify/Node default and the H3 red-test substrate. Versions on repeated keys. */
+export declare const memVault: () => Vault & {
+    store: Map<string, {
+        body: string;
+        version: number;
+        meta?: unknown;
+    }>;
+};
+//# sourceMappingURL=vault.d.ts.map

package/dist/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,KAAK;IACpB,yGAAyG;IACzG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxH,yDAAyD;IACzD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,gCAAgC;IAChC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC1C;AAED,0GAA0G;AAC1G,eAAO,MAAM,QAAQ,QAAO,KAAK,GAAG;IAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAgB1G,CAAC"}

package/dist/vault.js

@@ -0,0 +1,25 @@
+// vault.ts — the Vault seam (ADR-8). A cord's deliverables are persisted as versioned artifacts; the cord
+// core depends ONLY on this interface, so the SAME run logic writes to an in-memory store (Node/verify), an
+// R2 bucket (the Worker — see worker/src/vault.ts), or Cloudflare Artifacts (the versioned git target,
+// deploy-time). H3 = "every assess leaves a versioned deliverable" — the runtime calls vault.put() once the
+// deepsec gate has redacted the output.
+import { hashHex } from "./hash.js";
+/** In-memory Vault — the verify/Node default and the H3 red-test substrate. Versions on repeated keys. */
+export const memVault = () => {
+    const store = new Map();
+    return {
+        store,
+        async put(key, body, meta) {
+            const version = (store.get(key)?.version ?? 0) + 1;
+            store.set(key, { body, version, meta });
+            return { key, version: String(version), hash: hashHex(body) };
+        },
+        async get(key) {
+            return store.get(key)?.body ?? null;
+        },
+        async list(prefix = "") {
+            return [...store.keys()].filter((k) => k.startsWith(prefix));
+        },
+    };
+};
+//# sourceMappingURL=vault.js.map

package/dist/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,4GAA4G;AAC5G,uGAAuG;AACvG,4GAA4G;AAC5G,wCAAwC;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,0GAA0G;AAC1G,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAsF,EAAE;IAC9G,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6D,CAAC;IACnF,OAAO;QACL,KAAK;QACL,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI;YACvB,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACnD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;YACxC,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChE,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG;YACX,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;QACtC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,EAAE;YACpB,OAAO,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QAC/D,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@op0ai/sdk",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The op0 SDK — an agent with a computer: a governed function under a RunSpec (goal + stop rules + verifier), typed ports, a vendor-free core. Build agents that run on op0 (op0.ai), the governed runtime for agent work. Proprietary — free to use WITH the op0 runtime.",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./guards": {
+      "types": "./dist/guards.d.ts",
+      "default": "./dist/guards.js"
+    },
+    "./vault": {
+      "types": "./dist/vault.d.ts",
+      "default": "./dist/vault.js"
+    },
+    "./hash": {
+      "types": "./dist/hash.d.ts",
+      "default": "./dist/hash.js"
+    },
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "default": "./dist/session.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "test": "node scripts/dep-lint.mjs && vitest run --passWithNoTests",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "node scripts/sync-sdk.mjs && node ../../scripts/publish-exports.mjs prepack",
+    "postpack": "node ../../scripts/publish-exports.mjs postpack"
+  },
+  "keywords": [
+    "op0",
+    "agents",
+    "agent",
+    "runtime",
+    "runspec",
+    "governance",
+    "cloudflare",
+    "workers",
+    "fleet"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/op0ai/op0dotdev.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://op0.ai",
+  "bugs": {
+    "url": "https://github.com/op0ai/op0dotdev/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts"
+}