snipara-companion 2.0.0 → 2.0.2

package/README.md

@@ -31,10 +31,58 @@ Local continuity commands work without a Snipara account; commands that read
 hosted context or memory need `init`/`login` first. Run
 `snipara-companion --help` for the full command list.
 
+## Local Context Pack
+
+`context-pack` is a free, local-only reversible pack for long tool outputs,
+logs, diffs, and notes. It stores exact content under
+`.snipara/context-pack` and never uploads raw output to hosted Snipara.
+
+```bash
+# Pack piped tool output
+pnpm test 2>&1 | snipara-companion context-pack pack \
+  --label "package test output" \
+  --source "pnpm test"
+
+# Pack a local file
+snipara-companion context-pack pack --file ./debug.log --kind log --json
+
+# Retrieve exact content later
+snipara-companion context-pack retrieve latest
+snipara-companion context-pack retrieve cpack_abcd1234 --output ./restored.log
+snipara-companion context-pack retrieve cpack_abcd1234 --json --metadata-only
+
+# Inspect and clean local storage
+snipara-companion context-pack stats
+snipara-companion context-pack clean --older-than-days 14
+
+# Attach metadata-only receipts to events/checkpoints
+snipara-companion post-tool --tool Bash --result "$(cat ./debug.log)" --pack-result
+snipara-companion emit-event -e tool_result --context-pack cpack_abcd1234
+snipara-companion workflow runtime-checkpoint verify \
+  --summary "Captured verifier output" \
+  --context-pack cpack_abcd1234
+```
+
+The pack ID is derived from the content hash, so packing identical content is
+idempotent. Use `--ttl-days` when temporary output should be cleaned by the
+default `context-pack clean` path. The storage directory writes its own
+`.gitignore` so raw pack blobs do not appear in normal Git staging. Pack blobs
+are plaintext local files with restrictive permissions. Secret-like input is
+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"]
     Companion --> Diagnostics["status, brief, timeline, phase commits, handoff"]
+    Companion --> Packs["context-pack (local output packs)"]
     Companion --> Memory["snipara-memory (optional local memory)"]
     Companion --> Evals["snipara-evals (optional local evals)"]
     Companion --> Hosted["Snipara Hosted MCP / API"]
@@ -202,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

@@ -3,6 +3,136 @@ declare function resolveQueryFromToolInput(toolInput?: string, tool?: string): s
 
 declare function extractFilesFromToolInput(toolInput?: string): string[];
 
+type ContextPackKind = "tool_output" | "log" | "diff" | "file" | "text" | "note";
+interface ContextPackRecord {
+    version: "snipara.context_pack.v1";
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    kind: ContextPackKind;
+    label: string | null;
+    source: string | null;
+    tags: string[];
+    repoRoot: string;
+    sha256: string;
+    bytes: number;
+    lineCount: number;
+    contentType: "text/plain";
+    contentEncoding: "utf8";
+    preview: string;
+    expiresAt: string | null;
+    sensitive: boolean;
+    warnings: Array<{
+        code: string;
+        message: string;
+    }>;
+    storage: {
+        baseRelativePath: string;
+        manifestRelativePath: string;
+        blobRelativePath: string;
+    };
+}
+interface PackContextOptions {
+    cwd?: string;
+    content: string;
+    label?: string;
+    source?: string;
+    kind?: string;
+    tags?: string[];
+    ttlDays?: number;
+    maxBytes?: number;
+    allowSensitive?: boolean;
+    now?: Date;
+}
+interface ContextPackPackCommandOptions {
+    cwd?: string;
+    text?: string;
+    file?: string;
+    input?: string;
+    label?: string;
+    source?: string;
+    kind?: string;
+    tags?: string[];
+    ttlDays?: number;
+    maxBytes?: number;
+    allowSensitive?: boolean;
+    json?: boolean;
+}
+interface ContextPackRetrieveCommandOptions {
+    cwd?: string;
+    output?: string;
+    metadataOnly?: boolean;
+    json?: boolean;
+}
+interface ContextPackStatsCommandOptions {
+    cwd?: string;
+    json?: boolean;
+}
+interface ContextPackCleanCommandOptions {
+    cwd?: string;
+    all?: boolean;
+    expired?: boolean;
+    olderThanDays?: number;
+    dryRun?: boolean;
+    json?: boolean;
+    now?: Date;
+}
+interface ContextPackStoragePaths {
+    repoRoot: string;
+    baseDir: string;
+    blobsDir: string;
+    manifestsDir: string;
+    latestPath: string;
+}
+interface PackContextResult {
+    record: ContextPackRecord;
+    created: boolean;
+    baseDir: string;
+    manifestPath: string;
+    blobPath: string;
+}
+interface RetrieveContextPackResult {
+    record: ContextPackRecord;
+    content: string;
+    baseDir: string;
+    manifestPath: string;
+    blobPath: string;
+}
+interface ContextPackStats {
+    version: "snipara.context_pack.stats.v1";
+    baseDir: string;
+    totalPacks: number;
+    totalBytes: number;
+    sensitivePacks: number;
+    expiredPacks: number;
+    kinds: Record<string, number>;
+    oldestCreatedAt: string | null;
+    newestCreatedAt: string | null;
+    latestId: string | null;
+}
+interface ContextPackCleanResult {
+    version: "snipara.context_pack.clean.v1";
+    baseDir: string;
+    dryRun: boolean;
+    selected: number;
+    deleted: number;
+    deletedIds: string[];
+}
+declare function getContextPackStoragePaths(cwd?: string): ContextPackStoragePaths;
+declare function packContext(options: PackContextOptions): PackContextResult;
+declare function resolveContextPackRecord(idOrRef: string, cwd?: string): {
+    paths: ContextPackStoragePaths;
+    record: ContextPackRecord;
+    manifestPath: string;
+};
+declare function retrieveContextPack(idOrRef: string, cwd?: string): RetrieveContextPackResult;
+declare function buildContextPackStats(options?: ContextPackStatsCommandOptions): ContextPackStats;
+declare function cleanContextPacks(options?: ContextPackCleanCommandOptions): ContextPackCleanResult;
+declare function contextPackPackCommand(options: ContextPackPackCommandOptions): Promise<void>;
+declare function contextPackRetrieveCommand(idOrRef: string, options?: ContextPackRetrieveCommandOptions): Promise<void>;
+declare function contextPackStatsCommand(options?: ContextPackStatsCommandOptions): Promise<void>;
+declare function contextPackCleanCommand(options?: ContextPackCleanCommandOptions): Promise<void>;
+
 type PrivacyLevel = "standard" | "sensitive" | "restricted";
 type CanonicalEventType = "session_start" | "session_end" | "compact" | "message_user" | "message_assistant" | "tool_call" | "tool_result" | "file_changed" | "error_observed";
 interface CanonicalEventOptions {
@@ -13,7 +143,48 @@ interface CanonicalEventOptions {
     agentId?: string;
     privacyLevel?: PrivacyLevel;
     payload?: Record<string, unknown>;
+    contextPackReceipts?: LocalContextPackReceiptPayload[];
+}
+type LocalContextPackReceiptOperation = "pack" | "retrieve" | "reference";
+interface LocalContextPackReceiptPayload {
+    version: "snipara.context_pack.receipt.v1";
+    receipt_id: string;
+    pack_id: string;
+    operation: LocalContextPackReceiptOperation;
+    content_uploaded: false;
+    policy_decision: "local_only" | "blocked" | "metadata_only";
+    privacy_level: PrivacyLevel;
+    kind: ContextPackRecord["kind"];
+    label?: string | null;
+    source?: string | null;
+    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;
+    expires_at?: string | null;
+    local_ref: {
+        base_relative_path: string;
+        manifest_relative_path: string;
+    };
 }
+declare function buildLocalContextPackReceipt(record: ContextPackRecord, options?: {
+    operation?: LocalContextPackReceiptOperation;
+    privacyLevel?: PrivacyLevel;
+    policyDecision?: LocalContextPackReceiptPayload["policy_decision"];
+}): LocalContextPackReceiptPayload;
+declare function buildLocalContextPackReceipts(options: {
+    ids: string[];
+    cwd?: string;
+    operation?: LocalContextPackReceiptOperation;
+    privacyLevel?: PrivacyLevel;
+}): LocalContextPackReceiptPayload[];
+declare function attachLocalContextPackReceipts(payload: Record<string, unknown>, receipts: LocalContextPackReceiptPayload[]): Record<string, unknown>;
 declare function buildCanonicalEvent(options: CanonicalEventOptions): {
     type: CanonicalEventType;
     client: string;
@@ -2820,6 +2991,7 @@ interface OrchestratorHandoffRuntimeSandboxPhase {
     bootstrapQuery: string;
     files: string[];
     artifacts: string[];
+    contextPacks: string[];
     sessionId: string | null;
     environment: string | null;
     profile: string | null;
@@ -2849,6 +3021,8 @@ interface AdaptiveModelRequirements {
     preferredEndpointTypes?: string[];
     allowedEndpointTypes?: string[];
     catalogLimit?: number;
+    dailyBudgetCents?: number;
+    monthlyBudgetCents?: number;
     fallback: "main_agent";
 }
 interface AdaptiveRoutingCostEstimate {
@@ -2894,6 +3068,8 @@ interface AdaptiveWorkRoutingOptions {
     workerRole?: string;
     plannerRetainsReasoning?: boolean;
     catalogLimit?: number;
+    dailyBudgetCents?: number;
+    monthlyBudgetCents?: number;
 }
 interface OrchestratorHandoffArtifact {
     schemaVersion: "snipara.orchestrator.handoff.v1";
@@ -2986,4 +3162,4 @@ declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions):
 declare function buildAdaptiveWorkRoutingRecommendation(options: AdaptiveWorkRoutingOptions): AdaptiveWorkRoutingRecommendation;
 declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
 
-export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapQuality, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, collaborationIdeStatusCommand, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveFullWorkflowTokenBudget, resolveQueryFromToolInput, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };
+export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, COLLABORATION_STATE_RELATIVE_PATH, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, TEAM_SYNC_STATE_RELATIVE_PATH, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalShortestPathResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapQuality, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, collaborationIdeStatusCommand, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, extractCommandFromToolInput, extractFilesFromToolInput, formatOrchestratorRecommendationReason, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readLocalCodeOverlayCache, readLocalCodePromotionState, referencesIngestCommand, referencesScanCommand, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeOrchestratorHandoff };