@burtson-labs/agent-core 1.6.43 → 1.6.45

package/dist/graph/index.d.ts

@@ -3,4 +3,6 @@ export * from './scheduler';
 export * from './loopNode';
 export * from './contracts';
 export * from './envelopes';
+export * from './planner';
+export * from './routing';
 //# sourceMappingURL=index.d.ts.map

package/dist/graph/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC"}

package/dist/graph/index.js

@@ -19,4 +19,6 @@ __exportStar(require("./scheduler"), exports);
 __exportStar(require("./loopNode"), exports);
 __exportStar(require("./contracts"), exports);
 __exportStar(require("./envelopes"), exports);
+__exportStar(require("./planner"), exports);
+__exportStar(require("./routing"), exports);
 //# sourceMappingURL=index.js.map

package/dist/graph/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,8CAA4B;AAC5B,6CAA2B;AAC3B,8CAA4B;AAC5B,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/graph/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,8CAA4B;AAC5B,6CAA2B;AAC3B,8CAA4B;AAC5B,8CAA4B;AAC5B,4CAA0B;AAC1B,4CAA0B"}

package/dist/graph/planner.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Phase 9 — the planner: let the MODEL propose a graph; the HOST owns
+ * everything that runs.
+ *
+ * Hard boundary, per the plan ("the planner never owns the scheduler"):
+ * a proposal is pure DATA — ids, dependencies, per-node prompts, and a
+ * read-only hint. The model cannot name tools, pick executors, set
+ * concurrency, or touch scheduling. The host validates the proposal
+ * (structure, caps, DAG-ness), maps hints to envelopes it controls, builds
+ * the executors itself, and runs the graph with ITS options. A malicious or
+ * confused proposal can therefore only produce a smaller/different DAG of
+ * host-controlled work — never wider capabilities.
+ *
+ * Classification contract: the model first decides HOW a task should run —
+ *   direct  one answer, no tools needed beyond a single turn
+ *   loop    one focused multi-step turn (today's tool loop)
+ *   graph   ≥2 separable chunks that benefit from explicit deps/parallelism
+ * "graph always wins" is exactly the assumption Phase 10's bench exists to
+ * test, so `direct`/`loop` are first-class outcomes, not failures.
+ */
+import { type GraphSpec, type NodeEnvelope, type NodeExecutor } from './types';
+export type ExecutionKind = 'direct' | 'loop' | 'graph';
+/** One node as the model proposes it. Deliberately narrow: no tool names, no
+ *  envelopes, no scheduler knobs — just work description + shape. */
+export interface ProposalNode {
+    id: string;
+    /** Self-contained instruction for this node's turn. */
+    prompt: string;
+    label?: string;
+    dependsOn?: string[];
+    /** Hint that this node only reads/inspects. The HOST decides what envelope
+     *  that maps to; in v1 hosts run ALL planned nodes read-only regardless. */
+    readOnly?: boolean;
+}
+export interface GraphProposal {
+    kind: ExecutionKind;
+    /** One sentence the UI can show for the classification. */
+    reason?: string;
+    /** Present iff kind === 'graph'. */
+    nodes?: ProposalNode[];
+}
+export interface PlannerLimits {
+    /** Cap on proposed nodes. Default 6 — enough to prove decomposition,
+     *  small enough that a runaway proposal can't fan out a fleet. */
+    maxNodes?: number;
+}
+/** The classification+proposal prompt. One completion, no tools. */
+export declare function buildPlannerPrompt(task: string, limits?: PlannerLimits): string;
+export interface ParsedProposal {
+    ok: boolean;
+    proposal?: GraphProposal;
+    errors: string[];
+}
+/**
+ * Parse + strictly validate a model response into a proposal. Never throws.
+ * Accepts a ```json fence or bare JSON amid prose (first balanced object).
+ */
+export declare function parseGraphProposal(text: string, limits?: PlannerLimits): ParsedProposal;
+export interface MaterializeOptions {
+    /** Host-built executor for one proposed node (typically wrapLoopAsNode over
+     *  the node's prompt). The proposal never supplies executors. */
+    makeExecutor: (node: ProposalNode) => NodeExecutor;
+    /** Host-owned envelope for one proposed node. The proposal's readOnly flag
+     *  is a HINT; the host decides the actual bounds and may ignore or tighten
+     *  it — it can never be loosened by the proposal. */
+    envelopeFor: (node: ProposalNode) => NodeEnvelope | undefined;
+}
+/** Turn a validated graph proposal into a runnable spec + executor map. */
+export declare function materializeProposal(proposal: GraphProposal, opts: MaterializeOptions): {
+    spec: GraphSpec;
+    executors: Record<string, NodeExecutor>;
+};
+//# sourceMappingURL=planner.d.ts.map

package/dist/graph/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/graph/planner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAqC,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAElH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD;qEACqE;AACrE,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;gFAC4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,aAAa,CAAC;IACpB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B;sEACkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,MAAM,CAuBnF;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,cAAc,CA8D3F;AA6BD,MAAM,WAAW,kBAAkB;IACjC;qEACiE;IACjE,YAAY,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAC;IACnD;;yDAEqD;IACrD,WAAW,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,GAAG,SAAS,CAAC;CAC/D;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,kBAAkB,GACvB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CAAE,CAgB9D"}

package/dist/graph/planner.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPlannerPrompt = buildPlannerPrompt;
+exports.parseGraphProposal = parseGraphProposal;
+exports.materializeProposal = materializeProposal;
+/**
+ * Phase 9 — the planner: let the MODEL propose a graph; the HOST owns
+ * everything that runs.
+ *
+ * Hard boundary, per the plan ("the planner never owns the scheduler"):
+ * a proposal is pure DATA — ids, dependencies, per-node prompts, and a
+ * read-only hint. The model cannot name tools, pick executors, set
+ * concurrency, or touch scheduling. The host validates the proposal
+ * (structure, caps, DAG-ness), maps hints to envelopes it controls, builds
+ * the executors itself, and runs the graph with ITS options. A malicious or
+ * confused proposal can therefore only produce a smaller/different DAG of
+ * host-controlled work — never wider capabilities.
+ *
+ * Classification contract: the model first decides HOW a task should run —
+ *   direct  one answer, no tools needed beyond a single turn
+ *   loop    one focused multi-step turn (today's tool loop)
+ *   graph   ≥2 separable chunks that benefit from explicit deps/parallelism
+ * "graph always wins" is exactly the assumption Phase 10's bench exists to
+ * test, so `direct`/`loop` are first-class outcomes, not failures.
+ */
+const types_1 = require("./types");
+const DEFAULT_MAX_NODES = 6;
+/** The classification+proposal prompt. One completion, no tools. */
+function buildPlannerPrompt(task, limits = {}) {
+    const maxNodes = limits.maxNodes ?? DEFAULT_MAX_NODES;
+    return [
+        'You are a planning classifier for a coding agent. Decide how the task below should run and answer with ONE JSON object in a ```json fence and nothing else.',
+        '',
+        'Choose "kind":',
+        '- "direct": answerable in one response without multi-step tool work.',
+        '- "loop": one focused multi-step turn (read/edit/verify in sequence) — the default for most coding tasks.',
+        `- "graph": ONLY when the task splits into 2-${maxNodes} separable chunks where explicit dependencies or parallelism genuinely help (e.g. survey several areas independently, then synthesize).`,
+        '',
+        'JSON shape:',
+        '{"kind":"direct"|"loop"|"graph","reason":"one sentence","nodes":[{"id":"kebab-case","label":"short","prompt":"self-contained instruction","dependsOn":["other-id"],"readOnly":true}]}',
+        '',
+        'Rules for "graph":',
+        `- 2 to ${maxNodes} nodes; ids kebab-case and unique; dependsOn only lists earlier-declared ids; no cycles.`,
+        '- Each node prompt must stand alone (its reader sees ONLY that prompt plus its dependencies\' results).',
+        '- End with a node that depends on the others and synthesizes the final answer.',
+        '- Mark nodes that only read/inspect with "readOnly": true.',
+        '- Omit "nodes" entirely for "direct" and "loop".',
+        '',
+        'Task:',
+        task.trim()
+    ].join('\n');
+}
+/**
+ * Parse + strictly validate a model response into a proposal. Never throws.
+ * Accepts a ```json fence or bare JSON amid prose (first balanced object).
+ */
+function parseGraphProposal(text, limits = {}) {
+    const maxNodes = limits.maxNodes ?? DEFAULT_MAX_NODES;
+    const raw = extractJsonObject(text);
+    if (!raw)
+        return { ok: false, errors: ['no JSON object found in the planner response'] };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, errors: ['planner response JSON does not parse'] };
+    }
+    const obj = parsed;
+    const errors = [];
+    if (obj.kind !== 'direct' && obj.kind !== 'loop' && obj.kind !== 'graph') {
+        errors.push(`kind must be direct|loop|graph (got ${JSON.stringify(obj.kind)})`);
+    }
+    let nodes;
+    if (obj.kind === 'graph') {
+        if (!Array.isArray(obj.nodes) || obj.nodes.length === 0) {
+            errors.push('graph proposals need a non-empty "nodes" array');
+        }
+        else if (obj.nodes.length > maxNodes) {
+            errors.push(`too many nodes: ${obj.nodes.length} (max ${maxNodes})`);
+        }
+        else {
+            nodes = [];
+            for (const [i, n] of obj.nodes.entries()) {
+                const node = n;
+                if (!node || typeof node.id !== 'string' || node.id.trim() === '') {
+                    errors.push(`node[${i}]: missing id`);
+                    continue;
+                }
+                if (typeof node.prompt !== 'string' || node.prompt.trim().length < 8) {
+                    errors.push(`node "${node.id}": missing or trivial prompt`);
+                    continue;
+                }
+                nodes.push({
+                    id: node.id.trim(),
+                    prompt: node.prompt.trim(),
+                    label: typeof node.label === 'string' ? node.label : undefined,
+                    dependsOn: Array.isArray(node.dependsOn) ? node.dependsOn.filter((d) => typeof d === 'string') : undefined,
+                    readOnly: node.readOnly === true,
+                });
+            }
+            if (errors.length === 0 && nodes.length > 0) {
+                // Structural validation via the same code the scheduler trusts.
+                const structural = (0, types_1.validateGraph)({ nodes: nodes.map(({ id, dependsOn }) => ({ id, dependsOn })) });
+                if (!structural.ok)
+                    errors.push(...structural.errors);
+            }
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors };
+    return {
+        ok: true,
+        errors: [],
+        proposal: {
+            kind: obj.kind,
+            reason: typeof obj.reason === 'string' ? obj.reason : undefined,
+            nodes,
+        },
+    };
+}
+/** First ```json fence, else the first balanced top-level {...}. */
+function extractJsonObject(text) {
+    const fence = /```(?:json)?\s*([\s\S]*?)```/.exec(text);
+    if (fence && fence[1].trim().startsWith('{'))
+        return fence[1].trim();
+    const start = text.indexOf('{');
+    if (start === -1)
+        return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === '{')
+            depth += 1;
+        else if (ch === '}') {
+            depth -= 1;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return null;
+}
+/** Turn a validated graph proposal into a runnable spec + executor map. */
+function materializeProposal(proposal, opts) {
+    if (proposal.kind !== 'graph' || !proposal.nodes || proposal.nodes.length === 0) {
+        throw new Error('materializeProposal: only graph proposals with nodes can be materialized');
+    }
+    const specNodes = proposal.nodes.map((n) => ({
+        id: n.id,
+        label: n.label ?? n.id,
+        dependsOn: n.dependsOn,
+        envelope: opts.envelopeFor(n),
+        // Every planned node must actually produce something — silence is the
+        // graph version of a claim without work.
+        contract: { outputNonEmpty: true },
+    }));
+    const executors = {};
+    for (const n of proposal.nodes)
+        executors[n.id] = opts.makeExecutor(n);
+    return { spec: { nodes: specNodes }, executors };
+}
+//# sourceMappingURL=planner.js.map

package/dist/graph/planner.js.map

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

package/dist/graph/routing.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Phase 10 — routing heuristics (the cheap pre-gate).
+ *
+ * Empirical routing (Phase 10 proper) needs the BanditBench baseline to say
+ * WHICH execution mode wins for WHICH task shape. But calling the planner
+ * model on every prompt just to hear "this is a plain loop" is wasteful — most
+ * prompts are obviously not graph-shaped. This module is the zero-inference
+ * pre-gate: a fast, explainable signal for whether a prompt is even worth
+ * asking the planner about.
+ *
+ * It NEVER decides execution — it only gates the (paid) planner call:
+ *   score low   → don't bother the planner; run the normal loop
+ *   score high  → the prompt smells decomposable; offer/consult the planner
+ *
+ * Deliberately conservative and transparent (returns its reasons) so a host
+ * can log why it routed, and so tuning it against the bench is inspectable
+ * rather than a black box. "graph rarely wins" is the null hypothesis the
+ * bench exists to test, so the bar to even SUGGEST a graph is high.
+ */
+export interface GraphShapeSignal {
+    /** 0..1 — how graph-shaped the prompt looks. */
+    score: number;
+    /** Human-readable contributors, for logging + tuning. */
+    reasons: string[];
+    /** Convenience: score >= the suggest threshold. */
+    suggestsGraph: boolean;
+}
+export interface GraphShapeOptions {
+    /** Score at/above which we'd consult the planner. Default 0.6 (high bar). */
+    suggestThreshold?: number;
+}
+/**
+ * Score how graph-shaped a prompt looks. Pure, fast, no model call.
+ */
+export declare function classifyGraphShaped(prompt: string, opts?: GraphShapeOptions): GraphShapeSignal;
+//# sourceMappingURL=routing.d.ts.map

package/dist/graph/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/graph/routing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mDAAmD;IACnD,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA+CD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,gBAAgB,CA0DlG"}

package/dist/graph/routing.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Phase 10 — routing heuristics (the cheap pre-gate).
+ *
+ * Empirical routing (Phase 10 proper) needs the BanditBench baseline to say
+ * WHICH execution mode wins for WHICH task shape. But calling the planner
+ * model on every prompt just to hear "this is a plain loop" is wasteful — most
+ * prompts are obviously not graph-shaped. This module is the zero-inference
+ * pre-gate: a fast, explainable signal for whether a prompt is even worth
+ * asking the planner about.
+ *
+ * It NEVER decides execution — it only gates the (paid) planner call:
+ *   score low   → don't bother the planner; run the normal loop
+ *   score high  → the prompt smells decomposable; offer/consult the planner
+ *
+ * Deliberately conservative and transparent (returns its reasons) so a host
+ * can log why it routed, and so tuning it against the bench is inspectable
+ * rather than a black box. "graph rarely wins" is the null hypothesis the
+ * bench exists to test, so the bar to even SUGGEST a graph is high.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyGraphShaped = classifyGraphShaped;
+// Phrases that signal INDEPENDENT sub-parts (the thing a graph is for).
+const MULTI_PART_MARKERS = [
+    /\bcompare\b[\s\S]*\b(?:and|vs\.?|versus|with|to|against)\b/i, // two-sided compare
+    /\bcontrast\b/i,
+    /\beach of\b/i,
+    /\bboth\b[\s\S]*\band\b/i,
+    /\bin parallel\b/i,
+    /\bseparately\b/i,
+    /\bindependently\b/i,
+    /\bacross (the |these |all )?\w+/i,
+    /\bfor (?:each|every)\b/i,
+    // Sequential fan-in: "…then/finally summarize/combine/merge the results".
+    /\b(?:then|afterwards|finally)\b[\s\S]*\b(?:summari[sz]|synthesi[sz]|combin|merg|compil)/i,
+];
+// Explicit enumeration: "A, B, and C" or "A and B" of comparable nouns.
+const AND_LIST = /\b\w[\w./-]*(?:,\s*\w[\w./-]*)+\s*,?\s*and\s+\w[\w./-]*/i;
+const SIMPLE_AND = /\band\b/i;
+// A synthesis verb paired with multiple sources is the classic fan-in shape.
+// "compar(e|ison)" counts here too — a comparison IS a synthesis over sources.
+const SYNTHESIS_MARKERS = [
+    /\bsummari[sz]e\b/i,
+    /\bsynthesi[sz]e\b/i,
+    /\bcombine\b/i,
+    /\breport\b/i,
+    /\boverview\b/i,
+    /\bcompar(?:e|ison|ing)\b/i,
+];
+// Strong single-step signals that argue AGAINST a graph regardless.
+const SINGLE_STEP_MARKERS = [
+    /\bfix (the |a )?typo\b/i,
+    /\brename\b/i,
+    /\bbump (the )?version\b/i,
+    /^\s*(what|where|when|who|why|how)\b.*\?\s*$/i, // a single question
+    /\badd (a |an )?(comment|line|import|field)\b/i,
+];
+/** Count distinct file-ish tokens (paths, dotted names) mentioned. */
+function fileMentions(text) {
+    const matches = text.match(/\b[\w-]+\/[\w./-]+|\b[\w-]+\.(ts|tsx|js|jsx|py|cs|go|rs|md|json|ya?ml|sh)\b/gi) ?? [];
+    return new Set(matches.map((m) => m.toLowerCase())).size;
+}
+/**
+ * Score how graph-shaped a prompt looks. Pure, fast, no model call.
+ */
+function classifyGraphShaped(prompt, opts = {}) {
+    const threshold = opts.suggestThreshold ?? 0.6;
+    const text = prompt.trim();
+    const reasons = [];
+    let score = 0;
+    // Very short prompts are almost never worth decomposing.
+    const words = text.split(/\s+/).filter(Boolean).length;
+    if (words < 8) {
+        return { score: 0, reasons: ['prompt too short to decompose'], suggestsGraph: false };
+    }
+    // Hard single-step signals cap the score low — a typo fix is a typo fix.
+    for (const re of SINGLE_STEP_MARKERS) {
+        if (re.test(text)) {
+            return { score: 0.1, reasons: [`single-step marker: ${re.source}`], suggestsGraph: false };
+        }
+    }
+    const multiPartHits = MULTI_PART_MARKERS.filter((re) => re.test(text));
+    if (multiPartHits.length > 0) {
+        score += 0.4;
+        reasons.push(`multi-part phrasing (${multiPartHits.length})`);
+    }
+    const files = fileMentions(text);
+    if (files >= 3) {
+        score += 0.3;
+        reasons.push(`${files} distinct files/paths mentioned`);
+    }
+    else if (files === 2) {
+        score += 0.15;
+        reasons.push('2 files/paths mentioned');
+    }
+    const hasSynthesis = SYNTHESIS_MARKERS.some((re) => re.test(text));
+    const hasList = AND_LIST.test(text);
+    if (hasSynthesis && (hasList || multiPartHits.length > 0 || files >= 2)) {
+        // Synthesis over multiple things = the fan-in a graph handles well.
+        score += 0.3;
+        reasons.push('synthesis over multiple sources');
+    }
+    else if (hasList) {
+        score += 0.15;
+        reasons.push('enumerated list of targets');
+    }
+    else if (SIMPLE_AND.test(text) && words >= 20) {
+        // A bare "and" in a long prompt is weak evidence at most.
+        score += 0.05;
+        reasons.push('conjunction in a long prompt');
+    }
+    // Long, dense prompts have more room for separable work.
+    if (words >= 40) {
+        score += 0.1;
+        reasons.push('long prompt');
+    }
+    score = Math.min(1, score);
+    if (reasons.length === 0)
+        reasons.push('no graph-shape signals');
+    return { score, reasons, suggestsGraph: score >= threshold };
+}
+//# sourceMappingURL=routing.js.map

package/dist/graph/routing.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burtson-labs/agent-core",
-  "version": "1.6.43",
+  "version": "1.6.45",
   "author": {
     "name": "Burtson Labs",
     "email": "team@burtson.ai",