@constructive-db/machine-runner 0.1.0 → 0.2.2

package/README.md

@@ -1,11 +1,20 @@
 # @constructive-db/machine-runner
 
 The machine runner: the Node daemon a user installs on their own machine for
-Remote Control (constructive-planning#1690, phase 0). It dials **out** to a
-machine relay over WebSocket — it never listens on a port — spawns
-policy-checked processes in a pty (`node-pty`), and streams their bytes back
-as `@constructive-db/machine-protocol` frames. When the relay connection
-drops, it redials with exponential backoff and re-registers the machine.
+Remote Control (constructive-planning#1690). It is a **remote control and
+nothing else**: it dials **out** to a machine relay over WebSocket — it never
+listens on a port — runs the allow-listed commands the relay hands it (in a pty
+for a terminal, on pipes otherwise), streams their bytes back as
+`@constructive-db/machine-protocol` frames, and stops them when told. When the
+relay connection drops, it redials with exponential backoff and re-registers
+the machine.
+
+The runner knows nothing about what it runs. It has no notion of agents,
+Claude, Codex, runs, approvals or events; it never reads a byte of a
+command's output. Everything agentic sits *above* it, as ordinary commands
+(`constructive-agent-cli` from `@constructive-db/agent-cli`,
+`constructive-agent-host` from `@constructive-db/agent-host`) that the relay
+asks it to run and whose stdout the relay interprets. Keep it that way.
 
 ## Install
 
@@ -20,9 +29,19 @@ authorization answer comes from the relay it dials.
 ## Usage
 
 ```
-machine-runner --config ~/.constructive/machine-runner.json
+machine-runner enroll --relay wss://relay.example.com \
+  --machine <machine-uuid> --database <database-uuid>
+# the enrollment token is read from stdin or MACHINE_ENROLLMENT_TOKEN, never argv
+
+machine-runner start          # dial the relay and serve sessions
+machine-runner status         # what this runner is enrolled in, never secrets
 ```
 
+`enroll` writes the config `start` reads: `~/.machine-runner/config.json` at
+mode 0600, or wherever `--config <path>` / `MACHINE_RUNNER_CONFIG` points. A
+bare `machine-runner --config <path>` still boots the daemon, which is how the
+deployed unit and the bundle invoke it.
+
 The config carries a **list of enrollments** — one per relay/database this
 machine is enrolled in — plus the local policy:
 
@@ -30,7 +49,7 @@ machine is enrolled in — plus the local policy:
 {
   "enrollments": [
     {
-      "machineId": "my-laptop",
+      "machineId": "<machine-uuid>",
       "relayUrl": "wss://relay.example.com",
       "token": "<machine token>",
       "database": "db-uuid"
@@ -52,3 +71,105 @@ command not in `allowedCommands` is refused with an error frame, sessions
 start in the policy's `cwd`, and the spawned environment contains only the
 allow-listed pass-through variables plus the explicit `set` map — the runner's
 own environment (tokens included) never reaches a session.
+
+## What a session is
+
+An `open` frame names a command, its arguments, whether it wants a terminal,
+and optionally a directory. The runner:
+
+- refuses the command unless it is in `allowedCommands`, and refuses a `cwd`
+  that resolves outside the policy's `cwd` (a sibling such as
+  `/home/me/work-other` is outside `/home/me/work`);
+- spawns it in a pty (`interactive: true`, with `cols`/`rows`) or on pipes,
+  in that directory, with the projected environment;
+- streams `output` frames (pipe output tagged `stdout`/`stderr`; pty output is
+  the terminal's byte stream), writes `input` frames to its stdin, applies
+  `resize` and `signal`, and reports `exit` or `error`;
+- keeps a detached interactive session alive with a bounded scrollback until
+  a client reattaches or the session is closed.
+
+That is the whole contract. An agent session is one of these whose command
+happens to be an agent program — the relay composes that command and reads
+its output; the runner ran an allow-listed command:
+
+```json
+"policy": {
+  "allowedCommands": ["bash", "git", "constructive-agent-cli", "constructive-agent-host"],
+  "cwd": "/home/me/work",
+  "env": { "allow": ["PATH", "HOME"] }
+}
+```
+
+---
+
+## Education and Tutorials
+
+ 1. 🚀 [Quickstart: Getting Up and Running](https://constructive.io/learn/quickstart)
+Get started with modular databases in minutes. Install prerequisites and deploy your first module.
+
+ 2. 📦 [Modular PostgreSQL Development with Database Packages](https://constructive.io/learn/modular-postgres)
+Learn to organize PostgreSQL projects with pgpm workspaces and reusable database modules.
+
+ 3. ✏️ [Authoring Database Changes](https://constructive.io/learn/authoring-database-changes)
+Master the workflow for adding, organizing, and managing database changes with pgpm.
+
+ 4. 🧪 [End-to-End PostgreSQL Testing with TypeScript](https://constructive.io/learn/e2e-postgres-testing)
+Master end-to-end PostgreSQL testing with ephemeral databases, RLS testing, and CI/CD automation.
+
+ 5. ⚡ [Supabase Testing](https://constructive.io/learn/supabase)
+Use TypeScript-first tools to test Supabase projects with realistic RLS, policies, and auth contexts.
+
+ 6. 💧 [Drizzle ORM Testing](https://constructive.io/learn/drizzle-testing)
+Run full-stack tests with Drizzle ORM, including database setup, teardown, and RLS enforcement.
+
+ 7. 🔧 [Troubleshooting](https://constructive.io/learn/troubleshooting)
+Common issues and solutions for pgpm, PostgreSQL, and testing.
+
+## Related Constructive Tooling
+
+### 📦 Package Management
+
+* [pgpm](https://github.com/constructive-io/constructive/tree/main/pgpm/pgpm): **🖥️ PostgreSQL Package Manager** for modular Postgres development. Works with database workspaces, scaffolding, migrations, seeding, and installing database packages.
+
+### 🧪 Testing
+
+* [pgsql-test](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-test): **📊 Isolated testing environments** with per-test transaction rollbacks—ideal for integration tests, complex migrations, and RLS simulation.
+* [pglite-test](https://github.com/constructive-io/constructive/tree/main/postgres/pglite-test): **🪶 Drop-in pgsql-test replacement backed by PGlite** — in-process Postgres, no server required, instance-per-suite isolation.
+* [pgsql-seed](https://github.com/constructive-io/constructive/tree/main/postgres/pgsql-seed): **🌱 PostgreSQL seeding utilities** for CSV, JSON, SQL data loading, and pgpm deployment.
+* [supabase-test](https://github.com/constructive-io/constructive/tree/main/postgres/supabase-test): **🧪 Supabase-native test harness** preconfigured for the local Supabase stack—per-test rollbacks, JWT/role context helpers, and CI/GitHub Actions ready.
+* [graphile-test](https://github.com/constructive-io/constructive/tree/main/graphile/graphile-test): **🔐 Authentication mocking** for Graphile-focused test helpers and emulating row-level security contexts.
+* [pg-query-context](https://github.com/constructive-io/constructive/tree/main/postgres/pg-query-context): **🔒 Session context injection** to add session-local context (e.g., `SET LOCAL`) into queries—ideal for setting `role`, `jwt.claims`, and other session settings.
+
+### 🧠 Parsing & AST
+
+* [pgsql-parser](https://www.npmjs.com/package/pgsql-parser): **🔄 SQL conversion engine** that interprets and converts PostgreSQL syntax.
+* [libpg-query-node](https://www.npmjs.com/package/libpg-query): **🌉 Node.js bindings** for `libpg_query`, converting SQL into parse trees.
+* [pg-proto-parser](https://www.npmjs.com/package/pg-proto-parser): **📦 Protobuf parser** for parsing PostgreSQL Protocol Buffers definitions to generate TypeScript interfaces, utility functions, and JSON mappings for enums.
+* [@pgsql/enums](https://www.npmjs.com/package/@pgsql/enums): **🏷️ TypeScript enums** for PostgreSQL AST for safe and ergonomic parsing logic.
+* [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
+* [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
+
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
+## Credits
+
+**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**
+
+## Disclaimer
+
+AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED "AS IS", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.
+
+No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.

package/esm/index.js

@@ -1,4 +1,5 @@
 export { defaultConfigPath, parseFlags, resolveEnrollmentToken, RUNNER_USAGE, runRunnerCli, TOKEN_ENV, writeEnrollment } from './cli';
 export { loadRunnerConfig, parseRunnerConfig } from './config';
-export { DEFAULT_ENV_ALLOW, PolicyViolationError, resolveSpawn } from './policy';
+export { DEFAULT_ENV_ALLOW, PolicyViolationError, resolveCwd, resolveSpawn } from './policy';
+export { pipeProcess, ptyProcess } from './process';
 export { EnrollmentRunner, MachineRunner } from './runner';

package/esm/policy.js

@@ -2,7 +2,9 @@
 // machine it guards. The policy is written by the machine's owner and never
 // travels over the wire — a compromised relay can ask, but the answer is
 // decided here.
+import fs from 'fs';
 import os from 'os';
+import path from 'path';
 /** Pass-through vars a pty session cannot reasonably run without. */
 export const DEFAULT_ENV_ALLOW = ['PATH', 'HOME', 'TERM', 'LANG', 'USER', 'SHELL'];
 export class PolicyViolationError extends Error {
@@ -11,7 +13,42 @@ export class PolicyViolationError extends Error {
         this.name = 'PolicyViolationError';
     }
 }
-export function resolveSpawn(policy, command, args = []) {
+/**
+ * Where a path really points: symlinks resolved through the deepest ancestor
+ * that exists, the rest appended as written. A path that does not exist yet is
+ * judged by where it would be created.
+ */
+function realPath(target) {
+    let existing = target;
+    const rest = [];
+    while (!fs.existsSync(existing)) {
+        const parent = path.dirname(existing);
+        if (parent === existing)
+            return target;
+        rest.unshift(path.basename(existing));
+        existing = parent;
+    }
+    return path.join(fs.realpathSync.native(existing), ...rest);
+}
+/**
+ * The directory a session runs in: the policy root, or a requested directory
+ * resolved against it — and refused when it would land outside, symlinks
+ * included. The request is the client's; where the root is, is the machine
+ * owner's.
+ */
+export function resolveCwd(policy, requested) {
+    const root = path.resolve(policy.cwd || os.homedir());
+    if (requested === undefined)
+        return root;
+    const resolved = path.resolve(root, requested);
+    const realRoot = realPath(root);
+    const real = realPath(resolved);
+    if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+        throw new PolicyViolationError(`cwd '${requested}' is outside the policy root`);
+    }
+    return resolved;
+}
+export function resolveSpawn(policy, command, args = [], cwd) {
     if (!policy.allowedCommands.includes(command)) {
         throw new PolicyViolationError(`command '${command}' is not in the allowed command list`);
     }
@@ -28,7 +65,7 @@ export function resolveSpawn(policy, command, args = []) {
     return {
         command,
         args,
-        cwd: policy.cwd || os.homedir(),
+        cwd: resolveCwd(policy, cwd),
         env
     };
 }

package/esm/process.js

@@ -0,0 +1,101 @@
+// The two ways a session's process runs: in a pty, when the session is a
+// terminal, or on pipes, when it is a command. Both are driven through the
+// same small interface; the runner does not care which it holds beyond
+// whether it can be resized.
+import { spawn as spawnChild } from 'child_process';
+import * as pty from 'node-pty';
+import os from 'os';
+export function ptyProcess(spec, cols, rows) {
+    const proc = pty.spawn(spec.command, spec.args, {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        cwd: spec.cwd,
+        env: spec.env
+    });
+    return {
+        write: data => proc.write(data),
+        resize: (c, r) => proc.resize(c, r),
+        kill: signal => proc.kill(signal),
+        onData: listener => proc.onData(data => listener(data)),
+        onExit: listener => proc.onExit(listener),
+        // A pty has no asynchronous failure: `pty.spawn` throws, and everything
+        // after that is an exit.
+        onError: () => { }
+    };
+}
+function signalNumber(signal) {
+    if (!signal)
+        return undefined;
+    return os.constants.signals[signal];
+}
+export function pipeProcess(spec) {
+    const dataListeners = [];
+    const exitListeners = [];
+    const errorListeners = [];
+    let exited = false;
+    const child = spawnChild(spec.command, spec.args, {
+        cwd: spec.cwd,
+        env: spec.env,
+        stdio: ['pipe', 'pipe', 'pipe']
+    });
+    child.stdout.setEncoding('utf8').on('data', (data) => {
+        for (const listener of dataListeners)
+            listener(data, 'stdout');
+    });
+    child.stderr.setEncoding('utf8').on('data', (data) => {
+        for (const listener of dataListeners)
+            listener(data, 'stderr');
+    });
+    // A program that could not start (ENOENT, EACCES) reports once, as an
+    // error and then as the exit it never had; nothing follows.
+    child.on('error', err => {
+        if (exited)
+            return;
+        exited = true;
+        for (const listener of errorListeners)
+            listener(err);
+        for (const listener of exitListeners)
+            listener({ exitCode: -1 });
+    });
+    child.on('exit', (code, signal) => {
+        if (exited)
+            return;
+        exited = true;
+        const number = signalNumber(signal);
+        // A signal death has no code of its own; report it as a shell would.
+        const exitCode = code ?? (number !== undefined ? 128 + number : -1);
+        for (const listener of exitListeners) {
+            listener({ exitCode, ...(number !== undefined ? { signal: number } : {}) });
+        }
+    });
+    // A child that closed its stdin early makes the next write EPIPE. While it
+    // runs that is the session's failure; once it has exited, the exit already
+    // said everything and there is nobody left to tell.
+    child.stdin.on('error', err => {
+        if (exited)
+            return;
+        for (const listener of errorListeners)
+            listener(err);
+    });
+    return {
+        write(data) {
+            if (!exited && child.stdin.writable)
+                child.stdin.write(data);
+        },
+        kill(signal) {
+            if (exited)
+                return;
+            child.kill(signal);
+        },
+        onData(listener) {
+            dataListeners.push(listener);
+        },
+        onExit(listener) {
+            exitListeners.push(listener);
+        },
+        onError(listener) {
+            errorListeners.push(listener);
+        }
+    };
+}

package/esm/runner.js

@@ -1,9 +1,17 @@
 // One outbound connection per enrollment. The runner dials the relay, keeps
 // the socket alive with a reconnect loop, and serves sessions: an `open`
-// frame spawns a pty (after the local policy says yes), `input`/`resize`/
+// frame spawns a process (after the local policy says yes), `input`/`resize`/
 // `signal` drive it, and its output and exit stream back as frames. Nothing
 // here ever listens on a port.
 //
+// The runner is a remote control and nothing more. It runs the command it is
+// handed — in a pty when the session is a terminal, on pipes when it is a
+// command — moves the bytes, and reports the exit. It does not know what the
+// command is. A coding agent, an agent host, a build: each is an allow-listed
+// program on pipes whose stdout the runner forwards without reading. Whatever
+// vocabulary such a program speaks is between it and the relay's clients;
+// none of it is here, and none of it may be added here.
+//
 // A pty outlives the socket that asked for it. An interactive session is a
 // terminal on this machine, not a state of the connection, so `detach` (and a
 // dropped relay) stop the *streaming* and leave the process running; the bytes
@@ -12,9 +20,9 @@
 // ring so the program repaints. The runner is the only place those bytes are
 // held in memory, and it holds a bounded window of them, never a transcript.
 import { decodeFrame, encodeFrame, HEADER_MACHINE_DATABASE, HEADER_MACHINE_ID, RUNNER_CONNECT_PATH } from '@constructive-db/machine-protocol';
-import * as pty from 'node-pty';
 import { WebSocket } from 'ws';
 import { PolicyViolationError, resolveSpawn } from './policy';
+import { pipeProcess, ptyProcess } from './process';
 /** Stop presenting a credential this long before it expires. */
 const CREDENTIAL_SKEW_MS = 30_000;
 /**
@@ -169,11 +177,7 @@ export class EnrollmentRunner {
     handleFrame(ws, frame) {
         switch (frame.type) {
             case 'open':
-                this.openSession(ws, frame.sessionId, frame.command, frame.args ?? [], {
-                    interactive: frame.interactive === true,
-                    cols: frame.cols,
-                    rows: frame.rows
-                });
+                this.openSession(ws, frame);
                 return;
             case 'input': {
                 const session = this.require(ws, frame.sessionId);
@@ -186,6 +190,14 @@ export class EnrollmentRunner {
                 const session = this.require(ws, frame.sessionId);
                 if (!session)
                     return;
+                if (!session.proc.resize) {
+                    ws.send(encodeFrame({
+                        type: 'error',
+                        sessionId: frame.sessionId,
+                        message: 'command session has no terminal to resize'
+                    }));
+                    return;
+                }
                 session.cols = frame.cols;
                 session.rows = frame.rows;
                 session.proc.resize(frame.cols, frame.rows);
@@ -219,7 +231,7 @@ export class EnrollmentRunner {
                 if (!session)
                     return;
                 session.streaming = true;
-                if (frame.cols !== undefined && frame.rows !== undefined) {
+                if (frame.cols !== undefined && frame.rows !== undefined && session.proc.resize) {
                     session.cols = frame.cols;
                     session.rows = frame.rows;
                     session.proc.resize(frame.cols, frame.rows);
@@ -270,7 +282,7 @@ export class EnrollmentRunner {
      */
     deliverSignal(session, sessionId, signal) {
         const character = CONTROL_CHARACTERS[signal];
-        if (character) {
+        if (character && session.proc.resize) {
             session.proc.write(character);
             return;
         }
@@ -285,23 +297,20 @@ export class EnrollmentRunner {
             this.send({ type: 'error', sessionId, message: `${signal} failed: ${message}` });
         }
     }
-    openSession(ws, sessionId, command, args, shape) {
+    openSession(ws, frame) {
+        const { sessionId, command } = frame;
+        const args = frame.args ?? [];
+        const interactive = frame.interactive === true;
         if (this.sessions.has(sessionId)) {
             ws.send(encodeFrame({ type: 'error', sessionId, message: 'session id already in use' }));
             return;
         }
-        const cols = shape.cols ?? 80;
-        const rows = shape.rows ?? 24;
+        const cols = frame.cols ?? 80;
+        const rows = frame.rows ?? 24;
         let proc;
         try {
-            const spec = resolveSpawn(this.policy, command, args);
-            proc = pty.spawn(spec.command, spec.args, {
-                name: 'xterm-256color',
-                cols,
-                rows,
-                cwd: spec.cwd,
-                env: spec.env
-            });
+            const spec = resolveSpawn(this.policy, command, args, frame.cwd);
+            proc = interactive ? ptyProcess(spec, cols, rows) : pipeProcess(spec);
         }
         catch (err) {
             // A rejected command is the policy answering "no": the requester learns
@@ -318,7 +327,7 @@ export class EnrollmentRunner {
         }
         const session = {
             proc,
-            interactive: shape.interactive,
+            interactive,
             cols,
             rows,
             streaming: true,
@@ -326,20 +335,28 @@ export class EnrollmentRunner {
             truncated: false
         };
         this.sessions.set(sessionId, session);
-        proc.onData(data => {
+        proc.onData((data, stream) => {
             // Buffered for an interactive session whether or not anyone is watching:
             // that buffer is the repaint a reattach needs. Command mode streams and
             // keeps nothing — its transcript is the ledger.
             if (session.interactive)
                 this.remember(session, data);
-            if (session.streaming)
-                this.send({ type: 'output', sessionId, data });
+            if (session.streaming) {
+                this.send({ type: 'output', sessionId, data, ...(stream ? { stream } : {}) });
+            }
         });
         proc.onExit(({ exitCode, signal }) => {
             this.sessions.delete(sessionId);
             if (session.streaming)
                 this.send({ type: 'exit', sessionId, exitCode, signal });
         });
+        // The exit that follows — the process's own, or the one a failed start
+        // reports — is what ends the session.
+        proc.onError(err => {
+            this.logger.error(`machine-runner: session '${sessionId}' process failed: ${err.message}`);
+            this.send({ type: 'error', sessionId, message: `process failed: ${err.message}` });
+            proc.kill('SIGTERM');
+        });
     }
     /** Append to the capped ring, dropping the oldest bytes past the limit. */
     remember(session, data) {

package/index.d.ts

@@ -3,6 +3,8 @@ export { defaultConfigPath, parseFlags, resolveEnrollmentToken, RUNNER_USAGE, ru
 export type { Enrollment, RunnerConfig } from './config';
 export { loadRunnerConfig, parseRunnerConfig } from './config';
 export type { RunnerPolicy, SpawnSpec } from './policy';
-export { DEFAULT_ENV_ALLOW, PolicyViolationError, resolveSpawn } from './policy';
+export { DEFAULT_ENV_ALLOW, PolicyViolationError, resolveCwd, resolveSpawn } from './policy';
+export type { ProcessExit, SessionProcess } from './process';
+export { pipeProcess, ptyProcess } from './process';
 export type { EnrollmentRunnerOptions, MachineRunnerOptions } from './runner';
 export { EnrollmentRunner, MachineRunner } from './runner';

package/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MachineRunner = exports.EnrollmentRunner = exports.resolveSpawn = exports.PolicyViolationError = exports.DEFAULT_ENV_ALLOW = exports.parseRunnerConfig = exports.loadRunnerConfig = exports.writeEnrollment = exports.TOKEN_ENV = exports.runRunnerCli = exports.RUNNER_USAGE = exports.resolveEnrollmentToken = exports.parseFlags = exports.defaultConfigPath = void 0;
+exports.MachineRunner = exports.EnrollmentRunner = exports.ptyProcess = exports.pipeProcess = exports.resolveSpawn = exports.resolveCwd = exports.PolicyViolationError = exports.DEFAULT_ENV_ALLOW = exports.parseRunnerConfig = exports.loadRunnerConfig = exports.writeEnrollment = exports.TOKEN_ENV = exports.runRunnerCli = exports.RUNNER_USAGE = exports.resolveEnrollmentToken = exports.parseFlags = exports.defaultConfigPath = void 0;
 var cli_1 = require("./cli");
 Object.defineProperty(exports, "defaultConfigPath", { enumerable: true, get: function () { return cli_1.defaultConfigPath; } });
 Object.defineProperty(exports, "parseFlags", { enumerable: true, get: function () { return cli_1.parseFlags; } });
@@ -15,7 +15,11 @@ Object.defineProperty(exports, "parseRunnerConfig", { enumerable: true, get: fun
 var policy_1 = require("./policy");
 Object.defineProperty(exports, "DEFAULT_ENV_ALLOW", { enumerable: true, get: function () { return policy_1.DEFAULT_ENV_ALLOW; } });
 Object.defineProperty(exports, "PolicyViolationError", { enumerable: true, get: function () { return policy_1.PolicyViolationError; } });
+Object.defineProperty(exports, "resolveCwd", { enumerable: true, get: function () { return policy_1.resolveCwd; } });
 Object.defineProperty(exports, "resolveSpawn", { enumerable: true, get: function () { return policy_1.resolveSpawn; } });
+var process_1 = require("./process");
+Object.defineProperty(exports, "pipeProcess", { enumerable: true, get: function () { return process_1.pipeProcess; } });
+Object.defineProperty(exports, "ptyProcess", { enumerable: true, get: function () { return process_1.ptyProcess; } });
 var runner_1 = require("./runner");
 Object.defineProperty(exports, "EnrollmentRunner", { enumerable: true, get: function () { return runner_1.EnrollmentRunner; } });
 Object.defineProperty(exports, "MachineRunner", { enumerable: true, get: function () { return runner_1.MachineRunner; } });

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@constructive-db/machine-runner",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "The machine runner: a Node daemon installed on a user's own machine that dials out to a machine relay over WebSocket, spawns policy-checked processes in a pty, and streams their bytes back. No inbound port, ever.",
   "author": "Constructive <developers@constructive.io>",
   "license": "MIT",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive",
+    "directory": "agentic/machine-runner"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
   "keywords": [
     "pty",
     "remote-control",
@@ -20,28 +29,23 @@
     "access": "public",
     "directory": "dist"
   },
-  "dependencies": {
-    "@pgpmjs/logger": "^2.25.0",
-    "node-pty": "1.1.0",
-    "ws": "^8.18.0",
-    "@constructive-db/machine-protocol": "0.1.0"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.14",
-    "@types/node": "^22.10.4",
-    "@types/ws": "^8.5.13",
-    "jest": "^29.7.0",
-    "makage": "^0.1.12",
-    "ts-jest": "^29.2.0",
-    "typescript": "^5.1.6",
-    "@constructive-db/machine-relay": "0.1.0"
-  },
   "scripts": {
+    "prepack": "npm run build",
     "build": "makage build && cp LICENSE dist/LICENSE",
     "build:dev": "makage build --dev && cp LICENSE dist/LICENSE",
     "clean": "makage clean",
     "lint": "eslint . --fix",
     "start": "node dist/run.js",
     "test": "jest"
-  }
-}
+  },
+  "dependencies": {
+    "@constructive-db/machine-protocol": "0.2.2",
+    "@pgpmjs/logger": "^2.26.0",
+    "node-pty": "1.1.0",
+    "ws": "^8.21.3"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.13"
+  },
+  "gitHead": "81eed19332cc231de0fde02bc6e87002357f9536"
+}

package/policy.d.ts

@@ -1,7 +1,10 @@
 export interface RunnerPolicy {
     /** Commands (argv[0], exact match) a session may start. */
     allowedCommands: string[];
-    /** Working directory every session starts in. */
+    /**
+     * The root every session runs under: where a session starts by default, and
+     * the directory a requested `cwd` must stay inside.
+     */
     cwd: string;
     /**
      * Environment the spawned process sees: `allow` names process.env vars to
@@ -24,4 +27,11 @@ export interface SpawnSpec {
     cwd: string;
     env: Record<string, string>;
 }
-export declare function resolveSpawn(policy: RunnerPolicy, command: string, args?: string[]): SpawnSpec;
+/**
+ * The directory a session runs in: the policy root, or a requested directory
+ * resolved against it — and refused when it would land outside, symlinks
+ * included. The request is the client's; where the root is, is the machine
+ * owner's.
+ */
+export declare function resolveCwd(policy: RunnerPolicy, requested?: string): string;
+export declare function resolveSpawn(policy: RunnerPolicy, command: string, args?: string[], cwd?: string): SpawnSpec;

package/policy.js

@@ -8,8 +8,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PolicyViolationError = exports.DEFAULT_ENV_ALLOW = void 0;
+exports.resolveCwd = resolveCwd;
 exports.resolveSpawn = resolveSpawn;
+const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
 /** Pass-through vars a pty session cannot reasonably run without. */
 exports.DEFAULT_ENV_ALLOW = ['PATH', 'HOME', 'TERM', 'LANG', 'USER', 'SHELL'];
 class PolicyViolationError extends Error {
@@ -19,7 +22,42 @@ class PolicyViolationError extends Error {
     }
 }
 exports.PolicyViolationError = PolicyViolationError;
-function resolveSpawn(policy, command, args = []) {
+/**
+ * Where a path really points: symlinks resolved through the deepest ancestor
+ * that exists, the rest appended as written. A path that does not exist yet is
+ * judged by where it would be created.
+ */
+function realPath(target) {
+    let existing = target;
+    const rest = [];
+    while (!fs_1.default.existsSync(existing)) {
+        const parent = path_1.default.dirname(existing);
+        if (parent === existing)
+            return target;
+        rest.unshift(path_1.default.basename(existing));
+        existing = parent;
+    }
+    return path_1.default.join(fs_1.default.realpathSync.native(existing), ...rest);
+}
+/**
+ * The directory a session runs in: the policy root, or a requested directory
+ * resolved against it — and refused when it would land outside, symlinks
+ * included. The request is the client's; where the root is, is the machine
+ * owner's.
+ */
+function resolveCwd(policy, requested) {
+    const root = path_1.default.resolve(policy.cwd || os_1.default.homedir());
+    if (requested === undefined)
+        return root;
+    const resolved = path_1.default.resolve(root, requested);
+    const realRoot = realPath(root);
+    const real = realPath(resolved);
+    if (real !== realRoot && !real.startsWith(realRoot + path_1.default.sep)) {
+        throw new PolicyViolationError(`cwd '${requested}' is outside the policy root`);
+    }
+    return resolved;
+}
+function resolveSpawn(policy, command, args = [], cwd) {
     if (!policy.allowedCommands.includes(command)) {
         throw new PolicyViolationError(`command '${command}' is not in the allowed command list`);
     }
@@ -36,7 +74,7 @@ function resolveSpawn(policy, command, args = []) {
     return {
         command,
         args,
-        cwd: policy.cwd || os_1.default.homedir(),
+        cwd: resolveCwd(policy, cwd),
         env
     };
 }

package/process.d.ts

@@ -0,0 +1,23 @@
+import type { SignalName } from '@constructive-db/machine-protocol';
+import type { SpawnSpec } from './policy';
+export interface ProcessExit {
+    exitCode: number;
+    signal?: number;
+}
+/** What the runner drives, whether it is a pty or a pair of pipes. */
+export interface SessionProcess {
+    write(data: string): void;
+    /** Absent where there is no terminal to resize. */
+    resize?(cols: number, rows: number): void;
+    kill(signal?: SignalName): void;
+    /**
+     * Bytes the process wrote. A pty has one stream; a process on pipes says
+     * which of its two a chunk came from.
+     */
+    onData(listener: (data: string, stream?: 'stdout' | 'stderr') => void): void;
+    onExit(listener: (event: ProcessExit) => void): void;
+    /** The process failed to run at all (a pty reports that by throwing from spawn). */
+    onError(listener: (err: Error) => void): void;
+}
+export declare function ptyProcess(spec: SpawnSpec, cols: number, rows: number): SessionProcess;
+export declare function pipeProcess(spec: SpawnSpec): SessionProcess;

package/process.js

@@ -0,0 +1,141 @@
+"use strict";
+// The two ways a session's process runs: in a pty, when the session is a
+// terminal, or on pipes, when it is a command. Both are driven through the
+// same small interface; the runner does not care which it holds beyond
+// whether it can be resized.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ptyProcess = ptyProcess;
+exports.pipeProcess = pipeProcess;
+const child_process_1 = require("child_process");
+const pty = __importStar(require("node-pty"));
+const os_1 = __importDefault(require("os"));
+function ptyProcess(spec, cols, rows) {
+    const proc = pty.spawn(spec.command, spec.args, {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        cwd: spec.cwd,
+        env: spec.env
+    });
+    return {
+        write: data => proc.write(data),
+        resize: (c, r) => proc.resize(c, r),
+        kill: signal => proc.kill(signal),
+        onData: listener => proc.onData(data => listener(data)),
+        onExit: listener => proc.onExit(listener),
+        // A pty has no asynchronous failure: `pty.spawn` throws, and everything
+        // after that is an exit.
+        onError: () => { }
+    };
+}
+function signalNumber(signal) {
+    if (!signal)
+        return undefined;
+    return os_1.default.constants.signals[signal];
+}
+function pipeProcess(spec) {
+    const dataListeners = [];
+    const exitListeners = [];
+    const errorListeners = [];
+    let exited = false;
+    const child = (0, child_process_1.spawn)(spec.command, spec.args, {
+        cwd: spec.cwd,
+        env: spec.env,
+        stdio: ['pipe', 'pipe', 'pipe']
+    });
+    child.stdout.setEncoding('utf8').on('data', (data) => {
+        for (const listener of dataListeners)
+            listener(data, 'stdout');
+    });
+    child.stderr.setEncoding('utf8').on('data', (data) => {
+        for (const listener of dataListeners)
+            listener(data, 'stderr');
+    });
+    // A program that could not start (ENOENT, EACCES) reports once, as an
+    // error and then as the exit it never had; nothing follows.
+    child.on('error', err => {
+        if (exited)
+            return;
+        exited = true;
+        for (const listener of errorListeners)
+            listener(err);
+        for (const listener of exitListeners)
+            listener({ exitCode: -1 });
+    });
+    child.on('exit', (code, signal) => {
+        if (exited)
+            return;
+        exited = true;
+        const number = signalNumber(signal);
+        // A signal death has no code of its own; report it as a shell would.
+        const exitCode = code ?? (number !== undefined ? 128 + number : -1);
+        for (const listener of exitListeners) {
+            listener({ exitCode, ...(number !== undefined ? { signal: number } : {}) });
+        }
+    });
+    // A child that closed its stdin early makes the next write EPIPE. While it
+    // runs that is the session's failure; once it has exited, the exit already
+    // said everything and there is nobody left to tell.
+    child.stdin.on('error', err => {
+        if (exited)
+            return;
+        for (const listener of errorListeners)
+            listener(err);
+    });
+    return {
+        write(data) {
+            if (!exited && child.stdin.writable)
+                child.stdin.write(data);
+        },
+        kill(signal) {
+            if (exited)
+                return;
+            child.kill(signal);
+        },
+        onData(listener) {
+            dataListeners.push(listener);
+        },
+        onExit(listener) {
+            exitListeners.push(listener);
+        },
+        onError(listener) {
+            errorListeners.push(listener);
+        }
+    };
+}

package/runner.js

@@ -1,10 +1,18 @@
 "use strict";
 // One outbound connection per enrollment. The runner dials the relay, keeps
 // the socket alive with a reconnect loop, and serves sessions: an `open`
-// frame spawns a pty (after the local policy says yes), `input`/`resize`/
+// frame spawns a process (after the local policy says yes), `input`/`resize`/
 // `signal` drive it, and its output and exit stream back as frames. Nothing
 // here ever listens on a port.
 //
+// The runner is a remote control and nothing more. It runs the command it is
+// handed — in a pty when the session is a terminal, on pipes when it is a
+// command — moves the bytes, and reports the exit. It does not know what the
+// command is. A coding agent, an agent host, a build: each is an allow-listed
+// program on pipes whose stdout the runner forwards without reading. Whatever
+// vocabulary such a program speaks is between it and the relay's clients;
+// none of it is here, and none of it may be added here.
+//
 // A pty outlives the socket that asked for it. An interactive session is a
 // terminal on this machine, not a state of the connection, so `detach` (and a
 // dropped relay) stop the *streaming* and leave the process running; the bytes
@@ -12,45 +20,12 @@
 // `reattach` — from whichever client the tenant then authorizes — replays that
 // ring so the program repaints. The runner is the only place those bytes are
 // held in memory, and it holds a bounded window of them, never a transcript.
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MachineRunner = exports.EnrollmentRunner = void 0;
 const machine_protocol_1 = require("@constructive-db/machine-protocol");
-const pty = __importStar(require("node-pty"));
 const ws_1 = require("ws");
 const policy_1 = require("./policy");
+const process_1 = require("./process");
 /** Stop presenting a credential this long before it expires. */
 const CREDENTIAL_SKEW_MS = 30_000;
 /**
@@ -205,11 +180,7 @@ class EnrollmentRunner {
     handleFrame(ws, frame) {
         switch (frame.type) {
             case 'open':
-                this.openSession(ws, frame.sessionId, frame.command, frame.args ?? [], {
-                    interactive: frame.interactive === true,
-                    cols: frame.cols,
-                    rows: frame.rows
-                });
+                this.openSession(ws, frame);
                 return;
             case 'input': {
                 const session = this.require(ws, frame.sessionId);
@@ -222,6 +193,14 @@ class EnrollmentRunner {
                 const session = this.require(ws, frame.sessionId);
                 if (!session)
                     return;
+                if (!session.proc.resize) {
+                    ws.send((0, machine_protocol_1.encodeFrame)({
+                        type: 'error',
+                        sessionId: frame.sessionId,
+                        message: 'command session has no terminal to resize'
+                    }));
+                    return;
+                }
                 session.cols = frame.cols;
                 session.rows = frame.rows;
                 session.proc.resize(frame.cols, frame.rows);
@@ -255,7 +234,7 @@ class EnrollmentRunner {
                 if (!session)
                     return;
                 session.streaming = true;
-                if (frame.cols !== undefined && frame.rows !== undefined) {
+                if (frame.cols !== undefined && frame.rows !== undefined && session.proc.resize) {
                     session.cols = frame.cols;
                     session.rows = frame.rows;
                     session.proc.resize(frame.cols, frame.rows);
@@ -306,7 +285,7 @@ class EnrollmentRunner {
      */
     deliverSignal(session, sessionId, signal) {
         const character = CONTROL_CHARACTERS[signal];
-        if (character) {
+        if (character && session.proc.resize) {
             session.proc.write(character);
             return;
         }
@@ -321,23 +300,20 @@ class EnrollmentRunner {
             this.send({ type: 'error', sessionId, message: `${signal} failed: ${message}` });
         }
     }
-    openSession(ws, sessionId, command, args, shape) {
+    openSession(ws, frame) {
+        const { sessionId, command } = frame;
+        const args = frame.args ?? [];
+        const interactive = frame.interactive === true;
         if (this.sessions.has(sessionId)) {
             ws.send((0, machine_protocol_1.encodeFrame)({ type: 'error', sessionId, message: 'session id already in use' }));
             return;
         }
-        const cols = shape.cols ?? 80;
-        const rows = shape.rows ?? 24;
+        const cols = frame.cols ?? 80;
+        const rows = frame.rows ?? 24;
         let proc;
         try {
-            const spec = (0, policy_1.resolveSpawn)(this.policy, command, args);
-            proc = pty.spawn(spec.command, spec.args, {
-                name: 'xterm-256color',
-                cols,
-                rows,
-                cwd: spec.cwd,
-                env: spec.env
-            });
+            const spec = (0, policy_1.resolveSpawn)(this.policy, command, args, frame.cwd);
+            proc = interactive ? (0, process_1.ptyProcess)(spec, cols, rows) : (0, process_1.pipeProcess)(spec);
         }
         catch (err) {
             // A rejected command is the policy answering "no": the requester learns
@@ -354,7 +330,7 @@ class EnrollmentRunner {
         }
         const session = {
             proc,
-            interactive: shape.interactive,
+            interactive,
             cols,
             rows,
             streaming: true,
@@ -362,20 +338,28 @@ class EnrollmentRunner {
             truncated: false
         };
         this.sessions.set(sessionId, session);
-        proc.onData(data => {
+        proc.onData((data, stream) => {
             // Buffered for an interactive session whether or not anyone is watching:
             // that buffer is the repaint a reattach needs. Command mode streams and
             // keeps nothing — its transcript is the ledger.
             if (session.interactive)
                 this.remember(session, data);
-            if (session.streaming)
-                this.send({ type: 'output', sessionId, data });
+            if (session.streaming) {
+                this.send({ type: 'output', sessionId, data, ...(stream ? { stream } : {}) });
+            }
         });
         proc.onExit(({ exitCode, signal }) => {
             this.sessions.delete(sessionId);
             if (session.streaming)
                 this.send({ type: 'exit', sessionId, exitCode, signal });
         });
+        // The exit that follows — the process's own, or the one a failed start
+        // reports — is what ends the session.
+        proc.onError(err => {
+            this.logger.error(`machine-runner: session '${sessionId}' process failed: ${err.message}`);
+            this.send({ type: 'error', sessionId, message: `process failed: ${err.message}` });
+            proc.kill('SIGTERM');
+        });
     }
     /** Append to the capped ring, dropping the oldest bytes past the limit. */
     remember(session, data) {