import { BaseReport } from "../contracts/result/base-report.type.mjs";

//#region ../ai/src/utils/run-context.d.ts
/**
 * The ambient run frame an executable reads when it finishes building
 * its report. When present, a child execution (an `agent.execute()`,
 * `workflow.execute()`, `supervisor.execute()` call) auto-attaches its
 * report to `sink` and inherits the frame's `rootRunId` / `sessionId`
 * lineage — so reports nest under the enclosing run with NO manual id
 * threading by the dev.
 *
 * Installed by orchestration primitives (supervisor / orchestrator /
 * team) around the synchronous + async body of an intent's callback,
 * so any agent the callback invokes directly — `agent.execute(...)`
 * rather than `ctx.run(...)` — still lands in the trace tree.
 */
type RunFrame = {
  /**
   * The `children[]` array of the enclosing report node. A child
   * execution pushes its assembled report here on completion.
   */
  sink: BaseReport[];
  /**
   * The outermost run-id this subtree belongs to. Propagated onto the
   * child report's `rootRunId` so flat-row consumers group it with the
   * enclosing run.
   */
  rootRunId: string;
  /**
   * Run-id of the enclosing node (the immediate parent of any child
   * captured through this frame). Stamped onto the child's
   * `parentRunId`.
   */
  parentRunId: string;
  /**
   * Session identifier propagated onto the captured child's subtree.
   * `undefined` when the enclosing run had none.
   */
  sessionId?: string;
};
/**
 * Run `fn` with `frame` installed as the ambient {@link RunFrame} for
 * the entire async subtree it spawns. Restores the previous frame (or
 * none) when `fn` settles. Returns whatever `fn` returns.
 *
 * Nesting is natural: a callback that itself dispatches a nested
 * supervisor installs a fresh frame for the inner run, and the inner
 * frame shadows the outer one for the inner subtree only — exactly the
 * tree shape the report models.
 */
declare function withRunFrame<T>(frame: RunFrame, fn: () => T): T;
/**
 * Run `fn` with NO ambient {@link RunFrame} installed for its async
 * subtree, restoring the previous frame when `fn` settles. Used by the
 * supervisor's EXPLICIT capture paths (`ctx.run(...)` /
 * `ctx.intents.X.execute()`) — those already push the child report onto
 * the callback's `children[]` themselves, so the child must NOT also
 * self-capture via the ambient frame (which would double-count it).
 */
declare function withoutRunFrame<T>(fn: () => T): T;
/**
 * Read the current ambient {@link RunFrame}, or `undefined` when no
 * orchestration callback is on the stack. An executable calls this at
 * report-build time: a present frame means "you were invoked inside a
 * callback — attach yourself to its tree".
 */
declare function currentRunFrame(): RunFrame | undefined;
/**
 * Capture a freshly-built child `report` onto the current ambient
 * {@link RunFrame} when one is installed. Pushes the report onto the
 * frame's `sink` so it nests under the enclosing node, and rewrites the
 * report's lineage (`rootRunId`, `parentRunId`, `sessionId`) to the
 * frame's — mirroring how `step.agent` / `ctx.run` capture child
 * reports explicitly, but driven ambiently.
 *
 * No-op (returns `false`) when no frame is installed — a standalone
 * `agent.execute()` keeps its self-root untouched. Returns `true` when
 * the report was captured so the caller can suppress its own terminal
 * lineage stamp if needed.
 *
 * The lineage rewrite is intentionally shallow on the root + deep on
 * descendants would double-stamp; callers pass the already-lineage-
 * stamped subtree (self-root), and this relinks only the root's
 * `rootRunId` / `parentRunId` / `sessionId`. Descendants already carry
 * the child's own self-root as their `rootRunId`; the enclosing
 * primitive's terminal `stampReportLineage` pass (run once on the
 * outer tree) rewrites the whole subtree to the true outer root. This
 * keeps capture cheap and defers the single authoritative relink to
 * the outer build.
 */
declare function captureChildReport(report: BaseReport): boolean;
//#endregion
export { RunFrame, captureChildReport, currentRunFrame, withRunFrame, withoutRunFrame };
//# sourceMappingURL=run-context.d.mts.map