conductor-remote 1.116.0 → 1.118.0

package/dist-node/src/orchestration/persistence/runs.js

@@ -0,0 +1,156 @@
+import { randomUUID } from 'node:crypto';
+import { isTerminalWorkflowPhase } from "../workflow/machine.js";
+import { insertEffect } from "./effects.js";
+import { OrchestrationError, WorkflowTransitionError } from "./errors.js";
+import { appendEvent } from "./events.js";
+import { idempotentMutation } from "./idempotency.js";
+import { insertJob } from "./jobs.js";
+import { checkRunGuard, getWorkflowRun, requireRun } from "./records.js";
+import { isConstraintError, json, nonEmpty, optionalJson } from "./values.js";
+export function createWorkflowRun(context, input) {
+    const initialEffects = input.initialEffects ?? (input.initialEffect ? [input.initialEffect] : []);
+    if (new Set(initialEffects.map(effect => effect.actionId)).size !== initialEffects.length) {
+        throw new OrchestrationError('initial Workflow effects must have unique action IDs');
+    }
+    // Idempotency belongs to the normalized UI request, not to derived preflight
+    // evidence. Re-reading roles or the now-non-pristine root on a transport retry
+    // must not turn the same tap into a conflict.
+    const request = { objective: input.objective, target: input.target };
+    let createdRunId;
+    const answer = idempotentMutation(context, 'start_workflow', input.clientId, request, () => {
+        const runId = input.id ?? randomUUID();
+        createdRunId = runId;
+        const at = context.now();
+        const phase = input.target.kind === 'new_workspace' ? 'creating_workspace' : 'pending_root';
+        if (input.target.kind === 'existing_session') {
+            if (input.workspaceId && input.workspaceId !== input.target.workspaceId) {
+                throw new OrchestrationError('workspace binding conflicts with the existing-session target');
+            }
+            if (input.rootSessionId && input.rootSessionId !== input.target.sessionId) {
+                throw new OrchestrationError('root binding conflicts with the existing-session target');
+            }
+        }
+        try {
+            context.db
+                .prepare(`INSERT INTO workflow_runs (
+							id, objective, target_json, roles_json, phase, workspace_id, root_session_id,
+							pristine_evidence_json, delivery_baseline_json, created_at, updated_at
+						) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(runId, nonEmpty(input.objective, 'objective'), json(input.target), json(input.roles), phase, input.target.kind === 'existing_session' ? input.target.workspaceId : (input.workspaceId ?? null), input.target.kind === 'existing_session' ? input.target.sessionId : (input.rootSessionId ?? null), optionalJson(input.pristineEvidence), optionalJson(input.deliveryBaseline), at, at);
+        }
+        catch (error) {
+            if (isConstraintError(error)) {
+                throw new WorkflowTransitionError('the root already belongs to an active Workflow');
+            }
+            throw error;
+        }
+        insertJob(context, {
+            id: `${runId}:explore:0`,
+            runId,
+            logicalKey: 'explore:0',
+            role: 'exploration',
+            cycle: 0,
+            revision: 0,
+            resolvedRole: input.roles.exploration,
+            prompt: input.bootstrapPrompt ?? input.objective,
+            state: 'dormant',
+            cancellationGeneration: 0,
+            at
+        });
+        for (const effect of initialEffects) {
+            insertEffect(context, {
+                ...effect,
+                id: effect.id ?? `${runId}:${effect.actionId}`,
+                runId,
+                at
+            });
+        }
+        appendEvent(context, runId, 'workflow_started', 'workflow_started', {
+            target: input.target,
+            bootstrapJob: 'explore:0',
+            initialActionIds: initialEffects.map(effect => effect.actionId)
+        });
+        return { runId };
+    }, { runId: input.id, actionId: initialEffects[0]?.actionId });
+    const runId = answer.result.runId ?? createdRunId;
+    if (!runId)
+        throw new OrchestrationError('idempotent Workflow result did not contain a run ID');
+    const run = getWorkflowRun(context, runId);
+    if (!run)
+        throw new OrchestrationError(`Workflow ${runId} disappeared after creation`);
+    return { replayed: answer.replayed, run };
+}
+export function transitionWorkflowRun(context, input) {
+    return context.immediate(() => {
+        const current = requireRun(context, input.runId);
+        if (isTerminalWorkflowPhase(current.phase)) {
+            throw new WorkflowTransitionError(`terminal Workflow ${current.id} cannot transition from ${current.phase}`);
+        }
+        checkRunGuard(current, input.expectedPhase, input.expectedCancellationGeneration);
+        const phase = input.phase ?? current.phase;
+        const terminalAt = isTerminalWorkflowPhase(phase) ? (current.terminalAt ?? context.now()) : undefined;
+        const blocked = input.blocked === undefined ? current.blocked : (input.blocked ?? undefined);
+        const at = context.now();
+        try {
+            context.db
+                .prepare(`UPDATE workflow_runs SET
+						phase = ?, cycle = ?, revision = ?, workspace_id = ?, root_session_id = ?,
+						pristine_evidence_json = ?, delivery_baseline_json = ?, planning_interpretation = ?,
+						blocked_action_id = ?, blocked_error_code = ?, blocked_message = ?, resume_phase = ?,
+						retry_class = ?, blocked_candidates_json = ?, blocked_at = ?,
+						implementation_batons_delivered = ?, updated_at = ?, terminal_at = ?
+					 WHERE id = ? AND cancellation_generation = ?`)
+                .run(phase, input.cycle ?? current.cycle, input.revision ?? current.revision, input.workspaceId === undefined ? (current.workspaceId ?? null) : input.workspaceId, input.rootSessionId === undefined ? (current.rootSessionId ?? null) : input.rootSessionId, input.pristineEvidence === undefined
+                ? optionalJson(current.pristineEvidence)
+                : optionalJson(input.pristineEvidence), input.deliveryBaseline === undefined
+                ? optionalJson(current.deliveryBaseline)
+                : optionalJson(input.deliveryBaseline), input.planningInterpretation === undefined
+                ? (current.planningInterpretation ?? null)
+                : input.planningInterpretation, blocked?.actionId ?? null, blocked?.errorCode ?? null, blocked?.message ?? null, blocked?.resumePhase ?? null, blocked?.retryClass ?? null, optionalJson(blocked?.candidates), blocked ? (blocked.blockedAt ?? at) : null, input.implementationBatonsDelivered ?? current.implementationBatonsDelivered, at, terminalAt ?? null, input.runId, input.expectedCancellationGeneration);
+        }
+        catch (error) {
+            if (isConstraintError(error)) {
+                throw new WorkflowTransitionError('the requested root is already bound to another active Workflow');
+            }
+            throw error;
+        }
+        appendEvent(context, input.runId, input.eventKey, input.eventType, input.eventData);
+        return requireRun(context, input.runId);
+    });
+}
+export function cancelWorkflowRun(context, runId, eventKey, eventData) {
+    return context.immediate(() => {
+        const run = requireRun(context, runId);
+        if (run.phase === 'cancelled')
+            return run;
+        if (run.phase === 'completed')
+            throw new WorkflowTransitionError('a completed Workflow cannot be cancelled');
+        const at = context.now();
+        const generation = run.cancellationGeneration + 1;
+        context.db
+            .prepare(`UPDATE workflow_runs SET phase = 'cancelled', cancellation_generation = ?, updated_at = ?, terminal_at = ?,
+					blocked_action_id = NULL, blocked_error_code = NULL, blocked_message = NULL, resume_phase = NULL,
+					retry_class = NULL, blocked_candidates_json = NULL, blocked_at = NULL
+				 WHERE id = ? AND cancellation_generation = ?`)
+            .run(generation, at, at, runId, run.cancellationGeneration);
+        context.db
+            .prepare(`UPDATE workflow_jobs SET state = 'cancelled', cancellation_generation = ?, updated_at = ?, terminal_at = ?
+				 WHERE run_id = ? AND state NOT IN ('returned', 'failed', 'cancelled')`)
+            .run(generation, at, at, runId);
+        context.db
+            .prepare(`UPDATE workflow_job_attempts SET state = 'cancelled', updated_at = ?, terminal_at = ?
+				 WHERE job_id IN (SELECT id FROM workflow_jobs WHERE run_id = ?)
+					AND state NOT IN ('returned', 'failed', 'cancelled')`)
+            .run(at, at, runId);
+        context.db
+            .prepare(`UPDATE workflow_effects SET state = 'cancelled', updated_at = ?, terminal_at = ?
+				 WHERE run_id = ? AND state IN ('prepared', 'failed')`)
+            .run(at, at, runId);
+        context.db
+            .prepare(`UPDATE workflow_effect_attempts SET state = 'cancelled', updated_at = ?, terminal_at = ?
+				 WHERE effect_id IN (SELECT id FROM workflow_effects WHERE run_id = ?) AND state = 'prepared'`)
+            .run(at, at, runId);
+        appendEvent(context, runId, eventKey, 'workflow_cancelled', eventData);
+        return requireRun(context, runId);
+    });
+}

package/dist-node/src/{orchestration-schema.js → orchestration/persistence/schema.js}

@@ -2,7 +2,7 @@ import { getTableName, sql } from 'drizzle-orm';
 import { check, customType, index, integer, primaryKey, sqliteTable, text, unique, uniqueIndex } from 'drizzle-orm/sqlite-core';
 import { createSelectSchema, jsonSchema } from 'drizzle-orm/zod';
 import { z } from 'zod';
-export { ORCHESTRATION_BOOTSTRAP_SQL } from "./orchestration-schema.generated.js";
+export { ORCHESTRATION_BOOTSTRAP_SQL } from "./schema.generated.js";
 export const ORCHESTRATION_SCHEMA_VERSION = 1;
 export const WORKFLOW_PHASES = [
     'creating_workspace',

package/dist-node/src/orchestration/persistence/types.js

@@ -0,0 +1 @@
+export const ORCHESTRATION_PROTOCOL_VERSION = 1;

package/dist-node/src/orchestration/persistence/ui-lease.js

@@ -0,0 +1,197 @@
+import { randomUUID } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { OrchestrationError, UiLeaseUnavailableError } from "./errors.js";
+import { activateUiQuarantine, getUiQuarantine } from "./quarantine.js";
+import { assertRelayRegistered } from "./relays.js";
+import { uiMutex, uiMutexSelectSchema } from "./schema.js";
+import { externalFromColumns, nonEmpty, ownerFromColumns, probeAlive, sameLeaseSnapshot, validateProcessIdentity, validateRelayIdentity } from "./values.js";
+export function acquireUiLease(context, input) {
+    validateRelayIdentity(input.owner);
+    const probe = input.processProbe ?? context.processProbe;
+    const observed = readUiLeaseOwner(context);
+    const ownerAlive = observed ? probeAlive(observed, probe) : false;
+    const externalAlive = observed?.externalProcess ? probeAlive(observed.externalProcess, probe) : false;
+    return context.immediate(() => {
+        assertRelayRegistered(context, input.owner);
+        const quarantine = getUiQuarantine(context);
+        if (quarantine.active && input.priority === 'background')
+            return { status: 'quarantined', quarantine };
+        const current = readUiLeaseOwner(context);
+        if (observed && (!current || !sameLeaseSnapshot(observed, current))) {
+            return current ? { status: 'busy', owner: current, reason: 'changed' } : assignUiLease(context, input);
+        }
+        if (!observed && current)
+            return { status: 'busy', owner: current, reason: 'changed' };
+        if (current) {
+            if (ownerAlive)
+                return { status: 'busy', owner: current, reason: 'owner_alive' };
+            if (current.externalProcess && externalAlive) {
+                return { status: 'busy', owner: current, reason: 'external_process_alive' };
+            }
+            if (current.mayExecute) {
+                clearUiMutex(context, current);
+                const hold = activateUiQuarantine(context, {
+                    actionId: current.actionId,
+                    effectId: current.effectId,
+                    reason: 'a dead UI lease owner may have emitted an external action',
+                    owner: current,
+                    externalProcess: current.externalProcess
+                });
+                if (input.priority === 'background')
+                    return { status: 'quarantined', quarantine: hold };
+                return assignUiLease(context, input, current);
+            }
+            clearUiMutex(context, current);
+            return assignUiLease(context, input, current);
+        }
+        return assignUiLease(context, input);
+    });
+}
+export function assignUiLease(context, input, reclaimed) {
+    const nonce = input.nonce ?? randomUUID();
+    const at = context.now();
+    const result = context.db
+        .prepare(`UPDATE ui_mutex SET owner_instance_id = ?, owner_pid = ?, owner_process_started_at = ?,
+				owner_protocol_version = ?, nonce = ?, action_id = ?, effect_id = ?, external_pid = NULL,
+				external_process_started_at = NULL, external_process_group = NULL, may_execute = 0,
+				deadline_at = ?, acquired_at = ?, updated_at = ?
+			 WHERE id = 1 AND owner_instance_id IS NULL`)
+        .run(input.owner.instanceId, input.owner.pid, input.owner.processStartedAt, input.owner.protocolVersion, nonce, nonEmpty(input.actionId, 'UI action ID'), input.effectId ?? null, input.deadlineAt, at, at);
+    if (Number(result.changes) !== 1) {
+        const owner = readUiLeaseOwner(context);
+        if (!owner)
+            throw new OrchestrationError('UI mutex changed while being acquired');
+        return { status: 'busy', owner, reason: 'changed' };
+    }
+    return {
+        status: 'acquired',
+        lease: {
+            instanceId: input.owner.instanceId,
+            pid: input.owner.pid,
+            processStartedAt: input.owner.processStartedAt,
+            nonce,
+            actionId: input.actionId,
+            ...(input.effectId ? { effectId: input.effectId } : {})
+        },
+        ...(reclaimed ? { reclaimed } : {})
+    };
+}
+export function markUiLeaseMayExecute(context, lease, externalProcess, deadlineAt) {
+    if (externalProcess)
+        validateProcessIdentity(externalProcess, 'external UI process');
+    return context.immediate(() => {
+        const result = context.db
+            .prepare(`UPDATE ui_mutex SET may_execute = 1, external_pid = COALESCE(?, external_pid),
+					external_process_started_at = COALESCE(?, external_process_started_at),
+					external_process_group = CASE WHEN ? IS NULL THEN external_process_group ELSE ? END,
+					deadline_at = COALESCE(?, deadline_at), updated_at = ?
+				 WHERE id = 1 AND owner_instance_id = ? AND owner_pid = ? AND owner_process_started_at = ?
+					AND nonce = ? AND action_id = ?`)
+            .run(externalProcess?.pid ?? null, externalProcess?.processStartedAt ?? null, externalProcess?.pid ?? null, externalProcess?.processGroup ?? null, deadlineAt ?? null, context.now(), lease.instanceId, lease.pid, lease.processStartedAt, lease.nonce, lease.actionId);
+        return Number(result.changes) === 1;
+    });
+}
+export function renewUiLease(context, lease, deadlineAt) {
+    return context.immediate(() => {
+        const result = context.db
+            .prepare(`UPDATE ui_mutex SET deadline_at = ?, updated_at = ?
+				 WHERE id = 1 AND owner_instance_id = ? AND owner_pid = ? AND owner_process_started_at = ?
+					AND nonce = ? AND action_id = ?`)
+            .run(deadlineAt, context.now(), lease.instanceId, lease.pid, lease.processStartedAt, lease.nonce, lease.actionId);
+        return Number(result.changes) === 1;
+    });
+}
+export function releaseUiLease(context, lease) {
+    const observed = readUiLeaseOwner(context);
+    if (observed &&
+        observed.instanceId === lease.instanceId &&
+        observed.pid === lease.pid &&
+        observed.processStartedAt === lease.processStartedAt &&
+        observed.nonce === lease.nonce &&
+        observed.actionId === lease.actionId &&
+        observed.externalProcess &&
+        probeAlive(observed.externalProcess, context.processProbe)) {
+        // A returned/failed caller is not proof that a detached helper (or one of
+        // its process-group children) is gone. Retain the durable owner so the
+        // watchdog can terminate and prove the exact group dead before reclaim.
+        return false;
+    }
+    return context.immediate(() => {
+        const result = context.db
+            .prepare(`UPDATE ui_mutex SET owner_instance_id = NULL, owner_pid = NULL, owner_process_started_at = NULL,
+					owner_protocol_version = NULL, nonce = NULL, action_id = NULL, effect_id = NULL,
+					external_pid = NULL, external_process_started_at = NULL, external_process_group = NULL,
+					may_execute = 0, deadline_at = NULL, acquired_at = NULL, updated_at = ?
+				 WHERE id = 1 AND owner_instance_id = ? AND owner_pid = ? AND owner_process_started_at = ?
+					AND nonce = ? AND action_id = ?`)
+            .run(context.now(), lease.instanceId, lease.pid, lease.processStartedAt, lease.nonce, lease.actionId);
+        return Number(result.changes) === 1;
+    });
+}
+export function getUiLeaseOwner(context) {
+    return readUiLeaseOwner(context);
+}
+/** Adapter installed with `configureSharedUiLeaseProvider` in `src/writes/ui-lock.ts`. */
+export function createSharedUiLeaseProvider(context, owner, options = {}) {
+    const leaseMs = Math.max(1_000, options.leaseMs ?? 60_000);
+    return {
+        acquire: async (request) => {
+            const result = acquireUiLease(context, {
+                owner,
+                actionId: request.actionId ?? `ui:${owner.instanceId}:${randomUUID()}`,
+                deadlineAt: context.now() + leaseMs,
+                priority: request.priority
+            });
+            if (result.status !== 'acquired')
+                throw new UiLeaseUnavailableError(result);
+            return {
+                markMayExecute: externalProcess => {
+                    if (!markUiLeaseMayExecute(context, result.lease, externalProcess)) {
+                        throw new OrchestrationError('lost the shared UI lease before dispatch');
+                    }
+                },
+                release: () => {
+                    if (!releaseUiLease(context, result.lease)) {
+                        throw new OrchestrationError('shared UI lease release did not match its durable owner or its external process is still live');
+                    }
+                }
+            };
+        }
+    };
+}
+export function readUiLeaseOwner(context) {
+    const candidate = context.orm.select().from(uiMutex).where(eq(uiMutex.id, 1)).get();
+    if (!candidate)
+        throw new OrchestrationError('orchestration UI mutex singleton is missing');
+    const row = uiMutexSelectSchema.parse(candidate);
+    const owner = ownerFromColumns(row);
+    if (!owner ||
+        row.nonce === null ||
+        row.actionId === null ||
+        row.deadlineAt === null ||
+        row.acquiredAt === null ||
+        row.updatedAt === null) {
+        return undefined;
+    }
+    const externalProcess = externalFromColumns(row);
+    return {
+        ...owner,
+        nonce: row.nonce,
+        actionId: row.actionId,
+        ...(row.effectId === null ? {} : { effectId: row.effectId }),
+        ...(externalProcess ? { externalProcess } : {}),
+        mayExecute: row.mayExecute,
+        deadlineAt: row.deadlineAt,
+        acquiredAt: row.acquiredAt,
+        updatedAt: row.updatedAt
+    };
+}
+export function clearUiMutex(context, expected) {
+    context.db
+        .prepare(`UPDATE ui_mutex SET owner_instance_id = NULL, owner_pid = NULL, owner_process_started_at = NULL,
+				owner_protocol_version = NULL, nonce = NULL, action_id = NULL, effect_id = NULL,
+				external_pid = NULL, external_process_started_at = NULL, external_process_group = NULL,
+				may_execute = 0, deadline_at = NULL, acquired_at = NULL, updated_at = ?
+			 WHERE id = 1 AND owner_instance_id = ? AND owner_pid = ? AND owner_process_started_at = ? AND nonce = ?`)
+        .run(context.now(), expected.instanceId, expected.pid, expected.processStartedAt, expected.nonce);
+}

package/dist-node/src/orchestration/persistence/values.js

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { scrubWorkflowSecrets, withoutWindowEvidence } from "../../shared.js";
+import { OrchestrationError } from "./errors.js";
+export const ACTIVE_PHASES = [
+    'creating_workspace',
+    'binding_root',
+    'pending_root',
+    'exploring',
+    'planning',
+    'implementing',
+    'reviewing',
+    'blocked'
+];
+export const RUNNABLE_PHASES = ACTIVE_PHASES.filter(phase => phase !== 'blocked');
+export const ALL_JOB_STATES = [
+    'dormant',
+    'queued',
+    'owned',
+    'opening',
+    'configuring',
+    'sending',
+    'running',
+    'returning',
+    'returned',
+    'failed',
+    'cancelled'
+];
+export const TERMINAL_EFFECT_STATES = ['committed', 'failed', 'ambiguous', 'cancelled'];
+export const nonEmpty = (value, name) => {
+    if (!value.trim())
+        throw new OrchestrationError(`${name} must not be empty`);
+    return value;
+};
+export const validateProcessIdentity = (identity, name) => {
+    if (!Number.isSafeInteger(identity.pid) || identity.pid <= 0)
+        throw new OrchestrationError(`${name} PID is invalid`);
+    nonEmpty(identity.processStartedAt, `${name} process-start identity`);
+};
+export const validateRelayIdentity = (identity) => {
+    nonEmpty(identity.instanceId, 'relay instance ID');
+    validateProcessIdentity(identity, 'relay');
+    if (!Number.isSafeInteger(identity.protocolVersion) || identity.protocolVersion < 0) {
+        throw new OrchestrationError('relay orchestration protocol is invalid');
+    }
+};
+export const json = (value) => {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new OrchestrationError('value is not JSON serializable');
+    return encoded;
+};
+export const optionalJson = (value) => (value === undefined ? null : json(value));
+export const jsonProperty = (key, stored) => stored === null ? {} : { [key]: stored.value };
+export const isPromiseLike = (value) => value !== null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof value.then === 'function';
+export const isConstraintError = (error) => error instanceof Error && /constraint failed|unique constraint/i.test(error.message);
+export const ownerFromColumns = (row) => {
+    if (row.ownerInstanceId === null ||
+        row.ownerPid === null ||
+        row.ownerProcessStartedAt === null ||
+        row.ownerProtocolVersion === null) {
+        return undefined;
+    }
+    return {
+        instanceId: row.ownerInstanceId,
+        pid: row.ownerPid,
+        processStartedAt: row.ownerProcessStartedAt,
+        protocolVersion: row.ownerProtocolVersion
+    };
+};
+export const externalFromColumns = (row) => {
+    if (row.externalPid === null || row.externalProcessStartedAt === null)
+        return undefined;
+    return {
+        pid: row.externalPid,
+        processStartedAt: row.externalProcessStartedAt,
+        ...(row.externalProcessGroup === null ? {} : { processGroup: row.externalProcessGroup })
+    };
+};
+const sameProcess = (left, right) => left.pid === right.pid && left.processStartedAt === right.processStartedAt;
+export const sameOwner = (left, right) => left.instanceId === right.instanceId && left.protocolVersion === right.protocolVersion && sameProcess(left, right);
+export const processAuditKey = (identity) => `${identity.pid}:${createHash('sha256')
+    .update(`${identity.processStartedAt}\0${identity.processGroup ?? ''}`)
+    .digest('hex')
+    .slice(0, 16)}`;
+export const ownerAuditKey = (owner) => createHash('sha256')
+    .update(`${owner.instanceId}\0${owner.pid}\0${owner.processStartedAt}\0${owner.protocolVersion}`)
+    .digest('hex')
+    .slice(0, 16);
+export const defaultScrub = (text) => withoutWindowEvidence(scrubWorkflowSecrets(text))
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+export function probeAlive(identity, probe) {
+    try {
+        return probe(identity);
+    }
+    catch {
+        // Failure to prove death must never authorize overlap.
+        return true;
+    }
+}
+export const asObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+export const sameOptionalProcess = (left, right) => left === undefined
+    ? right === undefined
+    : right !== undefined && sameProcess(left, right) && left.processGroup === right.processGroup;
+export const sameLeaseSnapshot = (left, right) => sameOwner(left, right) &&
+    left.nonce === right.nonce &&
+    left.actionId === right.actionId &&
+    left.effectId === right.effectId &&
+    left.mayExecute === right.mayExecute &&
+    left.deadlineAt === right.deadlineAt &&
+    sameOptionalProcess(left.externalProcess, right.externalProcess);