@exellix/ai-tasks 7.8.0

package/dist/types/task-types.d.ts

@@ -0,0 +1,887 @@
+import type { RunSkillRequest, RunSkillResponse, ModelConfig, SmartInputConfig, SmartInputRenderOptions } from "@exellix/ai-skills";
+import type { SmartInputRenderResult } from "@x12i/rendrix";
+export type { SmartInputRenderResult };
+import type { WebScoperConfig } from "@exellix/narrix-web-scoper";
+import type { NarrixRunInput } from "../narrix/types.js";
+import type { PostCoreTaskStrategyKey, TaskStrategyKey } from "../task-strategies/canonicalTaskStrategies.js";
+import type { InputStrategyKey } from "../task-strategies/canonicalInputExecutionStrategies.js";
+import type { NarrixModeKey } from "../task-strategies/canonicalNarrixModes.js";
+import type { TaskStrategyItemData } from "../task-strategies/types.js";
+import type { LlmCallConfig, LlmCallObservation } from "./llmCall.js";
+/**
+ * @deprecated Use `narrixMode: "handler"` with `narrixInput` instead of any legacy “narrix-then-direct” execution label.
+ */
+export declare const NARRIX_THEN_DIRECT: "narrix-then-direct";
+/** Step type for PRE step: synthesize context before main task. */
+export declare const SYNTHESIZED_CONTEXT: "synthesized-context";
+/** Phase of a step in the execution pipeline. */
+export type ExecutionPhase = "pre" | "main" | "post";
+/** One step in the execution pipeline. */
+export interface ExecutionStep {
+    phase: ExecutionPhase;
+    type: string;
+    config?: SynthesisConfig | AuditConfig | PolishConfig;
+}
+/** One check in the audit gateway (must or should). */
+export interface AuditCheck {
+    /** Human-readable description of what to check. */
+    check: string;
+    /** Relative weight for scoring. Higher = more impact on weighted score. */
+    weight: number;
+}
+/** Result for a single check from the audit LLM (parsed from Flex-MD or fallback). */
+export interface AuditCheckResult {
+    check: string;
+    kind: "must" | "should";
+    passed: boolean;
+    feedback: string;
+}
+/** Logical shape of audit LLM output (parsed from structured markdown). */
+export interface AuditLLMOutput {
+    checks: AuditCheckResult[];
+    overallFeedback: string;
+}
+/** Full runtime audit result including computed weighted score. */
+export interface AuditResult {
+    checks: AuditCheckResult[];
+    overallFeedback: string;
+    weightedScore: number;
+}
+/** Config for the audit POST step. */
+export interface AuditConfig {
+    gateway: {
+        must: AuditCheck[];
+        should: AuditCheck[];
+    };
+    threshold?: number;
+    minCycles?: number;
+    maxCycles?: number;
+    /** How to pick or combine audit candidates after the core task. Keys match `CANONICAL_POST_CORE_TASK_STRATEGIES` / Catalox `ai-task-strategies-post`. */
+    selectionStrategy?: PostCoreTaskStrategyKey;
+    auditModelConfig?: ModelConfig;
+    synthesisModelConfig?: ModelConfig;
+    customAuditGuidelines?: string;
+    customSynthesisGuidelines?: string;
+    fallbackToBest?: boolean;
+    auditTimeoutMs?: number;
+    /**
+     * Per-role {@link LlmCallConfig} (model / maxTokensCap / temperature / topP / outputExpectation / timeoutMs / maxOutputLength).
+     * Forwarded to xynthesis `executeXynthesisAction` for the audit evaluator and synthesis-merge calls. Resolution
+     * order at the call site: `llmCall.<role>.X` → step env (e.g. `AUDIT_*`) → shared `POST_STEP_*` env → fallback.
+     */
+    llmCall?: {
+        audit?: LlmCallConfig;
+        synthesis?: LlmCallConfig;
+    };
+}
+/** Metadata attached to response.metadata.postSteps.audit after audit POST step. */
+export interface AuditPostStepMetadata {
+    totalCycles: number;
+    candidateScores: number[];
+    selectedCycleIndex: number;
+    allMustPassed: boolean;
+    synthesisUsed: boolean;
+    auditResults: AuditResult[];
+    durationMs: number;
+    /**
+     * Trace-mode-only: ordered list of `LlmCallObservation` for every audit-evaluator and synthesis-merge call
+     * the post-step performed. Includes failures (e.g. silent merge fallbacks) so callers can see what was asked,
+     * what was used, and why it failed. Omitted outside trace mode.
+     */
+    llmCalls?: LlmCallObservation[];
+}
+/** One item in the polish checklist. */
+export interface PolishChecklistItem {
+    instruction: string;
+    priority: "high" | "medium" | "low";
+}
+/** Config for the polish POST step. */
+export interface PolishConfig {
+    checklist: PolishChecklistItem[];
+    maxPasses?: number;
+    modelConfig?: ModelConfig;
+    customGuidelines?: string;
+    includeOriginalContext?: boolean;
+    timeoutMs?: number;
+    /**
+     * {@link LlmCallConfig} (model / maxTokensCap / temperature / topP / outputExpectation / timeoutMs / maxOutputLength)
+     * for the polish LLM call. Forwarded to xynthesis `executeXynthesisAction`. Resolution order at the call site:
+     * `llmCall.X` → step env (`POLISH_*`) → shared `POST_STEP_*` env → fallback.
+     */
+    llmCall?: LlmCallConfig;
+}
+/** Polish LLM output (JSON). */
+export interface PolishLLMOutput {
+    polishedOutput: string;
+    changeNotes: {
+        instruction: string;
+        action: "changed" | "no-change";
+        note: string;
+    }[];
+}
+/** Metadata attached to response.metadata.postSteps.polish after polish POST step. */
+export interface PolishPostStepMetadata {
+    totalPasses: number;
+    changeNotes: PolishLLMOutput["changeNotes"][];
+    durationMs: number;
+    /**
+     * Trace-mode-only: ordered list of `LlmCallObservation` for every polish pass call.
+     * Includes failures so callers can see what was asked / used / why it failed. Omitted outside trace mode.
+     */
+    llmCalls?: LlmCallObservation[];
+}
+/**
+ * When POST steps run, response.metadata may be extended with postSteps.
+ * Attached at runtime in task-sdk; RunTaskResponse aliases RunSkillResponse from ai-skills.
+ */
+export interface RunTaskResponsePostStepsMetadata {
+    audit?: AuditPostStepMetadata;
+    polish?: PolishPostStepMetadata;
+}
+/**
+ * AI scoping failure (per-item) surfaced in `response.metadata.aiScopingFailures` (trace mode only).
+ * Carries the originating instruction location and the upstream typed error so callers can read
+ * `error.invokeSummary` / `error.observation` without losing the rich payload.
+ */
+export interface AiScopingFailureRecord {
+    /** Index into `request.aiScoping[]`. */
+    index: number;
+    /** Same as `instruction.targetToken`. */
+    targetToken: string;
+    /** Same as `instruction.source`. */
+    source: string;
+    error: {
+        name: string;
+        message: string;
+        /** When the upstream threw `XynthesisInvokeError` / `XynthesisResponseParseError`, carries `invokeSummary`. */
+        invokeSummary?: import("./llmCall.js").InvokeAttemptSummary;
+        /** When wrapped with `LlmCallContextError`, carries the structured observation. */
+        observation?: LlmCallObservation;
+    };
+}
+/**
+ * Trace-mode-only top-level task response metadata extensions. Attached at runtime in `task-sdk` /
+ * post-steps; never appended outside trace mode (lean payload).
+ */
+export interface RunTaskResponseTraceMetadata {
+    /** Per-item `LlmCallObservation` for every PRE synthesis call (markdown / question-driven / structured). */
+    synthesizedContextLlmCalls?: LlmCallObservation[];
+    /** Per-item `LlmCallObservation` for every AI scoping call (success + failure). */
+    aiScopingLlmCalls?: LlmCallObservation[];
+    /** Per-item failure record for AI scoping items that did not complete successfully. */
+    aiScopingFailures?: AiScopingFailureRecord[];
+}
+/**
+ * What feeds the synthesis PRE step: Narrix markdown, web evidence markdown, and/or memory JSON.
+ * Legacy: `narrix-only` / `narrix+memory` are aliases for `narrix-web` / `narrix-web-memory`.
+ * `auto`: narrix-web-memory if Narrix output exists; else memory-web if web scoping hit; else memory-only.
+ */
+export type ContextSourcePolicy = "auto" | "narrix-only" | "narrix+memory" | "memory-only" | "narrix-web" | "narrix-web-memory" | "memory-web";
+/** Options for serializing `executionMemory.webContext` into synthesis source material. */
+export type WebEvidenceConfig = {
+    /** Prefer cleaned text over raw HTML in excerpts. Default true. */
+    preferCleanContent?: boolean;
+    /** Max sources after URL dedupe. Default 5. */
+    maxSources?: number;
+    /** Dedupe by normalized URL (first wins). Default true. */
+    dedupeByUrl?: boolean;
+    /** Hard cap on markdown size (Unicode code units). */
+    maxTotalChars?: number;
+};
+export type SynthesisMode = "markdown" | "structured";
+/**
+ * Job-scoped, task-scoped, and execution-scoped synthesized material for graph execution
+ * (logically separate from raw memories).
+ */
+export type XynthesizedMemory = {
+    job?: Record<string, unknown>;
+    task?: Record<string, unknown>;
+    /** Run-wide execution bucket (distinct from job and per-node task scopes). */
+    execution?: Record<string, unknown>;
+};
+export type { SmartInputConfig, SmartInputRenderOptions };
+/**
+ * Rendrix-native {@link SmartInputConfig} or wire form with `paths` (string[] or `{ title, path, required? }[]`)
+ * and optional `strict` (forwarded to gateway / Rendrix after normalization).
+ */
+export type RunTaskSmartInput = SmartInputConfig | {
+    paths: string[] | SmartInputConfig["paths"];
+    strict?: boolean;
+};
+export type XynthesizedDestinationScope = "job" | "task" | "execution";
+/** Optional PRE synthesis destination for graph-mergeable xynthesized memory. */
+export type XynthesizedOutputConfig = {
+    destination: XynthesizedDestinationScope;
+    outputKey: string;
+    mode?: "replace" | "merge";
+    /**
+     * When false, skip persisting to executionMemory.synthesizedContext / synthesizedInput for this PRE step.
+     * When omitted or true, preserve legacy MAIN context persistence.
+     */
+    alsoWriteLegacySynthesizedContext?: boolean;
+};
+/** Keys match `CANONICAL_PRE_CORE_TASK_STRATEGIES` and Catalox catalog `ai-task-strategies-pre`. */
+export type { TaskStrategyKey as SynthesisInputStrategy } from "../task-strategies/canonicalTaskStrategies.js";
+export type { PostCoreTaskStrategyKey } from "../task-strategies/canonicalTaskStrategies.js";
+export type TaskCore = "question" | "action" | "plan" | "objective" | "decision" | "comparison" | "classification" | "evaluation" | "analysis" | "summary" | "generation" | "extraction";
+export declare const TASK_CORES: readonly ["question", "action", "plan", "objective", "decision", "comparison", "classification", "evaluation", "analysis", "summary", "generation", "extraction"];
+/**
+ * Config for the synthesized-context PRE step (step.config when type is "synthesized-context").
+ */
+export interface SynthesisConfig {
+    modelConfig?: ModelConfig;
+    contextSourcePolicy?: ContextSourcePolicy;
+    /**
+     * Controls what raw input is provided to the synthesizer.
+     * - `policy` (default): use contextSourcePolicy + narrix/web/memory composition.
+     * - `execution-memory-only`: synthesize from executionMemory only.
+     * - `job-memory-only`: synthesize from jobMemory only.
+     * - `task-memory-only`: synthesize from taskMemory only.
+     * - `full-memory-bundle`: synthesize from {jobMemory, taskMemory, executionMemory}.
+     */
+    synthesisInputStrategy?: TaskStrategyKey;
+    autoEnableContext?: boolean;
+    synthesisPromptOverride?: string;
+    timeoutMs?: number;
+    maxOutputLength?: number;
+    memoryPaths?: string[];
+    customSynthesizingGuidelines?: string;
+    /** When true, on synthesis failure run main step without synthesized context. Default false. */
+    fallbackToDirect?: boolean;
+    /** Controls web excerpt markdown when web scoping is present (synthesis source material). */
+    webEvidence?: WebEvidenceConfig;
+    /**
+     * `markdown` (default): free-form synthesized context.
+     * `structured`: model returns JSON matching SynthesizedPromptPayload; main context via buildSynthesizedContextMarkdown.
+     */
+    synthesisMode?: SynthesisMode;
+    /**
+     * Dot-path into `request.input` for the task question (structured mode / explicit question field). Default `question`.
+     */
+    questionPath?: string;
+    /**
+     * Override question resolution for structured synthesis. Takes precedence over questionPath when it returns a non-empty string.
+     */
+    getQuestion?: (request: RunTaskRequest) => string | undefined;
+    /** Max synthesized items per side (local/supporting) after validation. Default 50. */
+    structuredMaxItemsPerSide?: number;
+    /** Max characters per item content. Default 8000. */
+    structuredMaxItemContentChars?: number;
+    /**
+     * Structured mode only: enable best-effort recovery when the provider returns non-JSON (or JSON wrapped in prose/markdown)
+     * and strict response normalization fails upstream. Default true.
+     */
+    structuredRepair?: boolean;
+    /**
+     * Structured mode only: max number of repair retries after a normalization failure. Default 1.
+     * A retry re-asks with a minimal "return ONLY valid JSON object" instruction.
+     */
+    structuredRepairMaxRetries?: number;
+    /** Structured mode only: max chars of raw output included in error diagnostics. Default 4000. */
+    structuredDiagnosticsMaxChars?: number;
+    /**
+     * When true, synthesize answers for multiple explicit questions and store them under
+     * executionMemory.synthesizedContext as a structured artifact (mode: "questionDriven").
+     * Backward compatible: when omitted/false, behavior is unchanged.
+     */
+    questionDriven?: boolean;
+    /**
+     * Questions to answer in question-driven mode. Each question can restrict which inputs are allowed:
+     * - record: only record-derived input (executionMemory.input.raw)
+     * - web: only web-derived input (executionMemory.webContext)
+     * - both: combine both when available
+     */
+    questions?: Array<{
+        id: string;
+        question: string;
+        source?: "record" | "web" | "both";
+    }>;
+    /**
+     * When true, if `request.executionMemory.synthesizedContext` is already a non-null object with a usable
+     * `contextMarkdown` string (or question-driven artifact including `contextMarkdown`), skip the PRE synthesis
+     * LLM call and reuse the cached artifact. Opt-in only; callers are responsible for cache validity.
+     */
+    reuseCachedSynthesizedContext?: boolean;
+    /**
+     * {@link LlmCallConfig} (model / maxTokensCap / temperature / topP / outputExpectation / timeoutMs / maxOutputLength)
+     * for the PRE synthesis LLM call (markdown / question-driven / structured branches). Forwarded to xynthesis
+     * `executeXynthesisAction` / `runStructuredSynthesisGatewayCallRobust`. Resolution order at the call site:
+     * `llmCall.X` → existing field on this config (e.g. `modelConfig.X`, `timeoutMs`, `maxOutputLength`) → env → fallback.
+     */
+    llmCall?: LlmCallConfig;
+    /** When set, write synthesis output under request.xynthesized.job|task|execution[outputKey] and return xynthesizedPatch. */
+    xynthesizedOutput?: XynthesizedOutputConfig;
+}
+/**
+ * One entry in taskMemory.narrix — output of a single Narrix run (possibly filtered by narrixScope).
+ */
+export type TaskMemoryNarrixEntry = {
+    entity: {
+        entityKind: string;
+        entityKey: string;
+    };
+    signals: unknown[];
+    stories: unknown[];
+    meta: Record<string, unknown>;
+};
+/**
+ * Filters which signals and stories from Narrix output are written into task memory.
+ * When includeSignals is set, only signals whose code is in the array are kept; excludeSignals is ignored.
+ * Same for includeStories / excludeStories with narrativeTypeId. When neither include nor exclude is set for a dimension, all pass through.
+ */
+export interface NarrixScope {
+    includeSignals?: string[];
+    excludeSignals?: string[];
+    includeStories?: string[];
+    excludeStories?: string[];
+}
+/**
+ * One explicit web search question for `@exellix/narrix-web-scoper` question-pack mode
+ * (`scopeQuestionPack`). Used when `webScopeTemplates` is unset.
+ */
+export interface NarrixWebScopeQuestion {
+    id?: string;
+    question: string;
+    source?: "manual" | "ai-driven";
+}
+/**
+ * Task-level NARRIX pre-processor config (e.g. from graph node `taskConfiguration.narrix`).
+ * When present, ai-tasks runs the NARRIX enrichment pipeline before the task and injects
+ * the result into executionMemory (and optionally jobMemory) so the handler can use it.
+ * Defaults: attachToField = "_narrix", deterministicSort = true.
+ * engineConfigPath / packsRoot are reserved for future use when runner supports them.
+ */
+export interface NarrixPreProcessorConfig {
+    datasetId: string;
+    /** Reserved for future use when @exellix/narrix-runner supports loading from path. */
+    engineConfigPath?: string;
+    /** Reserved for future use when packs can be loaded from a path. */
+    packsRoot?: string;
+    /** Field name on executionMemory for the _narrix attachment; default "_narrix". */
+    attachToField?: string;
+    /** Default true. */
+    deterministicSort?: boolean;
+    /** Reserved for future use when runner exposes an API. */
+    assumptionsPolicy?: {
+        allowAssumptions?: boolean;
+        requireAssumptionMarking?: boolean;
+        requireEvidenceForAssumptions?: boolean;
+    };
+    /**
+     * When true, run @exellix/narrix-web-scoper after CNI is built and inject the result into
+     * executionMemory.webContext. Requires TAVILY_API_KEY env. On failure, logs and continues
+     * with only NARRIX narrative (lenient fallback). Default false.
+     */
+    enableWebScope?: boolean;
+    /**
+     * When true with `enableWebScope`, skip the internal web-scoper if `executionMemory.webContextMarkdown` is a
+     * non-empty string (caller already supplied web markdown). Narrix narrative still runs.
+     */
+    skipWebScopeWhenExternalWebMarkdownPresent?: boolean;
+    /**
+     * When set (non-empty), passed to the web-scoper as `webScopeTemplates` and replaces normal query planning.
+     * Tokens use athenix-parser syntax (same as `@exellix/narrix-web-scoper`). Takes precedence over enriched `question`.
+     */
+    webScopeTemplates?: string[];
+    /**
+     * Optional Handlebars template for the search `question` when `webScopeTemplates` is not set.
+     * Rendered with context from CNI knownFacts, entity, `input.question`, plus `input` (full task input).
+     */
+    webScopeQuestionTemplate?: string;
+    /**
+     * Merged on top of auto-built template context when using `webScopeTemplates` (caller overrides).
+     */
+    webScopeObjects?: Record<string, unknown>;
+    /**
+     * Non-empty after normalization: run `scopeQuestionPack` with these questions instead of
+     * `scopeGeneric` / single `question` planning. Ignored when `webScopeTemplates` is non-empty.
+     */
+    webScopeQuestions?: NarrixWebScopeQuestion[];
+    /**
+     * Per-request web-scoper retrieval options (same shape as `WebScoperConfig.scoping` in
+     * `@exellix/narrix-web-scoper`): snippets, caps, raw body, max queries, freshness, etc.
+     * Forwarded when building the scoper for this call so defaults stay backward compatible.
+     */
+    webScoping?: WebScoperConfig["scoping"];
+}
+/**
+ * Execution-level memory type.
+ *
+ * Contains history of execution context (e.g., execution state, intermediate results,
+ * execution-level variables) that persists across execution attempts or retries.
+ */
+export type ExecutionHistory = Record<string, any>;
+/** Structured synthesis fills `templateCores` and validated `payload`; markdown synthesis uses `[]` and `payload.kind === "markdown-synthesis"`. */
+export type SynthesizedContextArtifact = {
+    templateCores: TaskCore[];
+    question: string;
+    mode: SynthesisMode;
+    payload: unknown;
+    contextMarkdown: string;
+};
+export type QuestionDrivenSynthesizedContext = {
+    mode: "questionDriven";
+    /** Same markdown fed to MAIN as synthesized context; set for persistence and `reuseCachedSynthesizedContext`. */
+    contextMarkdown?: string;
+    record?: Record<string, unknown>;
+    web?: Record<string, unknown>;
+    answers?: Record<string, {
+        question: string;
+        source: "record" | "web" | "both";
+        synthesis: string;
+        evidence?: {
+            recordPaths?: string[];
+            webScopeIds?: string[];
+            sources?: Array<{
+                url?: string;
+                title?: string;
+            }>;
+        };
+    }>;
+};
+/** Union for executionMemory.synthesizedContext. */
+export type AnySynthesizedContextArtifact = SynthesizedContextArtifact | QuestionDrivenSynthesizedContext;
+/**
+ * Material resolved for the synthesis PRE step (persistence / debugging). Stored at `executionMemory.synthesizedInput`.
+ * Large `sourceMaterial` may be truncated per `SYNTHESIZED_INPUT_MAX_CHARS` (default 200_000).
+ */
+export type SynthesizedInputArtifact = {
+    synthesisMode: SynthesisMode | "questionDriven";
+    sourceMaterial: string;
+    localMarkdown?: string;
+    supportingMarkdown?: string;
+    question?: string;
+    templateCores?: TaskCore[];
+    truncated?: boolean;
+};
+/**
+ * One instruction for AI scoping: which memory path to read and how to scope it.
+ * Used in RunTaskRequest.aiScoping.
+ */
+export type AIScopingInstruction = {
+    /** Dot-path to memory value (e.g. jobMemory.customerProfile, taskMemory.previousFindings). */
+    source: string;
+    /** Natural-language instructions for the internal scoping AI call. */
+    instructions: string;
+    /** Label for the scoped result; appears as aiScoped[].token. */
+    targetToken: string;
+    /**
+     * Optional per-instruction {@link LlmCallConfig} (overrides `RunTaskRequest.aiScopingOptions.llmCall`).
+     * Forwarded to the internal scoping AI call (`runScopingCall`).
+     */
+    llmCall?: LlmCallConfig;
+};
+/**
+ * One scoped result from an AI scoping call.
+ * Injected into main task input as input.aiScoped[].
+ */
+export type AIScopedItem = {
+    token: string;
+    scopedInfo: string;
+};
+/** Array of scoped results; injected into main task input as input.aiScoped. */
+export type AIScoped = AIScopedItem[];
+/** Phase relative to the MAIN gateway skill (`runSkill`) invocation. */
+export type ExecutionStrategyPhase = "before" | "after";
+/** Wrapper strategies implemented around MAIN (catalog rows `planner` / `optimizer`). */
+export type ExecutionStrategyWrapperKey = "planner" | "optimizer";
+/**
+ * One configured wrapper around MAIN: FuncX planner (once before MAIN) or optimizer (evaluates after each MAIN attempt).
+ * Sort within each phase by ascending `priority`; ties preserve request order.
+ */
+export interface ExecutionStrategyInvocation {
+    strategyKey: ExecutionStrategyWrapperKey;
+    phase: ExecutionStrategyPhase;
+    priority: number;
+    /** Optimizer only: max MAIN attempts when unsatisfied (minimum 1). Omitted uses env / package default. */
+    maxIterations?: number;
+    /** Per-invocation knobs (e.g. `functionId` override for FuncX). */
+    args?: Record<string, unknown>;
+}
+/**
+ * One step in a combined/multi-step task execution.
+ * Used when a task (or skill) runs multiple logical steps in one invocation
+ * (e.g. "to-cni + enrich + triage") so consumers can inspect and report the chain
+ * without extra round-trips.
+ */
+export interface IntermediateStep {
+    /** 1-based order in the execution chain. */
+    step: number;
+    /** Stable identifier for the step (e.g. "to-cni", "engine-enrich", "triage-q1-q6"). */
+    id: string;
+    /** Whether this step completed successfully. */
+    ok: boolean;
+    /** Optional short summary (e.g. "cni built", "enriched", "answers Q1,Q6"). */
+    summary?: string;
+    /** Optional error message when ok is false. */
+    error?: string;
+    /** Optional summary input (e.g. keys/ids) for reporting. */
+    inputSummary?: Record<string, unknown> | string;
+    /** Optional excerpt of step output for debugging; keep small to avoid payload bloat. */
+    outputExcerpt?: Record<string, unknown>;
+    /**
+     * Trace-mode-only: structured `LlmCallObservation` for this step (model / token resolution / usage / cost / error).
+     * Populated for failed audit-cycle / polish-pass steps so consumers see the request snapshot + upstream
+     * `invokeSummary` / `diagnostics` without inspecting the thrown error.
+     */
+    observation?: LlmCallObservation;
+}
+/** Optional list of intermediate steps, in execution order. */
+export type IntermediateSteps = IntermediateStep[];
+/**
+ * Task execution request for `WorexClientTasks.runTask()`.
+ *
+ * Extends `RunSkillRequest` with pipeline, NARRIX, synthesis, and related fields. `skillId` is omitted;
+ * `coreSkillId`, `graphId`, `nodeId`, and `prevNodeId` remain for graph execution and activity tracking.
+ *
+ * **Upstream-required correlation ids:** `agentId`, `jobTypeId`, and `taskTypeId` are **required** (same as `RunSkillRequest`).
+ * `runTask()` validates them at runtime; omitting them throws before execution.
+ *
+ * **Template variables (graph-engine 5.13+):** On MAIN, `variables` is the **job/graph bucket** only (forwarded as-is;
+ * same as `executionMemory.jobVariables`). Node scope lives on `executionMemory.taskVariables`. `input`, `xynthesized`,
+ * and `smartInput` are separate top-level fields — not folded into `variables`. Optional host merge:
+ * `mergeSkillTemplateVariables` (not used on default `runTask` MAIN).
+ *
+ * **Model:** `modelConfig` is forwarded on the request to the skills layer and gateway unchanged (per-invocation
+ * overrides for provider, model name, temperature, and other `ModelConfig` fields).
+ *
+ * **taskMemory:** May include `narrix` entries after the structured Narrix handler runs.
+ *
+ * **Wire contract:** Matches `documenations/schemas/v1/run-task-request.json` (closed object; no root `question`, `inputs`, `jobInput`, or `executionType`).
+ *
+ * **Graph task nodes:** Authoring may use `id`, `type`, `metadata`, `jobContextMapping`, `outputMapping`, and duplicate `inputs` labels — compile those into this interface before `runTask`. Mapping specs (`jobContextMapping`, `outputMapping`) are runtime-only. Only fields on this type (plus allowed `RunSkillRequest` fields such as `templateTokens` / `templateRenderOptions`) are valid. Split authoring `metadata` into the typed properties below (`narrixMode`, `inputStrategyKey`, `executionStrategies`, pipeline, scoping, validation, etc.).
+ */
+export interface RunTaskRequest extends Omit<RunSkillRequest, "skillId" | "jobId" | "taskId" | "executionType" | "smartInput"> {
+    /**
+     * Execution mode for task diagnostics behavior.
+     *
+     * - default: return the normal task response only.
+     * - trace: return the normal task response plus an authoritative ordered debug trace.
+     */
+    executionMode?: "default" | "trace";
+    /**
+     * Job correlation for skills gateway / logs. When omitted, `WorexClientTasks.runTask` assigns a UUID before
+     * invoking `@exellix/ai-skills` (required there on each request).
+     */
+    jobId?: string;
+    /**
+     * Task instance id (also used as Activix correlation when enabled). When omitted, `runTask` assigns a UUID.
+     */
+    taskId?: string;
+    /**
+     * Optional identity envelope for this task instance.
+     *
+     * This is treated as an opaque JSON object and is preserved through execution.
+     * Runtime may enrich it per-run (e.g. taskId, skillId) and attach it to downstream
+     * activity/phase tracking.
+     */
+    identity?: Record<string, unknown>;
+    /**
+     * Execution pipeline: array of steps (pre → main → post). When omitted, MAIN direct execution is implied.
+     */
+    executionPipeline?: ExecutionStep[];
+    /**
+     * Whether and which Narrix path runs at the **start** of `runTask` (before local tasks and pipeline PRE).
+     * Canonical keys match Catalox `ai-task-narrix-modes`. When omitted, inferred from `narrix` / `narrixInput`
+     * (see `resolveRunTaskRuntimeKnobs`).
+     */
+    narrixMode?: NarrixModeKey | (string & {});
+    /**
+     * Optional **authoring / UX / template-hint** metadata (e.g. for consoles or Xynthesis templates).
+     * Does **not** select Narrix invocation (`narrixMode`) and does **not** decide what slices PRE receives by default
+     * (PRE gets the full available context bundle; see product D6).
+     * Canonical keys match Catalox `ai-task-input-strategies`. Omitted: defaults to `no-narrative` (not inferred from Narrix wiring).
+     */
+    inputStrategyKey?: InputStrategyKey | (string & {});
+    /**
+     * **Required.** Wrappers around MAIN (`runSkill`): planners run once each before the first MAIN attempt (sorted by `priority`);
+     * optimizers run after each MAIN attempt — the first optimizer after sort drives the retry loop. Use `[]` for plain MAIN (no FuncX wrappers).
+     */
+    executionStrategies: ExecutionStrategyInvocation[];
+    /**
+     * Optional catalog item metadata from preferred catalog `execution-strategy`.
+     * Runtime uses only safe allowlisted fields after normal code validation passes; malformed or conflicting rows are ignored.
+     */
+    executionStrategyCatalogItems?: TaskStrategyItemData[];
+    /**
+     * Execution-scoped memory. Graph-engine mirrors template variables here as **`jobVariables`** (whole run) and
+     * **`taskVariables`** (current node). Forwarded unchanged; ai-tasks does not flatten buckets into `variables`.
+     */
+    executionMemory?: ExecutionHistory;
+    /** Required when `narrixMode` is `"handler"` (or inferred handler — see runtime knobs). May use `{ $path }` against jobMemory. */
+    narrixInput?: NarrixRunInput | {
+        $path: string;
+    };
+    /** Filters which signals/stories are written to `taskMemory.narrix` after the Narrix handler. */
+    narrixScope?: NarrixScope;
+    /** Optional: run internal AI calls to scope memory content into input.aiScoped before main task. */
+    aiScoping?: AIScopingInstruction[];
+    /**
+     * Optional global config for the AI scoping step (applies to every `aiScoping[]` instruction unless that
+     * instruction sets its own `llmCall`). Concurrency / per-item timeout are also configurable here (today
+     * they are env-only — `AI_SCOPING_CONCURRENCY` / `AI_SCOPING_TIMEOUT_MS_PER_ITEM`).
+     */
+    aiScopingOptions?: {
+        llmCall?: LlmCallConfig;
+        /** Max concurrent scoping calls; falls back to env `AI_SCOPING_CONCURRENCY`. */
+        concurrency?: number;
+        /** Per-item timeout in ms; falls back to env `AI_SCOPING_TIMEOUT_MS_PER_ITEM`. */
+        timeoutMsPerItem?: number;
+    };
+    /**
+     * Optional canonical {@link LlmCallConfig} for the **main skill** invocation (the underlying `runSkill` call).
+     *
+     * Composes with the legacy `modelConfig` field — when both are present, `llmCall.*` wins for fields it
+     * defines (`model`, `temperature`, `topP`, `maxTokensCap`/`maxTokens`, `timeoutMs`). `modelConfig` is still
+     * forwarded as-is to `@exellix/ai-skills` so all of its `[key: string]: any` extras (e.g. `frequencyPenalty`,
+     * `presencePenalty`, `stop`) keep working.
+     *
+     * Trace mode (`executionMode: "trace"`) returns the underlying ai-skills `RunSkillDiagnostics` /
+     * `SkillDiagnosticsTrace` on success, and a `SkillExecutionTraceError` (passed through unchanged) on
+     * failure — both of which carry the full `invokeRequest`, `usage`, `routing`, `costUsd`, `attempts[]`.
+     * Outside trace mode, raw underlying errors are wrapped in `LlmCallContextError` with a request snapshot.
+     */
+    llmCall?: LlmCallConfig;
+    /** Optional: run NARRIX enrichment before this task; inject result into executionMemory (and optionally jobMemory). */
+    narrix?: NarrixPreProcessorConfig;
+    /** When true, add context to the prompt (opt-in; default is no context). Set to false or omit to omit. */
+    includeContextInPrompt?: boolean;
+    /**
+     * Optional classification for stricter output semantics.
+     *
+     * - decision: routing-critical. `response.parsed` MUST be canonical and schema-valid.
+     * - utility: structured helper step. Validation recommended; may be strict by convention.
+     * - content: user-facing content generation. Structured fallbacks may be acceptable.
+     */
+    taskKind?: "decision" | "utility" | "content";
+    /**
+     * Optional runtime validation for the task's structured output (`response.parsed`).
+     * This is intended for deterministic graph mapping (e.g. output.parsed.shouldUseWeb).
+     *
+     * Integrators: specs that refer to **outputConstraints** for structured answers use the same minimal schema
+     * language as **`schema: OutputSchema`** here (no separate request field).
+     *
+     * - mode "fail" (default): throw an error when validation fails.
+     * - mode "warn": attach validation errors to response.metadata.outputValidation and continue.
+     */
+    outputValidation?: {
+        schema: OutputSchema;
+        mode?: "fail" | "warn";
+        /** When true, validation runs even if parsed is undefined/null (treated as missing). Default true. */
+        validateWhenMissing?: boolean;
+    };
+    /**
+     * When true (default), decision tasks may have default output validation injected by runtime.
+     * Set to false to disable auto-injected validation (not recommended for routing-critical nodes).
+     */
+    autoValidateDecisionOutput?: boolean;
+    /**
+     * Optional low-precedence template seed from graph `jobContextMapping`. Compile into `variables` /
+     * `executionMemory.jobVariables` before invoke; ai-tasks does not merge `jobContext` into `variables` on MAIN.
+     */
+    jobContext?: Record<string, unknown>;
+    /**
+     * Synthesized execution context: job-scoped (shared across graph nodes), task-scoped (this node only),
+     * or execution-scoped (run-wide). Distinct from jobMemory / taskMemory / executionMemory.
+     */
+    xynthesized?: XynthesizedMemory;
+    /** Smart-input config (Rendrix paths or legacy strings); normalized before MAIN executor. */
+    smartInput?: RunTaskSmartInput;
+    /**
+     * Optional graph node `taskConfiguration` forwarded by graph-engine for compile-only use.
+     * {@link compileTaskConfigurationOnRunTaskRequest} maps `aiTaskStrategies` / `aiTaskProfile.inputSynthesis`
+     * into `executionPipeline` and strips this field before execution.
+     */
+    taskConfiguration?: import("./task-configuration.js").TaskConfigurationAuthoring;
+}
+/** Versioned digest of synthesis / pipeline / memory signals for UIs (stable fields only). */
+export type AiTasksObservabilityDigest = {
+    schemaVersion: 1;
+    synthesisEnabled: boolean;
+    effectiveExecutionPipeline?: ExecutionStep[];
+    synthesizedContextPresent: boolean;
+    mainContextSource: "synthesizedContext" | "unsynthesized";
+    detectedTemplateCores?: string[];
+    synthesisMode?: SynthesisMode;
+    /** Shallow summary of merged execution memory (keys + size), not full content unless requested. */
+    executionMemorySummary?: {
+        topLevelKeys: string[];
+        approxJsonChars?: number;
+    };
+    /** Optional Narrix hints when metadata carries narrix blocks. */
+    narrixSummary?: {
+        durationMs?: number;
+        ok?: boolean;
+    };
+    /** Effective {@link RunTaskRequest.inputStrategyKey} (defaults applied by runtime when attached). */
+    inputStrategyKey?: InputStrategyKey | string;
+    /** Compact summary of resolved execution strategies (when attached by runtime). */
+    executionStrategiesSummary?: {
+        beforeKeys: ExecutionStrategyWrapperKey[];
+        afterKeys: ExecutionStrategyWrapperKey[];
+        primaryOptimizerMaxIterations?: number;
+    };
+    /** Effective {@link RunTaskRequest.narrixMode} after legacy resolution (when attached by runtime). */
+    narrixMode?: NarrixModeKey | string;
+};
+/**
+ * Task execution response type.
+ *
+ * This is the response format returned by runTask methods.
+ * Currently aliases RunSkillResponse but provides semantic clarity for tasks.
+ *
+ * For combined/multi-step tasks, the response MAY include an optional
+ * `intermediateSteps` array (see RunTaskResponseWithSteps). Consumers (e.g.
+ * worox-graphs reporter) can use it to render a chain view without separate
+ * graph nodes for each step.
+ */
+export type RunTaskResponse<TParsed = any> = RunSkillResponse<TParsed> & {
+    /**
+     * Resolved smart-input markdown and path diagnostics when downstream returns them
+     * (see also `metadata.smartInputRenderResult`).
+     */
+    smartInputRenderResult?: SmartInputRenderResult;
+    /**
+     * Optional identity envelope returned by downstream execution.
+     * When present, it is also mirrored into response.metadata.identity.
+     */
+    identity?: Record<string, unknown>;
+    /**
+     * Denormalized observability digest for graph consoles. Orchestrators should set this with
+     * {@link extractAiTasksObservabilityFromRunTaskResponse}; ai-tasks does not attach it by default.
+     */
+    aiTasksObservability?: AiTasksObservabilityDigest;
+    /**
+     * Patch for graph-engine to merge into durable xynthesized memory after PRE synthesis writes.
+     */
+    xynthesizedPatch?: XynthesizedMemory;
+};
+export type DebugTraceTask = {
+    taskType: "ai-task" | "pre-execution" | "post-execution";
+    details: string;
+    /**
+     * Structured metadata with stable top-level keys.
+     *
+     * Required keys (when available for the step):
+     * - step: { phase, type, stepId }
+     * - timing: { startedAt, endedAt, durationMs }
+     * - routing: { provider, region, retryCount, requestIds }
+     * - usage: { maxTokensRequested, tokensPrompt, tokensCompletion, tokensTotal, cachedTokens*?, costUsd? }
+     * - ok: boolean
+     */
+    metadata: Record<string, unknown>;
+    modelUsed?: string | null;
+};
+export type RunTaskTraceResponse<TParsed = unknown> = RunTaskResponse<TParsed> & {
+    debugTrace: {
+        tasks: DebugTraceTask[];
+    };
+};
+/**
+ * Explicit, testable execution policy for ai-tasks "utility" invocations.
+ *
+ * - debug: local dev / template debugging (more repair + diagnostics)
+ * - standard: normal interactive runs
+ * - batch-prod: large-scale cost-sensitive runs (minimize retries/repair)
+ */
+export type UtilityExecutionPolicy = "debug" | "standard" | "batch-prod";
+export type XynthesisFinalizeUtilityInput = {
+    /** For observability / tracing. */
+    finalizerNodeId: string;
+    templateId: string;
+    inputs: Record<string, unknown>;
+    outputContractId?: string;
+};
+export type XynthesisFinalizeUtilityRequest = {
+    utilityKind: "xynthesis-finalize";
+    /** Must be the public stable xynthesis utility key. */
+    utilityKey: "xynthesis/finalize";
+    input: XynthesisFinalizeUtilityInput;
+    /**
+     * Explicit policy; when omitted, runtime defaults to env-derived policy.
+     * Keep behavior explicit and unit-testable by passing this from upstream.
+     */
+    executionPolicy?: UtilityExecutionPolicy;
+    /**
+     * Optional global/shared repair budget (e.g. batch processing).
+     * When present and <= 0, repair is disabled even for debug/standard.
+     */
+    repairBudgetRemaining?: number;
+    /** Optional per-call execution config. */
+    exec?: {
+        model?: string;
+        timeoutMs?: number;
+        /** Hard ceiling on the auto-resolved max tokens (`callerMaxTokens` in xynthesis `resolveMaxTokens`). */
+        maxTokensCap?: number;
+        temperature?: number;
+        topP?: number;
+        /** Drives xynthesis `resolveMaxTokens`. When omitted, picks per-stage default via `resolveOutputExpectation`. */
+        outputExpectation?: import("./llmCall.js").OutputExpectation;
+        templatesBasePath?: string;
+        /** Forwarded to `runXynthesisFinalize`; opt-in for verbose upstream `debugTrace` (lifted into metadata). */
+        executionMode?: "default" | "trace";
+    };
+};
+export type RunUtilityRequest = XynthesisFinalizeUtilityRequest;
+export type RunUtilityResponse<TParsed = any> = {
+    utilityKind: RunUtilityRequest["utilityKind"];
+    utilityKey: RunUtilityRequest["utilityKey"];
+    /**
+     * Canonical business output. For xynthesis/finalize structured mode, this MUST
+     * come from the xynthesis response `parsed` field (no salvage/fallback).
+     */
+    parsed?: TParsed;
+    /**
+     * Free-form metadata sidecar. Trace-mode-populated keys (when `exec.executionMode === "trace"`):
+     *   - `exec`: snapshot of the resolved `RunUtilityRequest.exec` (model / cap / temperature / topP / outputExpectation / timeoutMs).
+     *   - `executionPolicy`: the resolved `UtilityExecutionPolicy`.
+     *   - `llmCalls`: per-attempt `LlmCallObservation[]` (success + failure).
+     *   - `debugTrace`: verbatim `XynthesisDebugTrace` from the underlying `runXynthesisFinalize` call.
+     *   - `attempts`: per-attempt `{ ok, repairCount, error?, invokeSummary? }` summaries.
+     *
+     * Non-trace mode: only the lean default upstream metadata + business fields are present.
+     */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Minimal schema for validating `response.parsed` without pulling in a JSON-schema dependency.
+ * Intended for decision/utility nodes producing stable structured artifacts.
+ */
+export type OutputSchema = {
+    type: "any";
+} | {
+    type: "string";
+} | {
+    type: "number";
+} | {
+    type: "boolean";
+} | {
+    type: "null";
+} | {
+    type: "array";
+    items?: OutputSchema;
+    minItems?: number;
+    maxItems?: number;
+} | {
+    type: "object";
+    properties?: Record<string, OutputSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+};
+/**
+ * Task response that may include structured intermediate steps.
+ * When a task performs multiple logical steps in one invocation, it can
+ * return this shape so consumers can inspect the chain (e.g. step 1: to-cni
+ * → step 2: engine-enrich → step 3: triage-q1-q6).
+ */
+export interface RunTaskResponseWithSteps<TParsed = any> extends RunSkillResponse<TParsed> {
+    /** Optional list of steps performed in order; only present for multi-step tasks. */
+    intermediateSteps?: IntermediateSteps;
+}
+/**
+ * Re-export RunSkillResponse from the package for backward compatibility.
+ *
+ * This is the response format returned by both runSkill and runTask methods.
+ */
+export type { RunSkillResponse } from "@exellix/ai-skills";
+//# sourceMappingURL=task-types.d.ts.map