agentfootprint/dist/types/adapters/hosting/responsesWire.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * adapters/hosting/responsesWire — the Responses protocol, as an `HttpWire`.
 *
 * ── What this is, and what it deliberately is not ────────────────────────────
 * This file speaks the **Responses** wire protocol: a request carries `input`
 * as text or as message items, a reply is a `response` object with an id and a
 * status, and a stream is a LIFECYCLE of named events that open the response,
 * announce output, carry deltas, and close each part before closing the
 * response itself.
 *
 * That protocol is nobody's product. It is the shape a Responses-speaking
 * client sends and expects, and several hosted runtimes speak it. So it lives
 * here as a dialect on its own, and the runtimes that CONFIGURE it — their
 * paths, their ports, their probe bodies, their session aliases — live in their
 * own files beside this one. Keeping the split means the next runtime that
 * speaks Responses is a configuration rather than a copy, and it means no
 * vendor's spelling ends up in the protocol.
 *
 * ── The subset ───────────────────────────────────────────────────────────────
 * A text turn, streamed or not, with a session. Deliberately not the whole
 * Responses API: tool calls, reasoning items, image/file input, structured
 * output and function-call output are NOT carried, and each is REFUSED by name
 * rather than dropped — a request whose content this dialect cannot represent
 * is answered 400 before a turn is paid for, never answered 200 with the parts
 * it happened to understand.
 *
 * @example  A host that speaks Responses on paths of its own choosing
 *   httpHost({
 *     name: 'myResponsesHost',
 *     wire: responsesWire({ defaultModel: 'my-agent' }),
 *     invokePath: '/responses',
 *     healthPath: '/health',
 *   });
 */
import type { HttpWire } from '../../hosting/httpHost.js';
/** Body fields that may carry a session id, in the order they are consulted. */
export declare const DEFAULT_SESSION_FIELDS: readonly string[];
/**
 * What a caller is told when a handler THREW.
 *
 * A thrown error's message is the author's note to their own logs — a query, a
 * path, a token in a connection string — and none of it is the caller's. A
 * handler that CHOSE to fail chose its words for the caller, so those travel
 * unchanged. The host tells this dialect which happened; it never guesses from
 * the message.
 */
export declare const PUBLIC_FAILURE_MESSAGE = "The agent could not complete this request.";
export interface ResponsesWireOptions {
    /** Model label echoed in `response` objects when the request names none. */
    readonly defaultModel?: string;
    /**
     * Body fields that carry a session id, in precedence order. The first one
     * present and non-empty wins. Default `['conversation', 'session_id']`.
     *
     * A runtime with its own spelling passes its own list — that is the seam a
     * hosting contract configures rather than forks this file for.
     */
    readonly sessionFields?: readonly string[];
    /** Body for the health probe. Default `{ status: 'ok' }`. */
    readonly health?: unknown;
}
type JsonObject = Readonly<Record<string, unknown>>;
/** The turn's text: a bare string, or the user message items that carry it. */
export declare function readResponsesInput(input: unknown): string;
/** The session this request claims, by whichever of its aliases it used. */
export declare function readResponsesSession(body: JsonObject, fields: readonly string[]): string | undefined;
/**
 * An `HttpWire` speaking the Responses protocol.
 *
 * Pair it with `httpHost` and the paths your deployment contract names. The
 * host keeps its own promises — draining, aborting on disconnect, failing a
 * handler that throws or answers nothing — and this supplies only the dialect.
 */
export declare function responsesWire(options?: ResponsesWireOptions): HttpWire;
export {};
//# sourceMappingURL=responsesWire.d.ts.map