@exellix/graph-composer 2.0.6 → 2.0.9

package/README.md

@@ -38,7 +38,7 @@ Requires **Node.js 20+** (Catalox embedder and this package align on `>=20`).
 | `OPENROUTER_API_KEY` | **Yes** (for API runs) | OpenRouter API key. |
 | `LLM_MODEL_STRONG` | No | Model slug when using `mode: "strong"` (default preset from @x12i/funcx). |
 | `LLM_MODEL_NORMAL` | No | Model slug for `normal` mode. |
-| `GRAPH_COMPOSER_LOGS_LEVEL` | No | Log level for [@x12i/logxer](https://www.npmjs.com/package/@x12i/logxer) (`info`, `warn`, …). |
+| `GRAPH_COMPOSER_LOGS_LEVEL` | No | Log level for [@x12i/logxer](https://www.npmjs.com/package/@x12i/logxer) (`debug`, `info`, `warn`, `off`, …). Overridable in code via `configureGraphComposerLogging` or per-call `logsLevel`. Uses diagnostic catalog `functions/graph-composer/metadata/log-diagnostics.json` (code `GRAPH_COMPOSER_WORKER_FAILED` on worker errors). |
 
 Copy [`.env.example`](./.env.example) to `.env` for local development. **Do not commit secrets.**
 
@@ -158,7 +158,30 @@ const result = await runGraphComposer(inputSuggestConceptObjectiveNetworkVulnSub
 
 **Requires** `existingGraph`. Returns **`verdict`** (`coherent`, `summary`) and **`findings`** (category, severity, summary, optional **`taskIndex`**, **`proposal`**, `nodeIds`, `suggestedChange`). When **`metadata.graphConcept.coreTasks`** is non-empty, the model should return **`graphConceptPatch`** or **`suggestedConceptPatch`** (same partial shape; prefer one) with **`coreTasks`** index-aligned to that array and partial **`requirements`** (`skill`, `catalogBinding`, `narrix`, `memoryIO`, optional **`webScoping`**, etc.) inferred from the graph and catalogs. When a single value cannot be chosen, the model may return **`requirementOptions`** (ranked **`candidates`** per `taskIndex` + dot-path **`field`**, plus **`needsNewArtifact`**). Optional extended string fields on the patch (e.g. `expectedInput`, `outputDescription`) and optional **`catalogProposals`** for catalog gaps. No `graph`, `changelog`, or `explanation`. Use for design review before heavy edits.
 
-**Tracing:** For `reviewConcept` only, `runGraphWorker` logs a **redacted** JSON snapshot of the serialized worker request and the **raw LLM worker response** (@x12i/funcx function-pack invocation): at **`debug`** by default (set `GRAPH_COMPOSER_LOGS_LEVEL=debug`), or at **`info`** when **`traceReviewConceptIo: true`** is passed in `RunGraphComposerOptions`. Payloads are capped (~500k chars) and keys matching secrets (`apiKey`, `password`, `token`, etc.) are replaced with `[redacted]`.
+**Tracing:** For `reviewConcept` only, `runGraphWorker` logs a **redacted** JSON snapshot of the serialized worker request and the **raw LLM worker response** (@x12i/funcx function-pack invocation): at **`debug`** by default (`logsLevel: "debug"` or `GRAPH_COMPOSER_LOGS_LEVEL=debug`), or at **`info`** when **`traceReviewConceptIo: true`** is passed in `RunGraphComposerOptions`. Payloads are capped (~500k chars) and keys matching secrets (`apiKey`, `password`, `token`, etc.) are replaced with `[redacted]`. Pass **`logContext`** (`jobId`, `runId`, `graphId`, …) in `RunGraphComposerOptions` so all logs correlate in Mongo/query APIs via logxer `runWithLogContext`.
+
+### Logging from downstream hosts
+
+Set the threshold once at process startup, per request, or via env:
+
+```ts
+import {
+  configureGraphComposerLogging,
+  getGraphComposerLoggingConfig,
+  runGraphComposer,
+} from "@x12i/graph-composer";
+
+// Process-wide (e.g. after reading your service config)
+configureGraphComposerLogging({ logsLevel: "info" });
+
+// Per invocation — wins over configure + env for that call only
+await runGraphComposer(input, { logsLevel: "debug", logContext: { jobId: "j-1" } });
+
+// Inspect effective level (after overrides)
+const { logsLevel, debugEnabled, envKeys } = getGraphComposerLoggingConfig();
+```
+
+Precedence per worker run: **`options.logsLevel`** → **`configureGraphComposerLogging`** → **`GRAPH_COMPOSER_LOGS_LEVEL`** (or legacy `GRAPH_COMPOSER_LOG_LEVEL`) → default **`warn`**. Use **`off`** / **`none`** / **`silent`** to silence graph-composer logs. **`getGraphComposerLogger()`** returns the shared logxer instance if you need `getJobLogs` / `scopeLogs` from the same sink.
 
 ### Generate example input
 
@@ -195,6 +218,8 @@ Both **require** `existingGraph`. Pass **`catalogCandidates`** (from **Catalox**
 In addition to `client`, `mode`, `model`, `temperature`, `maxTokens`, `askTimeoutMs`, `connectTimeoutMs`:
 
 - **`catalogMatchListsAssist`** — When not `false`, enables **`matchLists`** pre-passes for `suggestCatalogResolution`, `suggestCatalogCreations`, and **`suggestScopingNeedMatch`** when a client is resolved (skips if no client).
+- **`logsLevel`** — Per-call log threshold (`debug`, `info`, `off`, …). Overrides `configureGraphComposerLogging` and env for that run.
+- **`logContext`** — Correlation ids (`jobId`, `runId`, `graphId`, …) on every log line via logxer `runWithLogContext`.
 - **`traceReviewConceptIo`** — When `true`, emit **`reviewConcept`** request/response trace logs at **`info`** (still redacted). When `false` (default), the same traces use **`debug`** only.
 
 ### Worker actions cheat sheet

package/dist/graphComposerLogging.d.ts

@@ -0,0 +1,45 @@
+import { type LogLevel, type Logxer } from "@x12i/logxer";
+/** Canonical env prefix for graph-composer logs (`GRAPH_COMPOSER_LOGS_LEVEL`, …). */
+export declare const GRAPH_COMPOSER_LOG_ENV_PREFIX = "GRAPH_COMPOSER";
+export type { LogLevel };
+/** Accepted inputs for `configureGraphComposerLogging` and `RunGraphComposerOptions.logsLevel`. */
+export type GraphComposerLogsLevelInput = LogLevel | "off" | "none" | "silent" | (string & {});
+export type GraphComposerLoggingConfig = {
+    /** Effective threshold after overrides (`off` when logging is disabled). */
+    logsLevel: LogLevel | "off";
+    /** True when package logging is silenced (`off` / `none` / `silent`). */
+    logsDisabled: boolean;
+    /** Whether `debug` (and `verbose`) lines are emitted. */
+    debugEnabled: boolean;
+    envKeys: {
+        canonical: string;
+        legacy: string;
+    };
+};
+/**
+ * Parse a log-level string (case-insensitive). Unknown values disable logging (`off`).
+ * Accepts logxer synonyms: `off`, `none`, `silent`.
+ */
+export declare function parseGraphComposerLogsLevel(raw: string | undefined): {
+    logsLevel: LogLevel | "off";
+    logsDisabled: boolean;
+};
+/**
+ * Process-wide logging for graph-composer (downstream hosts, servers, CLIs).
+ *
+ * Precedence for each `runGraphComposer` / `runGraphComposerAgent` call:
+ * `options.logsLevel` → `configureGraphComposerLogging` → `GRAPH_COMPOSER_LOGS_LEVEL` env → default `warn`.
+ */
+export declare function configureGraphComposerLogging(options: {
+    logsLevel?: GraphComposerLogsLevelInput;
+}): void;
+/** Current effective logging configuration (after env + programmatic overrides). */
+export declare function getGraphComposerLoggingConfig(perCall?: GraphComposerLogsLevelInput): GraphComposerLoggingConfig;
+/** Shared @x12i/logxer instance for graph-composer (diagnostics catalog attached). */
+export declare function getGraphComposerLogger(): Logxer;
+/**
+ * Run `fn` with a temporary log threshold (`options.logsLevel` on workers).
+ * Restores the previous threshold when `fn` completes.
+ */
+export declare function withGraphComposerLogsLevel<T>(logsLevel: GraphComposerLogsLevelInput | undefined, fn: () => T | Promise<T>): Promise<T>;
+//# sourceMappingURL=graphComposerLogging.d.ts.map

package/dist/graphComposerLogging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphComposerLogging.d.ts","sourceRoot":"","sources":["../src/graphComposerLogging.ts"],"names":[],"mappings":"AAEA,OAAO,EAML,KAAK,QAAQ,EACb,KAAK,MAAM,EACZ,MAAM,cAAc,CAAC;AAGtB,qFAAqF;AACrF,eAAO,MAAM,6BAA6B,mBAAmB,CAAC;AAE9D,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB,mGAAmG;AACnG,MAAM,MAAM,2BAA2B,GACnC,QAAQ,GACR,KAAK,GACL,MAAM,GACN,QAAQ,GACR,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAElB,MAAM,MAAM,0BAA0B,GAAG;IACvC,4EAA4E;IAC5E,SAAS,EAAE,QAAQ,GAAG,KAAK,CAAC;IAC5B,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAC;IACtB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAAC;AA+DF;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB;IAAE,SAAS,EAAE,QAAQ,GAAG,KAAK,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAMxD;AAoCD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE;IACrD,SAAS,CAAC,EAAE,2BAA2B,CAAC;CACzC,GAAG,IAAI,CAMP;AAED,oFAAoF;AACpF,wBAAgB,6BAA6B,CAC3C,OAAO,CAAC,EAAE,2BAA2B,GACpC,0BAA0B,CAY5B;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAAC,CAAC,EAChD,SAAS,EAAE,2BAA2B,GAAG,SAAS,EAClD,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAYZ"}

package/dist/graphComposerLogging.js

@@ -0,0 +1,132 @@
+import path from "node:path";
+import { initConfig } from "@x12i/env";
+import { createLogxer, legacyPackageLogLevelEnvKey, packageLogsLevelEnvKey, parsePackageLogsLevelString, resolvePackageLogsLevel, } from "@x12i/logxer";
+import { graphComposerPackRoot } from "./packDir.js";
+/** Canonical env prefix for graph-composer logs (`GRAPH_COMPOSER_LOGS_LEVEL`, …). */
+export const GRAPH_COMPOSER_LOG_ENV_PREFIX = "GRAPH_COMPOSER";
+// Load .env before Logxer reads MONGO_URI (and related vars) at construction.
+initConfig({}, { dotenvPath: ".env", throwOnMissing: false });
+const logger = createLogxer({
+    packageName: "graph-composer",
+    envPrefix: GRAPH_COMPOSER_LOG_ENV_PREFIX,
+}, {
+    diagnostics: {
+        catalogPath: path.join(graphComposerPackRoot(), "metadata", "log-diagnostics.json"),
+    },
+});
+let processWideLogsLevel;
+function logxerMutableConfig(logxer) {
+    return logxer.config;
+}
+function applyResolvedToLogger(resolved) {
+    const internal = logxerMutableConfig(logger);
+    const prev = {
+        logLevel: internal.logLevel,
+        packageLogsDisabled: internal.packageLogsDisabled,
+    };
+    internal.logLevel = resolved.logLevel;
+    internal.packageLogsDisabled = resolved.packageLogsDisabled;
+    return () => {
+        internal.logLevel = prev.logLevel;
+        internal.packageLogsDisabled = prev.packageLogsDisabled;
+    };
+}
+const LOG_LEVELS = new Set([
+    "verbose",
+    "debug",
+    "info",
+    "warn",
+    "error",
+]);
+function isLogLevel(value) {
+    return LOG_LEVELS.has(value);
+}
+/**
+ * Parse a log-level string (case-insensitive). Unknown values disable logging (`off`).
+ * Accepts logxer synonyms: `off`, `none`, `silent`.
+ */
+export function parseGraphComposerLogsLevel(raw) {
+    const parsed = parsePackageLogsLevelString(raw);
+    if (parsed.packageLogsDisabled || parsed.logLevel === undefined) {
+        return { logsLevel: "off", logsDisabled: true };
+    }
+    return { logsLevel: parsed.logLevel, logsDisabled: false };
+}
+function resolveFromInput(input) {
+    if (input === "off" || input === "none" || input === "silent") {
+        return { packageLogsDisabled: true, logLevel: "error" };
+    }
+    if (typeof input === "string" && isLogLevel(input)) {
+        return { packageLogsDisabled: false, logLevel: input };
+    }
+    const parsed = parsePackageLogsLevelString(String(input));
+    if (parsed.packageLogsDisabled || parsed.logLevel === undefined) {
+        return { packageLogsDisabled: true, logLevel: "error" };
+    }
+    return { packageLogsDisabled: false, logLevel: parsed.logLevel };
+}
+function resolveGraphComposerLogsLevel(perCall) {
+    if (perCall !== undefined) {
+        return resolveFromInput(perCall);
+    }
+    if (processWideLogsLevel !== undefined) {
+        return resolveFromInput(processWideLogsLevel);
+    }
+    return resolvePackageLogsLevel({
+        envPrefix: GRAPH_COMPOSER_LOG_ENV_PREFIX,
+    });
+}
+function syncLoggerToEffectiveLevel(perCall) {
+    applyResolvedToLogger(resolveGraphComposerLogsLevel(perCall));
+}
+/**
+ * Process-wide logging for graph-composer (downstream hosts, servers, CLIs).
+ *
+ * Precedence for each `runGraphComposer` / `runGraphComposerAgent` call:
+ * `options.logsLevel` → `configureGraphComposerLogging` → `GRAPH_COMPOSER_LOGS_LEVEL` env → default `warn`.
+ */
+export function configureGraphComposerLogging(options) {
+    if (options.logsLevel === undefined) {
+        return;
+    }
+    processWideLogsLevel = options.logsLevel;
+    syncLoggerToEffectiveLevel();
+}
+/** Current effective logging configuration (after env + programmatic overrides). */
+export function getGraphComposerLoggingConfig(perCall) {
+    const resolved = resolveGraphComposerLogsLevel(perCall);
+    const logsDisabled = resolved.packageLogsDisabled;
+    return {
+        logsLevel: logsDisabled ? "off" : resolved.logLevel,
+        logsDisabled,
+        debugEnabled: !logsDisabled && logger.isLevelEnabled("debug"),
+        envKeys: {
+            canonical: packageLogsLevelEnvKey(GRAPH_COMPOSER_LOG_ENV_PREFIX),
+            legacy: legacyPackageLogLevelEnvKey(GRAPH_COMPOSER_LOG_ENV_PREFIX),
+        },
+    };
+}
+/** Shared @x12i/logxer instance for graph-composer (diagnostics catalog attached). */
+export function getGraphComposerLogger() {
+    return logger;
+}
+/**
+ * Run `fn` with a temporary log threshold (`options.logsLevel` on workers).
+ * Restores the previous threshold when `fn` completes.
+ */
+export async function withGraphComposerLogsLevel(logsLevel, fn) {
+    if (logsLevel === undefined) {
+        syncLoggerToEffectiveLevel();
+        return fn();
+    }
+    const restore = applyResolvedToLogger(resolveGraphComposerLogsLevel(logsLevel));
+    try {
+        return await fn();
+    }
+    finally {
+        restore();
+        syncLoggerToEffectiveLevel();
+    }
+}
+// Apply env / default level at module load (before first log line).
+syncLoggerToEffectiveLevel();

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { GRAPH_COMPOSER_ACTION_REGISTRY, getActionDefinition, getActionDefinitio
 export { graphComposerPackRoot, readGraphComposerPromptFile, } from "./packDir.js";
 export { DEFAULT_UTILITY_SKILLS } from "./defaultUtilitySkills.js";
 export { runGraphComposer, runGraphWorker, resolveGraphComposerClient, getGraphComposerLlmClient, getPackDir, normalizeGraphComposerExplainOutput, normalizeReviewConceptComposerOutput, redactSecretsForLog, type RunGraphComposerOptions, } from "./runGraphComposer.js";
+export type { LogRuntimeContext, LogLevel } from "@x12i/logxer";
+export { GRAPH_COMPOSER_LOG_ENV_PREFIX, configureGraphComposerLogging, getGraphComposerLogger, getGraphComposerLoggingConfig, parseGraphComposerLogsLevel, withGraphComposerLogsLevel, type GraphComposerLoggingConfig, type GraphComposerLogsLevelInput, } from "./graphComposerLogging.js";
 export { applyGraphConceptPatchOnlyIfEmpty } from "./graphConceptPatchMerge.js";
 export { runGraphComposerAgent, type GraphComposerAgentResult, type GraphComposerAgentOrchestrationStep, type RunGraphComposerAgentOptions, } from "./graphComposerAgent.js";
 export type { GraphComposerInput, GraphComposerAgentInput, GraphComposerIntent, GraphComposerConstraints, SkillDescriptor, PrimaryIntentType, GraphConceptStatus, GraphConceptEntityBindings, GraphConceptPatch, GraphConceptPatchKey, GraphConceptRequirementsPatch, GraphConceptCoreTaskPatchItem, RequirementOptionCandidate, RequirementOptionEntry, CatalogCandidates, ScopingMapCandidate, NarrixTemplateCandidate, } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -3,6 +3,7 @@ export { GRAPH_COMPOSER_ACTION_REGISTRY, getActionDefinition, getActionDefinitio
 export { graphComposerPackRoot, readGraphComposerPromptFile, } from "./packDir.js";
 export { DEFAULT_UTILITY_SKILLS } from "./defaultUtilitySkills.js";
 export { runGraphComposer, runGraphWorker, resolveGraphComposerClient, getGraphComposerLlmClient, getPackDir, normalizeGraphComposerExplainOutput, normalizeReviewConceptComposerOutput, redactSecretsForLog, } from "./runGraphComposer.js";
+export { GRAPH_COMPOSER_LOG_ENV_PREFIX, configureGraphComposerLogging, getGraphComposerLogger, getGraphComposerLoggingConfig, parseGraphComposerLogsLevel, withGraphComposerLogsLevel, } from "./graphComposerLogging.js";
 export { applyGraphConceptPatchOnlyIfEmpty } from "./graphConceptPatchMerge.js";
 export { runGraphComposerAgent, } from "./graphComposerAgent.js";
 export { buildCatalogMatchHints, } from "./catalogMatchAssist.js";

package/dist/runGraphComposer.d.ts

@@ -1,3 +1,5 @@
+import { type LogRuntimeContext } from "@x12i/logxer";
+import { type GraphComposerLogsLevelInput } from "./graphComposerLogging.js";
 import type { Client } from "@x12i/funcx";
 import { type LlmMode } from "@x12i/funcx/functions";
 import type { GraphComposerInput } from "./types.js";
@@ -34,9 +36,19 @@ export type RunGraphComposerOptions = {
     maxTokens?: number;
     /**
      * When true, `reviewConcept` logs redacted serialized request and raw LLM result at `info`.
-     * When false (default), the same traces use `debug` (enable via `GRAPH_COMPOSER_LOGS_LEVEL=debug`).
+     * When false (default), the same traces use `debug` (enable via `logsLevel: "debug"` or env).
      */
     traceReviewConceptIo?: boolean;
+    /**
+     * Per-call log threshold. Wins over `configureGraphComposerLogging` and env for this run only.
+     * Use `off` / `none` / `silent` to silence graph-composer logs for one invocation.
+     */
+    logsLevel?: GraphComposerLogsLevelInput;
+    /**
+     * Optional correlation ids merged into every log via @x12i/logxer `runWithLogContext`
+     * (jobId, runId, graphId, nodeId, taskId, sessionId, correlationId).
+     */
+    logContext?: LogRuntimeContext;
 };
 export declare function resolveGraphComposerClient(options: RunGraphComposerOptions): Client | undefined;
 /**
@@ -44,10 +56,6 @@ export declare function resolveGraphComposerClient(options: RunGraphComposerOpti
  * Unlike `resolveGraphComposerClient`, this always returns a `Client` when OpenRouter is configured.
  */
 export declare function getGraphComposerLlmClient(options?: RunGraphComposerOptions): Client;
-/**
- * Run a single graph-composer worker (`intent.action`) with the per-action system prompt.
- * Shared by `runGraphComposer` and `runGraphComposerAgent`.
- */
 export declare function runGraphWorker(input: GraphComposerInput, options?: RunGraphComposerOptions): Promise<unknown>;
 export declare function runGraphComposer(input: GraphComposerInput, options?: RunGraphComposerOptions): Promise<unknown>;
 export declare function getPackDir(): string;

package/dist/runGraphComposer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runGraphComposer.d.ts","sourceRoot":"","sources":["../src/runGraphComposer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,uBAAuB,CAAC;AAc/B,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAC;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAC/B,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAsHhF;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,IAAI,CASN;AAuDD;;GAEG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,OAAO,GACd,OAAO,CAKT;AA0ED,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC,CAAC;AAgDF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,GAAG,SAAS,CA4BpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAYR;AAMD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAkJlB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC"}
+{"version":3,"file":"runGraphComposer.d.ts","sourceRoot":"","sources":["../src/runGraphComposer.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAIL,KAAK,OAAO,EACb,MAAM,uBAAuB,CAAC;AAc/B,OAAO,KAAK,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAC;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGxD,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAC/B,OAAO,EAAE,iCAAiC,EAAE,MAAM,6BAA6B,CAAC;AAgHhF;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3B,IAAI,CASN;AAuDD;;GAEG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,OAAO,GACd,OAAO,CAKT;AA0ED,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,2FAA2F;IAC3F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,2BAA2B,CAAC;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC,CAAC;AAmDF,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,uBAAuB,GAC/B,MAAM,GAAG,SAAS,CA4BpB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAYR;AAqLD,wBAAsB,cAAc,CAClC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAQlB;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC"}

package/dist/runGraphComposer.js

@@ -1,7 +1,7 @@
 import { readFileSync, existsSync } from "node:fs";
 import path from "node:path";
-import { initConfig } from "@x12i/env";
-import { createLogxer } from "@x12i/logxer";
+import { DebugLogAbstract, exceptionEvidence, fieldEvidence, runWithLogContext, } from "@x12i/logxer";
+import { getGraphComposerLogger, withGraphComposerLogsLevel, } from "./graphComposerLogging.js";
 import { createClient } from "@x12i/funcx";
 import { buildRequestPrompt, executeFuncx as invokeFuncxPack, } from "@x12i/funcx/functions";
 import { composeWorkerInstructions } from "./composeInstructions.js";
@@ -33,12 +33,7 @@ function processSuggestConceptObjectiveOutput(shaped, intent, existingGraph) {
             typeof r === "string" && r.trim().length > 0 ? `${prefix} ${r}` : prefix;
     }
 }
-// Load .env into process.env before Logxer reads MONGO_URI (and related vars) at construction.
-initConfig({}, { dotenvPath: ".env", throwOnMissing: false });
-const logger = createLogxer({
-    packageName: "graph-composer",
-    envPrefix: "GRAPH_COMPOSER",
-});
+const logger = getGraphComposerLogger();
 let cachedRules = null;
 function loadRules() {
     if (cachedRules !== null)
@@ -253,6 +248,9 @@ function logReviewConceptIo(phase, data, traceReviewConceptIo) {
     const payload = safeJsonStringifyForLog(redacted);
     const msg = `graph-composer reviewConcept ${phase}`;
     const meta = {
+        phase,
+        debugKind: DebugLogAbstract.STATE,
+        evidence: [fieldEvidence("payloadCharLength", payload.length)],
         payloadCharLength: payload.length,
         payload,
     };
@@ -324,7 +322,7 @@ function buildGraphComposerPrompt(request) {
  * Run a single graph-composer worker (`intent.action`) with the per-action system prompt.
  * Shared by `runGraphComposer` and `runGraphComposerAgent`.
  */
-export async function runGraphWorker(input, options = {}) {
+async function runGraphWorkerInner(input, options) {
     assertInputShape(input);
     const normalized = normalizeInput(input);
     const action = normalized.intent.action;
@@ -391,6 +389,7 @@ export async function runGraphWorker(input, options = {}) {
         aiSkillCount: normalized.aiSkills.length,
         utilitySkillCount: normalized.utilitySkills.length,
         composedInstructionChars: system.length,
+        debugKind: DebugLogAbstract.EVENT,
     });
     const mode = options.mode ?? "strong";
     try {
@@ -425,17 +424,43 @@ export async function runGraphWorker(input, options = {}) {
                 });
             }
         }
-        logger.info("graph-composer worker complete", { action });
+        logger.info("graph-composer worker complete", {
+            action,
+            debugKind: DebugLogAbstract.EVENT,
+        });
         return shaped;
     }
     catch (e) {
-        logger.error("graph-composer worker failed", {
+        const message = e instanceof Error ? e.message : String(e);
+        logger.errorCode("GRAPH_COMPOSER_WORKER_FAILED", {
             action,
-            message: e instanceof Error ? e.message : String(e),
+            error: e,
+            debugKind: DebugLogAbstract.ANOMALY,
+            evidence: [
+                exceptionEvidence(e),
+                fieldEvidence("intent.action", action),
+            ],
+            diagnostics: {
+                expected: "The graph-composer worker should complete and return validated output.",
+                actual: message,
+                impact: "The requested graph-composer action did not complete; callers receive no result.",
+                retryable: true,
+                userActionRequired: false,
+                confidence: "medium",
+            },
         });
         throw e;
     }
 }
+export async function runGraphWorker(input, options = {}) {
+    return withGraphComposerLogsLevel(options.logsLevel, async () => {
+        const ctx = options.logContext;
+        if (ctx !== undefined && Object.keys(ctx).length > 0) {
+            return runWithLogContext(ctx, () => runGraphWorkerInner(input, options));
+        }
+        return runGraphWorkerInner(input, options);
+    });
+}
 export async function runGraphComposer(input, options = {}) {
     return runGraphWorker(input, options);
 }

package/functions/graph-composer/metadata/log-diagnostics.json

@@ -0,0 +1,20 @@
+{
+  "GRAPH_COMPOSER_WORKER_FAILED": {
+    "defaultLevel": "error",
+    "title": "Graph composer worker failed",
+    "impact": "The requested graph-composer action did not complete; callers receive no result.",
+    "possibleCauses": [
+      "OpenRouter or @x12i/funcx returned an error or timed out.",
+      "Model output failed action-specific validation.",
+      "Missing or invalid input (existingGraph, catalogCandidates, etc.)."
+    ],
+    "remediation": [
+      "Set GRAPH_COMPOSER_LOGS_LEVEL=debug (or traceReviewConceptIo for reviewConcept).",
+      "Inspect the exception message and validation errors in logs.",
+      "Verify OPENROUTER_API_KEY and LLM model slugs."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-composer",
-  "version": "2.0.6",
+  "version": "2.0.9",
   "publishConfig": {
     "access": "public"
   },
@@ -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/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/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/example-generation.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"
@@ -71,11 +71,11 @@
     }
   },
   "dependencies": {
-    "@x12i/ai-profiles": "^1.2.3",
+    "@x12i/ai-profiles": "^1.2.9",
     "@x12i/catalox": "^5.1.1",
     "@x12i/env": "^4.0.1",
-    "@x12i/funcx": "^4.2.0",
-    "@x12i/logxer": "^4.3.5"
+    "@x12i/funcx": "^4.2.3",
+    "@x12i/logxer": "^4.4.2"
   },
   "devDependencies": {
     "@exellix/graph-engine": "^7.2.0",