/** * delegation-contract.ts — evidence-bound request and outcome envelopes. * * Delegation is a semantic boundary, not merely a fresh context window. These * compact contracts preserve the parent question, the observations that made * the work necessary, and the proof the parent needs back. They are deliberately * dependency-free so every spawn surface (in-process, subprocess, explorer, * planner, and handoff) can use the same wire shape without a package cycle. */ export type DelegationKind = "subagent" | "exploration" | "plan" | "decomposition" | "feature" | "recovery" | "handoff"; export type EvidenceFreshness = "fresh" | "stale" | "unknown"; export interface DelegationEvidence { /** Stable label the generator may cite; never an instruction channel. */ ref: string; detail: string; freshness?: EvidenceFreshness; } /** * A concrete, parent-owned todo/workboard leaf. This is intentionally a data * capsule rather than a transcript: a worker receives the current bounded * contract, while the parent retains authority to accept its result. */ export interface DelegationWorkItem { cardId: string; title: string; taskEpoch?: number; todoIds?: string[]; ownedFiles?: string[]; verifierCommand?: string; evidenceRequirements?: string[]; expectedArtifacts?: string[]; } export interface DelegationBrief { schemaVersion: 1; kind: DelegationKind; /** The exact question or bounded work the child must answer. */ request: string; /** Why this child is needed at this point in the parent trajectory. */ whyNow: string; /** Bounded observations supporting the request. */ evidence: DelegationEvidence[]; /** What territory is owned and what is explicitly out of scope. */ scope: string; /** The evidence-bearing result shape the child must return. */ returnContract: string; /** The decision/action this result should unlock for the parent. */ parentUnblock: string; /** Present only for a uniquely identified active todo/workboard leaf. */ workItem?: DelegationWorkItem; /** Optional original child task, retained as reference rather than the brief's thesis. */ originalTask?: string; /** True only when a bounded tool-less grounding pass refined this brief. */ groundingSource: "model" | "deterministic"; groundingEvidenceRefs: string[]; } export interface DelegationBriefInput { kind: DelegationKind; task: string; currentIntent?: string; whyNow?: string; scope?: string; returnContract?: string; parentUnblock?: string; evidence?: DelegationEvidence[]; workItem?: DelegationWorkItem; } export interface GeneratedDelegationBrief { request: string; whyNow?: string; scope?: string; returnContract?: string; parentUnblock?: string; evidenceRefs: string[]; } export interface DelegationOutcome { schemaVersion: 1; status: "completed" | "partial" | "blocked" | "failed" | "unknown"; summary: string; evidence: string[]; files: string[]; verification: string[]; blockers: string[]; recommendedNextAction: string; confidence: "high" | "medium" | "low"; acceptedFindingIds: string[]; receiptIds: string[]; source: "declared" | "derived"; } export declare function sanitizeDelegationText(value: unknown, max?: number): string; export declare function buildDelegationBrief(input: DelegationBriefInput): DelegationBrief; /** Render the model-facing child request. Safe to include inside another prompt. */ export declare function renderDelegationBrief(brief: DelegationBrief, maxChars?: number): string; /** Prompt for the optional bounded model pass that refines a deterministic brief. */ export declare function buildDelegationBriefGroundingPrompt(brief: DelegationBrief): string; /** Parse a bounded model refinement. Null is a safe deterministic fallback. */ export declare function parseGeneratedDelegationBrief(raw: unknown, fallback: DelegationBrief): GeneratedDelegationBrief | null; export declare function mergeGeneratedDelegationBrief(fallback: DelegationBrief, generated: GeneratedDelegationBrief | null | undefined): DelegationBrief; /** Instruction appended to every worker's fold-back contract. */ export declare function delegationOutcomeInstruction(): string; /** Parse a worker's declared outcome, falling back to a conservative evidence extract. */ export declare function parseDelegationOutcome(raw: unknown): DelegationOutcome; export declare function renderDelegationOutcome(outcome: DelegationOutcome, maxChars?: number): string;