@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/serve/a2a-terminal-observer.js

@@ -0,0 +1,120 @@
+/**
+ * A2A terminal observer.
+ *
+ * v2 dispatch returns an A2A Task immediately. Executors may not also emit the
+ * executor-contract mission.* event stream, so aiwg serve must follow the task
+ * until it reaches a terminal A2A state and then project that state into the
+ * ExecutorRegistry mission model.
+ *
+ * @issue #1374
+ */
+import { A2AClient } from '../a2a/client.js';
+import { isTerminalTaskState, } from '../a2a/types.js';
+const DEFAULT_POLL_INTERVAL_MS = 1000;
+const DEFAULT_MAX_POLLS = 300;
+export async function observeA2ATerminalState(registry, executor, missionId, a2aInstanceId, initialTask, opts = {}) {
+    try {
+        const clientOpts = {
+            baseUrl: executor.transportEndpoints.rest,
+            bearer: executor.token,
+            instanceId: a2aInstanceId,
+        };
+        if (opts.fetch)
+            clientOpts.fetch = opts.fetch;
+        const client = new A2AClient(clientOpts);
+        let task = initialTask;
+        emitNonTerminalProgress(registry, executor.executorId, missionId, task);
+        for (let attempt = 0; attempt <= (opts.maxPolls ?? DEFAULT_MAX_POLLS); attempt++) {
+            if (isTerminalTaskState(task.status.state)) {
+                emitTerminalTask(registry, executor.executorId, missionId, task);
+                return;
+            }
+            if (attempt === (opts.maxPolls ?? DEFAULT_MAX_POLLS))
+                break;
+            await sleep(opts.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+            task = await client.getTask(task.id);
+            emitNonTerminalProgress(registry, executor.executorId, missionId, task);
+        }
+        registry.failMission(missionId, `A2A task ${initialTask.id} did not reach a terminal state before observer timeout`);
+    }
+    catch (err) {
+        registry.failMission(missionId, `A2A terminal observer failed: ${err.message ?? String(err)}`);
+        opts.onError?.(err);
+    }
+}
+function emitNonTerminalProgress(registry, executorId, missionId, task) {
+    const state = task.status.state;
+    if (state === 'working') {
+        registry.handleEvent(makeEnvelope('mission.started', executorId, missionId, task, {
+            state: 'running',
+            a2a_task_id: task.id,
+            summary: taskStatusSummary(task),
+        }));
+        return;
+    }
+    if (state === 'input-required') {
+        registry.handleEvent(makeEnvelope('mission.hitl_required', executorId, missionId, task, {
+            state: 'hitl-required',
+            a2a_task_id: task.id,
+            summary: taskStatusSummary(task),
+        }));
+    }
+}
+function emitTerminalTask(registry, executorId, missionId, task) {
+    const state = task.status.state;
+    if (state === 'completed') {
+        registry.handleEvent(makeEnvelope('mission.completed', executorId, missionId, task, {
+            state: 'done',
+            a2a_task_id: task.id,
+            summary: taskStatusSummary(task),
+            ...exitCodeData(task),
+        }));
+        return;
+    }
+    if (state === 'canceled') {
+        registry.handleEvent(makeEnvelope('mission.aborted', executorId, missionId, task, {
+            state: 'aborted',
+            a2a_task_id: task.id,
+            summary: taskStatusSummary(task),
+            error: taskStatusSummary(task) ?? `A2A task ${task.id} was canceled`,
+            ...exitCodeData(task),
+        }));
+        return;
+    }
+    registry.handleEvent(makeEnvelope('mission.failed', executorId, missionId, task, {
+        state: 'failed',
+        a2a_task_id: task.id,
+        summary: taskStatusSummary(task),
+        error: taskStatusSummary(task) ?? `A2A task ${task.id} reached terminal state ${state}`,
+        ...exitCodeData(task),
+    }));
+}
+function makeEnvelope(event, executorId, missionId, task, data) {
+    return {
+        event,
+        executor_id: executorId,
+        mission_id: missionId,
+        ts: task.status.timestamp ?? new Date().toISOString(),
+        data,
+    };
+}
+function taskStatusSummary(task) {
+    const status = task.status;
+    return typeof status.summary === 'string' ? status.summary : undefined;
+}
+function exitCodeData(task) {
+    const status = task.status;
+    return typeof status.exit_code === 'number' ? { exit_code: status.exit_code } : {};
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        if (typeof timer === 'object' && typeof timer.unref === 'function') {
+            timer.unref();
+        }
+    });
+}
+export function isA2ATerminalState(state) {
+    return isTerminalTaskState(state);
+}
+//# sourceMappingURL=a2a-terminal-observer.js.map

package/dist/src/serve/agent-router.js

@@ -0,0 +1,205 @@
+/**
+ * Agent Router
+ *
+ * Capability-based and load-aware agent routing for task dispatch (#916).
+ * Selects the best available agent for a task based on declared filters
+ * (framework requirements, inventory, resource thresholds) and real-time
+ * metrics (CPU/memory load from #911).
+ *
+ * Also exposes routeMission() for executor-level routing (#1179).
+ */
+/**
+ * Select the best executor from the provided list using filter criteria.
+ *
+ * Default-selection policy (per ADR §3):
+ *   1. Sandbox-first: prefer any executor with isolation:vm or isolation:container
+ *   2. Local fallback: isolation:none or isolation:host
+ *   3. 503 if no executor is connected and matching
+ *
+ * `long_running: true` requires the 'resumable' capability.
+ *
+ * Returns an ExecutorRoutingResult with the selected executor and full candidate list.
+ */
+export function routeMission(executors, filter, longRunning = false) {
+    const matched = [];
+    const rejected = [];
+    // Only consider connected executors
+    const connected = executors.filter((e) => e.connected);
+    const disconnected = executors.filter((e) => !e.connected);
+    for (const e of disconnected) {
+        rejected.push({ executorId: e.executorId, reason: 'executor not connected' });
+    }
+    for (const executor of connected) {
+        // Pinned executor_id
+        if (filter.executor_id && executor.executorId !== filter.executor_id) {
+            rejected.push({ executorId: executor.executorId, reason: `executor_id does not match '${filter.executor_id}'` });
+            continue;
+        }
+        // Long-running requires resumable
+        if (longRunning && !executor.capabilities.includes('resumable')) {
+            rejected.push({ executorId: executor.executorId, reason: 'long_running requires resumable capability' });
+            continue;
+        }
+        // All requested capabilities must be present
+        if (filter.capabilities && filter.capabilities.length > 0) {
+            const missing = filter.capabilities.filter((c) => !executor.capabilities.includes(c));
+            if (missing.length > 0) {
+                rejected.push({ executorId: executor.executorId, reason: `missing capabilities: ${missing.join(', ')}` });
+                continue;
+            }
+        }
+        matched.push({
+            executor,
+            matchReason: 'matches all filter criteria',
+            rejected,
+        });
+    }
+    if (matched.length === 0) {
+        return { selected: undefined, candidates: [], filter };
+    }
+    // ADR §3: sandbox-first policy — prefer vm/container isolation
+    const sandboxFirst = matched.filter((c) => c.executor.capabilities.some((cap) => cap === 'isolation:vm' || cap === 'isolation:container'));
+    let selected;
+    if (sandboxFirst.length > 0) {
+        selected = { ...sandboxFirst[0], matchReason: 'sandbox-first (isolation:vm/container)', rejected };
+    }
+    else {
+        selected = { ...matched[0], matchReason: 'local fallback (no vm/container executor)', rejected };
+    }
+    return { selected, candidates: matched, filter };
+}
+// ============================================================
+// Matching logic
+// ============================================================
+/** Returns a rejection reason string, or null if the agent matches. */
+export function matchAgent(agent, filter) {
+    // Direct agent targeting
+    if (filter.agent_id) {
+        const matches = agent.agentId === filter.agent_id
+            || agent.instanceId === filter.agent_id
+            || agent.logicalName === filter.agent_id;
+        if (!matches)
+            return `agentId/instanceId/logicalName does not match '${filter.agent_id}'`;
+    }
+    if (filter.agent_name) {
+        if (agent.logicalName !== filter.agent_name) {
+            return `logicalName '${agent.logicalName ?? 'none'}' does not match '${filter.agent_name}'`;
+        }
+    }
+    if (filter.sandbox_id && agent.sandboxId !== filter.sandbox_id) {
+        return `sandboxId '${agent.sandboxId}' does not match '${filter.sandbox_id}'`;
+    }
+    // Status check — skip disconnected/error agents
+    if (agent.status === 'disconnected' || agent.status === 'error') {
+        return `agent status is '${agent.status}'`;
+    }
+    // Platform requirements are declared per installed AIWG framework. A match
+    // on any framework provider means the agent can receive work for that
+    // provider.
+    if (filter.platform) {
+        const providers = new Set(agent.aiwgFrameworks?.flatMap((f) => f.providers) ?? []);
+        if (!providers.has(filter.platform)) {
+            return `platform providers do not include '${filter.platform}'`;
+        }
+    }
+    // Framework requirements
+    if (filter.frameworks && filter.frameworks.length > 0) {
+        const installed = new Set(agent.aiwgFrameworks?.map((f) => f.name) ?? []);
+        const missing = filter.frameworks.filter((f) => !installed.has(f));
+        if (missing.length > 0)
+            return `missing frameworks: ${missing.join(', ')}`;
+    }
+    // Agent inventory requirements
+    if (filter.agents && filter.agents.length > 0) {
+        const installed = new Set(agent.inventory?.agents.map((a) => a.name) ?? []);
+        const missing = filter.agents.filter((a) => !installed.has(a));
+        if (missing.length > 0)
+            return `missing agents in inventory: ${missing.join(', ')}`;
+    }
+    // Skill inventory requirements
+    if (filter.skills && filter.skills.length > 0) {
+        const installed = new Set(agent.inventory?.skills.map((s) => s.name) ?? []);
+        const missing = filter.skills.filter((s) => !installed.has(s));
+        if (missing.length > 0)
+            return `missing skills in inventory: ${missing.join(', ')}`;
+    }
+    // CPU load threshold
+    if (filter.max_cpu_percent !== undefined && agent.latestMetrics) {
+        if (agent.latestMetrics.cpu_percent > filter.max_cpu_percent) {
+            return `CPU ${agent.latestMetrics.cpu_percent.toFixed(1)}% exceeds max ${filter.max_cpu_percent}%`;
+        }
+    }
+    // Memory requirements (convert GB → bytes)
+    if (filter.min_memory_gb !== undefined && agent.latestMetrics) {
+        const freeBytes = agent.latestMetrics.memory_total_bytes - agent.latestMetrics.memory_used_bytes;
+        const freeGB = freeBytes / (1024 ** 3);
+        if (freeGB < filter.min_memory_gb) {
+            return `free memory ${freeGB.toFixed(1)}GB below min ${filter.min_memory_gb}GB`;
+        }
+    }
+    return null; // matches
+}
+/**
+ * Score an agent for ranking (lower = better).
+ * Primary: CPU percent. Secondary: memory usage percent.
+ */
+function agentScore(agent) {
+    const cpu = agent.latestMetrics?.cpu_percent ?? 50;
+    const memPct = agent.latestMetrics && agent.latestMetrics.memory_total_bytes > 0
+        ? (agent.latestMetrics.memory_used_bytes / agent.latestMetrics.memory_total_bytes) * 100
+        : 50;
+    return cpu * 0.7 + memPct * 0.3;
+}
+/**
+ * Select the best agent from candidates using filter criteria.
+ * Returns a RoutingResult with selected agent and full candidate list.
+ */
+export function routeTask(agents, filter) {
+    const matched = [];
+    const rejected = [];
+    for (const agent of agents) {
+        const reason = matchAgent(agent, filter);
+        if (reason === null) {
+            matched.push({
+                sandboxId: agent.sandboxId,
+                sandboxName: agent.sandboxName,
+                agent,
+                matchReason: 'matches all filter criteria',
+            });
+        }
+        else {
+            rejected.push({ agentId: agent.agentId, sandboxId: agent.sandboxId, reason });
+        }
+    }
+    // Sort matched agents by score (lower = better)
+    matched.sort((a, b) => agentScore(a.agent) - agentScore(b.agent));
+    // Apply fallback if no direct match
+    if (matched.length === 0 && filter.fallback && filter.fallback.strategy !== 'none') {
+        const relaxedFilter = { ...filter };
+        if (filter.fallback.strategy === 'any_with_framework') {
+            // Relax: keep only framework + status requirements
+            delete relaxedFilter.agents;
+            delete relaxedFilter.skills;
+            delete relaxedFilter.max_cpu_percent;
+            delete relaxedFilter.min_memory_gb;
+            delete relaxedFilter.agent_id;
+            delete relaxedFilter.agent_name;
+            relaxedFilter.fallback = undefined;
+        }
+        else if (filter.fallback.strategy === 'any') {
+            // Relax everything except sandbox affinity
+            return routeTask(agents, { sandbox_id: filter.sandbox_id });
+        }
+        return routeTask(agents, relaxedFilter);
+    }
+    const selected = matched[0];
+    if (selected) {
+        selected.rejected = rejected.map((r) => ({ agentId: r.agentId, reason: r.reason }));
+    }
+    return {
+        selected,
+        candidates: matched,
+        filter,
+    };
+}
+//# sourceMappingURL=agent-router.js.map

package/dist/src/serve/dispatch-router.js

@@ -0,0 +1,171 @@
+/**
+ * Dispatch Router — outbound mission dispatch with A2A-first + v1 fallback.
+ *
+ * AIWG exposes `POST /api/v1/sessions/:id/dispatch` as its public mission
+ * intake. The original implementation forwarded to the executor's v1
+ * `/dispatch` endpoint (`${rest}/dispatch`). Per #1252, AIWG should now
+ * try the A2A path first (`POST /agents/{a2aInstanceId}/v1/messages:send`)
+ * and fall back to v1 on 404 with a structured deprecation warning.
+ *
+ * Wire-shape mapping (v1 dispatch payload → A2A Message):
+ *
+ *   v1 payload                       →  A2A Message
+ *   --------------------------------    --------------------------------------
+ *   mission_id                          message.messageId (idempotency key)
+ *   objective                           parts[0] = { kind: 'text', text: ... }
+ *   completion                          metadata.completion
+ *   executor_filter                     metadata.executor_filter
+ *   long_running                        metadata.long_running
+ *   <any other field>                   metadata.<field>
+ *
+ * @issue #1252 #1254 #1259
+ */
+import { A2A_IDEMPOTENCY_V1, A2A_RUNTIME_V1, A2AClient, } from '../a2a/client.js';
+import { A2AError } from '../a2a/http.js';
+/**
+ * Route a dispatch to an executor. Tries v2 first, falls back to v1 on 404
+ * or when `forceV1` is set. Throws on all other failure modes — caller is
+ * responsible for surfacing 5xx to the inbound caller.
+ */
+export async function routeDispatch(executor, payload, opts = {}) {
+    if (opts.forceV1 === true) {
+        const v1 = await dispatchV1(executor, payload, opts);
+        return v1;
+    }
+    // Try v2 first.
+    try {
+        const v2 = await dispatchV2(executor, payload, opts);
+        return v2;
+    }
+    catch (err) {
+        // Only fall back on a 404 from the v2 path. Everything else propagates.
+        if (err instanceof A2AError && err.status === 404) {
+            // Capture sunset for the telemetry event if any was attached.
+            const sunset = err.problem.code === 'aiwg.deprecation_strict' ? undefined : undefined;
+            if (opts.onV1Fallback) {
+                opts.onV1Fallback({
+                    executorId: executor.executorId,
+                    reason: `v2 endpoint returned 404 (path=${err.path})`,
+                    ...(sunset !== undefined ? { sunset } : {}),
+                });
+            }
+            return dispatchV1(executor, payload, opts);
+        }
+        throw err;
+    }
+}
+/** v2 path — A2A `messages:send`. */
+async function dispatchV2(executor, payload, opts) {
+    const a2aInstanceId = resolveA2AInstanceId(executor, payload, opts);
+    const clientOpts = {
+        baseUrl: executor.transportEndpoints.rest,
+        bearer: executor.token,
+        instanceId: a2aInstanceId,
+        requiredExtensions: opts.requiredExtensions ?? [A2A_RUNTIME_V1, A2A_IDEMPOTENCY_V1],
+    };
+    if (opts.fetch)
+        clientOpts.fetch = opts.fetch;
+    if (opts.optionalExtensions)
+        clientOpts.optionalExtensions = opts.optionalExtensions;
+    if (opts.onDeprecation)
+        clientOpts.onDeprecation = opts.onDeprecation;
+    const client = new A2AClient(clientOpts);
+    const message = payloadToMessage(payload);
+    const result = await client.sendMessage(message);
+    return {
+        missionId: payload.mission_id,
+        executorId: executor.executorId,
+        a2aInstanceId,
+        dispatchPath: 'v2',
+        task: result.task,
+        idempotentReplayed: result.idempotentReplayed,
+    };
+}
+function resolveA2AInstanceId(executor, payload, opts) {
+    const filter = payload.executor_filter ?? {};
+    const filterInstance = filter['a2a_instance_id'] ?? filter['instance_id'];
+    return opts.a2aInstanceId
+        ?? payload.a2a_instance_id
+        ?? (typeof filterInstance === 'string' ? filterInstance : undefined)
+        ?? executor.a2aInstanceId
+        ?? executor.executorId;
+}
+/** v1 path — fall back to the legacy `/dispatch` endpoint. */
+async function dispatchV1(executor, payload, opts) {
+    const fetchImpl = opts.fetch ?? fetch;
+    const url = `${executor.transportEndpoints.rest.replace(/\/+$/, '')}/dispatch`;
+    const resp = await fetchImpl(url, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${executor.token}`,
+        },
+        body: JSON.stringify(payload),
+    });
+    // Inspect deprecation headers from the v1 response — these are exactly
+    // what #1259 is meant to surface.
+    if (opts.onDeprecation) {
+        const dep = readDeprecation(`${executor.transportEndpoints.rest}/dispatch`, resp.headers);
+        if (dep)
+            opts.onDeprecation(dep);
+    }
+    if (!resp.ok) {
+        const detail = await resp.text().catch(() => '');
+        throw new Error(`v1 dispatch failed: ${resp.status} ${detail}`);
+    }
+    let estimatedStart;
+    try {
+        const json = (await resp.json());
+        if (typeof json['estimated_start'] === 'string') {
+            estimatedStart = json['estimated_start'];
+        }
+    }
+    catch {
+        /* optional */
+    }
+    return {
+        missionId: payload.mission_id,
+        executorId: executor.executorId,
+        dispatchPath: 'v1-fallback',
+        idempotentReplayed: false,
+        ...(estimatedStart !== undefined ? { estimatedStart } : {}),
+    };
+}
+/** Map a v1 dispatch payload to an A2A Message. */
+function payloadToMessage(payload) {
+    const metadata = {};
+    for (const [k, v] of Object.entries(payload)) {
+        if (k === 'mission_id' || k === 'objective')
+            continue;
+        if (v === undefined)
+            continue;
+        // V1DispatchPayload allows boolean — coerce to JSON.
+        metadata[k] = v;
+    }
+    return {
+        messageId: payload.mission_id,
+        role: 'user',
+        parts: [{ kind: 'text', text: payload.objective }],
+        metadata,
+    };
+}
+function readDeprecation(path, headers) {
+    const sunset = headers.get('sunset') ?? undefined;
+    const deprecated = headers.get('deprecated') ?? undefined;
+    const link = headers.get('link') ?? undefined;
+    if (!sunset && !deprecated && !link)
+        return undefined;
+    let successor;
+    if (link) {
+        const m = /<([^>]+)>\s*;\s*[^,]*rel\s*=\s*"?successor-version"?/i.exec(link);
+        if (m)
+            successor = m[1];
+    }
+    return {
+        path,
+        ...(sunset ? { sunset } : {}),
+        ...(deprecated ? { deprecated } : {}),
+        ...(successor ? { successor } : {}),
+    };
+}
+//# sourceMappingURL=dispatch-router.js.map