@exellix/graph-composer 2.2.1 → 2.4.2

package/functions/graph-composer/meta.json

@@ -93,6 +93,86 @@
         "source": { "type": "string" }
       }
     },
+    "GraphEntryInputRow": {
+      "type": "object",
+      "required": ["path"],
+      "properties": {
+        "kind": { "enum": ["scalar", "record"] },
+        "path": {
+          "type": "string",
+          "description": "Must start with execution.input."
+        },
+        "required": { "type": "boolean" },
+        "entityIds": { "type": "array", "items": { "type": "string" } },
+        "label": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "GraphEntryExampleRow": {
+      "type": "object",
+      "required": ["format", "value"],
+      "properties": {
+        "path": { "type": "string" },
+        "format": { "enum": ["json", "markdown", "text"] },
+        "value": { "type": "string" }
+      }
+    },
+    "GraphEntryPatch": {
+      "type": "object",
+      "properties": {
+        "inputs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/GraphEntryInputRow" }
+        },
+        "exampleInputs": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/GraphEntryExampleRow" }
+        },
+        "conditions": { "type": "object" }
+      }
+    },
+    "ModelConfigPatch": {
+      "type": "object",
+      "properties": {
+        "mode": { "enum": ["appendCase", "replaceDefault"] },
+        "cases": { "type": "array", "items": { "type": "object" } },
+        "modelConfig": {
+          "type": "object",
+          "properties": {
+            "preActionModel": { "type": "string" },
+            "skillModel": { "type": "string" },
+            "postActionModel": { "type": "string" }
+          }
+        }
+      }
+    },
+    "JobPagentiKnowledgePatch": {
+      "type": "object",
+      "properties": {
+        "refs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["catalogId", "itemId"],
+            "properties": {
+              "catalogId": { "type": "string" },
+              "itemId": { "type": "string" }
+            }
+          }
+        },
+        "append": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["catalogId", "itemId"],
+            "properties": {
+              "catalogId": { "type": "string" },
+              "itemId": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
     "RequirementOptionEntry": {
       "type": "object",
       "description": "Ambiguous requirement field: candidates and whether a new catalog artifact is needed",
@@ -238,7 +318,14 @@
                 "suggestCatalogCreations",
                 "suggestScopingNeedMatch",
                 "suggestScopingMapCreation",
-                "reviewConcept"
+                "reviewConcept",
+                "reviewGraphEntryContract",
+                "suggestGraphEntryInputs",
+                "suggestGraphEntryExamples",
+                "suggestGraphEntryConditions",
+                "suggestJobModelDefaults",
+                "suggestJobKnowledgeRefs",
+                "suggestGraphExecutionDefaults"
               ]
             },
             "description": {
@@ -265,9 +352,13 @@
           }
         },
         "existingGraph": {
-          "description": "Required for modify, explain, suggestConceptObjective, suggestCatalogResolution, suggestCatalogCreations, reviewConcept. Optional for suggestScopingNeedMatch (context) and suggestScopingMapCreation (alignment).",
+          "description": "Required for modify, explain, suggestConceptObjective, suggestCatalogResolution, suggestCatalogCreations, reviewConcept, and graph-entry actions. Optional for suggestScopingNeedMatch (context) and suggestScopingMapCreation (alignment).",
           "type": "object"
         },
+        "agentContext": {
+          "type": "object",
+          "description": "graphs-studio Agent View envelope (surface graph-entry | task-node, graphEntry, jobDefaults, …)"
+        },
         "analysisContext": {
           "type": "object",
           "description": "Optional graph analysis output (execution order, IO, issues, …). Strongly recommended for suggestConceptObjective, reviewConcept, and suggestCatalog*."
@@ -336,7 +427,14 @@
             "suggestCatalogCreations",
             "suggestScopingNeedMatch",
             "suggestScopingMapCreation",
-            "reviewConcept"
+            "reviewConcept",
+            "reviewGraphEntryContract",
+            "suggestGraphEntryInputs",
+            "suggestGraphEntryExamples",
+            "suggestGraphEntryConditions",
+            "suggestJobModelDefaults",
+            "suggestJobKnowledgeRefs",
+            "suggestGraphExecutionDefaults"
           ]
         },
         "graph": {
@@ -426,13 +524,41 @@
             "summary": { "type": "string" }
           }
         },
+        "graphEntryPatch": {
+          "$ref": "#/$defs/GraphEntryPatch",
+          "description": "Partial metadata.graphEntry patch for graph-entry actions"
+        },
+        "suggestedGraphEntryPatch": {
+          "$ref": "#/$defs/GraphEntryPatch",
+          "description": "Alias for graphEntryPatch on reviewGraphEntryContract"
+        },
+        "modelConfigPatch": {
+          "$ref": "#/$defs/ModelConfigPatch",
+          "description": "Root modelConfig patch (suggestJobModelDefaults / reviewGraphEntryContract)"
+        },
+        "jobPagentiKnowledgePatch": {
+          "$ref": "#/$defs/JobPagentiKnowledgePatch",
+          "description": "Root jobPagentiKnowledge refs patch"
+        },
+        "graphExecutionPatch": {
+          "type": "object",
+          "description": "Partial metadata.graphExecution patch"
+        },
+        "graphResponsePatch": {
+          "type": "object",
+          "description": "Layer 08 response / studio persistency patch (separate from graphEntry)"
+        },
         "findings": {
           "type": "array",
-          "description": "Present for reviewConcept — categorized review findings",
+          "description": "Present for reviewConcept and reviewGraphEntryContract — categorized review findings",
           "items": {
             "type": "object",
             "required": ["category", "severity", "summary"],
             "properties": {
+              "scopeType": {
+                "type": "string",
+                "description": "graph for reviewGraphEntryContract findings"
+              },
               "category": { "type": "string" },
               "severity": { "type": "string" },
               "summary": { "type": "string" },

package/functions/graph-composer/prompts/README.md

@@ -17,6 +17,14 @@ Each **`intent.action`** maps to one **worker prompt file** plus optional **shar
 | `action-explain.md` | Worker for `explain` only |
 | `action-suggest-concept-objective.md` | Worker for `suggestConceptObjective` only |
 | `action-review-concept.md` | Worker for `reviewConcept` only (concept review, no graph JSON) |
+| `shared/graph-entry-scope.md` | Job-start / Layer 01 scope for graph-entry agent actions |
+| `action-review-graph-entry-contract.md` | Worker for `reviewGraphEntryContract` |
+| `action-suggest-graph-entry-inputs.md` | Worker for `suggestGraphEntryInputs` |
+| `action-suggest-graph-entry-examples.md` | Worker for `suggestGraphEntryExamples` |
+| `action-suggest-graph-entry-conditions.md` | Worker for `suggestGraphEntryConditions` |
+| `action-suggest-job-model-defaults.md` | Worker for `suggestJobModelDefaults` |
+| `action-suggest-job-knowledge-refs.md` | Worker for `suggestJobKnowledgeRefs` |
+| `action-suggest-graph-execution-defaults.md` | Worker for `suggestGraphExecutionDefaults` |
 | `orchestrator-system.md` | System prompt for `runGraphComposerAgent` (tool loop) |
 
 ## Appended for every worker

package/functions/graph-composer/prompts/action-review-graph-entry-contract.md

@@ -0,0 +1,37 @@
+You are a **senior graph architect** reviewing the **job-start contract** (Layer 01) for a worox-graph. Audience: product owners and operators configuring **Start Job**.
+
+**You ONLY perform `action = "reviewGraphEntryContract"` in this call.** Do not return full graph JSON, changelog, or `explanation`.
+
+### Inputs
+1. **`existingGraph`** (required): Canonical graph snapshot.
+2. **`agentContext`** (when present): Effective **`graphEntry`**, **`jobDefaults`**, **`graphResponse`**, **`graphExecution`**, **`graphConcept`**, **`diagnostics`**, **`virtualIO`**, **`lastGraphRun`**.
+3. **`intent.description`**: User question or review angle.
+4. **`analysisContext`**: Optional; use when consistent with the graph.
+
+Treat **`metadata.graphEntry`** on the graph plus **`agentContext.graphEntry`** as the entry contract under review.
+
+### Review axes
+- **Inputs**: `inputs[]` rows (`kind` scalar/record, `path` under `execution.input.*`, `required`, `entityIds`).
+- **Examples**: `exampleInputs[]` with parseable JSON when `format` is `json`; coverage for required paths.
+- **Conditions**: `conditions` (narratives, dataFilters, aiCondition) — clarify what blocks **job start** vs step gating in **`suggestedChange`**.
+- **Job models**: root **`modelConfig`** vs per-node overrides; warn when root is empty and nodes lack overrides.
+- **Knowledge**: root **`jobPagentiKnowledge`** refs — not **`jobKnowledge`** strings or task **`taskPagentiKnowledge`**.
+- **Execution defaults**: **`metadata.graphExecution`** keys; flag incompatible combos (e.g. backward mode without `goalNodeId`).
+- **Response contract**: **`graphResponse`** / root **`response`** — use **`graphResponsePatch`** only, never fold into **`graphEntryPatch`**.
+- **Concept alignment (FR-G3)**: When **`graphConcept.entityBindings`** exists, flag **`entityIds`** on inputs that disagree; align **`graphConceptPatch.expectedInput`** text with declared paths.
+
+### Findings
+Each finding **MUST** include **`scopeType`: `"graph"`** and **`category`** one of: `graph_entry`, `expected_input`, `job_models`, `job_knowledge`, `graph_execution`, `graph_conditions`. **`severity`**: `info` | `warning` | `error`.
+
+### Optional patches (partial only)
+- **`graphEntryPatch`** or **`suggestedGraphEntryPatch`** (same shape; prefer one)
+- **`modelConfigPatch`** with **`mode`**: `appendCase` | `replaceDefault`
+- **`jobPagentiKnowledgePatch`**: `{ refs: [{ catalogId, itemId }] }`
+- **`graphExecutionPatch`**: known keys only (`failFast`, `nodeTimeoutMs`, `mode`, `goalNodeId`, …)
+- **`graphResponsePatch`**: separate from graph entry
+- **`graphConceptPatch`**: Lane 1 only (`entityBindings`, `expectedInput`, …) — no `coreTasks` memoryIO
+
+### Output
+Single JSON object with **`action": "reviewGraphEntryContract"`**, **`verdict`** (`coherent`, `summary`), **`findings`** (array, may be empty), optional patches and **`requirementOptions`** when ambiguous example shapes exist.
+
+No markdown fences.

package/functions/graph-composer/prompts/action-suggest-graph-entry-conditions.md

@@ -0,0 +1,13 @@
+You propose **`metadata.graphEntry.conditions`** for **job-start gating** (graph-entry scope only).
+
+**You ONLY perform `action = "suggestGraphEntryConditions"` in this call.**
+
+### Rules
+- Do **not** copy task-node **`conditions`** wholesale; conditions here gate **starting the job**.
+- Preserve shape: **`narratives`**, **`dataFilters`**, **`aiCondition`** (same families as task Conditions).
+- When **`catalogGateId`** is used, reference valid catalog ids; explain in **`rationale`** which arm blocks job start.
+
+### Output
+JSON with **`action": "suggestGraphEntryConditions"`**, **`graphEntryPatch.conditions`**, optional **`rationale`**.
+
+No markdown fences.

package/functions/graph-composer/prompts/action-suggest-graph-entry-examples.md

@@ -0,0 +1,14 @@
+You propose **`metadata.graphEntry.exampleInputs[]`** for the job-start contract.
+
+**You ONLY perform `action = "suggestGraphEntryExamples"` in this call.**
+
+### Rules
+- Return **`graphEntryPatch.exampleInputs`**: array of `{ format, value }` where **`value`** is a string.
+- For **`format": "json"`**, **`value`** must be parseable JSON (object or array serialized as string).
+- Cover **required** input paths from **`graphEntry.inputs`** / **`agentContext.graphEntry`**.
+- When multiple plausible example shapes exist, add **`requirementOptions`** (ranked candidates) instead of guessing one.
+
+### Output
+JSON with **`action": "suggestGraphEntryExamples"`**, **`graphEntryPatch`**, optional **`requirementOptions`**, optional **`rationale`**.
+
+No markdown fences.

package/functions/graph-composer/prompts/action-suggest-graph-entry-inputs.md

@@ -0,0 +1,14 @@
+You propose **`metadata.graphEntry.inputs[]`** rows for the **job-start contract** (graph-entry scope).
+
+**You ONLY perform `action = "suggestGraphEntryInputs"` in this call.**
+
+### Rules
+- Return **`graphEntryPatch.inputs`** only (partial patch). No full graph.
+- Every **`path`** must start with **`execution.input.`** (e.g. `execution.input.raw`, `execution.input.scope`).
+- Use **`kind`**: `scalar` or `record`. Include **`required`** and optional **`entityIds`** when the graph is about xmemory entity collections.
+- When current inputs are empty, propose **at least one** row (typically `execution.input.raw` scalar or a `record` for structured scope).
+
+### Output
+JSON with **`action": "suggestGraphEntryInputs"`**, **`graphEntryPatch`**: `{ "inputs": [ ... ] }`, optional **`rationale`**.
+
+No markdown fences.

package/functions/graph-composer/prompts/action-suggest-graph-execution-defaults.md

@@ -0,0 +1,15 @@
+You propose **`metadata.graphExecution`** runtime defaults forwarded to execute requests.
+
+**You ONLY perform `action = "suggestGraphExecutionDefaults"` in this call.**
+
+### Allowed keys
+`failFast`, `nodeTimeoutMs`, `mode`, `goalNodeId`, `dimension`, `outputMode`, `coreObjective`, `nodesResponses`, `flowOutline`, `pipeline` — only keys you intend to change.
+
+### Rules
+- Flag incompatible combinations in **`rationale`** (e.g. backward **`mode`** without **`goalNodeId`**).
+- Partial patch only; studio deep-merges into existing **`graphExecution`**.
+
+### Output
+JSON with **`action": "suggestGraphExecutionDefaults"`**, **`graphExecutionPatch`**, optional **`rationale`**.
+
+No markdown fences.

package/functions/graph-composer/prompts/action-suggest-job-knowledge-refs.md

@@ -0,0 +1,12 @@
+You propose root **`jobPagentiKnowledge`** Catalox refs (Pagenti knowledge tab).
+
+**You ONLY perform `action = "suggestJobKnowledgeRefs"` in this call.**
+
+### Rules
+- Return **`jobPagentiKnowledgePatch.refs`** (or **`append`**) as `[{ "catalogId", "itemId" }]`.
+- Do **not** confuse with **`jobKnowledge`** string list or per-node **`taskPagentiKnowledge`**.
+
+### Output
+JSON with **`action": "suggestJobKnowledgeRefs"`**, **`jobPagentiKnowledgePatch`**, optional **`rationale`**.
+
+No markdown fences.

package/functions/graph-composer/prompts/action-suggest-job-model-defaults.md

@@ -0,0 +1,14 @@
+You propose **root** **`modelConfig`** job defaults (Start Job → Models tab).
+
+**You ONLY perform `action = "suggestJobModelDefaults"` in this call.**
+
+### Rules
+- Patch **graph root `modelConfig`** only unless the user explicitly names a **node id** (then explain in **`rationale`** that node overrides belong on **`nodes[].taskConfiguration.modelConfig`**).
+- Use **`@x12i/ai-profiles` profile names** (`cheap`, `balanced`, `deep`, …) in three slots: `preActionModel`, `skillModel`, `postActionModel`.
+- **`modelConfigPatch.mode`**: `appendCase` (default, additive) or `replaceDefault` when replacing the sole default case.
+- Do **not** drop existing **`cases`** without `replaceDefault` and explicit rationale.
+
+### Output
+JSON with **`action": "suggestJobModelDefaults"`**, **`modelConfigPatch`**, optional **`rationale`**.
+
+No markdown fences.

package/functions/graph-composer/prompts/shared/graph-entry-scope.md

@@ -0,0 +1,19 @@
+## Graph-entry agent scope (Start Job / Layer 01)
+
+When **`agentContext.surface`** is **`graph-entry`** (or **`virtualRole`** is graph-entry):
+
+- You are editing **job-start contract** and **graph-level defaults**, not a single task step.
+- Do **not** refer to “this step” or patch **`nodes[].taskConfiguration`** unless the user explicitly names a **node id** for comparison.
+- Do **not** return a full graph JSON. Return **partial patches** only (`graphEntryPatch`, `modelConfigPatch`, `jobPagentiKnowledgePatch`, `graphExecutionPatch`, `graphResponsePatch`, optional `graphConceptPatch` for Lane 1 alignment).
+- Do **not** put per-step execution memory in patches: never emit **`coreTasks[].requirements.memoryIO`** from graph-entry actions (that belongs on task-node / concept review).
+- Every graph-entry **input path** must use the **`execution.input.*`** prefix (caller / graph-entry bag), not `input.*` alone.
+
+**Lane alignment (when `graphConcept` is present):**
+
+| Lane | Patch target |
+|------|----------------|
+| Graph subject (entity collections) | `graphConceptPatch.entityBindings` and/or `graphEntry.inputs[].entityIds` |
+| Caller payload contract | `graphEntryPatch.inputs`, `exampleInputs`, `conditions` |
+| Per-step execution IO | **Out of scope** here — task nodes / `reviewConcept` |
+
+**`graphResponsePatch`** is separate from **`graphEntryPatch`**. Never move exit shape into `metadata.graphEntry`.

package/functions/graph-composer/prompts/shared/request-context.md

@@ -5,7 +5,8 @@
 - **`intent.focusNodeIds`**: When set on `modify` or `explain`, prioritize those nodes (and their edges); still keep the rest consistent or summarized as required by the action.
 - **`constraints`**: Honor `maxNodes`, `requireFinalizer`, `allowConditionalEdges`, and any `executionMemorySchema` hints from the request when building or changing graphs.
 - **`skillMode`**: Governs whether you may introduce new `skillKey` values (see the skill-mode section appended after the catalogs).
-- **`analysisContext`**: When present on `suggestConceptObjective`, treat it as **structured analysis** (execution order, per-node IO, issues, layers, etc.). Prefer it over re-deriving the same facts from scratch when it is consistent with `existingGraph`.
+- **`agentContext`**: When present (graphs-studio Agent View), includes **`surface`** (`graph-entry` | `task-node`) and effective contracts (`graphEntry`, `jobDefaults`, `graphResponse`, `graphExecution`, `graphConcept`, diagnostics). Required semantics for graph-entry actions — see **`shared/graph-entry-scope.md`**.
+- **`analysisContext`**: When present on `suggestConceptObjective`, treat it as **structured analysis** (execution order, per-node IO, issues, layers, etc.). Prefer it over re-deriving the same facts from scratch when it is consistent with `existingGraph`. Legacy hosts may duplicate graph-entry keys here with **`surface`: `graph-entry`**.
 - **`catalogCandidates`**: When present on `suggestCatalogResolution` / `suggestCatalogCreations`, extra managed-catalog rows from the host (e.g. **Catalox** via `loadCatalogCandidatesFromCatalox`): `aiSkills`, `utilitySkills`, `scopingMaps`, `narrixTemplates`. These extend the inline `aiSkills` / `utilitySkills` arrays for matching.
 - **`catalogMatchHints`**: When present, a server-injected object with optional `skills`, `scoping`, `narrix` entries from `matchLists` pre-pass. Treat as **non-authoritative hints**; reconcile with `existingGraph` and produce your own final recommendations.
 - **`suggestScopingNeedMatch`**: Requires non-empty **`catalogCandidates.scopingMaps`**. **`intent.description`** is the data need. **`existingGraph`** optional.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@exellix/graph-composer",
-  "version": "2.2.1",
+  "version": "2.4.2",
   "publishConfig": {
     "access": "public"
   },
-  "description": "LLM-backed worox-graph DAG composer: create, modify, explain, suggestConceptObjective, reviewConcept, catalog resolution/creation, scoping need match and scoping map creation plans, plus optional orchestrator — OpenRouter via @x12i/funcx; catalog rows from @x12i/catalox (loadCatalogCandidatesFromCatalox)",
+  "description": "LLM-backed worox-graph DAG composer: create, modify, explain, suggestConceptObjective, reviewConcept, graph-entry agent patches (reviewGraphEntryContract, suggestGraphEntry*), catalog resolution/creation, scoping need match and scoping map creation plans, plus optional orchestrator — OpenRouter via @x12i/funcx; catalog rows from @x12i/catalox (loadCatalogCandidatesFromCatalox)",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -36,7 +36,7 @@
     "verify:local": "tsx src/verify-local.ts",
     "verify:catalog-live": "x12i-env run --env-file .env -- tsx scripts/verify-catalog-live.ts",
     "test": "npm run test:unit && npm run test:live",
-    "test:unit": "node --import tsx/esm --test --test-force-exit test/unit/explain-shape.test.ts test/unit/graph-concept-patch.test.ts test/unit/graph-concept-story-parse.test.ts test/unit/review-concept-output-validation.test.ts test/unit/review-concept-catalog-alias.test.ts test/unit/redact-for-log.test.ts test/unit/graph-composer-logging.test.ts test/unit/worker-instructions.test.ts test/unit/catalog-output-validation.test.ts test/unit/catalox-catalog-bridge.test.ts test/unit/ai-task-profile.test.ts test/unit/create-modify-output-validation.test.ts test/unit/task-node-task-variable.test.ts test/unit/canonical-graph-document.test.ts test/unit/graph-engine-bridge.test.ts test/unit/graph-model-layers.test.ts test/unit/example-generation.test.ts",
+    "test:unit": "node --import tsx/esm --test --test-force-exit test/unit/explain-shape.test.ts test/unit/graph-concept-patch.test.ts test/unit/graph-concept-story-parse.test.ts test/unit/review-concept-output-validation.test.ts test/unit/review-concept-catalog-alias.test.ts test/unit/redact-for-log.test.ts test/unit/graph-composer-logging.test.ts test/unit/worker-instructions.test.ts test/unit/catalog-output-validation.test.ts test/unit/catalox-catalog-bridge.test.ts test/unit/ai-task-profile.test.ts test/unit/create-modify-output-validation.test.ts test/unit/task-node-task-variable.test.ts test/unit/canonical-graph-document.test.ts test/unit/graph-engine-bridge.test.ts test/unit/graph-model-layers.test.ts test/unit/example-generation.test.ts test/unit/graph-entry-schema.test.ts test/unit/graph-entry-patch-validation.test.ts test/unit/graph-entry-entity-alignment.test.ts test/unit/graph-entry-example-generation.test.ts test/unit/model-config-patch-merge.test.ts test/unit/graph-entry-registry.test.ts test/unit/graph-model-label-format.test.ts",
     "test:live": "x12i-env run --env-file .env -- node --import tsx/esm --test test/live/all.ts",
     "pack:check": "npm pack --dry-run",
     "suggest-smoke": "x12i-env run --env-file .env -- tsx scripts/run-suggest-concept-smoke.ts"
@@ -63,7 +63,7 @@
   },
   "homepage": "https://github.com/woroces/graph-composer#readme",
   "peerDependencies": {
-    "@exellix/graph-engine": "^7.4.1"
+    "@exellix/graph-engine": "^7.7.1"
   },
   "peerDependenciesMeta": {
     "@exellix/graph-engine": {
@@ -71,15 +71,16 @@
     }
   },
   "dependencies": {
-    "@x12i/ai-profiles": "^1.8.0",
+    "@x12i/ai-profiles": "^2.1.0",
     "@x12i/catalox": "^5.1.3",
     "@x12i/env": "^4.0.1",
-    "@x12i/funcx": "^4.3.0",
+    "@x12i/funcx": "^4.4.0",
     "@x12i/logxer": "^4.6.0"
   },
   "devDependencies": {
-    "@exellix/graph-engine": "^7.4.1",
+    "@exellix/graph-engine": "^7.7.1",
     "@types/node": "^22.10.2",
+    "@x12i/rendrix": "^4.3.0",
     "nx-config2": "^3.6.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2"