@exellix/ai-tasks 7.8.0

package/documenations/task-core-and-core-aware-synthesis.md

@@ -0,0 +1,58 @@
+# Template Core and Core-Aware Synthesis
+
+This guide documents template-declared core semantics in `@exellix/ai-tasks` and how they work with PRE `synthesized-context`.
+
+## Template core tokens
+
+Templates declare one or more core directives (Athenix `{{core:...}}` format) describing task shape:
+
+- `question`
+- `action`
+- `plan`
+- `objective`
+- `decision`
+- `comparison`
+- `classification`
+- `evaluation`
+- `analysis`
+- `summary`
+- `generation`
+- `extraction`
+
+Rules:
+
+- one or more cores per template are valid
+- closed list by default
+- domain-agnostic (not tied to security/ecommerce/etc.)
+- required when structured synthesis mode is selected (no cores => synthesis-blocking template error)
+- request-level `taskCore` is not used; template declarations are the only synthesis source of truth
+- discovery is pre-render from raw template content (resolved via `ai-skills.resolveRawTemplate(...)`)
+
+## Synthesis modes
+
+`synthesized-context` supports two additive modes:
+
+- `markdown`: existing markdown synthesis behavior
+- `structured`: core-aware synthesis returning validated structured payload, then converted to deterministic markdown for MAIN context
+
+Mode fields:
+
+- preferred: `SynthesisConfig.synthesisMode`
+- legacy-compatible: `SynthesisConfig.synthesisOutputFormat`
+
+When both are set, `synthesisMode` is used first.
+
+## Runtime layering
+
+- raw and enriched artifacts remain available in memory (`_narrix`, scoped memory, `webContext`)
+- structured synthesis artifact is persisted in `executionMemory.synthesizedContext`
+- final MAIN prompt context uses synthesized output when PRE synthesis override is active
+
+This keeps debugging traceability while keeping final model prompts concise.
+
+## ai-gateway boundary
+
+- `ai-tasks`: orchestration, runtime flow, contracts, compatibility
+- `ai-gateway`: model invocation for synthesis
+
+This keeps package roles aligned with existing architecture.

package/documenations/upstream-feature-requests/ai-skills-llm-observability.md

@@ -0,0 +1,129 @@
+# `@exellix/ai-skills` — LLM observability + dynamic budgeting feature requests
+
+Status: open
+Owner: `@exellix/ai-skills`
+Filed by: `@exellix/ai-tasks` (5.6+)
+Tracked here: [`documenations/upstream-feature-requests/ai-skills-llm-observability.md`](.)
+
+This document captures the gaps that remain in `@exellix/ai-skills` ≥ 5.0 after `@exellix/ai-tasks` adopted the upstream LLM observability primitives (`SkillExecutionTraceError`, `RunSkillDiagnostics`, `SkillDiagnosticsTrace`, `mapGatewayInvokeToTrace`, `traceToDiagnostics`, `usageFromGatewayMetadata`, `metadataFromInvokeError`).
+
+The big-ticket items are mostly already shipped — what remains is small but high-value for parity with `@exellix/xynthesis` 3.1+.
+
+---
+
+## 1. Typed error in **default mode** (non-trace) — required for parity with xynthesis
+
+### Today
+
+- `executionMode: "trace"` causes `runSkill` to throw `SkillExecutionTraceError` carrying `RunSkillDiagnostics` (`trace.ok === false`, `trace.invokeRequest`, error envelope, gateway/error metadata).
+- **Outside** trace mode, raw underlying errors are thrown — typically a generic `Error` with the provider/gateway message and no structured payload.
+
+### Why it hurts
+
+`@exellix/ai-tasks` is forced to wrap every non-trace MAIN skill failure in its own `LlmCallContextError` to preserve a snapshot of the request (`modelConfig`, `timeoutMs`, `outputExpectation`). That snapshot is necessarily incomplete — we don't see the gateway-level usage / routing / cost / attempts that the upstream had right there in scope.
+
+### Asked behavior
+
+Throw a `SkillExecutionError` (typed class, **always** thrown — not gated on `executionMode`) that carries:
+
+- `request: { modelConfig, timeoutMs }` — verbatim echo of what we sent.
+- `errorEnvelope: { name, message, code?, providerStatus?, providerCode? }`.
+- `partialDiagnostics?: Partial<RunSkillDiagnostics>` — whatever the call site managed to assemble before throwing (usage, routing, attempts so far). Empty / undefined is acceptable when we have nothing.
+- `cause: unknown` — the original error.
+
+`SkillExecutionTraceError` would still be the trace-only variant carrying the FULL `RunSkillDiagnostics`, and would extend `SkillExecutionError`.
+
+### Acceptance
+
+- `instanceof SkillExecutionError` is true for any failure thrown by `runSkill` (trace and non-trace).
+- `instanceof SkillExecutionTraceError` is true only in trace mode and is also a `SkillExecutionError` (via `extends`).
+- Existing trace-mode callers keep working unchanged.
+- Default-mode callers gain the structured payload without flipping the global trace flag.
+
+---
+
+## 2. `outputExpectation` passthrough on `RunSkillRequest` (when ai-skills adopts xynthesis-style automation)
+
+### Today
+
+`runSkill` accepts a `modelConfig.maxTokens` value and forwards it directly to the AI gateway. There is **no auto-sizer** — callers must pick a number themselves or accept the gateway / provider default.
+
+`@exellix/xynthesis` 3.1+ ships `resolveMaxTokens(input)` (`{ inputText, outputExpectation, modelId, callerMaxTokens?, structuredOutput? }`) plus `MODEL_CAPABILITIES` and `ACTION_OUTPUT_DEFAULTS` registries. `@exellix/ai-tasks` already calls this helper for every xynthesis-backed call (PRE / POST / scoping / utility).
+
+### Why it hurts
+
+The MAIN skill is the only LLM call in the task pipeline that bypasses the auto-sizer. Callers either set `modelConfig.maxTokens` to a hard number (loses dynamic adjustment per-input-size) or omit it (gets whatever the gateway / provider does by default — typically very generous).
+
+### Asked behavior
+
+1. Accept a top-level **optional** `outputExpectation: OutputExpectation` on `RunSkillRequest` (re-exporting the type from `@exellix/xynthesis` is fine — it's already a transitive dep via `xynthesis`).
+2. When `outputExpectation` is provided AND `modelConfig.maxTokens` is omitted, internally call `xynthesis.resolveMaxTokens` to compute the cap before invoking the gateway.
+3. When `modelConfig.maxTokens` is provided, treat it as a HARD CEILING (`callerMaxTokens` in xynthesis terms) and STILL run the auto-sizer to pick something smaller when appropriate.
+4. Echo the resolved cap on `RunSkillResponse.diagnostics.trace.invokeRequest` (alongside `modelConfig` / `timeoutMs`).
+5. Lift the resolution result onto `RunSkillResponse.diagnostics.trace.tokenResolution: MaxTokensResolution` for trace consumers.
+
+### Acceptance
+
+- Pre-existing callers that set `modelConfig.maxTokens` continue working unchanged (the auto-sizer never picks larger).
+- New callers that set only `outputExpectation` get sensible auto-sized caps without picking a number.
+- `result.diagnostics.trace.tokenResolution.reason` is one of `"computed" | "caller-override" | "model-ceiling" | "fallback"` and explains the choice.
+
+---
+
+## 3. Surface `invokeRequest` echo in non-trace `result.diagnostics`
+
+### Today
+
+`RunSkillResponse.diagnostics?: RunSkillDiagnostics` is opt-in via `executionMode: "trace"` (or `diagnostics: { includeDebugTrace: true }`). The `trace.invokeRequest` field (`{ modelConfig, timeoutMs }`) is therefore trace-only.
+
+### Why it hurts
+
+For routine cost/usage observability (no debug trace, no raw provider payload), callers want to see what was actually sent (resolved model id, `maxTokens`, `temperature`, `topP`, `stop`, …) without the overhead of full trace mode. Today they have to flip trace mode on for everything just to get the request echo.
+
+### Asked behavior
+
+Add a lightweight `diagnostics: { includeInvokeRequestEcho?: boolean }` opt-in that returns:
+
+```typescript
+result.diagnostics = {
+  invokeRequest: { modelConfig, timeoutMs },
+  // (no trace, no rawProviderPayload, no attempts[])
+};
+```
+
+Cheap to populate (we have it in scope) and answers most "what did we actually send?" questions.
+
+### Acceptance
+
+- `includeInvokeRequestEcho: true` returns `result.diagnostics.invokeRequest` without forcing full trace mode.
+- `executionMode: "trace"` continues to return the FULL `RunSkillDiagnostics` (superset).
+
+---
+
+## 4. Optional: `onLlmCall(invokeSummary)` hook on `runSkill`
+
+Mirror the request being filed against `@exellix/xynthesis` 3.x — a single per-call observation hook callers can subscribe to without parsing `RunSkillResponse.diagnostics`. Useful for cost / usage telemetry sinks.
+
+### Asked behavior
+
+```typescript
+runSkill({
+  ...,
+  onLlmCall: (summary: InvokeSummary) => void, // fire-and-forget; thrown errors swallowed
+});
+```
+
+Where `InvokeSummary` is whatever ai-skills already builds internally (analogous to xynthesis `InvokeAttemptSummary`).
+
+### Acceptance
+
+- Hook is invoked exactly once per terminal LLM attempt (success or failure) with `{ modelRequested, modelResolved, maxTokensFromCaller, maxTokensEffective, usage, routing, costUsd, errorEnvelope? }`.
+- Hook errors do not affect the call's outcome.
+
+---
+
+## Cross-references
+
+- xynthesis equivalents already shipped — see `documenations/upstream-feature-requests/xynthesis-llm-observability.md` for the residual xynthesis gaps.
+- ai-tasks integration: `src/strategies/direct-execution-strategy.ts` (the only call site that goes through `runSkill`) currently wraps non-trace errors in `LlmCallContextError`. That wrapping becomes redundant once #1 ships.
+- ai-tasks integration: `src/types/llmCall.ts` re-exports `SkillExecutionTraceError` so callers don't depend on `@exellix/ai-skills` directly. A new `SkillExecutionError` (item #1) would be added to that re-export.

package/documenations/upstream-feature-requests/xynthesis-llm-observability.md

@@ -0,0 +1,125 @@
+# `@exellix/xynthesis` — LLM observability + invoker knob feature requests
+
+Status: open
+Owner: `@exellix/xynthesis`
+Filed by: `@exellix/ai-tasks` (5.6+)
+Tracked here: [`documenations/upstream-feature-requests/xynthesis-llm-observability.md`](.)
+
+This document captures the gaps that remain in `@exellix/xynthesis` ≥ 3.1 after `@exellix/ai-tasks` adopted `resolveMaxTokens`, `MODEL_CAPABILITIES`, `ACTION_OUTPUT_DEFAULTS`, `runSynthesisCall.invokeSummary`, `runSynthesisCall.executionMode: "trace"`, `XynthesisInvokeError`, `XynthesisResponseParseError`, and `runStructuredSynthesisGatewayCall(outputExpectation, executionMode)`.
+
+The big-ticket items are mostly already shipped — what remains is a handful of small ergonomics fixes.
+
+---
+
+## 1. Accept `temperature` and `topP` on `RunSynthesisCallOpts` and `SynthesisInvokerOptions`
+
+### Today
+
+`RunSynthesisCallOpts` accepts `model`, `maxTokens`, `timeoutMs`, `maxOutputLength`, `tokenResolutionMetadata`, `executionMode` — but NOT `temperature` or `topP`. The same is true for `SynthesisInvokerOptions` (the lower-level invoker contract).
+
+### Why it hurts
+
+`@exellix/ai-tasks` exposes a unified `LlmCallConfig` that includes `temperature` and `topP` for every stage (PRE / MAIN / POST / scoping / utility). Today these knobs are honored end-to-end ONLY for the MAIN skill (which goes through `@exellix/ai-skills` `ModelConfig`). For PRE synthesis / POST audit / POST polish / scoping / `runXynthesisFinalize`, the values are accepted on the ai-tasks surface but DROPPED before the invoker sees them — because xynthesis has nowhere to put them.
+
+### Asked behavior
+
+Add optional `temperature?: number` and `topP?: number` fields to:
+
+- `RunSynthesisCallOpts` (in `runSynthesisCall.ts`).
+- `RunStructuredSynthesisParams` (in `contextSynthesizer.ts`) — already accepts `outputExpectation`, just needs these two.
+- `RunXynthesisFinalizeExecConfig` (in `finalize.ts`).
+- `SynthesisInvokerOptions` (in `invoker.ts`).
+
+Forward both to the underlying provider invoker (`AIFunctionsInvoker` / `AIGateway`). Out-of-band defaults: leave undefined (let provider pick). Don't enforce ranges (provider already does).
+
+### Acceptance
+
+- `runSynthesisCall({ ..., temperature: 0.4, topP: 0.9 })` honors both.
+- Existing callers that don't set them continue working unchanged.
+- `result.invokeSummary.executionMetadata` echoes the values that were actually sent (helps debugging).
+
+---
+
+## 2. Accept `outputExpectation` on `RunSynthesisCallOpts` (today only on `RunStructuredSynthesisParams`)
+
+### Today
+
+`runSynthesisCall(opts)` does NOT accept `outputExpectation`. Callers must:
+
+1. Manually call `resolveMaxTokens({ inputText, outputExpectation, modelId, callerMaxTokens })` themselves.
+2. Forward the resolved `maxTokens` AND build `tokenResolutionMetadata` for telemetry.
+
+`RunStructuredSynthesisParams` (used by `runStructuredSynthesisGatewayCall`) already accepts `outputExpectation` — the gap is on the simpler `runSynthesisCall` path.
+
+### Why it hurts
+
+Every xynthesis-backed call site in `@exellix/ai-tasks` (5+ today) repeats the same pre-call dance via the `resolveLlmCallForXynthesis` helper. Bug-prone (it's easy to forget the `tokenResolutionMetadata` echo) and a barrier to entry for new call sites.
+
+### Asked behavior
+
+Accept optional `outputExpectation?: OutputExpectation` on `RunSynthesisCallOpts`. When set AND `maxTokens` is omitted:
+
+1. Internally call `resolveMaxTokens({ inputText, outputExpectation, modelId, callerMaxTokens: opts.maxTokens })` — `inputText` is `(systemPrompt + userPrompt)` (xynthesis already concatenates these).
+2. Use the resolved `maxTokens`.
+3. Build the `tokenResolutionMetadata` for the invoker telemetry.
+
+When `maxTokens` is explicitly set, treat it as a HARD CEILING (`callerMaxTokens` in `resolveMaxTokens` terms) and STILL run the auto-sizer to pick something smaller when appropriate. (This is consistent with how `resolveMaxTokens` already behaves.)
+
+### Acceptance
+
+- `runSynthesisCall({ ..., outputExpectation })` works with no extra setup; `maxTokens` is auto-resolved.
+- `runSynthesisCall({ ..., outputExpectation, maxTokens })` keeps the cap as a ceiling.
+- `result.invokeSummary.maxTokensFromCaller` and `result.invokeSummary.maxTokensEffective` reflect the right values.
+- Existing callers that pre-resolve `maxTokens` themselves continue working unchanged.
+
+---
+
+## 3. Extend `runXynthesisFinalize` `out.diagnostics` to include `invokeSummary`
+
+### Today
+
+`runXynthesisFinalize(input, exec)` returns `{ parsed, debugTrace?, diagnostics? }`. The `diagnostics` object today carries gateway-level metadata (`renderedTemplateContext`, `outputContractVersion`, etc.) but does NOT include the equivalent of `RunSynthesisResult.invokeSummary` (the always-present per-call `InvokeAttemptSummary` with usage / routing / cost / model echo).
+
+### Why it hurts
+
+`@exellix/ai-tasks` `runUtility` (xynthesis-finalize utility) records per-attempt observations and tries to lift `invokeSummary` from the result on success — but there's nothing there. Today we record a partial observation built from the request snapshot only. On failure we DO get it (via `XynthesisInvokeError.invokeSummary`); the asymmetry is awkward.
+
+### Asked behavior
+
+Add `out.diagnostics.invokeSummary?: InvokeAttemptSummary` (always populated on success; mirroring `runSynthesisCall.invokeSummary`). For multi-attempt internal repair flows, an array `out.diagnostics.invokeSummaries?: InvokeAttemptSummary[]` would be even better; otherwise just the terminal one suffices.
+
+### Acceptance
+
+- `runXynthesisFinalize` returns `out.diagnostics.invokeSummary` on every successful call.
+- Schema unchanged for failure paths (still throw `XynthesisInvokeError` / `XynthesisResponseParseError` with `invokeSummary`).
+
+---
+
+## 4. Optional: `onLlmCall(summary)` hook on `runSynthesisCall` / `runXynthesisFinalize`
+
+A single per-call observation hook callers can subscribe to without parsing `result.invokeSummary` / `result.debugTrace`. Useful for cost / usage telemetry sinks that don't want to wrap every call site.
+
+### Asked behavior
+
+```typescript
+runSynthesisCall({
+  ...,
+  onLlmCall: (summary: InvokeAttemptSummary) => void, // fire-and-forget; thrown errors swallowed
+});
+```
+
+Same shape as the corresponding `@exellix/ai-skills` hook request (see `documenations/upstream-feature-requests/ai-skills-llm-observability.md`).
+
+### Acceptance
+
+- Hook fires exactly once per terminal LLM attempt (success or failure).
+- Hook errors do not affect the call's outcome.
+
+---
+
+## Cross-references
+
+- ai-skills equivalents — see `documenations/upstream-feature-requests/ai-skills-llm-observability.md`.
+- ai-tasks integration: `src/internal/runPostStepLlmCall.ts` (the central wrapper) currently runs the auto-sizer manually via `src/internal/resolveLlmCallForXynthesis.ts`. Items #1 and #2 would let that helper shrink to a thin pass-through.
+- ai-tasks integration: `src/utilities/runUtility.ts` records a placeholder `invokeSummary` on success today. Item #3 would let it record the real one.
+- ai-tasks integration: `src/types/llmCall.ts` re-exports `XynthesisInvokeError`, `XynthesisResponseParseError`, `InvokeAttemptSummary`, `MaxTokensResolution`, `OutputExpectation` so callers don't depend on `@exellix/xynthesis` directly.

package/documenations/upstream-feedback-request-shape-clarification.md

@@ -0,0 +1,101 @@
+# Upstream Feedback Response: `runTask` Request Shape and Runtime Model
+
+## Context
+
+Feedback received:
+
+> The `runTask` request still looks old-shaped.
+> In all 3 request files, top-level shape is still basically:
+> `question`, `record`, `inputs`, `narrix`, `executionMemory`, `variables`.
+> I do not see new explicit runtime concepts reflected in request shape:
+> - no `taskCore`
+> - no detected template core set
+> - no `synthesizedContext` being carried into MAIN
+> - no sign that template analysis is driving execution
+>
+> So request contract still looks like old model.
+
+This document is the formal response and clarification.
+
+---
+
+## Short Answer
+
+The request contract is **intentionally minimal and mostly unchanged at top-level**.
+The new model is a **runtime-orchestration contract**, not a request-field expansion.
+
+So the absence of new top-level fields is expected and correct.
+
+---
+
+## What Changed (and Why It May Not Appear in Request Shape)
+
+### 1) `taskCore` removed from request (intentional)
+
+- The old request-level `taskCore` is removed as source of truth.
+- Runtime now derives task semantics from template declarations.
+- This is a deliberate shift away from user-supplied task core metadata.
+
+### 2) Core detection is runtime-derived, not caller-supplied
+
+- `templateCores` are discovered pre-render from raw instructions/prompt templates.
+- Discovery is done by runtime internals (not by request payload).
+- Therefore `templateCores` does not need to be added as request input.
+
+### 3) `synthesizedContext` is execution memory artifact, not request input
+
+- In structured synthesis mode, runtime writes synthesized artifact to:
+  - `executionMemory.synthesizedContext`
+- This is generated during PRE step and then consumed by MAIN flow.
+- It is intentionally a runtime-produced artifact, not a required top-level request field.
+
+### 4) Template analysis drives execution internally
+
+- The execution decision path (for structured synthesis) is:
+  1. resolve raw templates,
+  2. detect `{{core:...}}` directives,
+  3. validate non-empty detected core set,
+  4. run structured synthesis with detected cores + resolved question,
+  5. materialize main context markdown and continue MAIN execution.
+- This orchestration is runtime behavior and does not require top-level request shape changes.
+
+---
+
+## Why Keeping Request Shape Stable Is Correct
+
+- Backward compatibility for callers that already send existing fields.
+- Avoids duplicating runtime-derived data in user input.
+- Prevents conflicting sources of truth (caller-provided core vs template-declared core).
+- Keeps request API focused on inputs/config, while runtime computes orchestration artifacts.
+
+---
+
+## Explicit Clarification to Upstream
+
+Please do **not** interpret the unchanged top-level request shape as "old model still active".
+
+The new model is active through runtime semantics:
+
+- no request-level `taskCore`,
+- template-driven core declaration (`{{core:...}}`),
+- pre-render core discovery from raw template content,
+- structured synthesis validation using detected `templateCores`,
+- synthesized artifact persisted to execution memory and used in MAIN flow.
+
+This is a contract change in **runtime behavior**, not a requirement to add more top-level request fields.
+
+---
+
+## What Upstream Still Needs To Ensure
+
+1. `ai-skills.resolveRawTemplate(...)` remains stable/public for pre-render analysis.
+2. `athenix-parser` keeps `core:` directives as first-class non-path tokens.
+3. Lifecycle cleanup/shutdown exists for test/runtime handle hygiene (non-functional hardening).
+
+---
+
+## Final Position
+
+The current request shape is acceptable and intentional.
+No additional top-level request fields are required to represent the new core-aware runtime model.
+

package/documenations/web-context-precedence.md

@@ -0,0 +1,33 @@
+# Web context precedence: structured scoping vs caller markdown
+
+This document describes how **web evidence** reaches MAIN context and the **synthesized-context** PRE step, and how to avoid **duplicate** web retrieval.
+
+## Sources
+
+1. **Internal structured web context** — When NARRIX pre-processor runs with **`narrix.enableWebScope: true`**, ai-tasks calls the Narrix web scoper and stores the result on **`executionMemory.webContext`**. Markdown for prompts is derived via **`buildWebContextEvidenceMarkdown`** (`src/narrix/webContextMarkdown.ts`).
+
+2. **Caller-provided markdown** — Orchestrators may attach a pre-rendered string on **`executionMemory.webContextMarkdown`**. When MAIN context is built (`_executeDirect`), if that string is non-empty and context assembly is active (see below), it is appended **after** Narrix narrative and internal web markdown as a section:
+
+   **`## Supplementary web context (caller-provided)`**
+
+## Precedence (MAIN `context` markdown)
+
+When **`includeContextInPrompt`** is true, or NARRIX narrative is in play, or MAIN runs with a **synthesized** override from the pipeline:
+
+1. Narrix attachment markdown (when present).
+2. Markdown built from **`executionMemory.webContext`** (when available).
+3. **`executionMemory.webContextMarkdown`** (caller supplementary), if non-empty.
+
+Synthesis PRE source material uses **`resolveSourceMaterial`** / **`resolveSourceMaterialParts`**, which serialize web as dedicated markdown and may **omit** raw `webContext` from JSON memory slices for specific policies (see [web-scoping-in-ai-tasks.md](./web-scoping-in-ai-tasks.md)).
+
+## Avoiding duplicate search
+
+- **Do not** set **`narrix.enableWebScope: true`** if the gateway already ran web search and you only persist results into **`executionMemory.webContext`** or **`webContextMarkdown`**.
+- Use **`narrix.skipWebScopeWhenExternalWebMarkdownPresent: true`** when **`executionMemory.webContextMarkdown`** is already set before the NARRIX pre-processor runs: internal Tavily/web-scoper **will not** run for that invocation (Narrix narrative still runs as usual).
+
+Optional environment knobs (existing) include caps on generated web markdown (e.g. **`WEB_CONTEXT_MARKDOWN_MAX_CHARS`** in web-scoping docs).
+
+## Related
+
+- [web-scoping-in-ai-tasks.md](./web-scoping-in-ai-tasks.md)
+- [synthesized-context-guide.md](./synthesized-context-guide.md)