@exellix/ai-tasks 9.0.6 → 9.1.1

package/.docs/flow-io/xynthesis-post.md

@@ -1,154 +0,0 @@
-# Calling **xynthesis** — POST (`audit` / `polish`)
-
-How `@exellix/ai-tasks` invokes the **`@exellix/xynthesis`** component in **POST** pipeline steps after MAIN completes.
-
----
-
-## When it runs
-
-- `executionPipeline` includes `{ phase: "post", type: "audit" | "polish", config: ... }`
-- Runs **after** MAIN (`runSkill`) returns
-- Only implemented POST types: **`audit`**, **`polish`** (others ignored)
-
-Does **not** run on local-task paths or requests without POST steps.
-
----
-
-## Shared adapter
-
-All POST LLM calls use the same path as PRE markdown:
-
-```
-runAuditCall / runPolishCall / audit merge
-  → runPostStepLlmCall
-      → resolveLlmCallForXynthesis(stage)
-      → runSynthesisCall(...)
-```
-
-Implementation: `src/internal/runPostStepLlmCall.ts`, `src/post-steps/audit/runAuditCall.ts`, `src/post-steps/polish/runPolishCall.ts`.
-
----
-
-## Audit
-
-**Config:** `AuditConfig` on the POST step.
-
-| Call | `LlmCallStage` | xynthesis `SidekickActionType` | Config |
-|------|----------------|--------------------------------|--------|
-| Evaluate candidate | `post-audit` | `audit` | `llmCall.audit` |
-| Merge / synthesis pass | `post-audit-merge` | `audit` | `llmCall.synthesis` |
-
-**Inputs:**
-
-- MAIN output text (candidate cycles)
-- `contextMarkdown` captured from MAIN
-- Audit templates: `loadAuditTemplates`, `renderAuditSystem`, `renderAuditUser`
-- Gateway checks: `config.gateway.must` / `should`
-
-**Outputs:**
-
-- Final selected text → response body
-- `metadata.postSteps.audit` (scores, cycles, `synthesisUsed`, …)
-- `metadata.postSteps.audit.llmCalls` in trace mode
-
-Orchestration: `src/post-steps/audit/runAudit.ts` (may re-run MAIN via `reRunMain` when audit fails).
-
----
-
-## Polish
-
-**Config:** `PolishConfig` on the POST step.
-
-| Call | `LlmCallStage` | xynthesis `SidekickActionType` | Config |
-|------|----------------|--------------------------------|--------|
-| Each pass | `post-polish` | `fix` | `llmCall` |
-
-**Inputs:**
-
-- MAIN (or prior POST) output
-- `config.checklist`
-- Optional original `contextMarkdown` when `includeOriginalContext`
-
-**Outputs:**
-
-- Polished text (parsed JSON: `polishedOutput`, `changeNotes`)
-- `metadata.postSteps.polish`
-- `metadata.postSteps.polish.llmCalls` in trace mode
-
-Orchestration: `src/post-steps/polish/runPolish.ts`.
-
----
-
-## `runSynthesisCall` payload
-
-Same shape as PRE (see [xynthesis-pre.md](./xynthesis-pre.md)):
-
-- `gateway`: `agentId`, `sessionId` (= `taskId`), new `aiRequestId` per call
-- `prompts`: audit/polish-rendered system + user
-- `workScope`: `{ jobId, taskId }`
-- `maxTokens` from `resolveLlmCallForXynthesis`
-- `executionMode: "trace"` when trace collector present
-
----
-
-## LLM config resolution
-
-| Step | Env prefix | Shared fallback |
-|------|------------|-----------------|
-| Audit evaluator | `AUDIT_*` | `POST_STEP_*` |
-| Audit synthesis merge | `AUDIT_*` (synthesis role) | `POST_STEP_*` |
-| Polish | `POLISH_*` | `POST_STEP_*` |
-
-Order per field: `config.llmCall.*` → step env → `POST_STEP_*` → code fallback (`resolveLlmCall` in `src/post-steps/resolvePostStepConfig.ts`).
-
-`outputExpectation`: caller `llmCall.outputExpectation` overrides xynthesis defaults for `audit` or `fix`.
-
----
-
-## Trace
-
-`executionMode: "trace"` on the `RunTaskRequest` attaches `LlmCallObservation` per POST call (`source: "xynthesis"`, `stage`, `invokeSummary`).
-
----
-
-## TaskNode model (graph authoring)
-
-POST xynthesis runs only when the compiled `RunTaskRequest` includes POST pipeline steps (or engine-generated equivalents from profile keys).
-
-| TaskNode field | Role for POST xynthesis |
-|----------------|-------------------------|
-| `executionPipeline[]` with `phase: "post"`, `type: "audit"` \| `"polish"` | Static `AuditConfig` / `PolishConfig` on the step (`gateway`, `checklist`, `llmCall`, thresholds, …). |
-| `taskConfiguration.aiTaskProfile.postStrategyKey` | Graph-engine may emit engine POST utility / pipeline steps before/instead of hand-authored POST; resolved model still comes from node model config (see runtime). |
-| `taskConfiguration.modelConfig` | Resolved `xynthesisModel` for audit evaluator, audit merge, and polish passes. |
-| `taskConfiguration.llmCall` | Node-level defaults the engine may map into POST step `llmCall` roles (`audit`, `synthesis`, polish). |
-| `executionPipeline` MAIN step | Must exist exactly once; POST runs on MAIN output after `runSkill` returns. |
-| `node.outputValidation` | Graph-engine **local** check before mappings — **not** the same as `taskConfiguration.aiTasksOutputValidation` (server-side in ai-tasks on MAIN). POST xynthesis is unrelated to either unless audit re-runs MAIN. |
-
-**Not on the model:** MAIN output text, audit scores, or polish `changeNotes` — those exist only after the run.
-
----
-
-## TaskNode runtime (per-run overrides)
-
-| Runtime field | Role for POST xynthesis |
-|---------------|------------------------|
-| `runtime.nodes[nodeId].modelConfig` | Same precedence as PRE/MAIN: overrides `xynthesisModel` / `skillModel` for **this node's entire `runTask`**, including POST audit/polish LLM calls inside that invocation. |
-| `runtime.nodes[nodeId].aliasConfig` | Per-node alias overlay for POST model resolution. |
-| `runtime.executionMemory` | Not written by POST inside ai-tasks for audit/polish metadata (those land on `response.metadata.postSteps`). Downstream mappings use `executionMapping` on the model after the node completes. |
-
-**Not on node runtime:** POST step definitions, audit checklists, or polish checklists — declare on `node.executionPipeline` or profile-generated pipeline on the model.
-
-Engine PRE/POST **utility** calls (from `preStrategyKey` / `postStrategyKey`) also receive this node's resolved `modelConfig` when graph-engine owns the `runTask`.
-
----
-
-## Source files
-
-| File | Role |
-|------|------|
-| `src/post-steps/audit/runAudit.ts` | Audit loop |
-| `src/post-steps/audit/runAuditCall.ts` | Single audit LLM |
-| `src/post-steps/polish/runPolish.ts` | Polish passes |
-| `src/post-steps/polish/runPolishCall.ts` | Single polish LLM |
-| `src/post-steps/resolvePostStepConfig.ts` | Model/timeout env resolution |
-| `src/internal/runPostStepLlmCall.ts` | xynthesis invoke |

package/.docs/flow-io/xynthesis-pre.md

@@ -1,181 +0,0 @@
-# Calling **xynthesis** — PRE (`synthesized-context`)
-
-How `@exellix/ai-tasks` invokes the **`@exellix/xynthesis`** component in the **PRE** pipeline step.
-
----
-
-## When it runs
-
-- `executionPipeline` contains a step: `{ phase: "pre", type: "synthesized-context", config: SynthesisConfig }`
-- Requires `includeContextInPrompt: true` **or** `config.autoEnableContext: true`
-- At most **one** PRE synthesis step runs (first in list, then pipeline continues)
-
-Does **not** run on: local-task short-circuit, MAIN-only requests, or requests without that pipeline step.
-
----
-
-## What ai-tasks calls in xynthesis
-
-| Mode | xynthesis entrypoint | ai-tasks wrapper |
-|------|----------------------|------------------|
-| Markdown (default) | `runSynthesisCall` | `runPostStepLlmCall` → stage `pre-synthesis-markdown` |
-| Question-driven | `runSynthesisCall` (per question) | `runPostStepLlmCall` → stage `pre-synthesis-question` |
-| Structured | `runStructuredSynthesisGatewayCall` (+ validate) | `runStructuredSynthesisGatewayCallRobust` → stage `pre-synthesis-structured` |
-
-Supporting xynthesis helpers used in PRE (not separate LLM calls):
-
-- `loadSynthesisTemplates`, `buildSynthesisSystemPrompt`, `buildSynthesisUserPrompt`
-- `getRenderedTemplates`, `discoverTemplateCores`, `resolveSynthesisQuestion`
-- `buildSynthesizedContextMarkdown`, `normalizeAndValidateSynthesizedPayload`
-
-Source material assembly (`resolveSourceMaterial`, `resolveSourceMaterialParts`) is **ai-tasks** code; see [narrix.md](./narrix.md) and [web-scoping.md](./web-scoping.md) for inputs that feed it.
-
----
-
-## Call chain (markdown mode)
-
-```
-runTask pipeline
-  → _runSynthesizedContextPreStep(request, SynthesisConfig)
-      → enrichMemoriesWithScoping (ai-skills)
-      → resolveSourceMaterial* (ai-tasks)
-      → getRenderedTemplates (xynthesis + bundle)
-      → runPostStepLlmCall
-            → resolveLlmCallForXynthesis(stage: pre-synthesis-markdown)
-            → runSynthesisCall({ gateway, prompts, workScope, maxTokens, ... })
-      → contextMarkdown + artifact
-  → overrideContext for MAIN
-```
-
-Implementation: `src/core/task-sdk.ts` (`_runSynthesizedContextPreStep`), `src/internal/runPostStepLlmCall.ts`.
-
----
-
-## `runSynthesisCall` payload (via `runPostStepLlmCall`)
-
-| Field | Source |
-|-------|--------|
-| `gateway.agentId` | `request.agentId` |
-| `gateway.sessionId` | `request.taskId` |
-| `prompts.systemPrompt` / `userPrompt` | xynthesis template builders + source material |
-| `workScope.jobId` / `taskId` | `request.jobId`, `request.taskId` |
-| `model`, `timeoutMs`, `maxOutputLength` | `SynthesisConfig.llmCall` → `modelConfig` → `SYNTHESIS_*` env |
-| `maxTokens` | `resolveLlmCallForXynthesis` → xynthesis `resolveMaxTokens` |
-| `tokenResolutionMetadata` | same resolver (Activix) |
-| `executionMode: "trace"` | when `request.executionMode === "trace"` |
-
-`request.identity` may be forwarded separately via `synthesisIdentityFromRequest` where the xynthesis API accepts it.
-
----
-
-## `SynthesisConfig` → xynthesis (LLM knobs)
-
-Resolution order for the PRE LLM call:
-
-1. `config.llmCall.*`
-2. `config.modelConfig` / `config.timeoutMs` / `config.maxOutputLength`
-3. Env: `SYNTHESIS_MODEL`, `SYNTHESIS_TIMEOUT_MS`, … (`llmCallEnvPrefix("SYNTHESIS")`)
-4. Fallbacks in `_runSynthesizedContextPreStep` (e.g. model `gpt-5-nano`, timeout 30s)
-
-`outputExpectation`: caller override wins; else xynthesis `resolveOutputExpectation("synthesis")`.
-
----
-
-## Inputs (what reaches the prompts)
-
-| Input | Role |
-|-------|------|
-| Enriched `jobMemory`, `taskMemory`, `executionMemory` | Serialized per `contextSourcePolicy` / `synthesisInputStrategy` |
-| Narrix attachment | From `executionMemory._narrix` (or `attachToField`) — see [narrix.md](./narrix.md) |
-| Web evidence markdown | From `executionMemory.webContext` when policy includes web — see [web-scoping.md](./web-scoping.md) |
-| Rendered skill templates | `getRenderedTemplates` with bundle including `xynthesized`, `smartInput` |
-| `request.input` | Question for structured mode (`questionPath` / `getQuestion`) |
-
-`contextSourcePolicy` default `auto` resolves to combined narrix + memory + web layout in `resolveSourceMaterial.ts`.
-
----
-
-## Outputs (after xynthesis returns)
-
-| Output | Where |
-|--------|--------|
-| `contextMarkdown` | Passed to MAIN as `overrideContext` |
-| `executionMemory.synthesizedContext` | Artifact (`mode`: markdown \| structured \| questionDriven) unless `xynthesizedOutput.alsoWriteLegacySynthesizedContext: false` |
-| `executionMemory.synthesizedInput` | Source material snapshot (size cap: `SYNTHESIZED_INPUT_MAX_CHARS`) |
-| `request.xynthesized[scope][outputKey]` | When `config.xynthesizedOutput` set (`src/utils/xynthesizedWrite.ts`) |
-| `response.xynthesizedPatch` | Graph merge slice from PRE write |
-| `metadata.synthesizedContextLlmCalls` | Trace mode only (`LlmCallObservation[]`) |
-
-Empty synthesized context is **not** replaced by Narrix/web fallback when synthesis was authoritative.
-
----
-
-## Structured mode extras
-
-- Requires `{{core:...}}` in raw instructions or prompt (`discoverTemplateCores`).
-- Repair path may use AIGateway + stage `structured-repair` (`src/synthesis/runStructuredSynthesisRobust.ts`).
-- Optional `getContextSynthesizer()` hook bypasses gateway if registered.
-
----
-
-## Cache
-
-`reuseCachedSynthesizedContext: true` skips all xynthesis LLM calls when `executionMemory.synthesizedContext` already has usable `contextMarkdown`.
-
----
-
-## TaskNode model (graph authoring)
-
-Static fields graph-engine maps into `RunTaskRequest` for PRE xynthesis. Nothing here is executed inside ai-tasks until compiled into a request.
-
-| TaskNode field | Role for PRE xynthesis |
-|----------------|------------------------|
-| `taskConfiguration.aiTaskProfile.inputSynthesis` | **Canonical** switch for generated PRE `synthesized-context`. `enabled`, `sources`, `destination` (`job` \| `task` \| `execution` → `xynthesizedOutput.destination`), synthesis mode/policy knobs. Must not conflict with a hand-authored PRE step (`INPUT_SYNTHESIS_PIPELINE_CONFLICT`). |
-| `taskConfiguration.aiTaskStrategies.pre: "synthesis"` | **Enable PRE** when forwarded on `RunTaskRequest.taskConfiguration` (compiled by ai-tasks at `runTask`). Use `preInputStrategy` for `synthesisInputStrategy`. |
-| `executionPipeline[]` with `phase: "pre"`, `type: "synthesized-context"` | Alternative to profile/strategies: full `SynthesisConfig` on the step (`contextSourcePolicy`, `synthesisMode`, `xynthesizedOutput`, `llmCall`, …). |
-| `taskConfiguration.modelConfig` | `ModelConfigSelection` → resolved `xynthesisModel` for the PRE LLM (via graph-engine alias resolution). |
-| `taskConfiguration.llmCall` | Optional per-node cap on model / `maxTokensCap` / `outputExpectation` / `timeoutMs` forwarded into pipeline `SynthesisConfig.llmCall` when the engine maps it. |
-| `taskConfiguration.timeoutMs` | May surface on the outbound request; PRE also reads step-level `timeoutMs`. |
-| `node.taskVariable` | Prompt literals and `$path` refs (`jobVariables.*`, `taskVariables.*`) → materialized **`RunTaskRequest.input`** (question for structured / question-driven synthesis). |
-| `node.inputsConfig` | Runtime binding wires only (`executionMemoryPath`) → values available under **`executionMemory`** for `resolveSourceMaterial` / question-driven `record` source. |
-| `node.variables` | Node templates → **`executionMemory.taskVariables`** → paths `taskVariables.*` in rendered synthesis templates. |
-| `node.smartInput` | Forwarded to **`RunTaskRequest.smartInput`**. Paths may include `xynthesized.job\|task\|execution.*`, `executionMemory.*`, `input.*`, `jobVariables.*`, `taskVariables.*`. Invalid shape throws **`SmartInputValidationError`** at `runTask` entry (before PRE xynthesis). |
-| `taskConfiguration.narrix` | Indirect: enables `_narrix` / `webContext` inputs to PRE (see [narrix.md](./narrix.md), [web-scoping.md](./web-scoping.md)). |
-| `skillKey` | Selects skill templates passed to `getRenderedTemplates`. |
-| `id` | Becomes `RunTaskRequest.nodeId` / correlation. |
-
-**Not on the model:** active `executionMemory`, resolved `xynthesized` payloads, or synthesis results — those are runtime or response-only.
-
-**Forbidden:** `metadata.inputSynthesis`, `metadata.modelConfig` — use `taskConfiguration.*`.
-
----
-
-## TaskNode runtime (per-run overrides)
-
-`GraphRuntimeObject.nodes[nodeId]` is **not** where synthesis config or pipelines live. Only fields that change the outbound `runTask` for this node matter.
-
-| Runtime field | Role for PRE xynthesis |
-|---------------|------------------------|
-| `runtime.nodes[nodeId].modelConfig` | **Highest-precedence** `xynthesisModel` / `skillModel` for this node's `runTask` (including PRE), after alias resolution with `runtime.aliasConfig` + optional `runtime.nodes[nodeId].aliasConfig`. |
-| `runtime.nodes[nodeId].aliasConfig` | Resolves alias keys on that node's `modelConfig` only. |
-| `runtime.executionMemory` | Live run state PRE reads: `synthesizedContext` (cache when `reuseCachedSynthesizedContext`), `_narrix`, `webContext`, `input` / `inputs`, `jobVariables` / `taskVariables` mirrors. |
-| `runtime.input` / `runtime.inputs` | Entry payloads; mirrored into `executionMemory` before NARRIX / PRE. |
-| `runtime.jobMemory` / `runtime.taskMemory` | Fed into memory bundle enrichment and source-material policies. |
-| `runtime.variables` / `runtime.jobVariables` | Run-wide template bucket → `jobVariables.*` in synthesis source / templates. |
-
-**Not on node runtime:** `executionPipeline`, `inputSynthesis`, `smartInput`, or per-node template overrides — use the static `TaskNode` (or graph `model.variables` for job scope).
-
-Graph-engine builds an ephemeral **ExellixRuntimeObject** per outbound `runTask`; ai-tasks only sees the compiled `RunTaskRequest`.
-
----
-
-## Source files
-
-| File | Role |
-|------|------|
-| `src/core/task-sdk.ts` | Pipeline + `_runSynthesizedContextPreStep` |
-| `src/internal/runPostStepLlmCall.ts` | `runSynthesisCall` adapter |
-| `src/internal/resolveLlmCallForXynthesis.ts` | Token sizing |
-| `src/synthesis/resolveSourceMaterial.ts` | PRE input text |
-| `src/synthesis/runStructuredSynthesisRobust.ts` | Structured branch |
-| `src/types/task-types.ts` | `SynthesisConfig` |

package/.docs/gap-analysis.md

@@ -1,201 +0,0 @@
-# Gap Analysis: @woroces/ai-tasks SDK Completion
-
-**Date:** Current  
-**Status:** Test passes but implementation doesn't match canonical algorithm
-
-## Executive Summary
-
-The current implementation works (test passes), but it **does NOT implement the canonical `runTask` algorithm**. It's currently just a thin wrapper that calls `client.runSkill()` directly, missing all the task-level enrichment and context generation logic.
-
-## Critical Gaps
-
-### 1. ❌ Missing: Canonical runTask Algorithm
-
-**Current State:**
-- `runTask()` just calls `client.runSkill()` directly
-- No task-level memory enrichment
-- No context markdown generation
-- No taskId extraction from skillKey
-
-**Required State:**
-- Extract `taskId = skillKey.replace(/^tasks\//, '')`
-- Build `memoryBundle = { jobMemory, taskMemory }`
-- Call `enrichMemoriesWithScoping(taskId, 'task', memoryBundle)`
-- Call `generateContextMarkdown(taskId, 'task', enrichedBundle)`
-- Create `enrichedInput` with enriched memories and context
-- Execute via executor (not `runSkill`)
-
-**Impact:** HIGH - This is the core functionality
-
----
-
-### 2. ❌ Missing: WorexClientTasks Class
-
-**Current State:**
-- Uses `TaskSDK` class (wrong name)
-- Constructor takes `WorecesSkillsClientOptions` (wrong signature)
-
-**Required State:**
-- Class name: `WorexClientTasks`
-- Constructor: `(skillsClient: WorexClientSkills, executor: { execute(...) })`
-
-**Impact:** HIGH - API naming and architecture
-
----
-
-### 3. ❌ Missing: WorexClientSkills Import
-
-**Current State:**
-- Uses `WorecesSkillsClient` (old/deprecated name)
-- Found in: `src/core/task-sdk.ts`, `src/index.ts`, `src/strategies/*.ts`
-
-**Required State:**
-- Use `WorexClientSkills` from `@woroces/ai-skills`
-
-**Impact:** HIGH - Wrong API usage
-
----
-
-### 4. ❌ Missing: RunTaskResponse Type
-
-**Current State:**
-- Only re-exports `RunSkillResponse`
-- No `RunTaskResponse` type defined
-
-**Required State:**
-- `RunTaskResponse<TParsed = any>` type (can alias `RunSkillResponse`)
-- Exported in public API
-
-**Impact:** MEDIUM - Type clarity for API consumers
-
----
-
-### 5. ❌ Missing: Executor Pattern
-
-**Current State:**
-- No executor passed to constructor
-- Directly calls `client.runSkill()`
-
-**Required State:**
-- Executor passed to constructor
-- Executor is "no-enrichment execute primitive"
-- `executor.execute(enrichedInput, onNotFound)` called for DIRECT execution
-
-**Impact:** HIGH - Architecture and separation of concerns
-
----
-
-### 6. ❌ Missing: Task-Level Enrichment Methods
-
-**Current State:**
-- No calls to `enrichMemoriesWithScoping()`
-- No calls to `generateContextMarkdown()`
-- No `diagnoseSkillContent()` in not-found callback
-
-**Required State:**
-- Call `skillsClient.enrichMemoriesWithScoping(taskId, 'task', memoryBundle)`
-- Call `skillsClient.generateContextMarkdown(taskId, 'task', enrichedBundle)`
-- Call `skillsClient.diagnoseSkillContent(key)` in onNotFound callback
-
-**Impact:** HIGH - Missing core functionality
-
----
-
-### 7. ⚠️ Partial: README Documentation
-
-**Current State:**
-- README shows old API (`TaskSDK`, `WorecesSkillsClient`)
-- Describes algorithm but doesn't match implementation
-- Missing new class-based API examples
-
-**Required State:**
-- Update to show `WorexClientTasks` class
-- Show constructor with `skillsClient` and `executor`
-- Document canonical algorithm accurately
-- Add note about private package and naming leakage acceptance
-
-**Impact:** MEDIUM - Documentation accuracy
-
----
-
-### 8. ⚠️ Partial: Type Exports
-
-**Current State:**
-- Exports `RunTaskRequest`, `RunSkillResponse`, `ExecutionType`
-- Missing `RunTaskResponse`
-
-**Required State:**
-- Export `RunTaskResponse` type
-- Ensure all types are properly exported
-
-**Impact:** LOW - Type completeness
-
----
-
-## Implementation Status by File
-
-### ✅ Working (but needs refactor)
-- `.tests/test-run-task.ts` - Test passes with current implementation
-- Function-based API (`runTask` function) works
-
-### ❌ Needs Complete Rewrite
-- `src/core/task-sdk.ts` - Missing canonical algorithm, wrong class name, wrong constructor
-- `src/index.ts` - Wrong imports, missing class export
-
-### ⚠️ Needs Updates
-- `src/types/task-types.ts` - Missing `RunTaskResponse` type
-- `src/types/index.ts` - Missing `RunTaskResponse` export
-- `README.md` - Outdated API documentation
-- `examples/basic-usage.ts` - Uses old API
-
-### ✅ Can Keep (with updates)
-- `src/strategies/*.ts` - Strategy pattern files (may not be needed if simplified)
-- `src/builders/*.ts` - Builder pattern (can keep)
-- `src/methods/*.ts` - Convenience methods (can keep)
-
----
-
-## Verification Checklist (Current vs Required)
-
-| Item | Current | Required | Status |
-|------|---------|----------|--------|
-| Class name | `TaskSDK` | `WorexClientTasks` | ❌ |
-| Client import | `WorecesSkillsClient` | `WorexClientSkills` | ❌ |
-| Constructor | `(options?)` | `(skillsClient, executor)` | ❌ |
-| TaskId extraction | ❌ Missing | ✅ Required | ❌ |
-| Memory enrichment | ❌ Missing | ✅ Required (level='task') | ❌ |
-| Context generation | ❌ Missing | ✅ Required (level='task') | ❌ |
-| Executor pattern | ❌ Missing | ✅ Required | ❌ |
-| RunTaskResponse type | ❌ Missing | ✅ Required | ❌ |
-| Not-found diagnosis | ❌ Missing | ✅ Required | ❌ |
-| README accuracy | ⚠️ Partial | ✅ Complete | ⚠️ |
-
----
-
-## Priority Order for Implementation
-
-1. **P0 - Critical (Blocks functionality)**
-   - Implement canonical `runTask` algorithm
-   - Replace `TaskSDK` with `WorexClientTasks`
-   - Update to `WorexClientSkills`
-   - Add executor pattern
-
-2. **P1 - High (API correctness)**
-   - Add `RunTaskResponse` type
-   - Update constructor signature
-   - Add task-level enrichment calls
-   - Add not-found diagnosis callback
-
-3. **P2 - Medium (Documentation)**
-   - Update README with new API
-   - Update examples
-   - Add type exports
-
----
-
-## Notes
-
-- Test currently passes because it's using the function-based API that calls `runSkill` directly
-- The canonical algorithm is documented in `.docs/code-used-before/run-task.txt`
-- All required methods (`enrichMemoriesWithScoping`, `generateContextMarkdown`, `diagnoseSkillContent`) are confirmed to be public on `WorexClientSkills`
-- Executor comes from `WorexClientSkills` (method/property on the client)

package/.docs/integration-facts-ai-tasks.md

@@ -1,109 +0,0 @@
-# Integration facts: ai-tasks (for clean implementation)
-
-This doc answers “what you need to know about ai-tasks” for wiring and file paths. It does **not** answer everything; focus is on **(1) how LLMs are called** and **(3) how tasks are invoked** so you can write a tight Cursor brief with exact scaffolding.
-
----
-
-## 1. How ai-tasks calls LLMs today
-
-### No direct LLM calls in ai-tasks
-
-- **ai-tasks does not call an LLM API directly.** There is no `getClient()`, `aiGateway`, or provider router in this repo.
-- Narrix flows go through **external packages**: `@narrices/narrix-ingest` and `@narrices/narrix-runner`.
-- The “completion” from ai-tasks’ perspective is **`runner.run({ cni, datasetId, sourceMeta })`**. The actual LLM calls happen inside the narrix pack/runner (outside ai-tasks).
-
-### Where it’s wired
-
-| Concern | Location | Notes |
-|--------|----------|--------|
-| Client singleton | `src/narrix/narrixClient.ts` | `getNarrixClient()` returns `{ ingest, runner }`. Singleton `Promise<NarrixClient>`. |
-| Ingest | `defaultIngest` from `@narrices/narrix-ingest` | Used as-is. |
-| Runner | `createRunner()` from `@narrices/narrix-runner` | Created once with `runtime: { onProcessorNotMatched: "attachError", onMissingMapping: "attachError", deterministicSort: true }`. |
-| Usage | `src/narrix/runNarrixForRecord.ts`, `runNarrixForChat.ts`, `runNarrixForText.ts`, `runNarrixForDocs.ts` | Each gets client via `getNarrixClient()`, calls `ingest.toCni(...)` then `runner.run(...)`. |
-
-### Function signature that effectively “runs” the AI
-
-- **Ingest:** `ingest.toCni({ kind, input })` → CNI or error.
-- **Run:** `runner.run({ cni, datasetId, sourceMeta })` → `{ entity, signals, stories, passes, meta }`.
-
-So: **there is no shared “completion” or “getClient” for a generic LLM in ai-tasks.** If you need to add a new path that calls an LLM directly (e.g. OpenAI), you’d introduce that in ai-tasks (or in a separate gateway package) and document it here.
-
-### Prompt templates
-
-- **No prompt-templates system in ai-tasks.** Prompts live inside the narrix packs/runner. The only “template”-like behavior in ai-tasks is in the **task SDK** when running non-local tasks: it uses `generateContextMarkdown` and builds a prompt from skill content + memory (see `task-sdk.ts`). For **local tasks** (e.g. narrix), the handler only receives `{ input, ctx }` and returns a value; no prompt assembly in this repo.
-
----
-
-## 2. Where runtime config lives
-
-- **Env vars:** Primary. Examples:
-  - `USE_NARRIX_INGEST` → `"1"` to enable narrix (see `src/narrix/flags.ts`).
-  - `NARRIX_DEBUG` → `"1"` for debug logs (`src/narrix/task.ts`).
-  - `NARRIX_DATASET_ID`, `NARRIX_PLAYGROUND_IN`, `NARRIX_PLAYGROUND_OUT` for playgrounds (e.g. `narrixSubnetPlayground.ts`).
-  - `MONGO_LOGS_DB` for task SDK / execution memory (e.g. `task-sdk.ts`, `index.ts`).
-- **Flags module:** `src/narrix/flags.ts` — single export `narrixFlags = { useNarrixIngest: process.env.USE_NARRIX_INGEST === "1" }`. No other centralized flags in src.
-- **No separate config file or config module** in the repo; everything is env-driven or hardcoded defaults.
-
----
-
-## 3. How tasks are invoked
-
-### narrixRunHandler: direct vs registry
-
-- **Registered in the task registry** and also **callable directly**:
-  - **Registry:** `src/narrix/index.ts` does `registerLocalTask(NARRIX_RUN_SKILL_KEY, narrixRunHandler)` with `NARRIX_RUN_SKILL_KEY = "skills/skill.local:narrixRun"`. So when the SDK looks up the handler by `skillKey`, it gets the handler from the registry and runs it.
-  - **Direct:** Tests and playground code call `narrixRunHandler({ input, ctx })` directly (e.g. `test/narrix/record.test.ts`, `src/localTasks/narrixSubnetPlayground.ts`).
-
-### How the dispatcher invokes the handler
-
-- **Entry:** `WorexClientTasks.runTask(input)` in `src/core/task-sdk.ts`.
-- **Lookup:** `handler = getLocalTask(request.skillKey)` from `src/localTasks/registry.js` (registry is keyed by full skillKey, e.g. `skills/skill.local:narrixRun`).
-- **Invocation:** `await handler({ input: input.input, ctx })` where `ctx` is built from the request (see below). So the handler receives **one argument: `{ input, ctx }`**.
-
-### Handler signature (what you can rely on)
-
-```ts
-// src/localTasks/types.ts
-type LocalTaskHandler = (args: {
-  input: any;   // ← request.input (RunTaskRequest.input)
-  ctx: LocalTaskContext;
-}) => Promise<any>;
-```
-
-- **`input`** = `RunTaskRequest.input` (the task payload; for narrix: `medium`, `datasetId`, `record`/`text`/`document`/`thread`, etc.).
-- **`ctx`** = `{ skillKey, jobMemory, taskMemory, executionMemory, variables, jobId, agentId, graphId, nodeId, prevNodeId, coreSkillId, masterSkillId, masterSkillActivityId }` (all from the request).
-
-### Can arguments include an options object?
-
-- **Yes, but only via the single `input` object.** The handler does **not** get a second “options” parameter. So any options must be:
-  - **Inside `request.input`** (e.g. `input.options` or `input.someFlag`), or
-  - **In `ctx.variables`** (e.g. `ctx.variables.options`).
-- `RunTaskRequest` extends `RunSkillRequest` and includes `input`, `variables`, `jobMemory`, `taskMemory`, `executionMemory`, etc. So callers can pass an options object as part of `input` or via `variables`; the handler reads it from `args.input` or `args.ctx.variables`.
-
----
-
-## 4. Where you’re allowed to store artifacts (dev/prod)
-
-- **In repo:** Playgrounds write under **local filesystem** only, e.g. `.tests/test-output/subnets`, `.tests/test-output/assets`, etc., with paths from env or defaults (`NARRIX_PLAYGROUND_IN`, `NARRIX_PLAYGROUND_OUT`).
-- **No S3/Blob storage** or artifact service is referenced in `src/`. So for now: **local filesystem only** in dev; prod artifact behavior is undefined in this codebase.
-- **Retention:** No retention rules or “store nothing” policy is implemented in ai-tasks. If you need retention or “no persistence,” that would be a new contract (e.g. in a wrapper or platform that calls ai-tasks).
-
----
-
-## 5. Downstream contract (who consumes the narrix result)
-
-- **Who consumes:** Anything that calls `runTask` (or the executor) and gets back a `RunTaskResponse<TParsed>`. For **local tasks**, the response is built in `task-sdk.ts`: the handler’s return value is used as `parsed` and also stringified into `rawText` and `flexMd.payloads.value`.
-- **Response shape (local task):**
-  - `skillKey`, `rawText` (JSON string of handler result), `flexMd: { frame: "localTask.v1", payloads: { value: "<same JSON>" } }`, `parsed` (handler result), `metadata: { instructionVersion: "local", activityId, durationMs, localSkillKey }`.
-- **answerMarkdown:** Not present in current narrix types or local-task response. The narrix output types (`NarrixRunOutput`) have `entity`, `signals`, `stories`, `passes`, `meta` — no `answerMarkdown`. If downstream wants markdown:
-  - Either add it to the handler’s return value (and thus to `parsed` and `flexMd.payloads`) in the same response object, or
-  - Store it elsewhere and put a ref in the response (would require a new convention and possibly artifact storage).
-
----
-
-## Quick reference for (1) and (3)
-
-- **LLM:** ai-tasks does not call an LLM directly. Narrix uses `getNarrixClient()` → `ingest.toCni()` + `runner.run()`. No shared getClient/aiGateway; no prompt-templates system in repo.
-- **Task invocation:** `narrixRunHandler` is registered under `skill.local:narrixRun` and invoked by the SDK with **one argument: `{ input, ctx }`**. `input` = `RunTaskRequest.input`; options only via `input` or `ctx.variables`. No second “options” parameter.
-
-Use this plus the exact file paths above for a minimal-assumptions Cursor brief and code scaffolding.