snipara-companion 1.4.21 → 1.4.22

package/README.md

@@ -127,6 +127,7 @@ snipara-companion brief --task "ship auth hardening" --changed-files src/auth.ts
 snipara-companion timeline
 snipara-companion workflow phase-commit build --summary "tests green"
 snipara-companion workflow impact-gate
+snipara-companion workflow run --adaptive-routing-dry-run --route-local-workers "document a scoped change"
 snipara-companion verify --changed-files src/auth.ts --diff-summary "auth hardening"
 snipara-companion run --task "ship auth hardening" --changed-files src/auth.ts --release
 snipara-companion handoff --summary "status command shipped" --next "publish package"
@@ -141,6 +142,9 @@ snipara-companion workflow resume --include-session-context
 - `workflow impact-gate` audits committed local workflow phases that are ahead
   of upstream but not pushed. It does not push, and dirty working-tree files are
   reported separately from the committed diff.
+- `workflow run --adaptive-routing-dry-run` prints an Adaptive Work Routing
+  card. Add `--route-local-workers` when a strong planner should keep deep
+  reasoning while a local worker handles scoped execution.
 - `verify` builds a transparent verification plan from companion code impact
   signals plus local package scripts. It recommends checks; it does not claim to
   execute them.
@@ -167,6 +171,35 @@ if the hosted call still times out. A hosted final-commit timeout does not modif
 Git state. Custom final-commit categories are namespaced under `final-commit`
 before the hosted call so they stay on the handoff-only path.
 
+## Adaptive Work Routing
+
+Adaptive Work Routing is a recommendation-first path for routing scoped work to
+the right worker class, endpoint type, and cost profile without hardcoding model
+names in the CLI.
+
+```bash
+snipara-companion workflow run \
+  --mode full \
+  --adaptive-routing-dry-run \
+  --route-local-workers \
+  --routing-worker-role coding \
+  --routing-preferred-endpoint local \
+  --routing-allowed-endpoint local \
+  --routing-allowed-endpoint cloud \
+  --planner-retains-reasoning \
+  "Update documentation for the new gateway"
+```
+
+The output is a routing card and handoff metadata. Companion calls the hosted
+`snipara_adaptive_routing_catalog` tool when project auth is configured, records
+the sanitized runtime catalog in the handoff, and falls back to local dry-run
+metadata when the hosted gateway is unavailable. It does not silently spawn
+workers. The stable contract is provider-neutral requirements such as worker
+role, reasoning depth, context budget, endpoint type, write scope, and fallback.
+Project credentials stay server-side behind the hosted gateway; local endpoints
+such as Ollama, LM Studio, AnythingLLM, or other OpenAI-compatible servers must
+be reachable from the worker execution environment.
+
 ## Verification Plans
 
 Use `verify` when an agent asks what to prove before handoff or release:

package/dist/index.d.ts

@@ -2837,10 +2837,24 @@ interface AdaptiveRoutingCard {
     reasons: string[];
     warnings: string[];
 }
+interface AdaptiveRoutingGatewayStatus {
+    source: "hosted_mcp";
+    success: boolean;
+    resolutionStatus?: string;
+    candidateCount: number;
+    fallback?: string;
+    warnings: string[];
+}
+interface AdaptiveRoutingRuntimeCatalog {
+    version?: string;
+    candidates: Array<Record<string, unknown>>;
+}
 interface AdaptiveWorkRoutingRecommendation {
     workProfile: AdaptiveWorkProfile;
     requirements: AdaptiveModelRequirements;
     routingCard: AdaptiveRoutingCard;
+    gateway?: AdaptiveRoutingGatewayStatus;
+    runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
 }
 interface AdaptiveWorkRoutingOptions {
     query: string;
@@ -2877,6 +2891,8 @@ interface OrchestratorHandoffArtifact {
         workProfile?: AdaptiveWorkProfile;
         requirements?: AdaptiveModelRequirements;
         routingCard?: AdaptiveRoutingCard;
+        gateway?: AdaptiveRoutingGatewayStatus;
+        runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
     };
     task: {
         title: string;

package/dist/index.js

@@ -11144,7 +11144,9 @@ function buildOrchestratorHandoff(options) {
       ...options.adaptiveRouting ? {
         workProfile: options.adaptiveRouting.workProfile,
         requirements: options.adaptiveRouting.requirements,
-        routingCard: options.adaptiveRouting.routingCard
+        routingCard: options.adaptiveRouting.routingCard,
+        ...options.adaptiveRouting.gateway ? { gateway: options.adaptiveRouting.gateway } : {},
+        ...options.adaptiveRouting.runtimeCatalog ? { runtimeCatalog: options.adaptiveRouting.runtimeCatalog } : {}
       } : {}
     },
     task: {
@@ -14648,6 +14650,20 @@ function stringValue5(value) {
   const stringified = String(value).trim();
   return stringified || void 0;
 }
+function numberValue5(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  const text = stringValue5(value);
+  if (!text) {
+    return void 0;
+  }
+  const parsed = Number(text);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function uniqueStrings3(values) {
+  return Array.from(new Set(values.filter((value) => value.trim().length > 0)));
+}
 function normalizeEnum(value) {
   return stringValue5(value)?.replace(/[-\s]/g, "_").toUpperCase() ?? "";
 }
@@ -17064,6 +17080,12 @@ function printAdaptiveRoutingRecommendation(routing) {
   if (routing.requirements.plannerRetainsReasoning) {
     printKeyValue("Planner retains reasoning:", "yes");
   }
+  if (routing.gateway) {
+    printKeyValue(
+      "Hosted catalog:",
+      routing.gateway.success ? `${routing.gateway.candidateCount} candidate(s), ${routing.gateway.resolutionStatus ?? "ready"}` : "unavailable"
+    );
+  }
   if (routing.routingCard.reasons.length > 0) {
     console.log("Reasons:");
     for (const reason of routing.routingCard.reasons) {
@@ -17077,6 +17099,73 @@ function printAdaptiveRoutingRecommendation(routing) {
     }
   }
 }
+async function enrichAdaptiveRoutingWithHostedCatalog(client, routing) {
+  try {
+    const result = await client.callTool(
+      "snipara_adaptive_routing_catalog",
+      {
+        work_profile: routing.workProfile,
+        model_requirements: routing.requirements,
+        limit: 20
+      }
+    );
+    const catalog = normalizeAdaptiveRoutingCatalog(result.catalog);
+    const warnings = normalizeStringArray3(result.warnings) ?? [];
+    const candidateCount = numberValue5(result.resolution?.candidate_count) ?? numberValue5(result.resolution?.candidateCount) ?? catalog.candidates.length;
+    const gateway = {
+      source: "hosted_mcp",
+      success: result.success !== false,
+      resolutionStatus: stringValue5(result.resolution?.status),
+      candidateCount,
+      fallback: stringValue5(result.fallback) ?? stringValue5(result.resolution?.fallback) ?? "main_agent",
+      warnings
+    };
+    const reasons = [
+      ...routing.routingCard.reasons,
+      candidateCount > 0 ? `hosted adaptive routing catalog returned ${candidateCount} candidate(s)` : "hosted adaptive routing catalog returned no candidates and will fail closed"
+    ];
+    return {
+      ...routing,
+      gateway,
+      runtimeCatalog: catalog,
+      routingCard: {
+        ...routing.routingCard,
+        reasons: uniqueStrings3(reasons),
+        warnings: uniqueStrings3([...routing.routingCard.warnings, ...warnings])
+      }
+    };
+  } catch (error) {
+    const warning = `Hosted adaptive routing catalog unavailable; keeping local dry-run metadata (${toPreview(error)}).`;
+    return {
+      ...routing,
+      gateway: {
+        source: "hosted_mcp",
+        success: false,
+        resolutionStatus: "unavailable",
+        candidateCount: 0,
+        fallback: "main_agent",
+        warnings: [warning]
+      },
+      routingCard: {
+        ...routing.routingCard,
+        warnings: uniqueStrings3([...routing.routingCard.warnings, warning])
+      }
+    };
+  }
+}
+function normalizeAdaptiveRoutingCatalog(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { candidates: [] };
+  }
+  const record = value;
+  const candidates = Array.isArray(record.candidates) ? record.candidates.filter(
+    (candidate) => Boolean(candidate) && typeof candidate === "object" && !Array.isArray(candidate)
+  ) : [];
+  return {
+    version: stringValue5(record.version),
+    candidates
+  };
+}
 function printUploadResult(path20, result) {
   printKeyValue("Uploaded:", path20);
   printCompactObject(result, ["message", "document_id", "documentId", "version", "status"]);
@@ -18551,7 +18640,7 @@ async function workflowRunCommand(options) {
   ensureConfigured();
   const client = createClient(2e4);
   const adaptiveRoutingRequested = shouldBuildAdaptiveRouting(options);
-  const adaptiveRouting = adaptiveRoutingRequested ? buildWorkflowAdaptiveRouting(options) : null;
+  const adaptiveRouting = adaptiveRoutingRequested ? await enrichAdaptiveRoutingWithHostedCatalog(client, buildWorkflowAdaptiveRouting(options)) : null;
   const orchestratorRecommendation = getOrchestratorRecommendation(options.query, options.mode, {
     policyAutoRoute: options.autoRouteOrchestrator,
     policySource: options.orchestratorPolicySource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "snipara-companion",
-  "version": "1.4.21",
+  "version": "1.4.22",
   "description": "Snipara Git-style companion CLI for local workflow continuity, hooks, hosted context, and Mini Snipara OSS workflows",
   "main": "dist/index.js",
   "bin": {