@relayflows/sdk 2.0.0

package/dist/wrapper-session.js

@@ -0,0 +1,244 @@
+import { spawn } from 'node:child_process';
+import { WRAPPER_EXECUTE_TOKEN, WRAPPER_IDENTIFY_ARG, WRAPPER_IDENTIFY_TOKEN, } from './cli-adapter.js';
+import { captureWrapperIdentity, sameWrapperIdentity, } from './wrapper-runtime.js';
+const DEFAULT_LIMITS = {
+    handshakeTimeoutMs: 10_000,
+    executionTimeoutMs: 300_000,
+    maxOutputBytes: 1_048_576,
+};
+const HANDSHAKE_OUTPUT_LIMIT = 8_192;
+const FORCE_KILL_DELAY_MS = 1_000;
+/**
+ * Grace after `SIGKILL` before the reader settles on its own. Node emits
+ * `'close'` only once every inherited stdio pipe is closed, which any
+ * descendant of the wrapper can withhold forever. Resolution therefore may
+ * not depend on `'close'`: past this point the reader settles regardless.
+ */
+const SETTLE_AFTER_KILL_MS = 250;
+/**
+ * Identify and execute a custom wrapper in one pinned process. No private
+ * request is written until its declared path still names the captured file.
+ */
+export function runWrapperSession(cli, instruction, wakeContext, model, env, overrides = {}) {
+    const limits = sessionLimits(overrides);
+    let request;
+    try {
+        request = JSON.stringify({
+            protocol: WRAPPER_IDENTIFY_TOKEN,
+            instruction,
+            ...(model !== undefined ? { model } : {}),
+            ...(wakeContext !== undefined ? { wakeContext } : {}),
+        });
+    }
+    catch (error) {
+        return Promise.resolve(failure(`wake_context could not be JSON-serialized for the CLI: ${String(error)}`));
+    }
+    let identity;
+    try {
+        identity = captureWrapperIdentity(cli, env);
+    }
+    catch (error) {
+        return Promise.resolve(failure(`CLI ${JSON.stringify(cli)} wrapper identity could not be pinned: ${String(error)}`));
+    }
+    return executePinnedWrapper(cli, identity, request, env, limits);
+}
+function executePinnedWrapper(cli, identity, request, env, limits) {
+    return new Promise((resolve) => {
+        const child = spawn(identity.executable, [WRAPPER_IDENTIFY_ARG], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env,
+        });
+        const stdout = [];
+        const stderr = [];
+        let handshakePending = '';
+        let executionPending = '';
+        let capturedBytes = 0;
+        let phase = 'identity';
+        let protocolError;
+        let settled = false;
+        let lifecycleTimer;
+        let killTimer;
+        let settleTimer;
+        const clearTimers = () => {
+            if (lifecycleTimer !== undefined)
+                clearTimeout(lifecycleTimer);
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            if (settleTimer !== undefined)
+                clearTimeout(settleTimer);
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimers();
+            resolve(result);
+        };
+        const terminate = (message) => {
+            if (protocolError !== undefined)
+                return;
+            protocolError = message;
+            if (lifecycleTimer !== undefined)
+                clearTimeout(lifecycleTimer);
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => child.kill('SIGKILL'), FORCE_KILL_DELAY_MS);
+            killTimer.unref();
+            // The reader owns the bound. `'close'` is emitted only after every
+            // inherited stdio pipe closes, so a wrapper that leaves a descendant
+            // holding one withholds it forever and strands the step with no
+            // `completionReason` at all. Settle on our own deadline instead — the
+            // same shape `spawnInvocation` uses in worker-cli.ts, where the timer
+            // resolves rather than delegating to a child-controlled event. The
+            // result is byte-identical to the one the `'close'` path would build
+            // for this `protocolError`, so this changes only WHEN we settle.
+            settleTimer = setTimeout(() => finish(failure(message)), FORCE_KILL_DELAY_MS + SETTLE_AFTER_KILL_MS);
+        };
+        const startExecutionTimer = () => {
+            if (lifecycleTimer !== undefined)
+                clearTimeout(lifecycleTimer);
+            lifecycleTimer = setTimeout(() => terminate(`CLI ${JSON.stringify(cli)} execution timed out after ${limits.executionTimeoutMs}ms.`), limits.executionTimeoutMs);
+        };
+        const exceedsOutputLimit = (additionalBytes) => {
+            const pendingBytes = Buffer.byteLength(executionPending);
+            if (capturedBytes + pendingBytes + additionalBytes <= limits.maxOutputBytes)
+                return false;
+            terminate(`CLI ${JSON.stringify(cli)} exceeded the captured output limit of ${limits.maxOutputBytes} bytes.`);
+            return true;
+        };
+        const appendStdout = (value) => {
+            const bytes = Buffer.byteLength(value);
+            capturedBytes += bytes;
+            stdout.push(value);
+        };
+        const acceptHandshakeLine = (line) => {
+            const normalized = normalizeLine(line);
+            if (phase === 'identity') {
+                if (normalized !== WRAPPER_IDENTIFY_TOKEN) {
+                    terminate(`CLI ${JSON.stringify(cli)} did not identify as ${WRAPPER_IDENTIFY_TOKEN} at worker execution.`);
+                    return;
+                }
+                if (!sameWrapperIdentity(cli, env, identity)) {
+                    terminate(`CLI ${JSON.stringify(cli)} wrapper identity changed before private request delivery.`);
+                    return;
+                }
+                phase = 'ack';
+                child.stdin.end(`${request}\n`);
+                return;
+            }
+            if (phase === 'ack') {
+                if (normalized !== WRAPPER_EXECUTE_TOKEN) {
+                    terminate(`CLI ${JSON.stringify(cli)} did not accept the ${WRAPPER_IDENTIFY_TOKEN} same-process execution request.`);
+                    return;
+                }
+                phase = 'execute';
+                startExecutionTimer();
+            }
+        };
+        const acceptExecutionData = (chunk) => {
+            executionPending += chunk;
+            if (exceedsOutputLimit(0))
+                return;
+            while (true) {
+                const newline = executionPending.indexOf('\n');
+                if (newline < 0)
+                    return;
+                const line = executionPending.slice(0, newline);
+                executionPending = executionPending.slice(newline + 1);
+                if (normalizeLine(line) === WRAPPER_EXECUTE_TOKEN) {
+                    terminate(`CLI ${JSON.stringify(cli)} emitted a duplicate execute protocol frame.`);
+                    return;
+                }
+                appendStdout(`${line}\n`);
+            }
+        };
+        const handshakeComplete = () => phase === 'execute';
+        lifecycleTimer = setTimeout(() => terminate(`CLI ${JSON.stringify(cli)} did not identify as ${WRAPPER_IDENTIFY_TOKEN} within ${limits.handshakeTimeoutMs}ms.`), limits.handshakeTimeoutMs);
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            if (protocolError !== undefined)
+                return;
+            if (phase === 'execute') {
+                acceptExecutionData(chunk);
+                return;
+            }
+            handshakePending += chunk;
+            // Drain every complete line FIRST. The handshake bound belongs to the
+            // handshake, and a line that is already terminated is no longer part
+            // of it: the execute token sitting at the front of this buffer ends
+            // the handshake, and the bytes behind it are execution output bound by
+            // `maxOutputBytes`. Measuring the whole buffer before draining capped a
+            // conforming wrapper's first result flush at HANDSHAKE_OUTPUT_LIMIT
+            // whenever the OS coalesced its writes, and named the wrong bound.
+            while (!handshakeComplete()) {
+                const newline = handshakePending.indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = handshakePending.slice(0, newline);
+                handshakePending = handshakePending.slice(newline + 1);
+                acceptHandshakeLine(line);
+                if (protocolError !== undefined)
+                    return;
+            }
+            if (handshakeComplete()) {
+                if (handshakePending.length > 0) {
+                    const remainder = handshakePending;
+                    handshakePending = '';
+                    acceptExecutionData(remainder);
+                }
+                return;
+            }
+            // Still handshaking: bound the un-terminated residue, which is the only
+            // buffer the handshake still owns.
+            if (Buffer.byteLength(handshakePending) > HANDSHAKE_OUTPUT_LIMIT) {
+                terminate(`CLI ${JSON.stringify(cli)} exceeded the wrapper handshake limit of ${HANDSHAKE_OUTPUT_LIMIT} bytes before completing the ${WRAPPER_IDENTIFY_TOKEN} handshake.`);
+            }
+        });
+        child.stderr.on('data', (chunk) => {
+            if (protocolError !== undefined || exceedsOutputLimit(chunk.byteLength))
+                return;
+            capturedBytes += chunk.byteLength;
+            stderr.push(chunk);
+        });
+        child.stdin.on('error', () => {
+            // A child that closes stdin before acknowledgement is classified on close.
+        });
+        child.once('error', (error) => finish(failure(error.message)));
+        child.once('close', (code) => {
+            if (protocolError === undefined && phase === 'execute' && executionPending.length > 0) {
+                if (normalizeLine(executionPending) === WRAPPER_EXECUTE_TOKEN) {
+                    protocolError = `CLI ${JSON.stringify(cli)} emitted a duplicate execute protocol frame.`;
+                }
+                else if (!exceedsOutputLimit(0)) {
+                    appendStdout(executionPending);
+                }
+            }
+            if (protocolError !== undefined || phase !== 'execute') {
+                finish(failure(protocolError
+                    ?? `CLI ${JSON.stringify(cli)} exited before completing the ${WRAPPER_IDENTIFY_TOKEN} same-process handshake.`));
+                return;
+            }
+            finish({
+                exit_code: code,
+                stdout_tail: stdout.join(''),
+                stderr_tail: Buffer.concat(stderr).toString('utf8'),
+            });
+        });
+    });
+}
+function sessionLimits(overrides) {
+    return {
+        handshakeTimeoutMs: positiveLimit(overrides.handshakeTimeoutMs, DEFAULT_LIMITS.handshakeTimeoutMs),
+        executionTimeoutMs: positiveLimit(overrides.executionTimeoutMs, DEFAULT_LIMITS.executionTimeoutMs),
+        maxOutputBytes: positiveLimit(overrides.maxOutputBytes, DEFAULT_LIMITS.maxOutputBytes),
+    };
+}
+function positiveLimit(value, fallback) {
+    return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+function normalizeLine(line) {
+    return line.endsWith('\r') ? line.slice(0, -1) : line;
+}
+function failure(stderr_tail) {
+    return { exit_code: null, stdout_tail: '', stderr_tail };
+}
+//# sourceMappingURL=wrapper-session.js.map

package/dist/wrapper-session.js.map

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@relayflows/sdk",
+  "version": "2.0.0",
+  "description": "TypeScript-first authoring SDK for Relayflows. Compiles specs; speaks the journal protocol.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "flows": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/make-cli-executable.mjs",
+    "demo:hn": "npm run build && node dist/demo-hn-monitor.js",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.type-tests.json",
+    "typecheck:tests": "tsc -p tsconfig.tests.json",
+    "test:prep": "( cd ../../kernel && sh ../ops/cargo.sh build ) && ( [ ! -d ../../testdata/preflight ] || find ../../testdata/preflight -name '*-cli' -type f -exec chmod +x {} + )",
+    "test": "sh scripts/test.sh",
+    "test:watch": "vitest"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@relayflows/surface": "2.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "ajv": "^8.17.1",
+    "ajv-draft-04": "^1.0.0",
+    "js-yaml": "^5.4.1",
+    "yaml": "^2.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/flows.git",
+    "directory": "packages/sdk"
+  }
+}

package/src/authored-flow-error.ts

@@ -0,0 +1,31 @@
+import type {
+  CompletionReason as ProtocolCompletionReason,
+  RunCompletionReason as ProtocolRunCompletionReason,
+} from './protocol.js';
+
+export type AuthoredFlowExecutionErrorCode =
+  | 'duplicate_completion'
+  | 'journal_protocol_violation'
+  | 'missing_completion'
+  | 'operation_after_completion'
+  | 'operation_callback_failed'
+  | 'step_failed'
+  | 'unsupported_completion'
+  | 'unsupported_gate'
+  | 'unsupported_header'
+  | 'unsettled_derived_work'
+  | 'unsupported_promise_lifecycle'
+  | 'unawaited_step'
+  | 'unsupported_verb';
+
+export class AuthoredFlowExecutionError extends Error {
+  constructor(
+    readonly code: AuthoredFlowExecutionErrorCode,
+    message: string,
+    readonly completionReason?: ProtocolCompletionReason | ProtocolRunCompletionReason,
+    readonly runId?: string,
+  ) {
+    super(`${code}: ${message}`);
+    this.name = 'AuthoredFlowExecutionError';
+  }
+}