snipara-companion 1.4.22 → 2.0.1

package/README.md

@@ -31,10 +31,52 @@ 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.
+
 ```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"]
@@ -191,15 +233,39 @@ snipara-companion workflow run \
 ```
 
 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.
+`snipara_adaptive_routing_catalog` tool when project auth and policy allow it,
+records the sanitized runtime catalog in the handoff, and falls back to local
+dry-run metadata when the hosted gateway is unavailable or omits
+`success: true`. 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 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.
 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.
 
+For the open package without Snipara SaaS, add a local policy file:
+
+```json
+{
+  "mode": "recommend",
+  "plannerRetainsReasoning": true,
+  "preferLocalWorkers": true,
+  "allowedEndpointTypes": ["local", "cloud"],
+  "preferredEndpointTypes": ["local"],
+  "allowedWorkerClasses": ["documentation", "tests", "review"],
+  "catalogLimit": 8
+}
+```
+
+Save it at `.snipara/adaptive-routing.json`. Without hosted configuration,
+`workflow run` only emits local Adaptive Work Routing metadata and handoff files:
+it does not query hosted context, call the hosted catalog, or spawn workers.
+
 ## Verification Plans
 
 Use `verify` when an agent asks what to prove before handoff or release:

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,44 @@ 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;
+    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;
@@ -379,6 +546,33 @@ interface AutomationConfigBundle {
     files: AutomationConfigFile[];
     instructions: string[];
 }
+interface ProjectAutomationSettings {
+    automationClient?: string;
+    autoInjectContext?: boolean;
+    trackAccessedFiles?: boolean;
+    preserveOnCompaction?: boolean;
+    restoreOnSessionStart?: boolean;
+    enrichPrompts?: boolean;
+    maxTokensPerQuery?: number;
+    searchMode?: string;
+    includeSummaries?: boolean;
+    adaptiveRoutingMode?: string;
+    adaptiveRoutingRequireApproval?: boolean;
+    adaptiveRoutingPlannerRetainsReasoning?: boolean;
+    adaptiveRoutingPreferLocalWorkers?: boolean;
+    adaptiveRoutingAllowedEndpointTypes?: string[];
+    adaptiveRoutingPreferredEndpointTypes?: string[];
+    adaptiveRoutingAllowedWorkerClasses?: string[];
+    adaptiveRoutingFallback?: string;
+    adaptiveRoutingDailyBudgetCents?: number;
+    adaptiveRoutingMonthlyBudgetCents?: number;
+    adaptiveRoutingCatalogLimit?: number;
+}
+interface ProjectAutomationSettingsResult {
+    settings: ProjectAutomationSettings;
+    plan?: string;
+    featureAvailability?: Record<string, unknown>;
+}
 interface RecentAutomationEvent {
     id: string;
     sessionId: string;
@@ -986,6 +1180,7 @@ declare class RLMClient {
         limit?: number;
     }): Promise<RecentAutomationEventsResult>;
     getAutomationConfigBundle(client: string): Promise<AutomationConfigBundle>;
+    getAutomationSettings(): Promise<ProjectAutomationSettingsResult>;
     evaluateStuckGuard(args?: EvaluateStuckGuardArgs): Promise<StuckGuardEvaluationResult>;
     getStuckGuardStatus(args?: {
         sessionId?: string;
@@ -2792,6 +2987,7 @@ interface OrchestratorHandoffRuntimeSandboxPhase {
     bootstrapQuery: string;
     files: string[];
     artifacts: string[];
+    contextPacks: string[];
     sessionId: string | null;
     environment: string | null;
     profile: string | null;
@@ -2820,6 +3016,7 @@ interface AdaptiveModelRequirements {
     writeScope: string[];
     preferredEndpointTypes?: string[];
     allowedEndpointTypes?: string[];
+    catalogLimit?: number;
     fallback: "main_agent";
 }
 interface AdaptiveRoutingCostEstimate {
@@ -2864,6 +3061,7 @@ interface AdaptiveWorkRoutingOptions {
     allowedEndpointTypes?: string[];
     workerRole?: string;
     plannerRetainsReasoning?: boolean;
+    catalogLimit?: number;
 }
 interface OrchestratorHandoffArtifact {
     schemaVersion: "snipara.orchestrator.handoff.v1";
@@ -2956,4 +3154,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 };