@exellix/ai-tasks 8.4.2 → 8.5.0

package/.docs/DOWNSTREAM_ENV.md

@@ -0,0 +1,42 @@
+# Downstream / upstream environment variables
+
+This document lists which env vars **ai-tasks** uses itself and which are consumed **downstream** (by @woroces/ai-skills, @athenices/ai-gateway, @athenices/ai-provider-router, @athenices/ai-activities-tracking). ai-tasks does **not** read router or Mongo collection env vars; they are used by dependencies. For full reference, see each package’s docs.
+
+---
+
+## Env vars used by ai-tasks
+
+| Variable | Purpose | Default |
+|----------|---------|--------|
+| `MONGO_LOGS_DB` | Default database name for activity logs; passed as `bindingDefaultsDb` to the skills client and used downstream for routing. | `logs-db` |
+
+---
+
+## Env vars consumed downstream (when using ai-tasks)
+
+These affect behavior when you run LLM-backed tasks or activity tracking but are **not** read by ai-tasks. They are used by ai-skills → ai-gateway → ai-provider-router and ai-activities-tracking.
+
+### Provider / router (ai-gateway, ai-provider-router)
+
+| Variable | Purpose |
+|----------|--------|
+| `OPEN_ROUTER_KEY` or `OPENROUTER_API_KEY` | Use OpenRouter for LLM calls; no need to register providers when set. |
+| `USE_OPENROUTER` | Can enable or disable OpenRouter when set. |
+
+Other provider keys (e.g. `OPENAI_API_KEY`, `GROK_API_KEY`) are validated by **ai-skills** at init; for OpenRouter-only setups, ai-skills must accept `OPEN_ROUTER_KEY` / `OPENROUTER_API_KEY` in its provider check.
+
+### Activity tracking (ai-gateway → ai-activities-tracking)
+
+| Variable | Purpose | Default (in ai-activities-tracking) |
+|----------|---------|-------------------------------------|
+| `MONGO_LOGS_COLLECTION` | Main activities collection name. | `cognitive-activities` |
+| `MONGO_BAD_REQUESTS_COLLECTION` | Bad/validation-failure requests collection name. | `ai-bad-requests` |
+
+Both are **optional**; safe to leave unset. If unset or unresolved, ai-activities-tracking uses the defaults above and never uses the env var name as the collection name.
+
+---
+
+## Summary
+
+- **ai-tasks** only reads `MONGO_LOGS_DB` (for `bindingDefaultsDb`). All other Mongo and router env vars are used by downstream packages.
+- For “No provider specified and no providers registered” and collection-name issues, fixes live in ai-provider-router, ai-gateway, and ai-activities-tracking. Ensure you use versions of `@athenices/ai-gateway` (and thus ai-activities-tracking) that include those fixes.

package/.docs/FEEDBACK_TO_CLIENT_DOWNSTREAM_FIXES.md

@@ -0,0 +1,64 @@
+# Feedback to client (worox-graphs): downstream fixes for the two reported issues
+
+**Audience:** Consumer of `@woroces/ai-tasks` (e.g. `@woroces/worox-graph`) who reported the router and Mongo collection-name issues.  
+**From:** ai-tasks maintainers  
+**Date:** 2026-02-23
+
+---
+
+## Summary
+
+Both issues you reported were **downstream** of ai-tasks (in ai-provider-router, ai-gateway, and ai-activities-tracking). They are fixed in those packages. **No change is required in your application (worox-graphs).** After upgrading to versions that include the fixes, the problems should be resolved.
+
+---
+
+## 1. “No provider specified and no providers registered”
+
+**What you saw:** The router threw this error even when `OPEN_ROUTER_KEY` was set; your app only calls `ai-tasks.runTask()` and does not register any provider.
+
+**Where it was fixed:** In `@athenices/ai-provider-router` and/or `@athenices/ai-gateway`:
+
+- OpenRouter is now considered (and can be used) **before** the “no providers registered” check, so when `OPEN_ROUTER_KEY` (or `OPENROUTER_API_KEY`) is set, the router can resolve a provider without your app registering anything.
+- Error messaging was improved to point to setting `OPEN_ROUTER_KEY` or registering a provider when no provider can be used.
+
+**What you should do:**
+
+- **Upgrade** so your resolved dependency stack includes the **fixed ai-gateway** (and thus the fixed ai-provider-router). That usually means upgrading `@woroces/ai-tasks` to a version that depends on the fixed ai-gateway (e.g. ai-tasks 2.8.x with ai-gateway ^7.3.1 or the version that includes the router fix), then run `npm install`.
+- Ensure **`OPEN_ROUTER_KEY`** (or `OPENROUTER_API_KEY`, depending on what the gateway reads) is set in your environment when you want to use OpenRouter. Load `.env` before the process starts (e.g. via dotenv/dotenvx) as you already do.
+- You do **not** need to create or configure the router or register any provider in your app.
+
+---
+
+## 2. Mongo collection names (ENV.MONGO_BAD_REQUESTS_COLLECTION etc.)
+
+**What you saw:** When `MONGO_LOGS_COLLECTION` / `MONGO_BAD_REQUESTS_COLLECTION` were unset, the app used the env var name (or an `ENV.*` token) as the MongoDB collection name, creating collections like `ENV.MONGO_BAD_REQUESTS_COLLECTION`.
+
+**Where it was fixed:** In `@athenices/ai-activities-tracking`:
+
+- Defaults were added: **`cognitive-activities`** for the main logs collection and **`ai-bad-requests`** for the bad-requests collection.
+- Collection names are normalized so that unset or unresolved `ENV.*` tokens are never used as collection names; the default is used instead.
+
+**What you should do:**
+
+- **Upgrade** so your resolved stack includes the **fixed ai-activities-tracking** (typically by depending on a version of ai-gateway that depends on the fixed ai-activities-tracking). Upgrading ai-tasks (and ensuring ai-gateway is updated) will pull in the fixed version.
+- You **do not** need to set `MONGO_LOGS_COLLECTION` or `MONGO_BAD_REQUESTS_COLLECTION` unless you want to override the defaults. If they are unset or unresolved, the packages now use `cognitive-activities` and `ai-bad-requests` and never the env var name.
+
+---
+
+## No changes required in your repo
+
+- **worox-graphs** does not need to create or configure the AI router, register providers, or read Mongo collection env vars. The fixes are entirely in the packages that implement that behavior (ai-provider-router, ai-gateway, ai-activities-tracking).
+- Your only required action is to **upgrade** to versions that include these fixes (via `@woroces/ai-tasks` and its dependency tree). Optional: ensure `OPEN_ROUTER_KEY` (or `OPENROUTER_API_KEY`) is set when using OpenRouter.
+
+---
+
+## Upgrade checklist
+
+| Step | Action |
+|------|--------|
+| 1 | Upgrade `@woroces/ai-tasks` to a version that depends on the fixed ai-gateway (e.g. ^2.8.x with ai-gateway that includes the router fix). |
+| 2 | Run `npm install` (or your package manager’s equivalent) so the lockfile resolves to the fixed ai-gateway and its transitive deps (ai-provider-router, ai-activities-tracking). |
+| 3 | Ensure `.env` is loaded before the process starts and contains `OPEN_ROUTER_KEY` (or `OPENROUTER_API_KEY`) when using OpenRouter. |
+| 4 | Optionally leave `MONGO_LOGS_COLLECTION` and `MONGO_BAD_REQUESTS_COLLECTION` unset; they now default to `cognitive-activities` and `ai-bad-requests`. |
+
+If you still see “No provider specified and no providers registered” after upgrading, confirm that the resolved `@athenices/ai-gateway` (and `@athenices/ai-provider-router`) in your lockfile are the versions that include the OpenRouter fix, and that your env key (`OPEN_ROUTER_KEY` or `OPENROUTER_API_KEY`) is set before any gateway call.

package/.docs/INTERMEDIATE_STEPS.md

@@ -0,0 +1,82 @@
+# Structured intermediate results for combined / multi-step tasks
+
+When a task (or skill) runs multiple logical steps in one invocation (e.g. “to-cni + enrich + triage”), the response can include structured data for each sub-step so consumers can inspect and report what happened “in between” without extra round-trips.
+
+## Response shape
+
+Task responses may include an optional top-level **`intermediateSteps`** array. When present, it describes each step performed in order.
+
+### Type: `IntermediateStep`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `step` | number | yes | 1-based order in the execution chain |
+| `id` | string | yes | Stable identifier (e.g. `"to-cni"`, `"engine-enrich"`, `"triage-q1-q6"`) |
+| `ok` | boolean | yes | Whether this step completed successfully |
+| `summary` | string | no | Short summary (e.g. `"cni built"`, `"enriched"`) |
+| `error` | string | no | Error message when `ok` is false |
+| `inputSummary` | object \| string | no | Summary input (e.g. keys/ids) for reporting |
+| `outputExcerpt` | object | no | Small excerpt of step output for debugging; keep small to avoid payload bloat |
+
+### Example response
+
+```json
+{
+  "success": true,
+  "output": { "answers": {}, "decision": {} },
+  "intermediateSteps": [
+    { "step": 1, "id": "to-cni", "summary": "cni built", "ok": true },
+    { "step": 2, "id": "engine-enrich", "summary": "enriched", "ok": true },
+    { "step": 3, "id": "triage-q1-q6", "summary": "answers Q1,Q6", "ok": true }
+  ]
+}
+```
+
+With optional excerpts for debugging:
+
+```json
+{
+  "intermediateSteps": [
+    { "step": 1, "id": "to-cni", "ok": true, "outputExcerpt": { "cni": { "subject": {} } } },
+    { "step": 2, "id": "engine-enrich", "ok": true, "outputExcerpt": { "record": {} } },
+    { "step": 3, "id": "triage-q1-q6", "ok": true }
+  ]
+}
+```
+
+## How it works in ai-tasks
+
+- **Skills/tasks** that perform multiple logical steps may return `intermediateSteps` either:
+  - **Top-level** on the response (if the executor passes it through), or
+  - **Inside `parsed`** as `parsed.intermediateSteps`.
+- **Task SDK** normalizes so that the **top-level** `response.intermediateSteps` is the canonical place:
+  - For **local tasks**: if the handler returns an object with `intermediateSteps`, they are lifted to the response and omitted from `parsed`.
+  - For **executor (DIRECT)** results: if `result.parsed.intermediateSteps` is present, it is lifted to `result.intermediateSteps` and removed from `parsed`.
+- **NARRIX_THEN_DIRECT**: the runtime prepends a step `{ step: 1, id: "narrix", ok: true, summary: "narrix run completed" }` and renumbers any steps from the direct phase (step 2, 3, …).
+
+## Consumer usage
+
+Consumers (e.g. worox-graphs playground reporter) can:
+
+1. **Persist or display** the chain (e.g. “Step 1: to-cni → Step 2: engine-enrich → Step 3: triage-q1-q6”).
+2. **Optionally link to or embed** excerpts of intermediate payloads when `outputExcerpt` is present.
+3. Use the list to get visibility equivalent to per-node request/response files, without requiring separate graph nodes for each step.
+
+## TypeScript
+
+```ts
+import type { RunTaskResponseWithSteps, IntermediateStep, IntermediateSteps } from "@woroces/ai-tasks";
+
+const res: RunTaskResponseWithSteps<MyOutput> = await runTask(request);
+if (res.intermediateSteps) {
+  for (const s of res.intermediateSteps) {
+    console.log(`Step ${s.step}: ${s.id} ${s.ok ? "ok" : s.error}`);
+  }
+}
+```
+
+## Acceptance criteria (reference)
+
+- A combined task can return an optional list of intermediate steps in execution order.
+- Each step has a stable identifier and success flag; optional summary or excerpt is supported.
+- Consumers can use this list to render a “chain” view (e.g. in reports or playground) equivalent to the current per-node visibility, without requiring separate graph nodes for each step.

package/.docs/activity-structure.md

@@ -0,0 +1,31 @@
+# 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

@@ -0,0 +1,338 @@
+# 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

@@ -0,0 +1,74 @@
+# 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 | Normalized by |
+|------|--------|---------------|
+| Xynthesis (PRE/POST/scoping/utilities) | `preActionModel`, `postActionModel`, step `llmCall.model` | `resolveModelReferenceForXynthesis` → `toStrictAiProfileResolveInput` |
+| ai-skills MAIN | `skillModel`, `RunTaskRequest.llmCall.model` | `resolveModelReference` → concrete `provider/model` |
+
+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.
+
+## 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).
+- Optional: pre-resolve aliases in graph-engine 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
+- `listAiTasksProfileChoices`, `listAiTasksProfiles`, `listAiTasksProfileChoiceKeys`
+
+See [README — Model profile aliases](../README.md#model-profile-aliases-x12iai-profiles).