@sema-agent/core/dist/fixtures/index.d.ts

Stateless, task-oriented AI agent core

/**
 * `@sema-agent/core/fixtures` — GOLDEN SHAPE fixtures for downstream consumers (server/SDK/cli),
 * the L2 layer of the anti-drift defense: downstream tests consume THESE shapes instead of
 * hand-building requests/frames, so an upstream shape change breaks a test instead of shipping a
 * silent mismatch (the "bare req = false-green pins" class).
 *
 * CONTRACT — shape truth, not value truth:
 *  - Every volatile value is NORMALIZED to an angle-bracket placeholder (`"<issuing-session-id>"`,
 *    `"<tool-call-id>"`, …). Downstream asserts KEY SETS and SHAPES (optionality, nesting, enum
 *    membership), never placeholder values.
 *  - Each fixture is PINNED against the live engine by test/fixtures-golden.test.ts: the pin runs
 *    the real code path (a real gate, a real delegated child), captures the real object, applies
 *    the same normalization, and requires deep equality with the fixture. A shape change upstream
 *    turns THAT pin red first — the fixture can never drift from the engine.
 *  - Additions here are additive API: removing/renaming a fixture key is a downstream-visible
 *    BREAKING change and belongs in the release notes' frame-shape section.
 */
import type { AskRequest } from "../core/tool-policy.js";
/** The normalization placeholders used across all fixtures (downstream may match on the form). */
export declare const FIXTURE_PLACEHOLDER_RE: RegExp;
/**
 * AskRequest, HOST form — the shape a live `onAsk` approver receives when the HOST task's own
 * gate raises a permission ask. Key facts downstream must not re-derive by guessing:
 *  - `sourceTaskId` is PRESENT on host asks too (always the issuing task's session id) — it is
 *    NOT a subagent discriminator;
 *  - `fromSubagent` / `sourceAgentName` are ABSENT on host asks (design/153 §1: `fromSubagent`
 *    is THE discriminator);
 *  - `principal` is absent unless the deployment sets TaskSpec.principal.
 */
export declare const ASK_REQUEST_HOST: AskRequest;
/**
 * AskRequest, DELEGATED-SUBAGENT form — the shape the approver receives when a delegated child's
 * gate raises the ask (bubbled through the inherited chain or the child's own caller slot):
 *  - `fromSubagent: true` — the explicit, unforgeable discriminator (1.378);
 *  - `sourceAgentName` — display identity (UNTRUSTED-for-display; redact + bound before render);
 *    present only when the spawn named the child (an unnamed child omits it);
 *  - `sourceTaskId` — the CHILD's session id (≠ the host's);
 *  - `isDelegatedChild: true` — the refusal-POSTURE fact (the raw trusted internals fact, set by
 *    every core spawn leg — a FORK carries it too, its interaction contract being one-shot). NOT a
 *    synonym for `fromSubagent` (`parentTaskId` presence): a directly-started workflow's children
 *    carry this one WITHOUT `fromSubagent`. Downstream must not fold the two into one flag.
 */
export declare const ASK_REQUEST_SUBAGENT: AskRequest;
/**
 * AskRequest, DIRECTLY-STARTED WORKFLOW CHILD form — the shape when a workflow with NO launching
 * tool call (e.g. cron-triggered) spawns an agent whose gate raises the ask. THE form that keeps
 * `isDelegatedChild` and `fromSubagent` from being conflated downstream:
 *  - `isDelegatedChild: true` — refusals speak the child posture to it;
 *  - `fromSubagent` ABSENT — there is no nameable `parentTaskId` and no id is ever fabricated;
 *  - `sourceAgentName` — the workflow spawn's display label.
 * A consumer that requires the two flags together, or classifies by `fromSubagent` alone, misreads
 * exactly this request.
 */
export declare const ASK_REQUEST_WORKFLOW_CHILD: AskRequest;
/** All AskRequest forms, keyed for iteration in downstream key-set diff gates. */
export declare const ASK_REQUEST_FIXTURES: {
    readonly host: AskRequest;
    readonly subagent: AskRequest;
    readonly workflowChild: AskRequest;
};