@exellix/ai-tasks 8.5.2 → 8.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/CHANGELOG.md +10 -8
  2. package/README.md +6 -20
  3. package/dist/aiSkillsUpstreamExports.d.ts +2 -2
  4. package/dist/aiSkillsUpstreamExports.d.ts.map +1 -1
  5. package/dist/aiSkillsUpstreamExports.js +1 -1
  6. package/dist/aiSkillsUpstreamExports.js.map +1 -1
  7. package/dist/index.d.ts +0 -3
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +0 -2
  10. package/dist/index.js.map +1 -1
  11. package/documenations/funcx-catalog-hosting-checklist.md +10 -6
  12. package/documenations/funcx-scoping-integration-gaps.md +2 -2
  13. package/documenations/studio-skill-invoke-preflight.md +298 -0
  14. package/documenations/upstream-feature-requests/README.md +4 -4
  15. package/documenations/upstream-feature-requests/ai-skills-orchestrator-invoke-contract-5.9.md +3 -3
  16. package/documenations/upstream-feature-requests/funcx-generic-xynthesis-hosting.md +177 -203
  17. package/documenations/upstream-feature-requests/funcx-pre-post-sidekick-actions.md +124 -212
  18. package/package.json +3 -3
package/documenations/upstream-feature-requests/funcx-generic-xynthesis-hosting.md CHANGED
@@ -1,294 +1,268 @@
1
1
  # `@x12i/funcx` — generic envelope hosting for xynthesis-domain capabilities
2
2
 
3
- **Filed by:** `@exellix/ai-tasks`
4
- **Consumers:** `@exellix/xynthesis` (LLM hops), `@exellix/ai-tasks` (envelope builders + adapters)
5
- **Out of scope:** `@exellix/ai-skills` MAIN gateway prompts (skill templates, `instructions` / `prompt` on `RunTaskRequest`)
3
+ **Filed by:** `@exellix/ai-tasks` + `@exellix/xynthesis`
4
+ **Baseline reviewed:** `@x12i/funcx` **4.4.0** (npm; `xynthesis` dependency `^4.4.0`)
5
+ **Consumers:** `@exellix/xynthesis` 4.4+ (LLM orchestration), `@exellix/ai-tasks` 8.5+ (envelope builders + adapters)
6
+ **Out of scope:** `@exellix/ai-skills` MAIN gateway prompts
6
7
 
7
8
  **Related:**
8
9
 
9
- - [`funcx-scoping-integration-gaps.md`](../funcx-scoping-integration-gaps.md) — scoping `ask()` gaps + §6 execution-strategy wire contracts
10
- - [`funcx-catalog-hosting-checklist.md`](../funcx-catalog-hosting-checklist.md) — deploy checklist for `run()` resolution
11
- - [`xynthesis-execution-strategies-option-a.md`](./xynthesis-execution-strategies-option-a.md) — **shipped** xynthesis 4.4 sidekick actions (interim: disk templates + `FuncxInvoker.ask`)
12
- - Envelope builders (stable): [`genericExecutionFuncxEnvelope.ts`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts)
13
- - Xynthesis templates today (duplicate host): `xynthesis/templates/execution-plan/`, `execution-evaluate-result/`, `plan-web-scope-questions/`
10
+ - [**funcx-pre-post-sidekick-actions.md**](./funcx-pre-post-sidekick-actions.md) — pre/post sidekick built-ins + `SidekickGenericEnvelope`
11
+ - [`funcx-scoping-integration-gaps.md`](../funcx-scoping-integration-gaps.md) §6 — execution-strategy adapter contracts
12
+ - [`funcx-catalog-hosting-checklist.md`](../funcx-catalog-hosting-checklist.md) — deploy / smoke-test checklist
13
+ - Consumer map: `xynthesis/src/catalog/sidekickFuncxCatalogMap.ts`, `xynthesis/src/sidekickFuncxEnvelope.ts`
14
+ - Envelope builders: [`genericExecutionFuncxEnvelope.ts`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts), [`auditChecklistFuncxEnvelope.ts`](../../src/post-steps/audit/auditChecklistFuncxEnvelope.ts)
14
15
 
15
16
  ---
16
17
 
17
18
  ## 0. Target architecture
18
19
 
19
- For every **xynthesis-domain** LLM capability (not ai-skills MAIN):
20
+ | Layer | Responsibility |
21
+ |-------|----------------|
22
+ | **FuncX** | Host prompts (Catalox `fx/*` content + `content:primitives:sync`), validate I/O, `run(functionId, envelope, runOptions)` |
23
+ | **xynthesis** | Model resolve, Optimixer / `outputExpectation`, JSON parse, Activix, `InvokeAttemptSummary`; gate FuncX prompts with `XYNTHESIS_FUNCX_SIDEKICK=1` |
24
+ | **ai-tasks** | Build envelopes; merge adapted JSON into `RunTaskRequest`; no inline `DEFAULT_SYSTEM` for migrated steps |
20
25
 
21
- 1. **Wire:** `GenericExecutionEnvelope` — `goal`, `input`, `context`, optional `result`, `args`, `attribution`.
22
- 2. **Prompt host:** FuncX function (built-in or Catalox content) — templates read envelope fields and **`args`** for per-template customization (guidelines, caps, variant keys).
23
- 3. **Orchestration:** `@exellix/xynthesis` owns model resolution, Optimixer / `outputExpectation`, JSON parse, Activix, `InvokeAttemptSummary` — ideally by calling **`run(functionId, envelope, options)`** instead of re-rendering duplicate templates and calling `Client.ask` directly.
24
- 4. **ai-tasks:** Builds envelopes only; merges adapted JSON into `RunTaskRequest` (planner/optimizer/web-scope). No inline system prompts for these paths.
26
+ **Two envelope families** (do not conflate):
25
27
 
26
- **Today (gap):** FuncX already ships built-ins `execution-plan`, `execution-evaluate-result`, `research-plan-questions` with envelope-shaped I/O, but **xynthesis 4.4 re-hosts prompts** under sidekick templates and uses `executeXynthesisAction` + `FuncxInvoker.ask`. **Post-steps and AI scoping** still use **caller-built** `systemPrompt` / `userPrompt` strings in ai-tasks (partially duplicated vs xynthesis `templates/audit`, `templates/fix`).
28
+ 1. **`GenericExecutionEnvelope`** — `@x12i/funcx/functions` type for **execution / research** built-ins (`execution/plan`, `execution/evaluate-result`, `research/plan-questions`, …).
29
+ 2. **`SidekickGenericEnvelope`** — defined in **xynthesis** (`sidekickFuncxEnvelope.ts`) for **pre/post sidekick** built-ins (`pre/synthesize`, `post/audit`, …). FuncX should accept the same *shape* at `run()` time; a dedicated exported type is optional (FR-PRE-POST-8).
27
30
 
28
31
  ---
29
32
 
30
- ## 1. Audit — where instructions live
33
+ ## 1. FuncX 4.4.0 — shipped structure (source of truth)
31
34
 
32
- | Capability | Prompt / instructions today | Wire today | Generic envelope? | FuncX `run()`? |
33
- |------------|----------------------------|------------|-------------------|----------------|
34
- | **execution-plan** | `xynthesis/templates/execution-plan/*` + `buildExecutionStrategyPrompts` | xynthesis `RunExecutionPlanRequest` | Yes (ai-tasks builds payload) | Built-in exists; **not used** by xynthesis 4.4 |
35
- | **execution-evaluate-result** | Same pattern | xynthesis request + `result` | Yes | Built-in exists; **not used** |
36
- | **plan-web-scope-questions** | Same pattern | `goal` / `input` / `context` / `args` | Yes | `research-plan-questions` built-in; **not used** |
37
- | **synthesis (PRE)** | xynthesis `templates/synthesis/*` | `SidekickInput` + rendered skill text | **Sidekick envelope** (FR-PRE-POST) | **`pre/synthesize`** — **missing** |
38
- | **post-audit** | **ai-tasks** `loadAuditTemplates` + `DEFAULT_SYSTEM` | Pre-built prompts → `executeXynthesisAction` | **Sidekick envelope** | **`post/audit-checklist`** — **missing** |
39
- | **post-polish** | **ai-tasks** `loadPolishTemplates` + `DEFAULT_SYSTEM` | Pre-built prompts; Optimixer maps stage → `fix` | **Sidekick envelope** | **`post/fix`** — **missing** |
40
- | **ai-scoping** | **Inline** `SCOPING_SYSTEM` in `runScopingCall.ts` | Pre-built prompts; no `sidekickAction` | **No** | **Missing** |
41
- | **audit / fix / pick-best / craft-final** (xynthesis-native) | xynthesis `templates/{audit,fix,...}/*` | `runSidekickGatewayCall` when used | Sidekick envelope | **`post/*`** — **missing** (today: rendrix + `ask`) |
35
+ Reviewed from `@x12i/funcx` **4.4.0** (`dist/functions`, README). Use this when implementing or extending FRs.
42
36
 
43
- **Duplication risk:** xynthesis 4.4 execution-strategy templates and FuncX `content-seed` / Catalox prompts for the same three capabilities can drift unless one is canonical.
37
+ ### 1.1 Call surface
44
38
 
45
- **ai-tasks still correct for:** envelope construction (`buildPlannerGenericPayload`, `buildOptimizerGenericPayload`, `buildResearchPlanQuestionsPayload`) and response adapters (`adaptExecutionPlanResult`, etc.) — keep even when xynthesis calls FuncX internally.
46
-
47
- ---
48
-
49
- ## 2. FuncX feature requests (tracker)
50
-
51
- | FR id | Topic | Priority |
52
- |-------|--------|----------|
53
- | **FR-GEN-1** | Canonical **template context** from `GenericExecutionEnvelope` | P0 |
54
- | **FR-GEN-2** | **`args` → template customization** contract (document + validate) | P0 |
55
- | **FR-GEN-3** | **Output JSON schemas** aligned with ai-tasks adapters | P0 |
56
- | **FR-GEN-4** | **`run()` + `RunOptions`** for model, timeout, `response_format`, attribution | P1 |
57
- | **FR-GEN-5** | **`runGenericExecution`** helper (envelope → ask → parse → usage) for xynthesis | P1 |
58
- | **FR-GEN-6** | **Post-step generic** functions (`post/audit`, `post/polish` or `xynthesis/audit`) | P1 |
59
- | **FR-PRE-POST-*** | **Pre/post sidekick built-ins** + Catalox mapping — see [**funcx-pre-post-sidekick-actions.md**](./funcx-pre-post-sidekick-actions.md) | **P0** |
60
- | **FR-GEN-7** | **AI scoping** generic function (`scoping/run` or `research/scope-content`) | P2 |
61
- | **FR-GEN-8** | **`strategyArgs` vs `args`** on wire (or documented merge rule) | P1 |
62
- | **FR-GEN-9** | **Catalox seed parity** with xynthesis 4.4 templates + CI diff | P1 |
63
- | **FR-GEN-10** | **Deprecate** legacy `ai-tasks-plan-task` / `ai-tasks-optimizer-evaluate` ids | P2 |
64
- | **FR-GEN-11** | **Sidekick-shaped** post-steps via envelope (audit checks in `context`) | P2 |
65
- | **FR-GEN-12** | **Contract tests** package: envelope fixtures → expected adapter output | P1 |
66
-
67
- §6 in [`funcx-scoping-integration-gaps.md`](../funcx-scoping-integration-gaps.md) remains the **adapter-level** contract for execution/research ids; this doc adds **hosting + template** requirements.
68
-
69
- ---
70
-
71
- ### FR-GEN-1 — Canonical template context from envelope
72
-
73
- **Need:** Every generic execution/research built-in must render prompts from a **stable, documented** variable map derived from the envelope — not ad hoc TS string building in each consumer.
74
-
75
- **Require FuncX built-ins / Catalox templates to expose at minimum:**
76
-
77
- | Token / field | Source |
78
- |---------------|--------|
79
- | `goal` | `envelope.goal` (string, trimmed) |
80
- | `input_json` | `JSON.stringify(envelope.input ?? null)` with documented max length + truncation suffix |
81
- | `context_json` | `JSON.stringify(envelope.context ?? {})` — same truncation rules |
82
- | `result_json` | Optimizer / evaluate only — `envelope.result` |
83
- | `args_json` | `JSON.stringify(envelope.args ?? {})` |
84
- | `iteration_index` | `envelope.args.iterationIndex` when present (stringified) |
85
-
86
- **Ask:** Export `buildGenericExecutionTemplateContext(envelope): Record<string, string>` from `@x12i/funcx/functions` (or document it in `docs/migration-generic-execution.md`) so xynthesis can stop duplicating `executionStrategyPromptTemplate.ts` stringification.
39
+ ```ts
40
+ import { run, getRunJsonResult, buildAskAttribution } from "@x12i/funcx/functions";
41
+ import type { GenericExecutionEnvelope } from "@x12i/funcx/functions";
42
+
43
+ const raw = await run("execution/plan", envelope, {
44
+ client,
45
+ model: resolvedSlug,
46
+ timeoutMs: 60_000,
47
+ responseFormat: { kind: "json_object" },
48
+ includeUsage: true,
49
+ });
50
+ const json = getRunJsonResult(raw);
51
+ ```
87
52
 
88
- **Acceptance:** xynthesis 4.4 templates and FuncX Catalox seeds use the **same** token names; one integration test compares rendered user prompt hashes for a golden fixture.
53
+ | Mechanism | Behavior |
54
+ |-----------|----------|
55
+ | **Id normalization** | Slash ids in constants (`execution/plan`) → hyphen registry keys (`execution-plan`) inside router |
56
+ | **Constants** | `FUNCX_EXECUTION_PLAN_FUNCTION_ID`, `FUNCX_EXECUTION_EVALUATE_RESULT_FUNCTION_ID`, `FUNCX_RESEARCH_PLAN_QUESTIONS_FUNCTION_ID` |
57
+ | **Schema** | `genericExecutionEnvelopeJsonSchema` (draft Ajv object; `goal` required at runtime for built-ins) |
58
+ | **Unwrap** | `getRunJsonResult` / `isHttpRunSuccessBody` — HTTP `{ result, usage }` vs in-process plain object |
89
59
 
90
- ---
60
+ ### 1.2 `GenericExecutionEnvelope` (shipped)
91
61
 
92
- ### FR-GEN-2 — `args` → template-level customization
62
+ ```ts
63
+ type GenericExecutionEnvelope = {
64
+ goal?: unknown; // runtime: non-empty string for execution/research built-ins
65
+ input?: unknown;
66
+ context?: unknown;
67
+ result?: unknown; // optimizer / evaluate-result
68
+ args?: Record<string, unknown>;
69
+ attribution?: Record<string, unknown>;
70
+ client?: Client; // in-process only; omit on HTTP
71
+ };
72
+ ```
93
73
 
94
- **Need:** Strategy rows and hosts pass opaque knobs in `args` (minus `functionId`) that **templates** read without new function ids — e.g. `customGuidelines`, `maxQuestions`, `allowSkip`, `templateVariant`, `density`.
74
+ **Not on the type today:** `strategyArgs` (xynthesis merges into `args` before `run()` — see §2.3).
95
75
 
96
- **Today (ai-tasks / xynthesis):**
76
+ ### 1.3 `buildAskAttribution` (shipped)
97
77
 
98
- - Planner/optimizer: `strategyArgs` forwarded separately in xynthesis; FuncX types only document `args`.
99
- - Audit: `customAuditGuidelines` merged in ai-tasks `renderAuditSystem`, not in envelope.
100
- - Web-scope: `args.maxQuestions`, `args.sourceType`, `args.allowSkip`.
78
+ `buildAskAttribution(implFunctionId, req)` merges:
101
79
 
102
- **Ask:**
80
+ - Top-level / `attribution.*`: `projectId`, `traceId`, `jobId`, `taskId`, `agentId`, `runId`, `parentRunId`, `actorId`, `subjectId`
81
+ - `attribution.tags` and top-level `tags`
82
+ - Preserves implementing `functionId`; stores caller `attribution.functionId` in `tags.callerFunctionId`
103
83
 
104
- 1. Document **reserved vs extension** keys in `args` per function id (JSON Schema `args` sub-schemas in `fx/*/meta.json`).
105
- 2. Support **nested template overrides** via convention, e.g. `args.promptOverrides.systemSuffix`, `args.customGuidelines`, without breaking generic envelope validation.
106
- 3. Optional: `args._templateProfile: "strict" | "lenient"` to select Catalox template variant.
84
+ **xynthesis / ai-tasks today:** `buildSidekickFuncxAttribution` / `buildExecutionStrategyAttribution` set `runId`←jobId, `subjectId`←taskId, `actorId`←agentId — compatible with FuncX merge rules.
107
85
 
108
- **Acceptance:** Changing only `args.customGuidelines` in a fixture changes the rendered system prompt in tests; no TypeScript change in consumers.
86
+ ### 1.4 `RunOptions` (shipped — partial vs orchestrator needs)
109
87
 
110
- ---
88
+ | Field | Shipped in 4.4.0 |
89
+ |-------|------------------|
90
+ | `client`, `model`, `backend`, `timeoutMs`, `signal` | Yes |
91
+ | `responseFormat` (`json_object` / text) | Yes |
92
+ | `includeUsage`, `validateOutput`, `profile` (race) | Yes |
93
+ | `temperature`, `topP`, `reasoningEffort` | **No** on `RunOptions` (still use `Client.ask` / xynthesis `FuncxInvoker` for sampling) |
111
94
 
112
- ### FR-GEN-3 — Output JSON schemas aligned with ai-tasks adapters
95
+ ### 1.5 Hosting model (content + router)
113
96
 
114
- **Need:** Built-in outputs must match what [`adaptExecutionPlanResult`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts), [`adaptEvaluateResultResponse`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts), and [`adaptResearchPlanQuestionsResult`](../../src/execution-strategies/genericExecutionFuncxEnvelope.ts) expect.
97
+ | Class | Examples | How prompts run |
98
+ |-------|----------|-----------------|
99
+ | **Content-backed** | `execution-plan`, `execution-evaluate-result`, `research-plan-questions`, `research-plan-web-search`, `research-plan-scoped-questions` | Catalox `fx/{id}/` via `executeFuncxFromContent`; instructions rendered with `renderInstructionTemplate(instructions, { input: request, variables })` where **`request` is the full envelope** passed to `run()` |
100
+ | **Code-bound router** | Primitives, runx.*, repair JSON, … | TS handlers; generic execution family delegates to `run("execution-plan", …)` |
101
+ | **Legacy (deprecate)** | `ai-tasks-plan-task`, `ai-tasks-optimizer-evaluate` | Hyphen ids; same envelope family; superseded by `execution-plan` / `execution-evaluate-result` |
115
102
 
116
- **Planner (`execution-plan` / `execution/plan`):**
117
- `plan?`, `instructions?`, `steps[]`, `assumptions[]`, `missingInputs[]`, optional `prompt`, `variables`, `templateTokens` (top-level or under `metadata`).
103
+ **Seed bundle:** `content-seed/functions/genericExecutionResearch.seed.json` → `npm run content:primitives:sync` (see FuncX README § Catalox merged primitive seeds).
118
104
 
119
- **Optimizer (`execution-evaluate-result`):**
120
- `satisfied` (boolean), `feedback?`, `suggestedChanges[]`, `issues[]`, optional `variables`, `templateTokens`, `metadata`.
105
+ **Executor primitives (all functions):** `executeFuncx` → `callAI` with `buildFuncxUserPrompt(buildPrompt(request))` — user message is JSON (or prefixed JSON body), not xynthesis-style pre-rendered system+user strings.
121
106
 
122
- **Research (`research-plan-questions`):**
123
- `questions[]` with `question`, optional `reason`, `confidence`; optional `skipped`, `reasonCodes`.
107
+ ### 1.6 Built-in I/O types (shipped — align adapters)
124
108
 
125
- **Ask:** Publish machine-readable schemas next to built-ins; version with semver when fields change. Include **`getRunJsonResult`** normalization examples in docs.
109
+ | Registry id | `run()` alias | Input highlights | Output highlights |
110
+ |-------------|---------------|------------------|-------------------|
111
+ | `execution-plan` | `execution/plan` | `goal`, `input?`, `context?`, `args?`, `attribution?` | `plan?`, `instructions?`, `steps[]`, `assumptions[]`, `missingInputs[]`, `metadata?` |
112
+ | `execution-evaluate-result` | `execution/evaluate-result` | + required `result` | `satisfied`, `feedback?`, `suggestedChanges[]`, `issues[]`, `metadata?` |
113
+ | `research-plan-questions` | `research/plan-questions` | same envelope | `questions[]`, `skipped?`, `reasonCodes?`, `confidence?` |
126
114
 
127
- **Gap vs xynthesis 4.4 parsers:** If FuncX adds fields, xynthesis `parseExecutionStrategyPayload` should defer to FuncX schema or share one JSON Schema file.
115
+ ai-tasks adapters: `adaptExecutionPlanResult`, `adaptEvaluateResultResponse`, `adaptResearchPlanQuestionsResult`.
128
116
 
129
117
  ---
130
118
 
131
- ### FR-GEN-4 — `run()` + `RunOptions` for orchestrator controls
132
-
133
- **Need:** `@exellix/xynthesis` must pass **resolved model**, timeout, temperature, `response_format: json_object`, and merged **attribution** without re-implementing `ask()` options.
134
-
135
- **Ask:**
136
-
137
- - Extend `RunOptions` (or documented overload) with: `model`, `timeoutMs`, `temperature`, `topP`, `reasoningEffort`, `responseFormat`, `maxTokens` / completion cap hint.
138
- - Built-ins call `buildAskAttribution(implFunctionId, envelope)` internally when `attribution` is present.
139
- - Return shape includes **`usage`** and fields xynthesis maps to `InvokeAttemptSummary` (or document mapping table).
140
-
141
- **Acceptance:** xynthesis `invokeExecutionStrategyAction` can replace `executeXynthesisAction` + manual prompts with `run(FUNCX_EXECUTION_PLAN_FUNCTION_ID, payload, options)` while preserving observability parity.
142
-
143
- ---
119
+ ## 2. Consumer prep (shipped in mono-repo)
144
120
 
145
- ### FR-GEN-5 — `runGenericExecution` helper for embedders
121
+ | Artifact | Package | Status |
122
+ |----------|---------|--------|
123
+ | `sidekickFuncxCatalogMap.ts` | xynthesis | **Shipped** — actionType ↔ `funcxFunctionId` ↔ Catalox catalog |
124
+ | `sidekickFuncxEnvelope.ts` | xynthesis | **Shipped** — `buildSidekickGenericEnvelope`, `buildExecutionStrategyGenericEnvelope` |
125
+ | `ENV_SIDEKICK_FUNCX` (`XYNTHESIS_FUNCX_SIDEKICK=1`) | xynthesis | **Shipped** — gate; no `run()` wiring in gateway yet |
126
+ | Catalox `XynthesisActionItem.funcx` | xynthesis seed | **Shipped** — `functionId` + `contentVersion: "0.0.0-pending-funcx"` |
127
+ | `auditChecklistFuncxEnvelope.ts` | ai-tasks | **Shipped** — `post/audit-checklist`, `post/audit-merge` envelopes |
128
+ | Execution via xynthesis actions | ai-tasks 8.5+ | **Shipped** — not direct `run()` from ai-tasks |
129
+ | `runExecutionStrategyViaXynthesis` | ai-tasks | **Shipped** — still uses xynthesis disk templates + `FuncxInvoker.ask` |
146
130
 
147
- **Need:** Thin API for packages that already own parse/Activix but should not fork prompt assembly.
131
+ ### 2.1 `strategyArgs` merge (consumer — no FuncX FR)
148
132
 
149
- **Proposed export (`@x12i/funcx/functions`):**
133
+ `buildExecutionStrategyGenericEnvelope` folds `req.strategyArgs` into **`args`** (and sets `args.iterationIndex` for optimizer). **Do not** wait for a FuncX type extension; hosts must merge before `run()`.
150
134
 
151
- ```ts
152
- runGenericExecution(opts: {
153
- functionId: string;
154
- envelope: GenericExecutionEnvelope;
155
- client?: Client;
156
- runOptions?: RunOptions;
157
- }): Promise<{ value: unknown; usage?: Usage; model?: string; raw?: unknown }>;
158
- ```
135
+ ### 2.2 Template token convention (parity gap)
159
136
 
160
- **Behavior:** Resolve content → render templates from FR-GEN-1 context → `ask` / `askJson` → validate against function output schema → return parsed object.
137
+ | Source | User-prompt tokens |
138
+ |--------|-------------------|
139
+ | **xynthesis disk** (`executionStrategyPromptTemplate.ts`) | `goal`, `input_json`, `context_json`, `result_json`, `args_json`, `strategy_args_json`, `iteration_index` |
140
+ | **FuncX content render** (envelope = `request`) | Typically `{{input.goal}}`, `{{input.context}}`, … via rendrix `input` = full envelope |
161
141
 
162
- **Acceptance:** xynthesis deletes duplicate template render path when this ships; tests use `createAskMock` at FuncX boundary only.
142
+ **FR-GEN-1** (revised): FuncX should export **`envelopeToTemplateVariables(envelope)`** that produces **both** conventions (or document Catalox seeds must use `input.*` paths). Until then, FR-GEN-9 parity diffs must compare normalized renders, not raw file text.
163
143
 
164
144
  ---
165
145
 
166
- ### FR-GEN-6 — Post-step generic functions (audit, polish)
167
-
168
- **Need:** Remove ai-tasks **inline** `DEFAULT_SYSTEM` and duplicate template trees; use envelope + FuncX templates.
169
-
170
- **Proposed ids:**
171
-
172
- | Capability | Suggested `functionId` | Envelope highlights |
173
- |------------|------------------------|---------------------|
174
- | Audit evaluator | `post/audit` or `xynthesis/audit` | `goal`: audit objective; `input`: output under test; `context`: checks, synthesis excerpt, pass metadata; `args`: `customGuidelines`, `passNumber` |
175
- | Polish | `post/polish` or `xynthesis/fix` | `input`: draft output; `context`: checklist, prior pass notes; `args`: `customGuidelines` |
176
-
177
- **Output:** Audit — markdown or structured sections; Polish — JSON `{ polishedOutput, changeNotes }` per current ai-tasks parsers.
146
+ ## 3. Audit — instructions vs `run()` (current)
178
147
 
179
- **Acceptance:** `runAuditCall` / `runPolishCall` build envelope + `run()`; xynthesis `executeXynthesisAction` only for transport if still needed, or xynthesis wraps FR-GEN-5.
148
+ | Capability | Prompt host today | Envelope | FuncX built-in 4.4.0 |
149
+ |------------|-------------------|----------|----------------------|
150
+ | execution-plan / optimizer / web-scope | xynthesis templates + `ask` | `GenericExecution*` via builders | **Yes** — not called from xynthesis yet |
151
+ | synthesis, audit, fix, pick-best, craft-final | xynthesis disk / Catalox + `ask` | `SidekickGenericEnvelope` when wired | **No** — see [funcx-pre-post-sidekick-actions.md](./funcx-pre-post-sidekick-actions.md) |
152
+ | ai-tasks checklist audit / merge | ai-tasks Handlebars | `auditChecklistFuncxEnvelope` | **No** (`post/audit-checklist`, `post/audit-merge`) |
153
+ | ai-scoping | inline `SCOPING_SYSTEM` | none | **No** |
180
154
 
181
155
  ---
182
156
 
183
- ### FR-GEN-7 — AI scoping generic function
184
-
185
- **Need:** Replace `SCOPING_SYSTEM` constant in [`runScopingCall.ts`](../../src/aiScoping/runScopingCall.ts).
186
-
187
- **Proposed id:** `scoping/run` or `research/scope-content`
188
-
189
- **Envelope:**
190
-
191
- - `goal`: scoping directive (from caller `instructions`)
192
- - `input`: `{ sourceContent: string }` or raw string policy documented
193
- - `args`: `outputExpectation` hints, `maxOutputLength`
194
-
195
- **Output:** Plain text scoped result (no markdown / fences) — document in schema.
196
-
197
- **Acceptance:** No inline system string in ai-tasks; FuncX template owns behavior.
157
+ ## 4. Feature request tracker (aligned to 4.4.0)
158
+
159
+ | FR id | Topic | Status @ 4.4.0 |
160
+ |-------|--------|----------------|
161
+ | **FR-GEN-0** | Baseline: envelope, constants, `buildAskAttribution`, `getRunJsonResult`, execution/research built-ins, `genericExecutionResearch` seed | **Shipped** |
162
+ | **FR-GEN-1** | `envelopeToTemplateVariables` (+ document `input.*` vs `*_json` tokens) | **Open** |
163
+ | **FR-GEN-2** | Per-function `args` JSON Schema + template knobs (`customGuidelines`, …) | **Open** (partially by convention) |
164
+ | **FR-GEN-3** | Published output schemas shared with xynthesis parsers | **Open** (TS types exist; no shared JSON Schema artifact) |
165
+ | **FR-GEN-4** | `RunOptions`: `temperature`, `topP`, `reasoningEffort` | **Open** (partial: model, timeout, responseFormat shipped) |
166
+ | **FR-GEN-5** | `runGenericExecution({ functionId, envelope, runOptions })` embedder helper | **Open** |
167
+ | **FR-GEN-6** | Post-step checklist / merge built-ins | **Open** → FR-PRE-POST-2 |
168
+ | **FR-GEN-7** | AI scoping built-in | **Open** |
169
+ | **FR-GEN-8** | `strategyArgs` on wire | **Closed (consumer)** — merge into `args` in xynthesis |
170
+ | **FR-GEN-9** | Catalox seed ↔ xynthesis template parity CI | **Open** |
171
+ | **FR-GEN-10** | Deprecate `ai-tasks-plan-task` / `ai-tasks-optimizer-evaluate` | **Open** |
172
+ | **FR-GEN-11** | Rich audit `context` sub-schema on envelope | **Open** (checklist envelope shipped in ai-tasks) |
173
+ | **FR-GEN-12** | Golden fixtures package | **Open** |
174
+ | **FR-PRE-POST-*** | Pre/post sidekick built-ins | **Open** — [funcx-pre-post-sidekick-actions.md](./funcx-pre-post-sidekick-actions.md) |
198
175
 
199
176
  ---
200
177
 
201
- ### FR-GEN-8 — `strategyArgs` vs `args` on wire
178
+ ## 5. Open FR details (only what 4.4.0 does not cover)
202
179
 
203
- **Need:** ai-tasks execution strategies pass catalog row `args` (minus `functionId`) while xynthesis 4.4 also accepts `strategyArgs` on the request object.
180
+ ### FR-GEN-1 — Template variables from envelope
204
181
 
205
- **Options (pick one in FuncX):**
206
-
207
- 1. **Merge rule:** At `run()` entry, `effectiveArgs = { ...envelope.args, ...envelope.strategyArgs }` if `strategyArgs` is added to `GenericExecutionEnvelope`.
208
- 2. **Document:** Consumers must fold `strategyArgs` into `args` before `run()`; export `mergeStrategyArgs(envelope)` helper.
209
-
210
- **Ask:** Update `GenericExecutionEnvelope` TypeScript type and `genericExecutionEnvelopeJsonSchema` if `strategyArgs` becomes first-class.
211
-
212
- ---
213
-
214
- ### FR-GEN-9 — Catalox seed parity with xynthesis 4.4
215
-
216
- **Need:** Single canonical prompt source.
182
+ **Need:** One function used by content-backed built-ins and xynthesis so Catalox instructions and `xynthesis/templates/*` stay aligned.
217
183
 
218
184
  **Ask:**
219
185
 
220
- 1. Diff `xynthesis/templates/execution-*` and `plan-web-scope-questions` against `content-seed/functions/genericExecutionResearch.seed.json` (or per-function seeds).
221
- 2. CI job fails on drift unless bumping `contentVersion`.
222
- 3. Document sync procedure: xynthesis exports → FuncX seed import (or FuncX seed → xynthesis pull).
186
+ ```ts
187
+ envelopeToTemplateVariables(
188
+ envelope: GenericExecutionEnvelope | SidekickGenericEnvelope
189
+ ): Record<string, string>;
190
+ ```
223
191
 
224
- **Acceptance:** Product can disable xynthesis disk templates when Catalox actions enabled (`isCataloxActionsEnabled`) without behavior change.
192
+ Minimum keys: parity with `buildExecutionStrategyUserVars` **and** nested `input.goal` style for `renderInstructionTemplate`.
225
193
 
226
- ---
194
+ ### FR-GEN-2 — `args` contract
227
195
 
228
- ### FR-GEN-10 — Deprecate legacy ai-tasks function ids
196
+ Document reserved keys per `functionId` in `fx/*/meta.json`. Execution/research: `maxQuestions`, `allowSkip`, `sourceType`, `iterationIndex`, `customGuidelines`, `templateMode`, …
229
197
 
230
- **Need:** FuncX registry still lists `ai-tasks-plan-task`, `ai-tasks-optimizer-evaluate` alongside `execution-plan`, `execution-evaluate-result`.
198
+ ### FR-GEN-3 — Shared output JSON Schema
231
199
 
232
- **Ask:** Mark legacy ids deprecated in meta; route aliases to generic built-ins; remove from seed catalog after one major.
200
+ Export versioned schemas next to built-ins; xynthesis `parseExecutionStrategyPayload` / sidekick parsers consume same files.
233
201
 
234
- ---
202
+ ### FR-GEN-4 — Orchestrator sampling on `run()`
235
203
 
236
- ### FR-GEN-11 — Sidekick-shaped post-steps via envelope (optional)
204
+ Add optional `temperature`, `topP`, `reasoningEffort` to `RunOptions` (or document that embedders must use `executeFuncxFromContent` + custom `callAI` until then). xynthesis today passes sampling via **`FuncxInvoker.ask`**, not `run()`.
237
205
 
238
- **Need:** Audit today uses rich `SidekickInput` (checks array, material blocks). Migrating to envelope should not lose structure.
206
+ ### FR-GEN-5 — `runGenericExecution`
239
207
 
240
- **Ask:** Define `context.audit` sub-schema (checks, outputText, synthesisSummary, …) in FR-GEN-6 meta so templates stay declarative.
208
+ Thin wrapper: resolve content → render → `askJson` → `getRunJsonResult` → return `{ value, usage, model }`. Sidekick variant accepts `SidekickGenericEnvelope` (FR-PRE-POST-5).
241
209
 
242
- ---
210
+ ### FR-GEN-9 — Seed parity
243
211
 
244
- ### FR-GEN-12 — Contract tests for adapters
212
+ Compare `genericExecutionResearch.seed.json` + deployed `fx/execution-plan/*` to `xynthesis/templates/execution-*` using **FR-GEN-1** normalized variables.
245
213
 
246
- **Need:** Prevent drift between FuncX built-in output and ai-tasks adapters.
214
+ ### FR-GEN-10 — Legacy ids
247
215
 
248
- **Ask:** Ship `test/fixtures/generic-execution/*.json` in `@x12i/funcx` run in CI; ai-tasks imports fixtures or duplicates with cross-package version pin.
216
+ Alias `ai-tasks-plan-task` → `execution-plan`, `ai-tasks-optimizer-evaluate` → `execution-evaluate-result`; mark deprecated in seed meta.
249
217
 
250
218
  ---
251
219
 
252
- ## 3. Recommended convergence path
220
+ ## 6. Convergence path
253
221
 
254
222
  ```mermaid
255
223
  flowchart LR
256
- subgraph ai_tasks
257
- A[buildPlannerGenericPayload]
224
+ subgraph consumers
225
+ AT[ai-tasks envelope builders]
226
+ XY[xynthesis run* / gateway]
258
227
  end
259
- subgraph xynthesis
260
- B[runExecutionPlan]
261
- C{FR-GEN-5 shipped?}
228
+ subgraph funcx44 [FuncX 4.4 shipped]
229
+ RUN[run slash id]
230
+ ATTR[buildAskAttribution]
231
+ SEED[genericExecutionResearch seed]
262
232
  end
263
- subgraph funcx
264
- D[run execution-plan]
265
- E[Catalox templates + args]
233
+ subgraph funcxNext [FuncX next]
234
+ PRE[pre/post built-ins]
235
+ VARS[envelopeToTemplateVariables]
266
236
  end
267
- A --> B
268
- B --> C
269
- C -->|yes| D
270
- C -->|interim 4.4| F[disk templates + ask]
271
- D --> E
272
- F --> E
237
+ AT --> XY
238
+ XY -->|XYNTHESIS_FUNCX_SIDEKICK=1| RUN
239
+ RUN --> ATTR
240
+ RUN --> SEED
241
+ PRE --> RUN
242
+ VARS --> SEED
273
243
  ```
274
244
 
275
- 1. **FuncX:** Implement FR-GEN-1–3, FR-GEN-9 (canonical prompts + schemas).
276
- 2. **FuncX:** FR-GEN-4–5 so xynthesis can call `run()` without duplicate `executionStrategyPromptTemplate.ts`.
277
- 3. **xynthesis:** Follow-up FR (separate doc) — switch `invokeExecutionStrategyAction` to FuncX `run()`; keep parsers/adapters.
278
- 4. **ai-tasks:** FR-GEN-6–7 for audit/polish/scoping; stop shipping `DEFAULT_SYSTEM` strings.
279
- 5. **Docs:** Update [`funcx-catalog-hosting-checklist.md`](../funcx-catalog-hosting-checklist.md) — built-ins are canonical; Catalox overrides via `args`.
245
+ 1. **Done:** execution/research envelopes + built-ins + attribution (4.4.0).
246
+ 2. **Next FuncX:** FR-GEN-1, FR-PRE-POST-1..4, FR-GEN-9 (before xynthesis deletes duplicate renderers).
247
+ 3. **xynthesis:** Wire `invokeExecutionStrategyAction` / gateway to `run(resolveSidekickFuncxFunctionId(...), envelope, opts)` behind `XYNTHESIS_FUNCX_SIDEKICK=1`.
248
+ 4. **ai-tasks:** Switch audit/polish/scoping to envelope + `run()` after post built-ins land.
280
249
 
281
250
  ---
282
251
 
283
- ## 4. Non-goals
252
+ ## 7. Non-goals
284
253
 
285
- - Changing ai-skills MAIN `instructions` / `prompt` contract.
286
- - Moving synthesis PRE-step template **cores** (`{{core:analysis}}`) into FuncX — cores stay rendrix/ai-skills; FuncX hosts the **synthesis action** via `pre/synthesize` (see [funcx-pre-post-sidekick-actions.md](./funcx-pre-post-sidekick-actions.md)).
287
- - Forcing ai-tasks to call `@x12i/funcx` directly again for execution strategies (xynthesis remains the facade after FR-GEN-5).
254
+ - ai-skills MAIN `instructions` / `prompt`.
255
+ - Template **cores** (`{{core:analysis}}`) inside FuncX — stay rendrix/ai-skills; `pre/synthesize` envelope carries **pre-rendered** downstream blocks in `input`.
256
+ - Forcing ai-tasks to call `@x12i/funcx` directly for execution strategies (xynthesis remains facade).
288
257
 
289
258
  ---
290
259
 
291
- ## 5. Version note
260
+ ## 8. Version note
261
+
262
+ | Package | Version | Notes |
263
+ |---------|---------|-------|
264
+ | `@x12i/funcx` | **4.4.0** (npm latest reviewed) | Baseline for §1 |
265
+ | `@exellix/xynthesis` | **4.4.3** | FuncX map + envelopes; execution hop still disk+ask |
266
+ | `@exellix/ai-tasks` | **8.5.2** | xynthesis actions; checklist envelopes ready |
292
267
 
293
- - **@x12i/funcx** ≥ **4.2.0** (ai-tasks dep): `FUNCX_*_FUNCTION_ID`, `genericExecutionEnvelopeJsonSchema`, `buildAskAttribution`, `getRunJsonResult`.
294
- - Built-in ids in registry: `execution-plan`, `execution-evaluate-result`, `research-plan-questions` (slash aliases normalize per README).
268
+ When FuncX ships pre/post built-ins, bump `contentVersion` on Catalox items from `0.0.0-pending-funcx` and enable `XYNTHESIS_FUNCX_SIDEKICK=1` in CI.