conductor-remote 1.107.0 → 1.108.0

package/dist-node/src/workflow-effect-runner.js

@@ -0,0 +1,336 @@
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_KILL_GRACE_MS = 500;
+const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
+const GATE_PROTOCOL_VERSION = 1;
+/**
+ * The wrapper receives no target command in argv or its environment. It waits for
+ * one newline-delimited descriptor on private fd 3, then and only then spawns the
+ * target inside its own process group. Pipe EOF before that descriptor is a no-op.
+ */
+const GATED_WRAPPER_SOURCE = String.raw `
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+const gate = fs.createReadStream(null, { fd: 3, encoding: 'utf8', autoClose: true });
+let input = '';
+let launched = false;
+const fail = code => { if (!launched) process.exit(code); };
+gate.on('data', chunk => {
+  if (launched) return;
+  input += chunk;
+  if (Buffer.byteLength(input) > 4 * 1024 * 1024) return fail(76);
+  const newline = input.indexOf('\n');
+  if (newline < 0) return;
+  launched = true;
+  gate.destroy();
+  let message;
+  try { message = JSON.parse(input.slice(0, newline)); } catch { return process.exit(77); }
+  if (!message || message.version !== ${GATE_PROTOCOL_VERSION} || message.go !== true || typeof message.command !== 'string') {
+    return process.exit(78);
+  }
+  const child = spawn(message.command, message.args || [], {
+    cwd: message.cwd || undefined,
+    env: { ...process.env, ...(message.env || {}) },
+    shell: false,
+    stdio: ['ignore', 'inherit', 'inherit']
+  });
+  child.once('error', error => {
+    process.stderr.write(String(error && error.stack || error));
+    process.exit(79);
+  });
+  child.once('exit', (code, signal) => {
+    if (signal) {
+      process.stderr.write('\n[target terminated by ' + signal + ']');
+      process.exit(80);
+    }
+    process.exit(code == null ? 81 : code);
+  });
+});
+gate.once('end', () => fail(74));
+gate.once('error', () => fail(75));
+`;
+export class WorkflowGatedCommandError extends Error {
+    code;
+    phase;
+    mayHaveExecuted;
+    externalProcess;
+    stdout;
+    stderr;
+    constructor(code, message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'WorkflowGatedCommandError';
+        this.code = code;
+        this.phase = options.phase;
+        this.mayHaveExecuted = options.phase === 'after_gate';
+        this.externalProcess = options.externalProcess;
+        this.stdout = options.stdout ?? '';
+        this.stderr = options.stderr ?? '';
+    }
+}
+function validate(options) {
+    if (!options.command.trim() || options.command.includes('\0')) {
+        throw new WorkflowGatedCommandError('invalid_command', 'Workflow gated command must be non-empty.', {
+            phase: 'before_gate'
+        });
+    }
+    for (const argument of options.args ?? []) {
+        if (argument.includes('\0')) {
+            throw new WorkflowGatedCommandError('invalid_command', 'Workflow gated command arguments cannot contain NUL.', {
+                phase: 'before_gate'
+            });
+        }
+    }
+    if (options.cwd?.includes('\0')) {
+        throw new WorkflowGatedCommandError('invalid_command', 'Workflow gated command cwd cannot contain NUL.', {
+            phase: 'before_gate'
+        });
+    }
+    for (const [name, value] of Object.entries(options.env ?? {})) {
+        if (!name || name.includes('=') || name.includes('\0') || value.includes('\0')) {
+            throw new WorkflowGatedCommandError('invalid_command', 'Workflow gated command environment is invalid.', {
+                phase: 'before_gate'
+            });
+        }
+    }
+}
+async function processStartedAt(pid) {
+    const { stdout } = await execFileAsync('/bin/ps', ['-o', 'lstart=', '-p', String(pid)], {
+        timeout: 2_000,
+        maxBuffer: 16_384
+    });
+    const value = stdout.trim().replace(/\s+/g, ' ');
+    if (!value)
+        throw new Error(`ps returned no start identity for PID ${pid}`);
+    return value;
+}
+function terminateGroup(pid, signal) {
+    if (!Number.isSafeInteger(pid) || pid <= 1)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error))
+            throw error;
+        if (error.code === 'ESRCH')
+            return;
+        // A just-spawned detached child can briefly exist before setsid has made its
+        // PID addressable as a process group. Killing that exact validated PID keeps
+        // the still-closed gate safe; after release the group path is required.
+        if (error.code === 'EPERM') {
+            try {
+                process.kill(pid, signal);
+            }
+            catch (fallback) {
+                if (!fallback || typeof fallback !== 'object' || !('code' in fallback) || fallback.code !== 'ESRCH')
+                    throw fallback;
+            }
+            return;
+        }
+        throw error;
+    }
+}
+function closeGate(gate) {
+    if (!gate.destroyed)
+        gate.destroy();
+}
+/**
+ * Execute one external GUI helper with a crash-safe start gate.
+ *
+ * The durable callback observes the blocked wrapper first. Only after it resolves
+ * does GO plus the private command descriptor cross fd 3. The detached wrapper
+ * remains the process-group leader until the target exits, so recovery has one
+ * stable PID/start identity and timeout cleanup can address the whole group.
+ */
+export async function runGatedWorkflowCommand(options) {
+    validate(options);
+    const timeoutMs = Math.max(1, Math.floor(options.timeoutMs ?? DEFAULT_TIMEOUT_MS));
+    const killGraceMs = Math.max(1, Math.floor(options.killGraceMs ?? DEFAULT_KILL_GRACE_MS));
+    const maxOutputBytes = Math.max(1, Math.floor(options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES));
+    let wrapper;
+    try {
+        wrapper = spawn(process.execPath, ['-e', GATED_WRAPPER_SOURCE], {
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe', 'pipe']
+        });
+    }
+    catch (cause) {
+        throw new WorkflowGatedCommandError('spawn_failed', 'Could not spawn the gated Workflow wrapper.', {
+            phase: 'before_gate',
+            cause
+        });
+    }
+    const pid = wrapper.pid;
+    const gate = wrapper.stdio[3];
+    if (!pid || pid <= 1 || !gate) {
+        wrapper.kill();
+        throw new WorkflowGatedCommandError('spawn_failed', 'The gated Workflow wrapper exposed no safe PID or pipe.', {
+            phase: 'before_gate'
+        });
+    }
+    let stdout = '';
+    let stderr = '';
+    let outputBytes = 0;
+    let gateReleased = false;
+    let timeout = false;
+    let aborted = options.signal?.aborted ?? false;
+    let outputLimit = false;
+    let settled = false;
+    let forceKillTimer;
+    let completionResolve;
+    const completion = new Promise(resolve => {
+        completionResolve = resolve;
+    });
+    const settle = (value) => {
+        if (settled)
+            return;
+        settled = true;
+        if (forceKillTimer)
+            clearTimeout(forceKillTimer);
+        completionResolve?.(value);
+    };
+    const armForceKill = () => {
+        if (forceKillTimer || settled)
+            return;
+        forceKillTimer = setTimeout(() => terminateGroup(pid, 'SIGKILL'), killGraceMs);
+    };
+    const collect = (stream, chunk) => {
+        outputBytes += chunk.byteLength;
+        if (outputBytes > maxOutputBytes) {
+            outputLimit = true;
+            terminateGroup(pid, 'SIGTERM');
+            armForceKill();
+            return;
+        }
+        if (stream === 'stdout')
+            stdout += chunk.toString('utf8');
+        else
+            stderr += chunk.toString('utf8');
+    };
+    wrapper.stdout?.on('data', chunk => collect('stdout', Buffer.from(chunk)));
+    wrapper.stderr?.on('data', chunk => collect('stderr', Buffer.from(chunk)));
+    wrapper.once('error', () => settle({ code: null, signal: null }));
+    wrapper.once('close', (code, signal) => settle({ code, signal }));
+    const abort = () => {
+        aborted = true;
+        closeGate(gate);
+        terminateGroup(pid, 'SIGTERM');
+        armForceKill();
+    };
+    options.signal?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => {
+        timeout = true;
+        closeGate(gate);
+        terminateGroup(pid, 'SIGTERM');
+        armForceKill();
+    }, timeoutMs);
+    let externalProcess;
+    try {
+        let startedAt;
+        try {
+            startedAt = await (options.readProcessStartedAt ?? processStartedAt)(pid);
+        }
+        catch (cause) {
+            closeGate(gate);
+            terminateGroup(pid, 'SIGTERM');
+            throw new WorkflowGatedCommandError('identity_failed', 'Could not prove the gated wrapper process identity.', {
+                phase: 'before_gate',
+                cause
+            });
+        }
+        externalProcess = { pid, processStartedAt: startedAt, processGroup: pid };
+        if (aborted || timeout) {
+            throw new WorkflowGatedCommandError(aborted ? 'aborted' : 'timed_out', 'Workflow command stopped before gate registration.', {
+                phase: 'before_gate',
+                externalProcess
+            });
+        }
+        try {
+            await options.onSpawned(externalProcess);
+        }
+        catch (cause) {
+            closeGate(gate);
+            terminateGroup(pid, 'SIGTERM');
+            throw new WorkflowGatedCommandError('gate_rejected', 'Durable Workflow process registration failed before gate release.', { phase: 'before_gate', externalProcess, cause });
+        }
+        if (aborted || timeout) {
+            throw new WorkflowGatedCommandError(aborted ? 'aborted' : 'timed_out', 'Workflow command stopped before gate release.', {
+                phase: 'before_gate',
+                externalProcess
+            });
+        }
+        const descriptor = JSON.stringify({
+            version: GATE_PROTOCOL_VERSION,
+            go: true,
+            command: options.command,
+            args: [...(options.args ?? [])],
+            ...(options.cwd ? { cwd: options.cwd } : {}),
+            ...(options.env ? { env: options.env } : {})
+        });
+        await new Promise((resolve, reject) => {
+            const failed = (error) => reject(error);
+            gate.once('error', failed);
+            gate.end(`${descriptor}\n`, () => {
+                gate.off('error', failed);
+                resolve();
+            });
+        });
+        gateReleased = true;
+        const finished = await completion;
+        if (timeout) {
+            throw new WorkflowGatedCommandError('timed_out', 'Workflow command exceeded its deadline.', {
+                phase: 'after_gate',
+                externalProcess,
+                stdout,
+                stderr
+            });
+        }
+        if (aborted) {
+            throw new WorkflowGatedCommandError('aborted', 'Workflow command was aborted.', {
+                phase: 'after_gate',
+                externalProcess,
+                stdout,
+                stderr
+            });
+        }
+        if (outputLimit) {
+            throw new WorkflowGatedCommandError('output_limit', 'Workflow command exceeded its output limit.', {
+                phase: 'after_gate',
+                externalProcess,
+                stdout,
+                stderr
+            });
+        }
+        if (finished.code !== 0) {
+            throw new WorkflowGatedCommandError('command_failed', `Workflow command exited with ${finished.signal ?? finished.code ?? 'no status'}.`, { phase: 'after_gate', externalProcess, stdout, stderr });
+        }
+        return { code: 0, stdout, stderr, externalProcess };
+    }
+    catch (error) {
+        if (!settled) {
+            closeGate(gate);
+            terminateGroup(pid, 'SIGTERM');
+            await Promise.race([completion, new Promise(resolve => setTimeout(resolve, killGraceMs))]);
+            if (!settled)
+                terminateGroup(pid, 'SIGKILL');
+            await completion;
+        }
+        if (error instanceof WorkflowGatedCommandError)
+            throw error;
+        throw new WorkflowGatedCommandError('gate_rejected', 'The private Workflow execution gate failed.', {
+            phase: gateReleased ? 'after_gate' : 'before_gate',
+            externalProcess,
+            stdout,
+            stderr,
+            cause: error
+        });
+    }
+    finally {
+        clearTimeout(timer);
+        if (forceKillTimer)
+            clearTimeout(forceKillTimer);
+        options.signal?.removeEventListener('abort', abort);
+    }
+}

package/dist-node/src/workflow-http.js

@@ -0,0 +1,141 @@
+export class WorkflowRequestError extends Error {
+    status;
+    code;
+    constructor(message, status = 400) {
+        super(message);
+        this.name = 'WorkflowRequestError';
+        this.status = status;
+        this.code = status === 403 ? 'workflow_authorization_failed' : 'invalid_request';
+    }
+}
+function record(value, name) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new WorkflowRequestError(`${name} must be an object.`);
+    }
+    return value;
+}
+function exact(value, allowed, name) {
+    const fields = new Set(allowed);
+    const unknown = Object.keys(value).filter(field => !fields.has(field));
+    if (unknown.length)
+        throw new WorkflowRequestError(`${name} has unknown field ${unknown.join(', ')}.`);
+}
+function text(value, name, maximum = 256) {
+    if (typeof value !== 'string' || !value.trim() || value.length > maximum) {
+        throw new WorkflowRequestError(`${name} is required.`);
+    }
+    return value.trim();
+}
+function clientId(value) {
+    return text(value, 'clientId', 256);
+}
+export function parseStartWorkflowRequest(raw) {
+    const body = record(raw, 'Workflow request');
+    exact(body, ['clientId', 'objective', 'target'], 'Workflow request');
+    const target = record(body.target, 'target');
+    const objective = text(body.objective, 'objective', 1_000_000);
+    const id = clientId(body.clientId);
+    if (target.kind === 'new_workspace') {
+        exact(target, ['kind', 'repo', 'sendImmediately'], 'new-workspace target');
+        if (typeof target.sendImmediately !== 'boolean') {
+            throw new WorkflowRequestError('target.sendImmediately must be a boolean.');
+        }
+        return {
+            clientId: id,
+            objective,
+            target: {
+                kind: 'new_workspace',
+                repo: text(target.repo, 'target.repo'),
+                sendImmediately: target.sendImmediately
+            }
+        };
+    }
+    if (target.kind === 'existing_session') {
+        exact(target, ['kind', 'workspaceId', 'sessionId'], 'existing-session target');
+        return {
+            clientId: id,
+            objective,
+            target: {
+                kind: 'existing_session',
+                workspaceId: text(target.workspaceId, 'target.workspaceId'),
+                sessionId: text(target.sessionId, 'target.sessionId')
+            }
+        };
+    }
+    throw new WorkflowRequestError('target.kind must be new_workspace or existing_session.');
+}
+export function parseWorkflowDelegateRequest(raw, workflowId) {
+    const body = record(raw, 'Workflow delegation');
+    exact(body, ['workflow_id', 'phase_capability', 'session_id', 'role', 'prompt'], 'Workflow delegation');
+    const bodyWorkflowId = text(body.workflow_id, 'workflow_id');
+    if (bodyWorkflowId !== workflowId) {
+        throw new WorkflowRequestError('The body workflow_id does not match the route.', 403);
+    }
+    if (body.role !== 'exploration' && body.role !== 'implementation') {
+        throw new WorkflowRequestError('role must be exploration or implementation.');
+    }
+    return {
+        workflow_id: bodyWorkflowId,
+        phase_capability: text(body.phase_capability, 'phase_capability', 512),
+        session_id: text(body.session_id, 'session_id'),
+        role: body.role,
+        prompt: text(body.prompt, 'prompt', 1_000_000)
+    };
+}
+export function parseWorkflowRetryRequest(raw) {
+    const body = record(raw, 'Workflow retry');
+    exact(body, ['clientId'], 'Workflow retry');
+    return { clientId: clientId(body.clientId) };
+}
+export function parseWorkflowCompleteRequest(raw) {
+    const body = record(raw, 'Workflow completion');
+    exact(body, ['clientId'], 'Workflow completion');
+    return { clientId: clientId(body.clientId) };
+}
+export function parseWorkflowAdoptRequest(raw) {
+    const body = record(raw, 'Workflow adoption');
+    exact(body, ['clientId', 'actionId', 'workspaceId', 'sessionId'], 'Workflow adoption');
+    const workspaceId = body.workspaceId === undefined ? undefined : text(body.workspaceId, 'workspaceId');
+    const sessionId = body.sessionId === undefined ? undefined : text(body.sessionId, 'sessionId');
+    const request = {
+        clientId: clientId(body.clientId),
+        actionId: text(body.actionId, 'actionId')
+    };
+    if (workspaceId && !sessionId)
+        return { ...request, workspaceId };
+    if (sessionId && !workspaceId)
+        return { ...request, sessionId };
+    throw new WorkflowRequestError('Adoption requires exactly one workspaceId or sessionId.');
+}
+export function parseWorkflowReplayRequest(raw) {
+    const body = record(raw, 'Workflow replay');
+    exact(body, ['clientId', 'actionId', 'confirmDuplicateRisk'], 'Workflow replay');
+    if (body.confirmDuplicateRisk !== true) {
+        throw new WorkflowRequestError('confirmDuplicateRisk must be true.');
+    }
+    return {
+        clientId: clientId(body.clientId),
+        actionId: text(body.actionId, 'actionId'),
+        confirmDuplicateRisk: true
+    };
+}
+export function parseConfirmUiStableRequest(raw) {
+    const body = record(raw, 'UI stability confirmation');
+    exact(body, ['clientId', 'confirmStable', 'createdAt', 'actionId', 'effectId'], 'UI stability confirmation');
+    if (body.confirmStable !== true) {
+        throw new WorkflowRequestError('confirmStable must be true.');
+    }
+    if (!Number.isSafeInteger(body.createdAt) || body.createdAt < 0) {
+        throw new WorkflowRequestError('createdAt must identify the displayed UI safety hold.');
+    }
+    return {
+        clientId: clientId(body.clientId),
+        confirmStable: true,
+        createdAt: body.createdAt,
+        ...(body.actionId === undefined ? {} : { actionId: text(body.actionId, 'actionId') }),
+        ...(body.effectId === undefined ? {} : { effectId: text(body.effectId, 'effectId') })
+    };
+}
+export function workflowClientIsMcp(headers) {
+    return headers['x-relay-client'] === 'mcp';
+}

package/dist-node/src/workflow-machine.js

@@ -0,0 +1,112 @@
+export class WorkflowGuardError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 409) {
+        super(message);
+        this.name = 'WorkflowGuardError';
+        this.code = code;
+        this.status = status;
+    }
+}
+export function isTerminalWorkflowPhase(phase) {
+    return phase === 'completed' || phase === 'cancelled';
+}
+export function isTerminalWorkflowJobState(state) {
+    return state === 'returned' || state === 'failed' || state === 'cancelled';
+}
+/** Which managed child role the root may request at this evidence barrier. */
+export function workflowAllowedRoles(phase) {
+    if (phase === 'exploring')
+        return ['exploration'];
+    if (phase === 'planning' || phase === 'reviewing')
+        return ['exploration', 'implementation'];
+    return [];
+}
+export function workflowOutstandingJobs(jobs, cycle) {
+    return jobs.filter(job => job.cycle === cycle && !isTerminalWorkflowJobState(job.status));
+}
+export function workflowExplorationBarrierSatisfied(jobs, cycle) {
+    const explorers = jobs.filter(job => job.cycle === cycle && job.role === 'exploration');
+    return explorers.length > 0 && explorers.every(job => job.status === 'returned' && job.batonReceiptKind === 'message');
+}
+export function workflowImplementationBarrierSatisfied(jobs, cycle) {
+    const implementers = jobs.filter(job => job.cycle === cycle && job.role === 'implementation');
+    return (implementers.length > 0 &&
+        implementers.every(job => job.status === 'returned' && job.batonReceiptKind === 'message'));
+}
+/**
+ * Validate a root delegation against the capability that was causally delivered
+ * to that exact chat. This is intentionally pure; the caller still consumes or
+ * rotates the matching database row in the same transaction that creates a job.
+ */
+export function assertWorkflowDelegation(run, claims, request, jobs) {
+    if (!run) {
+        throw new WorkflowGuardError('workflow_required', 'delegate_task is available only inside a UI-authorized Workflow.');
+    }
+    if (run.phase === 'blocked') {
+        throw new WorkflowGuardError('workflow_blocked', 'This Workflow is blocked and needs recovery from the phone.');
+    }
+    if (isTerminalWorkflowPhase(run.phase)) {
+        throw new WorkflowGuardError('workflow_phase_invalid', `This Workflow is ${run.phase}.`);
+    }
+    if (!run.rootSessionId || request.sessionId !== run.rootSessionId) {
+        throw new WorkflowGuardError('workflow_authorization_failed', 'The phase capability does not authorize this root session.', 403);
+    }
+    if (!claims ||
+        claims.consumed ||
+        claims.revoked ||
+        claims.runId !== run.id ||
+        claims.rootSessionId !== run.rootSessionId) {
+        throw new WorkflowGuardError('workflow_authorization_failed', 'The phase capability is missing, invalid, consumed, or revoked.', 403);
+    }
+    if (claims.cycle !== run.cycle ||
+        claims.revision !== run.revision ||
+        claims.phase !== run.phase ||
+        !claims.allowedRoles.includes(request.role)) {
+        throw new WorkflowGuardError('workflow_phase_invalid', 'That phase capability is stale or does not permit the requested role.');
+    }
+    if (!workflowAllowedRoles(run.phase).includes(request.role)) {
+        throw new WorkflowGuardError('workflow_phase_invalid', `Role ${request.role} cannot start while the Workflow is ${run.phase}.`);
+    }
+    const outstanding = workflowOutstandingJobs(jobs, run.cycle);
+    const conflicting = run.phase === 'exploring' && request.role === 'exploration'
+        ? outstanding.some(job => job.role === 'implementation')
+        : outstanding.length > 0;
+    if (conflicting) {
+        throw new WorkflowGuardError('workflow_phase_invalid', 'The current Workflow job must return before another phase can start.');
+    }
+    if (request.role === 'implementation' && !workflowExplorationBarrierSatisfied(jobs, run.cycle)) {
+        throw new WorkflowGuardError('workflow_phase_invalid', 'Implementation remains closed until every current explorer Baton is delivered.');
+    }
+}
+/** The transition materialized atomically beside capability consumption and job creation. */
+export function workflowDelegationTransition(run, role) {
+    if (role === 'implementation') {
+        return {
+            phase: 'implementing',
+            cycle: run.cycle,
+            revision: run.revision + 1,
+            logicalPrefix: 'implement'
+        };
+    }
+    if (run.phase === 'exploring') {
+        return {
+            phase: 'exploring',
+            cycle: run.cycle,
+            revision: run.revision + 1,
+            logicalPrefix: 'explore'
+        };
+    }
+    return {
+        phase: 'exploring',
+        cycle: run.cycle + 1,
+        revision: 0,
+        logicalPrefix: 'explore'
+    };
+}
+/** Delivered Batons, never merely accepted outbox rows, open the next root phase. */
+export function phaseAfterDeliveredBaton(role, jobs, cycle) {
+    if (role === 'exploration')
+        return workflowExplorationBarrierSatisfied(jobs, cycle) ? 'planning' : null;
+    return workflowImplementationBarrierSatisfied(jobs, cycle) ? 'reviewing' : null;
+}