/**
 * A mountable fetch router for the persistent-agent HTTP surface.
 *
 * Harness serves agents from its own runtimes (`fh dev`, the Node artifact,
 * the Cloudflare worker). This router covers the other direction: an
 * application that already owns an HTTP surface and wants Harness agents on it,
 * under its own paths, behind its own middleware.
 *
 * The router owns routing, method dispatch, request parsing, response shape,
 * and status codes — everything a client observes. A {@link FabricAgentRouterBackend}
 * owns durable submission, conversation reads, and lifecycle. That split is
 * what lets one definition of the wire contract serve hosts whose storage and
 * execution differ.
 *
 * Runtime-neutral: only `Request`, `Response`, `URL`, and plain objects. It runs
 * on Node, Cloudflare, Deno, Bun, or any fetch-capable host.
 */
import type { DeliveredMessage } from "./delivered-message.js";
/** Identity of one addressed conversation. */
export interface FabricAgentAddress {
    agent: string;
    instanceId: string;
    session: string;
}
export interface FabricAgentAdmission extends FabricAgentAddress {
    message: DeliveredMessage;
    initialData?: unknown;
    uid?: string | null;
    /** Tenant from `x-fabric-tenant`, when the host forwards one. */
    tenantId?: string;
}
export interface FabricAgentAdmissionResult {
    submissionId: string;
    /**
     * Stream position captured before admission. Reading from it returns this
     * delivery and the reply. Never substitute `"0"`: that re-reads the whole
     * conversation on every send.
     */
    offset: string;
    uid?: string;
    acceptedAt?: string;
}
export interface FabricAgentConversationPage {
    incarnation: string | null;
    batches: Array<{
        offset: string;
        records: unknown[];
    }>;
    nextOffset: string;
    upToDate: boolean;
}
export interface FabricAgentSubmissionStatus {
    submissionId: string;
    status: string;
    uid?: string;
    outcome?: string;
    result?: string;
    error?: string;
    answeredBySubmissionId?: string;
}
export interface FabricAgentDeletion {
    deleted: boolean;
    aborted?: boolean;
}
/**
 * The host-specific half of the router.
 *
 * Every method may throw; the router maps a thrown error to `500` with a
 * generic body rather than leaking host internals to the caller.
 */
export interface FabricAgentRouterBackend {
    /**
     * Whether the named agent exists and may be served over HTTP. Returning
     * `exposed: false` produces the same `404` as an unknown agent, so probing
     * cannot distinguish a private agent from a missing one.
     */
    resolveAgent(name: string): Promise<{
        found: boolean;
        exposed?: boolean;
    }>;
    admit(input: FabricAgentAdmission): Promise<FabricAgentAdmissionResult>;
    readConversation(address: FabricAgentAddress & {
        offset: string;
        limit: number;
    }): Promise<FabricAgentConversationPage>;
    getSubmission(address: FabricAgentAddress & {
        submissionId: string;
    }): Promise<FabricAgentSubmissionStatus | undefined>;
    abort(address: FabricAgentAddress): Promise<boolean>;
    /** Instance state for `GET`, or `undefined` when the instance does not exist. */
    loadInstance?(address: FabricAgentAddress): Promise<unknown | undefined>;
    deleteInstance?(address: FabricAgentAddress): Promise<FabricAgentDeletion>;
    /** Live updates over SSE. Hosts without one omit it and the route 404s. */
    streamUpdates?(address: FabricAgentAddress & {
        offset: string;
    }, request: Request): Promise<Response>;
    /** Per-instance schedules, where the host supports them. */
    handleSchedules?(address: FabricAgentAddress, request: Request): Promise<Response | undefined>;
}
export interface FabricAgentRouterOptions {
    /**
     * Path prefix this router is mounted under, e.g. `/api`. Stripped before
     * matching, so the router works at any mount point without the backend
     * knowing where it lives.
     */
    basePath?: string;
    /** Largest `limit` a conversation read may request. Defaults to 1000. */
    maxReadLimit?: number;
}
export interface FabricAgentRouter {
    /** Always returns a `Response`, 404-ing paths outside the agent surface. */
    fetch(request: Request): Promise<Response>;
    /**
     * Returns `undefined` for paths outside the agent surface, so a host can
     * fall through to its own routes.
     */
    handle(request: Request): Promise<Response | undefined>;
}
/**
 * Mount the persistent-agent HTTP surface on any fetch-capable host.
 *
 * ```ts
 * const router = createFabricAgentRouter(backend, { basePath: '/api' });
 * app.all('/api/agents/*', (c) => router.fetch(c.req.raw));
 * ```
 */
export declare function createFabricAgentRouter(backend: FabricAgentRouterBackend, options?: FabricAgentRouterOptions): FabricAgentRouter;
//# sourceMappingURL=agent-router.d.ts.map