@polycode-projects/the-mechanical-code-talker 1.9.1 → 1.10.0

package/src/router/drive.mjs

@@ -0,0 +1,183 @@
+// src/router/drive.mjs — the product-facing drive of the capability router: the
+// piece that turns a real English request into a real, executed answer over a
+// real repo graph. registry/resolver/planner/guardrail/goal-reasoner/
+// call-validator are all pure, deterministic decision machinery — this module
+// is the thin, stateful shell around them that a CLI or chat surface calls:
+// build a { dispatch, resolve, graph } context against the repo's actual code
+// graph, then run a request through resolver -> planner -> goal-reasoner.
+//
+// Single-shot -> the resolver. A compound "... then ..."/"if ..."/"of the ...,
+// which are ..." request -> the planner, HTN-decomposed into an ordered call
+// sequence with a POP causal-link proof chain, then folded into ONE composed
+// answer via the same set-algebra the HTN method names (relative-filter ->
+// intersect; conditional -> fallback/guard). A request neither stage can
+// ground escalates to the closed-world goal-reasoner — a maintenance-invariant
+// deduction (coverage-gap / cochange-risk), never a keyword guess. Anything
+// none of the three grounds is an honest refuse, the same "grounded or an
+// honest miss" contract as every other tmct answer path.
+
+import { resolveOne } from "./resolver.mjs";
+import { plan, isMultiStep, decompose, MAX_STEPS } from "./planner.mjs";
+import { goalReason } from "./goal-reasoner.mjs";
+import { capabilities } from "./registry.mjs";
+import { intersect, fallbackIfEmpty, guardIfEmpty, memberIndividuals, membersReaching, resultSetOf } from "./results.mjs";
+import { resolveObject } from "../ask.mjs";
+import { parseEntities } from "../codegraph.mjs";
+import { dispatchTool } from "../server.mjs";
+import { ToolError } from "../config.mjs";
+import * as defaultSource from "../source.mjs";
+
+export const ROUTER_DRIVER = "resolver-0.8.0";
+export const GOAL_DRIVER = "goal-0.8.1";
+
+/** Every registered capability's name — the default declared toolset for a
+ *  caller that doesn't want to hand-pick a subset. */
+export function declaredCapabilityNames() {
+  return capabilities().map((c) => c.name);
+}
+
+const CALLABLE_MEMBER_CLASSES = new Set(["Method", "Function"]);
+const refuse = (why, driver) => ({ calls: [], refused: true, terminated: true, proof: [], driver, why });
+
+/** Execute the MEMBER-FILTER HTN method ("which methods of X end up calling Y")
+ *  — the per-member hop the single-shot resolver cannot emit on its own. Step 1
+ *  grounds members(X) via resolveOne; then, per CALLABLE member (sorted, bounded
+ *  by the planner's MAX_STEPS budget), one tmct_callees hop. The fold is
+ *  membersReaching (the bounded transitive callsSymbol closure), computed over
+ *  the graph, never parsed from text. Honest refuses: no tmct_callees in the
+ *  declared toolset, an unbindable filter target, an over-budget member list. */
+async function memberFilterDrive(request, tools, ctx, segments) {
+  const [setSeg, filterSeg] = segments;
+  if (!tools.includes("tmct_callees")) {
+    return refuse("the member-filter reachability hop needs tmct_callees, which is not in the declared toolset — refusing the hop rather than guessing the fold", ROUTER_DRIVER);
+  }
+  const t = ctx.resolve ? ctx.resolve(String(filterSeg.text)) : null;
+  if (!t || !t.match || t.ambiguous) {
+    return refuse(`the member-filter target "${filterSeg.text}" does not bind to one graph entity (honest miss)`, ROUTER_DRIVER);
+  }
+  const target = t.match;
+
+  const r1 = await resolveOne(setSeg.text, tools, ctx, { execute: true });
+  if (r1.refused) return refuse(`sub-goal 1 ("${setSeg.text}") did not resolve: ${r1.reason}`, ROUTER_DRIVER);
+  const classInd = r1.resolved;
+  if (!classInd) return refuse(`sub-goal 1 ("${setSeg.text}") grounded no class entity to enumerate`, ROUTER_DRIVER);
+
+  const calls = [r1.selected];
+  const proof = [{ step: "causal-link", producer: "graph", condition: classInd.label, consumer: `step-1:${r1.selected.name}`, role: "action", ok: true }];
+  for (const s of r1.proof) proof.push({ ...s, ofStep: 1 });
+  const why = [
+    `HTN method: member-filter — enumerate members(${classInd.label}), hop tmct_callees per callable member, fold by bounded transitive reach of ${target.label}`,
+    ...(r1.why || []).map((w) => `[1] ${w}`),
+  ];
+
+  const members = memberIndividuals(ctx.graph, classInd)
+    .filter((m) => CALLABLE_MEMBER_CLASSES.has(m.class))
+    .sort((a, b) => String(a.label).localeCompare(String(b.label)));
+  if (1 + members.length > MAX_STEPS) {
+    return refuse(`member-filter needs ${1 + members.length} steps (> budget ${MAX_STEPS}) — escalate`, ROUTER_DRIVER);
+  }
+  for (let i = 0; i < members.length; i += 1) {
+    const m = members[i];
+    const res = await ctx.dispatch("tmct_callees", { symbol: m.label });
+    if (!res.ok) return refuse(`the callees hop for ${m.label} did not ground: ${res.error}`, ROUTER_DRIVER);
+    calls.push({ name: "tmct_callees", input: { symbol: m.label } });
+    proof.push({ step: "causal-link", producer: "step-1", condition: m.label, consumer: `step-${i + 2}:tmct_callees`, role: "member-filter", ok: true });
+    why.push(`[${i + 2}] callees hop over ${m.label} (a member step 1 produced)`);
+  }
+
+  const composed = membersReaching(ctx.graph, classInd, target.label);
+  return {
+    calls, refused: false, terminated: true, proof, driver: ROUTER_DRIVER, why, composed,
+    observed: `plan(member-filter): ${calls.map((c) => c.name).join(" -> ")} => {${composed.join(", ")}}`,
+  };
+}
+
+/** Fold a multi-step plan's EXECUTED, threaded step results into one composed
+ *  answer, choosing the operator from the router's HTN method:
+ *    - relative-filter ("of the <set>, which are <Y>")  -> set INTERSECTION
+ *    - conditional "... <action> instead"               -> FALLBACK-if-empty
+ *    - conditional "if <check>, <action>"                -> GUARD-if-empty
+ *    - sequence (independent "... then ...")             -> no single composed set
+ *  Returns a label array, or null when the method composes nothing (sequence). */
+async function composeResult(request, calls, ctx) {
+  const { method } = decompose(request);
+  if (method !== "relative-filter" && method !== "conditional") return null;
+  if (calls.length < 2) return null; // a relaxed/short plan cannot fold — result stays unmet
+
+  const sets = [];
+  for (const c of calls) {
+    const res = await ctx.dispatch(c.name, c.input || {});
+    sets.push(res.ok && Array.isArray(res.result) ? res.result : []);
+  }
+
+  if (method === "relative-filter") return intersect(sets[0], sets[1]);
+  return /\binstead\b/i.test(request) ? fallbackIfEmpty(sets[0], sets[1]) : guardIfEmpty(sets[0], sets[1]);
+}
+
+/** Single-shot via the resolver, compound via the planner (+ result
+ *  composition). Never escalates to the goal-reasoner on its own — see
+ *  runCapabilityPlan for the full resolver/planner -> goal-reasoner chain. */
+export async function runResolverPlan(request, tools, ctx) {
+  const d = decompose(request);
+  if (d.method === "member-filter") return memberFilterDrive(request, tools, ctx, d.segments);
+
+  if (isMultiStep(request)) {
+    const loop = await plan(request, tools, ctx, { driver: ROUTER_DRIVER });
+    if (loop.refused) return loop;
+    const composed = await composeResult(request, loop.calls, ctx);
+    return composed === null ? loop : { ...loop, composed };
+  }
+
+  const r = await resolveOne(request, tools, ctx, { execute: true });
+  if (r.refused) {
+    return { calls: [], refused: true, terminated: true, proof: [], driver: ROUTER_DRIVER, why: r.reason };
+  }
+  return {
+    calls: [r.selected], refused: false, terminated: true, proof: r.proof,
+    driver: ROUTER_DRIVER, why: r.why, observed: r.observed,
+  };
+}
+
+/** The full drive: resolver/planner first; a refusal there escalates to the
+ *  closed-world goal-reasoner. Mirrors agentbench's driver-resolver.mjs +
+ *  driver-goal.mjs composition, with no agentbench/ dependency (agentbench/
+ *  is dev-only, never shipped). Returns a loopResult:
+ *  `{ calls, refused, terminated, proof, why, driver, composed?, observed? }`. */
+export async function runCapabilityPlan(request, tools, ctx) {
+  const c1 = await runResolverPlan(request, tools, ctx);
+  if (!c1.refused) return c1;
+  const c2 = await goalReason(request, tools, ctx, { driver: GOAL_DRIVER });
+  // Both stages refused: carry the resolver/planner's own reason alongside the
+  // goal-reasoner's so a caller can show why the direct route AND the
+  // maintenance-goal route both declined,
+  // rather than only the last (often less specific) of the two.
+  return c2.refused ? { ...c2, c1Why: c1.why } : c2;
+}
+
+/** Build a real `{ dispatch, resolve, graph, config }` context against a repo's
+ *  actual code graph — the router's window onto the live tool layer. `dispatch`
+ *  runs the SAME dispatchTool the chat/CLI/server surfaces call, and computes
+ *  the structured `result` label-set (results.mjs's resultSetOf) a multi-step
+ *  plan folds. `resolve` delegates to resolveObject over the SAME parsed graph,
+ *  so resolve() and dispatch() always agree on what an entity resolves to.
+ *  Pass an already-parsed `graph` (e.g. a chat session's own) to skip reloading
+ *  it — mirrors the config -> source.fetchEntities -> parseEntities chain
+ *  dispatchTool runs internally, so a passed-in graph must come from that same
+ *  chain to stay consistent. */
+export async function buildCapabilityPlanCtx({ config, source = defaultSource, tel = null, graph = null } = {}) {
+  const g = graph || parseEntities(await source.fetchEntities(config));
+  const resolve = (term) => resolveObject(g, term);
+  const dispatch = async (name, input) => {
+    try {
+      const text = await dispatchTool(name, input, { config, source, tel });
+      const primary = input && (input.symbol ?? input.module ?? input.class ?? input.query);
+      const resolved = primary ? resolve(String(primary)).match : null;
+      const result = resultSetOf(g, name, input, resolved);
+      return { ok: true, text, resolved, result };
+    } catch (e) {
+      if (e instanceof ToolError) return { ok: false, error: e.message };
+      throw e;
+    }
+  };
+  return { dispatch, resolve, graph: g, config };
+}