@exellix/ai-tasks 9.1.0 → 9.1.1

package/documenations/feature-request-athenix-core-directive.md

@@ -1,145 +0,0 @@
-# Feature Request: Athenix `core:` Directive Tokens
-
-## Summary
-
-Add first-class support in `@x12i/rendrix` for semantic directive tokens:
-
-- `{{core:analysis}}`
-- `{{core:decision}}`
-- `{{core:question}}`
-
-These are **not** memory paths and must not be resolved via normal object lookup.
-
-## Why
-
-`@exellix/ai-tasks` uses template-declared task semantics to drive structured synthesis.
-
-Using path-like syntax such as `{{core.analysis}}` is incorrect because parser/runtime treats it as:
-
-- lookup object `core`
-- then property `analysis`
-
-That conflates semantic declaration with data lookup and causes false missing-token errors.
-
-We need directive syntax where `core:` is a command namespace, not path traversal.
-
-## Requested Behavior
-
-### 1) Parse `core:` as directive token (not path token)
-
-When parser sees:
-
-- `{{core:analysis}}`
-
-it should emit a dedicated token type (example `kind: "core"` or `kind: "directive"` with `directive: "core"`).
-
-It must **not** classify this as path/helper token.
-
-### 2) Do not perform memory-path resolution for `core:` tokens
-
-Renderer should not try to read:
-
-- `workingMemory.core.analysis`
-
-for `{{core:analysis}}`.
-
-No missing-path error should be thrown due to absent `core` object.
-
-### 3) Introspection output must expose directive value
-
-`listTokens()` (or equivalent) should include structured fields, e.g.:
-
-```ts
-{
-  kind: "core",
-  raw: "core:analysis",
-  directive: "core",
-  value: "analysis",
-  start: 123,
-  end: 141
-}
-```
-
-## API / Type Additions (Conceptual)
-
-```ts
-export type TemplateTokenKind =
-  | "path"
-  | "helper"
-  | "block"
-  | "core"
-  | "unknown";
-
-export interface TemplateTokenRef {
-  raw: string;
-  kind: TemplateTokenKind;
-  path?: string;        // only for path-kind
-  directive?: string;   // "core" for core-kind
-  value?: string;       // "analysis" for core-kind
-  start: number;
-  end: number;
-}
-```
-
-Optional utility:
-
-```ts
-export function listDirectiveValues(
-  template: string,
-  directive: string
-): string[];
-```
-
-## Rendering Semantics
-
-For `core:` tokens:
-
-- default render output can be empty string (`""`) unless overridden,
-- or configurable render policy (e.g. keep literal / empty / custom formatter),
-- but never path lookup failure.
-
-For all other required tokens:
-
-- existing strict behavior remains unchanged.
-
-## Validation Rules
-
-Parser-level validation should enforce:
-
-- `{{core:...}}` must include non-empty value segment
-- whitespace-trimmed value allowed (`{{core: analysis}}` -> `analysis`)
-
-Optional strict mode (consumer-level) can validate value against allowed set.
-
-## Backward Compatibility
-
-- Additive change.
-- Existing path tokens keep current behavior.
-- No change required for templates not using `core:`.
-
-## Acceptance Criteria
-
-1. `listTokens("...{{core:analysis}}...")` returns token with `kind: "core"` and `value: "analysis"`.
-2. Rendering template containing `{{core:analysis}}` does not throw missing-path errors when no `core` object exists.
-3. Existing strict missing-token behavior for non-core path tokens is unchanged.
-4. Unit tests added for:
-   - single and multiple core directives
-   - whitespace around colon/value
-   - invalid `{{core:}}`
-   - coexistence with normal path/helper tokens
-
-## Example
-
-Template:
-
-```md
-System contract:
-- {{core:analysis}}
-- {{core:decision}}
-```
-
-Expected:
-
-- introspection detects two core directives: `analysis`, `decision`
-- rendering does not require `core.analysis` or `core.decision` in memory
-

package/documenations/feature-request-athenix-token-extraction.md

@@ -1,124 +0,0 @@
-# Feature Request: Athenix Token Introspection and Selective Resolution
-
-## Summary
-
-`@exellix/ai-tasks` needs first-class support in Athenix parser for:
-
-1. Inspecting templates to discover tokens before rendering.
-2. Resolving values for a selected token set from a runtime context, without fully rendering output.
-
-This is required to implement template-contract-driven semantics (for example task core tokens) in a deterministic, pre-render-safe way.
-
-## Problem
-
-Current behavior in downstream runtime integrations can make full-template rendering unsuitable as a source of truth for semantic discovery:
-
-- Semantic tokens may be transformed/removed by template rendering pipelines.
-- Some integrations lazily initialize content resolvers.
-- Full rendered text is a poor boundary for extracting contract-level meaning.
-
-For `ai-tasks`, we must:
-
-- discover semantic tokens from template contract (`{{...}}`) pre-render,
-- then resolve token values against runtime memory/context,
-- then drive synthesis and execution from those resolved semantics.
-
-Without parser-native support, we are forced into brittle string probing.
-
-## Requested Capability
-
-### 1) Token Introspection API
-
-Return token metadata from a template without rendering.
-
-Conceptual API:
-
-```ts
-export interface TemplateTokenRef {
-  raw: string;             // original token expression
-  path?: string;           // normalized dot-path if applicable
-  kind: "path" | "helper" | "block" | "unknown";
-  start: number;           // source offset
-  end: number;             // source offset
-}
-
-export function listTokens(template: string, options?: {
-  includeDuplicates?: boolean; // default false
-}): TemplateTokenRef[];
-```
-
-### 2) Selective Token Resolution API
-
-Resolve only requested tokens from context, without full template rendering.
-
-Conceptual API:
-
-```ts
-export interface ResolveTokenValuesInput {
-  template: string;
-  context: Record<string, unknown>;
-  selectors: string[]; // e.g. ["core.*", "question", "metadata.intent"]
-  options?: {
-    strict?: boolean; // throw if selected token missing/invalid
-  };
-}
-
-export interface ResolvedTokenValue {
-  token: string;              // matched token expression
-  selector: string;           // selector that matched
-  value: unknown;             // resolved value
-  found: boolean;
-}
-
-export function resolveTokenValues(
-  input: ResolveTokenValuesInput
-): ResolvedTokenValue[];
-```
-
-## Behavioral Requirements
-
-1. **Pre-render safe**: no dependency on rendered final text.
-2. **Deterministic**: same template+context => same result.
-3. **Selector support**: dot-path and wildcard matching (`core.*`).
-4. **No implicit coercion surprises**: raw `unknown` values should be returned.
-5. **Stable with missing values**: explicit `found: false` (or strict throw).
-6. **Works with current Athenix token syntax** used across Woroces stack.
-
-## Why This Matters
-
-For template-driven orchestration, semantics belong to the template contract.
-The runtime should not infer semantics from caller hints or post-render text.
-
-Parser-native token introspection + selective resolution enables:
-
-- reliable template core discovery,
-- robust runtime validation,
-- traceable synthesis inputs,
-- less integration-specific glue logic.
-
-## Real Integration Use Case (`@exellix/ai-tasks`)
-
-Structured synthesis requires:
-
-- detect template core tokens (for example `core.analysis`, `core.decision`),
-- resolve relevant values from memory/context,
-- block execution when required semantic tokens are absent.
-
-This must happen before synthesis prompt rendering and must not rely on rendered output text.
-
-## Acceptance Criteria
-
-1. Add parser APIs (or equivalent methods) for token listing and selective token value resolution.
-2. Include docs with examples for token selectors and missing-token handling.
-3. Add tests for:
-   - nested paths,
-   - wildcard selectors,
-   - missing tokens in strict/non-strict mode,
-   - duplicate token references,
-   - mixed token kinds.
-4. Confirm compatibility with existing template render pipeline.
-
-## Notes
-
-- This request is additive; it should not break existing `render()` usage.
-- If preferred, these capabilities can be exposed under a utility namespace instead of top-level exports.

package/documenations/funcx-upstream-github-issues-draft.md

@@ -1,153 +0,0 @@
-# FuncX upstream — draft GitHub issues
-
-Use these as copy-paste bodies when filing against **`https://github.com/x12i/funcx`** (adjust labels: `bug`, `documentation`, `enhancement` as appropriate).
-
-**Update (@x12i/funcx ≥ 3.8.2):** Issue **#1** is largely addressed in-package via **`getRunJsonResult`**, **`isHttpRunSuccessBody`**, **`GenericExecutionEnvelope`**, **`genericExecutionEnvelopeJsonSchema`**, and **`buildAskAttribution`** exported from `@x12i/funcx/functions`. **`@exellix/ai-tasks`** depends on **`^3.8.2`** and delegates **`unwrapFuncxRunValue`** to **`getRunJsonResult`** (normalization fixes: **3.8.2**).
-
----
-
-## Issue 1 — `run()` success value shape is not formally specified or normalized (Bug / API contract)
-
-**Status:** Superseded for normalization — use **`getRunJsonResult`** (**≥3.8.2** recommended). Remaining gap: ensure **README / migration** links every consumer to this API (Issue #5 overlap).
-
-**Title:** `run()`: document and export stable JSON extraction for function results
-
-**Type:** Bug (integration hazard) + Documentation
-
-### Summary
-
-Downstream packages (e.g. `@exellix/ai-tasks`) call `run(functionId, payload, { client })` from `@x12i/funcx/functions` and must pass the **parsed function JSON** into app-specific adapters. The **success return shape** of `run()` is not clearly guaranteed in public TypeScript types or docs: hosts may wrap the model/object as `output`, `data`, `result`, or return the object root directly.
-
-### Current behavior
-
-Integrators defensively unwrap multiple keys or treat the whole value as JSON, which is fragile and can silently feed adapters the wrong object.
-
-### Expected behavior
-
-1. **Document** the canonical success shape of `run()` for JSON-returning functions (one paragraph + example in package README or `run` JSDoc).
-2. **Export** a small helper, e.g. `getRunJsonResult(runResult: unknown): unknown` (name TBD), that implements the **supported** unwrapping rules so consumers do not duplicate heuristics.
-3. **Type** the resolved JSON result where possible (generic parameter or discriminated union), even if implementation stays dynamic internally.
-
-### Acceptance criteria
-
-- [ ] Public API + docs agree on one normalization path.
-- [ ] At least one unit test in `@x12i/funcx` locks the behavior for JSON-mode functions.
-- [ ] Changelog calls out any tightening if older hosts relied on ambiguous shapes.
-
-### References
-
-- Consumer workaround today: local `unwrapFuncxRunValue` heuristics in `@exellix/ai-tasks` (`genericExecutionFuncxEnvelope.ts`).
-
----
-
-## Issue 2 — No published TypeScript / JSON Schema for generic execution envelope (Feature)
-
-**Title:** Publish shared types (and optional JSON Schema) for generic `goal` / `input` / `context` / `result` / `args` / `attribution` contracts
-
-**Type:** Feature request
-
-### Summary
-
-Multiple products want the same **generic FuncX envelope** for capabilities such as `execution/plan`, `execution/evaluate-result`, and `research/plan-questions`. Today each consumer re-declares structural types, which risks drift from FuncX’s actual validation and from other clients.
-
-### Request
-
-1. Export TypeScript types from `@x12i/funcx` (or a sibling package) for:
-   - Generic request envelope (`goal`, `input?`, `context?`, `result?`, `args?`, `attribution?`).
-   - Optional: per-function **response** types or Zod schemas where FuncX validates outputs.
-2. Optionally publish **JSON Schema** artifacts for the same contracts (for non-TS hosts and catalog tooling).
-
-### Acceptance criteria
-
-- [ ] Types are importable from a documented entrypoint (e.g. `@x12i/funcx` or `@x12i/funcx/contracts`).
-- [ ] Version SemVer policy documented (breaking changes to envelope bump major or explicit migration note).
-
-### References
-
-- Draft consumer types: `@exellix/ai-tasks` `genericExecutionFuncxEnvelope.ts`.
-
----
-
-## Issue 3 — Canonical catalog functions for generic execution / research planning (Feature)
-
-**Title:** Ship and register `execution/plan`, `execution/evaluate-result`, `research/plan-questions` as first-class FuncX functions
-
-**Type:** Feature request (blocking for generic orchestration clients)
-
-### Summary
-
-Orchestrators are standardizing on **capability-based** ids (`execution/plan`, etc.) with a **single generic envelope**. Consumers call `run()` with that payload. Today, npm still emphasizes legacy **`aiTasksPlanTask` / `aiTasksOptimizerEvaluate`**-style entrypoints while the ecosystem moves away from product-prefixed ids and bespoke envelopes.
-
-### Request
-
-1. Implement the three functions with behavior matching the published generic contract (prompting, JSON mode, validation, retries as appropriate).
-2. Register them in the **content/catalog path** used by `run()` for typical deployments (document exact ids: slash + hyphen router forms).
-3. Forward **`attribution`** from the inbound envelope into **every** nested `client.ask()` / `askJson` call inside those functions (for billing/trace parity).
-4. Document migration for hosts that still register **`ai-tasks/plan-task`** (if aliases are supported, document explicitly; if not, document cutover).
-
-### Acceptance criteria
-
-- [ ] `run("execution/plan", payload, { client })` (and hyphen alias if applicable) returns validated JSON per spec.
-- [ ] Same for `execution/evaluate-result` and `research/plan-questions`.
-- [ ] Live or CI-backed test that attribution tags survive to provider-facing calls where OpenRouter/Activix expect them.
-
-### References
-
-- Consumer defaults: `@exellix/ai-tasks` `constants.ts` (`FUNCX_EXECUTION_*`, `FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID`).
-
----
-
-## Issue 4 — Document attribution forwarding contract for custom FuncX functions (Documentation)
-
-**Title:** Document: function implementations MUST propagate `payload.attribution` (or equivalent) to nested LLM calls
-
-**Type:** Documentation (severity: high for observability)
-
-### Summary
-
-Generic envelopes include **`attribution`** (`runId`, `subjectId`, `actorId`, `tags`, etc.). If implementers only log the outer HTTP boundary but omit attribution on internal `ask()` calls, **usage, cost, and trace correlation** break for nested completions.
-
-### Request
-
-1. Add a **short “FuncX function author checklist”** section: read `attribution` from input → merge with `functionId` / `traceId` as needed → pass on `AskOptions.attribution` for every LLM call.
-2. Reference existing helpers (`formatOpenRouterUserField`, `execAttribution`, etc.) if those are the supported path.
-3. Optionally add a **lint or runtime warning** in dev mode when `ask()` is invoked without attribution inside functions that received a populated envelope (stretch goal).
-
-### Acceptance criteria
-
-- [ ] Public docs linked from `run()` / “authoring functions” guide.
-- [ ] Example function in repo demonstrates nested attribution.
-
----
-
-## Issue 5 — Clarify relationship between direct TS exports (`aiTasksPlanTask`) and `run()` generic functions (Documentation / Deprecation)
-
-**Title:** Migration guide: `aiTasksPlanTask` / `aiTasksOptimizerEvaluate` vs `run("execution/plan", …)` generic envelope
-
-**Type:** Documentation + Deprecation policy (could start as docs-only)
-
-### Summary
-
-`@x12i/funcx/functions` still exports **direct** helpers for legacy ai-tasks-shaped payloads while new integrators use **`run()`** + generic envelope + new ids. Without an explicit migration table, teams duplicate behavior or pick the wrong integration path.
-
-### Request
-
-1. Document **one recommended path** for new code (generic ids + `run()` + shared types).
-2. State whether **`aiTasksPlanTask`** / **`aiTasksOptimizerEvaluate`** are **deprecated**, **supported aliases**, or **frozen** — with semver expectations.
-3. If generic functions supersede them, provide a **payload mapping table** (old `kind` + `request` → new `goal` + `input` + `context` + `attribution`).
-
-### Acceptance criteria
-
-- [ ] README or `docs/migration-generic-execution.md` committed and linked from changelog when generic functions ship.
-
----
-
-### Filing checklist
-
-| Draft # | Suggested GitHub label        | Blocking `@exellix/ai-tasks`?      |
-|---------|-------------------------------|-----------------------------------|
-| 1       | `bug`, `documentation`, `api` | Yes (correctness of parsing)      |
-| 2       | `enhancement`                 | No (quality / drift reduction)    |
-| 3       | `enhancement`                 | Yes (runtime unless content-only) |
-| 4       | `documentation`               | Yes (observability parity)        |
-| 5       | `documentation`               | No (clarity / migration)         |

package/documenations/identity-metadata-contract.md

@@ -1,165 +0,0 @@
-# Feature request: `identity` propagation + Activix identity
-
-## Goal
-
-Add a generic, end-to-end **identity envelope** to each task run so that:
-
-- Upstream callers can describe *what this task instance is* (domain identity, purpose, correlation).
-- Runtime can add a **unique per-run `taskId`** and the **`skillId` used**.
-- Downstream components that support Activix receive this identity as a **first-class Activix field**: `identity`.
-
-This is a contract-level feature request for **`ai-gateway`** and **`ai-skills`** integrations, expressed generically so it applies to any task/skill combination.
-
----
-
-## Terminology
-
-- **Upstream**: The caller that initiates a `runTask` request (product/app/service).
-- **Gateway**: The LLM gateway layer (`ai-gateway`) used for model/tool calls.
-- **Skills**: Skill resolver/executor layer (`ai-skills`) used by task execution.
-- **Downstream**: Any component invoked during execution (LLM calls, tools, connectors). This doc focuses on **Activix-capable** downstreams.
-- **Activix-capable**: A downstream path that records execution via Activix and can attach first-class `identity`.
-
----
-
-## API shape (high-level)
-
-### Upstream request addition
-
-Task-run requests should allow an optional field:
-
-- `identity?: object`
-
-Constraints:
-
-- Treat as an **opaque JSON object** (no strict schema required at first).
-- Must be safe for logging/tracing (no secrets). If secrets are possible, either upstream must redact or the runtime must enforce redaction policy before emitting observability.
-
-### Runtime enrichment (per execution instance)
-
-For every execution instance, runtime must produce an **effective identity**:
-
-- `effectiveIdentity = identity (from upstream, if present) + { taskId, skillId }`
-
-Where:
-
-- `taskId`: **required**, generated by runtime, unique per task-run instance.
-- `skillId`: **required when a skill is selected/resolved**, set to the skill used for this run.
-
-Notes:
-
-- `identity` from upstream is **never dropped** when present.
-- `taskId` and `skillId` **must not** be accepted from upstream as authoritative values if they are provided there; runtime-generated/selected values win.
-
----
-
-## Behavior contract
-
-### 1) Preserve upstream identity
-
-- If upstream sends `identity`, keep it attached to the run for the full lifecycle.
-- If upstream does not send it, initialize identity as an empty object for the purpose of downstream propagation and enrichment.
-
-### 2) Create a per-run `taskId`
-
-- Create `taskId` once per `runTask` invocation.
-- The ID must be stable across the entire run (pre/main/post steps, retries within the run, and all downstream calls spawned by this run).
-- The ID must be unique across runs (collision-resistant).
-
-### 3) Attach `skillId` when known
-
-- When the runtime resolves the skill used for this run, attach `skillId` to the effective identity.
-- If the run is “direct” (no skills), either:
-  - omit `skillId`, or
-  - set `skillId` to a documented sentinel (only if that’s already a platform convention).
-
-### 4) Forward to all Activix-capable downstream calls
-
-When creating Activix records, attach identity as a first-class field:
-
-- `activixRecord.identity = effectiveIdentity`
-
-This requires Activix to treat `identity` as a first-class, supported object field (preserved end-to-end on start/complete/fail and queryable in stored records). This is intentional: identity is part of the methodology/contract, not an ad-hoc blob nested under arbitrary meta.
-
-This identity must be included for:
-
-- MAIN execution calls
-- PRE steps that call downstream (e.g., synthesis)
-- POST steps that call downstream
-
-If a downstream path is not Activix-capable, the runtime should still retain the identity in memory/metadata so it can be used when a later step *is* Activix-capable.
-
----
-
-## Ownership and responsibilities
-
-### Upstream (product/service calling `runTask`)
-
-- Provide `identity` describing the task instance in domain terms.
-- Do not include secrets.
-- Do not attempt to control `taskId` generation; treat `taskId` as runtime-owned.
-
-Examples of useful upstream fields (non-prescriptive):
-
-- `source`: service/app identifier
-- `purpose`: why the task was launched
-- `correlationId`: upstream correlation ID (if already present)
-- `user`: stable user/account identity (non-secret)
-- `entity`: domain object reference (e.g., `{ type: "...", id: "..." }`)
-
-### ai-skills (skill resolution/execution)
-
-- Ensure `skillId` for the selected skill is available to the runtime and included in the effective identity.
-- Ensure any skill-spawned downstream calls that record to Activix also receive the effective identity in Activix record `identity`.
-
-### ai-gateway (gateway for LLM/tool calls)
-
-- Accept and preserve an identity object on calls originating from task execution.
-- When the gateway records to Activix, place the effective identity under top-level `identity` (do not rename/flatten fields).
-- Do not mutate upstream identity fields except for the controlled addition/override of `taskId` and `skillId` as defined in this contract.
-
----
-
-## Activix mapping (required)
-
-When an execution path uses Activix:
-
-- **Input**: Upstream `identity` + runtime `{ taskId, skillId }`
-- **Output**: `identity` equals the merged object
-
-Merging rules:
-
-- Start with upstream `identity` (or `{}` if missing)
-- Add/overwrite:
-  - `taskId` (runtime generated)
-  - `skillId` (runtime resolved)
-
----
-
-## Observability and debugging (recommended)
-
-Expose minimal, non-sensitive observability so runs can be traced:
-
-- `metadata.taskId` (top-level convenience mirror)
-- `metadata.skillId` (top-level convenience mirror when present)
-- `metadata.identityPresent: boolean`
-
-If the full `identity` is logged, enforce redaction policy; otherwise log only safe subsets or presence flags.
-
----
-
-## Backward compatibility stance
-
-- New field is additive: existing callers continue to work with `identity` absent.
-- Downstream Activix paths should be tolerant to missing identity fields (but runtime should always generate `taskId` once this feature is implemented).
-
----
-
-## Acceptance criteria
-
-- A `runTask` request may include `identity` and it is preserved for the full run.
-- Each run results in a unique runtime-generated `taskId` that is stable across all downstream calls for that run.
-- When a skill is used, the effective identity includes `skillId`.
-- Any Activix record created by the system includes first-class `identity` populated with the effective identity.
-- Minimal observability surfaces `taskId` (and `skillId` when applicable) so traces/logs can correlate all calls to a single run.
-