@qodo/sdk 0.13.4 → 2.0.0-next.0

package/dist/qar/payloads.js

@@ -0,0 +1,37 @@
+/**
+ * Per-`kind` payload shapes for the QAR envelope union — public surface.
+ *
+ * Backed by the codegen output in `./generated/envelope.ts`. The overlay
+ * sharpens the wire shape with three SDK-side projections that the JSON
+ * Schema cannot express:
+ *
+ *   - **Branded UUIDs.** `task_id`, `tool_call_id`, `since_message_id`, and
+ *     `offending_message_id` arrive from codegen as plain `string`. Each is
+ *     widened back to its branded type (`TaskId`, `ToolCallId`, `MessageId`)
+ *     so the compiler stops callers from mixing IDs at API boundaries.
+ *   - **`ToolResponseResult`.** The discriminated-union convenience accepted
+ *     by `client.tools.respond(node_name, response)`. The wire ships a flat
+ *     `status: 'ok' | 'error'` per-response item; the SDK union preserves
+ *     `success` / `error` / `denied` semantics, and the glue translates
+ *     between the two at send time (denied → `status: 'error'` with
+ *     `error.code: 'denied'`).
+ *   - **Parallel-batched tool envelope.** `tool.request` carries
+ *     `calls: ToolCall[]` (always a list, even for a single call — modern
+ *     LLM `parallel_tool_use`) and a required `node_name`; `tool.response`
+ *     carries `responses: ToolResponseItem[]` plus the same `node_name`.
+ *     The overlay here is the consumer-facing shape; while the QAR-side
+ *     schema bump is in flight, the codegen output in
+ *     `./generated/envelope.ts` still carries the pre-amendment single-call
+ *     shape — the overlay masks it. When `schemas/qar/.qar-version` is
+ *     bumped, re-running `npm run codegen:qar` collapses the overlay back
+ *     to a thin branded-id projection.
+ *
+ * QAR↔SDK name reconciliation: QAR's `task.start` envelope payload is
+ * `TaskStartPayload`; QAR's inner `task.start.input` shape is
+ * `QodoTaskStartPayload`. This module exports BOTH names — `TaskStartPayload`
+ * (QAR-native) and `QodoTaskStartPayload` (legacy alias) point at the same
+ * envelope-payload type; `QodoTaskStartInput` (legacy) and the QAR-native
+ * inner-payload type are the same.
+ */
+export {};
+//# sourceMappingURL=payloads.js.map

package/dist/qar/payloads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payloads.js","sourceRoot":"","sources":["../../src/qar/payloads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}

package/dist/qar/specs.d.ts

@@ -0,0 +1,604 @@
+/**
+ * Wire types for `task.start { agent: InlineAgentSpec }` (Pattern B) and
+ * `task.start { graph: InlineGraphSpec }` (Pattern C) — also accepted by
+ * `client.specs.validate(spec)` for pre-wire validation.
+ *
+ * **Naming.** The public symbol `AgentSpec` is owned by `QarRegistryClient`
+ * as the *local-registry* agent shape (simple `name` + `instructions` +
+ * tool strings). The `Inline*`-prefixed types here are the *wire* shape
+ * — what flows on the network to QAR's `task.start` and
+ * `POST /v1/specs/validate`. Two different layers, two different types,
+ * kept orthogonal so consumers writing local agents and consumers
+ * writing inline specs don't have to share a single struct trying to
+ * span both.
+ *
+ * Field names match QAR's wire vocabulary verbatim — `apiVersion`,
+ * `instructions` (not `system_prompt`), `tools: FunctionToolDef[]`
+ * (not `{ name }`-refs), `kind: 'AgentSpec'` (the discriminator the
+ * validator routes on; matches QAR's `SPEC_KIND_AGENT`).
+ *
+ * Rule-checking lives at QAR's `qar.specs.validator.validate_spec_payload`
+ * — single source of truth shared between `POST /v1/specs/validate` and
+ * `_handle_task_start`. Client-side, pre-wire
+ * `assertInlineAgentSpecPreWire` (see `TaskClient`) rejects the obvious
+ * forbidden-key cases at intake so the consumer's stack trace points at
+ * their call site instead of a `task.done(failed)` arriving over the
+ * wire.
+ */
+import type { JsonObject } from './json.js';
+/**
+ * MCP tool annotations — mirrors the upstream `Tool.annotations` shape from
+ * the MCP specification (https://modelcontextprotocol.io/docs/concepts/tools,
+ * checked 2026-05-21). Carried through the SDK's MCP projection layer so
+ * consumers writing dynamic filters (Shape C) and downstream observability
+ * (OTel span attrs) can read the upstream hints verbatim.
+ *
+ * **Annotations are explicitly UNTRUSTED per the MCP spec** — they're
+ * advisory hints from a third-party MCP server, not policy authority.
+ * QAR's trust-tier classification (whether a tool gates on HITL, whether
+ * write operations need confirmation) stays name-based on the consumer
+ * side. The QAR-side OTel span attribute pass-through carries them
+ * through to span attributes for observability tooling.
+ */
+export interface McpToolAnnotations {
+    /** Human-readable title — the upstream `Tool.annotations.title` field. */
+    readonly title?: string;
+    /** True if the tool only reads state; advisory hint for security-aware filters. */
+    readonly readOnlyHint?: boolean;
+    /** True if the tool may perform destructive operations; advisory. */
+    readonly destructiveHint?: boolean;
+    /** True if repeated invocations are safe; advisory. */
+    readonly idempotentHint?: boolean;
+    /** True if the tool interacts with an external/open world; advisory. */
+    readonly openWorldHint?: boolean;
+}
+/** OpenAI function-tool definition body. */
+export interface FunctionDef {
+    readonly name: string;
+    readonly description?: string;
+    /** JSON Schema for the call arguments. Free-form `JsonObject`. */
+    readonly parameters: JsonObject;
+    /** OpenAI strict-mode flag for argument validation. Defaults to true server-side. */
+    readonly strict?: boolean;
+    /**
+     * Upstream MCP `Tool.annotations` passed through verbatim by the MCP
+     * projection layer. Optional and advisory only — see {@link McpToolAnnotations}.
+     * Consumer-shipped `FunctionToolDef` entries may set this directly for
+     * non-MCP-backed tools that want to carry the same advisory hints.
+     */
+    readonly annotations?: McpToolAnnotations;
+}
+/** Wrapping discriminator for the OpenAI function-tool shape. */
+export interface FunctionToolDef {
+    readonly type: 'function';
+    readonly function: FunctionDef;
+}
+/**
+ * Read-only view of a single MCP-discovered tool, passed to a Shape C
+ * filter callback. Carries the upstream MCP `Tool` shape verbatim:
+ *
+ *   - `mcpName` — the registry name passed to `client.qar.registerMcp(name, ...)`
+ *   - `name` — the upstream tool name as returned by `tools/list`
+ *     (BEFORE the SDK's optional `<mcp>.<tool>` prefix)
+ *   - `description` — upstream description (may be overridden by
+ *     `mcpToolOverrides` at projection time)
+ *   - `inputSchema` — JSON Schema for the call arguments, verbatim
+ *   - `outputSchema` — optional JSON Schema for the structured output,
+ *     verbatim (added in MCP 2025-06-18; absent on older servers)
+ *   - `annotations` — see {@link McpToolAnnotations}
+ *
+ * Used by Shape C filter callbacks; consumers can read `annotations`
+ * (`readOnlyHint`, `destructiveHint`, etc.) to build security-aware tool
+ * surfaces without hand-maintaining a per-tool classification table.
+ */
+export interface DiscoveredMcpTool {
+    readonly mcpName: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: JsonObject;
+    readonly outputSchema?: JsonObject;
+    readonly annotations?: McpToolAnnotations;
+}
+/**
+ * Shape B — static allowlist + blocklist. Entries are either bare MCP
+ * names (matches every tool from that MCP) or `<mcp>.<tool>` dotted
+ * references (matches the specific tool). The effective surface is
+ * `union(allowlist) - blocklist`. An entry referencing an unregistered
+ * MCP, or a dotted name whose tool isn't in the live catalog, surfaces
+ * as a typed projection error at task.start.
+ */
+export interface McpToolsSelectorAllowBlock {
+    readonly allowlist?: readonly string[];
+    readonly blocklist?: readonly string[];
+}
+/**
+ * Shape C — dynamic filter callback. Receives every discovered tool
+ * across every registered MCP (per the pool's cached catalog) and
+ * returns `true` to include the tool in the projection. Useful for
+ * security-aware filtering off `annotations.readOnlyHint`, alphabetical
+ * subsetting, or any rule that needs richer logic than a string-list
+ * match.
+ *
+ * The callback runs once per tool per `tasks.start*` call — keep it pure.
+ */
+export type McpToolsSelectorFilter = (tool: DiscoveredMcpTool) => boolean;
+/**
+ * The `mcpTools` selector field. Discriminated union of three shapes:
+ *
+ *   - **Shape A** — `readonly string[]`. Entries are either MCP names
+ *     (whole-server inclusion) or `<mcp>.<tool>` dotted names (specific
+ *     tool). Matches the v1 SDK default ergonomic.
+ *   - **Shape B** — `McpToolsSelectorAllowBlock`. Allowlist + optional
+ *     blocklist, both using the same `<mcp>` / `<mcp>.<tool>` entry form.
+ *   - **Shape C** — `McpToolsSelectorFilter` callback for dynamic /
+ *     security-aware filtering.
+ *
+ * The shapes are mutually exclusive at the type level. Set `mcpTools` to
+ * one of the three; mixing allowlist + dynamic filter requires composing
+ * the callback yourself.
+ */
+export type McpToolsSelector = readonly string[] | McpToolsSelectorAllowBlock | McpToolsSelectorFilter;
+/**
+ * Per-tool description overlay applied after projection. Keys are tool
+ * names AS PROJECTED — including the `<mcp>.<tool>` prefix when the MCP
+ * is registered with `prefixToolNames: true` (default), or the bare tool
+ * name when prefix is opted out. Values override the discovered MCP
+ * `description` only; `inputSchema` / `outputSchema` / `annotations`
+ * remain MCP-authoritative.
+ *
+ * Unknown override keys (no matching projected tool) surface as a
+ * typed `QodoUnknownMcpToolError` at task.start.
+ */
+export interface McpToolOverride {
+    readonly description?: string;
+}
+export type McpToolOverrides = {
+    readonly [projectedToolName: string]: McpToolOverride;
+};
+export interface InstructionsPreset {
+    readonly preset: 'qodo-default';
+    readonly append?: string;
+}
+export type Instructions = string | InstructionsPreset;
+/**
+ * Inner shape of `output_schema.json_schema` and `deps_schema`. `strict`
+ * defaults to true server-side so the model's structured output gets
+ * OpenAI strict-mode validation.
+ */
+export interface JsonSchemaSpec {
+    readonly name: string;
+    readonly schema: JsonObject;
+    readonly strict?: boolean;
+}
+/** `output_schema` wrapper that carries the OpenAI strict-mode flag. */
+export interface OutputSchemaSpec {
+    readonly json_schema: JsonSchemaSpec;
+}
+/**
+ * A composed-skill reference. `vendor` defaults to `'qodo'` (canonical
+ * first-party namespace); `version` defaults to `'*'` (resolved at
+ * task.start via the deployment's lockfile).
+ */
+export interface SkillRef {
+    readonly vendor?: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly config?: JsonObject | null;
+}
+export interface SpawnableAgentRef {
+    readonly name: string;
+    readonly agent_id?: string | null;
+    readonly spec?: InlineAgentSpec | null;
+}
+export interface InlineAgentSpec {
+    readonly apiVersion: 'qar/v1';
+    /**
+     * The Pydantic discriminator QAR's `validate_spec_payload` routes on
+     * (`SPEC_KIND_AGENT = "AgentSpec"`). Optional in TypeScript so consumers
+     * can write `{ apiVersion, instructions, model }` literally and the SDK's
+     * pre-wire normalizer fills it in; the server-side validator requires
+     * the field, so an envelope crossing the wire always has it.
+     */
+    readonly kind?: 'AgentSpec';
+    readonly name?: string;
+    readonly instructions: Instructions;
+    readonly model: string;
+    readonly tools?: readonly FunctionToolDef[] | null;
+    readonly use_managed_tools?: boolean;
+    readonly excluded_tools?: readonly string[];
+    readonly output_schema?: OutputSchemaSpec | null;
+    readonly deps_schema?: JsonSchemaSpec | null;
+    readonly skills?: readonly SkillRef[];
+    readonly spawnable_agents?: readonly SpawnableAgentRef[];
+    /**
+     * Reserved by `D10-R1`. Rejected by the wire validator until the
+     * sandbox-execution ADR designs the runtime. Typing as literal `null`
+     * means the only value the TS compiler accepts is `null` itself, so a
+     * consumer who tries to attach `custom_code: { ... }` fails at compile
+     * time instead of getting a `task.done(failed)` round-trip.
+     */
+    readonly custom_code?: null;
+    /**
+     * Content-trust policy. Threads through to QAR's
+     * `AgentSpec.content_trust` and gates how untrusted content sources
+     * (tool outputs, HITL reasons, bulletin posts, evaluator rationale
+     * when this agent dispatches an evaluator) are wrapped before reaching
+     * the model. Absent/null = QAR-side defaults apply.
+     */
+    readonly content_trust?: ContentTrustPolicy | null;
+    /**
+     * Chat-mode primitive — mirror of QAR's
+     * `AgentSpec.auto_pause_on_turn_end`. When `true`, the runtime
+     * suspends the session on a synthetic `__auto_pause__` HITL after
+     * every successful agent turn so the next user message can resume
+     * the same session via `task.continue`. Default `false`. Field name
+     * is snake_case to match the existing SDK convention (every other
+     * AgentSpec field mirrors the Python wire spelling verbatim — see
+     * `hitl_default`, `use_managed_tools`, `content_trust`).
+     */
+    readonly auto_pause_on_turn_end?: boolean;
+    /**
+     * MCP tool auto-discovery selector. SDK-only field — the projection
+     * layer resolves this against the live `McpClientPool` catalog at
+     * `tasks.startWithAgent` / `tasks.startWithGraph` time and replaces it
+     * with the concrete `tools[]` shipped to QAR. Never crosses the wire as
+     * `mcpTools`; QAR sees the projected `tools[]` only.
+     *
+     * See {@link McpToolsSelector} for the three shapes (A whole-server, B
+     * allowlist/blocklist, C dynamic filter). Consumer-shipped `tools[]`
+     * entries continue to work and win on name collision with discovered
+     * tools — explicit > implicit.
+     */
+    readonly mcpTools?: McpToolsSelector;
+    /**
+     * Per-tool description overlay. SDK-only sibling field to
+     * `mcpTools` — applied AFTER projection so keys are tool names as
+     * projected (prefix-on or prefix-off depending on per-MCP
+     * `prefixToolNames`). Values override the discovered MCP `description`
+     * only; `inputSchema` / `outputSchema` / `annotations` remain
+     * MCP-authoritative. Stripped from the wire envelope alongside
+     * `mcpTools`. See {@link McpToolOverrides}.
+     */
+    readonly mcpToolOverrides?: McpToolOverrides;
+}
+/**
+ * Closed enum for a graph node's role in a `GraphSpec`.
+ *
+ * Widening this set (e.g. adding `router`, `peer`, `swarm`) requires bumping
+ * the wire `apiVersion` — the no-v0-planning rule binds the SDK to one role
+ * set per major version. Required on `InlineGraphAgent` (matches QAR's
+ * Pydantic shape, which has no default).
+ */
+export type InlineGraphRole = 'supervisor' | 'collaborator' | 'evaluator';
+/**
+ * Closed enum for a graph edge's dispatch kind.
+ *
+ * - `handoff` — control transfers: the producer hands off the task to the
+ *   target node and the supervisor resumes when the target completes.
+ * - `ai_tool` — the target appears in the producer's tool catalog as a
+ *   callable LLM-tool; results return as a tool response.
+ * - `evaluate` — the producer dispatches the target as an evaluator. The
+ *   target must have `role: 'evaluator'`; its response is bound to the
+ *   producer's `_verdicts[node]` state slot.
+ *
+ * Required on `InlineGraphEdge` (matches QAR's Pydantic shape; the field has
+ * no default).
+ */
+export type InlineGraphEdgeKind = 'handoff' | 'ai_tool' | 'evaluate';
+/**
+ * Trust mode for a piece of model-facing content. `'trusted'` means the
+ * content is passed verbatim to downstream prompts; `'untrusted'` means it
+ * is wrapped/sanitized per QAR's content-shielding protocol so injected
+ * instructions inside the content cannot exfiltrate authority. New values
+ * may be added by QAR without an SDK bump — the field is typed as the
+ * union below but the runtime validates against QAR's authoritative set.
+ */
+export type ContentTrustMode = 'trusted' | 'untrusted';
+/**
+ * Content-trust policy attached to an `AgentSpec` or
+ * `GraphSpec`. Field names match QAR's `ContentTrustPolicy` Pydantic
+ * model verbatim; the SDK does no normalization between this shape and
+ * the wire shape so the typed object posted by a consumer to
+ * `task.start { agent | graph, content_trust }` is what reaches QAR.
+ *
+ * **Policy fields** (every field is optional; absence = QAR-side default):
+ *
+ *   - `evaluator_rationale_policy` — trust mode applied to rationale text
+ *     emitted by evaluator-role nodes. Controls whether the
+ *     rationale is rendered verbatim to the supervisor's prompt context
+ *     or wrapped as untrusted content.
+ *   - `hitl_reason_policy` — trust mode applied to HITL resolution
+ *     `reason` strings. Consumers escalating untrusted user
+ *     input (chat operator, end-user resolution) should set this to
+ *     `'untrusted'`.
+ *   - `tool_output_policy` — trust mode applied to tool response
+ *     payloads stitched back into the model's context window. Default
+ *     QAR-side is `'untrusted'` for tools fetching external data and
+ *     `'trusted'` for in-process SDK tools.
+ *   - `bulletin_post_policy` — trust mode applied to bulletin findings
+ *     when forwarded into a supervisor's prompt.
+ *   - `max_untrusted_bytes` — byte cap applied to any single piece of
+ *     untrusted content before truncation. Default QAR-side. Use to
+ *     guard against prompt-injection payloads that try to bury
+ *     instructions in long content.
+ *   - `max_trusted_bytes` — byte cap on trusted content too (defense in
+ *     depth against runaway evaluator rationales). Optional.
+ */
+export interface ContentTrustPolicy {
+    readonly evaluator_rationale_policy?: ContentTrustMode | null;
+    readonly hitl_reason_policy?: ContentTrustMode | null;
+    readonly tool_output_policy?: ContentTrustMode | null;
+    readonly bulletin_post_policy?: ContentTrustMode | null;
+    readonly max_untrusted_bytes?: number | null;
+    readonly max_trusted_bytes?: number | null;
+}
+/**
+ * Agent / graph-node HITL mode. Mirrors QAR's `qar.protocol.hitl.HITLMode`
+ * string-enum verbatim:
+ *
+ *   - `'enabled'` — frame MAY auto-resolve in-process (subject to the
+ *     `Sensitivity.SECRET` bypass) or forward upward / to the consumer.
+ *   - `'passthrough'` — frame forwards every HITL envelope unchanged to its
+ *     ancestor; never auto-resolves.
+ *   - `'disabled'` — frame rejects any HITL surfaced at this boundary;
+ *     synthesized `hitl_resolved` closes the row. ADR-prescribed default —
+ *     headless automation is the dominant SDK use case.
+ *
+ * The wire spelling matches Python's `HITLMode` value strings exactly so the
+ * dispatch-side parse doesn't translate.
+ */
+export type InlineHITLMode = 'enabled' | 'passthrough' | 'disabled';
+/**
+ * Server-static reference inside a graph node's `spec`. Matches QAR's
+ * `qar.specs.models.GraphAgentStaticRef` — the only field is
+ * `agent_id`, a non-empty string that resolves against the deployment's
+ * static agent table. The discriminated-union arm for "this node is a
+ * pre-registered static agent, not an inline spec".
+ */
+export interface InlineGraphAgentStaticRef {
+    readonly agent_id: string;
+}
+/**
+ * One node in the graph. Matches QAR's `qar.specs.models.GraphAgent`:
+ *
+ *   - `spec` is the discriminated union the validator routes on — inline
+ *     `InlineAgentSpec` (kind `'AgentSpec'`), nested `InlineGraphSpec`
+ *     (kind `'GraphSpec'`, recursive subgraph), or
+ *     `InlineGraphAgentStaticRef` (`{ agent_id }`, server-side ref).
+ *     The wire validator narrows on `spec.kind` for the first two arms and
+ *     by the presence of `agent_id` for the static ref.
+ *   - `role` is required (no Pydantic default).
+ *   - `hitl` is optional and overrides the enclosing graph's
+ *     `hitl_default`. `null`/absent means "inherit from the graph default"
+ *     — a distinct semantic from "explicitly set to `'disabled'`".
+ *
+ * **The node name is the dict key in `InlineGraphSpec.agents`**, not a
+ * field on this type — QAR's Pydantic model is `dict[str, GraphAgent]`.
+ * Lifting the name out of the value lets dict key uniqueness enforce
+ * agent-name uniqueness for free (D11-R3) and gives `entry: <name>` a
+ * referential anchor.
+ */
+export interface InlineGraphAgent {
+    readonly spec: InlineAgentSpec | InlineGraphSpec | InlineGraphAgentStaticRef;
+    readonly role: InlineGraphRole;
+    readonly hitl?: InlineHITLMode | null;
+    /**
+     * Chat-mode primitive — per-node override for the graph's
+     * `auto_pause_on_turn_end_default`. `null` / absent means "inherit
+     * the graph default" (matching the `hitl` field's
+     * none-vs-disabled distinction). An explicit `false` opts the
+     * node OUT of chat-mode the graph turned on. Wire-facing
+     * auto-pause only applies to the entry supervisor's turn — see
+     * the chat-mode doc for the per-role semantics.
+     */
+    readonly auto_pause_on_turn_end?: boolean | null;
+}
+/**
+ * Discriminated `on_error` policy for an edge. Mirrors QAR's
+ * `EdgeOnErrorAbort | EdgeOnErrorRoute`:
+ *
+ *   - `{ abort: true }` — terminate the graph with the error.
+ *   - `{ route_to: <node> }` — route control to the named recovery node.
+ *
+ * Exactly one shape per object (Pydantic `extra='forbid'`).
+ */
+export type InlineEdgeOnError = {
+    readonly abort: true;
+} | {
+    readonly route_to: string;
+};
+/**
+ * A directed edge in the graph (spawn permission `from -> to`). Mirrors
+ * QAR's `Edge`. `kind` is required (no Pydantic default); `on_error` is
+ * optional and carries the same shape across all three edge kinds (no
+ * per-kind subclassing — see `Edge.__doc__` in QAR).
+ */
+export interface InlineGraphEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: InlineGraphEdgeKind;
+    readonly on_error?: InlineEdgeOnError | null;
+}
+/**
+ * Per-graph budget envelope. Mirrors QAR's `GraphBudget` — every field is
+ * required and must be `> 0` server-side. The SDK exposes the same shape so
+ * a consumer authoring a graph from TS picks the limits explicitly.
+ */
+export interface InlineGraphBudget {
+    readonly total_input_tokens: number;
+    readonly total_output_tokens: number;
+    readonly total_wall_clock_s: number;
+}
+/**
+ * Graph-wide limits. Mirrors QAR's `GraphLimits`. Pydantic side has defaults
+ * for every numeric field; the SDK type makes `limits` required on
+ * `InlineGraphSpec` so consumers think about the caps explicitly, but
+ * each individual sub-field stays optional so a consumer who only wants
+ * to override `max_steps` doesn't have to copy the other defaults
+ * verbatim.
+ *
+ * `max_depth` is the nesting cap. Pydantic enforces `ge=1`; the
+ * effective ceiling at dispatch time is `min(platform_cap, tenant_cap,
+ * spec_declared)` — the wire validator emits `D13-R2` when this value
+ * exceeds the deployment's effective cap.
+ */
+export interface InlineGraphLimits {
+    readonly max_steps?: number;
+    readonly max_depth?: number;
+    readonly per_agent_iterations?: number;
+    readonly budget?: InlineGraphBudget | null;
+}
+/**
+ * Per-dispatch
+ * budget envelope handed from an outer supervisor to a subgraph. Carried on
+ * the subgraph-dispatch tool-call's `args` under the reserved key
+ * `allocation`. Mirrors QAR's `SubgraphAllocation`.
+ *
+ * Every field is optional; omitted layers are auto-filled at dispatch time
+ * with `min(inner.declared, outer.remaining)`. The cross-layer comparison
+ * is rule `D13-R3` and runs server-side.
+ */
+export interface InlineSubgraphAllocation {
+    readonly input_tokens?: number | null;
+    readonly output_tokens?: number | null;
+    readonly wall_clock_s?: number | null;
+    readonly max_steps?: number | null;
+}
+/**
+ * Closed union of termination conditions. Mirrors QAR's `TerminationCondition`:
+ *
+ *   - `{ kind: 'agent_returns', agent: <name> }` — graph terminates when the
+ *     named agent returns.
+ *   - `{ kind: 'max_steps_reached' }` — graph terminates when `limits.max_steps`
+ *     is reached.
+ *   - `{ kind: 'error_uncaught' }` — graph terminates on an unhandled error.
+ *
+ * `kind` discriminates the three shapes at parse time. QAR's wire validator
+ * (`D11-R*`) checks the union exhaustively; the SDK's pre-wire validator
+ * does the obvious well-formedness checks.
+ */
+export type InlineTerminationCondition = {
+    readonly kind: 'agent_returns';
+    readonly agent: string;
+} | {
+    readonly kind: 'max_steps_reached';
+} | {
+    readonly kind: 'error_uncaught';
+};
+/**
+ * Inline-graph spec — multi-agent declarative topology. Mirrors QAR's
+ * `qar.specs.models.GraphSpec` verbatim.
+ *
+ * Wire-required fields per QAR's Pydantic model:
+ *   - `apiVersion: 'qar/v1'` — discriminator the validator routes on.
+ *   - `kind: 'GraphSpec'` — matches `SPEC_KIND_GRAPH`.
+ *   - `agents: Record<string, InlineGraphAgent>` — dict keyed by node name
+ *     (NOT an array; the dict key gives agent names referential integrity
+ *     against `entry: <name>` and edge `from`/`to` fields).
+ *   - `entry: string` — name of the entry node (must be a key of `agents`).
+ *   - `termination: InlineTerminationCondition[]` — non-empty list of
+ *     termination conditions.
+ *
+ * SDK-required (TS-side opinion):
+ *   - `limits: InlineGraphLimits` — wire-side this has a Pydantic
+ *     `default_factory=GraphLimits`, but the SDK forces consumers to be
+ *     explicit. Passing `{}` accepts every default.
+ *
+ * Optional fields (with Pydantic-side defaults):
+ *   - `name`, `output_schema`, `deps_schema`, `hitl_default`,
+ *     `parent_close_policy` (reserved-and-rejected — must be `null`;
+ *     wire validator emits `D13-R5` on any non-null).
+ *   - `edges: InlineGraphEdge[]` — defaults to `[]` on the QAR side.
+ */
+export interface InlineGraphSpec {
+    readonly apiVersion: 'qar/v1';
+    readonly kind: 'GraphSpec';
+    readonly name?: string | null;
+    readonly agents: Readonly<Record<string, InlineGraphAgent>>;
+    readonly edges?: readonly InlineGraphEdge[];
+    readonly entry: string;
+    readonly limits: InlineGraphLimits;
+    readonly termination: readonly InlineTerminationCondition[];
+    readonly output_schema?: OutputSchemaSpec | null;
+    readonly deps_schema?: JsonSchemaSpec | null;
+    /** Graph-wide default HITL mode applied to nodes whose own `hitl` is unset. */
+    readonly hitl_default?: InlineHITLMode;
+    /**
+     * Chat-mode primitive — graph-wide default for
+     * `InlineGraphAgent.auto_pause_on_turn_end`. A node whose own
+     * field is `null`/absent inherits this value; an explicit
+     * per-node `true`/`false` wins. Default `false` matches the
+     * ADR-prescribed "headless is default" stance. Threads through to
+     * QAR's `GraphSpec.auto_pause_on_turn_end_default`.
+     */
+    readonly auto_pause_on_turn_end_default?: boolean;
+    /**
+     * Reserved-and-rejected — must be `null`. Typed as literal `null` so
+     * the only value the TS compiler accepts is `null` itself; QAR's wire
+     * validator emits `D13-R5` on any non-null. Mirrors AgentSpec's
+     * `custom_code`.
+     */
+    readonly parent_close_policy?: null;
+    /**
+     * Content-trust policy. Graph-wide defaults applied to inline agents
+     * that don't declare their own `content_trust`. Threads through to
+     * QAR's `GraphSpec.content_trust`. Absent/null = QAR-side defaults
+     * apply.
+     */
+    readonly content_trust?: ContentTrustPolicy | null;
+}
+/**
+ * Per-agent verdict shape returned by evaluator-role nodes. Mirrors QAR
+ * QAR's Pydantic `VerdictResult` (and the LLM-as-judge patterns in
+ * RAGAS / OpenAI Evals):
+ *
+ *   - `verdict` — closed three-arm enum. The supervisor's next turn branches
+ *     on this discriminator.
+ *   - `confidence` — optional scalar in `[0, 1]`. QAR's Pydantic model
+ *     enforces the range with `ge=0, le=1`; the SDK matches that for
+ *     pre-flight rejection (`D11-R12`).
+ *   - `rationale` — optional free-form explanation. Surfaced verbatim to
+ *     the supervisor's prompt context.
+ *   - `[k: string]: unknown` — RAGAS-style additional scores (e.g.
+ *     `faithfulness`, `answer_relevancy`). QAR's Pydantic model uses
+ *     `extra="allow"`; the SDK mirrors that with the open index signature.
+ *
+ * Bound at runtime to the producer's `_verdicts[node]` state slot — see
+ * QAR's `dispatch_evaluator` runtime.
+ */
+export interface VerdictResult {
+    readonly verdict: 'pass' | 'fail' | 'needs_revision';
+    readonly confidence?: number;
+    readonly rationale?: string;
+    readonly [k: string]: unknown;
+}
+/** Discriminated union accepted by `client.specs.validate`. */
+export type InlineSpec = InlineAgentSpec | InlineGraphSpec;
+/**
+ * Discriminator literal — the value of `kind` on each branch.
+ * Matches QAR's `SPEC_KIND_AGENT` / `SPEC_KIND_GRAPH` exactly.
+ */
+export type InlineSpecKind = 'AgentSpec' | 'GraphSpec';
+/**
+ * Per-rule validation failure. Mirrors QAR's response shape. `rule_id` is
+ * one of the `D10-R*` set, the `D11-R*` set, or a small set of
+ * surface-rejection ids (`D10-UNSUPPORTED`, `D10-UNSUPPORTED-SPAWN`); `path`
+ * is a JSON Pointer (RFC 6901) into the spec, with `""` denoting the root.
+ */
+export interface SpecValidationError {
+    readonly rule_id: string;
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Result envelope returned by `client.specs.validate`. Discriminated on
+ * `valid` so consumers can branch directly on `result.valid` (no extra
+ * type guard needed) — the `errors` array only exists on the `false` arm.
+ */
+export type SpecValidateResult = {
+    readonly valid: true;
+} | {
+    readonly valid: false;
+    readonly errors: readonly SpecValidationError[];
+};
+//# sourceMappingURL=specs.d.ts.map

package/dist/qar/specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs.d.ts","sourceRoot":"","sources":["../../src/qar/specs.ts"],"names":[],"mappings":"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"}