pi-smart-router 0.3.0 → 0.5.0

package/.pi/extensions/smart-router/index.ts

@@ -94,6 +94,15 @@ export {
   initHydraMatcher,
   wireSmartRouterExtension,
 };
+export {
+  buildCompressedDelegateContext,
+  defaultSpawnPlanningDelegate,
+  extractAssistantText,
+  injectPlanningDelegateObservation,
+  isPlanningDelegateActive,
+  PLANNING_DELEGATE_OBSERVATION_PREFIX,
+  resolvePlanningDelegatePath,
+} from './planning-delegate.js';
 export { SMART_ROUTER_FULL_INVOCATIONS, SMART_ROUTER_USAGE } from './commands.js';
 export { routeAndDelegate } from './route-and-delegate.js';
 export {

package/.pi/extensions/smart-router/pi-model-scope.ts

@@ -1,4 +1,7 @@
-import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -15,41 +18,145 @@ type ResolveModelScopeFn = (
   modelRegistry: ModelRegistry,
 ) => Promise<ScopedModel[]>;
 
-function findPiCodingAgentDir(): string {
+const PI_CODING_AGENT_PKG = '@earendil-works/pi-coding-agent';
+const MODEL_RESOLVER_REL = 'dist/core/model-resolver.js';
+const INSTALL_HINT =
+  'Install @earendil-works/pi-coding-agent where pi can resolve it ' +
+  '(e.g. cd ~/.pi/agent/npm && npm install @earendil-works/pi-coding-agent).';
+
+function hasModelResolver(pkgDir: string): boolean {
+  return existsSync(join(pkgDir, MODEL_RESOLVER_REL));
+}
+
+function collectAncestorPackageDirs(startDir: string, maxDepth = 12): string[] {
   const candidates: string[] = [];
-  const roots = [dirname(fileURLToPath(import.meta.url)), process.cwd()];
-
-  for (const start of roots) {
-    let dir = start;
-    for (let i = 0; i < 12; i++) {
-      candidates.push(join(dir, 'node_modules/@earendil-works/pi-coding-agent'));
-      const parent = dirname(dir);
-      if (parent === dir) {
-        break;
+  let dir = startDir;
+  for (let i = 0; i < maxDepth; i++) {
+    candidates.push(join(dir, 'node_modules', PI_CODING_AGENT_PKG));
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return candidates;
+}
+
+function resolvePiBinaryPackageDirs(): string[] {
+  try {
+    const piBin = execSync('which pi', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (!piBin) {
+      return [];
+    }
+    return collectAncestorPackageDirs(dirname(realpathSync(piBin)), 8);
+  } catch {
+    return [];
+  }
+}
+
+function resolveViaModuleResolution(): string | undefined {
+  const attempts: Array<() => string> = [
+    () => fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PKG)),
+    () => createRequire(import.meta.url).resolve(`${PI_CODING_AGENT_PKG}/package.json`),
+    () => createRequire(import.meta.url).resolve(`${PI_CODING_AGENT_PKG}/${MODEL_RESOLVER_REL}`),
+  ];
+
+  for (const attempt of attempts) {
+    try {
+      const resolvedPath = attempt();
+      const marker = `node_modules/${PI_CODING_AGENT_PKG}`;
+      const markerIndex = resolvedPath.lastIndexOf(marker);
+      if (markerIndex === -1) {
+        continue;
       }
-      dir = parent;
+      const pkgDir = resolvedPath.slice(0, markerIndex + marker.length);
+      if (hasModelResolver(pkgDir)) {
+        return pkgDir;
+      }
+    } catch {
+      // Try the next resolution strategy.
+    }
+  }
+
+  return undefined;
+}
+
+/** Locate pi-coding-agent on disk for the resolveModelScope shim. */
+export function findPiCodingAgentDir(): string {
+  const seen = new Set<string>();
+  const candidates: string[] = [];
+
+  const addCandidate = (candidate: string): void => {
+    if (!seen.has(candidate)) {
+      seen.add(candidate);
+      candidates.push(candidate);
     }
+  };
+
+  const viaModuleResolution = resolveViaModuleResolution();
+  if (viaModuleResolution) {
+    addCandidate(viaModuleResolution);
+  }
+
+  for (const start of [dirname(fileURLToPath(import.meta.url)), process.cwd()]) {
+    for (const candidate of collectAncestorPackageDirs(start)) {
+      addCandidate(candidate);
+    }
+  }
+
+  addCandidate(join(homedir(), '.pi/agent/npm/node_modules', PI_CODING_AGENT_PKG));
+
+  if (process.env.HOMEBREW_PREFIX) {
+    addCandidate(join(process.env.HOMEBREW_PREFIX, 'lib/node_modules', PI_CODING_AGENT_PKG));
+  }
+
+  for (const candidate of resolvePiBinaryPackageDirs()) {
+    addCandidate(candidate);
   }
 
   for (const candidate of candidates) {
-    if (existsSync(join(candidate, 'dist/core/model-resolver.js'))) {
+    if (hasModelResolver(candidate)) {
       return candidate;
     }
   }
 
-  throw new Error('Unable to locate @earendil-works/pi-coding-agent for resolveModelScope');
+  throw new Error(
+    `Unable to locate ${PI_CODING_AGENT_PKG} for resolveModelScope. ${INSTALL_HINT}`,
+  );
 }
 
-const piPkgDir = findPiCodingAgentDir();
-const modelResolver = await import(
-  pathToFileURL(join(piPkgDir, 'dist/core/model-resolver.js')).href
-);
-const piResolveModelScope = modelResolver.resolveModelScope as ResolveModelScopeFn;
+async function loadResolveModelScopeFn(): Promise<ResolveModelScopeFn> {
+  try {
+    const pkg = await import('@earendil-works/pi-coding-agent');
+    const publicResolve = (pkg as { resolveModelScope?: ResolveModelScopeFn }).resolveModelScope;
+    if (typeof publicResolve === 'function') {
+      return publicResolve;
+    }
+  } catch {
+    // Fall back to filesystem discovery when the public export is unavailable.
+  }
+
+  const piPkgDir = findPiCodingAgentDir();
+  const modelResolver = await import(
+    pathToFileURL(join(piPkgDir, MODEL_RESOLVER_REL)).href
+  );
+  return modelResolver.resolveModelScope as ResolveModelScopeFn;
+}
+
+let resolveModelScopeFnPromise: Promise<ResolveModelScopeFn> | undefined;
+
+function getResolveModelScopeFn(): Promise<ResolveModelScopeFn> {
+  resolveModelScopeFnPromise ??= loadResolveModelScopeFn();
+  return resolveModelScopeFnPromise;
+}
 
 /** Delegate to pi's resolveModelScope (not yet on the public package export surface). */
 export function resolveModelScope(
   patterns: string[],
   modelRegistry: ModelRegistry,
 ): Promise<ScopedModel[]> {
-  return piResolveModelScope(patterns, modelRegistry);
+  return getResolveModelScopeFn().then((fn) => fn(patterns, modelRegistry));
 }

package/.pi/extensions/smart-router/planning-delegate.ts

@@ -0,0 +1,318 @@
+/**
+ * Cache-preserving planning delegate (SP-144, #71).
+ *
+ * When the pipeline emits `planning_delegate`, run an ephemeral frontier sub-call
+ * on compressed context, inject the result as an observation, and keep primary
+ * inference on the pinned economical model. Falls back to direct frontier routing
+ * when sub-agent spawn is unavailable (pi has no native sub-agent API yet).
+ */
+
+import {
+  type Api,
+  type AssistantMessage,
+  type Context,
+  type Message,
+  type Model,
+  type SimpleStreamOptions,
+  type TextContent,
+} from '@earendil-works/pi-ai/compat';
+
+import type {
+  CompressedContextSpec,
+  PlanningDelegateObservability,
+  RoutingDecision,
+} from '../../../src/domain/types/index.js';
+import {
+  createPlanningDelegateObservability,
+  enrichRoutingDecisionWithPlanningDelegate,
+  PLANNING_DELEGATE,
+  PLANNING_DELEGATE_UNAVAILABLE,
+  PLANNING_DIRECT_FRONTIER,
+} from '../../../src/infrastructure/telemetry/routing-telemetry.js';
+import { collectDelegatedStream } from './delegate-stream.js';
+import { findFleetProfile, resolveRegistryModel } from './delegation-runtime.js';
+import type { StreamDelegationDeps } from './types.js';
+
+/** Prefix for injected planning observations visible to the primary model. */
+export const PLANNING_DELEGATE_OBSERVATION_PREFIX =
+  '[smart-router planning delegate]' as const;
+
+export type PlanningDelegateSpawnResult =
+  | { readonly ok: true; readonly observationText: string }
+  | { readonly ok: false; readonly reason: string };
+
+/** Injectable sub-agent spawn hook (mocked in unit tests). */
+export type PlanningDelegateSpawnFn = (
+  frontierModel: Model<Api>,
+  compressedContext: Context,
+  options: SimpleStreamOptions | undefined,
+  deps: StreamDelegationDeps,
+) => Promise<PlanningDelegateSpawnResult>;
+
+export function isPlanningDelegateActive(
+  decision: RoutingDecision,
+): decision is RoutingDecision & {
+  features: { planning_delegate: PlanningDelegateObservability };
+} {
+  const observability = decision.features?.planning_delegate;
+  return (
+    decision.reason_code === PLANNING_DELEGATE &&
+    observability?.path === 'delegate' &&
+    observability.delegate_model_id !== null
+  );
+}
+
+function isConversationalMessage(message: Message): boolean {
+  return message.role === 'user' || message.role === 'assistant';
+}
+
+function isExecutionTraceMessage(message: Message): boolean {
+  if (message.role === 'toolResult') {
+    return true;
+  }
+  if (message.role !== 'assistant') {
+    return false;
+  }
+  const blocks = message.content;
+  if (!Array.isArray(blocks) || blocks.length === 0) {
+    return false;
+  }
+  return blocks.every(
+    (block) => block.type === 'toolCall' || block.type === 'thinking',
+  );
+}
+
+function estimateContextTokens(context: Context): number {
+  let charCount = 0;
+  if (context.systemPrompt) {
+    charCount += context.systemPrompt.length;
+  }
+  for (const message of context.messages) {
+    if (typeof message.content === 'string') {
+      charCount += message.content.length;
+      continue;
+    }
+    for (const block of message.content) {
+      if (block.type === 'text') {
+        charCount += block.text.length;
+      } else if (block.type === 'thinking') {
+        charCount += block.thinking.length;
+      } else if (block.type === 'toolCall') {
+        charCount += JSON.stringify(block.arguments).length;
+      }
+    }
+  }
+  return Math.max(0, Math.ceil(charCount / 4));
+}
+
+/**
+ * Build compressed context for the ephemeral frontier sub-call (SP-142 limits).
+ * Excludes tool execution history when configured; caps message count and tokens.
+ */
+export function buildCompressedDelegateContext(
+  context: Context,
+  spec: CompressedContextSpec | null | undefined,
+): Context {
+  if (!spec) {
+    return context;
+  }
+
+  let messages = context.messages.filter(isConversationalMessage);
+  if (spec.exclude_execution_history) {
+    messages = messages.filter((message) => !isExecutionTraceMessage(message));
+  }
+
+  if (messages.length > spec.max_messages) {
+    messages = messages.slice(-spec.max_messages);
+  }
+
+  while (messages.length > 1 && estimateContextTokens({ ...context, messages }) > spec.max_tokens) {
+    messages = messages.slice(1);
+  }
+
+  return {
+    ...context,
+    messages,
+  };
+}
+
+export function extractAssistantText(message: AssistantMessage | undefined): string {
+  if (!message) {
+    return '';
+  }
+  return message.content
+    .filter((block): block is TextContent => block.type === 'text')
+    .map((block) => block.text)
+    .join('\n')
+    .trim();
+}
+
+/** Inject frontier sub-call output as a user observation for the primary model. */
+export function injectPlanningDelegateObservation(
+  context: Context,
+  observationText: string,
+): Context {
+  const trimmed = observationText.trim();
+  if (!trimmed) {
+    return context;
+  }
+
+  const observationMessage: Message = {
+    role: 'user',
+    content: `${PLANNING_DELEGATE_OBSERVATION_PREFIX}\n${trimmed}`,
+    timestamp: Date.now(),
+  };
+
+  return {
+    ...context,
+    messages: [...context.messages, observationMessage],
+  };
+}
+
+/** Default frontier sub-call via provider stream (ephemeral one-shot delegate). */
+export async function defaultSpawnPlanningDelegate(
+  frontierModel: Model<Api>,
+  compressedContext: Context,
+  options: SimpleStreamOptions | undefined,
+  deps: StreamDelegationDeps,
+): Promise<PlanningDelegateSpawnResult> {
+  try {
+    const result = await collectDelegatedStream(
+      frontierModel,
+      compressedContext,
+      deps,
+      options,
+    );
+    if (result.failed || !result.finalMessage) {
+      return {
+        ok: false,
+        reason:
+          result.finalMessage?.errorMessage ??
+          'planning delegate sub-call failed',
+      };
+    }
+
+    const observationText = extractAssistantText(result.finalMessage);
+    if (!observationText) {
+      return {
+        ok: false,
+        reason: 'planning delegate sub-call returned empty response',
+      };
+    }
+
+    return { ok: true, observationText };
+  } catch (error) {
+    return {
+      ok: false,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export interface PlanningDelegateResolution {
+  readonly context: Context;
+  readonly decision: RoutingDecision;
+  readonly targetModelId: string;
+  readonly usedDelegatePath: boolean;
+}
+
+/**
+ * Resolve planning delegate path: sub-call + observation injection, or direct frontier fallback.
+ */
+export async function resolvePlanningDelegatePath(
+  context: Context,
+  decision: RoutingDecision,
+  options: SimpleStreamOptions | undefined,
+  deps: StreamDelegationDeps,
+): Promise<PlanningDelegateResolution> {
+  const observability = decision.features!.planning_delegate!;
+  const delegateModelId = observability.delegate_model_id!;
+  const primaryModelId = decision.selected_model_id;
+
+  const frontierProfile = findFleetProfile(deps.fleet, delegateModelId);
+  const frontierModel = frontierProfile
+    ? resolveRegistryModel(deps.modelRegistry, frontierProfile)
+    : undefined;
+
+  if (!frontierModel) {
+    console.warn(
+      '[smart-router] planning delegate unavailable: frontier model missing from registry',
+      delegateModelId,
+    );
+    return applyPlanningDelegateDirectFallback(
+      context,
+      decision,
+      delegateModelId,
+      PLANNING_DELEGATE_UNAVAILABLE,
+      deps,
+    );
+  }
+
+  const compressedContext = buildCompressedDelegateContext(
+    context,
+    observability.compressed_context,
+  );
+  const spawnFn = deps.spawnPlanningDelegate ?? defaultSpawnPlanningDelegate;
+  const spawnResult = await spawnFn(frontierModel, compressedContext, options, deps);
+
+  if (!spawnResult.ok) {
+    console.warn(
+      '[smart-router] planning delegate sub-call failed, falling back to direct frontier route',
+      spawnResult.reason,
+    );
+    return applyPlanningDelegateDirectFallback(
+      context,
+      decision,
+      delegateModelId,
+      PLANNING_DELEGATE_UNAVAILABLE,
+      deps,
+    );
+  }
+
+  console.warn(
+    '[smart-router] planning delegate sub-call completed',
+    JSON.stringify({
+      primary_model_id: primaryModelId,
+      delegate_model_id: delegateModelId,
+      observation_chars: spawnResult.observationText.length,
+    }),
+  );
+
+  return {
+    context: injectPlanningDelegateObservation(context, spawnResult.observationText),
+    decision,
+    targetModelId: primaryModelId,
+    usedDelegatePath: true,
+  };
+}
+
+function applyPlanningDelegateDirectFallback(
+  context: Context,
+  decision: RoutingDecision,
+  delegateModelId: string,
+  fallbackReason: string,
+  deps: StreamDelegationDeps,
+): PlanningDelegateResolution {
+  const profile = findFleetProfile(deps.fleet, delegateModelId);
+  const fallbackDecision = enrichRoutingDecisionWithPlanningDelegate(
+    {
+      ...decision,
+      selected_model_id: delegateModelId,
+      tier: profile?.tier ?? decision.tier,
+      reason_code: PLANNING_DIRECT_FRONTIER,
+    },
+    createPlanningDelegateObservability({
+      path: 'direct',
+      delegate_model_id: delegateModelId,
+      planning_delegate_reason_code: PLANNING_DIRECT_FRONTIER,
+      fallback_reason: fallbackReason,
+    }),
+  );
+
+  return {
+    context,
+    decision: fallbackDecision,
+    targetModelId: delegateModelId,
+    usedDelegatePath: false,
+  };
+}

package/.pi/extensions/smart-router/route-and-delegate.ts

@@ -34,6 +34,10 @@ import {
 } from './delegation-runtime.js';
 import { buildRoutingRequest } from './routing-context.js';
 import { capturePreRouteOutcomes, updateSessionRoutingSnapshot } from './routing-outcomes.js';
+import {
+  isPlanningDelegateActive,
+  resolvePlanningDelegatePath,
+} from './planning-delegate.js';
 import type { StreamDelegationDeps } from './types.js';
 
 function isRoutingLogEnabled(): boolean {
@@ -287,6 +291,22 @@ export async function routeAndDelegate(
   deps.datasetRecorder?.record(request, decision);
   updateSessionRoutingSnapshot(deps, sessionId, request, decision);
 
+  let delegationContext: Context = context;
+
+  if (isPlanningDelegateActive(decision)) {
+    const planningResolution = await resolvePlanningDelegatePath(
+      context,
+      decision,
+      options,
+      deps,
+    );
+    delegationContext = planningResolution.context;
+    decision = planningResolution.decision;
+    if (!planningResolution.usedDelegatePath) {
+      deps.onRoutingDecision?.(decision);
+    }
+  }
+
   let targetModel = resolveTargetModel(deps, decision);
   if (!targetModel) {
     console.warn(
@@ -374,7 +394,7 @@ export async function routeAndDelegate(
 
       const result = await delegateWithOutcome(
         targetModel,
-        context,
+        delegationContext,
         deps,
         options,
         sessionId,

package/.pi/extensions/smart-router/types.ts

@@ -15,6 +15,7 @@ import type {
   PriceCatalog,
   RoutingDecision,
 } from '../../../src/domain/types/index.js';
+import type { PlanningDelegateSpawnFn } from './planning-delegate.js';
 import type { StorePort } from '../../../src/domain/types/store-port.js';
 import {
   DatasetRecorder,
@@ -56,6 +57,8 @@ export interface StreamDelegationDeps {
   readonly executionLedger: ExecutionLedger;
   /** Injectable for tests; production uses pi-ai streamSimple. */
   delegateStream?: DelegateStreamFn;
+  /** Injectable planning delegate sub-call; production uses frontier stream delegate. */
+  spawnPlanningDelegate?: PlanningDelegateSpawnFn;
   readonly lifecycleHookState?: LifecycleHookState;
   readonly datasetRecorder?: DatasetRecorder;
   readonly outcomeRecorder?: OutcomeRecorder;