@constructive-db/machine-protocol 0.1.0 → 0.2.2

package/README.md

@@ -1,7 +1,7 @@
 # @constructive-db/machine-protocol
 
-The wire protocol shared by the machine relay (`compute/services/machine-relay`)
-and the machine runner (`compute/lib/machine-runner`): the JSON frames a remote
+The wire protocol shared by the machine relay (`compute/services/machine-relay` in constructive-db)
+and the machine runner (`agentic/machine-runner`): the JSON frames a remote
 session is made of — `open`, `input`, `resize`, `close` from the client side;
 `output`, `exit`, `error` from the runner side; `attached` from the relay — and
 the codec that encodes them and refuses malformed ones.
@@ -11,3 +11,95 @@ The relay never interprets terminal bytes: `input` flows client → runner and
 session lifecycle. The package has no dependencies so the relay can carry it
 into the functions image without dragging the runner's native pty bindings
 along.
+
+## Two legs, two vocabularies
+
+The runner leg — what a runner sends and receives — is the generic subset:
+`open` (`command`, `args`, `interactive`, `cols`, `rows`, `cwd`), `input`,
+`resize`, `signal`, `detach`, `reattach`, `close` in; `output` (with an
+optional `stream: 'stdout' | 'stderr'` for a process on pipes), `exit`,
+`error`, `scrollback` out; plus enrollment and credential exchange. A runner
+never sees anything else, and never parses `output`.
+
+The agent vocabulary is the client leg's, spoken between a client and the
+relay: an `open` may carry a binding (`runId`, `agentMode`, `cliSessionId`,
+resolved by `agentBinding`), and the relay turns a bound program's stdout
+lines into `agent_event` frames (`assertAgentEvent`). An approval decision is
+not a frame at all on the runner side: the relay writes it to the program's
+stdin as one JSON line (`encodeApprovalDecisionLine` /
+`parseApprovalDecisionLine`), which `constructive-agent-cli` reads. The runner
+carried bytes.
+
+---
+
+## 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

@@ -14,6 +14,19 @@
 // a decision. That is what makes a reattach from a different client safe —
 // nothing about the attach that opened the session carries over.
 //
+// Two vocabularies live here, and the line between them is the line between the
+// runner and everything above it:
+//
+// - The *machine* frames (`open` … `exit`, plus enrollment) are the remote
+//   control. A runner speaks only these: it runs an allow-listed command in a
+//   pty or on pipes, moves bytes, reports the exit. It has no notion of what the
+//   command is.
+// - The *agent* vocabulary (`AgentBinding` on an `open`, `AgentEvent`, the
+//   `agent_event` frame, the stdio contract below) is between a client, the
+//   relay and an agent program running *under* the runner. The runner never
+//   reads or writes any of it; to the runner an agent program is a command on
+//   pipes whose stdout happens to be JSON lines.
+//
 // This package is vocabulary, never policy. Everything a socket puts on the wire
 // — its database, its machine id — is a *coordinate*: it says which row the
 // socket is asking about, and the relay answers by asking that database's SQL.
@@ -86,6 +99,17 @@ export function parseClientAttachPath(path) {
         machineId: decodeURIComponent(match[2])
     };
 }
+export const AGENT_MODES = ['cli', 'embedded'];
+/** The binding an `open` frame carries, or null for a plain session. */
+export function agentBinding(frame) {
+    if (frame.runId === undefined || frame.agentMode === undefined)
+        return null;
+    return {
+        runId: frame.runId,
+        agentMode: frame.agentMode,
+        ...(frame.cliSessionId !== undefined ? { cliSessionId: frame.cliSessionId } : {})
+    };
+}
 /**
  * Signals a client may ask for. `SIGINT` and `SIGQUIT` are the terminal's own
  * interrupt characters, so on a pty they are delivered the way a keyboard
@@ -94,6 +118,124 @@ export function parseClientAttachPath(path) {
  * session. The rest are delivered to the session leader and do end it.
  */
 export const SIGNAL_NAMES = ['SIGINT', 'SIGQUIT', 'SIGTERM', 'SIGHUP', 'SIGKILL'];
+export const AGENT_EVENT_KINDS = [
+    'session',
+    'text',
+    'tool_call',
+    'tool_result',
+    'approval_requested',
+    'approval_resolved',
+    'result'
+];
+// ---------------------------------------------------------------------------
+// The agent program contract. An agent runs under the runner as an ordinary
+// non-interactive command; this is what it speaks on its pipes, and the relay
+// is the peer that reads and writes it — not the runner, which sees bytes.
+//
+//   stdin  — one prompt per line, and {@link ApprovalDecisionLine}s as JSON
+//            lines where the relay answers a question the program asked;
+//   stdout — {@link AgentEvent}s as JSON lines; any other line is plain output;
+//   stderr — plain output;
+//   exit   — the program's own.
+//
+// `constructive-agent-host` (`@constructive-db/agent-host`) speaks it natively.
+// `constructive-agent-cli` (`@constructive-db/agent-cli`) speaks it on behalf
+// of a coding-agent CLI (`claude`, `codex`) that does not.
+// ---------------------------------------------------------------------------
+/**
+ * The program the relay runs for a `cli` binding: it wraps the CLI the opener
+ * named (`claude`, `codex`) and translates its stream to this contract. The
+ * machine's policy must allow it by this exact name.
+ */
+export const AGENT_CLI_COMMAND = 'constructive-agent-cli';
+export function encodeApprovalDecisionLine(line) {
+    return `${JSON.stringify(line)}\n`;
+}
+/** The decision a stdin line carries, or null when the line is a prompt. */
+export function parseApprovalDecisionLine(line) {
+    if (!line.startsWith('{'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const value = parsed;
+    if (value.kind !== 'approval_decision')
+        return null;
+    if (typeof value.requestId !== 'string' || value.requestId.length === 0) {
+        throw new Error('machine-protocol: approval_decision line is missing requestId');
+    }
+    if (value.decision !== 'allow' && value.decision !== 'deny') {
+        throw new Error('machine-protocol: approval_decision line has invalid decision');
+    }
+    const reason = value.reason;
+    if (reason !== undefined && typeof reason !== 'string') {
+        throw new Error('machine-protocol: approval_decision line reason must be a string');
+    }
+    const decoded = {
+        kind: 'approval_decision',
+        requestId: value.requestId,
+        decision: value.decision
+    };
+    if (typeof reason === 'string')
+        decoded.reason = reason;
+    return decoded;
+}
+/** The longest line a {@link LineSplitter} buffers before giving up on it. */
+export const MAX_LINE_LENGTH = 1024 * 1024;
+/**
+ * Split a stream into the complete lines it has delivered so far. Keeps the
+ * unterminated tail for the next chunk; `flush` hands it over at the end. A
+ * tail that outgrows `maxLineLength` is dropped and reported, so a program
+ * that never writes a newline cannot grow the reader without bound.
+ */
+export class LineSplitter {
+    maxLineLength;
+    tail = '';
+    constructor(maxLineLength = MAX_LINE_LENGTH) {
+        this.maxLineLength = maxLineLength;
+    }
+    /**
+     * Complete lines are delivered before an oversized tail in the same chunk is
+     * reported: the failure is raised on the next call instead of losing them.
+     */
+    overflowed = false;
+    push(chunk) {
+        this.raiseOverflow();
+        this.tail += chunk;
+        const lines = this.tail.split('\n');
+        this.tail = lines.pop() ?? '';
+        if (this.tail.length > this.maxLineLength) {
+            this.tail = '';
+            this.overflowed = true;
+            if (lines.length === 0)
+                this.raiseOverflow();
+        }
+        return lines.map(stripCarriageReturn);
+    }
+    raiseOverflow() {
+        if (!this.overflowed)
+            return;
+        this.overflowed = false;
+        throw new Error(`machine-protocol: line exceeds ${this.maxLineLength} characters without a newline`);
+    }
+    flush() {
+        this.raiseOverflow();
+        if (!this.tail)
+            return [];
+        const line = stripCarriageReturn(this.tail);
+        this.tail = '';
+        return [line];
+    }
+}
+function stripCarriageReturn(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
 const FRAME_TYPES = new Set([
     'open',
     'input',
@@ -103,6 +245,7 @@ const FRAME_TYPES = new Set([
     'reattach',
     'close',
     'output',
+    'agent_event',
     'exit',
     'error',
     'scrollback',
@@ -121,6 +264,7 @@ const SESSION_FRAME_TYPES = new Set([
     'reattach',
     'close',
     'output',
+    'agent_event',
     'exit',
     'scrollback',
     'detached',
@@ -140,6 +284,105 @@ function validDimension(value) {
         value > 0 &&
         value <= MAX_DIMENSION);
 }
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether `value` looks like an {@link AgentEvent} — an object naming one of
+ * the event kinds. Shape is not checked; that is {@link assertAgentEvent}. A
+ * headless agent process speaks these on its stdout one per line, and this is
+ * how a relaying runner tells an event line from any other line it prints.
+ */
+export function isAgentEventLike(value) {
+    return (isPlainObject(value) &&
+        typeof value.kind === 'string' &&
+        AGENT_EVENT_KINDS.includes(value.kind));
+}
+/**
+ * `value` as an {@link AgentEvent}, or a thrown protocol error naming what is
+ * wrong with it. `where` names the carrier in the message (the frame, a
+ * process's stdout) so the fault is attributed.
+ */
+export function assertAgentEvent(value, where = "'agent_event' frame") {
+    if (!isPlainObject(value)) {
+        throw new Error(`machine-protocol: ${where} is missing event`);
+    }
+    const event = value;
+    const kind = event.kind;
+    if (typeof kind !== 'string' || !AGENT_EVENT_KINDS.includes(kind)) {
+        throw new Error(`machine-protocol: ${where} has unknown event kind '${String(kind)}'`);
+    }
+    const requiredString = (field) => {
+        if (typeof event[field] !== 'string') {
+            throw new Error(`machine-protocol: ${where} ${kind} event is missing ${field}`);
+        }
+    };
+    switch (kind) {
+        case 'session':
+            requiredString('cliSessionId');
+            break;
+        case 'text':
+            requiredString('text');
+            break;
+        case 'tool_call':
+            requiredString('id');
+            requiredString('name');
+            break;
+        case 'tool_result':
+            requiredString('id');
+            break;
+        case 'approval_requested':
+            requiredString('requestId');
+            requiredString('tool');
+            break;
+        case 'approval_resolved':
+            requiredString('requestId');
+            if (event.decision !== 'allow' && event.decision !== 'deny') {
+                throw new Error(`machine-protocol: ${where} approval_resolved event has invalid decision`);
+            }
+            break;
+        case 'result':
+            if (typeof event.ok !== 'boolean') {
+                throw new Error(`machine-protocol: ${where} result event is missing ok`);
+            }
+            break;
+    }
+    return event;
+}
+/**
+ * The agent-run binding, checked the way `machine_session`'s own constraint
+ * checks it, so a frame the tenant would refuse is refused before it is ever
+ * asked: `runId` and `agentMode` come together or not at all, `cliSessionId`
+ * names a CLI session and so needs `agentMode: 'cli'`, and a bound session is
+ * headless — it is the run's process, not a terminal — so `interactive` is a
+ * contradiction rather than an option.
+ */
+function validateAgentBinding(frame) {
+    const { runId, agentMode, cliSessionId } = frame;
+    if (runId !== undefined && (typeof runId !== 'string' || runId.length === 0)) {
+        throw new Error("machine-protocol: 'open' frame runId must be a non-empty string");
+    }
+    if (agentMode !== undefined && !AGENT_MODES.includes(agentMode)) {
+        throw new Error(`machine-protocol: 'open' frame agentMode must be one of ${AGENT_MODES.join(', ')}`);
+    }
+    if ((runId === undefined) !== (agentMode === undefined)) {
+        throw new Error("machine-protocol: 'open' frame needs both runId and agentMode, or neither");
+    }
+    if (cliSessionId !== undefined) {
+        if (typeof cliSessionId !== 'string' || cliSessionId.length === 0) {
+            throw new Error("machine-protocol: 'open' frame cliSessionId must be a non-empty string");
+        }
+        if (agentMode !== 'cli') {
+            throw new Error("machine-protocol: 'open' frame cliSessionId requires agentMode 'cli'");
+        }
+    }
+    if (runId !== undefined && frame.interactive === true) {
+        throw new Error("machine-protocol: 'open' frame bound to a run cannot be interactive");
+    }
+    if (frame.cwd !== undefined && (typeof frame.cwd !== 'string' || frame.cwd.length === 0)) {
+        throw new Error("machine-protocol: 'open' frame cwd must be a non-empty string");
+    }
+}
 export function encodeFrame(frame) {
     return JSON.stringify(frame);
 }
@@ -177,12 +420,22 @@ export function decodeFrame(raw) {
                     throw new Error(`machine-protocol: 'open' frame needs integer cols/rows in 1..${MAX_DIMENSION}`);
                 }
             }
+            validateAgentBinding(frame);
             break;
         case 'input':
         case 'output':
             if (typeof frame.data !== 'string') {
                 throw new Error(`machine-protocol: '${type}' frame is missing data`);
             }
+            if (type === 'output' &&
+                frame.stream !== undefined &&
+                frame.stream !== 'stdout' &&
+                frame.stream !== 'stderr') {
+                throw new Error("machine-protocol: 'output' frame stream must be 'stdout' or 'stderr'");
+            }
+            break;
+        case 'agent_event':
+            assertAgentEvent(frame.event);
             break;
         case 'resize':
             if (!validDimension(frame.cols) || !validDimension(frame.rows)) {

package/index.d.ts

@@ -45,6 +45,28 @@ export declare function parseClientAttachPath(path: string): {
     databaseId: string;
     machineId: string;
 } | null;
+/**
+ * How a session bound to an agent run executes the agent: `cli` drives the
+ * user's own installed CLI, `embedded` runs our loop. Mirrors the
+ * `machine_session.agent_mode` check constraint.
+ */
+export type AgentMode = 'cli' | 'embedded';
+export declare const AGENT_MODES: readonly AgentMode[];
+/**
+ * The agent-run binding an `open` frame may carry, client → relay. A bound
+ * session is headless: its process is the agent's, driven by the run rather
+ * than by a keyboard, so it never gets a pty. Like every coordinate on this
+ * wire the run id is a request — the tenant's SQL decides whether the opener
+ * may bind to that run. The relay keeps the binding; what reaches the runner
+ * is a plain `open` for the agent program, with the binding folded into its
+ * arguments.
+ */
+export interface AgentBinding {
+    runId: string;
+    agentMode: AgentMode;
+    /** The CLI's own resumable session identifier; `cli` mode only. */
+    cliSessionId?: string;
+}
 /** Client → runner: start a process in a new session. */
 export interface OpenFrame {
     type: 'open';
@@ -54,13 +76,27 @@ export interface OpenFrame {
     cols?: number;
     rows?: number;
     /**
-     * Ask for a terminal rather than a pipe. An interactive session gets a pty,
+     * Ask for a terminal rather than pipes. An interactive session gets a pty,
      * so its output is opaque terminal bytes (escape sequences and all) and its
      * geometry is part of the session — which is what makes `vim` render and
-     * reflow. Command mode (phase 1) is the default and unchanged.
+     * reflow. The default is a command on pipes: stdin in, stdout and stderr out
+     * (each `output` frame says which), no echo, no geometry.
      */
     interactive?: boolean;
+    /** Agent run this session executes locally. Requires `agentMode`. */
+    runId?: string;
+    /** How a bound session runs the agent. Requires `runId`. */
+    agentMode?: AgentMode;
+    /** The CLI's own session identifier; only with `agentMode: 'cli'`. */
+    cliSessionId?: string;
+    /**
+     * Working directory the session runs in, as a request: resolved against the
+     * runner's policy root, and refused when it would leave it.
+     */
+    cwd?: string;
 }
+/** The binding an `open` frame carries, or null for a plain session. */
+export declare function agentBinding(frame: OpenFrame): AgentBinding | null;
 /** Client → runner: bytes for the session's stdin. */
 export interface InputFrame {
     type: 'input';
@@ -124,6 +160,95 @@ export interface OutputFrame {
     type: 'output';
     sessionId: string;
     data: string;
+    /**
+     * Which pipe the bytes came from, on a non-interactive session. A terminal
+     * has one stream, so a pty session's output carries none; a program on
+     * pipes has two, and a consumer parsing stdout line by line (an agent's
+     * events) must not have stderr spliced into it.
+     */
+    stream?: 'stdout' | 'stderr';
+}
+export type AgentEvent = {
+    kind: 'session';
+    cliSessionId: string;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'tool_call';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: 'tool_result';
+    id: string;
+    output: unknown;
+    isError?: boolean;
+} | {
+    kind: 'approval_requested';
+    requestId: string;
+    tool: string;
+    input: unknown;
+    reason?: string;
+} | {
+    kind: 'approval_resolved';
+    requestId: string;
+    decision: 'allow' | 'deny';
+    reason?: string;
+} | {
+    kind: 'result';
+    ok: boolean;
+    summary?: string;
+    usage?: unknown;
+    costUsd?: number;
+};
+export declare const AGENT_EVENT_KINDS: readonly AgentEvent['kind'][];
+export interface AgentEventFrame {
+    type: 'agent_event';
+    sessionId: string;
+    event: AgentEvent;
+}
+export type ApprovalDecision = 'allow' | 'deny';
+/**
+ * The program the relay runs for a `cli` binding: it wraps the CLI the opener
+ * named (`claude`, `codex`) and translates its stream to this contract. The
+ * machine's policy must allow it by this exact name.
+ */
+export declare const AGENT_CLI_COMMAND = "constructive-agent-cli";
+/**
+ * Relay → agent program (a line on its stdin): the answer to an
+ * `approval_requested` event the program emitted. Carries no identity: who
+ * answered was the run's RLS, asked on the bound run's log.
+ */
+export interface ApprovalDecisionLine {
+    kind: 'approval_decision';
+    requestId: string;
+    decision: ApprovalDecision;
+    reason?: string;
+}
+export declare function encodeApprovalDecisionLine(line: ApprovalDecisionLine): string;
+/** The decision a stdin line carries, or null when the line is a prompt. */
+export declare function parseApprovalDecisionLine(line: string): ApprovalDecisionLine | null;
+/** The longest line a {@link LineSplitter} buffers before giving up on it. */
+export declare const MAX_LINE_LENGTH: number;
+/**
+ * Split a stream into the complete lines it has delivered so far. Keeps the
+ * unterminated tail for the next chunk; `flush` hands it over at the end. A
+ * tail that outgrows `maxLineLength` is dropped and reported, so a program
+ * that never writes a newline cannot grow the reader without bound.
+ */
+export declare class LineSplitter {
+    private readonly maxLineLength;
+    private tail;
+    constructor(maxLineLength?: number);
+    /**
+     * Complete lines are delivered before an oversized tail in the same chunk is
+     * reported: the failure is raised on the next call instead of losing them.
+     */
+    private overflowed;
+    push(chunk: string): string[];
+    private raiseOverflow;
+    flush(): string[];
 }
 /** Runner → client: the process ended. */
 export interface ExitFrame {
@@ -141,6 +266,8 @@ export interface ErrorFrame {
     type: 'error';
     sessionId?: string;
     message: string;
+    /** A stable, machine-readable reason, where the sender has one. */
+    code?: string;
 }
 /**
  * Runner → relay: the scrollback a detaching session leaves behind, capped by
@@ -199,8 +326,23 @@ export interface EnrolledFrame {
     expiresAt: number;
 }
 export type ClientToRunnerFrame = OpenFrame | InputFrame | ResizeFrame | SignalFrame | DetachFrame | ReattachFrame | CloseFrame;
-export type RunnerToClientFrame = OutputFrame | ExitFrame | ErrorFrame | ScrollbackFrame;
+export type RunnerToClientFrame = OutputFrame | AgentEventFrame | ExitFrame | ErrorFrame | ScrollbackFrame;
 export type Frame = ClientToRunnerFrame | RunnerToClientFrame | AttachedFrame | DetachedFrame | ReattachedFrame | EnrolledFrame;
+/**
+ * Whether `value` looks like an {@link AgentEvent} — an object naming one of
+ * the event kinds. Shape is not checked; that is {@link assertAgentEvent}. A
+ * headless agent process speaks these on its stdout one per line, and this is
+ * how a relaying runner tells an event line from any other line it prints.
+ */
+export declare function isAgentEventLike(value: unknown): value is Record<string, unknown> & {
+    kind: AgentEvent['kind'];
+};
+/**
+ * `value` as an {@link AgentEvent}, or a thrown protocol error naming what is
+ * wrong with it. `where` names the carrier in the message (the frame, a
+ * process's stdout) so the fault is attributed.
+ */
+export declare function assertAgentEvent(value: unknown, where?: string): AgentEvent;
 export declare function encodeFrame(frame: Frame): string;
 /**
  * Parse one wire message into a frame. Malformed input is a protocol fault on

package/index.js

@@ -15,6 +15,19 @@
 // a decision. That is what makes a reattach from a different client safe —
 // nothing about the attach that opened the session carries over.
 //
+// Two vocabularies live here, and the line between them is the line between the
+// runner and everything above it:
+//
+// - The *machine* frames (`open` … `exit`, plus enrollment) are the remote
+//   control. A runner speaks only these: it runs an allow-listed command in a
+//   pty or on pipes, moves bytes, reports the exit. It has no notion of what the
+//   command is.
+// - The *agent* vocabulary (`AgentBinding` on an `open`, `AgentEvent`, the
+//   `agent_event` frame, the stdio contract below) is between a client, the
+//   relay and an agent program running *under* the runner. The runner never
+//   reads or writes any of it; to the runner an agent program is a command on
+//   pipes whose stdout happens to be JSON lines.
+//
 // This package is vocabulary, never policy. Everything a socket puts on the wire
 // — its database, its machine id — is a *coordinate*: it says which row the
 // socket is asking about, and the relay answers by asking that database's SQL.
@@ -23,9 +36,14 @@
 // the tenant that issued it, and RLS decides everything after that. Addressing a
 // database you have no credential for is simply a refusal.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SIGNAL_NAMES = exports.attachSubprotocols = exports.ATTACH_SUBPROTOCOL = exports.clientAttachPath = exports.RUNNER_CONNECT_PATH = exports.HEADER_MACHINE_DATABASE = exports.HEADER_MACHINE_ID = void 0;
+exports.LineSplitter = exports.MAX_LINE_LENGTH = exports.AGENT_CLI_COMMAND = exports.AGENT_EVENT_KINDS = exports.SIGNAL_NAMES = exports.AGENT_MODES = exports.attachSubprotocols = exports.ATTACH_SUBPROTOCOL = exports.clientAttachPath = exports.RUNNER_CONNECT_PATH = exports.HEADER_MACHINE_DATABASE = exports.HEADER_MACHINE_ID = void 0;
 exports.credentialFromSubprotocols = credentialFromSubprotocols;
 exports.parseClientAttachPath = parseClientAttachPath;
+exports.agentBinding = agentBinding;
+exports.encodeApprovalDecisionLine = encodeApprovalDecisionLine;
+exports.parseApprovalDecisionLine = parseApprovalDecisionLine;
+exports.isAgentEventLike = isAgentEventLike;
+exports.assertAgentEvent = assertAgentEvent;
 exports.encodeFrame = encodeFrame;
 exports.decodeFrame = decodeFrame;
 // Token hashing is deliberately NOT re-exported here: it needs node's `crypto`,
@@ -95,6 +113,17 @@ function parseClientAttachPath(path) {
         machineId: decodeURIComponent(match[2])
     };
 }
+exports.AGENT_MODES = ['cli', 'embedded'];
+/** The binding an `open` frame carries, or null for a plain session. */
+function agentBinding(frame) {
+    if (frame.runId === undefined || frame.agentMode === undefined)
+        return null;
+    return {
+        runId: frame.runId,
+        agentMode: frame.agentMode,
+        ...(frame.cliSessionId !== undefined ? { cliSessionId: frame.cliSessionId } : {})
+    };
+}
 /**
  * Signals a client may ask for. `SIGINT` and `SIGQUIT` are the terminal's own
  * interrupt characters, so on a pty they are delivered the way a keyboard
@@ -103,6 +132,125 @@ function parseClientAttachPath(path) {
  * session. The rest are delivered to the session leader and do end it.
  */
 exports.SIGNAL_NAMES = ['SIGINT', 'SIGQUIT', 'SIGTERM', 'SIGHUP', 'SIGKILL'];
+exports.AGENT_EVENT_KINDS = [
+    'session',
+    'text',
+    'tool_call',
+    'tool_result',
+    'approval_requested',
+    'approval_resolved',
+    'result'
+];
+// ---------------------------------------------------------------------------
+// The agent program contract. An agent runs under the runner as an ordinary
+// non-interactive command; this is what it speaks on its pipes, and the relay
+// is the peer that reads and writes it — not the runner, which sees bytes.
+//
+//   stdin  — one prompt per line, and {@link ApprovalDecisionLine}s as JSON
+//            lines where the relay answers a question the program asked;
+//   stdout — {@link AgentEvent}s as JSON lines; any other line is plain output;
+//   stderr — plain output;
+//   exit   — the program's own.
+//
+// `constructive-agent-host` (`@constructive-db/agent-host`) speaks it natively.
+// `constructive-agent-cli` (`@constructive-db/agent-cli`) speaks it on behalf
+// of a coding-agent CLI (`claude`, `codex`) that does not.
+// ---------------------------------------------------------------------------
+/**
+ * The program the relay runs for a `cli` binding: it wraps the CLI the opener
+ * named (`claude`, `codex`) and translates its stream to this contract. The
+ * machine's policy must allow it by this exact name.
+ */
+exports.AGENT_CLI_COMMAND = 'constructive-agent-cli';
+function encodeApprovalDecisionLine(line) {
+    return `${JSON.stringify(line)}\n`;
+}
+/** The decision a stdin line carries, or null when the line is a prompt. */
+function parseApprovalDecisionLine(line) {
+    if (!line.startsWith('{'))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const value = parsed;
+    if (value.kind !== 'approval_decision')
+        return null;
+    if (typeof value.requestId !== 'string' || value.requestId.length === 0) {
+        throw new Error('machine-protocol: approval_decision line is missing requestId');
+    }
+    if (value.decision !== 'allow' && value.decision !== 'deny') {
+        throw new Error('machine-protocol: approval_decision line has invalid decision');
+    }
+    const reason = value.reason;
+    if (reason !== undefined && typeof reason !== 'string') {
+        throw new Error('machine-protocol: approval_decision line reason must be a string');
+    }
+    const decoded = {
+        kind: 'approval_decision',
+        requestId: value.requestId,
+        decision: value.decision
+    };
+    if (typeof reason === 'string')
+        decoded.reason = reason;
+    return decoded;
+}
+/** The longest line a {@link LineSplitter} buffers before giving up on it. */
+exports.MAX_LINE_LENGTH = 1024 * 1024;
+/**
+ * Split a stream into the complete lines it has delivered so far. Keeps the
+ * unterminated tail for the next chunk; `flush` hands it over at the end. A
+ * tail that outgrows `maxLineLength` is dropped and reported, so a program
+ * that never writes a newline cannot grow the reader without bound.
+ */
+class LineSplitter {
+    maxLineLength;
+    tail = '';
+    constructor(maxLineLength = exports.MAX_LINE_LENGTH) {
+        this.maxLineLength = maxLineLength;
+    }
+    /**
+     * Complete lines are delivered before an oversized tail in the same chunk is
+     * reported: the failure is raised on the next call instead of losing them.
+     */
+    overflowed = false;
+    push(chunk) {
+        this.raiseOverflow();
+        this.tail += chunk;
+        const lines = this.tail.split('\n');
+        this.tail = lines.pop() ?? '';
+        if (this.tail.length > this.maxLineLength) {
+            this.tail = '';
+            this.overflowed = true;
+            if (lines.length === 0)
+                this.raiseOverflow();
+        }
+        return lines.map(stripCarriageReturn);
+    }
+    raiseOverflow() {
+        if (!this.overflowed)
+            return;
+        this.overflowed = false;
+        throw new Error(`machine-protocol: line exceeds ${this.maxLineLength} characters without a newline`);
+    }
+    flush() {
+        this.raiseOverflow();
+        if (!this.tail)
+            return [];
+        const line = stripCarriageReturn(this.tail);
+        this.tail = '';
+        return [line];
+    }
+}
+exports.LineSplitter = LineSplitter;
+function stripCarriageReturn(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
 const FRAME_TYPES = new Set([
     'open',
     'input',
@@ -112,6 +260,7 @@ const FRAME_TYPES = new Set([
     'reattach',
     'close',
     'output',
+    'agent_event',
     'exit',
     'error',
     'scrollback',
@@ -130,6 +279,7 @@ const SESSION_FRAME_TYPES = new Set([
     'reattach',
     'close',
     'output',
+    'agent_event',
     'exit',
     'scrollback',
     'detached',
@@ -149,6 +299,105 @@ function validDimension(value) {
         value > 0 &&
         value <= MAX_DIMENSION);
 }
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether `value` looks like an {@link AgentEvent} — an object naming one of
+ * the event kinds. Shape is not checked; that is {@link assertAgentEvent}. A
+ * headless agent process speaks these on its stdout one per line, and this is
+ * how a relaying runner tells an event line from any other line it prints.
+ */
+function isAgentEventLike(value) {
+    return (isPlainObject(value) &&
+        typeof value.kind === 'string' &&
+        exports.AGENT_EVENT_KINDS.includes(value.kind));
+}
+/**
+ * `value` as an {@link AgentEvent}, or a thrown protocol error naming what is
+ * wrong with it. `where` names the carrier in the message (the frame, a
+ * process's stdout) so the fault is attributed.
+ */
+function assertAgentEvent(value, where = "'agent_event' frame") {
+    if (!isPlainObject(value)) {
+        throw new Error(`machine-protocol: ${where} is missing event`);
+    }
+    const event = value;
+    const kind = event.kind;
+    if (typeof kind !== 'string' || !exports.AGENT_EVENT_KINDS.includes(kind)) {
+        throw new Error(`machine-protocol: ${where} has unknown event kind '${String(kind)}'`);
+    }
+    const requiredString = (field) => {
+        if (typeof event[field] !== 'string') {
+            throw new Error(`machine-protocol: ${where} ${kind} event is missing ${field}`);
+        }
+    };
+    switch (kind) {
+        case 'session':
+            requiredString('cliSessionId');
+            break;
+        case 'text':
+            requiredString('text');
+            break;
+        case 'tool_call':
+            requiredString('id');
+            requiredString('name');
+            break;
+        case 'tool_result':
+            requiredString('id');
+            break;
+        case 'approval_requested':
+            requiredString('requestId');
+            requiredString('tool');
+            break;
+        case 'approval_resolved':
+            requiredString('requestId');
+            if (event.decision !== 'allow' && event.decision !== 'deny') {
+                throw new Error(`machine-protocol: ${where} approval_resolved event has invalid decision`);
+            }
+            break;
+        case 'result':
+            if (typeof event.ok !== 'boolean') {
+                throw new Error(`machine-protocol: ${where} result event is missing ok`);
+            }
+            break;
+    }
+    return event;
+}
+/**
+ * The agent-run binding, checked the way `machine_session`'s own constraint
+ * checks it, so a frame the tenant would refuse is refused before it is ever
+ * asked: `runId` and `agentMode` come together or not at all, `cliSessionId`
+ * names a CLI session and so needs `agentMode: 'cli'`, and a bound session is
+ * headless — it is the run's process, not a terminal — so `interactive` is a
+ * contradiction rather than an option.
+ */
+function validateAgentBinding(frame) {
+    const { runId, agentMode, cliSessionId } = frame;
+    if (runId !== undefined && (typeof runId !== 'string' || runId.length === 0)) {
+        throw new Error("machine-protocol: 'open' frame runId must be a non-empty string");
+    }
+    if (agentMode !== undefined && !exports.AGENT_MODES.includes(agentMode)) {
+        throw new Error(`machine-protocol: 'open' frame agentMode must be one of ${exports.AGENT_MODES.join(', ')}`);
+    }
+    if ((runId === undefined) !== (agentMode === undefined)) {
+        throw new Error("machine-protocol: 'open' frame needs both runId and agentMode, or neither");
+    }
+    if (cliSessionId !== undefined) {
+        if (typeof cliSessionId !== 'string' || cliSessionId.length === 0) {
+            throw new Error("machine-protocol: 'open' frame cliSessionId must be a non-empty string");
+        }
+        if (agentMode !== 'cli') {
+            throw new Error("machine-protocol: 'open' frame cliSessionId requires agentMode 'cli'");
+        }
+    }
+    if (runId !== undefined && frame.interactive === true) {
+        throw new Error("machine-protocol: 'open' frame bound to a run cannot be interactive");
+    }
+    if (frame.cwd !== undefined && (typeof frame.cwd !== 'string' || frame.cwd.length === 0)) {
+        throw new Error("machine-protocol: 'open' frame cwd must be a non-empty string");
+    }
+}
 function encodeFrame(frame) {
     return JSON.stringify(frame);
 }
@@ -186,12 +435,22 @@ function decodeFrame(raw) {
                     throw new Error(`machine-protocol: 'open' frame needs integer cols/rows in 1..${MAX_DIMENSION}`);
                 }
             }
+            validateAgentBinding(frame);
             break;
         case 'input':
         case 'output':
             if (typeof frame.data !== 'string') {
                 throw new Error(`machine-protocol: '${type}' frame is missing data`);
             }
+            if (type === 'output' &&
+                frame.stream !== undefined &&
+                frame.stream !== 'stdout' &&
+                frame.stream !== 'stderr') {
+                throw new Error("machine-protocol: 'output' frame stream must be 'stdout' or 'stderr'");
+            }
+            break;
+        case 'agent_event':
+            assertAgentEvent(frame.event);
             break;
         case 'resize':
             if (!validDimension(frame.cols) || !validDimension(frame.rows)) {

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@constructive-db/machine-protocol",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Wire protocol shared by the machine relay and the machine runner: the JSON frames a session is made of, and the codec that refuses malformed ones.",
   "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-protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
   "main": "index.js",
   "module": "esm/index.js",
   "types": "index.d.ts",
@@ -11,19 +20,13 @@
     "access": "public",
     "directory": "dist"
   },
-  "devDependencies": {
-    "@types/jest": "^29.5.14",
-    "@types/node": "^22.10.4",
-    "jest": "^29.7.0",
-    "makage": "^0.1.12",
-    "ts-jest": "^29.2.0",
-    "typescript": "^5.1.6"
-  },
   "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",
     "test": "jest"
-  }
-}
+  },
+  "gitHead": "81eed19332cc231de0fde02bc6e87002357f9536"
+}