aiwg/dist/src/a2a/hitl.d.ts

Deployment tool and support utility for AI context. Copies agents, skills, commands, rules, and behaviors into the paths each AI platform reads (Claude Code, Codex, Copilot, Cursor, Warp, OpenClaw, and 6 more) so one source of truth works across 10 platfo

import type { JsonValue, Message, Task, TaskStatus } from './types.js';
/** Envelope shape (executor-side mirror of `metadata.<HITL URI>`). */
export interface HitlPromptEnvelope {
    /** Server-assigned correlation id; used in the reply's `hitl_response_for`. */
    prompt_id: string;
    /** Human-readable prompt text (markdown allowed). */
    prompt: string;
    /** JSON Schema the operator response must conform to. */
    response_schema: JsonValue;
    /** Optional RFC 3339 deadline; orchestrator policy decides on expiry. */
    deadline?: string;
    /** Optional list of authorized responder ids (operator usernames, role names). */
    allowed_responders?: string[];
    /** Free-form vendor metadata. */
    [extra: string]: JsonValue | undefined;
}
/** Result of structural envelope validation. */
export type EnvelopeValidation = {
    ok: true;
    envelope: HitlPromptEnvelope;
} | {
    ok: false;
    reason: string;
};
/**
 * 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 declare function extractHitlEnvelope(source: Task | TaskStatus | Message | null | undefined): EnvelopeValidation | null;
/** Build the response Message that closes a HITL prompt cycle. */
export declare function buildHitlResponseMessage(opts: {
    promptId: string;
    response: JsonValue;
    messageId: string;
    taskId?: string;
    contextId?: string;
}): Message;
/** Delivery adapter interface — pluggable transport for the prompt. */
export interface HitlDeliveryAdapter {
    /** Display name (for logging / audit trail). */
    name: string;
    /**
     * Deliver a prompt to the operator and collect their response payload.
     *
     * The adapter is responsible for:
     *   - rendering the prompt
     *   - reading the operator's response (UI / stdin / web form)
     *   - returning a JsonValue that conforms to `envelope.response_schema`
     *
     * If validation against the schema fails the orchestrator will reject
     * the response and may re-prompt. Throwing here aborts the flow.
     *
     * Adapters MUST honor `signal` for cancellation. The orchestrator
     * aborts the signal when `deadline` passes or the task is canceled.
     */
    collect(envelope: HitlPromptEnvelope, ctx: {
        taskId?: string;
        contextId?: string;
        signal?: AbortSignal;
    }): Promise<JsonValue>;
}
/** Validation result shape returned by `validateResponseAgainstSchema`. */
export type SchemaValidation = {
    ok: true;
} | {
    ok: false;
    errors: string[];
};
/**
 * 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 declare function validateResponseStructurally(schema: JsonValue, response: JsonValue): SchemaValidation;
//# sourceMappingURL=hitl.d.ts.map