snipara-companion 2.0.1 → 2.0.2

package/README.md

@@ -72,6 +72,12 @@ blocked by default; use `--allow-sensitive` only when you intentionally need an
 exact local recovery artifact, and prefer the exact pack ID over `latest` in
 handoffs.
 
+Metadata-only context-pack receipts include token economy fields:
+`baseline_tokens`, `packed_tokens`, `retrieved_tokens`, and `saved_tokens`.
+Pack/reference receipts can claim saved tokens because only receipt metadata is
+uploaded; retrieve receipts set retrieved tokens to the local baseline so they
+do not overstate savings.
+
 ```mermaid
 flowchart LR
     Project["Local project"] --> Companion["snipara-companion"]
@@ -244,6 +250,15 @@ Project owners can configure Adaptive Work Routing in Project > Automation:
 `off`, `recommend`, or `catalog`; approval; planner-retained reasoning; allowed
 endpoint types (`cloud`, `local`, `self_hosted`); worker classes; and budget
 hints. `workflow run` reads that hosted policy and CLI flags cannot broaden it.
+Companion passes policy budgets into provider-neutral model requirements; the
+hosted gateway enforces project and provider daily/monthly budgets when receipt
+history is available.
+
+Approval is an MCP contract, not a dashboard-only UX path. When project policy
+requires approval, a coding agent calls `snipara_adaptive_routing_approve` with
+the routing card or handoff subject, approved write scopes, endpoint types, a
+stable `idempotency_key`, and optional cost/expiry bounds. Companion dry-runs
+surface the approval requirement but do not auto-approve or spawn workers.
 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.

package/dist/index.d.ts

@@ -160,6 +160,10 @@ interface LocalContextPackReceiptPayload {
     tags: string[];
     bytes: number;
     line_count: number;
+    baseline_tokens?: number;
+    packed_tokens?: number;
+    retrieved_tokens?: number;
+    saved_tokens?: number;
     payload_digest?: string;
     sensitive: boolean;
     created_at: string;
@@ -3017,6 +3021,8 @@ interface AdaptiveModelRequirements {
     preferredEndpointTypes?: string[];
     allowedEndpointTypes?: string[];
     catalogLimit?: number;
+    dailyBudgetCents?: number;
+    monthlyBudgetCents?: number;
     fallback: "main_agent";
 }
 interface AdaptiveRoutingCostEstimate {
@@ -3062,6 +3068,8 @@ interface AdaptiveWorkRoutingOptions {
     workerRole?: string;
     plannerRetainsReasoning?: boolean;
     catalogLimit?: number;
+    dailyBudgetCents?: number;
+    monthlyBudgetCents?: number;
 }
 interface OrchestratorHandoffArtifact {
     schemaVersion: "snipara.orchestrator.handoff.v1";

package/dist/index.js

@@ -2683,9 +2683,19 @@ async function contextPackCleanCommand(options = {}) {
 function uniqueStrings2(values) {
   return Array.from(new Set(values.map((value) => value.trim()).filter(Boolean)));
 }
+function estimateTokensFromBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes <= 0) {
+    return 0;
+  }
+  return Math.ceil(bytes / 4);
+}
+function estimateReceiptTokens(value) {
+  return estimateTokensFromBytes(Buffer.byteLength(JSON.stringify(value), "utf8"));
+}
 function buildLocalContextPackReceipt(record, options = {}) {
   const operation = options.operation ?? "reference";
-  return {
+  const baselineTokens = estimateTokensFromBytes(record.bytes);
+  const baseReceipt = {
     version: "snipara.context_pack.receipt.v1",
     receipt_id: `${record.id}:${operation}:${record.updatedAt}`,
     pack_id: record.id,
@@ -2708,6 +2718,16 @@ function buildLocalContextPackReceipt(record, options = {}) {
       manifest_relative_path: record.storage.manifestRelativePath
     }
   };
+  const packedTokens = estimateReceiptTokens(baseReceipt);
+  const retrievedTokens = operation === "retrieve" ? baselineTokens : 0;
+  const savedTokens = Math.max(0, baselineTokens - packedTokens - retrievedTokens);
+  return {
+    ...baseReceipt,
+    baseline_tokens: baselineTokens,
+    packed_tokens: packedTokens,
+    retrieved_tokens: retrievedTokens,
+    saved_tokens: savedTokens
+  };
 }
 function buildLocalContextPackReceipts(options) {
   return uniqueStrings2(options.ids).slice(0, 20).map((id) => {
@@ -11853,6 +11873,8 @@ function buildAdaptiveWorkRoutingRecommendation(options) {
     preferredEndpointTypes,
     allowedEndpointTypes,
     catalogLimit: options.catalogLimit,
+    dailyBudgetCents: options.dailyBudgetCents,
+    monthlyBudgetCents: options.monthlyBudgetCents,
     fallback: "main_agent"
   });
   const warnings = [
@@ -19673,7 +19695,9 @@ function buildWorkflowAdaptiveRouting(options, policy = null, intentWarnings = [
     allowedEndpointTypes,
     workerRole,
     plannerRetainsReasoning: options.plannerRetainsReasoning ?? policy?.plannerRetainsReasoning ?? (options.routeLocalWorkers ? true : void 0),
-    catalogLimit: policy?.catalogLimit ?? DEFAULT_ADAPTIVE_ROUTING_CATALOG_LIMIT
+    catalogLimit: policy?.catalogLimit ?? DEFAULT_ADAPTIVE_ROUTING_CATALOG_LIMIT,
+    dailyBudgetCents: policy?.dailyBudgetCents,
+    monthlyBudgetCents: policy?.monthlyBudgetCents
   });
   const requestedWorkerRole = stringValue5(options.routingWorkerRole);
   let routing = buildRecommendation(requestedWorkerRole);

package/package.json

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