@sema-agent/core/dist/core/runner/prepare-listings.d.ts

Stateless, task-oriented AI agent core

/**
 * PrepareTask's LISTINGS phase: the per-task agent definitions' tool-name audit
 * (deny entries fail loud, allow entries advise), the agent-listing announce face read off the
 * delegation tool's roster (with its deferred / excluded / removal-to-zero arms), the two listing
 * opt-out advisories, the announced-listings mirror seeded from the once-per-session ledger, the
 * deferred roster's ToolSearch ride, and the date_change seam. The body is the driver's stretch moved
 * verbatim; the interface is the dependency list it had implicitly.
 *
 * SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await, so the phase adds no yield between
 * the disclosure mount before it and the context-lane seats after it (a stretch
 * with no await is extracted as a sync function — an `async` wrapper would open a microtask window).
 *
 * Throws pass through unchanged: `config.agent.unknown_tool` (a deny entry naming a tool this
 * deployment does not mount — a typo there would silently guard nothing).
 */
import type { AgentTool } from "../../internal/harness.js";
import type { TaskSpec } from "../types.js";
import type { AnnounceOnceSink, DateAnchorRead, Prepared, PrepareResume, ToolFaceSnapshot } from "./contracts.js";
import type { AnnouncedListingSnapshot } from "../../internal/harness.js";
import type { ResolvedSkillListingBudget } from "../skill-listing-budget.js";
export interface PrepareListingsInput {
    /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `agents` (the audit's subject), `tools`
     *  (the roster-bearing delegation tool, by its `agentListing` marker), `sessionId` (continuation
     *  ⇒ seeded/removal projections), `attachments` (the two opt-outs). Never mutated. */
    spec: Pick<TaskSpec, "agents" | "tools" | "sessionId" | "attachments">;
    /** borrowed-readonly — the FULLY ASSEMBLED mount array (names + aliases = the audit's universe).
     *  Read only; this phase never mutates the roster. */
    tools: ReadonlyArray<AgentTool>;
    /** borrowed-readonly — the once-per-session ledger: its deduplicated operator sink (`onError`) and
     *  the whole announced snapshot (`arms()`) the mirror is seeded from. */
    onceLedger: AnnounceOnceSink & {
        arms(): AnnouncedListingSnapshot;
    };
    /** borrowed-readonly — the acquired session's id (operator-line context). */
    sessionId: string;
    /** borrowed-readonly — the frozen tool face: `exclude` / `defer` decide the roster face's arm. */
    toolFaceSnapshot: Pick<ToolFaceSnapshot, "exclude" | "defer">;
    /** borrowed-readonly — the activated deferred names as of prepare (transcript replay / checkpoint
     *  seed); only `has()` is read: an already-ACTIVE roster tool un-defers its listing face. The set
     *  keeps mutating mid-run (ToolSearch activations) — this phase reads it once, here. */
    activeTools: ReadonlySet<string>;
    /** borrowed-readonly — the durable-resume carrier: presence (seedAnnounced) and
     *  `seed.announcedListings.agents` (the removal-to-zero projection's gate). */
    resume: Pick<PrepareResume, "seed"> | undefined;
    /** borrowed-readonly — the project-context phase's skills-listing projection; read only for the
     *  skills opt-out advisory (entries.length). */
    skillsListing: Prepared["skillsListing"];
    /** borrowed-readonly — the listing family's resolved budget; the agent roster frames fold into it. */
    listingBudget: ResolvedSkillListingBudget;
    /** borrowed-mutable — the deferred roster's ToolSearch RIDE seat (declared by the disclosure
     *  mount, read at activation time through `listingRideRef.current?.(newly)`). Written here, once,
     *  on a deferred roster face; no later writer. Identity is the contract (the mount's closures read
     *  this exact cell). */
    listingRideRef: {
        current?: (newly: readonly string[]) => string | undefined;
    };
    /** borrowed-readonly — the prompt assembly's date re-renderer; presence alone decides whether the
     *  date_change seam exists (a provider that owns the whole prompt has none). */
    renderWithDate: ((date: string) => string) | undefined;
    /** borrowed-readonly — the environment facts; only `date` is read (the leg's frozen date). */
    envFacts: {
        readonly date?: string;
    };
    /** borrowed-readonly — whether the client zone validated (the seam re-judges "today" in it). */
    tzValid: boolean;
    /** borrowed-readonly — the client's declared zone (used only when `tzValid`). */
    userTz: string | undefined;
    /** borrowed-readonly — the session's date anchor as the prompt-inputs phase read it (rides the seam). */
    dateAnchor: DateAnchorRead | undefined;
}
export interface PrepareListingsResult {
    /** owned — the agent-listing announce projection (`Prepared.agentListing`): the roster off the
     *  delegation tool's effective face, the removal-to-zero projection, or undefined (silent). */
    agentListing: Prepared["agentListing"];
    /** owned — the announced-listings mirror seeded from the ledger's whole snapshot
     *  (`Prepared.announcedListingsRef`); the run loop and the checkpoint serializer write it from here on. */
    announcedListingsRef: Prepared["announcedListingsRef"];
    /** owned — the date_change seam (`Prepared.dateChange`), or undefined when the prompt has no date re-renderer. */
    dateChange: Prepared["dateChange"];
}
/** The M15 phase body — prepareTask's listings stretch, verbatim (see the module header). */
export declare function prepareListings(input: PrepareListingsInput): PrepareListingsResult;