comisai 1.0.41 → 1.0.44

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-executor-cores.js

@@ -0,0 +1,396 @@
+import { execFile } from "node:child_process";
+import { safePath, systemNowMs } from "@comis/core";
+import { createComisReadTool } from "../file-tools/read-tool.js";
+import { createComisGrepTool } from "../file-tools/grep-tool.js";
+import { createComisFindTool } from "../file-tools/find-tool.js";
+import { createComisLsTool } from "../file-tools/ls-tool.js";
+import { createWebSearchTool } from "../web-search-tool/index.js";
+/** An error-shaped honest-degrade (mirrors web-fetch-tool.ts:218-223). */
+function errorResult(error) {
+    return { error };
+}
+/** Bound a duckdb stderr diagnostic before it crosses the jail boundary (IN-04). */
+const DUCKDB_STDERR_MAX_CHARS = 500;
+/**
+ * Scrub a duckdb stderr diagnostic for the `{ error }` returned to the jailed
+ * client (IN-04). DuckDB error text can echo the offending SQL AND absolute host
+ * paths (e.g. a failed `read_json_auto('/abs/...')` names the path); the jailed
+ * client must never see daemon-side host paths. Replace any absolute path-like
+ * run (`/...`, `~/...`, `C:\...`) with `<path>` and bound the length. Pure.
+ *
+ * @param stderr - The raw duckdb stderr (may be empty).
+ * @returns A trimmed, length-bounded, path-scrubbed diagnostic.
+ */
+function scrubDuckDbStderr(stderr) {
+    return stderr
+        .trim()
+        .slice(0, DUCKDB_STDERR_MAX_CHARS)
+        // Unix abs path (/...), home (~/...), and Windows drive path (C:\...).
+        .replace(/(?:[A-Za-z]:\\|~?\/)[^\s'"]+/g, "<path>");
+}
+const DEFAULT_JQ_TIMEOUT_MS = 10_000;
+/** Bound the captured jq stdout so a huge slice cannot blow the daemon's heap. */
+const JQ_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+const DEFAULT_SQL_TIMEOUT_MS = 10_000;
+/** Bound the captured duckdb stdout so a huge slice cannot blow the daemon's heap. */
+const SQL_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+/**
+ * Build the DuckDB hardening prelude prepended before the (untrusted) model
+ * query on EVERY `-c` payload. The ORDER is load-bearing — each statement runs
+ * left-to-right and the security knobs LOCK once restrictive, so they must be
+ * set BEFORE the model query (which is appended after this prelude) so the query
+ * cannot widen them from inside its own SQL (CR-01):
+ *
+ *   1. `allowed_directories=['<workspaceDir>']` — the run's workspace is the ONLY
+ *      directory DuckDB may read; these allow-roots are queryable IRRESPECTIVE of
+ *      the master switch below (DuckDB >= 1.2). Set FIRST, while config is still
+ *      mutable, so the carve-out registers before the switch flips.
+ *   2. `enable_external_access=false` — the master external-access kill. Blocks
+ *      ALL local-file table functions (read_text/read_blob/read_csv/
+ *      read_json_auto/glob/…), ATTACH/COPY, the extension auto-installer's remote
+ *      fetch, and url-readers WHOLESALE — except reads under the allow-root above.
+ *      This is the real confinement (a keyword denylist cannot enumerate DuckDB's
+ *      growing reader surface); it makes a `read_text('/etc/passwd')` refuse even
+ *      if the keyword screen ever misses a reader. Self-locks once false.
+ *   3. autoinstall/autoload off — defense in depth alongside (2); the extension
+ *      auto-installer is the one path that touches the network.
+ *   4. `lock_configuration=true` — freeze ALL config so the appended model query
+ *      cannot `SET allowed_directories=...` / `SET enable_external_access=true`.
+ *
+ * @param workspaceDir - The lease-resolved workspace abs path (the sole allow-root).
+ * @returns The prelude string, ending in `; ` so the model query appends cleanly.
+ */
+function buildDuckDbHardeningPrelude(workspaceDir) {
+    // Single-quote-escape the workspace path for the SQL string-list literal
+    // (a data-dir / agent-id containing a quote must not break out — mirrors WR-01).
+    const escWs = workspaceDir.replace(/'/g, "''");
+    return (`SET allowed_directories=['${escWs}']; ` +
+        "SET enable_external_access=false; " +
+        "SET autoinstall_known_extensions=false; SET autoload_known_extensions=false; " +
+        "SET lock_configuration=true; ");
+}
+/**
+ * Statement keywords that let DuckDB install an extension, load one, attach an
+ * external database, or read/write a file/URL outside the confined `results/`
+ * input — the daemon-side SSRF / exfil / file-write surface (T-221-QRY-01). The
+ * query engine is a read-only slicer; ANY of these in a model-supplied query is
+ * refused BEFORE `duckdb` is ever spawned. Matched as whole words, case-insensitive.
+ */
+const DANGEROUS_SQL_KEYWORDS = [
+    "INSTALL",
+    "LOAD",
+    "ATTACH",
+    "DETACH",
+    "COPY",
+    "EXPORT",
+    "IMPORT",
+    "PRAGMA",
+];
+/**
+ * URL-reader scheme prefixes DuckDB's `read_*`/httpfs can reach off-host. Even
+ * with autoload off + readonly, a literal `http(s)://` / `s3://` / `gcs://` /
+ * `azure://` inside a reader is a remote-fetch attempt — refuse it (defense in
+ * depth alongside the extension lockdown). Matched as a case-insensitive substring.
+ */
+const DANGEROUS_URL_SCHEMES = ["http://", "https://", "s3://", "gcs://", "gs://", "azure://"];
+/**
+ * DuckDB local-file / environment table functions that have NO legitimate use
+ * over a tabular `results/` ResultRef — they read raw file bytes, enumerate a
+ * directory, or read a daemon env var from an ARBITRARY absolute host path with
+ * none of the {@link DANGEROUS_SQL_KEYWORDS} and no url-scheme (CR-01). The real
+ * confinement is `enable_external_access=false` + `allowed_directories` in
+ * {@link buildDuckDbHardeningPrelude} (which blocks ALL readers off the allow-root,
+ * including future ones); this denylist is belt-and-suspenders for the pure-exfil
+ * readers so they are refused BEFORE `duckdb` is ever spawned.
+ *
+ * Deliberately NOT listed (the documented tabular-query contract uses them, so
+ * they are confined by `allowed_directories`, never keyword-blocked):
+ * `read_csv`/`read_csv_auto`/`read_json`/`read_json_auto`/`read_ndjson`/
+ * `read_parquet`/`parquet_scan`. Matched as whole words, case-insensitive.
+ */
+const DANGEROUS_SQL_READERS = [
+    "READ_TEXT",
+    "READ_BLOB",
+    "GLOB",
+    "GETENV",
+    "PARQUET_METADATA",
+    "PARQUET_SCHEMA",
+];
+/**
+ * Screen a model-supplied DuckDB query for the extension / file-write / network
+ * verbs and url-readers a read-only slicer must never run (T-221-QRY-01). Pure —
+ * returns a human reason on the FIRST hit, or `null` when the query is safe to
+ * spawn. Called BEFORE `execFile` so a malicious query NEVER reaches `duckdb`.
+ *
+ * @param query - The model-supplied SQL (already path-confined at the core).
+ * @returns A rejection reason string, or `null` if the query is allowed.
+ */
+export function rejectDangerousSql(query) {
+    const upper = query.toUpperCase();
+    for (const kw of DANGEROUS_SQL_KEYWORDS) {
+        // Whole-word match so `INSTALLED_AT` (a column) does not trip on `INSTALL`.
+        // \b handles the surrounding punctuation/space DuckDB statements use.
+        if (new RegExp(`\\b${kw}\\b`).test(upper)) {
+            return `sql rejected: the \`${kw}\` statement is not allowed on the read-only query surface`;
+        }
+    }
+    for (const reader of DANGEROUS_SQL_READERS) {
+        // Whole-word match so a column/table named e.g. `glob_count` does not trip.
+        if (new RegExp(`\\b${reader}\\b`).test(upper)) {
+            return `sql rejected: the \`${reader.toLowerCase()}\` reader is not allowed — the query may only read the run-scoped results/ file (use read_json_auto/read_csv/read_parquet)`;
+        }
+    }
+    const lower = query.toLowerCase();
+    for (const scheme of DANGEROUS_URL_SCHEMES) {
+        if (lower.includes(scheme)) {
+            return `sql rejected: remote url readers (${scheme}…) are not allowed — the query may only read the run-scoped results/ file`;
+        }
+    }
+    return null;
+}
+/**
+ * A safe JSONPath expression for the `jsonpath` core: a `$`-rooted dot/bracket
+ * path of identifiers and numeric indices only — e.g. `$.items[0].price`,
+ * `$['a']['b']`, `$`. Deliberately conservative: NO wildcards, filters, slices,
+ * functions, or quotes-with-metacharacters, so the compiled `json_extract` path
+ * literal can never carry SQL/quote injection into the DuckDB statement.
+ */
+const SAFE_JSONPATH_RE = /^\$(\.[A-Za-z_][A-Za-z0-9_]*|\[\d+\]|\['[A-Za-z0-9_ -]+'\]|\["[A-Za-z0-9_ -]+"\])*$/;
+/**
+ * Validate a model-supplied JSONPath expression for the `jsonpath` core. Pure —
+ * returns `true` only for the conservative `$`-rooted dot/bracket grammar above.
+ * A `false` is honest-degraded to `{ error }` by the core (never a throw). This
+ * is the no-eval safety floor: the expression becomes a `json_extract(j, '<expr>')`
+ * literal, so it must contain no SQL metacharacters / unmatched quotes.
+ *
+ * @param expr - The model-supplied JSONPath.
+ * @returns `true` if the expression is a safe dot/bracket path, else `false`.
+ */
+export function isSafeJsonPath(expr) {
+    return SAFE_JSONPATH_RE.test(expr);
+}
+/**
+ * Build the shipped daemon-side cores for the orchestrate `tool.invoke` executor.
+ * See the module doc for the per-core composition + the jq containment.
+ */
+export function createOrchestrateExecutorCores(deps) {
+    const log = deps.logger.child({ submodule: "orchestrate-executor-cores" });
+    const jqTimeoutMs = deps.jqTimeoutMs ?? DEFAULT_JQ_TIMEOUT_MS;
+    const sqlTimeoutMs = deps.sqlTimeoutMs ?? DEFAULT_SQL_TIMEOUT_MS;
+    // The shipped web-search tool is multi-provider + cache-bearing — construct it
+    // ONCE (the cache is module-level + factory-shared).
+    const webSearchTool = createWebSearchTool(deps.webSearchConfig);
+    /**
+     * Adapt a SHIPPED file-tool factory into an {@link OrchestrateFileCore}: build
+     * the AgentTool under `ctx.workspaceDir` (path-confined by the factory's own
+     * `safePath` wrapping) and `.execute()` it. Per-call construction is cheap
+     * (no I/O at build) and keeps each call scoped to the lease's workspace.
+     */
+    function fileCore(factory, toolName) {
+        return async (args, ctx) => {
+            const started = systemNowMs();
+            const tool = factory(ctx.workspaceDir);
+            const result = await tool.execute("tool.invoke", args);
+            log.debug({ step: "file-core", toolName, durationMs: systemNowMs() - started }, "orchestrate file core executed");
+            return result;
+        };
+    }
+    /**
+     * The `jq` core (READ-02): resolve the workspace-confined path and run the
+     * system `jq` over it (no shell — `execFile`). Returns the parsed slice, or a
+     * content-free `{ error }` on a bad path / missing binary / non-zero exit.
+     */
+    const jq = async (args, ctx) => {
+        const started = systemNowMs();
+        const rawPath = typeof args.path === "string" ? args.path : "";
+        const expr = typeof args.expr === "string" ? args.expr : ".";
+        if (rawPath === "") {
+            log.warn({ errorKind: "validation", hint: "jq called without a string `path` to a results/ file", toolName: "jq" }, "orchestrate jq missing path");
+            return errorResult("jq requires a string `path`");
+        }
+        // Confine the path under the workspace (the ResultRef ref is workspace-relative).
+        let absPath;
+        try {
+            absPath = safePath(ctx.workspaceDir, rawPath);
+        }
+        catch (err) {
+            log.warn({ err, errorKind: "validation", hint: "jq path escaped the workspace — refusing", toolName: "jq" }, "orchestrate jq path traversal blocked");
+            return errorResult("jq path escapes the workspace");
+        }
+        log.debug({ step: "jq-spawn", toolName: "jq" }, "orchestrate jq spawning");
+        return await new Promise((resolve) => {
+            execFile("jq", 
+            // `--compact-output` so the slice is line-bounded JSON; `--` ends options
+            // so a hostile `expr` cannot be read as a flag. The path is the confined
+            // absolute path (validated above), never the caller's raw segment.
+            ["--compact-output", "--", expr, absPath], { timeout: jqTimeoutMs, maxBuffer: JQ_MAX_BUFFER_BYTES, encoding: "utf8" }, (err, stdout, stderr) => {
+                if (err) {
+                    const code = err.code;
+                    const missing = code === "ENOENT";
+                    log.warn({
+                        err,
+                        errorKind: missing ? "precondition" : "validation",
+                        hint: missing
+                            ? "the `jq` binary is not installed on the host — install jq to slice ResultRefs in-jail"
+                            : "jq exited non-zero (a bad filter or non-JSON input)",
+                        toolName: "jq",
+                    }, "orchestrate jq failed");
+                    resolve(errorResult(missing ? "jq is not installed on the host" : `jq error: ${stderr.trim() || "non-zero exit"}`));
+                    return;
+                }
+                log.debug({ step: "jq-done", toolName: "jq", durationMs: systemNowMs() - started }, "orchestrate jq complete");
+                // Return the raw compact-JSON text — the in-jail SDK parses it. (We do
+                // not JSON.parse here: a jq stream of multiple values is not a single
+                // JSON document, so the text slice is the honest return.)
+                resolve(stdout);
+            });
+        });
+    };
+    /**
+     * Run a model-supplied DuckDB query (already screened by `rejectDangerousSql` /
+     * `isSafeJsonPath` at the calling core) through the HARDENED CLI and resolve the
+     * JSON-rows slice (or a content-free `{ error }`). `--readonly :memory:` (no DB
+     * file / no writes), `-json` (rows on stdout), `-c` (one statement) with the
+     * autoload-off prelude prepended. A missing `duckdb` binary →
+     * `errorKind:"precondition"` (the install prerequisite is unmet); a non-zero
+     * exit (bad SQL / non-table input) → `errorKind:"validation"`. Never throws —
+     * mirrors the jq ENOENT/non-zero branches.
+     */
+    function runDuckDb(query, workspaceDir, toolName, started) {
+        log.debug({ step: "duckdb-spawn", toolName }, "orchestrate duckdb spawning");
+        // Confine the daemon-side duckdb to the run's workspace: the prelude sets
+        // allowed_directories=[<ws>] + enable_external_access=false + lock BEFORE the
+        // (untrusted) model query (CR-01), and the process cwd is the workspace so a
+        // workspace-relative `results/...` read resolves inside the allow-root rather
+        // than against the daemon's cwd.
+        const payload = buildDuckDbHardeningPrelude(workspaceDir) + query;
+        return new Promise((resolve) => {
+            execFile("duckdb", ["--readonly", ":memory:", "-json", "-c", payload], { cwd: workspaceDir, timeout: sqlTimeoutMs, maxBuffer: SQL_MAX_BUFFER_BYTES, encoding: "utf8" }, (err, stdout, stderr) => {
+                if (err) {
+                    const code = err.code;
+                    const missing = code === "ENOENT";
+                    log.warn({
+                        err,
+                        errorKind: missing ? "precondition" : "validation",
+                        hint: missing
+                            ? "the `duckdb` binary is not installed on the host — install duckdb (pinned static binary) to run SQL/JSONPath over ResultRefs"
+                            : "duckdb exited non-zero (bad SQL or non-table input)",
+                        toolName,
+                    }, "orchestrate duckdb failed");
+                    resolve(errorResult(missing
+                        ? "duckdb is not installed on the host"
+                        : // Scrub absolute host paths + bound length before the error
+                            // crosses the jail boundary (IN-04): a duckdb diagnostic can
+                            // echo the offending SQL/path; the jailed client must not see
+                            // daemon-side host paths.
+                            `duckdb error: ${scrubDuckDbStderr(stderr) || "non-zero exit"}`));
+                    return;
+                }
+                log.debug({ step: "duckdb-done", toolName, durationMs: systemNowMs() - started }, "orchestrate duckdb complete");
+                // Return the raw `-json` rows text — the in-jail SDK parses it (mirrors jq).
+                resolve(stdout);
+            });
+        });
+    }
+    /**
+     * The `sql` core (QRY-01): run a model-supplied DuckDB query over the
+     * workspace-confined ResultRef file. Path-confined (`safePath`), then screened
+     * (`rejectDangerousSql` — INSTALL/LOAD/ATTACH/COPY/EXPORT/url-readers refused
+     * BEFORE any spawn, the SSRF/exfil floor), then run through the hardened
+     * `runDuckDb`. Returns the JSON-rows slice, or a content-free `{ error }`.
+     */
+    const sql = async (args, ctx) => {
+        const started = systemNowMs();
+        const rawPath = typeof args.path === "string" ? args.path : "";
+        const query = typeof args.query === "string" ? args.query : "";
+        if (rawPath === "") {
+            log.warn({ errorKind: "validation", hint: "sql called without a string `path` to a results/ file", toolName: "sql" }, "orchestrate sql missing path");
+            return errorResult("sql requires a string `path`");
+        }
+        if (query === "") {
+            log.warn({ errorKind: "validation", hint: "sql called without a string `query`", toolName: "sql" }, "orchestrate sql missing query");
+            return errorResult("sql requires a string `query`");
+        }
+        // Confine the path under the workspace (the ResultRef ref is workspace-relative).
+        try {
+            safePath(ctx.workspaceDir, rawPath);
+        }
+        catch (err) {
+            log.warn({ err, errorKind: "validation", hint: "sql path escaped the workspace — refusing", toolName: "sql" }, "orchestrate sql path traversal blocked");
+            return errorResult("sql path escapes the workspace");
+        }
+        // Screen the model query for extension / file-write / network verbs, the
+        // pure-exfil local-file readers, + url readers BEFORE spawning duckdb
+        // (T-221-QRY-01 / CR-01) — refuse, never spawn, on a hit. The running duckdb
+        // is ALSO confined to the workspace via the hardening prelude (defense in depth).
+        const rejection = rejectDangerousSql(query);
+        if (rejection !== null) {
+            log.warn({ errorKind: "validation", hint: "sql query contained a disallowed extension/file-write/network verb, an exfil reader, or a url-reader — refusing before spawn", toolName: "sql" }, "orchestrate sql dangerous query blocked");
+            return errorResult(rejection);
+        }
+        return await runDuckDb(query, ctx.workspaceDir, "sql", started);
+    };
+    /**
+     * The `jsonpath` core (QRY-02): extract a precise value from a JSON ResultRef
+     * via DuckDB `json_extract` — NO eval-based JSONPath library (banned, RCE CVEs).
+     * Path-confined (`safePath`), the expr validated to a conservative `$`-dot/bracket
+     * grammar (`isSafeJsonPath`) so it carries no SQL/quote injection, then compiled
+     * into a `json_extract` query run through the SAME hardened `runDuckDb` as `sql`.
+     */
+    const jsonpath = async (args, ctx) => {
+        const started = systemNowMs();
+        const rawPath = typeof args.path === "string" ? args.path : "";
+        const expr = typeof args.expr === "string" ? args.expr : "";
+        if (rawPath === "") {
+            log.warn({ errorKind: "validation", hint: "jsonpath called without a string `path` to a results/ file", toolName: "jsonpath" }, "orchestrate jsonpath missing path");
+            return errorResult("jsonpath requires a string `path`");
+        }
+        if (expr === "") {
+            log.warn({ errorKind: "validation", hint: "jsonpath called without a string `expr`", toolName: "jsonpath" }, "orchestrate jsonpath missing expr");
+            return errorResult("jsonpath requires a string `expr`");
+        }
+        // Confine the path under the workspace.
+        let absPath;
+        try {
+            absPath = safePath(ctx.workspaceDir, rawPath);
+        }
+        catch (err) {
+            log.warn({ err, errorKind: "validation", hint: "jsonpath path escaped the workspace — refusing", toolName: "jsonpath" }, "orchestrate jsonpath path traversal blocked");
+            return errorResult("jsonpath path escapes the workspace");
+        }
+        // Validate the JSONPath to the conservative dot/bracket grammar so it cannot
+        // inject SQL/quotes into the json_extract literal (the no-eval safety floor,
+        // T-221-QRY-03). Refused BEFORE any spawn.
+        if (!isSafeJsonPath(expr)) {
+            log.warn({ errorKind: "validation", hint: "jsonpath expr is not a safe $-rooted dot/bracket path — refusing", toolName: "jsonpath" }, "orchestrate jsonpath unsafe expr blocked");
+            return errorResult("jsonpath expr must be a $-rooted dot/bracket path (e.g. $.items[0].price) — wildcards/filters/functions are not supported");
+        }
+        // Compile the JSONPath into a DuckDB json_extract query over read_json_auto.
+        // The path literal is the safePath-confined absolute path; the expr passed the
+        // grammar gate above. read_json_auto yields one row of the doc as `j`.
+        // WR-01: single-quote-escape absPath before interpolating it into the SQL
+        // string literal. `safePath` confines the LOCATION (under the workspace) but
+        // does NOT escape SQL metacharacters; an operator data-dir / agent-id
+        // containing a `'` (agentId is only z.string().min(1)) would otherwise break
+        // out of the literal. Double the quote per SQL string-literal escaping.
+        const escPath = absPath.replace(/'/g, "''");
+        const query = `SELECT json_extract(j, '${expr}') AS value FROM read_json_auto('${escPath}') t(j)`;
+        return await runDuckDb(query, ctx.workspaceDir, "jsonpath", started);
+    };
+    const fileExecutors = {
+        read: fileCore((w) => createComisReadTool(w), "read"),
+        grep: fileCore((w) => createComisGrepTool(w), "grep"),
+        find: fileCore((w) => createComisFindTool(w), "find"),
+        ls: fileCore((w) => createComisLsTool(w), "ls"),
+        jq,
+        sql,
+        jsonpath,
+    };
+    const webSearch = async (args, _ctx) => {
+        const started = systemNowMs();
+        const result = await webSearchTool.execute("tool.invoke", args);
+        log.debug({ step: "web-search-core", toolName: "web_search", durationMs: systemNowMs() - started }, "orchestrate web_search core executed");
+        return result;
+    };
+    return { fileExecutors, webSearch };
+}

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-sdk-runtime.d.ts

@@ -0,0 +1,62 @@
+import type { ResultRef } from "@comis/core";
+/**
+ * A ResultRef decorated with the §23.9 in-jail extraction helpers (REF-02). The
+ * big (untrusted) payload stays materialized on the jailed workspace as DATA;
+ * these helpers slice it IN-JAIL via the `orch:read`-gated read/grep/jq/sql/
+ * jsonpath tools so only the relevant rows/lines re-enter context — the full
+ * payload never does.
+ */
+export interface WrappedResultRef extends ResultRef {
+    /** Grep the materialized file for `pattern`; returns the matching lines (orch:read). */
+    grep(pattern: string): Promise<string>;
+    /** Run a jq `expr` over the materialized JSON/JSONL; returns the result (orch:read). */
+    jq(expr: string): Promise<unknown>;
+    /** Run DuckDB SQL over the materialized CSV/JSONL/JSON; returns the row slice (orch:read). */
+    sql(query: string): Promise<unknown>;
+    /** Extract a precise value via a JSONPath `$`-expr (DuckDB json_extract) (orch:read). */
+    jsonpath(expr: string): Promise<unknown>;
+    /** Read a bounded slice of the materialized file (`offset`/`limit`) (orch:read). */
+    read(offset?: number, limit?: number): Promise<string>;
+}
+/**
+ * Send one `{ bearer, method, params }` line over the cap socket for an ARBITRARY
+ * method and resolve with the `{ result }` (or reject with the `{ error }`). One
+ * connection per call mirrors the endpoint's per-connection request/response
+ * framing exactly. The `method` and `params` are passed THROUGH verbatim — the
+ * caller decides whether it is a `tool.invoke` (see {@link invoke}) or a direct
+ * orchestration method (`session.spawn`, `graph.execute`, `cron.add`, …, the
+ * `comis-agent` CLI-04 subcommands). The lease (`COMIS_CAP_LEASE`) authenticates
+ * every call; the unix cap socket (`COMIS_ORCH_SOCKET`) is the only egress — this
+ * is deliberately NOT the loopback gateway WebSocket (the wire CLI-04 forbids).
+ *
+ * @param method - The wire method (e.g. `"tool.invoke"`, `"session.spawn"`).
+ * @param params - The method params, forwarded verbatim (no envelope wrapping).
+ * @returns The endpoint's `result` field.
+ * @throws When the lease env is absent (only valid inside an orchestrate jail),
+ *   when the endpoint replies `{ error }`, or when the reply line is malformed /
+ *   the connection closes before a complete reply (a containment fault).
+ */
+export declare function callCapSocket(method: string, params: Record<string, unknown>): Promise<unknown>;
+/**
+ * Send one `{ bearer, method: "tool.invoke", params: { tool, args } }` line over
+ * the cap socket and resolve with the `{ result }`. This is the `tool.invoke`
+ * specialization of {@link callCapSocket} — the stable contract the generated
+ * `comis_tools.js` imports; every typed SDK method delegates here.
+ *
+ * @param tool - The capability-mapped tool name (e.g. `"memory_search"`).
+ * @param args - The tool's arguments (forwarded verbatim as `params.args`).
+ * @returns The tool result (the endpoint's `result` field).
+ * @throws When the lease env is absent (only valid inside an orchestrate jail),
+ *   when the endpoint replies `{ error }`, or when the reply line is malformed.
+ */
+export declare function invoke(tool: string, args?: Record<string, unknown>): Promise<unknown>;
+/**
+ * Decorate a {@link ResultRef} with the in-jail extraction helpers (REF-02). The
+ * generated SDK calls this for the high-volume tool returns; the helpers route
+ * through {@link invoke} to the `orch:read`-gated read/grep/jq tools over the
+ * materialized `results/` file, so only the requested slice re-enters context.
+ *
+ * @param ref - The materialized result handle (from a tool return).
+ * @returns The same handle plus `.read`/`.grep`/`.jq` extraction methods.
+ */
+export declare function wrapResultRef(ref: ResultRef): WrappedResultRef;

package/node_modules/@comis/skills/dist/tools/builtin/orchestrate/orchestrate-sdk-runtime.js

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `orchestrate-sdk-runtime` — the cap-socket CLIENT the in-jail autonomy surface
+ * speaks. {@link callCapSocket} is the generalized wire primitive: one
+ * `{ bearer, method, params }` newline-JSON line over the lease-authenticated
+ * unix cap socket for an ARBITRARY method, resolving the `{ result }` (or
+ * rejecting the `{ error }`). {@link invoke} is its `tool.invoke` specialization
+ * — the stable `./orchestrate-sdk-runtime.js` contract the generated
+ * `comis_tools.js` imports (`invoke` + `wrapResultRef`), where each typed SDK
+ * method delegates to {@link invoke}. `comis-agent`'s direct-method subcommands
+ * (CLI-04) ride {@link callCapSocket} directly so they can dispatch a non-tool
+ * method (`session.spawn`, `graph.execute`, …) without the `tool.invoke`
+ * envelope. Both speak the exact wire the Phase-211 capability endpoint serves
+ * (`setup-capability-endpoint.ts` — one `{ bearer, method, params }` line per
+ * connection → one `{ result }` / `{ error }` line back).
+ *
+ * Containment context (why this is tiny + dependency-free, AGENTS.md §2.3): this
+ * module runs INSIDE the orchestrate jail (`--unshare-net`, `~/.comis` masked).
+ * The cap socket bound into the jail is the ONLY reachable egress; the lease
+ * (`COMIS_CAP_LEASE`) authenticates every call, audience-bound at the endpoint.
+ * So the runtime needs nothing but `node:net` + JSON — there is deliberately NO
+ * WebSocket / gateway client: that loopback gateway transport is unreachable
+ * from the `--unshare-net` jail and is the very wire CLI-04 forbids.
+ *
+ * Globals rule (AGENTS.md §2.2): this runtime executes INSIDE the jail, which has
+ * NO `node_modules` — so it MUST be self-contained (node built-ins only). It
+ * therefore reads the two lease env vars via a local `process.env` accessor rather
+ * than importing `@comis/core`'s `systemGetEnv` seam: that import is unreachable
+ * from the jail and would make EVERY `comis_tools` import fail `ERR_MODULE_NOT_FOUND`
+ * (live VPS finding 2026-06-23 — guarded by `orchestrate-sdk-self-contained.test.ts`).
+ *
+ * @module
+ */
+import * as net from "node:net";
+/**
+ * Read an env var inside the jail. Inlined (not `@comis/core`'s `systemGetEnv`)
+ * because the jailed runtime has no `node_modules` to resolve it from; `process.env`
+ * is the only env access available here.
+ */
+// eslint-disable-next-line no-restricted-syntax -- jailed runtime: process.env is the sole env source (no @comis/core seam reachable in the jail)
+const systemGetEnv = (name) => process.env[name];
+/** The method the runtime always sends — the one-route dispatch (v8 §6.2). */
+const TOOL_INVOKE_METHOD = "tool.invoke";
+/** The lease env var the cap socket authenticates each call with. */
+const ENV_CAP_LEASE = "COMIS_CAP_LEASE";
+/** The unix-socket path the cap endpoint listens on (bound into the jail). */
+const ENV_ORCH_SOCKET = "COMIS_ORCH_SOCKET";
+/**
+ * Send one `{ bearer, method, params }` line over the cap socket for an ARBITRARY
+ * method and resolve with the `{ result }` (or reject with the `{ error }`). One
+ * connection per call mirrors the endpoint's per-connection request/response
+ * framing exactly. The `method` and `params` are passed THROUGH verbatim — the
+ * caller decides whether it is a `tool.invoke` (see {@link invoke}) or a direct
+ * orchestration method (`session.spawn`, `graph.execute`, `cron.add`, …, the
+ * `comis-agent` CLI-04 subcommands). The lease (`COMIS_CAP_LEASE`) authenticates
+ * every call; the unix cap socket (`COMIS_ORCH_SOCKET`) is the only egress — this
+ * is deliberately NOT the loopback gateway WebSocket (the wire CLI-04 forbids).
+ *
+ * @param method - The wire method (e.g. `"tool.invoke"`, `"session.spawn"`).
+ * @param params - The method params, forwarded verbatim (no envelope wrapping).
+ * @returns The endpoint's `result` field.
+ * @throws When the lease env is absent (only valid inside an orchestrate jail),
+ *   when the endpoint replies `{ error }`, or when the reply line is malformed /
+ *   the connection closes before a complete reply (a containment fault).
+ */
+export function callCapSocket(method, params) {
+    const socketPath = systemGetEnv(ENV_ORCH_SOCKET);
+    const bearer = systemGetEnv(ENV_CAP_LEASE);
+    if (!socketPath || !bearer) {
+        return Promise.reject(new Error(`comis-agent / orchestrate runtime requires ${ENV_ORCH_SOCKET}/${ENV_CAP_LEASE} — ` +
+            `only valid inside an orchestrate jail`));
+    }
+    const payload = JSON.stringify({ bearer, method, params }) + "\n";
+    return new Promise((resolve, reject) => {
+        const socket = net.connect(socketPath);
+        let buf = "";
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            fn();
+        };
+        socket.setEncoding("utf8");
+        socket.on("connect", () => {
+            socket.write(payload);
+        });
+        socket.on("data", (chunk) => {
+            buf += chunk;
+            const nl = buf.indexOf("\n");
+            if (nl === -1)
+                return;
+            const line = buf.slice(0, nl);
+            let reply;
+            try {
+                reply = JSON.parse(line);
+            }
+            catch {
+                finish(() => reject(new Error(`malformed response from cap socket: ${line.slice(0, 120)}`)));
+                return;
+            }
+            if (reply.error !== undefined) {
+                const message = typeof reply.error === "string" ? reply.error : "capability call failed";
+                finish(() => reject(new Error(message)));
+                return;
+            }
+            finish(() => resolve(reply.result));
+        });
+        socket.on("error", (err) => {
+            finish(() => reject(err));
+        });
+        // The endpoint `socket.end()`s after the reply line. If it closes without a
+        // newline-terminated reply, surface a malformed/empty-response error rather
+        // than hanging (a closed connection mid-protocol is a containment fault).
+        socket.on("close", () => {
+            finish(() => reject(new Error("cap socket closed before a complete response line")));
+        });
+    });
+}
+/**
+ * Send one `{ bearer, method: "tool.invoke", params: { tool, args } }` line over
+ * the cap socket and resolve with the `{ result }`. This is the `tool.invoke`
+ * specialization of {@link callCapSocket} — the stable contract the generated
+ * `comis_tools.js` imports; every typed SDK method delegates here.
+ *
+ * @param tool - The capability-mapped tool name (e.g. `"memory_search"`).
+ * @param args - The tool's arguments (forwarded verbatim as `params.args`).
+ * @returns The tool result (the endpoint's `result` field).
+ * @throws When the lease env is absent (only valid inside an orchestrate jail),
+ *   when the endpoint replies `{ error }`, or when the reply line is malformed.
+ */
+export function invoke(tool, args) {
+    return callCapSocket(TOOL_INVOKE_METHOD, { tool, args: args ?? {} });
+}
+/**
+ * Decorate a {@link ResultRef} with the in-jail extraction helpers (REF-02). The
+ * generated SDK calls this for the high-volume tool returns; the helpers route
+ * through {@link invoke} to the `orch:read`-gated read/grep/jq tools over the
+ * materialized `results/` file, so only the requested slice re-enters context.
+ *
+ * @param ref - The materialized result handle (from a tool return).
+ * @returns The same handle plus `.read`/`.grep`/`.jq` extraction methods.
+ */
+export function wrapResultRef(ref) {
+    return {
+        ...ref,
+        grep(pattern) {
+            return invoke("grep", { path: ref.ref, pattern });
+        },
+        jq(expr) {
+            return invoke("jq", { path: ref.ref, expr });
+        },
+        sql(query) {
+            return invoke("sql", { path: ref.ref, query });
+        },
+        jsonpath(expr) {
+            return invoke("jsonpath", { path: ref.ref, expr });
+        },
+        read(offset, limit) {
+            return invoke("read", { path: ref.ref, offset, limit });
+        },
+    };
+}