@voybio/ace-swarm 2.4.8 → 2.4.10

package/dist/host-plan-revision.js

@@ -0,0 +1,101 @@
+import { isDeepStrictEqual } from "node:util";
+import { amendTaskPlan } from "./orchestrator-supervisor.js";
+/** Prepare a requirement change; the caller owns persistence and execution. */
+export function reviseHostRequirements(plan, updates) {
+    const steps = new Map();
+    const children = new Map();
+    const remaining = new Map();
+    for (const step of plan.steps) {
+        if (!step.step_id || steps.has(step.step_id)) {
+            throw new Error(`Invalid or duplicate step: ${step.step_id}`);
+        }
+        steps.set(step.step_id, step);
+        children.set(step.step_id, []);
+        remaining.set(step.step_id, step.depends_on?.length ?? 0);
+    }
+    for (const step of plan.steps) {
+        for (const dependency of step.depends_on ?? []) {
+            if (!steps.has(dependency))
+                throw new Error(`Missing dependency: ${dependency}`);
+            children.get(dependency).push(step.step_id);
+        }
+    }
+    const ready = [...remaining].filter(([, count]) => count === 0).map(([id]) => id);
+    for (let index = 0; index < ready.length; index++) {
+        for (const child of children.get(ready[index])) {
+            const count = remaining.get(child) - 1;
+            remaining.set(child, count);
+            if (count === 0)
+                ready.push(child);
+        }
+    }
+    if (ready.length !== steps.size)
+        throw new Error("Invalid task graph: dependency cycle");
+    const named = new Map();
+    for (const update of updates) {
+        if (!steps.has(update.step_id))
+            throw new Error(`Missing step: ${update.step_id}`);
+        if (typeof update.reason !== "string" || !update.reason.trim()) {
+            throw new Error(`Missing change reason: ${update.step_id}`);
+        }
+        // Compare only the public requirement fields, independent of object key order.
+        const normalized = {
+            step_id: update.step_id,
+            reason: update.reason,
+            task: update.task,
+            expected_artifacts: update.expected_artifacts,
+            required_evidence_refs: update.required_evidence_refs,
+        };
+        const previous = named.get(update.step_id);
+        if (previous && !isDeepStrictEqual(previous, normalized)) {
+            throw new Error(`Conflicting updates: ${update.step_id}`);
+        }
+        named.set(update.step_id, normalized);
+    }
+    const reasons = new Map();
+    for (const update of named.values()) {
+        const pending = [update.step_id];
+        const visited = new Set();
+        for (let index = 0; index < pending.length; index++) {
+            const id = pending[index];
+            if (visited.has(id))
+                continue;
+            visited.add(id);
+            if (!reasons.has(id))
+                reasons.set(id, new Set());
+            reasons.get(id).add(update.reason);
+            pending.push(...children.get(id));
+        }
+    }
+    // Detach all nested data too, so later edits to the prepared plan cannot mutate
+    // its source or the caller's update objects.
+    const copy = structuredClone(plan);
+    const reopened = copy.steps.filter(step => reasons.has(step.step_id)).map(step => step.step_id);
+    if (!reopened.length)
+        return { plan: copy, reopened };
+    const updateSteps = copy.steps.filter(step => reasons.has(step.step_id)).map(step => {
+        const update = named.get(step.step_id);
+        const { attempt_history: history = [], ...receipt } = step;
+        const patch = {
+            status: "planned",
+            blocked_reason: `Requirement changed: ${[...reasons.get(step.step_id)].join("; ")}`,
+            attempt_history: [...history, structuredClone(receipt)],
+            assignee: undefined,
+            started_at: undefined,
+            job_id: undefined,
+            handoff_id: undefined,
+            waiting_on: undefined,
+            result_digest: undefined,
+            result_response: undefined,
+        };
+        if (update?.task !== undefined)
+            patch.task = update.task;
+        if (update?.expected_artifacts !== undefined)
+            patch.expected_artifacts = structuredClone(update.expected_artifacts);
+        if (update?.required_evidence_refs !== undefined)
+            patch.required_evidence_refs = [...update.required_evidence_refs];
+        return { step_id: step.step_id, patch };
+    });
+    return { plan: amendTaskPlan(copy, { update_steps: updateSteps }), reopened };
+}
+//# sourceMappingURL=host-plan-revision.js.map

package/dist/host-verification-job.d.ts

@@ -0,0 +1,12 @@
+import { type GoalRecord } from './store/repositories/goal-repository.js';
+import { type GoalEngineDeps } from './goal-engine.js';
+type Snapshot = {
+    goal: GoalRecord;
+    planDigest: string;
+};
+/** Unknown identity is retained; it is never permission to rerun a check. */
+export declare function hostVerificationActive(root: string, goalId: string): boolean;
+export declare function scheduleHostVerification(goalId: string, snapshot: Snapshot, deps?: GoalEngineDeps): Promise<void>;
+export declare function executeHostVerificationJob(root: string, jobId: string): Promise<void>;
+export {};
+//# sourceMappingURL=host-verification-job.d.ts.map

package/dist/host-verification-job.js

@@ -0,0 +1,183 @@
+/** Durable host verification over the existing scheduler and goal coordinator. */
+import { spawn } from 'node:child_process';
+import { openSync, closeSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { GoalRepository } from './store/repositories/goal-repository.js';
+import { resolveGoalDeps } from './goal-engine.js';
+import { withStoreWriteCoordinator } from './store/write-coordinator.js';
+import { enqueueJob, readJobQueue, claimJobExecution, recordJobExecutionChild } from './job-scheduler.js';
+import { withWorkspaceRoot } from './helpers.js';
+import { readProcessIdentity, probeProcess } from './process-identity.js';
+import { runProgressCommand } from './progress-command.js';
+const injected = new Map();
+const key = (root, goalId) => `${root}\0${goalId}`;
+/** Unknown identity is retained; it is never permission to rerun a check. */
+export function hostVerificationActive(root, goalId) {
+    if (injected.has(key(root, goalId)))
+        return true;
+    const run = new GoalRepository(root).getGoal(goalId)?.verification_run;
+    if (!run || ['done', 'failed', 'interrupted'].includes(run.status))
+        return false;
+    if (run.worker && probeProcess(run.worker) !== 'dead')
+        return true;
+    if (run.command?.process && probeProcess(run.command.process) !== 'dead')
+        return true;
+    // An OS identity unavailable at launch is ambiguous, not a dead execution.
+    return run.status === 'uncertain';
+}
+export async function scheduleHostVerification(goalId, snapshot, deps = {}) {
+    const d = resolveGoalDeps(deps), token = key(d.workspaceRoot, goalId);
+    // Injected verifiers cannot be serialized to a process. They still run after
+    // the receipt returns; production always uses the durable scheduler worker.
+    if (deps.runVerification || deps.artifactExists || deps.now || deps.observations) {
+        if (injected.has(token))
+            return;
+        const work = new Promise(resolve => setImmediate(resolve)).then(async () => {
+            const { finishHostVerification } = await import('./host-goal-engine.js');
+            await finishHostVerification(goalId, snapshot, deps);
+        }).finally(() => { if (injected.get(token) === work)
+            injected.delete(token); });
+        injected.set(token, work);
+        void work.catch(async (error) => {
+            await withStoreWriteCoordinator(d.repo.planPath(goalId), async () => {
+                const goal = d.repo.getGoal(goalId);
+                if (goal && goal.verification_attempt === snapshot.goal.verification_attempt) {
+                    goal.status = 'blocked';
+                    goal.reason_code = 'verification_interrupted';
+                    goal.result_summary = String(error);
+                    d.repo.saveGoal(goal);
+                }
+            });
+        });
+        return;
+    }
+    await withStoreWriteCoordinator(d.repo.planPath(goalId), async () => {
+        const goal = d.repo.getGoal(goalId);
+        if (!goal || goal.status !== 'verifying' || goal.verification_attempt !== snapshot.goal.verification_attempt || goal.stop_requested)
+            return;
+        if (hostVerificationActive(d.workspaceRoot, goalId))
+            return;
+        if (goal.verification_run) {
+            const previous = withWorkspaceRoot(d.workspaceRoot, () => readJobQueue()).jobs.find(j => j.job_id === goal.verification_run.job_id);
+            if (previous?.status === 'running' && previous.execution) {
+                const recovered = await claimJobExecution({ job_id: previous.job_id, owner: 'capability-ops' }, d.workspaceRoot);
+                if (recovered.reason_code !== 'execution_dead') {
+                    goal.verification_run.status = 'uncertain';
+                    goal.verification_run.error = 'Previous scheduler execution has not been confirmed dead. Retain its resource locks.';
+                    d.repo.saveGoal(goal);
+                    return;
+                }
+            }
+        }
+        const jobId = `goal-verify-${randomUUID()}`;
+        goal.verification_run = { job_id: jobId, attempt: goal.verification_attempt, enqueued_at: new Date(d.now()).toISOString(), status: 'queued' };
+        // Reserve the generation before enqueue/spawn. Recovery uses this retained
+        // obligation if the launching server dies between these operations.
+        d.repo.saveGoal(goal);
+        const queued = await withWorkspaceRoot(d.workspaceRoot, () => enqueueJob({ job_id: jobId, kind: 'goal.verify',
+            payload: { goal_id: goalId, attempt: goal.verification_attempt, plan_digest: snapshot.planDigest },
+            resource_requirements: [`goal:${goalId}:verification`], max_attempts: 1 }));
+        if (!queued.ok) {
+            goal.verification_run.status = 'interrupted';
+            goal.verification_run.error = queued.nack?.reason;
+            d.repo.saveGoal(goal);
+            return;
+        }
+        const dir = join(d.workspaceRoot, '.ace-runtime', 'verification', jobId);
+        mkdirSync(dir, { recursive: true });
+        const log = openSync(join(dir, 'worker.log'), 'a');
+        try {
+            const child = spawn(process.execPath, [fileURLToPath(new URL('./verification-worker.js', import.meta.url)), d.workspaceRoot, jobId], {
+                cwd: d.workspaceRoot, env: { ...process.env, ACE_WORKSPACE_ROOT: d.workspaceRoot }, detached: true, stdio: ['ignore', log, log],
+            });
+            await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+            const identity = child.pid && readProcessIdentity(child.pid);
+            if (identity)
+                goal.verification_run.worker = identity;
+            else {
+                goal.verification_run.status = 'uncertain';
+                goal.verification_run.error = 'Worker launched but its OS identity could not be verified. Inspect it before resuming.';
+            }
+            child.unref();
+            d.repo.saveGoal(goal);
+        }
+        catch (error) {
+            goal.verification_run.status = 'interrupted';
+            goal.verification_run.error = String(error);
+            d.repo.saveGoal(goal);
+        }
+        finally {
+            closeSync(log);
+        }
+    }, { operation_label: 'host_verification_enqueue' });
+}
+export async function executeHostVerificationJob(root, jobId) {
+    const d = resolveGoalDeps({ workspaceRoot: root });
+    const job = withWorkspaceRoot(root, () => readJobQueue()).jobs.find(j => j.job_id === jobId);
+    if (!job)
+        throw new Error(`Verification job not found: ${jobId}`);
+    const goalId = String(job.payload.goal_id), attempt = Number(job.payload.attempt);
+    const initial = await withStoreWriteCoordinator(d.repo.planPath(goalId), async () => {
+        const goal = d.repo.getGoal(goalId);
+        if (!goal || goal.verification_attempt !== attempt || goal.verification_run?.job_id !== jobId || goal.stop_requested)
+            return undefined;
+        const identity = readProcessIdentity(process.pid);
+        if (!identity) {
+            goal.verification_run.status = 'uncertain';
+            goal.verification_run.error = 'Worker OS identity unavailable; no checks were started.';
+            d.repo.saveGoal(goal);
+            return undefined;
+        }
+        goal.verification_run.worker = identity;
+        goal.verification_run.status = 'running';
+        d.repo.saveGoal(goal);
+        return goal;
+    }, { operation_label: 'host_verification_worker_start' });
+    if (!initial)
+        return;
+    const snapshot = { goal: initial, planDigest: String(job.payload.plan_digest) };
+    let index = 0;
+    const { finishHostVerification } = await import('./host-goal-engine.js');
+    await finishHostVerification(goalId, snapshot, { workspaceRoot: root, runVerification: async (command, commandRoot, policy) => {
+            const controller = new AbortController();
+            const logPath = join(root, '.ace-runtime', 'verification', jobId, `command-${++index}.log`);
+            let identity;
+            let latest, writing;
+            const persist = () => {
+                if (writing)
+                    return writing;
+                writing = (async () => {
+                    while (latest) {
+                        const progress = latest;
+                        latest = undefined;
+                        await withStoreWriteCoordinator(d.repo.planPath(goalId), async () => {
+                            const goal = d.repo.getGoal(goalId);
+                            if (!goal || goal.verification_attempt !== attempt || goal.verification_run?.job_id !== jobId) {
+                                controller.abort();
+                                return;
+                            }
+                            if (goal.stop_requested || goal.status === 'stopped')
+                                controller.abort();
+                            goal.verification_run.status = goal.stop_requested ? 'stopped' : 'running';
+                            goal.verification_run.command = { ...progress, index, command, log_path: logPath, ...(identity ? { process: identity } : {}) };
+                            d.repo.saveGoal(goal);
+                        }, { operation_label: 'host_verification_progress' });
+                    }
+                })().finally(() => { writing = undefined; });
+                return writing;
+            };
+            const result = await runProgressCommand(command, commandRoot, { ...policy, log_path: logPath, signal: controller.signal,
+                onSpawn: async (process) => {
+                    identity = process;
+                    const registered = await recordJobExecutionChild({ job_id: jobId, token: job.execution?.token, identity: process }, root);
+                    if (!registered.ok)
+                        controller.abort(new Error('Unable to retain command process identity in the scheduler.'));
+                },
+                onProgress: progress => { latest = progress; return persist(); } });
+            await persist();
+            return { ok: result.ok, output: result.reason_code ? `${result.output}\n[${result.reason_code}]` : result.output };
+        } });
+}
+//# sourceMappingURL=host-verification-job.js.map

package/dist/host-work-context.d.ts

@@ -0,0 +1,12 @@
+export interface HostWorkBinding {
+    agent: string;
+    goal_id?: string;
+    step_id?: string;
+    attempt?: number;
+}
+type Binding = HostWorkBinding;
+export declare function getHostBinding(session?: string): HostWorkBinding | undefined;
+export declare function bindHostWork(binding: Binding, session?: string): void;
+export declare function hostAgent(agent?: string, session?: string): string;
+export {};
+//# sourceMappingURL=host-work-context.d.ts.map

package/dist/host-work-context.js

@@ -0,0 +1,8 @@
+/** Process/session bindings are convenience only; durable ownership lives on TaskStep. */
+import { resolveWorkspaceRoot } from './helpers.js';
+const bindings = new Map();
+function key(session) { return `${resolveWorkspaceRoot()}\0${session ?? 'process'}`; }
+export function getHostBinding(session) { return bindings.get(key(session)); }
+export function bindHostWork(binding, session) { bindings.set(key(session), binding); }
+export function hostAgent(agent, session) { return agent ?? getHostBinding(session)?.agent ?? `host-${session ?? process.pid}`; }
+//# sourceMappingURL=host-work-context.js.map

package/dist/job-scheduler.d.ts

@@ -1,3 +1,4 @@
+import { type ProcessIdentity } from "./process-identity.js";
 export declare const JOB_QUEUE_REL = "agent-state/job-queue.json";
 export declare const JOB_LOCK_TABLE_REL = "agent-state/job-locks.json";
 export declare const SCHEDULER_LEASE_REL = "agent-state/scheduler-lease.json";
@@ -31,6 +32,12 @@ export interface JobRecord {
     evidence_ref?: string;
     error?: string;
     reason_code?: string;
+    /** Durable handler claim: owner strings alone do not identify an execution. */
+    execution?: ProcessIdentity & {
+        token: string;
+    };
+    /** Commands can outlive their worker; retain their process identities too. */
+    execution_children?: ProcessIdentity[];
 }
 export interface JobQueueFile {
     version: 1;
@@ -92,6 +99,8 @@ export interface EnqueueJobResult {
 }
 export interface DispatchJobsInput {
     owner?: string;
+    /** Restrict admission, recovery and watchdog changes to these jobs. */
+    job_ids?: string[];
     lease_ttl_seconds?: number;
     now_iso?: string;
     /**
@@ -103,8 +112,12 @@ export interface DispatchJobsInput {
 }
 export interface DispatchJobsResult {
     ok: boolean;
+    reason_code?: "scheduler_lease_held";
+    error?: string;
     owner: string;
     lease_acquired: boolean;
+    /** Whether execution still retains ownership after this tick. */
+    lease_retained: boolean;
     lease: SchedulerLeaseFile;
     queue_path: string;
     lock_path: string;
@@ -196,12 +209,12 @@ export interface AckJobResult {
     to?: JobStatus;
     error?: string;
 }
-export declare function getJobQueuePath(): string;
-export declare function getJobLockTablePath(): string;
-export declare function getSchedulerLeasePath(): string;
-export declare function readJobQueue(): JobQueueFile;
-export declare function readJobLockTable(): JobLockTableFile;
-export declare function readSchedulerLease(): SchedulerLeaseFile | undefined;
+export declare function getJobQueuePath(workspaceRoot?: string): string;
+export declare function getJobLockTablePath(workspaceRoot?: string): string;
+export declare function getSchedulerLeasePath(workspaceRoot?: string): string;
+export declare function readJobQueue(workspaceRoot?: string): JobQueueFile;
+export declare function readJobLockTable(workspaceRoot?: string): JobLockTableFile;
+export declare function readSchedulerLease(workspaceRoot?: string): SchedulerLeaseFile | undefined;
 /**
  * Default window a running job may go without a worker heartbeat before the
  * watchdog presumes the worker is dead and reaps the job into
@@ -209,11 +222,43 @@ export declare function readSchedulerLease(): SchedulerLeaseFile | undefined;
  * `heartbeatJob` well within this window (see job-worker.ts).
  */
 export declare const DEFAULT_HEARTBEAT_STALE_MS = 120000;
-export declare function enqueueJob(input: EnqueueJobInput): Promise<EnqueueJobResult>;
-export declare function acknowledgeJob(input: AckJobInput): Promise<AckJobResult>;
-export declare function dispatchJobs(input?: DispatchJobsInput): Promise<DispatchJobsResult>;
-export declare function dispatchJobNow(input: DispatchJobNowInput): Promise<DispatchJobNowResult>;
-export declare function completeJob(input: CompleteJobInput): Promise<CompleteJobResult>;
+export declare function enqueueJob(input: EnqueueJobInput, workspaceRoot?: string): Promise<EnqueueJobResult>;
+/** Mirror handoff lifecycle without admitting or executing a job. */
+export declare function syncHandoffLifecycleJob(input: EnqueueJobInput & {
+    job_id: string;
+    now_iso?: string;
+}, workspaceRoot?: string): Promise<EnqueueJobResult & {
+    enqueued: boolean;
+}>;
+export declare function acknowledgeJob(input: AckJobInput, workspaceRoot?: string): Promise<AckJobResult>;
+export declare function dispatchJobs(input?: DispatchJobsInput, workspaceRoot?: string): Promise<DispatchJobsResult>;
+export declare function dispatchJobNow(input: DispatchJobNowInput, workspaceRoot?: string): Promise<DispatchJobNowResult>;
+export interface ClaimJobExecutionInput {
+    job_id: string;
+    owner?: string;
+    now_iso?: string;
+}
+export interface ClaimJobExecutionResult {
+    ok: boolean;
+    reason_code?: string;
+    error?: string;
+    token?: string;
+    job?: JobRecord;
+}
+/** Atomically claim the side-effecting handler, independently of scheduler owner. */
+export declare function claimJobExecution(input: ClaimJobExecutionInput, workspaceRoot?: string): Promise<ClaimJobExecutionResult>;
+export interface RecordJobExecutionChildInput {
+    job_id: string;
+    token?: string;
+    identity: ProcessIdentity;
+}
+/** Register a command before waiting on it; only its claimed attempt may do so. */
+export declare function recordJobExecutionChild(input: RecordJobExecutionChildInput, workspaceRoot?: string): Promise<{
+    ok: boolean;
+    reason_code?: string;
+    error?: string;
+}>;
+export declare function completeJob(input: CompleteJobInput, workspaceRoot?: string): Promise<CompleteJobResult>;
 /**
  * Prove liveness for a running job. A live in-process worker calls this
  * periodically while executing a job body so the heartbeat watchdog does not
@@ -222,12 +267,12 @@ export declare function completeJob(input: CompleteJobInput): Promise<CompleteJo
  * job's heartbeat — the dispatcher deliberately does not, so a missing
  * heartbeat reliably signals a dead worker.
  */
-export declare function heartbeatJob(input: HeartbeatJobInput): Promise<HeartbeatJobResult>;
+export declare function heartbeatJob(input: HeartbeatJobInput, workspaceRoot?: string): Promise<HeartbeatJobResult>;
 /**
  * Standalone heartbeat-watchdog tick: reap stale running jobs without planning
  * or starting anything. Takes its own scheduler lock. Useful for a dedicated
  * watchdog cadence separate from dispatch. Does not require lease ownership —
  * reaping a dead worker's job must not depend on holding the lease.
  */
-export declare function reapStaleRunningJobsTick(input?: ReapStaleRunningJobsInput): Promise<ReapStaleRunningJobsResult>;
+export declare function reapStaleRunningJobsTick(input?: ReapStaleRunningJobsInput, workspaceRoot?: string): Promise<ReapStaleRunningJobsResult>;
 //# sourceMappingURL=job-scheduler.d.ts.map