{"version":3,"file":"base-report.type.mjs","names":[],"sources":["../../../../../../../../ai/src/contracts/result/base-report.type.ts"],"sourcesContent":["import type { AIError } from \"../../errors/ai-error\";\nimport type { AttemptEntry } from \"./attempt-entry.type\";\nimport type { Usage } from \"./usage.type\";\n\n/**\n * Wire-format version stamped on every root `BaseReport`. Bumped only\n * when we make a BREAKING change to the report shape (field removed,\n * required-ness flipped, semantics changed). Additive changes (new\n * optional fields) do not bump.\n *\n * Panoptic and other downstream consumers branch on this to parse\n * old stored reports with their original-shape rules.\n *\n * Current: **1** — initial Panoptic-readiness shape.\n */\nexport const REPORT_SCHEMA_VERSION = 1;\n\n/**\n * Discriminator for the kind of executable that produced a given\n * {@link BaseReport}. Forms a closed union so consumers can narrow on\n * the tree without string-matching on `name`.\n */\nexport type ReportType =\n  | \"tool\"\n  | \"callback\"\n  | \"agent\"\n  | \"workflow\"\n  | \"supervisor\"\n  | \"team\"\n  | \"orchestrator\"\n  | \"batch\"\n  | \"planner\"\n  | \"image\"\n  | \"speech\"\n  | \"transcription\"\n  | \"video\"\n  | \"realtime\";\n\n/**\n * Terminal status every executable primitive reports. Unified across\n * tools, agents, workflows, and supervisors so dashboards and\n * generic traversal helpers don't special-case per primitive.\n *\n * - `\"completed\"` — ran to natural end with a usable result.\n * - `\"failed\"` — aborted mid-run or finished without a usable result\n *   (crash, schema failure, max-trips, etc.). The\n *   accompanying `error` on the envelope carries the typed cause.\n * - `\"cancelled\"` — caller aborted before completion via `AbortSignal`.\n * - `\"max-iterations\"` — supervisor-specific termination when the\n *   iteration cap was hit without an explicit `END` / `satisfied`.\n *   Harmless on non-supervisor reports; keeping it on the shared\n *   union lets consumers write one `switch` for every status.\n * - `\"awaiting-input\"` — orchestrator-specific NON-terminal status: the\n *   session is paused waiting for the next user turn (§15.6). The only\n *   non-terminal member of this union; consumers branching on\n *   `status === \"completed\"` must treat it as a session-continues path,\n *   not a failure. Harmless on non-orchestrator reports.\n * - `\"awaiting-approval\"` — planner-specific NON-terminal status: a\n *   `mode: \"plan-only\"` run generated and validated a plan but executed\n *   nothing, pending sign-off (the plan rides on `result.plan`). Mirrors\n *   `\"awaiting-input\"` at the plan boundary. Harmless on non-planner\n *   reports.\n */\nexport type ReportStatus =\n  | \"completed\"\n  | \"failed\"\n  | \"cancelled\"\n  | \"max-iterations\"\n  | \"awaiting-input\"\n  | \"awaiting-approval\";\n\n/**\n * Universal execution report shared by every primitive. Per-primitive\n * report types extend this with their own domain-specific fields\n * (agent trips, workflow steps, supervisor iteration snapshots) while\n * keeping the root fields identical. Recursion happens through\n * {@link BaseReport.children} — any executable this node invoked\n * contributes its own full report here, producing a walkable tree of\n * the entire run.\n *\n * **Usage rollup.** `usage` at every node equals this node's own cost\n * plus the sum of each child's `usage`. Leaves (tools) contribute\n * zero own-cost; composites contribute their direct LLM spend only,\n * with children covering everything delegated.\n *\n * @example\n * function totalCost(report: BaseReport): number {\n *   return report.usage.total;\n * }\n *\n * function walk(report: BaseReport, depth = 0): void {\n *   console.log(`${\"  \".repeat(depth)}${report.type} \"${report.name}\" — ${report.status}`);\n *   for (const child of report.children) walk(child, depth + 1);\n * }\n */\nexport type BaseReport = {\n  /** Stable id for this execution node. Generated per `execute()`/`invoke()` call. */\n  runId: string;\n  /**\n   * Run-id of the immediate parent execution node, when this node was\n   * invoked as part of a larger run (e.g. a tool dispatched by an\n   * agent; an agent dispatched by a supervisor; an inner primitive\n   * wrapped via `asTool()`). Absent on root nodes.\n   *\n   * Lets Panoptic and other flat-row consumers reconstruct the tree\n   * without traversing `children[]` in memory.\n   */\n  parentRunId?: string;\n  /**\n   * Run-id of the top-level execution this node belongs to. Equals\n   * `runId` on the root node, and is propagated downward to every\n   * descendant. Used to slice flat report tables back into per-run\n   * groupings.\n   */\n  rootRunId: string;\n  /** Executable identity — the tool/agent/workflow/supervisor name. */\n  name: string;\n  /**\n   * Dev-curated version string mirrored from the primitive's config\n   * (`AgentConfig.version`, `ToolConfig.version`, etc.). Free-form —\n   * the framework neither parses nor compares it. Stored verbatim on\n   * every report so trip-archive queries can distinguish runs of\n   * \"agent X v2.1\" from \"agent X v2.2\" even when name + signature\n   * are identical.\n   *\n   * Stays `undefined` when the dev didn't declare one — never\n   * auto-defaulted.\n   */\n  version?: string;\n  /**\n   * Caller-supplied identifier that groups multiple `.execute()` calls\n   * into one conceptual user session / request. Propagated to every\n   * descendant report node so flat queries (\"total spend for session\n   * X today\") work without joining the tree.\n   *\n   * Threaded from `execute()` options on every primitive. Optional —\n   * absent when the caller didn't supply one.\n   */\n  sessionId?: string;\n  /** Discriminator for the kind of executable that produced this report. */\n  type: ReportType;\n  /** Terminal status of this execution. */\n  status: ReportStatus;\n  /**\n   * Terminal error stamped on a `failed` / `cancelled` node so the typed\n   * cause travels WITH the report tree — not only on the result envelope.\n   * Essential for the observe path: an {@link import(\"../../observe/observer.contract\").Observer}\n   * receives `collect(report)` with no envelope, so a failed root would\n   * otherwise expose `status` with no error type/message. Child tool nodes\n   * already carry their error this way (`ToolCall.error`); root primitives\n   * (agent / workflow / supervisor / orchestrator / planner) stamp it here\n   * too. Absent on a `completed` node. Panoptic normalizes it to a JSON-safe\n   * span error during projection — the raw `AIError` never has to serialize.\n   */\n  error?: AIError;\n  /** ISO-8601 wall-clock timestamp when execution began. */\n  startedAt: string;\n  /** ISO-8601 wall-clock timestamp when execution finished. */\n  endedAt: string;\n  /** Monotonic duration in milliseconds — `performance.now()` delta. */\n  duration: number;\n  /** Rolled-up usage: own cost + sum of `children[].usage`. */\n  usage: Usage;\n  /**\n   * Reports of every executable invoked by this node, in invocation\n   * order. Empty for leaves (pure tools) and for executables that\n   * didn't delegate work.\n   */\n  children: BaseReport[];\n  /**\n   * Retry history when middleware (or, for workflow steps, the engine\n   * itself) retried this node before it either succeeded or gave up.\n   * Absent when zero retries happened — keeps the common-case payload\n   * lean. The surviving (final) attempt is NOT duplicated here; its\n   * outcome is the report's own `status` / timing.\n   */\n  attempts?: AttemptEntry[];\n  /**\n   * Wire-format version of this report shape. Only present on root\n   * report nodes — implies the same version for the whole tree.\n   * Panoptic / archive consumers branch on this to parse old reports\n   * with their original-shape rules.\n   *\n   * Always equals {@link REPORT_SCHEMA_VERSION} at write time.\n   */\n  reportSchemaVersion?: number;\n};\n"],"mappings":";;;;;;;;;;;;AAeA,MAAa,wBAAwB"}