@aiwg/cli 2026.8.0 → 2026.8.2

package/dist/src/serve/agentic-sandbox-fleet-client.js

@@ -0,0 +1,213 @@
+/**
+ * AIWG management-plane adapter for Agentic Sandbox's neutral fleet API.
+ * The adapter owns no runtime state: it dispatches contract records and
+ * converts durable Sandbox observations into FleetMissionConductor events.
+ *
+ * @implements #1991
+ */
+import { routeDispatch } from './dispatch-router.js';
+const terminal = new Set([
+    'retained', 'healthy', 'scheduled', 'succeeded', 'failed', 'cancelled', 'timed-out',
+    'unknown', 'operator-review-required',
+]);
+export class AgenticSandboxFleetClient {
+    baseUrl;
+    token;
+    fetchImpl;
+    executorFetch;
+    pollIntervalMs;
+    maxPolls;
+    defaultPolicy;
+    defaultBudgets;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.token = options.token;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.executorFetch = options.executorFetch ?? globalThis.fetch.bind(globalThis);
+        this.pollIntervalMs = options.pollIntervalMs ?? 250;
+        this.maxPolls = options.maxPolls ?? 120;
+        this.defaultPolicy = options.defaultPolicy ?? { trustTier: 'T2', isolationKind: 'vm' };
+        this.defaultBudgets = options.defaultBudgets ?? { maxAttempts: 1, timeoutSeconds: 3600 };
+    }
+    /** Directly assignable to FleetMissionConductor's `runWorker` option. */
+    runWorker = async (cycle, executor, invocation, lineage) => {
+        const record = this.workloadRecord(cycle, executor, lineage);
+        const admitted = await this.request('/api/v2/fleet/workloads', { method: 'POST', body: JSON.stringify(record) });
+        const events = [this.toEvent(admitted.workload)];
+        if (!admitted.workload.lineage.task_id) {
+            const dispatched = await routeDispatch(executor, {
+                mission_id: lineage.dispatchId,
+                objective: cycle.prompt,
+                long_running: cycle.longRunning ?? cycle.workloadKind !== 'one-shot-command',
+                fleet_workload_kind: cycle.workloadKind,
+                fleet_child_id: lineage.childId,
+                native_primitive: invocation.primitive,
+                ...(executor.a2aInstanceId ? { a2a_instance_id: executor.a2aInstanceId } : {}),
+            }, { fetch: this.executorFetch });
+            if (!dispatched.task?.id) {
+                throw new Error(`Agentic Sandbox dispatch for '${lineage.childId}' returned no durable task identity`);
+            }
+            const bound = await this.bindDispatchedTask(cycle, lineage.childId, admitted.workload.status, dispatched.task.id, this.taskObservedState(cycle, dispatched.task.status.state));
+            events.push(this.toEvent(bound));
+        }
+        for (let attempt = 0; attempt < this.maxPolls && !this.settled(cycle, events.at(-1)); attempt += 1) {
+            if (this.pollIntervalMs > 0) {
+                await new Promise((resolve) => setTimeout(resolve, this.pollIntervalMs));
+            }
+            const next = await this.request(`/api/v2/fleet/workloads/${encodeURIComponent(lineage.childId)}`);
+            const event = this.toEvent(next);
+            if (event.revision > events.at(-1).revision)
+                events.push(event);
+        }
+        const latest = events.at(-1);
+        return {
+            output: latest.artifacts?.find((artifact) => artifact.kind === 'result')?.uri,
+            commandId: latest.commandId,
+            sessionId: latest.sessionId,
+            events,
+        };
+    };
+    async bindDispatchedTask(cycle, childId, current, taskId, observedState) {
+        const status = {
+            observed_state: observedState,
+            revision: current.revision + 1,
+            last_seen: new Date().toISOString(),
+            artifacts: current.artifacts ?? [],
+            ...(cycle.workloadKind === 'daemon' ? { health: observedState === 'healthy' ? 'healthy' : 'unknown' } : {}),
+            ...(observedState === 'blocked' ? { backpressure: { reason: 'approval', retryable: false } } : {}),
+        };
+        return this.request(`/api/v2/fleet/workloads/${encodeURIComponent(childId)}/observations`, {
+            method: 'POST',
+            body: JSON.stringify({
+                expected_revision: current.revision,
+                runtime_identity: { task_id: taskId },
+                status,
+            }),
+        });
+    }
+    taskObservedState(cycle, taskState) {
+        switch (taskState) {
+            case 'submitted': return 'starting';
+            case 'working': return cycle.workloadKind === 'daemon' ? 'healthy' : 'running';
+            case 'input-required': return 'blocked';
+            case 'completed':
+                if (cycle.workloadKind === 'persistent-agent')
+                    return 'retained';
+                if (cycle.workloadKind === 'daemon')
+                    return 'healthy';
+                if (cycle.workloadKind === 'scheduled-collector')
+                    return 'scheduled';
+                return 'succeeded';
+            case 'failed': return 'failed';
+            case 'canceled':
+            case 'cancelled': return 'cancelled';
+            case 'rejected': return 'failed';
+            default: return 'unknown';
+        }
+    }
+    async inventory() {
+        return this.request('/api/v2/fleet/workloads');
+    }
+    async reconcile(beforeRevision, childIds) {
+        return this.request('/api/v2/fleet/reconcile', {
+            method: 'POST',
+            body: JSON.stringify({ before_revision: beforeRevision, child_ids: childIds }),
+        });
+    }
+    workloadRecord(cycle, executor, lineage) {
+        if (cycle.workloadKind === 'scheduled-collector' && !cycle.schedule) {
+            throw new Error(`scheduled collector '${cycle.id}' requires a schedule`);
+        }
+        const policy = cycle.policy ?? this.defaultPolicy;
+        const budgets = cycle.budgets ?? this.defaultBudgets;
+        const spec = {
+            desired_state: 'running',
+            capabilities: (cycle.requiredCapabilities ?? []).map((name) => ({ name, status: 'supported' })),
+            policy: {
+                trust_tier: policy.trustTier,
+                isolation_kind: policy.isolationKind,
+                ...(policy.credentialPolicyRef ? { credential_policy_ref: policy.credentialPolicyRef } : {}),
+                ...(policy.networkPolicyRef ? { network_policy_ref: policy.networkPolicyRef } : {}),
+            },
+            budgets: {
+                max_attempts: budgets.maxAttempts,
+                timeout_seconds: budgets.timeoutSeconds,
+                ...(budgets.maxCostUsd === undefined ? {} : { max_cost_usd: budgets.maxCostUsd }),
+            },
+            ...(cycle.schedule ? { schedule: cycle.schedule } : {}),
+            orchestrator_metadata: { executor_spec_version: executor.specVersion },
+        };
+        return {
+            document_type: 'workload',
+            api_version: 'agentic-orchestration/v1',
+            kind: cycle.workloadKind,
+            lineage: {
+                orchestrator_id: lineage.orchestratorId,
+                mission_id: lineage.missionId,
+                dispatch_id: lineage.dispatchId,
+                idempotency_key: lineage.idempotencyKey,
+                parent_id: lineage.parentId,
+                child_id: lineage.childId,
+                target_id: lineage.targetId,
+                executor_id: lineage.executorId,
+                runtime_id: lineage.runtimeId,
+                session_id: null,
+                task_id: null,
+                command_id: null,
+            },
+            spec,
+            status: {
+                observed_state: 'pending',
+                revision: 0,
+                last_seen: new Date().toISOString(),
+                ...(cycle.workloadKind === 'daemon' ? { health: 'unknown' } : {}),
+                artifacts: [],
+            },
+        };
+    }
+    settled(cycle, event) {
+        if (event.observedState === 'running' && cycle.workloadKind === 'persistent-agent')
+            return true;
+        if (event.observedState === 'running' && cycle.workloadKind === 'daemon' && event.health === 'healthy')
+            return true;
+        if (event.observedState === 'blocked')
+            return event.backpressure?.retryable !== true;
+        return terminal.has(event.observedState);
+    }
+    toEvent(record) {
+        const { status, lineage } = record;
+        return {
+            revision: status.revision,
+            observedState: status.observed_state,
+            lastSeen: status.last_seen,
+            sessionId: lineage.session_id ?? undefined,
+            taskId: lineage.task_id ?? undefined,
+            commandId: lineage.command_id ?? undefined,
+            health: status.health,
+            backpressure: status.backpressure ? {
+                reason: status.backpressure.reason,
+                retryable: status.backpressure.retryable,
+                retryAfter: status.backpressure.retry_after,
+            } : undefined,
+            artifacts: status.artifacts,
+            errorCode: status.error_code,
+        };
+    }
+    async request(path, init = {}) {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                accept: 'application/json',
+                authorization: `Bearer ${this.token}`,
+                ...(init.body ? { 'content-type': 'application/json' } : {}),
+                ...init.headers,
+            },
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Agentic Sandbox fleet API ${response.status}: ${body.slice(0, 512)}`);
+        }
+        return response.json();
+    }
+}
+//# sourceMappingURL=agentic-sandbox-fleet-client.js.map

package/dist/src/serve/fleet-mission-conductor.js

@@ -0,0 +1,293 @@
+/**
+ * Fleet Mission Conductor — management-plane orchestration over N executor
+ * targets using the neutral fleet-workload/v1 vocabulary.
+ *
+ * AIWG owns parent fan-out, aggregation, audit, and completion. Execution
+ * substrates (Agentic Sandbox first, other adapters later) own target-local
+ * lifecycle and report revisioned observations through the RunFleetWorker seam.
+ *
+ * @implements #1991
+ */
+import { routeMission } from './agent-router.js';
+import { StackAdapterRegistry } from './stack-adapters.js';
+const terminalFailures = new Set(['failed', 'cancelled', 'timed-out']);
+const reviewStates = new Set(['unknown', 'operator-review-required']);
+function lifecycleSatisfied(kind, state, health) {
+    switch (kind) {
+        case 'one-shot-command': return state === 'succeeded';
+        case 'persistent-agent': return state === 'retained' || state === 'detached' || state === 'running';
+        case 'daemon': return (state === 'healthy' || state === 'running') && health === 'healthy';
+        case 'scheduled-collector': return state === 'scheduled' || state === 'succeeded';
+    }
+}
+function collapseEvents(events) {
+    let latest;
+    const stale = [];
+    const artifacts = new Map();
+    for (const event of events) {
+        if (latest && event.revision <= latest.revision) {
+            stale.push(event.revision);
+            continue;
+        }
+        latest = event;
+        for (const artifact of event.artifacts ?? [])
+            artifacts.set(`${artifact.kind}:${artifact.uri}`, artifact);
+    }
+    return { latest, stale, artifacts: [...artifacts.values()] };
+}
+function emptyAggregation(policy) {
+    return {
+        policy,
+        successful: 0,
+        failed: 0,
+        pending: 0,
+        reviewRequired: 0,
+        evidenceMissing: [],
+        completionEligible: false,
+        reason: 'children have not been evaluated',
+    };
+}
+function aggregate(policy, cycles) {
+    const successful = cycles.filter((cycle) => cycle.satisfied).length;
+    const failed = cycles.filter((cycle) => terminalFailures.has(cycle.observedState)).length;
+    const reviewRequired = cycles.filter((cycle) => reviewStates.has(cycle.observedState)).length;
+    const pending = cycles.length - successful - failed - reviewRequired;
+    const evidenceMissing = cycles.filter((cycle) => !cycle.evidenceComplete).map((cycle) => cycle.cycleId);
+    const allEvidence = evidenceMissing.length === 0;
+    let policySatisfied = false;
+    let reason = '';
+    switch (policy.mode) {
+        case 'all-pass':
+            policySatisfied = cycles.length > 0 && successful === cycles.length;
+            reason = `${successful}/${cycles.length} children satisfied all-pass`;
+            break;
+        case 'quorum':
+            policySatisfied = successful >= policy.minimumSuccesses;
+            reason = `${successful}/${policy.minimumSuccesses} quorum successes`;
+            break;
+        case 'best-output':
+            policySatisfied = cycles.some((cycle) => cycle.satisfied && Boolean(cycle.output));
+            reason = policySatisfied ? 'at least one satisfied child produced output' : 'no satisfied child produced output';
+            break;
+        case 'fail-fast':
+            policySatisfied = failed === 0 && cycles.length > 0 && successful === cycles.length;
+            reason = failed > 0 ? 'a child reached a terminal failure' : `${successful}/${cycles.length} children satisfied`;
+            break;
+        case 'manual-review':
+            policySatisfied = false;
+            reason = 'manual-review policy requires an audited operator decision';
+            break;
+    }
+    if (reviewRequired > 0)
+        reason = `${reviewRequired} child observation(s) require operator review`;
+    if (!allEvidence)
+        reason = `required evidence missing for: ${evidenceMissing.join(', ')}`;
+    return {
+        policy,
+        successful,
+        failed,
+        pending,
+        reviewRequired,
+        evidenceMissing,
+        completionEligible: policySatisfied && allEvidence && reviewRequired === 0,
+        reason,
+    };
+}
+function cloneLedger(ledger) {
+    return structuredClone(ledger);
+}
+/**
+ * Runs every newly admitted child concurrently. Target allocation happens
+ * before execution, so one slow child cannot serialize unrelated work.
+ */
+export class FleetMissionConductor {
+    adapters;
+    runWorker;
+    scoreOutput;
+    ledgerStore;
+    /** Prevent concurrent child completions from committing snapshots out of order. */
+    persistQueue = Promise.resolve();
+    constructor(options) {
+        this.adapters = options.adapters ?? new StackAdapterRegistry();
+        this.runWorker = options.runWorker;
+        this.scoreOutput = options.scoreOutput ?? ((result) => result.output?.length ?? 0);
+        this.ledgerStore = options.ledgerStore;
+    }
+    async conduct(plan, pool, resumeFrom) {
+        const priorById = new Map((resumeFrom?.cycles ?? []).map((cycle) => [cycle.cycleId, cycle]));
+        const ledger = {
+            missionId: plan.missionId,
+            goal: plan.goal,
+            completionCriterion: plan.completionCriterion,
+            activityLog: [`mission ${plan.missionId} fleet start — ${plan.cycles.length} child workload(s)`],
+            cycles: [],
+            totalCost: 0,
+            checkpoint: { completed: [], pending: plan.cycles.map((cycle) => cycle.id), failed: [] },
+            runtimesUsed: [],
+            parentState: 'running',
+            aggregation: emptyAggregation(plan.aggregation),
+        };
+        const admitted = [];
+        const usedExecutors = new Set();
+        for (const cycle of plan.cycles) {
+            const prior = priorById.get(cycle.id);
+            if (prior?.satisfied && prior.evidenceComplete && !reviewStates.has(prior.observedState)) {
+                ledger.cycles.push(prior);
+                ledger.activityLog.push(`child ${cycle.id} re-adopted from durable completed state`);
+                continue;
+            }
+            const adapter = this.adapters.get(cycle.runtime);
+            if (!adapter) {
+                ledger.cycles.push(this.unroutable(cycle, `no stack adapter registered for runtime '${cycle.runtime}'`));
+                continue;
+            }
+            let candidates = pool;
+            if (cycle.targetId)
+                candidates = candidates.filter((executor) => executor.executorId === cycle.targetId);
+            if (plan.requireDistinctTargets !== false) {
+                candidates = candidates.filter((executor) => !usedExecutors.has(executor.executorId));
+            }
+            const routing = routeMission(candidates, {
+                capabilities: [adapter.runtimeCapability, ...(cycle.requiredCapabilities ?? [])],
+            }, cycle.longRunning ?? false);
+            if (!routing.selected) {
+                ledger.cycles.push(this.unroutable(cycle, 'no distinct connected executor satisfies the child requirements'));
+                continue;
+            }
+            const executor = routing.selected.executor;
+            usedExecutors.add(executor.executorId);
+            const dispatchId = cycle.dispatchId ?? `${plan.missionId}:${cycle.id}:dispatch`;
+            const lineage = {
+                orchestratorId: plan.orchestratorId,
+                missionId: plan.missionId,
+                dispatchId,
+                idempotencyKey: cycle.idempotencyKey ?? dispatchId,
+                parentId: plan.missionId,
+                childId: cycle.id,
+                targetId: cycle.targetId ?? executor.executorId,
+                executorId: executor.executorId,
+                runtimeId: cycle.runtime,
+            };
+            admitted.push({ cycle, executor, invocation: adapter.invoke(cycle.prompt), lineage });
+            ledger.activityLog.push(`child ${cycle.id} admitted on target ${lineage.targetId} as ${cycle.workloadKind}`);
+        }
+        ledger.aggregation = aggregate(plan.aggregation, ledger.cycles);
+        await this.persist(ledger);
+        await Promise.all(admitted.map(async ({ cycle, executor, invocation, lineage }) => {
+            let result;
+            try {
+                const ran = await this.runWorker(cycle, executor, invocation, lineage);
+                const collapsed = collapseEvents(ran.events);
+                const latest = collapsed.latest;
+                const observedState = latest?.observedState ?? 'unknown';
+                const artifacts = collapsed.artifacts;
+                const required = cycle.requiredEvidence ?? [];
+                const evidenceComplete = required.every((kind) => artifacts.some((artifact) => artifact.kind === kind));
+                result = {
+                    cycleId: cycle.id,
+                    runtime: cycle.runtime,
+                    primitive: invocation.primitive,
+                    executorId: executor.executorId,
+                    routed: true,
+                    reason: latest ? `observed revision ${latest.revision}: ${observedState}` : 'runtime returned no lifecycle event',
+                    output: ran.output,
+                    cost: ran.cost ?? 0,
+                    workloadKind: cycle.workloadKind,
+                    lineage,
+                    commandId: ran.commandId ?? latest?.commandId,
+                    taskId: latest?.taskId,
+                    sessionId: ran.sessionId ?? latest?.sessionId,
+                    observedState,
+                    revision: latest?.revision ?? 0,
+                    lastSeen: latest?.lastSeen,
+                    health: latest?.health,
+                    backpressure: latest?.backpressure,
+                    artifacts,
+                    staleEventRevisions: collapsed.stale,
+                    evidenceComplete,
+                    satisfied: evidenceComplete && lifecycleSatisfied(cycle.workloadKind, observedState, latest?.health),
+                };
+            }
+            catch (error) {
+                result = {
+                    cycleId: cycle.id,
+                    runtime: cycle.runtime,
+                    primitive: invocation.primitive,
+                    executorId: executor.executorId,
+                    routed: true,
+                    reason: `worker error: ${error instanceof Error ? error.message : String(error)}`,
+                    cost: 0,
+                    workloadKind: cycle.workloadKind,
+                    lineage,
+                    observedState: 'unknown',
+                    revision: 0,
+                    artifacts: [],
+                    staleEventRevisions: [],
+                    evidenceComplete: (cycle.requiredEvidence ?? []).length === 0,
+                    satisfied: false,
+                };
+            }
+            ledger.cycles.push(result);
+            ledger.activityLog.push(`child ${cycle.id} observed ${result.observedState} at revision ${result.revision}`);
+            ledger.aggregation = aggregate(plan.aggregation, ledger.cycles);
+            await this.persist(ledger);
+        }));
+        // Stable plan order makes durable snapshots and UI projection deterministic.
+        const order = new Map(plan.cycles.map((cycle, index) => [cycle.id, index]));
+        ledger.cycles.sort((a, b) => (order.get(a.cycleId) ?? 0) - (order.get(b.cycleId) ?? 0));
+        ledger.totalCost = ledger.cycles.reduce((sum, cycle) => sum + cycle.cost, 0);
+        ledger.runtimesUsed = [...new Set(ledger.cycles.filter((cycle) => cycle.routed).map((cycle) => cycle.runtime))];
+        ledger.checkpoint = {
+            completed: ledger.cycles.filter((cycle) => cycle.satisfied).map((cycle) => cycle.cycleId),
+            failed: ledger.cycles.filter((cycle) => terminalFailures.has(cycle.observedState)).map((cycle) => cycle.cycleId),
+            pending: ledger.cycles.filter((cycle) => !cycle.satisfied && !terminalFailures.has(cycle.observedState)).map((cycle) => cycle.cycleId),
+        };
+        let best;
+        for (const cycle of ledger.cycles) {
+            if (!cycle.output || !cycle.satisfied)
+                continue;
+            const score = this.scoreOutput(cycle);
+            if (!best || score > best.score)
+                best = { cycleId: cycle.cycleId, runtime: cycle.runtime, output: cycle.output, score };
+        }
+        ledger.bestOutput = best;
+        ledger.aggregation = aggregate(plan.aggregation, ledger.cycles);
+        ledger.parentState = ledger.aggregation.completionEligible
+            ? 'completed'
+            : ledger.aggregation.reviewRequired > 0 || plan.aggregation.mode === 'manual-review'
+                ? 'operator-review-required'
+                : ledger.aggregation.failed > 0
+                    ? 'failed'
+                    : 'pending';
+        ledger.activityLog.push(`mission ${plan.missionId} fleet end — ${ledger.parentState}: ${ledger.aggregation.reason}`);
+        await this.persist(ledger);
+        return ledger;
+    }
+    unroutable(cycle, reason) {
+        return {
+            cycleId: cycle.id,
+            runtime: cycle.runtime,
+            primitive: '(none)',
+            routed: false,
+            reason,
+            cost: 0,
+            workloadKind: cycle.workloadKind,
+            observedState: 'operator-review-required',
+            revision: 0,
+            artifacts: [],
+            staleEventRevisions: [],
+            evidenceComplete: (cycle.requiredEvidence ?? []).length === 0,
+            satisfied: false,
+        };
+    }
+    async persist(ledger) {
+        if (!this.ledgerStore)
+            return;
+        const snapshot = cloneLedger(ledger);
+        this.persistQueue = this.persistQueue.then(async () => {
+            await this.ledgerStore.save(snapshot);
+        });
+        await this.persistQueue;
+    }
+}
+//# sourceMappingURL=fleet-mission-conductor.js.map

package/dist/src/sessions/index.js

@@ -9,6 +9,7 @@ export * from './optional-backends.js';
 export * from './knowledge-shard.js';
 export * from './candidates.js';
 export * from './promotion.js';
+export * from './output-registration.js';
 export * from './importer.js';
 export * from './import-lease.js';
 export * from './batch-contracts.js';