@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/a2a/hitl-driver.js

@@ -0,0 +1,370 @@
+// HITL orchestrator driver — glues the SSE stream consumer, envelope
+// extractor, delivery adapter, schema validator, and reply poster
+// together.
+//
+// Usage:
+//
+//   import { A2AClient } from './client.js';
+//   import { CliHitlDeliveryAdapter } from './hitl-cli.js';
+//   import { driveHitlPromptsForTask } from './hitl-driver.js';
+//
+//   const client = new A2AClient({ ... });
+//   await driveHitlPromptsForTask({
+//     client,
+//     taskId,
+//     adapter: new CliHitlDeliveryAdapter(),
+//     auditLog,
+//   });
+//
+// The driver:
+//   1. Subscribes to the task's SSE stream.
+//   2. For each `status-update` with `state === 'input-required'`, extracts
+//      the hitl-prompt envelope (returns silently if absent — not every
+//      input-required state carries a HITL prompt).
+//   3. Validates the envelope, sets up a deadline-based AbortController if
+//      `envelope.deadline` is present.
+//   4. Routes to the configured delivery adapter to collect a response.
+//   5. Validates the response against `envelope.response_schema` using Ajv.
+//   6. POSTs the reply Message via `client.sendMessage`. Surfaces 422
+//      `hitl_response_invalid` as a clear operator error and re-prompts.
+//   7. Writes one audit-log entry per decision.
+//
+// Concurrent prompts are correlated by `prompt_id` and tracked in an
+// in-memory Map so a single task may have multiple outstanding HITL
+// prompts simultaneously (per spec).
+//
+// @issue #1255
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildHitlResponseMessage, extractHitlEnvelope, validateResponseStructurally, } from './hitl.js';
+/** Default audit log — writes to stderr as JSONL. Replace with a file/HTTP sink in production. */
+export class StderrHitlAuditLog {
+    append(entry) {
+        process.stderr.write(JSON.stringify({ hitl_audit: entry }) + '\n');
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _ajvCompile = null;
+let _ajvBootstrapped = false;
+function bootstrapAjv() {
+    if (_ajvBootstrapped)
+        return;
+    _ajvBootstrapped = true;
+    try {
+        const require = createRequire(fileURLToPath(import.meta.url));
+        const projectRoot = resolvePath(dirname(fileURLToPath(import.meta.url)), '..', '..');
+        const candidates = [
+            join(projectRoot, 'node_modules', 'ajv', 'dist', '2020.js'),
+            join(projectRoot, 'node_modules', 'ajv', 'dist', 'ajv.js'),
+        ];
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let Ajv = null;
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                try {
+                    Ajv = require(p);
+                    break;
+                }
+                catch {
+                    /* try next */
+                }
+            }
+        }
+        if (!Ajv)
+            return;
+        const AjvClass = Ajv.default ?? Ajv;
+        // strict: false because operator-supplied schemas vary widely; we
+        // accept whatever they declare. validateSchema: false avoids meta-
+        // schema URI fetches.
+        const ajv = new AjvClass({
+            strict: false,
+            allErrors: true,
+            validateSchema: false,
+        });
+        const formatsPath = join(projectRoot, 'node_modules', 'ajv-formats', 'dist', 'index.js');
+        if (existsSync(formatsPath)) {
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const fm = require(formatsPath);
+                const addFormats = fm.default ?? fm;
+                if (typeof addFormats === 'function')
+                    addFormats(ajv);
+            }
+            catch {
+                /* formats are optional */
+            }
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        _ajvCompile = (schema) => ajv.compile(schema);
+    }
+    catch {
+        /* graceful degrade to structural validator */
+    }
+}
+/**
+ * Validate `response` against the JSON Schema in `envelope.response_schema`.
+ * Uses Ajv when available (transitive dep); falls back to the structural
+ * validator in `hitl.ts` otherwise.
+ */
+export function validateResponseAgainstSchema(envelope, response) {
+    bootstrapAjv();
+    if (_ajvCompile) {
+        try {
+            const validate = _ajvCompile(envelope.response_schema);
+            if (validate(response))
+                return { ok: true };
+            const errors = (validate.errors ?? []).map(formatAjvError);
+            return { ok: false, errors };
+        }
+        catch (e) {
+            // Schema itself was malformed — fall through to structural.
+            // Don't swallow silently: include the error in fallback notes.
+            const structural = validateResponseStructurally(envelope.response_schema, response);
+            if (structural.ok)
+                return structural;
+            return {
+                ok: false,
+                errors: [
+                    `ajv refused schema (${e.message}); structural fallback:`,
+                    ...structural.errors,
+                ],
+            };
+        }
+    }
+    return validateResponseStructurally(envelope.response_schema, response);
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function formatAjvError(err) {
+    const path = err.instancePath || '$';
+    return `${path}: ${err.message ?? 'invalid'}`;
+}
+/**
+ * Subscribe to a task's SSE stream and drive HITL prompts to completion
+ * via the supplied adapter. Resolves when the stream closes (task reaches
+ * a terminal state) or when `maxPrompts` is reached.
+ */
+export async function driveHitlPromptsForTask(opts) {
+    const auditLog = opts.auditLog ?? new StderrHitlAuditLog();
+    const maxRetries = Math.max(1, opts.maxRevalidationRetries ?? 3);
+    const messageIdFactory = opts.messageIdFactory ?? defaultMessageIdFactory;
+    let prompts = 0;
+    const subscription = opts.client.subscribeToTask(opts.taskId, {
+        signal: opts.signal,
+    });
+    try {
+        for await (const event of subscription) {
+            const envelope = extractEnvelopeFromEvent(event);
+            if (!envelope)
+                continue;
+            const ctx = inferEventContext(event);
+            await driveOnePrompt({
+                envelope,
+                client: opts.client,
+                adapter: opts.adapter,
+                auditLog,
+                taskId: opts.taskId,
+                contextId: ctx.contextId,
+                deadline: envelope.deadline,
+                maxRetries,
+                messageIdFactory,
+            });
+            prompts++;
+            if (opts.maxPrompts !== undefined && prompts >= opts.maxPrompts)
+                break;
+        }
+    }
+    finally {
+        subscription.close();
+    }
+}
+/**
+ * Drive a single prompt-response cycle. Exposed for callers that want
+ * to bypass the SSE stream (e.g. when an envelope arrives via the push-
+ * notification webhook receiver in #1256).
+ */
+export async function driveOnePrompt(opts) {
+    const auditLog = opts.auditLog;
+    const maxRetries = Math.max(1, opts.maxRetries ?? 3);
+    const messageIdFactory = opts.messageIdFactory ?? defaultMessageIdFactory;
+    const startedAt = Date.now();
+    // Set up the deadline AbortController if the envelope declares one.
+    const controller = new AbortController();
+    const deadlineMs = parseDeadline(opts.envelope.deadline);
+    let deadlineTimer;
+    if (deadlineMs !== null) {
+        const remaining = deadlineMs - Date.now();
+        if (remaining <= 0) {
+            controller.abort();
+        }
+        else {
+            deadlineTimer = setTimeout(() => controller.abort(), remaining);
+        }
+    }
+    let lastError;
+    try {
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            let response;
+            try {
+                response = await opts.adapter.collect(opts.envelope, {
+                    ...(opts.taskId !== undefined ? { taskId: opts.taskId } : {}),
+                    ...(opts.contextId !== undefined ? { contextId: opts.contextId } : {}),
+                    signal: controller.signal,
+                });
+            }
+            catch (err) {
+                if (controller.signal.aborted) {
+                    await auditLog.append({
+                        decided_at: new Date().toISOString(),
+                        operator: adapterOperator(opts.adapter),
+                        channel: opts.adapter.name,
+                        prompt_id: opts.envelope.prompt_id,
+                        ...(opts.taskId !== undefined ? { task_id: opts.taskId } : {}),
+                        ...(opts.contextId !== undefined ? { context_id: opts.contextId } : {}),
+                        outcome: 'expired',
+                        error: deadlineMs !== null && Date.now() >= deadlineMs
+                            ? 'deadline expired before response'
+                            : err.message,
+                        duration_ms: Date.now() - startedAt,
+                    });
+                    return;
+                }
+                await auditLog.append({
+                    decided_at: new Date().toISOString(),
+                    operator: adapterOperator(opts.adapter),
+                    channel: opts.adapter.name,
+                    prompt_id: opts.envelope.prompt_id,
+                    ...(opts.taskId !== undefined ? { task_id: opts.taskId } : {}),
+                    ...(opts.contextId !== undefined ? { context_id: opts.contextId } : {}),
+                    outcome: 'aborted',
+                    error: err.message,
+                    duration_ms: Date.now() - startedAt,
+                });
+                return;
+            }
+            const validation = validateResponseAgainstSchema(opts.envelope, response);
+            if (!validation.ok) {
+                lastError = validation.errors.join('; ');
+                // Surface the schema gap clearly and let the operator retry.
+                process.stderr.write(`HITL response invalid: ${lastError}\n` +
+                    (attempt + 1 < maxRetries
+                        ? `(retry ${attempt + 1}/${maxRetries - 1})\n`
+                        : ''));
+                continue;
+            }
+            // Validation passed — POST the reply.
+            const reply = buildHitlResponseMessage({
+                promptId: opts.envelope.prompt_id,
+                response,
+                messageId: messageIdFactory(),
+                ...(opts.taskId !== undefined ? { taskId: opts.taskId } : {}),
+                ...(opts.contextId !== undefined ? { contextId: opts.contextId } : {}),
+            });
+            try {
+                await opts.client.sendMessage(reply);
+            }
+            catch (err) {
+                // Surface 422 hitl_response_invalid distinctly from network errors.
+                const msg = err.message;
+                if (/422|hitl_response_invalid/.test(msg)) {
+                    lastError = msg;
+                    process.stderr.write(`Executor rejected response (HTTP 422): ${msg}\n` +
+                        (attempt + 1 < maxRetries
+                            ? `(retry ${attempt + 1}/${maxRetries - 1})\n`
+                            : ''));
+                    continue;
+                }
+                await auditLog.append({
+                    decided_at: new Date().toISOString(),
+                    operator: adapterOperator(opts.adapter),
+                    channel: opts.adapter.name,
+                    prompt_id: opts.envelope.prompt_id,
+                    ...(opts.taskId !== undefined ? { task_id: opts.taskId } : {}),
+                    ...(opts.contextId !== undefined ? { context_id: opts.contextId } : {}),
+                    outcome: 'send_failed',
+                    error: msg,
+                    duration_ms: Date.now() - startedAt,
+                });
+                throw err;
+            }
+            await auditLog.append({
+                decided_at: new Date().toISOString(),
+                operator: adapterOperator(opts.adapter),
+                channel: opts.adapter.name,
+                prompt_id: opts.envelope.prompt_id,
+                ...(opts.taskId !== undefined ? { task_id: opts.taskId } : {}),
+                ...(opts.contextId !== undefined ? { context_id: opts.contextId } : {}),
+                outcome: 'responded',
+                response,
+                duration_ms: Date.now() - startedAt,
+            });
+            return;
+        }
+        // Exhausted retries — record the final invalid outcome.
+        await auditLog.append({
+            decided_at: new Date().toISOString(),
+            operator: adapterOperator(opts.adapter),
+            channel: opts.adapter.name,
+            prompt_id: opts.envelope.prompt_id,
+            ...(opts.taskId !== undefined ? { task_id: opts.taskId } : {}),
+            ...(opts.contextId !== undefined ? { context_id: opts.contextId } : {}),
+            outcome: 'invalid',
+            error: lastError ?? 'response did not validate after max retries',
+            duration_ms: Date.now() - startedAt,
+        });
+    }
+    finally {
+        if (deadlineTimer)
+            clearTimeout(deadlineTimer);
+    }
+}
+// ── helpers ────────────────────────────────────────────────────────────
+function extractEnvelopeFromEvent(event) {
+    if (event.kind === 'task-state') {
+        const result = extractHitlEnvelope(event.task);
+        if (result?.ok)
+            return result.envelope;
+        return null;
+    }
+    if (event.kind === 'status-update') {
+        const result = extractHitlEnvelope(event.status);
+        if (result?.ok)
+            return result.envelope;
+        return null;
+    }
+    return null;
+}
+function inferEventContext(event) {
+    if (event.kind === 'task-state') {
+        return event.task.contextId !== undefined
+            ? { contextId: event.task.contextId }
+            : {};
+    }
+    // status-update / artifact-update don't carry a contextId; the caller
+    // can pass one through `driveOnePrompt` directly if it has one cached.
+    return {};
+}
+function parseDeadline(deadline) {
+    if (!deadline)
+        return null;
+    const ms = Date.parse(deadline);
+    return Number.isFinite(ms) ? ms : null;
+}
+function adapterOperator(adapter) {
+    // CLI adapter exposes `operatorId`; other adapters may too. Fall back
+    // to the adapter name so the audit entry is never empty.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const id = adapter.operatorId;
+    return typeof id === 'string' && id.length > 0 ? id : adapter.name;
+}
+function defaultMessageIdFactory() {
+    // Prefer crypto.randomUUID; fall back to timestamp+random for older node.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const crypto = globalThis.crypto;
+    if (crypto && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    return `hitl-reply-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
+}
+//# sourceMappingURL=hitl-driver.js.map

package/dist/src/a2a/hitl.js

@@ -0,0 +1,181 @@
+// HITL prompt envelope extractor + delivery adapter interface.
+//
+// Per `agentic-sandbox/docs/contracts/extensions/hitl-prompt/v1/spec.md`,
+// when a task transitions to `input-required` the executor places a HITL
+// prompt envelope at:
+//
+//   task.status.message.metadata['https://agentic-sandbox.aiwg.io/extensions/hitl-prompt/v1']
+//
+// The envelope has required keys (prompt_id, prompt, response_schema) and
+// optional keys (deadline, allowed_responders). AIWG's orchestrator owns
+// the workflow:
+//
+//   1. Detect `input-required` state on a Task / status-update event
+//   2. Extract the envelope
+//   3. Route to a HitlDeliveryAdapter (CLI / Slack / web)
+//   4. Validate the operator's response against `response_schema`
+//   5. POST a reply Message with `metadata.hitl_response_for: <prompt_id>`
+//      and the response payload at `metadata.<URI>`
+//
+// This module handles steps 1–4. Step 5 lives in the A2AClient consumer
+// that drives the task lifecycle.
+//
+// @issue #1255
+import { A2A_HITL_PROMPT_V1 } from './client.js';
+/** Required envelope keys per spec §Prompt envelope. */
+const REQUIRED_ENVELOPE_KEYS = ['prompt_id', 'prompt', 'response_schema'];
+/**
+ * Pull the HITL envelope out of a Task / TaskStatus / Message metadata
+ * blob. Returns `null` when the structure is not `input-required` or
+ * doesn't carry the envelope. Returns a typed envelope when valid.
+ *
+ * Pass either the full Task, just the TaskStatus, or just the
+ * `status.message` to suit the calling site.
+ */
+export function extractHitlEnvelope(source) {
+    if (!source)
+        return null;
+    // Get to the `metadata` object that should carry the envelope.
+    let metadata;
+    let stateGuardPassed = false;
+    if (isTask(source)) {
+        if (source.status.state !== 'input-required')
+            return null;
+        stateGuardPassed = true;
+        metadata = source.status.message?.metadata;
+    }
+    else if (isTaskStatus(source)) {
+        if (source.state !== 'input-required')
+            return null;
+        stateGuardPassed = true;
+        metadata = source.message?.metadata;
+    }
+    else if (isMessage(source)) {
+        // No state to guard on; assume caller already filtered by state.
+        stateGuardPassed = true;
+        metadata = source.metadata;
+    }
+    if (!stateGuardPassed)
+        return null;
+    if (!metadata) {
+        return { ok: false, reason: 'no metadata on status.message' };
+    }
+    const raw = metadata[A2A_HITL_PROMPT_V1];
+    if (raw === undefined) {
+        return { ok: false, reason: `missing envelope at metadata[${A2A_HITL_PROMPT_V1}]` };
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        return { ok: false, reason: 'envelope is not an object' };
+    }
+    const env = raw;
+    for (const key of REQUIRED_ENVELOPE_KEYS) {
+        if (!(key in env)) {
+            return { ok: false, reason: `envelope missing required key: ${key}` };
+        }
+    }
+    if (typeof env['prompt_id'] !== 'string' || env['prompt_id'].length === 0) {
+        return { ok: false, reason: 'prompt_id must be a non-empty string' };
+    }
+    if (typeof env['prompt'] !== 'string') {
+        return { ok: false, reason: 'prompt must be a string' };
+    }
+    return { ok: true, envelope: env };
+}
+/** Build the response Message that closes a HITL prompt cycle. */
+export function buildHitlResponseMessage(opts) {
+    const message = {
+        messageId: opts.messageId,
+        role: 'user',
+        parts: [
+            {
+                kind: 'data',
+                data: opts.response,
+            },
+        ],
+        metadata: {
+            hitl_response_for: opts.promptId,
+            [A2A_HITL_PROMPT_V1]: { response: opts.response },
+        },
+    };
+    if (opts.taskId !== undefined)
+        message.taskId = opts.taskId;
+    if (opts.contextId !== undefined)
+        message.contextId = opts.contextId;
+    return message;
+}
+/**
+ * Validate a response payload against the envelope's `response_schema`.
+ *
+ * This module deliberately stays free of an `ajv` import so consumers can
+ * either plug in their own validator (see `validateResponseAgainstSchema`)
+ * or fall back to structural checks. AIWG already has `ajv` in the dep
+ * graph from `src/research/`, so the typical wiring is:
+ *
+ *   import Ajv from 'ajv';
+ *   const ajv = new Ajv({ allErrors: true });
+ *   const validate = ajv.compile(envelope.response_schema);
+ *   const ok = validate(response);
+ *   if (!ok) { ... use validate.errors ... }
+ *
+ * For tests we ship a tiny structural validator below that covers the
+ * happy path. A full `ajv` wiring lands at the orchestrator call site so
+ * AIWG can pick its own validator strategy (Ajv strict mode, Zod, etc.).
+ */
+export function validateResponseStructurally(schema, response) {
+    const errors = [];
+    walk(schema, response, '$', errors);
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+function walk(schema, value, path, errors) {
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema))
+        return;
+    const s = schema;
+    if (typeof s['type'] === 'string') {
+        const expected = s['type'];
+        const actual = typeOf(value);
+        if (expected !== actual) {
+            errors.push(`${path}: expected ${expected}, got ${actual}`);
+            return;
+        }
+    }
+    if (s['type'] === 'object' && value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const v = value;
+        const required = Array.isArray(s['required']) ? s['required'] : [];
+        for (const r of required) {
+            if (typeof r === 'string' && !(r in v)) {
+                errors.push(`${path}.${r}: required field missing`);
+            }
+        }
+        const properties = s['properties'] && typeof s['properties'] === 'object' && !Array.isArray(s['properties'])
+            ? s['properties']
+            : {};
+        for (const [k, sub] of Object.entries(properties)) {
+            if (k in v)
+                walk(sub, v[k], `${path}.${k}`, errors);
+        }
+    }
+    if (s['type'] === 'array' && Array.isArray(value)) {
+        const items = s['items'];
+        if (items) {
+            value.forEach((el, i) => walk(items, el, `${path}[${i}]`, errors));
+        }
+    }
+}
+function typeOf(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+// ---------- narrow type guards ----------
+function isTask(v) {
+    return typeof v === 'object' && v !== null && 'id' in v && 'status' in v;
+}
+function isTaskStatus(v) {
+    return typeof v === 'object' && v !== null && 'state' in v && !('id' in v);
+}
+function isMessage(v) {
+    return typeof v === 'object' && v !== null && 'messageId' in v && 'role' in v;
+}
+//# sourceMappingURL=hitl.js.map