@exellix/ai-tasks 9.1.0 → 10.0.0

package/.docs/activity-structure.md

@@ -1,31 +0,0 @@
-# Activity Structure (Activix)
-
-Activix activity records follow a layered structure:
-
-- **Lifecycle-owned fields** (managed by Activix):
-  - identifiers (primary key / activity id)
-  - `status` and lifecycle transitions
-  - timing fields (`startTime`, `endTime`, `duration`)
-  - error fields (via `failRecord`)
-- **Integrator-owned fields** (provided by the caller):
-  - `runContext` (correlation envelope)
-  - `outer` (required I/O payload tier)
-  - optional `inner` (structured sub-steps / nested call payload)
-
-## `outer` (required)
-
-`outer` is the canonical “activity I/O” tier and should include:
-
-- `input`: domain input payload
-- `output`: domain output payload (or omitted/null until completion)
-- `metadata`: object for domain tags (type, version, sizes, routing keys, etc.)
-
-## `inner` (optional)
-
-Use `inner` for nested request/response payloads when you want structured visibility into sub-work (e.g. a tool call inside a broader activity).
-
-## Ownership rules
-
-- Do **not** manually set lifecycle-owned fields (`status`, timestamps, ids).
-- Avoid duplicating correlation identifiers in multiple places; prefer `runContext`.
-

package/.docs/ai-task-ai-scoping-spec.md

@@ -1,338 +0,0 @@
-# AI Task Input Scoping (aiScoping) — Detailed Specification
-
-## 1) Purpose
-
-Add an **optional** pre-processing mode for `runTask` that can scope large memory content into compact, task-focused snippets before the main AI task call.
-
-The mode introduces a new request field:
-
-- `aiScoping?: Array<{ source: string; instructions: string; targetToken: string }>`
-
-Each `aiScoping` item triggers an **internal AI call** (in parallel), which:
-
-1. Reads data from memory using `source`.
-2. Applies `instructions` to that source content.
-3. Writes result into `aiScoped` as:
-   - `{ token: targetToken, scopedInfo: string }`
-
-The final main AI task then receives `aiScoped` as part of its input/context.
-
----
-
-## 2) Goals
-
-- Reduce prompt bloat when memory has large/irrelevant content.
-- Allow targeted extraction/summary/selection from specific memory paths.
-- Run scoping calls in parallel to minimize added latency.
-- Keep this behavior strictly optional and backward compatible.
-
-## 3) Non-goals
-
-- No changes to existing behavior when `aiScoping` is not provided.
-- No mandatory schema migration for existing callers.
-- No change to current Narrix flow semantics.
-- No implementation in this phase (spec/design only).
-
----
-
-## 4) API Contract Changes
-
-## 4.1 Request (new optional field)
-
-Add to `RunTaskRequest`:
-
-```ts
-type AIScopingInstruction = {
-  source: string;        // path to memory value
-  instructions: string;  // prompt for internal scoping call
-  targetToken: string;   // label for downstream use
-};
-
-interface RunTaskRequest {
-  // ...existing fields
-  aiScoping?: AIScopingInstruction[];
-}
-```
-
-### Field semantics
-
-- `source`
-  - Dot-path to a memory value, including nested properties.
-  - Must resolve to a value in the memory bundle available during execution.
-- `instructions`
-  - Natural-language guidance for the internal scoping call.
-  - Should describe desired output format/constraints.
-- `targetToken`
-  - Logical name of the scoped result.
-  - Used in output as `aiScoped[].token`.
-
-## 4.2 Derived runtime output (new runtime data)
-
-During execution (when `aiScoping` is provided), construct:
-
-```ts
-type AIScopedItem = {
-  token: string;
-  scopedInfo: string;
-};
-
-type AIScoped = AIScopedItem[];
-```
-
-Result is injected into the main task execution input/context as:
-
-- `input.aiScoped: AIScoped` (preferred canonical location), and/or
-- equivalent context markdown section (optional, implementation choice).
-
-Note: This does **not** require changing external `RunTaskResponse` shape.
-
----
-
-## 5) Source Resolution Rules
-
-`source` must resolve from execution memory roots. Canonical roots:
-
-- `jobMemory.*`
-- `taskMemory.*`
-- `executionMemory.*`
-
-Examples:
-
-- `jobMemory.customerProfile`
-- `jobMemory.records.current.incidents`
-- `taskMemory.previousFindings`
-- `executionMemory.executionLog.steps`
-
-### Resolution behavior
-
-1. If `source` is missing/invalid/unresolvable:
-   - The item is treated as failed scoping item.
-   - It does not break full task execution (default tolerant mode).
-2. If resolved value is object/array:
-   - Serialize to deterministic JSON string for internal scoping input.
-3. If resolved value is primitive:
-   - Convert to string.
-4. If resolved value is empty:
-   - Proceed with empty content marker or skip item (implementation choice, see error policy).
-
----
-
-## 6) Execution Flow (Normative)
-
-When `aiScoping` exists and has items:
-
-1. Build the enriched memory bundle as usual (current behavior unchanged).
-2. For each `aiScoping` item:
-   - Resolve `source` from memory bundle.
-   - Build internal AI call input with:
-     - resolved source content
-     - item `instructions`
-     - output requirement: plain text scoped result
-3. Dispatch all internal AI scoping calls **in parallel**.
-4. Collect all fulfilled results into:
-   - `aiScoped: Array<{ token, scopedInfo }>`
-5. Inject `aiScoped` into main task input/context.
-6. Execute main task call as normal.
-
-If `aiScoping` is absent or empty:
-
-- skip all scoping logic;
-- execute current pipeline exactly as today.
-
----
-
-## 7) Internal AI Scoping Call Contract
-
-Each internal call should be deterministic and constrained:
-
-- Input:
-  - `instructions` (caller-provided)
-  - `sourceContent` (resolved from memory)
-- Expected output:
-  - single string (scoped information)
-- Output post-processing:
-  - trim surrounding whitespace
-  - enforce max length safeguards (implementation-configurable)
-
-Suggested prompt policy for internal calls:
-
-- "Use only provided source content."
-- "Do not invent missing facts."
-- "Return concise scoped result for downstream AI task."
-
----
-
-## 8) Parallelism and Performance
-
-### Parallel execution requirement
-
-- All scoping items should run concurrently for latency efficiency.
-
-### Concurrency limits
-
-- Use bounded concurrency (recommended) to avoid overload.
-- Suggested default: 3–8 concurrent calls (configurable).
-
-### Ordering
-
-- Preserve original `aiScoping` order in final `aiScoped` output.
-- If futures resolve out-of-order, reorder results before injection.
-
-### Timeouts
-
-- Apply per-item timeout.
-- Timeout should fail only the scoping item, not the main task (default tolerant mode).
-
----
-
-## 9) Error Handling Policy
-
-Default policy: **tolerant** (recommended for backward compatibility and resilience).
-
-- If one scoping item fails (resolution error, timeout, internal AI error):
-  - other items continue;
-  - successful items still populate `aiScoped`;
-  - main task still executes.
-
-Failure visibility:
-
-- Log/metadata should include failed item info (`targetToken`, failure reason).
-- Avoid leaking sensitive source data into error logs.
-
-Optional future extension (not required now):
-
-- strict mode that aborts task when any scoping item fails.
-
----
-
-## 10) Validation Rules
-
-Before execution, validate `aiScoping` items:
-
-- `source`: non-empty string
-- `instructions`: non-empty string
-- `targetToken`: non-empty string
-- `targetToken` uniqueness recommended within one request
-
-If duplicates exist:
-
-- recommended behavior: last-write-wins **or** reject request; choose one and document in implementation.
-- preferred for predictability: reject duplicates with clear error.
-
----
-
-## 11) Security and Privacy
-
-- Treat resolved `source` content as sensitive memory material.
-- Do not log raw source payloads in plaintext logs.
-- Internal scoping calls must receive only needed source slice (not entire memory bundle).
-- Respect existing gateway/client auth and model policies.
-
----
-
-## 12) Integration Points (Current Codebase Guidance)
-
-Expected integration in `runTask` DIRECT path:
-
-- after memory enrichment (so scoped reads use enriched memory),
-- before final executor call (so `aiScoped` is available to main task input/context).
-
-Natural integration area: logic near `_executeDirect(...)` where enriched bundle and context are built.
-
-No Narrix-specific branching is required; this feature is generic and optional for any task execution type that reaches DIRECT execution.
-
----
-
-## 13) Example Request/Derived Output
-
-## 13.1 Example request
-
-```json
-{
-  "skillKey": "tasks/example",
-  "input": {
-    "goal": "Produce executive incident summary"
-  },
-  "jobMemory": {
-    "incidentDump": {
-      "tickets": ["...large data..."]
-    },
-    "customerContext": {
-      "name": "Acme",
-      "tier": "enterprise"
-    }
-  },
-  "aiScoping": [
-    {
-      "source": "jobMemory.incidentDump",
-      "instructions": "Extract only high-severity incidents from last 7 days with one-line impact each.",
-      "targetToken": "recentCriticalIncidents"
-    },
-    {
-      "source": "jobMemory.customerContext",
-      "instructions": "Summarize customer profile relevant to incident communication tone.",
-      "targetToken": "customerCommunicationProfile"
-    }
-  ]
-}
-```
-
-## 13.2 Derived scoped output injected to final task
-
-```json
-{
-  "aiScoped": [
-    {
-      "token": "recentCriticalIncidents",
-      "scopedInfo": "..."
-    },
-    {
-      "token": "customerCommunicationProfile",
-      "scopedInfo": "..."
-    }
-  ]
-}
-```
-
----
-
-## 14) Backward Compatibility
-
-- If `aiScoping` is omitted: execution remains exactly current behavior.
-- Existing clients and builders remain valid.
-- Existing tasks do not need modification.
-- Feature is opt-in per request.
-
----
-
-## 15) Test Plan (for future implementation)
-
-Unit tests:
-
-- validation of `aiScoping` items (required fields, duplicate tokens)
-- source path resolution (valid, invalid, nested, primitive/object/array)
-- deterministic output ordering under parallel completion
-- tolerant failure behavior (partial success still runs main task)
-
-Integration tests:
-
-- end-to-end DIRECT execution with `aiScoping` and injected `input.aiScoped`
-- timeout and internal call failure handling
-- no-regression test: request without `aiScoping` matches current behavior
-
-Performance tests:
-
-- compare serial vs parallel scoping latency with multiple items
-- verify bounded concurrency behavior under high item counts
-
----
-
-## 16) Acceptance Criteria
-
-1. `RunTaskRequest` accepts optional `aiScoping`.
-2. Each scoping item triggers internal AI scoping based on memory `source` + `instructions`.
-3. Scoping calls execute in parallel (with bounded concurrency).
-4. Results are available to main task as `aiScoped: [{ token, scopedInfo }]`.
-5. Absence of `aiScoping` preserves current behavior with no output/flow regressions.
-6. Failures in individual scoping items do not break the main task by default.
-

package/.docs/ai-tasks-model-profile-aliases-7x.md

@@ -1,96 +0,0 @@
-# Model profile aliases (graph-engine 7.x+ / ai-tasks 8.4+)
-
-Wire contract for **`RunTaskRequest.modelConfig`** and per-stage **`llmCall.model`** when using **`@x12i/ai-profiles`** instead of concrete provider ids.
-
-## Required triplet (8.4+)
-
-Every `runTask()` call must set all three slots:
-
-| Slot | Role | xynthesis vs ai-skills |
-|------|------|------------------------|
-| `preActionModel` | PRE synthesis / utility | **ai-profiles alias only** → xynthesis |
-| `skillModel` | MAIN skill | alias **or** concrete id → ai-skills |
-| `postActionModel` | POST audit/polish/scoping | **ai-profiles alias only** → xynthesis |
-
-```json
-{
-  "preActionModel": "cheap/default",
-  "skillModel": "pro/default",
-  "postActionModel": "cheap/default"
-}
-```
-
-## Accepted alias shapes
-
-| Shape | Example | Notes |
-|-------|---------|-------|
-| `profile/choice` | `cheap/default`, `json/default` | Preferred — sync-checkable via `isKnownProfileChoice` |
-| Bare profile | `cheap`, `pro` | Expanded to `profile/default` at invoke (`toStrictAiProfileResolveInput`) |
-| `@` form | `cheap@default`, `pro@fast` | Normalized to `profile/choice` before `resolveAIProfile` |
-
-**List keys:** `listAiTasksProfileChoiceKeys()` / `listAiTasksProfileChoices()` from `@exellix/ai-tasks` (text lane, bundled or remote registry).
-
-## Rejected (legacy)
-
-- Graph-era tiers: `weak`, `strong`
-- Deprecated slots: `xynthesisModel`, root `modelConfig.model`
-- Host token caps: `maxTokens`, `maxTokensCap` on task payloads
-- Removed ai-profiles 2.0 shortcuts: `cheapest`, sync `isKnownProfileOrShortcut`
-
-Unknown profile keys fail at **`resolveAIProfile`** with a clear error.
-
-## Resolution boundaries
-
-| Path | Fields at ingress (before `resolveRunTaskModelReferences`) | Internal transform |
-|------|----------------------------------------------------------|--------------------|
-| **PRE / POST (xynthesis)** | `preActionModel`, `postActionModel`, step `llmCall.model` — **ai-profiles alias required** | `resolveModelReferenceForXynthesis` → `profile/choice` keys only |
-| **MAIN (ai-skills)** | `skillModel`, root `llmCall.model` — alias **or** concrete provider id | `resolveModelReference` → concrete `provider/model` for gateway |
-
-Concrete ids (`openrouter/...`, `anthropic/claude-...`, `openai/gpt-5`) pass through on **`skillModel`** only. PRE/POST must stay ai-profiles aliases under `@exellix/xynthesis` ≥ 4.3.1.
-
-### Ingress rule for hosts (graph-engine, studio BFF)
-
-> **Do not** pre-resolve `preActionModel` or `postActionModel` to OpenRouter/OpenAI model ids. Pass through profile keys, `profile/choice`, or shortcut keys (e.g. `cheap`, `cheap/default`).
-
-> **`skillModel`** may still be a concrete provider id at ingress.
-
-### Internal rule (ai-tasks)
-
-> `resolveRunTaskModelReferences` is the **only** place that transforms aliases on xynthesis paths at `runTask` entry. If a concrete id is detected on a xynthesis slot, ai-tasks fails with stable code **`XYNTHESIS_CONCRETE_MODEL_REJECTED`** (typed `RunTaskModelResolutionError`, not a generic wrapper).
-
-### Stable pre-MAIN error codes
-
-| Condition | `error.code` |
-|-----------|--------------|
-| Concrete id on xynthesis slot | `XYNTHESIS_CONCRETE_MODEL_REJECTED` |
-| Unknown / unresolvable alias | `XYNTHESIS_ALIAS_RESOLUTION_FAILED` |
-| PRE synthesis enabled but required paths empty | `SYNTHESIS_INPUT_EMPTY` |
-
-Failures emit logxer diagnostics with `failureClassification.role: "cause"` and event ids such as `xynthesis_concrete_model_rejected`. Hosts (graph-engine CR-7) should preserve `error.code` and `failureClassification` on attempt records instead of collapsing to `TASK_RUN_FAILED` / `classification: other`.
-
-## graph-engine guidance
-
-- Send the triplet on every node/task compile — no env defaults, no `"balanced"` fallback.
-- Prefer explicit **`profile/choice`** keys in compiled payloads; bare profile keys are OK (ai-tasks normalizes before xynthesis).
-- **Do not** pre-resolve `preActionModel` / `postActionModel` to concrete provider ids — pass aliases and let ai-tasks normalize at `runTask` entry (see ingress rule above).
-- Optional: pre-resolve **`skillModel`** aliases for diagnostics; ai-tasks re-resolves at invoke (idempotent for concrete ids).
-- Do **not** npm-override `@x12i/ai-profiles` or pin `<2.1`.
-
-## Stack minimums
-
-| Package | Minimum |
-|---------|---------|
-| `@exellix/ai-tasks` | 8.4.x |
-| `@x12i/ai-profiles` | 2.1.0 |
-| `@exellix/xynthesis` | 4.3.1 |
-| `@exellix/ai-skills` | 6.0.0 |
-
-## Public helpers (`@exellix/ai-tasks`)
-
-- `toStrictAiProfileResolveInput` — bare profile → `profile/default`
-- `resolveModelReference` / `resolveModelReferenceForXynthesis`
-- `isResolvableModelAlias` — true for known **`profile/choice`** keys only
-- `RunTaskModelResolutionError`, `isRunTaskModelResolutionError` — stable pre-MAIN model slot failures
-- `listAiTasksProfileChoices`, `listAiTasksProfiles`, `listAiTasksProfileChoiceKeys`
-
-See [README — Model profile aliases](../README.md#model-profile-aliases-x12iai-profiles).