@sema-agent/core/dist/agents/read-inbox-tool.d.ts

Stateless, task-oriented AI agent core

import { Type } from "typebox";
import type { PulledInbox } from "./peer-session-drain.js";
export declare const READ_INBOX_TOOL_NAME = "ReadInbox";
/** The most records one call may ask for (a bound on one tool result, not on the box). */
export declare const READ_INBOX_MAX_LIMIT = 50;
/**
 * #1036 — the tool's OWN page bound, in rendered characters. A record settles only when its frame is
 * present in this result as committed, so a result large enough for a size transformation to replace
 * with a head/tail preview would hand nothing over (the face declares `offload: false` for the same
 * reason, belt to this suspender — a deployment may set a global threshold below any default).
 * Records that do not fit stay in the box and are reported as still waiting, exactly as they are when
 * the per-pass count budget runs out; one oversized record is always handed over alone rather than
 * parked forever. Sized well under the smallest first-party offload floor.
 */
export declare const READ_INBOX_RESULT_BUDGET_CHARS = 20000;
export interface ReadInboxToolOptions {
    /** The bound drain's pull face, read LATE (the drain binds after the roster is minted). Absent ⇒ no box. */
    pull: () => ((limit?: number, toolCallId?: string, charBudget?: number) => Promise<PulledInbox>) | undefined;
    /**
     * The drain this face pulls from also covers the scope's PRINCIPAL INBOX, so a result
     * can carry another principal's words: the tool then declares `contentOrigin: "external"`, and the
     * engine's content-origin accounting fires on every call exactly as it does for a web fetch. Set from the
     * same consumer judgment that adds the drain's principal lane — never independently.
     */
    coversPrincipalInbox?: boolean;
}
export declare function createReadInboxTool(opts: ReadInboxToolOptions): import("../core/types.js").AgentTool<Type.TObject<{
    limit: Type.TOptional<Type.TInteger>;
}>, unknown>;