@aiwg/cli 2026.8.3 → 2026.8.5

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

@@ -39,6 +39,7 @@ 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';
+import { digestDecisionContext } from '../audit/operator-decision.js';
 /** Default audit log — writes to stderr as JSONL. Replace with a file/HTTP sink in production. */
 export class StderrHitlAuditLog {
     append(entry) {
@@ -189,6 +190,21 @@ export async function driveOnePrompt(opts) {
     const maxRetries = Math.max(1, opts.maxRetries ?? 3);
     const messageIdFactory = opts.messageIdFactory ?? defaultMessageIdFactory;
     const startedAt = Date.now();
+    const operator = adapterOperator(opts.adapter);
+    if (!isResponderAllowed(opts.envelope.allowed_responders, operator)) {
+        await auditLog.append({
+            decided_at: new Date().toISOString(),
+            operator,
+            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: 'unauthorized',
+            error: 'operator is not authorized by allowed_responders',
+            duration_ms: Date.now() - startedAt,
+        });
+        return;
+    }
     // Set up the deadline AbortController if the envelope declares one.
     const controller = new AbortController();
     const deadlineMs = parseDeadline(opts.envelope.deadline);
@@ -296,7 +312,7 @@ export async function driveOnePrompt(opts) {
                 ...(opts.taskId !== undefined ? { task_id: opts.taskId } : {}),
                 ...(opts.contextId !== undefined ? { context_id: opts.contextId } : {}),
                 outcome: 'responded',
-                response,
+                response_digest: digestDecisionContext(response),
                 duration_ms: Date.now() - startedAt,
             });
             return;
@@ -358,6 +374,17 @@ function adapterOperator(adapter) {
     const id = adapter.operatorId;
     return typeof id === 'string' && id.length > 0 ? id : adapter.name;
 }
+/**
+ * Enforce the v1 coarse responder policy before collecting or forwarding a
+ * response. Consensus policies require an aggregate routing adapter and are
+ * therefore not satisfied by a single-principal adapter.
+ */
+export function isResponderAllowed(policies, responderId) {
+    const effective = policies?.length ? policies : ['any'];
+    if (effective.includes('any'))
+        return true;
+    return effective.some(policy => policy.startsWith('specific:') && policy.slice('specific:'.length) === responderId);
+}
 function defaultMessageIdFactory() {
     // Prefer crypto.randomUUID; fall back to timestamp+random for older node.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/src/a2a/hitl.js

@@ -14,8 +14,8 @@
 //   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>`
+//   5. POST a reply Message with the canonical
+//      `metadata.hitl_response_for: { prompt_id, payload }` envelope
 //
 // This module handles steps 1–4. Step 5 lives in the A2AClient consumer
 // that drives the task lifecycle.
@@ -24,6 +24,9 @@
 import { A2A_HITL_PROMPT_V1 } from './client.js';
 /** Required envelope keys per spec §Prompt envelope. */
 const REQUIRED_ENVELOPE_KEYS = ['prompt_id', 'prompt', 'response_schema'];
+const PROMPT_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const RESPONDER_RE = /^(any|specific:\S+|consensus:[1-9][0-9]*)$/;
+const MAX_RESPONSE_SCHEMA_BYTES = 64 * 1024;
 /**
  * Pull the HITL envelope out of a Task / TaskStatus / Message metadata
  * blob. Returns `null` when the structure is not `input-required` or
@@ -73,11 +76,30 @@ export function extractHitlEnvelope(source) {
             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' };
+    const allowedKeys = new Set([...REQUIRED_ENVELOPE_KEYS, 'deadline', 'allowed_responders']);
+    const unexpected = Object.keys(env).find(key => !allowedKeys.has(key));
+    if (unexpected)
+        return { ok: false, reason: `envelope contains unsupported key: ${unexpected}` };
+    if (typeof env['prompt_id'] !== 'string' || !PROMPT_ID_RE.test(env['prompt_id'])) {
+        return { ok: false, reason: 'prompt_id must be an RFC 4122 UUID' };
     }
-    if (typeof env['prompt'] !== 'string') {
-        return { ok: false, reason: 'prompt must be a string' };
+    if (typeof env['prompt'] !== 'string' || env['prompt'].length === 0) {
+        return { ok: false, reason: 'prompt must be a non-empty string' };
+    }
+    if (typeof env['response_schema'] !== 'object' || env['response_schema'] === null || Array.isArray(env['response_schema'])) {
+        return { ok: false, reason: 'response_schema must be an object' };
+    }
+    if (env['response_schema']['type'] !== 'object') {
+        return { ok: false, reason: 'response_schema must declare top-level type object' };
+    }
+    if (Buffer.byteLength(JSON.stringify(env['response_schema']), 'utf8') > MAX_RESPONSE_SCHEMA_BYTES) {
+        return { ok: false, reason: 'response_schema exceeds 64 KiB' };
+    }
+    if (env['deadline'] !== undefined && (typeof env['deadline'] !== 'string' || !Number.isFinite(Date.parse(env['deadline'])))) {
+        return { ok: false, reason: 'deadline must be an RFC 3339 timestamp' };
+    }
+    if (env['allowed_responders'] !== undefined && (!Array.isArray(env['allowed_responders']) || env['allowed_responders'].some(value => typeof value !== 'string' || !RESPONDER_RE.test(value)))) {
+        return { ok: false, reason: 'allowed_responders contains an invalid responder policy' };
     }
     return { ok: true, envelope: env };
 }
@@ -93,8 +115,10 @@ export function buildHitlResponseMessage(opts) {
             },
         ],
         metadata: {
-            hitl_response_for: opts.promptId,
-            [A2A_HITL_PROMPT_V1]: { response: opts.response },
+            hitl_response_for: {
+                prompt_id: opts.promptId,
+                payload: opts.response,
+            },
         },
     };
     if (opts.taskId !== undefined)

package/dist/src/audit/operator-decision.js

@@ -0,0 +1,180 @@
+/**
+ * Versioned, tamper-evident operator decision records for orchestration.
+ *
+ * Records contain correlation and digests, never raw prompts or credentials.
+ * The JSONL hash chain detects modification/deletion/reordering inside an
+ * exported segment; external checkpointing anchors segment heads.
+ *
+ * @implements #1567
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFile, chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export const OPERATOR_DECISION_SCHEMA = 'operator-decision.aiwg.io/v1';
+const secretKey = /token|secret|password|credential|authorization|cookie|csrf|api[_-]?key/i;
+const secretValue = /(?:bearer\s+\S+|\bsk-[a-z0-9_-]+|\bgh[pousr]_[a-z0-9_]+)/i;
+export function digestDecisionContext(context) {
+    const safe = redact(context).value;
+    return `sha256:${createHash('sha256').update(canonicalJson(safe)).digest('hex')}`;
+}
+export function createDecisionRecord(input, previousHash) {
+    validateInput(input);
+    const actor = redact(input.actor);
+    const correlation = redact(input.correlation);
+    const runtime = input.runtime ? redact(input.runtime) : undefined;
+    const reason = redact(input.reason);
+    const detected = [...actor.paths, ...correlation.paths, ...(runtime?.paths ?? []), ...reason.paths];
+    const unsigned = {
+        schema_version: OPERATOR_DECISION_SCHEMA,
+        event_id: input.event_id ?? randomUUID(),
+        timestamp: input.timestamp ?? new Date().toISOString(),
+        kind: input.kind,
+        outcome: input.outcome,
+        actor: actor.value,
+        reason: reason.value,
+        context_digest: digestDecisionContext(input.context),
+        classification: input.classification,
+        correlation: correlation.value,
+        ...(runtime ? { runtime: runtime.value } : {}),
+        ...(input.policy_ref ? { policy_ref: input.policy_ref } : {}),
+        redacted_fields: [...new Set([...(input.redacted_fields ?? []), ...detected])].sort(),
+        previous_hash: previousHash,
+    };
+    return {
+        ...unsigned,
+        record_hash: hashRecord(unsigned),
+    };
+}
+export function verifyDecisionChain(records) {
+    let previous = null;
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (record.previous_hash !== previous)
+            return { ok: false, index, reason: 'previous hash mismatch' };
+        const { record_hash, ...unsigned } = record;
+        if (hashRecord(unsigned) !== record_hash)
+            return { ok: false, index, reason: 'record hash mismatch' };
+        previous = record_hash;
+    }
+    return { ok: true };
+}
+export function toOpenTelemetryLog(record) {
+    return {
+        timeUnixNano: String(BigInt(Date.parse(record.timestamp)) * 1000000n),
+        severityText: record.outcome === 'denied' ? 'WARN' : 'INFO',
+        body: { stringValue: `${record.kind}:${record.outcome}` },
+        attributes: Object.entries({
+            'aiwg.audit.schema': record.schema_version,
+            'aiwg.audit.event_id': record.event_id,
+            'aiwg.audit.record_hash': record.record_hash,
+            'aiwg.decision.actor_id': record.actor.id,
+            'aiwg.decision.context_digest': record.context_digest,
+            'aiwg.mission.id': record.correlation.mission_id,
+            'aiwg.flow.id': record.correlation.flow_id,
+            'aiwg.provider.id': record.correlation.provider_id,
+            'aiwg.sandbox.task_id': record.correlation.sandbox_task_id,
+            'aiwg.prompt.id': record.correlation.prompt_id,
+        }).filter(([, value]) => value !== undefined).map(([key, value]) => ({
+            key,
+            value: { stringValue: String(value) },
+        })),
+    };
+}
+export class JsonlOperatorDecisionStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async append(input) {
+        const records = await this.read();
+        const verification = verifyDecisionChain(records);
+        if (!verification.ok)
+            throw new Error(`operator decision audit chain is invalid at ${verification.index}: ${verification.reason}`);
+        const record = createDecisionRecord(input, records.at(-1)?.record_hash ?? null);
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        await appendFile(this.path, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+        await chmod(this.path, 0o600);
+        return record;
+    }
+    async read() {
+        try {
+            const raw = await readFile(this.path, 'utf8');
+            return raw.split(/\n+/).filter(Boolean).map(line => JSON.parse(line));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+    }
+    async prune(policy, now = Date.now()) {
+        const prior = await this.read();
+        const retainedInputs = prior.filter(record => {
+            const days = policy.maxAgeDays[record.classification];
+            return days === undefined || Date.parse(record.timestamp) + days * 86_400_000 > now;
+        });
+        let previous = null;
+        const retained = retainedInputs.map(record => {
+            const { record_hash: _hash, previous_hash: _previous, ...rest } = record;
+            const next = { ...rest, previous_hash: previous };
+            const rebuilt = { ...next, record_hash: hashRecord(next) };
+            previous = rebuilt.record_hash;
+            return rebuilt;
+        });
+        const temporary = `${this.path}.tmp`;
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        await writeFile(temporary, retained.map(record => JSON.stringify(record)).join('\n') + (retained.length ? '\n' : ''), { mode: 0o600 });
+        await rename(temporary, this.path);
+        return { retained: retained.length, deleted: prior.length - retained.length, head_hash: previous };
+    }
+}
+function validateInput(input) {
+    if (!input.actor.id || !input.actor.authentication)
+        throw new Error('actor identity and authentication are required');
+    if (!input.reason.trim())
+        throw new Error('a non-empty operator reason is required');
+    if (!Object.values(input.correlation).some(Boolean))
+        throw new Error('at least one correlation identifier is required');
+    if (input.timestamp && !Number.isFinite(Date.parse(input.timestamp)))
+        throw new Error('timestamp must be valid ISO time');
+}
+function hashRecord(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function redact(value, path = '$') {
+    if (Array.isArray(value)) {
+        const rows = value.map((item, index) => redact(item, `${path}[${index}]`));
+        return { value: rows.map(row => row.value), paths: rows.flatMap(row => row.paths) };
+    }
+    if (value && typeof value === 'object') {
+        const output = {};
+        const paths = [];
+        for (const [key, item] of Object.entries(value)) {
+            if (secretKey.test(key)) {
+                output[key] = '[redacted]';
+                paths.push(`${path}.${key}`);
+            }
+            else {
+                const child = redact(item, `${path}.${key}`);
+                output[key] = child.value;
+                paths.push(...child.paths);
+            }
+        }
+        return { value: output, paths };
+    }
+    if (typeof value === 'string' && secretValue.test(value))
+        return { value: '[redacted]', paths: [path] };
+    return { value, paths: [] };
+}
+//# sourceMappingURL=operator-decision.js.map