lorenz 0.1.0

package/packages/ssh/dist/index.js

@@ -0,0 +1,281 @@
+import path from "node:path";
+import { accessSync, constants } from "node:fs";
+import { setTimeout, clearTimeout } from "node:timers";
+import { setTimeout as delay } from "node:timers/promises";
+import { execa } from "execa";
+const DEFAULT_SSH_TIMEOUT_MS = 60_000;
+const FORCE_KILL_DELAY_MS = 5_000;
+const DEFAULT_REMOTE_TCP_PORT_READY_TIMEOUT_MS = 10_000;
+const DEFAULT_REMOTE_TCP_PORT_READY_INTERVAL_MS = 200;
+const DEFAULT_REMOTE_TCP_PORT_READY_ATTEMPT_TIMEOUT_MS = 1_000;
+const TCP_PORT_MAX = 65_535;
+const NUMERIC_CHMOD_MODE = /^[0-7]{3,4}$/;
+const SYMBOLIC_CHMOD_MODE = /^(?:[ugoa]*(?:(?:[+-][rwxXstugo]+)|(?:=[rwxXstugo]*)))(?:,(?:[ugoa]*(?:(?:[+-][rwxXstugo]+)|(?:=[rwxXstugo]*))))*$/;
+function requireSshExecutable() {
+    const pathValue = process.env.PATH ?? "";
+    for (const directory of pathValue.split(path.delimiter)) {
+        if (!directory)
+            continue;
+        const executable = path.join(directory, "ssh");
+        try {
+            accessSync(executable, constants.X_OK);
+            return executable;
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error("ssh_not_found");
+}
+export async function runSsh(host, command, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SSH_TIMEOUT_MS;
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0)
+        throw new Error(`invalid_ssh_timeout: ${timeoutMs}`);
+    if (options.abortSignal?.aborted)
+        throw new Error(`ssh_aborted: ${host}`);
+    try {
+        // Spawn in its own process group (detached) so we can kill the entire group on timeout.
+        // execa's built-in timeout only signals the direct child, leaving sub-processes alive
+        // with open pipes that block resolution until they exit naturally.
+        // SIGTERM first to allow trap handlers / graceful shutdown; SIGKILL after 5s as fallback.
+        // TODO - this may not be enough to ensure the remote ssh process cleans up its children
+        const subprocess = execa("ssh", sshArgs(host, command), {
+            reject: false,
+            ...(options.stderrToStdout ? { all: true } : {}),
+            stdin: "ignore",
+            stripFinalNewline: false,
+            detached: true,
+        });
+        let timeoutTimer;
+        let forceKillTimer;
+        let terminationRequested = false;
+        let abortHandler;
+        const killProcessGroup = (signal) => {
+            try {
+                process.kill(-subprocess.pid, signal);
+            }
+            catch {
+                /* process already exited */
+            }
+        };
+        const forceKillProcessGroup = () => {
+            forceKillTimer ??= setTimeout(() => {
+                killProcessGroup("SIGKILL");
+            }, FORCE_KILL_DELAY_MS);
+        };
+        const clearTimers = () => {
+            if (timeoutTimer !== undefined)
+                clearTimeout(timeoutTimer);
+            // After timeout, descendants can still hold inherited pipes open even if the direct child exits.
+            if (!terminationRequested && forceKillTimer !== undefined)
+                clearTimeout(forceKillTimer);
+            if (abortHandler)
+                options.abortSignal?.removeEventListener("abort", abortHandler);
+        };
+        const clearForceKillTimer = () => {
+            if (forceKillTimer !== undefined)
+                clearTimeout(forceKillTimer);
+        };
+        const terminate = (error, reject) => {
+            terminationRequested = true;
+            killProcessGroup("SIGTERM");
+            forceKillProcessGroup();
+            reject(error);
+        };
+        const timeout = new Promise((_, reject) => {
+            timeoutTimer = setTimeout(() => {
+                terminate(new Error(`ssh_timeout: ${host} ${timeoutMs}`), reject);
+            }, timeoutMs);
+        });
+        const abort = new Promise((_, reject) => {
+            if (!options.abortSignal)
+                return;
+            abortHandler = () => terminate(new Error(`ssh_aborted: ${host}`), reject);
+            options.abortSignal.addEventListener("abort", abortHandler, { once: true });
+        });
+        void subprocess.then(clearForceKillTimer, clearForceKillTimer);
+        const result = await Promise.race([subprocess, timeout, abort]).finally(clearTimers);
+        if (result.code === "ENOENT")
+            throw new Error("ssh_not_found");
+        if (typeof result.exitCode !== "number")
+            throw sshMissingExitCodeError(host, result);
+        return {
+            stdout: options.stderrToStdout ? (result.all ?? "") : result.stdout,
+            stderr: options.stderrToStdout ? "" : result.stderr,
+            status: result.exitCode,
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT")
+            throw new Error("ssh_not_found", { cause: error });
+        throw error;
+    }
+}
+export function startSshProcess(host, command) {
+    return execa("ssh", sshArgs(host, command), {
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe",
+        reject: false,
+    });
+}
+export function startReverseTunnel(host, remotePort, localHost, localPort) {
+    return execa(requireSshExecutable(), reverseTunnelArgs(host, remotePort, localHost, localPort), {
+        stdin: "pipe",
+        stdout: "pipe",
+        stderr: "pipe",
+        reject: false,
+    });
+}
+export async function waitForRemoteTcpPort(host, remotePort, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_REMOTE_TCP_PORT_READY_TIMEOUT_MS;
+    const intervalMs = options.intervalMs ?? DEFAULT_REMOTE_TCP_PORT_READY_INTERVAL_MS;
+    const attemptTimeoutMs = options.attemptTimeoutMs ?? DEFAULT_REMOTE_TCP_PORT_READY_ATTEMPT_TIMEOUT_MS;
+    if (!Number.isInteger(remotePort) || remotePort <= 0 || remotePort > TCP_PORT_MAX) {
+        throw new Error(`invalid_remote_tcp_port: ${remotePort}`);
+    }
+    if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+        throw new Error(`invalid_remote_tcp_port_ready_timeout: ${timeoutMs}`);
+    }
+    if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
+        throw new Error(`invalid_remote_tcp_port_ready_interval: ${intervalMs}`);
+    }
+    if (!Number.isInteger(attemptTimeoutMs) || attemptTimeoutMs <= 0) {
+        throw new Error(`invalid_remote_tcp_port_ready_attempt_timeout: ${attemptTimeoutMs}`);
+    }
+    const deadline = Date.now() + timeoutMs;
+    let lastFailure;
+    while (Date.now() < deadline) {
+        const remainingMs = Math.max(1, deadline - Date.now());
+        try {
+            const result = await runSsh(host, `: < /dev/tcp/127.0.0.1/${remotePort}`, {
+                stderrToStdout: true,
+                timeoutMs: Math.min(attemptTimeoutMs, remainingMs),
+            });
+            if (result.status === 0)
+                return;
+            lastFailure = new Error(`remote_tcp_probe_status: ${result.status} ${result.stdout}`);
+        }
+        catch (error) {
+            lastFailure = error;
+        }
+        const sleepMs = Math.min(intervalMs, Math.max(0, deadline - Date.now()));
+        if (sleepMs > 0)
+            await delay(sleepMs);
+    }
+    throw new Error(`remote_tcp_port_unreachable: ${host} ${remotePort}`, {
+        cause: lastFailure,
+    });
+}
+export async function writeRemoteFile(host, remotePath, contents, options = {}) {
+    const command = [
+        `mkdir -p ${shellEscape(path.posix.dirname(remotePath))}`,
+        `printf '%s' ${shellEscape(contents)} > ${shellEscape(remotePath)}`,
+        chmodCommand(options.mode, remotePath),
+    ].join("\n");
+    const result = await runSsh(host, command, { ...options, stderrToStdout: true });
+    if (result.status !== 0)
+        throw new Error(`remote_write_failed: ${result.status} ${result.stdout}`);
+}
+export function sshArgs(host, command) {
+    const target = parseSshTarget(host);
+    return [
+        ...sshConfigArgs(),
+        "-T",
+        ...(target.port ? ["-p", target.port] : []),
+        "--",
+        target.destination,
+        remoteShellCommand(command),
+    ];
+}
+export function reverseTunnelArgs(host, remotePort, localHost, localPort) {
+    const target = parseSshTarget(host);
+    return [
+        ...sshConfigArgs(),
+        "-T",
+        "-N",
+        "-o",
+        "ExitOnForwardFailure=yes",
+        ...(target.port ? ["-p", target.port] : []),
+        "-R",
+        `${remotePort}:${localHost}:${localPort}`,
+        "--",
+        target.destination,
+    ];
+}
+export function remoteShellCommand(command) {
+    return `bash -lc ${shellEscape(command)}`;
+}
+export function shellEscape(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+export function parseSshTarget(target) {
+    const trimmed = target.trim();
+    const match = /^(.*):(\d+)$/.exec(trimmed);
+    if (!match)
+        return { destination: validateSshDestination(trimmed), port: null };
+    const destination = match[1] ?? "";
+    const port = match[2] ?? "";
+    if (validPortDestination(destination))
+        return { destination: validateSshDestination(destination), port };
+    return { destination: validateSshDestination(trimmed), port: null };
+}
+function sshMissingExitCodeError(host, result) {
+    const killed = result.killed ?? result.isTerminated ?? result.isForcefullyTerminated ?? false;
+    const metadata = [
+        `signal=${result.signal ?? "none"}`,
+        result.signalDescription
+            ? `signalDescription=${JSON.stringify(result.signalDescription)}`
+            : null,
+        `terminated=${Boolean(result.isTerminated)}`,
+        `killed=${Boolean(killed)}`,
+        `forcefullyTerminated=${Boolean(result.isForcefullyTerminated)}`,
+        `timedOut=${Boolean(result.timedOut)}`,
+        `canceled=${Boolean(result.isCanceled)}`,
+        `failed=${Boolean(result.failed)}`,
+    ].filter((entry) => entry !== null);
+    return new Error(`ssh_failed_without_exit_code: ${host} ${metadata.join(" ")}`, {
+        cause: result,
+    });
+}
+function sshConfigArgs() {
+    const configPath = process.env.SYMPHONY_SSH_CONFIG;
+    return configPath ? ["-F", configPath] : [];
+}
+function validPortDestination(destination) {
+    return destination !== "" && (!destination.includes(":") || bracketedHost(destination));
+}
+function validateSshDestination(destination) {
+    if (destination === "" || destination.startsWith("-"))
+        throw new Error(`invalid_ssh_destination: ${destination}`);
+    return destination;
+}
+function bracketedHost(destination) {
+    return destination.includes("[") && destination.includes("]");
+}
+function chmodCommand(mode, remotePath) {
+    if (typeof mode === "number" && Number.isInteger(mode))
+        return `chmod ${mode.toString(8)} ${shellEscape(chmodPathOperand(remotePath))}`;
+    if (typeof mode === "string") {
+        const normalizedMode = normalizeChmodMode(mode);
+        if (normalizedMode !== "")
+            return `chmod ${shellEscape(normalizedMode)} ${shellEscape(chmodPathOperand(remotePath))}`;
+    }
+    return "true";
+}
+function normalizeChmodMode(mode) {
+    const trimmed = mode.trim();
+    if (trimmed === "")
+        return "";
+    if (trimmed !== mode || !validChmodMode(trimmed))
+        throw new Error(`invalid_chmod_mode: ${JSON.stringify(mode)}`);
+    return trimmed;
+}
+function validChmodMode(mode) {
+    return NUMERIC_CHMOD_MODE.test(mode) || SYMBOLIC_CHMOD_MODE.test(mode);
+}
+function chmodPathOperand(remotePath) {
+    return remotePath.startsWith("-") ? `./${remotePath}` : remotePath;
+}
+//# sourceMappingURL=index.js.map

package/packages/ssh/dist/index.js.map

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

package/packages/ssh/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@lorenz/ssh",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@lorenz/domain": "file:../domain",
+    "execa": "^9.6.1"
+  }
+}

package/packages/static-worker/dist/index.d.ts

@@ -0,0 +1,73 @@
+import type { WorkerDescriptor, WorkerDriver, WorkerDriverFactory, WorkerDriverRegistry, WorkerHealth, DriverCapabilities, DriverDeps, ProvisionRequest, TeardownReason } from "@lorenz/worker-sdk";
+/**
+ * A {@link WorkerDriver} over a FIXED set of pre-existing SSH machines configured
+ * via the `ssh_hosts` (or `sshHosts`) driver option. It owns no lifecycle for the
+ * machines themselves: `min == max == hosts.length` is the implicit shape, and
+ * the address IS the `workerId`. `provision` hands out one of the configured
+ * addresses idempotently; `probe` runs `printf ready` over SSH using the
+ * caller-supplied `opts.timeoutMs` (the pool threads `worker.sshTimeoutMs` here);
+ * `destroy` merely forgets the address locally - it runs NO workspace hooks and
+ * NEVER deletes a machine (a destroyed host is immediately re-provisionable);
+ * `list` returns the configured set minus the addresses currently forgotten.
+ */
+export declare class StaticSshWorkerDriver implements WorkerDriver {
+    private readonly deps;
+    readonly kind = "static-ssh";
+    readonly capabilities: DriverCapabilities;
+    /** The full configured inventory (the fixed address set), in config order. */
+    private readonly hosts;
+    private readonly hostSet;
+    /**
+     * workerId -> assigned host. Keys are the pool's idempotency keys: either a
+     * synthetic `worker-N` the pool minted, or a configured host string (the legacy
+     * "address IS the workerId" shape). Tracks the provisioned-minus-destroyed view.
+     */
+    private readonly assignments;
+    private readonly runSsh;
+    constructor(options: Readonly<Record<string, unknown>>, deps: DriverDeps);
+    /**
+     * Hands out a configured address for `req.workerId`. The pool mints synthetic
+     * `worker-N` idempotency keys (NOT host strings), so an unknown workerId is ASSIGNED a
+     * free configured host round-robin and that mapping is remembered (the
+     * `workerHost` is the chosen host while the `workerId` stays the pool's key). A
+     * workerId that already IS a configured host is served directly (the legacy
+     * "address is the workerId" shape, e.g. a host-keyed hydrate survivor). Idempotent
+     * on `workerId`: a second call returns the same assignment. Rejects with
+     * `static_ssh_unknown_host` only when the fixed inventory is exhausted (no free
+     * host remains).
+     */
+    provision(req: ProvisionRequest): Promise<WorkerDescriptor>;
+    /**
+     * Runs `printf ready` over SSH against the worker's address, using the
+     * caller-supplied `opts.timeoutMs` (the pool passes `worker.sshTimeoutMs`). A
+     * non-zero exit or any transport error (e.g. `ssh_timeout`) gates the worker to
+     * `{ ok: false }` rather than throwing, so the reaper can demote it.
+     */
+    probe(worker: WorkerDescriptor, opts: {
+        timeoutMs: number;
+        signal?: AbortSignal;
+    }): Promise<WorkerHealth>;
+    /**
+     * Forgets the address locally. This is a pure bookkeeping no-op against the
+     * machine: it runs NO workspace hooks and NEVER deletes the machine (a static
+     * host is pre-existing infrastructure). Idempotent and tolerant of an
+     * already-forgotten or never-provisioned address.
+     */
+    destroy(worker: WorkerDescriptor, _opts: {
+        timeoutMs: number;
+        reason: TeardownReason;
+    }): Promise<void>;
+    /** Returns the live inventory (provisioned-minus-destroyed assignments). */
+    list(): Promise<WorkerDescriptor[]>;
+    private descriptorFor;
+}
+/** The registered `static-ssh` factory: constructs a driver over the configured hosts. */
+export declare const staticSshWorkerDriverFactory: WorkerDriverFactory;
+/**
+ * Register this built-in worker driver. Idempotent; called by the composition
+ * root (or a test) against its registry, defaulting to the process-wide one.
+ */
+export declare function registerStaticSshWorkerDriver(registries?: {
+    workerDrivers?: WorkerDriverRegistry | undefined;
+}): void;
+//# sourceMappingURL=index.d.ts.map

package/packages/static-worker/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAEhB,cAAc,EACf,MAAM,oBAAoB,CAAC;AAgC5B;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,YAAW,YAAY;IAiBtD,OAAO,CAAC,QAAQ,CAAC,IAAI;IAhBvB,QAAQ,CAAC,IAAI,gBAAQ;IACrB,QAAQ,CAAC,YAAY,qBAAgB;IAErC,8EAA8E;IAC9E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;gBAGjC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzB,IAAI,EAAE,UAAU;IAOnC;;;;;;;;;;OAUG;IACG,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuBjE;;;;;OAKG;IACG,KAAK,CACT,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAChD,OAAO,CAAC,YAAY,CAAC;IAcxB;;;;;OAKG;IACG,OAAO,CACX,MAAM,EAAE,gBAAgB,EACxB,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,cAAc,CAAA;KAAE,GACnD,OAAO,CAAC,IAAI,CAAC;IAOhB,4EAA4E;IACtE,IAAI,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAQzC,OAAO,CAAC,aAAa;CAUtB;AAED,0FAA0F;AAC1F,eAAO,MAAM,4BAA4B,EAAE,mBAG1C,CAAC;AAEF;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,GAAE;IAAE,aAAa,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAA;CAAO,GACpE,IAAI,CAKN"}

package/packages/static-worker/dist/index.js

@@ -0,0 +1,150 @@
+import { defaultWorkerDriverRegistry } from "@lorenz/worker-sdk";
+const KIND = "static-ssh";
+const CAPABILITIES = {
+    sshAddressable: true,
+    ephemeral: false,
+    usesLedger: false,
+};
+/** The readiness command the probe runs over SSH (a cheap liveness check). */
+const PROBE_COMMAND = "printf ready";
+/**
+ * Reads the configured host list from the driver options, accepting BOTH the
+ * snake_case `ssh_hosts` and the camelCase `sshHosts` spellings. This is the
+ * documented passthrough: the config normalizer is a flat per-key alias map and
+ * does NOT recurse into the driver options, so an operator may write either form.
+ * Throws `static_ssh_hosts_required` when neither is a non-empty string array.
+ */
+function readSshHosts(options) {
+    const raw = options?.["ssh_hosts"] ?? options?.["sshHosts"];
+    if (Array.isArray(raw) &&
+        raw.length > 0 &&
+        raw.every((value) => typeof value === "string" && value.length > 0)) {
+        return raw;
+    }
+    throw new Error("static_ssh_hosts_required");
+}
+/**
+ * A {@link WorkerDriver} over a FIXED set of pre-existing SSH machines configured
+ * via the `ssh_hosts` (or `sshHosts`) driver option. It owns no lifecycle for the
+ * machines themselves: `min == max == hosts.length` is the implicit shape, and
+ * the address IS the `workerId`. `provision` hands out one of the configured
+ * addresses idempotently; `probe` runs `printf ready` over SSH using the
+ * caller-supplied `opts.timeoutMs` (the pool threads `worker.sshTimeoutMs` here);
+ * `destroy` merely forgets the address locally - it runs NO workspace hooks and
+ * NEVER deletes a machine (a destroyed host is immediately re-provisionable);
+ * `list` returns the configured set minus the addresses currently forgotten.
+ */
+export class StaticSshWorkerDriver {
+    deps;
+    kind = KIND;
+    capabilities = CAPABILITIES;
+    /** The full configured inventory (the fixed address set), in config order. */
+    hosts;
+    hostSet;
+    /**
+     * workerId -> assigned host. Keys are the pool's idempotency keys: either a
+     * synthetic `worker-N` the pool minted, or a configured host string (the legacy
+     * "address IS the workerId" shape). Tracks the provisioned-minus-destroyed view.
+     */
+    assignments = new Map();
+    runSsh;
+    constructor(options, deps) {
+        this.deps = deps;
+        this.hosts = readSshHosts(options);
+        this.hostSet = new Set(this.hosts);
+        this.runSsh = deps.runSsh;
+    }
+    /**
+     * Hands out a configured address for `req.workerId`. The pool mints synthetic
+     * `worker-N` idempotency keys (NOT host strings), so an unknown workerId is ASSIGNED a
+     * free configured host round-robin and that mapping is remembered (the
+     * `workerHost` is the chosen host while the `workerId` stays the pool's key). A
+     * workerId that already IS a configured host is served directly (the legacy
+     * "address is the workerId" shape, e.g. a host-keyed hydrate survivor). Idempotent
+     * on `workerId`: a second call returns the same assignment. Rejects with
+     * `static_ssh_unknown_host` only when the fixed inventory is exhausted (no free
+     * host remains).
+     */
+    async provision(req) {
+        const existing = this.assignments.get(req.workerId);
+        if (existing) {
+            return Promise.resolve(this.descriptorFor(req.workerId, existing, [...req.labels]));
+        }
+        // Legacy shape: the workerId itself is a configured address (the address IS the
+        // key). Serve that host directly so a host-keyed provision/hydrate still works.
+        if (this.hostSet.has(req.workerId)) {
+            this.assignments.set(req.workerId, req.workerId);
+            return Promise.resolve(this.descriptorFor(req.workerId, req.workerId, [...req.labels]));
+        }
+        // Synthetic workerId (the pool's `worker-N`): assign the first free configured host.
+        const taken = new Set(this.assignments.values());
+        const host = this.hosts.find((candidate) => !taken.has(candidate));
+        if (host === undefined) {
+            return Promise.reject(new Error(`static_ssh_unknown_host: ${req.workerId}`));
+        }
+        this.assignments.set(req.workerId, host);
+        return Promise.resolve(this.descriptorFor(req.workerId, host, [...req.labels]));
+    }
+    /**
+     * Runs `printf ready` over SSH against the worker's address, using the
+     * caller-supplied `opts.timeoutMs` (the pool passes `worker.sshTimeoutMs`). A
+     * non-zero exit or any transport error (e.g. `ssh_timeout`) gates the worker to
+     * `{ ok: false }` rather than throwing, so the reaper can demote it.
+     */
+    async probe(worker, opts) {
+        try {
+            const result = await this.runSsh(worker.workerHost, PROBE_COMMAND, {
+                timeoutMs: opts.timeoutMs,
+            });
+            if (result.status !== 0) {
+                return { ok: false, reason: `static_ssh_probe_exit_${result.status}` };
+            }
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /**
+     * Forgets the address locally. This is a pure bookkeeping no-op against the
+     * machine: it runs NO workspace hooks and NEVER deletes the machine (a static
+     * host is pre-existing infrastructure). Idempotent and tolerant of an
+     * already-forgotten or never-provisioned address.
+     */
+    async destroy(worker, _opts) {
+        // Free the host assignment so the address re-enters the pool of free hosts a
+        // future provision can hand out. Idempotent and tolerant of an already-gone id.
+        this.assignments.delete(worker.workerId);
+        return Promise.resolve();
+    }
+    /** Returns the live inventory (provisioned-minus-destroyed assignments). */
+    async list() {
+        return Promise.resolve([...this.assignments.entries()].map(([workerId, host]) => this.descriptorFor(workerId, host, [])));
+    }
+    descriptorFor(workerId, host, labels) {
+        return {
+            workerId,
+            workerHost: host,
+            driverRef: host,
+            createdAtMs: this.deps.clock.now().getTime(),
+            labels,
+            metadata: {},
+        };
+    }
+}
+/** The registered `static-ssh` factory: constructs a driver over the configured hosts. */
+export const staticSshWorkerDriverFactory = {
+    kind: KIND,
+    create: (options, deps) => new StaticSshWorkerDriver(options, deps),
+};
+/**
+ * Register this built-in worker driver. Idempotent; called by the composition
+ * root (or a test) against its registry, defaulting to the process-wide one.
+ */
+export function registerStaticSshWorkerDriver(registries = {}) {
+    const drivers = registries.workerDrivers ?? defaultWorkerDriverRegistry;
+    if (drivers.get(KIND) === undefined) {
+        drivers.register(staticSshWorkerDriverFactory);
+    }
+}
+//# sourceMappingURL=index.js.map

package/packages/static-worker/dist/index.js.map

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

package/packages/static-worker/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@lorenz/static-worker",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "dependencies": {
+    "@lorenz/worker-sdk": "file:../worker-sdk"
+  }
+}

package/packages/tool-sdk/dist/filter.d.ts

@@ -0,0 +1,70 @@
+/**
+ * A small query DSL backing the read tools of the structured trackers
+ * (`local_query` today). It is the composable, side-effect-free analog of `linear_graphql`'s
+ * read power: a query can never mutate the backend, so it carries no trust-boundary or
+ * atomicity risk and the agent can filter/project/sort/page freely.
+ *
+ * The DSL is intentionally total - no regex, no `eval`, no JSONPath - and is evaluated in
+ * memory over already-parsed records (a board `Issue[]`).
+ * Nesting depth and node count are bounded so a hostile or runaway filter cannot blow up.
+ */
+type Scalar = string | number | boolean | null;
+type Predicate = {
+    field: string;
+    op: "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
+    value: Scalar;
+} | {
+    field: string;
+    op: "in" | "nin";
+    value: Scalar[];
+} | {
+    field: string;
+    op: "contains";
+    value: string;
+    ci?: boolean;
+} | {
+    field: string;
+    op: "exists";
+    value: boolean;
+};
+export type Filter = Predicate | {
+    and: Filter[];
+} | {
+    or: Filter[];
+} | {
+    not: Filter;
+};
+interface OrderBy {
+    field: string;
+    dir: "asc" | "desc";
+}
+export interface QuerySpec {
+    where?: Filter;
+    orderBy: OrderBy[];
+    limit: number;
+    offset: number;
+}
+/**
+ * Validate untrusted agent input into a typed {@link Filter}, reconstructing each node so no
+ * stray properties survive. Throws a clear `Error` on malformed input or when the tree exceeds
+ * the depth/node bounds.
+ */
+export declare function parseFilter(input: unknown): Filter;
+/** Evaluate a validated {@link Filter} against a record. Side-effect free. */
+export declare function matchesFilter(record: Record<string, unknown>, filter: Filter): boolean;
+/**
+ * Parse the shared query envelope (`where`, `order_by`, `limit`, `offset`) from raw tool args.
+ * `select`, and any tracker-specific args, are parsed by the calling tool.
+ */
+export declare function parseQuerySpec(args: Record<string, unknown>): QuerySpec;
+/** Filter, then (stably) sort, then page a record list. Returns the page plus the pre-page total. */
+export declare function applyQuery<T extends Record<string, unknown>>(records: T[], spec: QuerySpec): {
+    rows: T[];
+    total: number;
+};
+/** Validate an optional `select` projection: an array of field-name strings, or undefined. */
+export declare function parseSelect(input: unknown): string[] | undefined;
+/** Project a record down to the named fields, dropping any the record does not have. */
+export declare function pickFields(record: Record<string, unknown>, fields: string[]): Record<string, unknown>;
+export {};
+//# sourceMappingURL=filter.d.ts.map

package/packages/tool-sdk/dist/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,KAAK,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/C,KAAK,SAAS,GACV;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,IAAI,GAAG,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GACpD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,MAAM,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAExF,UAAU,OAAO;IACf,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,KAAK,GAAG,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAElD;AAoED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAKtF;AAuCD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAOvE;AAED,qGAAqG;AACrG,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,OAAO,EAAE,CAAC,EAAE,EACZ,IAAI,EAAE,SAAS,GACd;IAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAO9B;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAMhE;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzB"}