@exellix/ai-tasks 8.5.3 → 8.6.2

package/documenations/studio-skill-invoke-preflight.md

@@ -0,0 +1,298 @@
+# Studio skill invoke preflight (suggested design)
+
+**Status:** Reference for **studio / skills-manager** products — **not** implemented by `@exellix/ai-tasks` or `@exellix/ai-skills` at runtime.
+
+**Intent:** This document captures functionality that **used to ship inside the runtime stack** (through `@exellix/ai-tasks` 8.5.x and older `@exellix/ai-skills` exports) and describes a **suggested** way to provide it in studio. Studio teams may follow this design, adapt it, or replace it entirely. Nothing here is required for `runTask()` or `runSkill()` to work.
+
+**Related (runtime, still supported):**
+
+| Package | Runtime preflight (orchestrator / engine) |
+|---------|---------------------------------------------|
+| `@exellix/ai-tasks` | `validateRunTaskConfig`, `validateRunTaskInvoke`, `analyzeExpectedRunTaskInput`, `checkExpectedInputAgainstRequest` |
+| `@exellix/ai-skills` | `validateModelConfigForInvoke`, `diagnoseSkillInCatalog`, Catalox template fetch helpers |
+| `@exellix/ai-skills` | [`SKILLS_MANAGER_CLIENT_GUIDE.md`](../../ai-skills/docs/SKILLS_MANAGER_CLIENT_GUIDE.md) — responsibility split |
+
+---
+
+## Why this moved out of runtime
+
+| Layer | Should do | Should not do |
+|-------|-----------|----------------|
+| **Runtime** (`ai-tasks`, `ai-skills`, `xynthesis`) | Execute hops; minimal shape validation; Optimixer budgets; gateway/funcx invoke | Authoring “Run analysis”, invoke-packet UI, FuncX wiring for studio |
+| **Studio / skills-manager** | Preflight before save or before “Run task”; template/smartInput review; optional LLM critique | Replace `runSkill` or bypass Optimixer on invoke |
+
+From **`@exellix/ai-tasks` 8.6.0** and **`@exellix/ai-skills` ≥ 6.1.0**, the following were **removed from runtime exports** (see [CHANGELOG](../CHANGELOG.md)).
+
+---
+
+## Removed from `@exellix/ai-tasks` (8.6.0)
+
+### Functions
+
+| Removed export | Former role |
+|----------------|-------------|
+| **`analyzeRunTaskRequest(catalox, request, options?)`** | Ran skill-level preflight on `pickRunSkillRequestFields(request)`, then merged **`validateRunTaskConfig`** findings into the same report shape. |
+| Re-export **`buildSkillRequestAnalysisPacket`** | Built sanitized gateway invoke packet + deterministic findings for a flat **`RunSkillRequest`**. |
+| Re-export **`formatSkillRequestAnalysisMarkdown`** | Rendered **`SkillRequestAnalysisReport`** as markdown for studio UI / logs. |
+| Re-export **`FUNCX_ANALYZE_GATEWAY_INVOKE_REQUEST_ID`** | Constant: `"ai-skills/analyze-gateway-invoke-request"`. |
+| Re-export **`FUNCX_MIN_VERSION_FOR_ANALYZE_GATEWAY`** | Constant: `"4.3.3"` (minimum FuncX with analyzer seed). |
+
+### Types (re-exports removed)
+
+`AnalyzeSkillRequestOptions`, `AnalyzeSkillRequestResult`, `BuildSkillRequestAnalysisPacketResult`, `SkillRequestAnalysisCategory`, `SkillRequestAnalysisFinding`, `SkillRequestAnalysisReport`, `SkillRequestAnalysisSeverity`, `SkillRequestAnalysisVerdict`, `AnalyzeGatewayInvokeRequestPacket`.
+
+### Removed from `@exellix/ai-skills` (≥ 6.1.0 public API)
+
+The engine no longer exports **`analyzeSkillRequest`**, **`ExellixSkillsClient.analyzeSkillRequest`**, packet builders, or FuncX constants. Historical implementation lived under `dist/analysis/` in older builds; **source was removed** from the engine package intentionally.
+
+---
+
+## What the former preflight did (behavior reference)
+
+This section describes the **old runtime behavior** so studio can reproduce equivalent UX if desired.
+
+### End-to-end flow (historical)
+
+```mermaid
+sequenceDiagram
+  participant Studio as Studio / manager
+  participant Preflight as analyzeSkillRequest / analyzeRunTaskRequest
+  participant Catalox as Catalox ai-skills catalog
+  participant FuncX as FuncX optional LLM review
+
+  Studio->>Preflight: RunSkillRequest or RunTaskRequest slice
+  Preflight->>Catalox: fetchSkillTemplatesFromCatalox (unless templateOverride)
+  Preflight->>Preflight: buildSkillGatewayInvokePayload (no gateway.invoke)
+  Preflight->>Preflight: Rendrix template render → workingMemory
+  Preflight->>Preflight: collectDeterministicFindings
+  Preflight-->>Studio: report, markdownReport, gatewayPayload preview
+  opt Optional LLM review
+    Studio->>FuncX: analyze-gateway-invoke-request(packet)
+    FuncX-->>Studio: enriched narrative / findings
+  end
+  Studio->>Runtime: runTask / runSkill when satisfied
+```
+
+**Important:** Preflight never called **`gateway.invoke()`** or **`runSkill()`**. Optimixer **`maxTokens`** were typically **not** on the preview payload (engine merges Optimixer output immediately before invoke).
+
+### `analyzeSkillRequest` (flat `RunSkillRequest`)
+
+1. **`buildSkillRequestAnalysisPacket`**
+   - Load templates from Catalox (or use `templateOverride`).
+   - Build **`buildSkillGatewayInvokePayload`** with resolved `jobId` / `taskId`.
+   - Render templates with Rendrix (`renderSkillTemplatesWithRendrix`) using the same working memory as invoke.
+   - Run **`collectDeterministicFindings`** (see catalog below).
+   - Sanitize packet fields (truncate templates, strip secrets) for FuncX / UI.
+2. Assemble **`SkillRequestAnalysisReport`** from findings (verdict, assessments, expected response shape hints).
+3. **`formatSkillRequestAnalysisMarkdown`** for display.
+4. Optional **`strictDeterministic`**: throw if any finding has `severity: "error"`.
+
+**Options (`AnalyzeSkillRequestOptions`):**
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `templateOverride` | — | Skip Catalox fetch; use supplied instructions/prompt strings. |
+| `maxTemplateCharsInPacket` | `12000` | Truncate template bodies in the analyze packet. |
+| `strictDeterministic` | `false` | Fail fast on error-level deterministic findings. |
+| `cataloxAppId` | env default | Catalox app context for catalog fetch. |
+
+**Result (`AnalyzeSkillRequestResult`):** `functionId`, `skillKey`, `verdict`, `confidence`, `report`, `markdownReport`, `deterministicFindings`, optional `gatewayPayload`.
+
+### `analyzeRunTaskRequest` (orchestrator `RunTaskRequest`)
+
+Same as **`analyzeSkillRequest`** on **`pickRunSkillRequestFields(request)`**, plus:
+
+- **`includeAiTasksConfigValidation`** (default `true`): merge **`validateRunTaskConfig`** issues as additional findings (`AI_TASKS_<code>` ids), mapped to categories (`smartInput`, `modelConfig`, `activix`, `template`, `executionMemory`, `catalog`).
+- Recompute merged **`verdict`** from skill + config validation.
+
+**Replacement at runtime today:** call **`validateRunTaskConfig(request)`** (and optionally **`validateRunTaskInvoke`**) directly from `@exellix/ai-tasks` — without skill template packet preview.
+
+---
+
+## Suggested studio requirements
+
+Studio **may** implement some or all of the following. Treat as a checklist, not a contract.
+
+### Functional
+
+1. **Catalog** — Skill exists in Catalox **`ai-skills`**, published/runnable; surface catalog status in UI.
+2. **Activix linkage** — Non-empty `agentId`, `jobTypeId`, `taskTypeId`; warn on missing `jobId` / `taskId`.
+3. **Model** — After `@exellix/ai-tasks` **`resolveInvocationPlan`**, wire model is concrete (not a bare profile alias); warn if caller set `maxTokens` on `modelConfig` (Optimixer-owned at invoke).
+4. **Templates** — Fetch same bodies as `runSkill`; render with Rendrix; flag unresolved `{{tokens}}` and large payloads.
+5. **Smart input** — Paths resolve against merged working memory; required paths fail preflight.
+6. **Output contract** — Contract fields reflected in template headings or FlexMD hints.
+7. **Invoke packet preview** — Sanitized view of what **`buildSkillGatewayInvokePayload`** would send (no secrets, truncated bodies).
+8. **RunTask slice** — When analyzing a graph node, apply orchestrator validation (`validateRunTaskConfig`) in addition to skill checks.
+9. **Optional FuncX review** — LLM narrative / deeper critique via **`ai-skills/analyze-gateway-invoke-request`** (does not replace deterministic checks).
+
+### Non-functional
+
+- **No live LLM invoke** for deterministic preflight (FuncX optional step is separate).
+- **No duplicate Optimixer predict** required for preflight (note in UI that invoke budget is applied at runtime).
+- **Stable finding ids** for studio filtering (see catalog below).
+- **Markdown + structured report** for authoring UI.
+
+---
+
+## Suggested API surface (studio-owned)
+
+Studio can define its own module names. This mirrors the **former** public types for migration.
+
+### Verdict and findings
+
+```typescript
+type SkillRequestAnalysisSeverity = "error" | "warning" | "info";
+type SkillRequestAnalysisVerdict = "ok" | "warnings" | "errors";
+
+type SkillRequestAnalysisCategory =
+  | "activix"
+  | "session"
+  | "workingMemory"
+  | "smartInput"
+  | "template"
+  | "outputContract"
+  | "modelConfig"
+  | "executionMemory"
+  | "catalog"
+  | "prediction"
+  | "runtime";
+
+interface SkillRequestAnalysisFinding {
+  id: string;
+  severity: SkillRequestAnalysisSeverity;
+  category: SkillRequestAnalysisCategory;
+  path?: string;
+  message: string;
+  suggestion?: string;
+  evidence?: string;
+}
+```
+
+**Verdict rule (suggested):** any `error` → `"errors"`; else any `warning` → `"warnings"`; else `"ok"`.
+
+### Analyze packet (for FuncX or internal UI)
+
+```typescript
+interface AnalyzeGatewayInvokeRequestPacket {
+  functionId: string; // same as skillKey / actionRef
+  aiRequestId?: string;
+  jobId?: string;
+  taskId?: string;
+  agentId?: string;
+  jobTypeId?: string;
+  taskTypeId?: string;
+  gatewayPayload: Record<string, unknown>; // sanitized
+  runSkillRequest?: Record<string, unknown>; // sanitized
+  templates?: {
+    raw?: { instructions?: string; prompt?: string };
+    rendered?: { instructions?: string; prompt?: string };
+    catalogStatus?: string;
+  };
+  outputContract?: OutputContract;
+  resolvedOutputFields?: string[];
+  deterministicFindings?: SkillRequestAnalysisFinding[];
+  flexMdFrameHint?: string;
+  templateTokenInventory?: string[];
+}
+```
+
+Use **`functionId`** on FuncX packets (not deprecated top-level `skillKey` alone).
+
+### FuncX (optional LLM step)
+
+| Constant (historical name) | Value |
+|----------------------------|--------|
+| FuncX function id | `ai-skills-analyze-gateway-invoke-request` |
+| Slash alias | `ai-skills/analyze-gateway-invoke-request` |
+| Suggested minimum `@x12i/funcx` | `4.3.3` (ships analyzer seed) |
+
+```typescript
+import { run } from "@x12i/funcx/functions";
+
+const report = await run("ai-skills/analyze-gateway-invoke-request", packet, {
+  mode: "strong",
+  validateOutput: true,
+  includeUsage: false,
+});
+```
+
+Seed location: `@x12i/funcx` → `content-seed/functions/ai-skills/analyze-gateway-invoke-request/`.
+
+---
+
+## Deterministic finding catalog (historical ids)
+
+Studio implementations **may** emit the same ids for continuity with older UIs.
+
+| Id | Severity | Category | Trigger (summary) |
+|----|----------|----------|-------------------|
+| `ACTIVIX_MANDATORY_FIELDS_MISSING` | error | activix | Missing agentId / jobTypeId / taskTypeId |
+| `JOB_ID_MISSING` | warning | activix | Empty jobId on request and identity |
+| `TASK_ID_MISSING` | warning | activix | Empty taskId on request and identity |
+| `SESSION_ID_MISMATCH` | error | session | `sessionId` vs `identity.sessionId` disagree |
+| `MODEL_CONFIG_MISSING` | error | modelConfig | No wire `model` / `modelId` on modelConfig |
+| `CALLER_MAX_TOKENS_IGNORED` | warning | modelConfig | Caller sent maxTokens (Optimixer owns budget) |
+| `AI_ENGINE_ID_UNKNOWN` | error | catalog | Invalid / unknown aiEngineId |
+| `INPUT_EMPTY` | warning | workingMemory | Empty `input` |
+| `SMART_INPUT_PATH_EMPTY` | warning | smartInput | Empty path entry |
+| `SMART_INPUT_PATH_MISSING` | error | smartInput | Required path not in workingMemory |
+| `SMART_INPUT_PATH_EMPTY_VALUE` | warning | smartInput | Optional path empty |
+| `TEMPLATE_RENDER_FAILED` | error | template | Rendrix render threw |
+| `TEMPLATE_TOKEN_UNRESOLVED` | warning | template | `{{token}}` left after render |
+| `OUTPUT_CONTRACT_FIELD_NOT_IN_TEMPLATE` | warning | outputContract | Contract field missing from template sections |
+| `TEMPLATE_TOKEN_LIKELY_MISSING` | info | template | Template references path not in workingMemory |
+| `TEMPLATE_PAYLOAD_LARGE` | warning | template | Combined template chars over threshold (~80k default) |
+| `SKILL_KEY_MISSING` | error | catalog | Empty skillKey |
+| `AI_TASKS_<code>` | varies | varies | From `validateRunTaskConfig` when analyzing RunTaskRequest |
+
+---
+
+## Suggested implementation building blocks
+
+Reuse runtime packages; do **not** fork invoke logic into studio long-term.
+
+| Step | Suggested reuse |
+|------|-----------------|
+| Resolve wire model | `@exellix/ai-tasks` → `resolveInvocationPlan` / slot helpers |
+| Orchestrator shape | `@exellix/ai-tasks` → `validateRunTaskConfig`, `buildRunTaskValidationContext` |
+| Fetch templates | `@exellix/ai-skills` → `fetchSkillTemplatesFromCatalox`, `defaultAiSkillsCataloxContext` |
+| Build invoke shape | Mirror `@exellix/ai-skills` → `buildSkillGatewayInvokePayload` (same fields as `runSkill`) |
+| Template render | `@exellix/ai-skills` / Rendrix path used by `renderSkillTemplatesWithRendrix` |
+| Wire model check | `@exellix/ai-skills` → `assessModelConfigForInvoke` |
+| Smart input / tokens | `@exellix/ai-tasks` re-exports Rendrix helpers (`renderSmartInput`, `analyzeTemplateResolution`, …) |
+| Execute | `@exellix/ai-skills` → `runSkill` only after preflight passes |
+
+**Reference implementation (historical):** `@exellix/ai-skills` `dist/analysis/` in releases **before** 6.1.0 source removal — useful as a migration guide, not a supported import path.
+
+---
+
+## Suggested studio UX flow
+
+```
+Graph / studio plan
+  → @exellix/ai-tasks (resolveInvocationPlan, validateRunTaskConfig)
+  → Studio preflight service (deterministic packet + findings)
+  → [optional] FuncX ai-skills/analyze-gateway-invoke-request
+  → User approves / fixes
+  → @exellix/ai-skills runSkill()  (Optimixer merge + gateway.invoke)
+```
+
+---
+
+## Migration notes (8.5.x → 8.6.0+)
+
+| If you used… | Suggested replacement |
+|--------------|----------------------|
+| `analyzeRunTaskRequest` from `@exellix/ai-tasks` | Studio service + `validateRunTaskConfig`; optional port of old analysis module |
+| `buildSkillRequestAnalysisPacket` re-export | Implement in studio (see building blocks) or copy historical `dist/analysis` |
+| `formatSkillRequestAnalysisMarkdown` re-export | Studio formatter from `SkillRequestAnalysisReport` |
+| `ExellixSkillsClient.analyzeSkillRequest` | Studio service; engine no longer exposes this |
+
+---
+
+## Out of scope for this preflight
+
+- PRE/POST xynthesis hops (use xynthesis-specific studio tools if needed).
+- Live LLM execution tests (`test:live`, gateway smoke).
+- Replacing Optimixer sizing or max-token retry (runtime owns retry via `retryPrediction`).
+- Mandatory enforcement at `runTask()` — runtime validation remains minimal by design; studio may **choose** to block “Run” in UI only.

package/documenations/upstream-feature-requests/ai-skills-orchestrator-invoke-contract-5.9.md

@@ -114,10 +114,10 @@ The open item **“`outputExpectation` passthrough + xynthesis-style auto-sizer
 
 ## Integration note (5.9.12 — ai-tasks)
 
-### `analyzeSkillRequest` root export removed
+### `analyzeSkillRequest` — studio / manager only (not runtime)
 
-- **Today:** `analyzeSkillRequest(catalox, …)` exists in `dist/analysis/` but is **not** re-exported from `@exellix/ai-skills` package root. Use **`ExellixSkillsClient.analyzeSkillRequest`** (or export the function again from `index.js` for Catalox-only callers).
-- **ai-tasks:** `analyzeRunTaskRequest` uses a short-lived `ExellixSkillsClient` until root export returns.
+- **`@exellix/ai-skills` ≥ 6.1.0** does not export **`analyzeSkillRequest`**, packet builders, or FuncX analyzer constants — preflight belongs in **studio / skills-manager** (see **`SKILLS_MANAGER_CLIENT_GUIDE.md`**) via **`@x12i/funcx`** (`ai-skills/analyze-gateway-invoke-request`).
+- **`@exellix/ai-tasks`** does not re-export or wrap skill invoke analysis. Use **`validateRunTaskConfig`** / **`analyzeExpectedRunTaskInput`** for orchestrator request shape checks before **`runTask()`**. For a **suggested** studio preflight design (everything removed from runtime, requirements, former behavior), see **`@exellix/ai-tasks`** [`documenations/studio-skill-invoke-preflight.md`](../../ai-tasks/documenations/studio-skill-invoke-preflight.md).
 
 ### `testContentRegistryConnection` renamed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/ai-tasks",
-  "version": "8.5.3",
+  "version": "8.6.2",
   "description": "Task orchestration for the Exellix stack: runTask() with local handlers or LLM-backed execution, task-scoped memory/context enrichment, and executor dispatch via @exellix/ai-skills. ERC-compliant.",
   "type": "module",
   "main": "dist/index.js",
@@ -60,7 +60,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@exellix/ai-skills": "^6.0.2",
+    "@exellix/ai-skills": "^6.2.1",
     "@exellix/memorix-narrix-adapter": "^2.0.0",
     "@exellix/narrix-adapter-chat": "^2.0.0",
     "@exellix/narrix-adapter-docs": "^2.0.0",
@@ -72,9 +72,8 @@
     "@exellix/narrix-ingest": "^2.0.0",
     "@exellix/narrix-runner": "^2.0.0",
     "@exellix/narrix-web-scoper": "^2.0.0",
-    "@exellix/xynthesis": "^4.4.5",
+    "@exellix/xynthesis": "^4.4.7",
     "@x12i/activix": "^8.5.0",
-    "@x12i/ai-profiles": "^2.1.0",
     "@x12i/catalox": "^5.1.3",
     "@x12i/env": "^4.0.1",
     "@x12i/execution-memory-manager": "^1.2.0",