snipara-companion 3.2.19 → 3.2.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/index.d.ts +1541 -1503
  2. package/dist/index.js +17255 -16966
  3. package/package.json +1 -1
package/dist/index.d.ts CHANGED
@@ -2747,1640 +2747,1678 @@ interface CodingLedgerExportCommandOptions extends CodingLedgerBuildOptions {
2747
2747
  declare function buildCodingIntelligenceLedger(options?: CodingLedgerBuildOptions): CodingIntelligenceLedger;
2748
2748
  declare function codingLedgerExportCommand(options: CodingLedgerExportCommandOptions): Promise<void>;
2749
2749
 
2750
- declare const TEAM_SYNC_STATE_RELATIVE_PATH: string;
2751
- type TeamSyncAttention = "note" | "watch" | "review" | "proof";
2752
- type TeamSyncWorkStatus = "active" | "completed" | "archived";
2753
- interface TeamSyncRecordInput {
2754
- summary: string;
2755
- files?: string[];
2756
- branch?: string;
2757
- actor?: string;
2758
- next?: string;
2759
- attention?: string;
2760
- risk?: string;
2761
- now?: Date;
2762
- }
2763
- interface TeamSyncWorkRecord {
2764
- id: string;
2765
- type: "work";
2766
- summary: string;
2767
- files: string[];
2768
- branch?: string;
2769
- actor?: string;
2770
- status: TeamSyncWorkStatus;
2771
- createdAt: string;
2772
- updatedAt: string;
2773
- completedAt?: string;
2774
- completionReason?: string;
2775
- archivedAt?: string;
2776
- archiveReason?: string;
2777
- }
2778
- interface TeamSyncHandoffRecord {
2779
- id: string;
2780
- type: "handoff";
2781
- summary: string;
2782
- files: string[];
2783
- next?: string;
2784
- attention?: TeamSyncAttention;
2785
- actor?: string;
2786
- createdAt: string;
2787
- }
2788
- interface TeamSyncState {
2789
- schemaVersion: "snipara.team-sync.v1";
2790
- updatedAt: string;
2791
- work: TeamSyncWorkRecord[];
2792
- handoffs: TeamSyncHandoffRecord[];
2793
- }
2794
- interface TeamSyncSummary {
2795
- activeWorkCount: number;
2796
- staleWorkCount: number;
2797
- completedWorkCount: number;
2798
- archivedWorkCount: number;
2799
- handoffCount: number;
2800
- files: string[];
2801
- staleWorkExplanation: TeamSyncStaleWorkExplanation;
2802
- hygieneActions: TeamSyncHygieneAction[];
2803
- latestActiveWork?: TeamSyncWorkRecord;
2804
- latestStaleWork?: TeamSyncWorkRecord;
2805
- latestCompletedWork?: TeamSyncWorkRecord;
2806
- latestArchivedWork?: TeamSyncWorkRecord;
2807
- latestHandoff?: TeamSyncHandoffRecord;
2808
- }
2809
- interface TeamSyncStaleWorkExplanation {
2810
- staleAfterHours: number;
2811
- autoArchiveAfterDays: number;
2812
- activeStaleCount: number;
2813
- autoArchivableCount: number;
2814
- completedIgnoredCount: number;
2815
- archivedIgnoredCount: number;
2816
- latestStaleWorkAgeHours?: number;
2817
- message: string;
2818
- }
2819
- interface TeamSyncHygieneAction {
2820
- kind: "sweep-preview" | "sweep-archive" | "complete-work" | "handoff";
2821
- command: string;
2750
+ declare const COLLABORATION_STATE_RELATIVE_PATH: string;
2751
+ type CollaborationGuardActionKind = "safe_to_ack" | "needs_handoff" | "needs_test" | "needs_package_review" | "blocking_conflict" | "guard_unavailable";
2752
+ interface CollaborationGuardActionCard {
2753
+ kind: CollaborationGuardActionKind;
2754
+ title: string;
2822
2755
  reason: string;
2823
- mutates: boolean;
2824
- }
2825
- interface TeamSyncCommandOptions {
2826
- id?: string;
2827
- summary?: string;
2828
- files?: string[];
2829
- branch?: string;
2830
- actor?: string;
2831
- next?: string;
2832
- attention?: string;
2833
- risk?: string;
2834
- adapterPack?: boolean;
2835
- adapterTarget?: string;
2836
- context?: string[];
2837
- proof?: string[];
2838
- acceptance?: string[];
2839
- conflictPosture?: string;
2840
- since?: string;
2841
- dir?: string;
2842
- includeSessionContext?: boolean;
2843
- emitOrchestratorHandoff?: boolean;
2844
- autoRouteOrchestrator?: boolean;
2845
- orchestratorPolicySource?: string;
2846
- output?: string;
2847
- days?: string;
2848
- dryRun?: boolean;
2849
- json?: boolean;
2756
+ severity: "info" | "watch" | "warning" | "critical";
2757
+ safeToAck: boolean;
2758
+ command?: string;
2759
+ conflictCode?: string;
2760
+ resource?: string;
2850
2761
  }
2851
- interface HostedAttempt<T> {
2762
+ interface HostedAttempt$1<T> {
2852
2763
  status: "skipped" | "ok" | "error";
2853
2764
  data?: T;
2854
2765
  error?: string;
2855
2766
  }
2856
- interface TeamSyncSweepResult {
2857
- action: "sweep";
2767
+ interface WorkflowCollaborationReceipt {
2768
+ workSessionId?: string;
2769
+ hostedSessionStatus: HostedAttempt$1<CollaborationSessionResponse>["status"];
2770
+ hostedClaimStatus?: HostedAttempt$1<CollaborationLeaseResponse>["status"];
2771
+ hostedReleaseStatus?: HostedAttempt$1<Array<{
2772
+ lease: CollaborationLeaseSummary;
2773
+ }>>["status"];
2774
+ hostedError?: string;
2775
+ files: string[];
2776
+ resourceCount: number;
2777
+ leaseCount: number;
2858
2778
  statePath: string;
2859
- dryRun: boolean;
2860
- thresholdDays: number;
2861
- thresholdMs: number;
2862
- archivedCount: number;
2863
- archivedWork: TeamSyncWorkRecord[];
2864
- explanation: TeamSyncSweepExplanation;
2865
- summary: TeamSyncSummary;
2866
- }
2867
- interface TeamSyncSweepExplanation {
2868
- mode: "preview" | "archive";
2869
- candidateCount: number;
2870
- archivedCount: number;
2871
- remainingStaleCount: number;
2872
- message: string;
2873
- }
2874
- type AgenticHandoffAdapterTarget = "codex" | "claude-code" | "cursor" | "orca" | "windsurf" | "custom";
2875
- type AgenticHandoffConflictPosture = "continue" | "wait" | "split_work" | "review_only" | "handoff";
2876
- interface AgenticHandoffAdapterPack {
2877
- version: "snipara.ade_adapter_pack.v1";
2878
- target: {
2879
- id: AgenticHandoffAdapterTarget;
2880
- label: string;
2881
- profile: string;
2882
- instruction: string;
2883
- runtimeControl: "handoff_only";
2884
- };
2885
- contextPack: {
2886
- summary: string;
2887
- files: string[];
2888
- contextRefs: string[];
2889
- workflow?: {
2890
- goal?: string;
2891
- status?: string;
2892
- currentPhaseId?: string;
2893
- currentPhaseTitle?: string;
2894
- };
2895
- resumeCommands: string[];
2896
- constraints: string[];
2897
- };
2898
- conflictPosture: AgenticHandoffConflictPosture;
2899
- proofGates: string[];
2900
- acceptanceCriteria: string[];
2901
- receiptExpectation: {
2902
- required: boolean;
2903
- command: string;
2904
- requiredFields: string[];
2905
- };
2906
- prompt: string;
2907
- caveats: string[];
2779
+ recordedAt: string;
2908
2780
  }
2909
- interface TeamSyncCompletionEvidenceOptions {
2781
+ interface CollaborationCommandOptions {
2910
2782
  summary?: string;
2911
- workflowGoal?: string;
2912
2783
  files?: string[];
2784
+ resources?: string[];
2785
+ actor?: string;
2786
+ actorId?: string;
2787
+ actorType?: string;
2788
+ sessionId?: string;
2789
+ workSessionId?: string;
2790
+ swarmId?: string;
2791
+ client?: string;
2792
+ repository?: string;
2793
+ branch?: string;
2794
+ worktree?: string;
2795
+ action?: string;
2796
+ profile?: string;
2797
+ mode?: string;
2913
2798
  reason?: string;
2914
- now?: Date;
2799
+ ttlSeconds?: string;
2800
+ heartbeatTtlSeconds?: string;
2801
+ intervalSeconds?: string;
2802
+ maxFiles?: string;
2803
+ leaseId?: string;
2804
+ all?: boolean;
2805
+ once?: boolean;
2806
+ autoClaim?: boolean;
2807
+ releaseStale?: boolean;
2808
+ persist?: boolean;
2809
+ enforce?: boolean;
2810
+ ackReviewOnly?: boolean;
2811
+ dir?: string;
2812
+ json?: boolean;
2813
+ verbose?: boolean;
2814
+ }
2815
+ interface CollaborationHooksInstallOptions {
2816
+ dir?: string;
2915
2817
  dryRun?: boolean;
2818
+ json?: boolean;
2916
2819
  }
2917
- interface AgenticHandoffArtifact {
2918
- version: "snipara.agentic_handoff.v1";
2919
- generatedAt: string;
2920
- command: "snipara-companion handoff";
2921
- record: TeamSyncHandoffRecord;
2922
- statePath: string;
2923
- hosted: {
2924
- status: HostedAttempt<TeamSyncHandoffResponse>["status"];
2925
- handoffId?: string;
2926
- error?: string;
2927
- };
2928
- sections: {
2929
- whatChanged: string[];
2930
- verified: string[];
2931
- risky: string[];
2932
- remains: string[];
2933
- whereToResume: string[];
2820
+ interface CollaborationLocalLeaseRecord {
2821
+ id: string;
2822
+ mode: CollaborationLeaseMode;
2823
+ status: CollaborationLeaseStatus;
2824
+ resources: CollaborationResource[];
2825
+ reason?: string;
2826
+ claimedAt?: string;
2827
+ expiresAt?: string | null;
2828
+ workSessionId?: string;
2829
+ }
2830
+ interface CollaborationLocalState {
2831
+ schemaVersion: "snipara.collaboration.v1";
2832
+ updatedAt: string;
2833
+ workSessionId?: string;
2834
+ sessionId?: string;
2835
+ actorId?: string;
2836
+ actorType?: CollaborationActorType;
2837
+ actorLabel?: string;
2838
+ client?: string;
2839
+ repository?: string;
2840
+ branch?: string;
2841
+ worktree?: string;
2842
+ task?: string;
2843
+ files: string[];
2844
+ resources: CollaborationResource[];
2845
+ leases: CollaborationLocalLeaseRecord[];
2846
+ lastGuard?: {
2847
+ decision: CollaborationGuardDecision;
2848
+ severity: string;
2849
+ checkedAt: string;
2850
+ action: string;
2851
+ resources: CollaborationResource[];
2852
+ conflictCount: number;
2934
2853
  };
2935
- suggestedCommands: string[];
2936
- adapter?: AgenticHandoffAdapterPack;
2937
2854
  }
2938
- declare function buildTeamSyncStartWorkRecord(input: TeamSyncRecordInput): TeamSyncWorkRecord;
2939
- declare function buildTeamSyncHandoffRecord(input: TeamSyncRecordInput): TeamSyncHandoffRecord;
2940
- declare function createEmptyTeamSyncState(now?: Date): TeamSyncState;
2941
- declare function buildTeamSyncSummary(state: TeamSyncState, since?: Date, now?: Date): TeamSyncSummary;
2942
- declare function archiveInactiveTeamSyncWork(state: TeamSyncState, options?: {
2943
- now?: Date;
2944
- thresholdMs?: number;
2945
- dryRun?: boolean;
2946
- }): TeamSyncSweepResult["archivedWork"];
2947
- declare function completeTeamSyncWorkFromEvidence(state: TeamSyncState, options?: TeamSyncCompletionEvidenceOptions): TeamSyncWorkRecord[];
2948
- declare function completeTeamSyncStateFromEvidence(rootDir?: string, options?: TeamSyncCompletionEvidenceOptions): TeamSyncWorkRecord[];
2949
- declare function autoArchiveTeamSyncState(rootDir?: string, now?: Date): TeamSyncSweepResult["archivedWork"];
2950
- declare function loadTeamSyncState(rootDir?: string): TeamSyncState;
2951
- declare function saveTeamSyncState(state: TeamSyncState, rootDir?: string): void;
2952
- declare function getTeamSyncStatePath(rootDir?: string): string;
2953
- declare function buildAgenticHandoffMarkdown(artifact: AgenticHandoffArtifact): string;
2954
- declare function teamSyncSweepCommand(options: TeamSyncCommandOptions): Promise<void>;
2955
-
2956
- type SyncDocumentKind = "DOC" | "BINARY";
2957
- type WorkflowMode = "lite" | "standard" | "auto" | "full" | "orchestrate";
2958
- type OnboardFolderMode = "auto" | "business_context" | "code_project" | "mixed";
2959
- type DetectedOnboardFolderMode = "business_context" | "code_project" | "mixed" | "unknown";
2960
- type ManagedWorkflowStatus = "active" | "completed" | "blocked";
2961
- type ManagedWorkflowPhaseStatus = "pending" | "in_progress" | "completed" | "blocked" | "skipped";
2962
- type ReindexKind = "doc" | "code";
2963
- type ReindexMode = "incremental" | "full";
2964
- type ManagedWorkflowPlanSource = "file" | "inline";
2965
- type TaskCommitOutcome = "completed" | "partial" | "blocked" | "abandoned";
2966
- type ManagedWorkflowSchemaVersion = "snipara.workflow.v1" | "snipara.workflow.v2";
2967
- declare const WORKFLOW_STATE_RELATIVE_PATH: string;
2968
- declare const WORKFLOW_PLANS_RELATIVE_DIR: string;
2969
- declare const PRODUCER_LOOP_ARTIFACT_VERSION: "snipara.producer_loop_artifact.v0";
2970
- declare const PRODUCER_LOOP_REPORT_VERSION: "snipara.producer_loop_report.v0";
2971
- declare const PRODUCER_LOOP_RELATIVE_DIR: string;
2972
- type ProducerLoopProducerKind = "workflow_phase_commit" | "workflow_final_commit" | "pr_answer_pack_decision_capture";
2973
- type ProducerLoopSampleReviewStatus = "sample_unreviewed" | "sample_reviewed" | "sample_rejected";
2974
- interface ProducerLoopArtifactWriteResult {
2975
- status: "written" | "error";
2976
- schemaVersion: typeof PRODUCER_LOOP_ARTIFACT_VERSION;
2977
- artifactId?: string;
2978
- path?: string;
2979
- relativePath?: string;
2980
- artifactHash?: string;
2981
- ledgerHash?: string;
2982
- error?: string;
2983
- caveats: string[];
2855
+ interface ResolvedCollaborationContext {
2856
+ rootDir: string;
2857
+ config: RLMConfig;
2858
+ actor: Required<Pick<CollaborationActorPayload, "actorId" | "actorType" | "actorLabel">> & {
2859
+ sessionId?: string;
2860
+ };
2861
+ client: string;
2862
+ branch?: string;
2863
+ repository?: string;
2864
+ worktree?: string;
2984
2865
  }
2985
- interface ProducerLoopArtifactReportSummary {
2986
- artifactId: string;
2987
- generatedAt: string;
2988
- producerKind: ProducerLoopProducerKind;
2989
- workflowId?: string;
2990
- phaseId?: string;
2991
- phaseTitle?: string;
2992
- outcome?: TaskCommitOutcome;
2993
- summary?: string;
2994
- path: string;
2995
- relativePath: string;
2996
- artifactHash: string;
2997
- ledgerHash?: string;
2998
- reasonCodes: string[];
2866
+ declare function createEmptyCollaborationState(now?: Date): CollaborationLocalState;
2867
+ declare function getCollaborationStatePath(rootDir?: string): string;
2868
+ declare function loadCollaborationState(rootDir?: string): CollaborationLocalState;
2869
+ declare function saveCollaborationState(state: CollaborationLocalState, rootDir?: string): void;
2870
+ declare function buildCollaborationActor(options: Pick<CollaborationCommandOptions, "actor" | "actorId" | "actorType" | "sessionId" | "client">, config: RLMConfig): ResolvedCollaborationContext["actor"];
2871
+ declare function normalizeCollaborationFiles(files: string[] | undefined): string[];
2872
+ declare function parseCollaborationResources(values: string[] | undefined): CollaborationResource[];
2873
+ declare function deriveLocalCollaborationResourcesFromFiles(files: string[] | undefined, rootDir?: string, maxFiles?: number): CollaborationResource[];
2874
+ declare function buildCollaborationHooksInstallPlan(options?: CollaborationHooksInstallOptions): Record<string, unknown>;
2875
+ declare function collaborationIdeStatusCommand(options: CollaborationCommandOptions): Promise<void>;
2876
+ declare function buildCollaborationGuardActionCards(evaluation: CollaborationGuardEvaluation | undefined, context?: {
2877
+ profile?: string;
2878
+ enforced?: boolean;
2879
+ ackReviewOnly?: boolean;
2880
+ reviewOnlyAcknowledged?: boolean;
2881
+ }): CollaborationGuardActionCard[];
2882
+ interface HostedGuardPayload {
2999
2883
  files: string[];
3000
- calibrationStatus?: string;
3001
- reviewStatus: ProducerLoopSampleReviewStatus;
3002
- reviewOutcome?: string;
3003
- reviewedAt?: string;
3004
- reviewer?: string;
2884
+ resources: CollaborationResource[];
2885
+ fileCount: number;
2886
+ resourceCount: number;
2887
+ filesTruncated: boolean;
2888
+ resourcesTruncated: boolean;
3005
2889
  }
3006
- interface ProducerLoopReport {
3007
- version: typeof PRODUCER_LOOP_REPORT_VERSION;
3008
- generatedAt: string;
3009
- source: {
3010
- directory: string;
3011
- localOnly: true;
2890
+ declare function buildHostedGuardPayload(files: string[], resources: CollaborationResource[]): HostedGuardPayload;
2891
+ declare function compactHostedGuardResources(resources: CollaborationResource[]): CollaborationResource[];
2892
+ declare function shouldFailCollaborationGuard(input: {
2893
+ hostedStatus: HostedAttempt$1<unknown>["status"];
2894
+ evaluation: CollaborationGuardEvaluation | undefined;
2895
+ enforce: boolean;
2896
+ ackReviewOnly: boolean;
2897
+ }): boolean;
2898
+
2899
+ type RuntimeEnvironment = Record<string, string | undefined>;
2900
+ type ProviderKeySource = "environment" | "env-file";
2901
+ type OrchestratorRecommendationLevel = "suggest" | "confirm" | "auto";
2902
+ type OrchestratorRecommendationReason = "workflow_mode_orchestrate" | "production_validation_intent" | "proof_gate_intent" | "htask_or_swarm_intent" | "multi_agent_intent" | "parallel_worker_intent" | "changed_files_threshold" | "team_sync_collision" | "policy_auto_route";
2903
+ interface OrchestratorRecommendation {
2904
+ level: OrchestratorRecommendationLevel;
2905
+ reasons: OrchestratorRecommendationReason[];
2906
+ score: number;
2907
+ orchestratorRequired: boolean;
2908
+ policySource?: string;
2909
+ }
2910
+ interface OrchestratorRecommendationOptions {
2911
+ changedFilesCount?: number;
2912
+ hasActiveCollisions?: boolean;
2913
+ policyAutoRoute?: boolean;
2914
+ policySource?: string;
2915
+ adaptiveRoutingDryRun?: boolean;
2916
+ }
2917
+ interface RuntimeDetectionReport {
2918
+ cwd: string;
2919
+ workspaceRoot: string | null;
2920
+ companion: {
2921
+ configured: boolean;
2922
+ configPath: string;
3012
2923
  };
3013
- adoption: {
3014
- status: "missing" | "active";
3015
- artifactCount: number;
3016
- producerKinds: ProducerLoopProducerKind[];
3017
- workflowIds: string[];
2924
+ runtime: {
2925
+ cliAvailable: boolean;
2926
+ command?: string;
2927
+ legacyCommand?: boolean;
2928
+ version?: string;
2929
+ cliVersion?: string;
2930
+ installedPackageVersion?: string;
2931
+ versionMismatch?: boolean;
2932
+ mcpConfigured: boolean;
2933
+ mcpConfigPaths: string[];
3018
2934
  };
3019
- artifacts: ProducerLoopArtifactReportSummary[];
3020
- latestArtifact?: ProducerLoopArtifactReportSummary;
3021
- invalidArtifacts: Array<{
3022
- path: string;
3023
- relativePath: string;
3024
- error: string;
3025
- }>;
3026
- reasonCodes: {
3027
- counts: Record<string, number>;
2935
+ orchestrator: {
2936
+ cliAvailable: boolean;
2937
+ command?: string;
2938
+ version?: string;
2939
+ source?: "path" | "workspace_venv";
2940
+ workspacePackageVersion?: string;
2941
+ versionMismatch?: boolean;
3028
2942
  };
3029
- calibration: {
3030
- status: "no_samples" | "insufficient_samples" | "reviewable_sample_set";
3031
- sampleSize: number;
3032
- reviewedSampleSize: number;
3033
- rejectedSampleSize: number;
3034
- unreviewedSampleSize: number;
3035
- minReviewSampleSize: number;
3036
- reviewOutcomes: Record<string, number>;
3037
- hardGateReady: false;
3038
- notes: string[];
2943
+ providerKeys: {
2944
+ openai: boolean;
2945
+ anthropic: boolean;
2946
+ any: boolean;
2947
+ sources: {
2948
+ openai?: ProviderKeySource;
2949
+ anthropic?: ProviderKeySource;
2950
+ };
2951
+ envFilesLoaded: string[];
3039
2952
  };
3040
- recommendedActions: string[];
3041
- caveats: string[];
3042
- }
3043
- type WorkflowPlanPreset = "memory-backend-unification" | "project-intelligence-continuity-layer";
3044
- interface WorkflowPlanScaffoldDocument {
3045
- preset: WorkflowPlanPreset;
3046
- mode: "full";
3047
- goal: string;
3048
- steps: Array<{
3049
- id: string;
3050
- title: string;
3051
- query: string;
3052
- acceptance?: string;
3053
- files?: string[];
3054
- gates?: string[];
3055
- needs_runtime?: boolean;
3056
- }>;
3057
- }
3058
- interface ManagedWorkflowRuntimeCheckpoint {
3059
- summary: string;
3060
- capturedAt: string;
3061
- automationSessionId?: string;
3062
- hostedEventId?: string;
3063
- hostedRecordedAt?: string;
3064
- environment?: string;
3065
- profile?: string;
3066
- bootstrapQuery?: string;
3067
- files?: string[];
3068
- commands?: string[];
3069
- artifacts?: string[];
3070
- contextPackReceipts?: LocalContextPackReceiptPayload[];
3071
- rehydratableState?: Record<string, unknown>;
3072
- }
3073
- interface ManagedWorkflowSandboxRuntimeBinding {
3074
- phaseId: string;
3075
- sessionId: string;
3076
- automationSessionId?: string;
3077
- boundAt: string;
3078
- bootstrapQuery: string;
3079
- environment?: string;
3080
- profile?: string;
3081
- artifacts?: string[];
3082
- lastCheckpoint?: ManagedWorkflowRuntimeCheckpoint;
3083
- }
3084
- interface ManagedWorkflowRuntimeState {
3085
- sandbox?: {
3086
- provider: "snipara-sandbox";
3087
- bindings: ManagedWorkflowSandboxRuntimeBinding[];
2953
+ docker: {
2954
+ available: boolean;
3088
2955
  };
3089
2956
  }
3090
- interface ManagedWorkflowPhase {
2957
+ declare function detectRuntimeEnvironment(cwd?: string, env?: RuntimeEnvironment): RuntimeDetectionReport;
2958
+ declare function shouldSuggestRuntimeForWorkflow(query: string, mode: WorkflowMode): boolean;
2959
+ /**
2960
+ * Recommend whether work should be routed to snipara-orchestrator.
2961
+ *
2962
+ * Scores intent signals from the query and workflow mode (orchestrate mode,
2963
+ * production / proof / htask / multi-agent / parallel patterns) plus contextual
2964
+ * signals (changed-file count, active Team Sync collisions, policy auto-route).
2965
+ * The returned recommendation's level escalates with the accumulated score
2966
+ * (suggest → confirm → auto).
2967
+ *
2968
+ * @returns A recommendation with its reasons, or `null` when no signal fires.
2969
+ */
2970
+ declare function getOrchestratorRecommendation(query: string, mode: WorkflowMode, options?: OrchestratorRecommendationOptions): OrchestratorRecommendation | null;
2971
+ declare function formatOrchestratorRecommendationReason(reason: OrchestratorRecommendationReason): string;
2972
+ declare function shouldSuggestOrchestratorForWorkflow(query: string, mode: WorkflowMode): boolean;
2973
+
2974
+ declare const ORCHESTRATOR_HANDOFF_RELATIVE_PATH: string;
2975
+ interface OrchestratorHandoffWorkflowPhase {
3091
2976
  id: string;
3092
2977
  title: string;
3093
2978
  query: string;
3094
- status: ManagedWorkflowPhaseStatus;
2979
+ status: string;
3095
2980
  acceptance?: string;
3096
- files?: string[];
3097
- gates?: string[];
3098
- needsRuntime?: boolean;
3099
- startedAt?: string;
3100
- completedAt?: string;
3101
- summary?: string;
3102
- outcome?: TaskCommitOutcome;
3103
- }
3104
- interface ManagedWorkflowState {
3105
- schemaVersion: ManagedWorkflowSchemaVersion;
3106
- workflowId: string;
3107
- goal: string;
3108
- status: ManagedWorkflowStatus;
3109
- currentPhaseId?: string;
3110
- planSource: ManagedWorkflowPlanSource;
3111
- planFile?: string;
3112
- createdAt: string;
3113
- updatedAt: string;
3114
- phases: ManagedWorkflowPhase[];
3115
- runtime?: ManagedWorkflowRuntimeState;
3116
- lastCommit?: {
3117
- category: string;
3118
- outcome: TaskCommitOutcome;
3119
- summary: string;
3120
- committedAt: string;
3121
- };
3122
- }
3123
- interface AgenticWorkStatus {
3124
- version: "snipara.agentic_status.v1";
3125
- generatedAt: string;
3126
- branch?: string;
3127
- git: {
3128
- head?: string;
3129
- dirtyFileCount: number;
3130
- statusLines: string[];
3131
- error?: string;
3132
- };
3133
- workflow: {
3134
- id: string;
3135
- goal: string;
3136
- status: ManagedWorkflowStatus;
3137
- currentPhase?: {
3138
- id: string;
3139
- title: string;
3140
- status: ManagedWorkflowPhaseStatus;
3141
- };
3142
- lastPhaseCommit?: {
3143
- phaseId: string;
3144
- title: string;
3145
- summary?: string;
3146
- outcome?: TaskCommitOutcome;
3147
- completedAt?: string;
3148
- };
3149
- resumeCommand: string;
3150
- } | null;
3151
- teamSync: {
3152
- activeWorkCount: number;
3153
- staleWorkCount: number;
3154
- staleWorkExplanation: TeamSyncStaleWorkExplanation;
3155
- archivedWorkCount: number;
3156
- handoffCount: number;
3157
- latestHandoff?: {
3158
- summary: string;
3159
- next?: string;
3160
- attention?: string;
3161
- createdAt: string;
3162
- };
3163
- };
3164
- risks: string[];
3165
- openDecisions: {
3166
- count?: number;
3167
- note: string;
3168
- };
3169
- operationalLoop: {
3170
- status: "clear" | "attention" | "blocked";
3171
- decisionRequestCount: number;
3172
- receiptGapCount: number;
3173
- nextActions: string[];
3174
- receiptActions: string[];
3175
- caveats: string[];
3176
- };
3177
- suggestedNextAction: string;
2981
+ files: string[];
2982
+ gates: string[];
2983
+ needsRuntime: boolean;
3178
2984
  }
3179
- interface AgenticTimelineEvent {
3180
- time: string;
3181
- kind: string;
2985
+ interface OrchestratorHandoffRuntimeSandboxPhase {
2986
+ phaseId: string;
3182
2987
  title: string;
3183
- detail?: string;
3184
- source: ActivityEventSource;
3185
- files?: string[];
2988
+ bootstrapQuery: string;
2989
+ files: string[];
2990
+ artifacts: string[];
2991
+ contextPacks: string[];
2992
+ sessionId: string | null;
2993
+ environment: string | null;
2994
+ profile: string | null;
2995
+ hasCheckpoint: boolean;
2996
+ checkpointSummary: string | null;
2997
+ checkpointCapturedAt: string | null;
3186
2998
  }
3187
- interface AgenticTimeline {
3188
- version: "snipara.agentic_timeline.v1";
3189
- generatedAt: string;
3190
- events: AgenticTimelineEvent[];
3191
- limit: number;
2999
+ interface AdaptiveWorkProfile {
3000
+ taskType: string;
3001
+ risk: string;
3002
+ scope: string[];
3003
+ contextBudget: string;
3004
+ reasoningDepth: string;
3005
+ evidenceRequirements?: string[];
3006
+ preferredProfileStrengths?: string[];
3007
+ notes?: string[];
3192
3008
  }
3193
- interface WorkflowImpactGateCommit {
3194
- sha: string;
3195
- shortSha: string;
3196
- subject: string;
3197
- author?: string;
3198
- authoredAt?: string;
3009
+ interface AdaptiveModelRequirements {
3010
+ workerRole: string;
3011
+ reasoning: string;
3012
+ plannerRetainsReasoning: boolean;
3013
+ speed: string;
3014
+ cost: string;
3015
+ contextBudget: string;
3016
+ capabilities: string[];
3017
+ forbiddenCapabilities: string[];
3018
+ writeScope: string[];
3019
+ structuredOutputRequired?: boolean;
3020
+ preferredEndpointTypes?: string[];
3021
+ allowedEndpointTypes?: string[];
3022
+ catalogLimit?: number;
3023
+ dailyBudgetCents?: number;
3024
+ monthlyBudgetCents?: number;
3025
+ fallback: "main_agent";
3199
3026
  }
3200
- interface WorkflowImpactGatePhase {
3201
- id: string;
3202
- title: string;
3203
- summary?: string;
3204
- outcome?: TaskCommitOutcome;
3205
- completedAt?: string;
3206
- files: string[];
3207
- filesInUnpushedDiff: string[];
3027
+ interface AdaptiveRoutingCostEstimate {
3028
+ currency: "USD";
3029
+ confidence: "low" | "medium" | "high";
3208
3030
  }
3209
- interface WorkflowImpactGateResult {
3210
- version: "snipara.workflow_impact_gate.v1";
3211
- generatedAt: string;
3212
- gate: {
3213
- status: "pass" | "attention";
3214
- reasonCodes: string[];
3215
- };
3216
- repo: {
3217
- root: string;
3218
- branch?: string;
3219
- upstream: string;
3220
- baseSha?: string;
3221
- headSha?: string;
3222
- };
3223
- unpushed: {
3224
- commitCount: number;
3225
- commits: WorkflowImpactGateCommit[];
3226
- changedFiles: string[];
3227
- codeChangedFiles: string[];
3228
- nonCodeChangedFiles: string[];
3229
- };
3230
- dirtyWorkingTree: {
3231
- fileCount: number;
3232
- statusLines: string[];
3233
- files: string[];
3234
- includedInLocalImpact: false;
3235
- };
3236
- workflow: {
3237
- id?: string;
3238
- goal?: string;
3239
- status?: ManagedWorkflowStatus;
3240
- completedPhases: WorkflowImpactGatePhase[];
3241
- changedFilesWithoutPhase: string[];
3242
- phaseFilesOutsideUnpushedDiff: string[];
3243
- };
3244
- localImpact: Record<string, unknown> | null;
3245
- recommendedActions: string[];
3246
- caveats: string[];
3247
- hostedFollowUpCommand?: string;
3031
+ interface AdaptiveRoutingCard {
3032
+ mode: "dry_run";
3033
+ workProfile: AdaptiveWorkProfile;
3034
+ requirements: AdaptiveModelRequirements;
3035
+ recommendedWorkerClass: string;
3036
+ costEstimate: AdaptiveRoutingCostEstimate;
3037
+ humanApprovalRequired: boolean;
3038
+ fallback: "main_agent";
3039
+ rejectedReasons?: Record<string, string[]>;
3040
+ reasons: string[];
3041
+ warnings: string[];
3248
3042
  }
3249
- interface WorkflowPlanScaffoldResult {
3250
- preset: WorkflowPlanPreset;
3251
- goal: string;
3252
- outputPath: string;
3253
- relativeOutputPath: string;
3254
- plan: WorkflowPlanScaffoldDocument;
3043
+ interface AdaptiveRoutingGatewayStatus {
3044
+ source: "hosted_mcp" | "local_orchestrator";
3045
+ success: boolean;
3046
+ resolutionStatus?: string;
3047
+ candidateCount: number;
3048
+ fallback?: string;
3049
+ warnings: string[];
3255
3050
  }
3256
- interface SyncDocumentsManifestOptions {
3257
- metadataDefaults: Record<string, unknown>;
3258
- deleteMissing?: boolean;
3259
- dryRun?: boolean;
3260
- reindex?: boolean;
3261
- reindexKind?: ReindexKind;
3262
- reindexMode?: ReindexMode;
3051
+ interface AdaptiveRoutingRuntimeCatalog {
3052
+ version?: string;
3053
+ source?: string;
3054
+ provider?: string;
3055
+ baseUrl?: string;
3056
+ models?: string[];
3057
+ apiPaths?: Record<string, unknown>;
3058
+ workerEndpoints?: Record<string, Record<string, unknown>>;
3059
+ workerProfiles?: Record<string, Record<string, unknown>>;
3060
+ candidates: Array<Record<string, unknown>>;
3263
3061
  }
3264
- interface CollectedSyncDocuments {
3265
- documents: SyncDocumentInput[];
3266
- manifestOptions: SyncDocumentsManifestOptions;
3062
+ interface AdaptiveRoutingResolution {
3063
+ status?: string;
3064
+ selected?: Record<string, unknown>;
3065
+ policyDecision?: Record<string, unknown>;
3066
+ evaluatedCount?: number;
3067
+ rejectedCount?: number;
3068
+ fallback?: string;
3069
+ reasons?: string[];
3070
+ warnings?: string[];
3071
+ rejectedReasons?: Record<string, string[]>;
3267
3072
  }
3268
- interface SyncDocumentsDryRunItem {
3269
- path: string;
3270
- status: "valid" | "invalid_metadata";
3271
- recommended_action: "none" | "reupload" | "review_source_metadata";
3272
- reasons: string[];
3273
- kind?: SyncDocumentKind;
3274
- format?: string;
3275
- size_bytes: number;
3276
- content_hash: string;
3277
- assetClass?: string;
3278
- usageMode?: string;
3279
- sourceKind?: string;
3073
+ interface AdaptiveWorkRoutingRecommendation {
3074
+ workProfile: AdaptiveWorkProfile;
3075
+ requirements: AdaptiveModelRequirements;
3076
+ routingCard: AdaptiveRoutingCard;
3077
+ gateway?: AdaptiveRoutingGatewayStatus;
3078
+ runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
3079
+ resolution?: AdaptiveRoutingResolution;
3280
3080
  }
3281
- interface SyncDocumentsDryRunSummary {
3282
- dry_run: true;
3283
- remote_diff_available: false;
3284
- total: number;
3285
- would_sync: number;
3286
- invalid_metadata: number;
3287
- stale: number;
3288
- needs_reupload: number;
3289
- needs_metadata_review: number;
3290
- delete_missing: boolean;
3291
- reindex_requested: boolean;
3292
- reindex_kind: ReindexKind;
3293
- reindex_mode: ReindexMode;
3294
- created: null;
3295
- updated: null;
3296
- unchanged: null;
3297
- missing_from_manifest: null;
3298
- note: string;
3299
- documents: SyncDocumentsDryRunItem[];
3300
- }
3301
- interface OnboardFolderScannedFile {
3302
- path: string;
3303
- size_bytes: number;
3304
- supported: boolean;
3305
- kind?: SyncDocumentKind;
3306
- format?: string;
3307
- }
3308
- interface OnboardFolderClassification {
3309
- mode: DetectedOnboardFolderMode;
3310
- detected_mode: DetectedOnboardFolderMode;
3311
- confidence: number;
3312
- code_score: number;
3313
- business_score: number;
3314
- signals: {
3315
- code: string[];
3316
- business: string[];
3317
- };
3081
+ interface AdaptiveWorkRoutingOptions {
3082
+ query: string;
3083
+ mode?: string;
3084
+ changedFiles?: string[];
3085
+ preferredEndpointTypes?: string[];
3086
+ allowedEndpointTypes?: string[];
3087
+ workerRole?: string;
3088
+ plannerRetainsReasoning?: boolean;
3089
+ preferredProfileStrengths?: string[];
3090
+ structuredOutputRequired?: boolean;
3091
+ catalogLimit?: number;
3092
+ dailyBudgetCents?: number;
3093
+ monthlyBudgetCents?: number;
3318
3094
  }
3319
- interface OnboardFolderManifest {
3320
- schemaVersion: "snipara.onboard-folder.v1";
3095
+ interface OrchestratorHandoffArtifact {
3096
+ schemaVersion: "snipara.orchestrator.handoff.v1";
3321
3097
  source: {
3322
- root: string;
3323
- sourceKind: string;
3324
- sourceProvider: string;
3325
- sourceUri?: string;
3326
- snapshotAt: string;
3327
- recursive: boolean;
3098
+ client: "snipara-companion";
3099
+ command: string;
3100
+ generatedAt: string;
3328
3101
  };
3329
- classification: OnboardFolderClassification;
3330
- summary: {
3331
- total_files: number;
3332
- supported_documents: number;
3333
- ignored_files: number;
3334
- unsupported_business_files: number;
3102
+ workflow: {
3103
+ mode: string;
3104
+ workflowId: string | null;
3105
+ currentPhaseId: string | null;
3106
+ phases: OrchestratorHandoffWorkflowPhase[];
3335
3107
  };
3336
- warnings: string[];
3337
- ignored: OnboardFolderScannedFile[];
3338
- sync: {
3339
- dryRun: boolean;
3340
- reindex: boolean;
3341
- reindexKind: ReindexKind;
3342
- reindexMode: ReindexMode;
3343
- deleteMissing: boolean;
3344
- metadata: Record<string, unknown>;
3345
- documents: SyncDocumentInput[];
3108
+ runtime: {
3109
+ sandbox: {
3110
+ provider: "snipara-sandbox";
3111
+ phases: OrchestratorHandoffRuntimeSandboxPhase[];
3112
+ } | null;
3346
3113
  };
3347
- dryRun: SyncDocumentsDryRunSummary;
3348
- }
3349
- declare function getPlanStepDisplayTitle(step: unknown, index?: number): string;
3350
- interface PlanQualityReport {
3351
- valid: boolean;
3352
- issues: string[];
3353
- warnings: string[];
3354
- stepCount: number;
3355
- actions: string[];
3356
- planId?: string;
3357
- }
3358
- interface WorkflowTokenBudgetReport {
3359
- requested_max_tokens: number;
3360
- allocations: {
3361
- critical_memory_tokens: number;
3362
- session_context_tokens: number;
3363
- context_query_tokens: number;
3364
- shared_context_tokens: number;
3365
- plan_tokens: number;
3114
+ routing: {
3115
+ level: OrchestratorRecommendation["level"];
3116
+ reasons: OrchestratorRecommendation["reasons"];
3117
+ policySource: string | null;
3118
+ workProfile?: AdaptiveWorkProfile;
3119
+ requirements?: AdaptiveModelRequirements;
3120
+ routingCard?: AdaptiveRoutingCard;
3121
+ gateway?: AdaptiveRoutingGatewayStatus;
3122
+ runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
3123
+ resolution?: AdaptiveRoutingResolution;
3366
3124
  };
3367
- estimated_max_tokens: number;
3368
- include_session_context: boolean;
3369
- explicit: {
3370
- max_critical_tokens: boolean;
3371
- max_context_tokens: boolean;
3125
+ task: {
3126
+ title: string;
3127
+ query: string;
3128
+ summary: string;
3372
3129
  };
3373
- warnings: string[];
3374
- }
3375
- interface SessionBootstrapQualityReport {
3376
- warnings: string[];
3377
- counts: {
3378
- critical_memories: number;
3379
- session_context_memories: number;
3380
- low_confidence_memories: number;
3381
- stale_memories: number;
3382
- test_memories: number;
3130
+ repo: {
3131
+ root: string;
3132
+ branch: string | null;
3133
+ headSha: string | null;
3134
+ changedFiles: string[];
3135
+ };
3136
+ coordination: {
3137
+ swarmId: string | null;
3138
+ claimScope: {
3139
+ files: string[];
3140
+ symbols: string[];
3141
+ };
3142
+ htask: {
3143
+ featureTitle: string | null;
3144
+ workstreams: string[];
3145
+ };
3146
+ };
3147
+ validation: {
3148
+ requiresProofGate: boolean;
3149
+ requiresDriftCheck: boolean;
3150
+ liveChecks: string[];
3151
+ requiredEvidence: Array<{
3152
+ type: string;
3153
+ description: string;
3154
+ }>;
3155
+ };
3156
+ memory: {
3157
+ decisionIds: string[];
3158
+ contextRefs: string[];
3159
+ resumeSummary: string | null;
3383
3160
  };
3384
- total_tokens?: number;
3385
- oldest_memory_age_days?: number;
3386
3161
  }
3387
- interface SessionBootstrapBrief {
3388
- entries: SessionMemoryEntry[];
3389
- availableCount: number;
3390
- hiddenCount: number;
3391
- estimatedTokens: number;
3392
- budgetTokens: number;
3162
+ interface OrchestratorHandoffOptions {
3163
+ sourceCommand: string;
3164
+ recommendation: OrchestratorRecommendation;
3165
+ query: string;
3166
+ summary: string;
3167
+ title?: string;
3168
+ mode?: string;
3169
+ rootDir?: string;
3170
+ changedFiles?: string[];
3171
+ contextRefs?: string[];
3172
+ decisionIds?: string[];
3173
+ resumeSummary?: string;
3174
+ featureTitle?: string;
3175
+ workstreams?: string[];
3176
+ adaptiveRouting?: AdaptiveWorkRoutingRecommendation | null;
3393
3177
  }
3394
- interface GeneratedWorkflowPlanDocument {
3395
- mode: "full";
3396
- goal: string;
3397
- source: "snipara_plan";
3398
- plan_id?: string;
3399
- generatedAt: string;
3400
- steps: Array<{
3401
- id: string;
3402
- title: string;
3403
- query: string;
3404
- acceptance?: string;
3405
- files?: string[];
3406
- needs_runtime?: boolean;
3407
- }>;
3178
+ interface WrittenOrchestratorHandoff {
3179
+ handoff: OrchestratorHandoffArtifact;
3180
+ path: string;
3181
+ relativePath: string;
3182
+ command: string;
3408
3183
  }
3409
- declare function resolveFullWorkflowTokenBudget(options: {
3410
- maxTokens?: number;
3411
- includeSessionContext?: boolean;
3412
- includeSharedContext?: boolean;
3413
- maxCriticalTokens?: number;
3414
- maxContextTokens?: number;
3415
- }): WorkflowTokenBudgetReport;
3416
- declare function validatePlanResult(plan: unknown, options?: {
3417
- query?: string;
3184
+ declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
3185
+ declare function buildAdaptiveWorkRoutingRecommendation(options: AdaptiveWorkRoutingOptions): AdaptiveWorkRoutingRecommendation;
3186
+ declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
3187
+
3188
+ interface JournalCheckpointPayload {
3189
+ action: string;
3190
+ summary: string;
3191
+ outcome?: string;
3192
+ workflowId?: string;
3193
+ phaseId?: string;
3194
+ phaseTitle?: string;
3195
+ branch?: string;
3196
+ actor?: string;
3197
+ next?: string;
3198
+ attention?: string;
3199
+ files?: string[];
3418
3200
  cwd?: string;
3419
- }): PlanQualityReport;
3420
- declare function buildSessionBootstrapBrief(result: SessionMemoriesResult, options: {
3421
- includeSessionContext: boolean;
3422
- maxTokens?: number;
3423
- maxEntries?: number;
3201
+ }
3202
+ declare function buildJournalCheckpointEntry(payload: JournalCheckpointPayload): {
3203
+ text: string;
3204
+ tags: string[];
3205
+ };
3206
+
3207
+ declare const TEAM_SYNC_STATE_RELATIVE_PATH: string;
3208
+ type TeamSyncAttention = "note" | "watch" | "review" | "proof";
3209
+ type TeamSyncWorkStatus = "active" | "completed" | "archived";
3210
+ interface TeamSyncRecordInput {
3211
+ summary: string;
3212
+ files?: string[];
3213
+ branch?: string;
3214
+ actor?: string;
3215
+ next?: string;
3216
+ attention?: string;
3217
+ risk?: string;
3424
3218
  now?: Date;
3425
- }): SessionBootstrapBrief;
3426
- declare function buildSessionBootstrapQuality(result: SessionMemoriesResult, options?: {
3427
- expectedMaxTokens?: number;
3428
- now?: Date;
3429
- }): SessionBootstrapQualityReport;
3430
- declare function buildGeneratedWorkflowPlanDocument(plan: Record<string, unknown>, fallbackGoal: string): GeneratedWorkflowPlanDocument;
3431
- declare function normalizeWorkflowPlanInput(input: unknown, fallbackGoal: string): ManagedWorkflowPhase[];
3432
- declare function buildWorkflowPlanScaffold(preset: WorkflowPlanPreset, options?: {
3433
- goal?: string;
3434
- outputPath?: string;
3435
- cwd?: string;
3436
- }): WorkflowPlanScaffoldResult;
3437
- declare function writeProducerLoopArtifact(options: {
3438
- kind: ProducerLoopProducerKind;
3439
- command: "workflow phase-commit" | "workflow final-commit";
3440
- state?: ManagedWorkflowState;
3441
- phase?: ManagedWorkflowPhase;
3442
- category: string;
3443
- outcome: TaskCommitOutcome;
3219
+ }
3220
+ interface TeamSyncWorkRecord {
3221
+ id: string;
3222
+ type: "work";
3444
3223
  summary: string;
3445
- files?: string[];
3446
- journalAttempted: boolean;
3447
- teamSyncCompletionAttempted: boolean;
3448
- }): ProducerLoopArtifactWriteResult;
3449
- declare function buildProducerLoopReport(options?: {
3450
- cwd?: string;
3451
- minReviewSampleSize?: number;
3452
- }): ProducerLoopReport;
3453
- declare function buildWorkflowPhaseCommitSummary(args: {
3454
- workflowId: string;
3455
- phase: Pick<ManagedWorkflowPhase, "id" | "title">;
3224
+ files: string[];
3225
+ branch?: string;
3226
+ actor?: string;
3227
+ status: TeamSyncWorkStatus;
3228
+ createdAt: string;
3229
+ updatedAt: string;
3230
+ completedAt?: string;
3231
+ completionReason?: string;
3232
+ archivedAt?: string;
3233
+ archiveReason?: string;
3234
+ }
3235
+ interface TeamSyncHandoffRecord {
3236
+ id: string;
3237
+ type: "handoff";
3456
3238
  summary: string;
3457
- }): string;
3458
- declare function resolveAutoWorkflowMode(query: string): Exclude<WorkflowMode, "auto">;
3459
- /**
3460
- * Compute the impact gate for committed-but-unpushed workflow phases.
3461
- *
3462
- * Compares `upstream..HEAD`, separates unpushed code changes from non-code and
3463
- * dirty working-tree files, runs local code-overlay impact on the committed
3464
- * code files, and maps the result back to completed workflow phases. Surfaces
3465
- * reason codes such as `dirty_working_tree_not_included` and phase files that
3466
- * fall outside the unpushed diff, so a phase is not treated as verified on
3467
- * stale or partial evidence.
3468
- *
3469
- * @returns A `WorkflowImpactGateResult` with changed files, local impact,
3470
- * matched phases, and reason codes.
3471
- */
3472
- declare function buildWorkflowImpactGate(options?: {
3473
- cwd?: string;
3474
- base?: string;
3475
- maxFiles?: number;
3476
- }): WorkflowImpactGateResult;
3477
- declare function collectSyncDocuments(options: {
3478
- file?: string;
3479
- dir?: string;
3480
- prefix?: string;
3481
- recursive?: boolean;
3482
- }): SyncDocumentInput[];
3483
- declare function collectSyncDocumentsInput(options: {
3484
- file?: string;
3485
- dir?: string;
3486
- prefix?: string;
3487
- recursive?: boolean;
3488
- }): CollectedSyncDocuments;
3489
- interface OnboardFolderOptions {
3490
- dir: string;
3491
- recursive?: boolean;
3492
- mode?: OnboardFolderMode;
3493
- prefix?: string;
3494
- usageMode?: string;
3495
- sourceKind?: string;
3496
- sourceProvider?: string;
3497
- sourceUri?: string;
3498
- clientId?: string;
3499
- snapshotAt?: string;
3500
- deleteMissing?: boolean;
3501
- reindex?: boolean;
3502
- reindexKind?: ReindexKind;
3503
- reindexMode?: ReindexMode;
3239
+ files: string[];
3240
+ next?: string;
3241
+ attention?: TeamSyncAttention;
3242
+ actor?: string;
3243
+ createdAt: string;
3504
3244
  }
3505
- declare function buildOnboardFolderManifest(options: OnboardFolderOptions): OnboardFolderManifest;
3506
- declare function buildSyncDocumentsDryRun(documents: SyncDocumentInput[], options?: {
3507
- deleteMissing?: boolean;
3508
- reindex?: boolean;
3509
- reindexKind?: ReindexKind;
3510
- reindexMode?: ReindexMode;
3511
- now?: Date;
3512
- }): SyncDocumentsDryRunSummary;
3513
- declare function buildAgenticWorkStatus(cwd?: string): AgenticWorkStatus;
3514
- declare function buildAgenticTimeline(options?: {
3515
- limit?: number;
3516
- cwd?: string;
3517
- }): AgenticTimeline;
3518
-
3519
- type LocalSourceProvider = "local_folder";
3520
- type LocalSourceFileKind = "DOC" | "BINARY" | "CODE" | "CONFIG" | "OTHER";
3521
- type LocalSourceSkippedReason = "ignored" | "too_large" | "read_error";
3522
- type LocalSourceReindexKind = "doc" | "code";
3523
- type LocalSourceReindexMode = "incremental" | "full";
3524
- interface LocalSourceFile {
3525
- path: string;
3526
- kind: LocalSourceFileKind;
3527
- format: string | null;
3528
- sizeBytes: number;
3529
- modifiedAt: string;
3530
- sha256: string;
3245
+ interface TeamSyncState {
3246
+ schemaVersion: "snipara.team-sync.v1";
3247
+ updatedAt: string;
3248
+ work: TeamSyncWorkRecord[];
3249
+ handoffs: TeamSyncHandoffRecord[];
3531
3250
  }
3532
- interface LocalSourceSkippedFile {
3533
- path: string;
3534
- reason: LocalSourceSkippedReason;
3535
- sizeBytes?: number;
3251
+ interface TeamSyncSummary {
3252
+ activeWorkCount: number;
3253
+ staleWorkCount: number;
3254
+ completedWorkCount: number;
3255
+ archivedWorkCount: number;
3256
+ handoffCount: number;
3257
+ files: string[];
3258
+ staleWorkExplanation: TeamSyncStaleWorkExplanation;
3259
+ hygieneActions: TeamSyncHygieneAction[];
3260
+ latestActiveWork?: TeamSyncWorkRecord;
3261
+ latestStaleWork?: TeamSyncWorkRecord;
3262
+ latestCompletedWork?: TeamSyncWorkRecord;
3263
+ latestArchivedWork?: TeamSyncWorkRecord;
3264
+ latestHandoff?: TeamSyncHandoffRecord;
3536
3265
  }
3537
- interface LocalSourceSummary {
3538
- totalFiles: number;
3539
- totalBytes: number;
3540
- byKind: Record<LocalSourceFileKind, number>;
3541
- skipped: number;
3266
+ interface TeamSyncStaleWorkExplanation {
3267
+ staleAfterHours: number;
3268
+ autoArchiveAfterDays: number;
3269
+ activeStaleCount: number;
3270
+ autoArchivableCount: number;
3271
+ completedIgnoredCount: number;
3272
+ archivedIgnoredCount: number;
3273
+ latestStaleWorkAgeHours?: number;
3274
+ message: string;
3542
3275
  }
3543
- interface LocalSourceSnapshot {
3544
- version: "snipara.local_source_snapshot.v1";
3545
- generatedAt: string;
3546
- root: string;
3547
- provider: LocalSourceProvider;
3548
- revision: string;
3549
- recursive: boolean;
3550
- maxFiles: number;
3551
- maxFileBytes: number;
3552
- summary: LocalSourceSummary;
3553
- files: LocalSourceFile[];
3554
- skipped: {
3555
- total: number;
3556
- byReason: Record<LocalSourceSkippedReason, number>;
3557
- samples: LocalSourceSkippedFile[];
3558
- };
3559
- warnings: string[];
3276
+ interface TeamSyncHygieneAction {
3277
+ kind: "sweep-preview" | "sweep-archive" | "complete-work" | "handoff";
3278
+ command: string;
3279
+ reason: string;
3280
+ mutates: boolean;
3560
3281
  }
3561
- interface LocalSourceSnapshotOptions {
3282
+ interface TeamSyncCommandOptions {
3283
+ id?: string;
3284
+ summary?: string;
3285
+ files?: string[];
3286
+ branch?: string;
3287
+ actor?: string;
3288
+ next?: string;
3289
+ attention?: string;
3290
+ risk?: string;
3291
+ adapterPack?: boolean;
3292
+ adapterTarget?: string;
3293
+ context?: string[];
3294
+ proof?: string[];
3295
+ acceptance?: string[];
3296
+ conflictPosture?: string;
3297
+ since?: string;
3562
3298
  dir?: string;
3563
- recursive?: boolean;
3564
- maxFiles?: number;
3565
- maxFileBytes?: number;
3299
+ includeSessionContext?: boolean;
3300
+ emitOrchestratorHandoff?: boolean;
3301
+ autoRouteOrchestrator?: boolean;
3302
+ orchestratorPolicySource?: string;
3303
+ output?: string;
3304
+ days?: string;
3305
+ dryRun?: boolean;
3306
+ json?: boolean;
3566
3307
  }
3567
- interface LocalSourceComparison {
3568
- added: string[];
3569
- modified: string[];
3570
- deleted: string[];
3571
- unchanged: number;
3308
+ interface HostedAttempt<T> {
3309
+ status: "skipped" | "ok" | "error";
3310
+ data?: T;
3311
+ error?: string;
3572
3312
  }
3573
- interface LocalSourceStatusResult {
3574
- root: string;
3575
- snapshotPath: string;
3576
- previous: LocalSourceSnapshot | null;
3577
- current: LocalSourceSnapshot;
3578
- comparison: LocalSourceComparison;
3313
+ interface TeamSyncSweepResult {
3314
+ action: "sweep";
3315
+ statePath: string;
3316
+ dryRun: boolean;
3317
+ thresholdDays: number;
3318
+ thresholdMs: number;
3319
+ archivedCount: number;
3320
+ archivedWork: TeamSyncWorkRecord[];
3321
+ explanation: TeamSyncSweepExplanation;
3322
+ summary: TeamSyncSummary;
3579
3323
  }
3580
- interface LocalSourceSyncOptions extends LocalSourceSnapshotOptions {
3581
- prefix?: string;
3582
- mode?: OnboardFolderMode;
3583
- deleteMissing?: boolean;
3584
- apply?: boolean;
3585
- reindex?: boolean;
3586
- reindexKind?: LocalSourceReindexKind;
3587
- reindexMode?: LocalSourceReindexMode;
3588
- includeGraph?: boolean;
3589
- json?: boolean;
3324
+ interface TeamSyncSweepExplanation {
3325
+ mode: "preview" | "archive";
3326
+ candidateCount: number;
3327
+ archivedCount: number;
3328
+ remainingStaleCount: number;
3329
+ message: string;
3590
3330
  }
3591
- interface LocalSourceSyncResult {
3592
- root: string;
3593
- snapshotPath: string;
3594
- snapshot: LocalSourceSnapshot;
3595
- comparison: LocalSourceComparison;
3596
- documents: {
3597
- onboarding: Pick<OnboardFolderManifest, "source" | "classification" | "summary" | "warnings">;
3598
- dryRun: OnboardFolderManifest["dryRun"];
3331
+ type AgenticHandoffAdapterTarget = "codex" | "claude-code" | "cursor" | "orca" | "windsurf" | "custom";
3332
+ type AgenticHandoffConflictPosture = "continue" | "wait" | "split_work" | "review_only" | "handoff";
3333
+ interface AgenticHandoffAdapterPack {
3334
+ version: "snipara.ade_adapter_pack.v1";
3335
+ target: {
3336
+ id: AgenticHandoffAdapterTarget;
3337
+ label: string;
3338
+ profile: string;
3339
+ instruction: string;
3340
+ runtimeControl: "handoff_only";
3599
3341
  };
3600
- codeOverlay: {
3601
- cachePath: string;
3602
- summary: LocalCodeOverlaySummary;
3342
+ contextPack: {
3343
+ summary: string;
3344
+ files: string[];
3345
+ contextRefs: string[];
3346
+ workflow?: {
3347
+ goal?: string;
3348
+ status?: string;
3349
+ currentPhaseId?: string;
3350
+ currentPhaseTitle?: string;
3351
+ };
3352
+ resumeCommands: string[];
3353
+ constraints: string[];
3603
3354
  };
3604
- apply: null | {
3605
- sync: Record<string, unknown>;
3606
- reindex?: Record<string, unknown>;
3355
+ conflictPosture: AgenticHandoffConflictPosture;
3356
+ proofGates: string[];
3357
+ acceptanceCriteria: string[];
3358
+ receiptExpectation: {
3359
+ required: boolean;
3360
+ command: string;
3361
+ requiredFields: string[];
3607
3362
  };
3608
- warnings: string[];
3609
- }
3610
- declare function getLocalSourceSnapshotPath(cwd?: string): string;
3611
- declare function buildLocalSourceSnapshot(options?: LocalSourceSnapshotOptions): LocalSourceSnapshot;
3612
- declare function writeLocalSourceSnapshot(snapshot: LocalSourceSnapshot): string;
3613
- declare function readLocalSourceSnapshot(cwd?: string): LocalSourceSnapshot | null;
3614
- declare function compareLocalSourceSnapshots(previous: LocalSourceSnapshot | null, current: LocalSourceSnapshot): LocalSourceComparison;
3615
- declare function buildLocalSourceStatus(options?: LocalSourceSnapshotOptions): LocalSourceStatusResult;
3616
- declare function buildLocalSourceSyncResult(options?: LocalSourceSyncOptions): Promise<LocalSourceSyncResult>;
3617
-
3618
- interface LocalWorkerDeclaration {
3619
- id: string;
3620
- workerRole: string;
3621
- endpointType: "local";
3622
- provider: string;
3623
- baseUrl: string;
3624
- command?: string;
3625
- model?: string;
3626
- preferModel?: string;
3627
- capabilities: string[];
3628
- reasoning: "low" | "medium" | "high";
3629
- writeScope: string[];
3630
- createdAt: string;
3631
- updatedAt: string;
3363
+ prompt: string;
3364
+ caveats: string[];
3632
3365
  }
3633
- interface LocalWorkersConfig {
3634
- schemaVersion: "snipara.local_workers.v1";
3635
- updatedAt: string;
3636
- defaultWorkerId: string;
3637
- workers: LocalWorkerDeclaration[];
3366
+ interface TeamSyncCompletionEvidenceOptions {
3367
+ summary?: string;
3368
+ workflowGoal?: string;
3369
+ files?: string[];
3370
+ reason?: string;
3371
+ now?: Date;
3372
+ dryRun?: boolean;
3638
3373
  }
3639
- interface LocalWorkerRoutingDefaults {
3640
- worker: LocalWorkerDeclaration;
3641
- routeLocalWorkers: true;
3642
- routingWorkerRole: string;
3643
- routingLocalBaseUrl: string;
3644
- routingLocalModel?: string;
3645
- routingLocalPreferModel?: string;
3646
- routingLocalProvider: string;
3647
- routingPreferredEndpoints: string[];
3648
- routingAllowedEndpoints: string[];
3649
- plannerRetainsReasoning: true;
3374
+ interface AgenticHandoffArtifact {
3375
+ version: "snipara.agentic_handoff.v1";
3376
+ generatedAt: string;
3377
+ command: "snipara-companion handoff";
3378
+ record: TeamSyncHandoffRecord;
3379
+ statePath: string;
3380
+ hosted: {
3381
+ status: HostedAttempt<TeamSyncHandoffResponse>["status"];
3382
+ handoffId?: string;
3383
+ error?: string;
3384
+ };
3385
+ sections: {
3386
+ whatChanged: string[];
3387
+ verified: string[];
3388
+ risky: string[];
3389
+ remains: string[];
3390
+ whereToResume: string[];
3391
+ };
3392
+ suggestedCommands: string[];
3393
+ adapter?: AgenticHandoffAdapterPack;
3650
3394
  }
3651
- interface LocalWorkerAddOptions {
3652
- id?: string;
3653
- role?: string;
3654
- provider?: string;
3655
- baseUrl?: string;
3656
- model?: string;
3657
- preferModel?: string;
3658
- capabilities?: string[];
3659
- writeScope?: string[];
3660
- contextWindow?: number;
3661
- reasoning?: "low" | "medium" | "high";
3662
- default?: boolean;
3663
- json?: boolean;
3664
- transport?: "openai_http" | "cli";
3665
- command?: string;
3395
+ declare function buildTeamSyncStartWorkRecord(input: TeamSyncRecordInput): TeamSyncWorkRecord;
3396
+ declare function buildTeamSyncHandoffRecord(input: TeamSyncRecordInput): TeamSyncHandoffRecord;
3397
+ declare function createEmptyTeamSyncState(now?: Date): TeamSyncState;
3398
+ declare function buildTeamSyncSummary(state: TeamSyncState, since?: Date, now?: Date): TeamSyncSummary;
3399
+ declare function archiveInactiveTeamSyncWork(state: TeamSyncState, options?: {
3400
+ now?: Date;
3401
+ thresholdMs?: number;
3402
+ dryRun?: boolean;
3403
+ }): TeamSyncSweepResult["archivedWork"];
3404
+ declare function completeTeamSyncWorkFromEvidence(state: TeamSyncState, options?: TeamSyncCompletionEvidenceOptions): TeamSyncWorkRecord[];
3405
+ declare function completeTeamSyncStateFromEvidence(rootDir?: string, options?: TeamSyncCompletionEvidenceOptions): TeamSyncWorkRecord[];
3406
+ declare function autoArchiveTeamSyncState(rootDir?: string, now?: Date): TeamSyncSweepResult["archivedWork"];
3407
+ declare function loadTeamSyncState(rootDir?: string): TeamSyncState;
3408
+ declare function saveTeamSyncState(state: TeamSyncState, rootDir?: string): void;
3409
+ declare function getTeamSyncStatePath(rootDir?: string): string;
3410
+ declare function buildAgenticHandoffMarkdown(artifact: AgenticHandoffArtifact): string;
3411
+ declare function teamSyncSweepCommand(options: TeamSyncCommandOptions): Promise<void>;
3412
+
3413
+ type SyncDocumentKind = "DOC" | "BINARY";
3414
+ type WorkflowMode = "lite" | "standard" | "auto" | "full" | "orchestrate";
3415
+ type OnboardFolderMode = "auto" | "business_context" | "code_project" | "mixed";
3416
+ type DetectedOnboardFolderMode = "business_context" | "code_project" | "mixed" | "unknown";
3417
+ type ManagedWorkflowStatus = "active" | "completed" | "blocked";
3418
+ type ManagedWorkflowPhaseStatus = "pending" | "in_progress" | "completed" | "blocked" | "skipped";
3419
+ type ReindexKind = "doc" | "code";
3420
+ type ReindexMode = "incremental" | "full";
3421
+ type ManagedWorkflowPlanSource = "file" | "inline";
3422
+ type TaskCommitOutcome = "completed" | "partial" | "blocked" | "abandoned";
3423
+ type ManagedWorkflowSchemaVersion = "snipara.workflow.v1" | "snipara.workflow.v2";
3424
+ declare const WORKFLOW_STATE_RELATIVE_PATH: string;
3425
+ declare const WORKFLOW_PLANS_RELATIVE_DIR: string;
3426
+ declare const PRODUCER_LOOP_ARTIFACT_VERSION: "snipara.producer_loop_artifact.v0";
3427
+ declare const PRODUCER_LOOP_REPORT_VERSION: "snipara.producer_loop_report.v0";
3428
+ declare const PRODUCER_LOOP_RELATIVE_DIR: string;
3429
+ type ProducerLoopProducerKind = "workflow_phase_commit" | "workflow_final_commit" | "pr_answer_pack_decision_capture";
3430
+ type ProducerLoopSampleReviewStatus = "sample_unreviewed" | "sample_reviewed" | "sample_rejected";
3431
+ interface ProducerLoopArtifactWriteResult {
3432
+ status: "written" | "error";
3433
+ schemaVersion: typeof PRODUCER_LOOP_ARTIFACT_VERSION;
3434
+ artifactId?: string;
3435
+ path?: string;
3436
+ relativePath?: string;
3437
+ artifactHash?: string;
3438
+ ledgerHash?: string;
3439
+ error?: string;
3440
+ caveats: string[];
3666
3441
  }
3667
- interface LocalWorkerStatusOptions {
3668
- json?: boolean;
3442
+ interface ProducerLoopArtifactReportSummary {
3443
+ artifactId: string;
3444
+ generatedAt: string;
3445
+ producerKind: ProducerLoopProducerKind;
3446
+ workflowId?: string;
3447
+ phaseId?: string;
3448
+ phaseTitle?: string;
3449
+ outcome?: TaskCommitOutcome;
3450
+ summary?: string;
3451
+ path: string;
3452
+ relativePath: string;
3453
+ artifactHash: string;
3454
+ ledgerHash?: string;
3455
+ reasonCodes: string[];
3456
+ files: string[];
3457
+ calibrationStatus?: string;
3458
+ reviewStatus: ProducerLoopSampleReviewStatus;
3459
+ reviewOutcome?: string;
3460
+ reviewedAt?: string;
3461
+ reviewer?: string;
3669
3462
  }
3670
- interface LocalWorkerListOptions {
3671
- json?: boolean;
3463
+ interface ProducerLoopReport {
3464
+ version: typeof PRODUCER_LOOP_REPORT_VERSION;
3465
+ generatedAt: string;
3466
+ source: {
3467
+ directory: string;
3468
+ localOnly: true;
3469
+ };
3470
+ adoption: {
3471
+ status: "missing" | "active";
3472
+ artifactCount: number;
3473
+ producerKinds: ProducerLoopProducerKind[];
3474
+ workflowIds: string[];
3475
+ };
3476
+ artifacts: ProducerLoopArtifactReportSummary[];
3477
+ latestArtifact?: ProducerLoopArtifactReportSummary;
3478
+ invalidArtifacts: Array<{
3479
+ path: string;
3480
+ relativePath: string;
3481
+ error: string;
3482
+ }>;
3483
+ reasonCodes: {
3484
+ counts: Record<string, number>;
3485
+ };
3486
+ calibration: {
3487
+ status: "no_samples" | "insufficient_samples" | "reviewable_sample_set";
3488
+ sampleSize: number;
3489
+ reviewedSampleSize: number;
3490
+ rejectedSampleSize: number;
3491
+ unreviewedSampleSize: number;
3492
+ minReviewSampleSize: number;
3493
+ reviewOutcomes: Record<string, number>;
3494
+ hardGateReady: false;
3495
+ notes: string[];
3496
+ };
3497
+ recommendedActions: string[];
3498
+ caveats: string[];
3672
3499
  }
3673
- interface LocalWorkerRemoveOptions {
3674
- id: string;
3675
- json?: boolean;
3500
+ type WorkflowPlanPreset = "memory-backend-unification" | "project-intelligence-continuity-layer";
3501
+ interface WorkflowPlanScaffoldDocument {
3502
+ preset: WorkflowPlanPreset;
3503
+ mode: "full";
3504
+ goal: string;
3505
+ steps: Array<{
3506
+ id: string;
3507
+ title: string;
3508
+ query: string;
3509
+ acceptance?: string;
3510
+ files?: string[];
3511
+ gates?: string[];
3512
+ needs_runtime?: boolean;
3513
+ }>;
3676
3514
  }
3677
- interface LocalWorkerProbeOptions {
3678
- baseUrl?: string;
3679
- provider?: string;
3680
- model?: string;
3681
- preferModel?: string;
3682
- role?: string;
3683
- workerId?: string;
3684
- capabilities?: string[];
3685
- writeScope?: string[];
3686
- reasoning?: "low" | "medium" | "high";
3687
- contextWindow?: number;
3688
- json?: boolean;
3515
+ interface ManagedWorkflowRuntimeCheckpoint {
3516
+ summary: string;
3517
+ capturedAt: string;
3518
+ automationSessionId?: string;
3519
+ hostedEventId?: string;
3520
+ hostedRecordedAt?: string;
3521
+ environment?: string;
3522
+ profile?: string;
3523
+ bootstrapQuery?: string;
3524
+ files?: string[];
3525
+ commands?: string[];
3526
+ artifacts?: string[];
3527
+ contextPackReceipts?: LocalContextPackReceiptPayload[];
3528
+ rehydratableState?: Record<string, unknown>;
3689
3529
  }
3690
- declare function workersLocalAddCommand(options: LocalWorkerAddOptions): void;
3691
- declare function workersLocalStatusCommand(options?: LocalWorkerStatusOptions): void;
3692
- declare function workersLocalListCommand(options?: LocalWorkerListOptions): void;
3693
- declare function workersLocalRemoveCommand(options: LocalWorkerRemoveOptions): void;
3694
- declare function workersLocalProbePrintCommand(options: LocalWorkerProbeOptions): void;
3695
- declare function addLocalWorker(options: LocalWorkerAddOptions): {
3696
- worker: LocalWorkerDeclaration;
3697
- config: LocalWorkersConfig;
3698
- workerConfigPath: string;
3699
- policyPath: string;
3700
- };
3701
- declare function resolveLocalWorkerRoutingDefaults(options?: {
3702
- workerId?: string;
3703
- workerRole?: string;
3704
- }): LocalWorkerRoutingDefaults | null;
3705
- declare function readLocalWorkersConfig(): LocalWorkersConfig | null;
3706
-
3707
- interface ControlledWorkerExecuteOptions {
3708
- task: string;
3709
- workerId?: string;
3710
- workerRole?: string;
3711
- endpointType?: "local" | "cloud" | "self_hosted" | "unknown";
3712
- mode?: ControlledWorkerExecutionMode;
3713
- command?: string;
3714
- execute?: boolean;
3715
- approvalReceipt?: string;
3716
- outcomeReceipt?: string;
3717
- writeScope?: string[];
3718
- acceptance?: string[];
3719
- proof?: string[];
3720
- output?: string;
3721
- projectId?: string;
3722
- unifiedOutput?: string;
3723
- dir?: string;
3724
- json?: boolean;
3530
+ interface ManagedWorkflowSandboxRuntimeBinding {
3531
+ phaseId: string;
3532
+ sessionId: string;
3533
+ automationSessionId?: string;
3534
+ boundAt: string;
3535
+ bootstrapQuery: string;
3536
+ environment?: string;
3537
+ profile?: string;
3538
+ artifacts?: string[];
3539
+ lastCheckpoint?: ManagedWorkflowRuntimeCheckpoint;
3725
3540
  }
3726
- interface ControlledWorkerExecuteResult {
3727
- executed: boolean;
3728
- blocked: boolean;
3729
- receiptPath: string;
3730
- unifiedReceiptPath: string | null;
3731
- receipt: ControlledWorkerExecutionReceipt;
3732
- unifiedReceipt: UnifiedReceiptEnvelope<ControlledWorkerExecutionReceipt> | null;
3541
+ interface ManagedWorkflowRuntimeState {
3542
+ sandbox?: {
3543
+ provider: "snipara-sandbox";
3544
+ bindings: ManagedWorkflowSandboxRuntimeBinding[];
3545
+ };
3733
3546
  }
3734
- declare function controlledWorkerExecuteCommand(options: ControlledWorkerExecuteOptions): ControlledWorkerExecuteResult;
3735
-
3736
- declare const MANIFEST_VERSION = "snipara.references.v1";
3737
- type ReferenceStatus = "allowed" | "pending" | "denied" | "unsupported";
3738
- interface ReferenceOccurrence {
3739
- file: string;
3740
- line: number;
3741
- label?: string;
3547
+ type ManagedWorkflowCoordinationMode = "standard" | "full" | "orchestrate";
3548
+ interface ManagedWorkflowCoordinationState {
3549
+ mode: ManagedWorkflowCoordinationMode;
3550
+ autoPublish: boolean;
3551
+ startedAt?: string;
3552
+ lastUpdatedAt?: string;
3553
+ workSessionId?: string;
3554
+ startReceipt?: WorkflowCollaborationReceipt;
3555
+ teamSyncReceipt?: Record<string, unknown>;
3556
+ releaseReceipt?: WorkflowCollaborationReceipt;
3742
3557
  }
3743
- interface ReferenceManifestItem {
3558
+ interface ManagedWorkflowPhase {
3744
3559
  id: string;
3745
- url: string;
3746
- normalizedUrl: string;
3747
- domain: string;
3748
- status: ReferenceStatus;
3749
- reason: string;
3750
- discoveredAt: string;
3751
- occurrences: ReferenceOccurrence[];
3752
- latestSnapshotPath?: string;
3753
- latestFetchStatus?: number;
3754
- latestFetchAt?: string;
3755
- latestContentHash?: string;
3756
- latestError?: string;
3560
+ title: string;
3561
+ query: string;
3562
+ status: ManagedWorkflowPhaseStatus;
3563
+ acceptance?: string;
3564
+ files?: string[];
3565
+ gates?: string[];
3566
+ needsRuntime?: boolean;
3567
+ startedAt?: string;
3568
+ completedAt?: string;
3569
+ summary?: string;
3570
+ outcome?: TaskCommitOutcome;
3757
3571
  }
3758
- interface ReferenceManifest {
3759
- version: typeof MANIFEST_VERSION;
3760
- generatedAt: string;
3761
- root: string;
3762
- allowDomains: string[];
3763
- denyDomains: string[];
3764
- items: ReferenceManifestItem[];
3572
+ interface ManagedWorkflowState {
3573
+ schemaVersion: ManagedWorkflowSchemaVersion;
3574
+ workflowId: string;
3575
+ goal: string;
3576
+ status: ManagedWorkflowStatus;
3577
+ currentPhaseId?: string;
3578
+ planSource: ManagedWorkflowPlanSource;
3579
+ planFile?: string;
3580
+ createdAt: string;
3581
+ updatedAt: string;
3582
+ phases: ManagedWorkflowPhase[];
3583
+ runtime?: ManagedWorkflowRuntimeState;
3584
+ coordination?: ManagedWorkflowCoordinationState;
3585
+ lastCommit?: {
3586
+ category: string;
3587
+ outcome: TaskCommitOutcome;
3588
+ summary: string;
3589
+ committedAt: string;
3590
+ };
3765
3591
  }
3766
- interface ScanReferencesOptions {
3767
- root?: string;
3768
- output?: string;
3769
- allowDomain?: string[];
3770
- denyDomain?: string[];
3771
- extensions?: string[];
3772
- maxFiles?: number;
3773
- json?: boolean;
3592
+ interface AgenticWorkStatus {
3593
+ version: "snipara.agentic_status.v1";
3594
+ generatedAt: string;
3595
+ branch?: string;
3596
+ git: {
3597
+ head?: string;
3598
+ dirtyFileCount: number;
3599
+ statusLines: string[];
3600
+ error?: string;
3601
+ };
3602
+ workflow: {
3603
+ id: string;
3604
+ goal: string;
3605
+ status: ManagedWorkflowStatus;
3606
+ currentPhase?: {
3607
+ id: string;
3608
+ title: string;
3609
+ status: ManagedWorkflowPhaseStatus;
3610
+ };
3611
+ lastPhaseCommit?: {
3612
+ phaseId: string;
3613
+ title: string;
3614
+ summary?: string;
3615
+ outcome?: TaskCommitOutcome;
3616
+ completedAt?: string;
3617
+ };
3618
+ resumeCommand: string;
3619
+ } | null;
3620
+ teamSync: {
3621
+ activeWorkCount: number;
3622
+ staleWorkCount: number;
3623
+ staleWorkExplanation: TeamSyncStaleWorkExplanation;
3624
+ archivedWorkCount: number;
3625
+ handoffCount: number;
3626
+ latestHandoff?: {
3627
+ summary: string;
3628
+ next?: string;
3629
+ attention?: string;
3630
+ createdAt: string;
3631
+ };
3632
+ };
3633
+ risks: string[];
3634
+ openDecisions: {
3635
+ count?: number;
3636
+ note: string;
3637
+ };
3638
+ operationalLoop: {
3639
+ status: "clear" | "attention" | "blocked";
3640
+ decisionRequestCount: number;
3641
+ receiptGapCount: number;
3642
+ nextActions: string[];
3643
+ receiptActions: string[];
3644
+ caveats: string[];
3645
+ };
3646
+ suggestedNextAction: string;
3774
3647
  }
3775
- interface IngestReferencesOptions {
3776
- manifest?: string;
3777
- outputDir?: string;
3778
- allowDomain?: string[];
3779
- ids?: string[];
3780
- max?: number;
3781
- timeoutMs?: number;
3782
- maxBytes?: number;
3783
- destinationPrefix?: string;
3784
- upload?: boolean;
3785
- reindex?: boolean;
3786
- dryRun?: boolean;
3787
- json?: boolean;
3648
+ interface AgenticTimelineEvent {
3649
+ time: string;
3650
+ kind: string;
3651
+ title: string;
3652
+ detail?: string;
3653
+ source: ActivityEventSource;
3654
+ files?: string[];
3788
3655
  }
3789
- interface ScanSummary {
3790
- manifest: ReferenceManifest;
3791
- outputPath: string;
3792
- scannedFiles: number;
3793
- foundUrls: number;
3794
- allowed: number;
3795
- pending: number;
3796
- denied: number;
3797
- unsupported: number;
3656
+ interface AgenticTimeline {
3657
+ version: "snipara.agentic_timeline.v1";
3658
+ generatedAt: string;
3659
+ events: AgenticTimelineEvent[];
3660
+ limit: number;
3798
3661
  }
3799
- interface IngestSummary {
3800
- manifestPath: string;
3801
- selected: number;
3802
- fetched: number;
3803
- uploaded: number;
3804
- failed: number;
3805
- dryRun: boolean;
3806
- snapshots: Array<{
3807
- id: string;
3808
- url: string;
3809
- snapshotPath?: string;
3810
- destinationPath?: string;
3811
- status?: number;
3812
- uploaded?: boolean;
3813
- error?: string;
3814
- }>;
3662
+ interface WorkflowImpactGateCommit {
3663
+ sha: string;
3664
+ shortSha: string;
3665
+ subject: string;
3666
+ author?: string;
3667
+ authoredAt?: string;
3815
3668
  }
3816
- declare function scanReferences(options?: ScanReferencesOptions): ScanSummary;
3817
- declare function ingestReferences(options?: IngestReferencesOptions): Promise<IngestSummary>;
3818
- declare function referencesScanCommand(options: ScanReferencesOptions): Promise<void>;
3819
- declare function referencesIngestCommand(options: IngestReferencesOptions): Promise<void>;
3820
-
3821
- declare const POLICY_LEDGER_SYNC_REPORT_VERSION: "snipara.workflow_policy_ledger_sync.v0";
3822
- interface PolicyLedgerSyncSummary {
3823
- total: number;
3824
- pendingRequests: number;
3825
- resolvedDecisions: number;
3826
- applyReceipts: number;
3827
- policyDrafts: number;
3669
+ interface WorkflowImpactGatePhase {
3670
+ id: string;
3671
+ title: string;
3672
+ summary?: string;
3673
+ outcome?: TaskCommitOutcome;
3674
+ completedAt?: string;
3675
+ files: string[];
3676
+ filesInUnpushedDiff: string[];
3828
3677
  }
3829
- interface PolicyLedgerSyncReport {
3830
- version: typeof POLICY_LEDGER_SYNC_REPORT_VERSION;
3678
+ interface WorkflowImpactGateResult {
3679
+ version: "snipara.workflow_impact_gate.v1";
3831
3680
  generatedAt: string;
3832
- dryRun: boolean;
3833
- summary: PolicyLedgerSyncSummary;
3834
- artifacts: ProjectPolicyLedgerSyncArtifactInput[];
3835
- hosted?: Record<string, unknown>;
3681
+ gate: {
3682
+ status: "pass" | "attention";
3683
+ reasonCodes: string[];
3684
+ };
3685
+ repo: {
3686
+ root: string;
3687
+ branch?: string;
3688
+ upstream: string;
3689
+ baseSha?: string;
3690
+ headSha?: string;
3691
+ };
3692
+ unpushed: {
3693
+ commitCount: number;
3694
+ commits: WorkflowImpactGateCommit[];
3695
+ changedFiles: string[];
3696
+ codeChangedFiles: string[];
3697
+ nonCodeChangedFiles: string[];
3698
+ };
3699
+ dirtyWorkingTree: {
3700
+ fileCount: number;
3701
+ statusLines: string[];
3702
+ files: string[];
3703
+ includedInLocalImpact: false;
3704
+ };
3705
+ workflow: {
3706
+ id?: string;
3707
+ goal?: string;
3708
+ status?: ManagedWorkflowStatus;
3709
+ completedPhases: WorkflowImpactGatePhase[];
3710
+ changedFilesWithoutPhase: string[];
3711
+ phaseFilesOutsideUnpushedDiff: string[];
3712
+ };
3713
+ localImpact: Record<string, unknown> | null;
3714
+ recommendedActions: string[];
3836
3715
  caveats: string[];
3716
+ hostedFollowUpCommand?: string;
3837
3717
  }
3838
- declare function buildPolicyLedgerSyncReport(options?: {
3839
- cwd?: string;
3840
- dryRun?: boolean;
3841
- }): PolicyLedgerSyncReport;
3842
- declare function workflowSyncPolicyLedgerCommand(options: {
3843
- dryRun?: boolean;
3844
- json?: boolean;
3845
- }): Promise<void>;
3846
- declare function collectPolicyLedgerSyncArtifacts(cwd?: string): ProjectPolicyLedgerSyncArtifactInput[];
3847
-
3848
- type CacheStrategy = "exact" | "nearby" | "warm";
3849
- interface QueryCacheScope {
3850
- cwd?: string;
3851
- projectId?: string;
3852
- sessionId?: string;
3853
- }
3854
- interface QueryCacheLookup {
3855
- query: string;
3856
- maxTokens: number;
3857
- }
3858
- interface QueryCacheHit {
3859
- strategy: CacheStrategy;
3860
- result: ContextQueryResult;
3861
- sourceQuery: string;
3862
- similarity?: number;
3718
+ interface WorkflowPlanScaffoldResult {
3719
+ preset: WorkflowPlanPreset;
3720
+ goal: string;
3721
+ outputPath: string;
3722
+ relativeOutputPath: string;
3723
+ plan: WorkflowPlanScaffoldDocument;
3863
3724
  }
3864
- interface WarmSnapshotResult {
3865
- storedEntries: number;
3866
- fileName?: string;
3725
+ interface SyncDocumentsManifestOptions {
3726
+ metadataDefaults: Record<string, unknown>;
3727
+ deleteMissing?: boolean;
3728
+ dryRun?: boolean;
3729
+ reindex?: boolean;
3730
+ reindexKind?: ReindexKind;
3731
+ reindexMode?: ReindexMode;
3867
3732
  }
3868
- declare class LocalQueryCache {
3869
- private readonly scope;
3870
- private readonly ttlMs;
3871
- private readonly warmTtlMs;
3872
- private readonly maxEntries;
3873
- private readonly maxBytes;
3874
- constructor(scope?: QueryCacheScope);
3875
- lookup(options: QueryCacheLookup): QueryCacheHit | null;
3876
- save(options: QueryCacheLookup, result: ContextQueryResult): void;
3877
- storeWarmSnapshot(result: SessionMemoriesResult): WarmSnapshotResult;
3878
- clear(): number;
3879
- private loadIndex;
3880
- private persistIndex;
3881
- private pruneIndex;
3882
- private readEntry;
3883
- private findNearbyEntry;
3884
- private lookupWarmSnapshot;
3733
+ interface CollectedSyncDocuments {
3734
+ documents: SyncDocumentInput[];
3735
+ manifestOptions: SyncDocumentsManifestOptions;
3885
3736
  }
3886
- declare function createLocalQueryCache(scope?: QueryCacheScope): LocalQueryCache;
3887
-
3888
- declare const AUTOMATION_MANIFEST_RELATIVE_PATH = ".snipara/automations/manifest.json";
3889
- type AutomationFileState = "create" | "update" | "unchanged" | "conflict";
3890
- interface AutomationManifestFile {
3737
+ interface SyncDocumentsDryRunItem {
3891
3738
  path: string;
3892
- sha256: string;
3739
+ status: "valid" | "invalid_metadata";
3740
+ recommended_action: "none" | "reupload" | "review_source_metadata";
3741
+ reasons: string[];
3742
+ kind?: SyncDocumentKind;
3743
+ format?: string;
3744
+ size_bytes: number;
3745
+ content_hash: string;
3746
+ assetClass?: string;
3747
+ usageMode?: string;
3748
+ sourceKind?: string;
3893
3749
  }
3894
- interface AutomationManifest {
3895
- version: number;
3896
- client: string;
3897
- projectId?: string;
3898
- apiUrl?: string;
3899
- installedAt: string;
3900
- files: AutomationManifestFile[];
3750
+ interface SyncDocumentsDryRunSummary {
3751
+ dry_run: true;
3752
+ remote_diff_available: false;
3753
+ total: number;
3754
+ would_sync: number;
3755
+ invalid_metadata: number;
3756
+ stale: number;
3757
+ needs_reupload: number;
3758
+ needs_metadata_review: number;
3759
+ delete_missing: boolean;
3760
+ reindex_requested: boolean;
3761
+ reindex_kind: ReindexKind;
3762
+ reindex_mode: ReindexMode;
3763
+ created: null;
3764
+ updated: null;
3765
+ unchanged: null;
3766
+ missing_from_manifest: null;
3767
+ note: string;
3768
+ documents: SyncDocumentsDryRunItem[];
3901
3769
  }
3902
- interface AutomationFilePlan {
3770
+ interface OnboardFolderScannedFile {
3903
3771
  path: string;
3904
- targetPath: string;
3905
- state: AutomationFileState;
3906
- reason: string;
3907
- currentSha256?: string;
3908
- previousSha256?: string;
3909
- nextSha256: string;
3910
- writeContent?: string;
3911
- }
3912
- interface AutomationInstallResult {
3913
- manifest: AutomationManifest;
3914
- plan: AutomationFilePlan[];
3915
- written: number;
3916
- unchanged: number;
3917
- dryRun: boolean;
3772
+ size_bytes: number;
3773
+ supported: boolean;
3774
+ kind?: SyncDocumentKind;
3775
+ format?: string;
3918
3776
  }
3919
- interface AutomationStatusResult {
3920
- manifest: AutomationManifest | null;
3921
- files: Array<{
3922
- path: string;
3923
- targetPath: string;
3924
- state: "up-to-date" | "modified" | "missing";
3925
- expectedSha256: string;
3926
- currentSha256?: string;
3927
- }>;
3777
+ interface OnboardFolderClassification {
3778
+ mode: DetectedOnboardFolderMode;
3779
+ detected_mode: DetectedOnboardFolderMode;
3780
+ confidence: number;
3781
+ code_score: number;
3782
+ business_score: number;
3783
+ signals: {
3784
+ code: string[];
3785
+ business: string[];
3786
+ };
3928
3787
  }
3929
- declare class AutomationInstallConflictError extends Error {
3930
- conflicts: AutomationFilePlan[];
3931
- constructor(conflicts: AutomationFilePlan[]);
3788
+ interface OnboardFolderManifest {
3789
+ schemaVersion: "snipara.onboard-folder.v1";
3790
+ source: {
3791
+ root: string;
3792
+ sourceKind: string;
3793
+ sourceProvider: string;
3794
+ sourceUri?: string;
3795
+ snapshotAt: string;
3796
+ recursive: boolean;
3797
+ };
3798
+ classification: OnboardFolderClassification;
3799
+ summary: {
3800
+ total_files: number;
3801
+ supported_documents: number;
3802
+ ignored_files: number;
3803
+ unsupported_business_files: number;
3804
+ };
3805
+ warnings: string[];
3806
+ ignored: OnboardFolderScannedFile[];
3807
+ sync: {
3808
+ dryRun: boolean;
3809
+ reindex: boolean;
3810
+ reindexKind: ReindexKind;
3811
+ reindexMode: ReindexMode;
3812
+ deleteMissing: boolean;
3813
+ metadata: Record<string, unknown>;
3814
+ documents: SyncDocumentInput[];
3815
+ };
3816
+ dryRun: SyncDocumentsDryRunSummary;
3932
3817
  }
3933
- declare class AutomationUnsupportedHookBundleError extends Error {
3934
- client: string;
3935
- files: string[];
3936
- constructor(client: string, files: string[]);
3818
+ declare function getPlanStepDisplayTitle(step: unknown, index?: number): string;
3819
+ interface PlanQualityReport {
3820
+ valid: boolean;
3821
+ issues: string[];
3822
+ warnings: string[];
3823
+ stepCount: number;
3824
+ actions: string[];
3825
+ planId?: string;
3937
3826
  }
3938
- declare function getAutomationManifestPath(projectDir?: string): string;
3939
- declare function loadAutomationManifest(projectDir?: string): AutomationManifest | null;
3940
- declare function buildAutomationInstallPlan(args: {
3941
- projectDir: string;
3942
- bundle: AutomationConfigBundle;
3943
- manifest?: AutomationManifest | null;
3944
- force?: boolean;
3945
- }): AutomationFilePlan[];
3946
- declare function installAutomationBundle(args: {
3947
- client: string;
3948
- projectDir?: string;
3949
- bundle?: AutomationConfigBundle;
3950
- force?: boolean;
3951
- dryRun?: boolean;
3952
- }): Promise<AutomationInstallResult>;
3953
- declare function getAutomationStatus(projectDir?: string): AutomationStatusResult;
3954
-
3955
- declare const COLLABORATION_STATE_RELATIVE_PATH: string;
3956
- type CollaborationGuardActionKind = "safe_to_ack" | "needs_handoff" | "needs_test" | "needs_package_review" | "blocking_conflict" | "guard_unavailable";
3957
- interface CollaborationGuardActionCard {
3958
- kind: CollaborationGuardActionKind;
3959
- title: string;
3960
- reason: string;
3961
- severity: "info" | "watch" | "warning" | "critical";
3962
- safeToAck: boolean;
3963
- command?: string;
3964
- conflictCode?: string;
3965
- resource?: string;
3827
+ interface WorkflowTokenBudgetReport {
3828
+ requested_max_tokens: number;
3829
+ allocations: {
3830
+ critical_memory_tokens: number;
3831
+ session_context_tokens: number;
3832
+ context_query_tokens: number;
3833
+ shared_context_tokens: number;
3834
+ plan_tokens: number;
3835
+ };
3836
+ estimated_max_tokens: number;
3837
+ include_session_context: boolean;
3838
+ explicit: {
3839
+ max_critical_tokens: boolean;
3840
+ max_context_tokens: boolean;
3841
+ };
3842
+ warnings: string[];
3966
3843
  }
3967
- interface CollaborationCommandOptions {
3968
- summary?: string;
3844
+ interface SessionBootstrapQualityReport {
3845
+ warnings: string[];
3846
+ counts: {
3847
+ critical_memories: number;
3848
+ session_context_memories: number;
3849
+ low_confidence_memories: number;
3850
+ stale_memories: number;
3851
+ test_memories: number;
3852
+ };
3853
+ total_tokens?: number;
3854
+ oldest_memory_age_days?: number;
3855
+ }
3856
+ interface SessionBootstrapBrief {
3857
+ entries: SessionMemoryEntry[];
3858
+ availableCount: number;
3859
+ hiddenCount: number;
3860
+ estimatedTokens: number;
3861
+ budgetTokens: number;
3862
+ }
3863
+ interface GeneratedWorkflowPlanDocument {
3864
+ mode: "full";
3865
+ goal: string;
3866
+ source: "snipara_plan";
3867
+ plan_id?: string;
3868
+ generatedAt: string;
3869
+ steps: Array<{
3870
+ id: string;
3871
+ title: string;
3872
+ query: string;
3873
+ acceptance?: string;
3874
+ files?: string[];
3875
+ needs_runtime?: boolean;
3876
+ }>;
3877
+ }
3878
+ declare function resolveFullWorkflowTokenBudget(options: {
3879
+ maxTokens?: number;
3880
+ includeSessionContext?: boolean;
3881
+ includeSharedContext?: boolean;
3882
+ maxCriticalTokens?: number;
3883
+ maxContextTokens?: number;
3884
+ }): WorkflowTokenBudgetReport;
3885
+ declare function validatePlanResult(plan: unknown, options?: {
3886
+ query?: string;
3887
+ cwd?: string;
3888
+ }): PlanQualityReport;
3889
+ declare function buildSessionBootstrapBrief(result: SessionMemoriesResult, options: {
3890
+ includeSessionContext: boolean;
3891
+ maxTokens?: number;
3892
+ maxEntries?: number;
3893
+ now?: Date;
3894
+ }): SessionBootstrapBrief;
3895
+ declare function buildSessionBootstrapQuality(result: SessionMemoriesResult, options?: {
3896
+ expectedMaxTokens?: number;
3897
+ now?: Date;
3898
+ }): SessionBootstrapQualityReport;
3899
+ declare function buildGeneratedWorkflowPlanDocument(plan: Record<string, unknown>, fallbackGoal: string): GeneratedWorkflowPlanDocument;
3900
+ declare function normalizeWorkflowPlanInput(input: unknown, fallbackGoal: string): ManagedWorkflowPhase[];
3901
+ declare function buildWorkflowPlanScaffold(preset: WorkflowPlanPreset, options?: {
3902
+ goal?: string;
3903
+ outputPath?: string;
3904
+ cwd?: string;
3905
+ }): WorkflowPlanScaffoldResult;
3906
+ declare function writeProducerLoopArtifact(options: {
3907
+ kind: ProducerLoopProducerKind;
3908
+ command: "workflow phase-commit" | "workflow final-commit";
3909
+ state?: ManagedWorkflowState;
3910
+ phase?: ManagedWorkflowPhase;
3911
+ category: string;
3912
+ outcome: TaskCommitOutcome;
3913
+ summary: string;
3969
3914
  files?: string[];
3970
- resources?: string[];
3971
- actor?: string;
3972
- actorId?: string;
3973
- actorType?: string;
3974
- sessionId?: string;
3975
- workSessionId?: string;
3976
- swarmId?: string;
3977
- client?: string;
3978
- repository?: string;
3979
- branch?: string;
3980
- worktree?: string;
3981
- action?: string;
3982
- profile?: string;
3983
- mode?: string;
3984
- reason?: string;
3985
- ttlSeconds?: string;
3986
- heartbeatTtlSeconds?: string;
3987
- intervalSeconds?: string;
3988
- maxFiles?: string;
3989
- leaseId?: string;
3990
- all?: boolean;
3991
- once?: boolean;
3992
- autoClaim?: boolean;
3993
- releaseStale?: boolean;
3994
- persist?: boolean;
3995
- enforce?: boolean;
3996
- ackReviewOnly?: boolean;
3915
+ journalAttempted: boolean;
3916
+ teamSyncCompletionAttempted: boolean;
3917
+ }): ProducerLoopArtifactWriteResult;
3918
+ declare function buildProducerLoopReport(options?: {
3919
+ cwd?: string;
3920
+ minReviewSampleSize?: number;
3921
+ }): ProducerLoopReport;
3922
+ declare function buildWorkflowPhaseCommitSummary(args: {
3923
+ workflowId: string;
3924
+ phase: Pick<ManagedWorkflowPhase, "id" | "title">;
3925
+ summary: string;
3926
+ }): string;
3927
+ declare function resolveAutoWorkflowMode(query: string): Exclude<WorkflowMode, "auto">;
3928
+ /**
3929
+ * Compute the impact gate for committed-but-unpushed workflow phases.
3930
+ *
3931
+ * Compares `upstream..HEAD`, separates unpushed code changes from non-code and
3932
+ * dirty working-tree files, runs local code-overlay impact on the committed
3933
+ * code files, and maps the result back to completed workflow phases. Surfaces
3934
+ * reason codes such as `dirty_working_tree_not_included` and phase files that
3935
+ * fall outside the unpushed diff, so a phase is not treated as verified on
3936
+ * stale or partial evidence.
3937
+ *
3938
+ * @returns A `WorkflowImpactGateResult` with changed files, local impact,
3939
+ * matched phases, and reason codes.
3940
+ */
3941
+ declare function buildWorkflowImpactGate(options?: {
3942
+ cwd?: string;
3943
+ base?: string;
3944
+ maxFiles?: number;
3945
+ }): WorkflowImpactGateResult;
3946
+ declare function collectSyncDocuments(options: {
3947
+ file?: string;
3997
3948
  dir?: string;
3998
- json?: boolean;
3999
- verbose?: boolean;
3949
+ prefix?: string;
3950
+ recursive?: boolean;
3951
+ }): SyncDocumentInput[];
3952
+ declare function collectSyncDocumentsInput(options: {
3953
+ file?: string;
3954
+ dir?: string;
3955
+ prefix?: string;
3956
+ recursive?: boolean;
3957
+ }): CollectedSyncDocuments;
3958
+ interface OnboardFolderOptions {
3959
+ dir: string;
3960
+ recursive?: boolean;
3961
+ mode?: OnboardFolderMode;
3962
+ prefix?: string;
3963
+ usageMode?: string;
3964
+ sourceKind?: string;
3965
+ sourceProvider?: string;
3966
+ sourceUri?: string;
3967
+ clientId?: string;
3968
+ snapshotAt?: string;
3969
+ deleteMissing?: boolean;
3970
+ reindex?: boolean;
3971
+ reindexKind?: ReindexKind;
3972
+ reindexMode?: ReindexMode;
4000
3973
  }
4001
- interface CollaborationHooksInstallOptions {
3974
+ declare function buildOnboardFolderManifest(options: OnboardFolderOptions): OnboardFolderManifest;
3975
+ declare function buildSyncDocumentsDryRun(documents: SyncDocumentInput[], options?: {
3976
+ deleteMissing?: boolean;
3977
+ reindex?: boolean;
3978
+ reindexKind?: ReindexKind;
3979
+ reindexMode?: ReindexMode;
3980
+ now?: Date;
3981
+ }): SyncDocumentsDryRunSummary;
3982
+ declare function buildAgenticWorkStatus(cwd?: string): AgenticWorkStatus;
3983
+ declare function buildAgenticTimeline(options?: {
3984
+ limit?: number;
3985
+ cwd?: string;
3986
+ }): AgenticTimeline;
3987
+
3988
+ type LocalSourceProvider = "local_folder";
3989
+ type LocalSourceFileKind = "DOC" | "BINARY" | "CODE" | "CONFIG" | "OTHER";
3990
+ type LocalSourceSkippedReason = "ignored" | "too_large" | "read_error";
3991
+ type LocalSourceReindexKind = "doc" | "code";
3992
+ type LocalSourceReindexMode = "incremental" | "full";
3993
+ interface LocalSourceFile {
3994
+ path: string;
3995
+ kind: LocalSourceFileKind;
3996
+ format: string | null;
3997
+ sizeBytes: number;
3998
+ modifiedAt: string;
3999
+ sha256: string;
4000
+ }
4001
+ interface LocalSourceSkippedFile {
4002
+ path: string;
4003
+ reason: LocalSourceSkippedReason;
4004
+ sizeBytes?: number;
4005
+ }
4006
+ interface LocalSourceSummary {
4007
+ totalFiles: number;
4008
+ totalBytes: number;
4009
+ byKind: Record<LocalSourceFileKind, number>;
4010
+ skipped: number;
4011
+ }
4012
+ interface LocalSourceSnapshot {
4013
+ version: "snipara.local_source_snapshot.v1";
4014
+ generatedAt: string;
4015
+ root: string;
4016
+ provider: LocalSourceProvider;
4017
+ revision: string;
4018
+ recursive: boolean;
4019
+ maxFiles: number;
4020
+ maxFileBytes: number;
4021
+ summary: LocalSourceSummary;
4022
+ files: LocalSourceFile[];
4023
+ skipped: {
4024
+ total: number;
4025
+ byReason: Record<LocalSourceSkippedReason, number>;
4026
+ samples: LocalSourceSkippedFile[];
4027
+ };
4028
+ warnings: string[];
4029
+ }
4030
+ interface LocalSourceSnapshotOptions {
4002
4031
  dir?: string;
4003
- dryRun?: boolean;
4032
+ recursive?: boolean;
4033
+ maxFiles?: number;
4034
+ maxFileBytes?: number;
4035
+ }
4036
+ interface LocalSourceComparison {
4037
+ added: string[];
4038
+ modified: string[];
4039
+ deleted: string[];
4040
+ unchanged: number;
4041
+ }
4042
+ interface LocalSourceStatusResult {
4043
+ root: string;
4044
+ snapshotPath: string;
4045
+ previous: LocalSourceSnapshot | null;
4046
+ current: LocalSourceSnapshot;
4047
+ comparison: LocalSourceComparison;
4048
+ }
4049
+ interface LocalSourceSyncOptions extends LocalSourceSnapshotOptions {
4050
+ prefix?: string;
4051
+ mode?: OnboardFolderMode;
4052
+ deleteMissing?: boolean;
4053
+ apply?: boolean;
4054
+ reindex?: boolean;
4055
+ reindexKind?: LocalSourceReindexKind;
4056
+ reindexMode?: LocalSourceReindexMode;
4057
+ includeGraph?: boolean;
4004
4058
  json?: boolean;
4005
4059
  }
4006
- interface CollaborationLocalLeaseRecord {
4060
+ interface LocalSourceSyncResult {
4061
+ root: string;
4062
+ snapshotPath: string;
4063
+ snapshot: LocalSourceSnapshot;
4064
+ comparison: LocalSourceComparison;
4065
+ documents: {
4066
+ onboarding: Pick<OnboardFolderManifest, "source" | "classification" | "summary" | "warnings">;
4067
+ dryRun: OnboardFolderManifest["dryRun"];
4068
+ };
4069
+ codeOverlay: {
4070
+ cachePath: string;
4071
+ summary: LocalCodeOverlaySummary;
4072
+ };
4073
+ apply: null | {
4074
+ sync: Record<string, unknown>;
4075
+ reindex?: Record<string, unknown>;
4076
+ };
4077
+ warnings: string[];
4078
+ }
4079
+ declare function getLocalSourceSnapshotPath(cwd?: string): string;
4080
+ declare function buildLocalSourceSnapshot(options?: LocalSourceSnapshotOptions): LocalSourceSnapshot;
4081
+ declare function writeLocalSourceSnapshot(snapshot: LocalSourceSnapshot): string;
4082
+ declare function readLocalSourceSnapshot(cwd?: string): LocalSourceSnapshot | null;
4083
+ declare function compareLocalSourceSnapshots(previous: LocalSourceSnapshot | null, current: LocalSourceSnapshot): LocalSourceComparison;
4084
+ declare function buildLocalSourceStatus(options?: LocalSourceSnapshotOptions): LocalSourceStatusResult;
4085
+ declare function buildLocalSourceSyncResult(options?: LocalSourceSyncOptions): Promise<LocalSourceSyncResult>;
4086
+
4087
+ interface LocalWorkerDeclaration {
4007
4088
  id: string;
4008
- mode: CollaborationLeaseMode;
4009
- status: CollaborationLeaseStatus;
4010
- resources: CollaborationResource[];
4011
- reason?: string;
4012
- claimedAt?: string;
4013
- expiresAt?: string | null;
4089
+ workerRole: string;
4090
+ endpointType: "local";
4091
+ provider: string;
4092
+ baseUrl: string;
4093
+ command?: string;
4094
+ model?: string;
4095
+ preferModel?: string;
4096
+ capabilities: string[];
4097
+ reasoning: "low" | "medium" | "high";
4098
+ writeScope: string[];
4099
+ createdAt: string;
4100
+ updatedAt: string;
4014
4101
  }
4015
- interface CollaborationLocalState {
4016
- schemaVersion: "snipara.collaboration.v1";
4102
+ interface LocalWorkersConfig {
4103
+ schemaVersion: "snipara.local_workers.v1";
4017
4104
  updatedAt: string;
4018
- workSessionId?: string;
4019
- sessionId?: string;
4020
- actorId?: string;
4021
- actorType?: CollaborationActorType;
4022
- actorLabel?: string;
4023
- client?: string;
4024
- repository?: string;
4025
- branch?: string;
4026
- worktree?: string;
4027
- task?: string;
4028
- files: string[];
4029
- resources: CollaborationResource[];
4030
- leases: CollaborationLocalLeaseRecord[];
4031
- lastGuard?: {
4032
- decision: CollaborationGuardDecision;
4033
- severity: string;
4034
- checkedAt: string;
4035
- action: string;
4036
- resources: CollaborationResource[];
4037
- conflictCount: number;
4038
- };
4105
+ defaultWorkerId: string;
4106
+ workers: LocalWorkerDeclaration[];
4039
4107
  }
4040
- interface ResolvedCollaborationContext {
4041
- rootDir: string;
4042
- config: RLMConfig;
4043
- actor: Required<Pick<CollaborationActorPayload, "actorId" | "actorType" | "actorLabel">> & {
4044
- sessionId?: string;
4045
- };
4046
- client: string;
4047
- branch?: string;
4048
- repository?: string;
4049
- worktree?: string;
4108
+ interface LocalWorkerRoutingDefaults {
4109
+ worker: LocalWorkerDeclaration;
4110
+ routeLocalWorkers: true;
4111
+ routingWorkerRole: string;
4112
+ routingLocalBaseUrl: string;
4113
+ routingLocalModel?: string;
4114
+ routingLocalPreferModel?: string;
4115
+ routingLocalProvider: string;
4116
+ routingPreferredEndpoints: string[];
4117
+ routingAllowedEndpoints: string[];
4118
+ plannerRetainsReasoning: true;
4050
4119
  }
4051
- declare function createEmptyCollaborationState(now?: Date): CollaborationLocalState;
4052
- declare function getCollaborationStatePath(rootDir?: string): string;
4053
- declare function loadCollaborationState(rootDir?: string): CollaborationLocalState;
4054
- declare function saveCollaborationState(state: CollaborationLocalState, rootDir?: string): void;
4055
- declare function buildCollaborationActor(options: Pick<CollaborationCommandOptions, "actor" | "actorId" | "actorType" | "sessionId" | "client">, config: RLMConfig): ResolvedCollaborationContext["actor"];
4056
- declare function normalizeCollaborationFiles(files: string[] | undefined): string[];
4057
- declare function parseCollaborationResources(values: string[] | undefined): CollaborationResource[];
4058
- declare function deriveLocalCollaborationResourcesFromFiles(files: string[] | undefined, rootDir?: string, maxFiles?: number): CollaborationResource[];
4059
- declare function buildCollaborationHooksInstallPlan(options?: CollaborationHooksInstallOptions): Record<string, unknown>;
4060
- declare function collaborationIdeStatusCommand(options: CollaborationCommandOptions): Promise<void>;
4061
- declare function buildCollaborationGuardActionCards(evaluation: CollaborationGuardEvaluation | undefined, context?: {
4062
- profile?: string;
4063
- enforced?: boolean;
4064
- ackReviewOnly?: boolean;
4065
- reviewOnlyAcknowledged?: boolean;
4066
- }): CollaborationGuardActionCard[];
4067
- interface HostedGuardPayload {
4068
- files: string[];
4069
- resources: CollaborationResource[];
4070
- fileCount: number;
4071
- resourceCount: number;
4072
- filesTruncated: boolean;
4073
- resourcesTruncated: boolean;
4120
+ interface LocalWorkerAddOptions {
4121
+ id?: string;
4122
+ role?: string;
4123
+ provider?: string;
4124
+ baseUrl?: string;
4125
+ model?: string;
4126
+ preferModel?: string;
4127
+ capabilities?: string[];
4128
+ writeScope?: string[];
4129
+ contextWindow?: number;
4130
+ reasoning?: "low" | "medium" | "high";
4131
+ default?: boolean;
4132
+ json?: boolean;
4133
+ transport?: "openai_http" | "cli";
4134
+ command?: string;
4135
+ }
4136
+ interface LocalWorkerStatusOptions {
4137
+ json?: boolean;
4138
+ }
4139
+ interface LocalWorkerListOptions {
4140
+ json?: boolean;
4141
+ }
4142
+ interface LocalWorkerRemoveOptions {
4143
+ id: string;
4144
+ json?: boolean;
4145
+ }
4146
+ interface LocalWorkerProbeOptions {
4147
+ baseUrl?: string;
4148
+ provider?: string;
4149
+ model?: string;
4150
+ preferModel?: string;
4151
+ role?: string;
4152
+ workerId?: string;
4153
+ capabilities?: string[];
4154
+ writeScope?: string[];
4155
+ reasoning?: "low" | "medium" | "high";
4156
+ contextWindow?: number;
4157
+ json?: boolean;
4158
+ }
4159
+ declare function workersLocalAddCommand(options: LocalWorkerAddOptions): void;
4160
+ declare function workersLocalStatusCommand(options?: LocalWorkerStatusOptions): void;
4161
+ declare function workersLocalListCommand(options?: LocalWorkerListOptions): void;
4162
+ declare function workersLocalRemoveCommand(options: LocalWorkerRemoveOptions): void;
4163
+ declare function workersLocalProbePrintCommand(options: LocalWorkerProbeOptions): void;
4164
+ declare function addLocalWorker(options: LocalWorkerAddOptions): {
4165
+ worker: LocalWorkerDeclaration;
4166
+ config: LocalWorkersConfig;
4167
+ workerConfigPath: string;
4168
+ policyPath: string;
4169
+ };
4170
+ declare function resolveLocalWorkerRoutingDefaults(options?: {
4171
+ workerId?: string;
4172
+ workerRole?: string;
4173
+ }): LocalWorkerRoutingDefaults | null;
4174
+ declare function readLocalWorkersConfig(): LocalWorkersConfig | null;
4175
+
4176
+ interface ControlledWorkerExecuteOptions {
4177
+ task: string;
4178
+ workerId?: string;
4179
+ workerRole?: string;
4180
+ endpointType?: "local" | "cloud" | "self_hosted" | "unknown";
4181
+ mode?: ControlledWorkerExecutionMode;
4182
+ command?: string;
4183
+ execute?: boolean;
4184
+ approvalReceipt?: string;
4185
+ outcomeReceipt?: string;
4186
+ writeScope?: string[];
4187
+ acceptance?: string[];
4188
+ proof?: string[];
4189
+ output?: string;
4190
+ projectId?: string;
4191
+ unifiedOutput?: string;
4192
+ dir?: string;
4193
+ json?: boolean;
4074
4194
  }
4075
- declare function buildHostedGuardPayload(files: string[], resources: CollaborationResource[]): HostedGuardPayload;
4076
- declare function compactHostedGuardResources(resources: CollaborationResource[]): CollaborationResource[];
4077
-
4078
- interface JournalCheckpointPayload {
4079
- action: string;
4080
- summary: string;
4081
- outcome?: string;
4082
- workflowId?: string;
4083
- phaseId?: string;
4084
- phaseTitle?: string;
4085
- branch?: string;
4086
- actor?: string;
4087
- next?: string;
4088
- attention?: string;
4089
- files?: string[];
4090
- cwd?: string;
4195
+ interface ControlledWorkerExecuteResult {
4196
+ executed: boolean;
4197
+ blocked: boolean;
4198
+ receiptPath: string;
4199
+ unifiedReceiptPath: string | null;
4200
+ receipt: ControlledWorkerExecutionReceipt;
4201
+ unifiedReceipt: UnifiedReceiptEnvelope<ControlledWorkerExecutionReceipt> | null;
4091
4202
  }
4092
- declare function buildJournalCheckpointEntry(payload: JournalCheckpointPayload): {
4093
- text: string;
4094
- tags: string[];
4095
- };
4203
+ declare function controlledWorkerExecuteCommand(options: ControlledWorkerExecuteOptions): ControlledWorkerExecuteResult;
4096
4204
 
4097
- type RuntimeEnvironment = Record<string, string | undefined>;
4098
- type ProviderKeySource = "environment" | "env-file";
4099
- type OrchestratorRecommendationLevel = "suggest" | "confirm" | "auto";
4100
- type OrchestratorRecommendationReason = "workflow_mode_orchestrate" | "production_validation_intent" | "proof_gate_intent" | "htask_or_swarm_intent" | "multi_agent_intent" | "parallel_worker_intent" | "changed_files_threshold" | "team_sync_collision" | "policy_auto_route";
4101
- interface OrchestratorRecommendation {
4102
- level: OrchestratorRecommendationLevel;
4103
- reasons: OrchestratorRecommendationReason[];
4104
- score: number;
4105
- orchestratorRequired: boolean;
4106
- policySource?: string;
4205
+ declare const MANIFEST_VERSION = "snipara.references.v1";
4206
+ type ReferenceStatus = "allowed" | "pending" | "denied" | "unsupported";
4207
+ interface ReferenceOccurrence {
4208
+ file: string;
4209
+ line: number;
4210
+ label?: string;
4107
4211
  }
4108
- interface OrchestratorRecommendationOptions {
4109
- changedFilesCount?: number;
4110
- hasActiveCollisions?: boolean;
4111
- policyAutoRoute?: boolean;
4112
- policySource?: string;
4113
- adaptiveRoutingDryRun?: boolean;
4212
+ interface ReferenceManifestItem {
4213
+ id: string;
4214
+ url: string;
4215
+ normalizedUrl: string;
4216
+ domain: string;
4217
+ status: ReferenceStatus;
4218
+ reason: string;
4219
+ discoveredAt: string;
4220
+ occurrences: ReferenceOccurrence[];
4221
+ latestSnapshotPath?: string;
4222
+ latestFetchStatus?: number;
4223
+ latestFetchAt?: string;
4224
+ latestContentHash?: string;
4225
+ latestError?: string;
4114
4226
  }
4115
- interface RuntimeDetectionReport {
4116
- cwd: string;
4117
- workspaceRoot: string | null;
4118
- companion: {
4119
- configured: boolean;
4120
- configPath: string;
4121
- };
4122
- runtime: {
4123
- cliAvailable: boolean;
4124
- command?: string;
4125
- legacyCommand?: boolean;
4126
- version?: string;
4127
- cliVersion?: string;
4128
- installedPackageVersion?: string;
4129
- versionMismatch?: boolean;
4130
- mcpConfigured: boolean;
4131
- mcpConfigPaths: string[];
4132
- };
4133
- orchestrator: {
4134
- cliAvailable: boolean;
4135
- command?: string;
4136
- version?: string;
4137
- source?: "path" | "workspace_venv";
4138
- workspacePackageVersion?: string;
4139
- versionMismatch?: boolean;
4140
- };
4141
- providerKeys: {
4142
- openai: boolean;
4143
- anthropic: boolean;
4144
- any: boolean;
4145
- sources: {
4146
- openai?: ProviderKeySource;
4147
- anthropic?: ProviderKeySource;
4148
- };
4149
- envFilesLoaded: string[];
4150
- };
4151
- docker: {
4152
- available: boolean;
4153
- };
4227
+ interface ReferenceManifest {
4228
+ version: typeof MANIFEST_VERSION;
4229
+ generatedAt: string;
4230
+ root: string;
4231
+ allowDomains: string[];
4232
+ denyDomains: string[];
4233
+ items: ReferenceManifestItem[];
4154
4234
  }
4155
- declare function detectRuntimeEnvironment(cwd?: string, env?: RuntimeEnvironment): RuntimeDetectionReport;
4156
- declare function shouldSuggestRuntimeForWorkflow(query: string, mode: WorkflowMode): boolean;
4157
- /**
4158
- * Recommend whether work should be routed to snipara-orchestrator.
4159
- *
4160
- * Scores intent signals from the query and workflow mode (orchestrate mode,
4161
- * production / proof / htask / multi-agent / parallel patterns) plus contextual
4162
- * signals (changed-file count, active Team Sync collisions, policy auto-route).
4163
- * The returned recommendation's level escalates with the accumulated score
4164
- * (suggest → confirm → auto).
4165
- *
4166
- * @returns A recommendation with its reasons, or `null` when no signal fires.
4167
- */
4168
- declare function getOrchestratorRecommendation(query: string, mode: WorkflowMode, options?: OrchestratorRecommendationOptions): OrchestratorRecommendation | null;
4169
- declare function formatOrchestratorRecommendationReason(reason: OrchestratorRecommendationReason): string;
4170
- declare function shouldSuggestOrchestratorForWorkflow(query: string, mode: WorkflowMode): boolean;
4235
+ interface ScanReferencesOptions {
4236
+ root?: string;
4237
+ output?: string;
4238
+ allowDomain?: string[];
4239
+ denyDomain?: string[];
4240
+ extensions?: string[];
4241
+ maxFiles?: number;
4242
+ json?: boolean;
4243
+ }
4244
+ interface IngestReferencesOptions {
4245
+ manifest?: string;
4246
+ outputDir?: string;
4247
+ allowDomain?: string[];
4248
+ ids?: string[];
4249
+ max?: number;
4250
+ timeoutMs?: number;
4251
+ maxBytes?: number;
4252
+ destinationPrefix?: string;
4253
+ upload?: boolean;
4254
+ reindex?: boolean;
4255
+ dryRun?: boolean;
4256
+ json?: boolean;
4257
+ }
4258
+ interface ScanSummary {
4259
+ manifest: ReferenceManifest;
4260
+ outputPath: string;
4261
+ scannedFiles: number;
4262
+ foundUrls: number;
4263
+ allowed: number;
4264
+ pending: number;
4265
+ denied: number;
4266
+ unsupported: number;
4267
+ }
4268
+ interface IngestSummary {
4269
+ manifestPath: string;
4270
+ selected: number;
4271
+ fetched: number;
4272
+ uploaded: number;
4273
+ failed: number;
4274
+ dryRun: boolean;
4275
+ snapshots: Array<{
4276
+ id: string;
4277
+ url: string;
4278
+ snapshotPath?: string;
4279
+ destinationPath?: string;
4280
+ status?: number;
4281
+ uploaded?: boolean;
4282
+ error?: string;
4283
+ }>;
4284
+ }
4285
+ declare function scanReferences(options?: ScanReferencesOptions): ScanSummary;
4286
+ declare function ingestReferences(options?: IngestReferencesOptions): Promise<IngestSummary>;
4287
+ declare function referencesScanCommand(options: ScanReferencesOptions): Promise<void>;
4288
+ declare function referencesIngestCommand(options: IngestReferencesOptions): Promise<void>;
4171
4289
 
4172
- declare const ORCHESTRATOR_HANDOFF_RELATIVE_PATH: string;
4173
- interface OrchestratorHandoffWorkflowPhase {
4174
- id: string;
4175
- title: string;
4176
- query: string;
4177
- status: string;
4178
- acceptance?: string;
4179
- files: string[];
4180
- gates: string[];
4181
- needsRuntime: boolean;
4290
+ declare const POLICY_LEDGER_SYNC_REPORT_VERSION: "snipara.workflow_policy_ledger_sync.v0";
4291
+ interface PolicyLedgerSyncSummary {
4292
+ total: number;
4293
+ pendingRequests: number;
4294
+ resolvedDecisions: number;
4295
+ applyReceipts: number;
4296
+ policyDrafts: number;
4182
4297
  }
4183
- interface OrchestratorHandoffRuntimeSandboxPhase {
4184
- phaseId: string;
4185
- title: string;
4186
- bootstrapQuery: string;
4187
- files: string[];
4188
- artifacts: string[];
4189
- contextPacks: string[];
4190
- sessionId: string | null;
4191
- environment: string | null;
4192
- profile: string | null;
4193
- hasCheckpoint: boolean;
4194
- checkpointSummary: string | null;
4195
- checkpointCapturedAt: string | null;
4298
+ interface PolicyLedgerSyncReport {
4299
+ version: typeof POLICY_LEDGER_SYNC_REPORT_VERSION;
4300
+ generatedAt: string;
4301
+ dryRun: boolean;
4302
+ summary: PolicyLedgerSyncSummary;
4303
+ artifacts: ProjectPolicyLedgerSyncArtifactInput[];
4304
+ hosted?: Record<string, unknown>;
4305
+ caveats: string[];
4196
4306
  }
4197
- interface AdaptiveWorkProfile {
4198
- taskType: string;
4199
- risk: string;
4200
- scope: string[];
4201
- contextBudget: string;
4202
- reasoningDepth: string;
4203
- evidenceRequirements?: string[];
4204
- preferredProfileStrengths?: string[];
4205
- notes?: string[];
4307
+ declare function buildPolicyLedgerSyncReport(options?: {
4308
+ cwd?: string;
4309
+ dryRun?: boolean;
4310
+ }): PolicyLedgerSyncReport;
4311
+ declare function workflowSyncPolicyLedgerCommand(options: {
4312
+ dryRun?: boolean;
4313
+ json?: boolean;
4314
+ }): Promise<void>;
4315
+ declare function collectPolicyLedgerSyncArtifacts(cwd?: string): ProjectPolicyLedgerSyncArtifactInput[];
4316
+
4317
+ type CacheStrategy = "exact" | "nearby" | "warm";
4318
+ interface QueryCacheScope {
4319
+ cwd?: string;
4320
+ projectId?: string;
4321
+ sessionId?: string;
4206
4322
  }
4207
- interface AdaptiveModelRequirements {
4208
- workerRole: string;
4209
- reasoning: string;
4210
- plannerRetainsReasoning: boolean;
4211
- speed: string;
4212
- cost: string;
4213
- contextBudget: string;
4214
- capabilities: string[];
4215
- forbiddenCapabilities: string[];
4216
- writeScope: string[];
4217
- structuredOutputRequired?: boolean;
4218
- preferredEndpointTypes?: string[];
4219
- allowedEndpointTypes?: string[];
4220
- catalogLimit?: number;
4221
- dailyBudgetCents?: number;
4222
- monthlyBudgetCents?: number;
4223
- fallback: "main_agent";
4323
+ interface QueryCacheLookup {
4324
+ query: string;
4325
+ maxTokens: number;
4224
4326
  }
4225
- interface AdaptiveRoutingCostEstimate {
4226
- currency: "USD";
4227
- confidence: "low" | "medium" | "high";
4327
+ interface QueryCacheHit {
4328
+ strategy: CacheStrategy;
4329
+ result: ContextQueryResult;
4330
+ sourceQuery: string;
4331
+ similarity?: number;
4228
4332
  }
4229
- interface AdaptiveRoutingCard {
4230
- mode: "dry_run";
4231
- workProfile: AdaptiveWorkProfile;
4232
- requirements: AdaptiveModelRequirements;
4233
- recommendedWorkerClass: string;
4234
- costEstimate: AdaptiveRoutingCostEstimate;
4235
- humanApprovalRequired: boolean;
4236
- fallback: "main_agent";
4237
- rejectedReasons?: Record<string, string[]>;
4238
- reasons: string[];
4239
- warnings: string[];
4333
+ interface WarmSnapshotResult {
4334
+ storedEntries: number;
4335
+ fileName?: string;
4240
4336
  }
4241
- interface AdaptiveRoutingGatewayStatus {
4242
- source: "hosted_mcp" | "local_orchestrator";
4243
- success: boolean;
4244
- resolutionStatus?: string;
4245
- candidateCount: number;
4246
- fallback?: string;
4247
- warnings: string[];
4337
+ declare class LocalQueryCache {
4338
+ private readonly scope;
4339
+ private readonly ttlMs;
4340
+ private readonly warmTtlMs;
4341
+ private readonly maxEntries;
4342
+ private readonly maxBytes;
4343
+ constructor(scope?: QueryCacheScope);
4344
+ lookup(options: QueryCacheLookup): QueryCacheHit | null;
4345
+ save(options: QueryCacheLookup, result: ContextQueryResult): void;
4346
+ storeWarmSnapshot(result: SessionMemoriesResult): WarmSnapshotResult;
4347
+ clear(): number;
4348
+ private loadIndex;
4349
+ private persistIndex;
4350
+ private pruneIndex;
4351
+ private readEntry;
4352
+ private findNearbyEntry;
4353
+ private lookupWarmSnapshot;
4248
4354
  }
4249
- interface AdaptiveRoutingRuntimeCatalog {
4250
- version?: string;
4251
- source?: string;
4252
- provider?: string;
4253
- baseUrl?: string;
4254
- models?: string[];
4255
- apiPaths?: Record<string, unknown>;
4256
- workerEndpoints?: Record<string, Record<string, unknown>>;
4257
- workerProfiles?: Record<string, Record<string, unknown>>;
4258
- candidates: Array<Record<string, unknown>>;
4355
+ declare function createLocalQueryCache(scope?: QueryCacheScope): LocalQueryCache;
4356
+
4357
+ declare const AUTOMATION_MANIFEST_RELATIVE_PATH = ".snipara/automations/manifest.json";
4358
+ type AutomationFileState = "create" | "update" | "unchanged" | "conflict";
4359
+ interface AutomationManifestFile {
4360
+ path: string;
4361
+ sha256: string;
4259
4362
  }
4260
- interface AdaptiveRoutingResolution {
4261
- status?: string;
4262
- selected?: Record<string, unknown>;
4263
- policyDecision?: Record<string, unknown>;
4264
- evaluatedCount?: number;
4265
- rejectedCount?: number;
4266
- fallback?: string;
4267
- reasons?: string[];
4268
- warnings?: string[];
4269
- rejectedReasons?: Record<string, string[]>;
4363
+ interface AutomationManifest {
4364
+ version: number;
4365
+ client: string;
4366
+ projectId?: string;
4367
+ apiUrl?: string;
4368
+ installedAt: string;
4369
+ files: AutomationManifestFile[];
4270
4370
  }
4271
- interface AdaptiveWorkRoutingRecommendation {
4272
- workProfile: AdaptiveWorkProfile;
4273
- requirements: AdaptiveModelRequirements;
4274
- routingCard: AdaptiveRoutingCard;
4275
- gateway?: AdaptiveRoutingGatewayStatus;
4276
- runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
4277
- resolution?: AdaptiveRoutingResolution;
4371
+ interface AutomationFilePlan {
4372
+ path: string;
4373
+ targetPath: string;
4374
+ state: AutomationFileState;
4375
+ reason: string;
4376
+ currentSha256?: string;
4377
+ previousSha256?: string;
4378
+ nextSha256: string;
4379
+ writeContent?: string;
4278
4380
  }
4279
- interface AdaptiveWorkRoutingOptions {
4280
- query: string;
4281
- mode?: string;
4282
- changedFiles?: string[];
4283
- preferredEndpointTypes?: string[];
4284
- allowedEndpointTypes?: string[];
4285
- workerRole?: string;
4286
- plannerRetainsReasoning?: boolean;
4287
- preferredProfileStrengths?: string[];
4288
- structuredOutputRequired?: boolean;
4289
- catalogLimit?: number;
4290
- dailyBudgetCents?: number;
4291
- monthlyBudgetCents?: number;
4381
+ interface AutomationInstallResult {
4382
+ manifest: AutomationManifest;
4383
+ plan: AutomationFilePlan[];
4384
+ written: number;
4385
+ unchanged: number;
4386
+ dryRun: boolean;
4292
4387
  }
4293
- interface OrchestratorHandoffArtifact {
4294
- schemaVersion: "snipara.orchestrator.handoff.v1";
4295
- source: {
4296
- client: "snipara-companion";
4297
- command: string;
4298
- generatedAt: string;
4299
- };
4300
- workflow: {
4301
- mode: string;
4302
- workflowId: string | null;
4303
- currentPhaseId: string | null;
4304
- phases: OrchestratorHandoffWorkflowPhase[];
4305
- };
4306
- runtime: {
4307
- sandbox: {
4308
- provider: "snipara-sandbox";
4309
- phases: OrchestratorHandoffRuntimeSandboxPhase[];
4310
- } | null;
4311
- };
4312
- routing: {
4313
- level: OrchestratorRecommendation["level"];
4314
- reasons: OrchestratorRecommendation["reasons"];
4315
- policySource: string | null;
4316
- workProfile?: AdaptiveWorkProfile;
4317
- requirements?: AdaptiveModelRequirements;
4318
- routingCard?: AdaptiveRoutingCard;
4319
- gateway?: AdaptiveRoutingGatewayStatus;
4320
- runtimeCatalog?: AdaptiveRoutingRuntimeCatalog;
4321
- resolution?: AdaptiveRoutingResolution;
4322
- };
4323
- task: {
4324
- title: string;
4325
- query: string;
4326
- summary: string;
4327
- };
4328
- repo: {
4329
- root: string;
4330
- branch: string | null;
4331
- headSha: string | null;
4332
- changedFiles: string[];
4333
- };
4334
- coordination: {
4335
- swarmId: string | null;
4336
- claimScope: {
4337
- files: string[];
4338
- symbols: string[];
4339
- };
4340
- htask: {
4341
- featureTitle: string | null;
4342
- workstreams: string[];
4343
- };
4344
- };
4345
- validation: {
4346
- requiresProofGate: boolean;
4347
- requiresDriftCheck: boolean;
4348
- liveChecks: string[];
4349
- requiredEvidence: Array<{
4350
- type: string;
4351
- description: string;
4352
- }>;
4353
- };
4354
- memory: {
4355
- decisionIds: string[];
4356
- contextRefs: string[];
4357
- resumeSummary: string | null;
4358
- };
4388
+ interface AutomationStatusResult {
4389
+ manifest: AutomationManifest | null;
4390
+ files: Array<{
4391
+ path: string;
4392
+ targetPath: string;
4393
+ state: "up-to-date" | "modified" | "missing";
4394
+ expectedSha256: string;
4395
+ currentSha256?: string;
4396
+ }>;
4359
4397
  }
4360
- interface OrchestratorHandoffOptions {
4361
- sourceCommand: string;
4362
- recommendation: OrchestratorRecommendation;
4363
- query: string;
4364
- summary: string;
4365
- title?: string;
4366
- mode?: string;
4367
- rootDir?: string;
4368
- changedFiles?: string[];
4369
- contextRefs?: string[];
4370
- decisionIds?: string[];
4371
- resumeSummary?: string;
4372
- featureTitle?: string;
4373
- workstreams?: string[];
4374
- adaptiveRouting?: AdaptiveWorkRoutingRecommendation | null;
4398
+ declare class AutomationInstallConflictError extends Error {
4399
+ conflicts: AutomationFilePlan[];
4400
+ constructor(conflicts: AutomationFilePlan[]);
4375
4401
  }
4376
- interface WrittenOrchestratorHandoff {
4377
- handoff: OrchestratorHandoffArtifact;
4378
- path: string;
4379
- relativePath: string;
4380
- command: string;
4402
+ declare class AutomationUnsupportedHookBundleError extends Error {
4403
+ client: string;
4404
+ files: string[];
4405
+ constructor(client: string, files: string[]);
4381
4406
  }
4382
- declare function buildOrchestratorHandoff(options: OrchestratorHandoffOptions): OrchestratorHandoffArtifact;
4383
- declare function buildAdaptiveWorkRoutingRecommendation(options: AdaptiveWorkRoutingOptions): AdaptiveWorkRoutingRecommendation;
4384
- declare function writeOrchestratorHandoff(options: OrchestratorHandoffOptions): WrittenOrchestratorHandoff;
4407
+ declare function getAutomationManifestPath(projectDir?: string): string;
4408
+ declare function loadAutomationManifest(projectDir?: string): AutomationManifest | null;
4409
+ declare function buildAutomationInstallPlan(args: {
4410
+ projectDir: string;
4411
+ bundle: AutomationConfigBundle;
4412
+ manifest?: AutomationManifest | null;
4413
+ force?: boolean;
4414
+ }): AutomationFilePlan[];
4415
+ declare function installAutomationBundle(args: {
4416
+ client: string;
4417
+ projectDir?: string;
4418
+ bundle?: AutomationConfigBundle;
4419
+ force?: boolean;
4420
+ dryRun?: boolean;
4421
+ }): Promise<AutomationInstallResult>;
4422
+ declare function getAutomationStatus(projectDir?: string): AutomationStatusResult;
4385
4423
 
4386
- export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, CODING_INTELLIGENCE_LEDGER_VERSION, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES, ENGINEERING_LEAD_PROOF_VERIFICATION_STATUSES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, POLICY_LEDGER_SYNC_REPORT_VERSION, PRODUCER_LOOP_ARTIFACT_VERSION, PRODUCER_LOOP_RELATIVE_DIR, PRODUCER_LOOP_REPORT_VERSION, TEAM_SYNC_STATE_RELATIVE_PATH, WHY_OUTCOME_CAPTURE_VERSION, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, addLocalWorker, agentReadinessAuditCommand, appendActivityEvent, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCodingIntelligenceLedger, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalProjectRealityCheck, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildPolicyLedgerSyncReport, buildProducerLoopReport, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapBrief, buildSessionBootstrapQuality, buildSessionSnapshot, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWhyOutcomeCaptureReport, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, codingLedgerExportCommand, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectPolicyLedgerSyncArtifacts, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, controlledWorkerExecuteCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, memoryReviewsCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, outcomeCapturePreviewCommand, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readActivityTimeline, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, readLocalWorkersConfig, readSessionSnapshot, realityCheckCommand, referencesIngestCommand, referencesScanCommand, resolveAutoWorkflowMode, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveLocalWorkerRoutingDefaults, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, workersLocalAddCommand, workersLocalListCommand, workersLocalProbePrintCommand, workersLocalRemoveCommand, workersLocalStatusCommand, workflowSyncPolicyLedgerCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff, writeProducerLoopArtifact, writeSessionSnapshot };
4424
+ export { AUTOMATION_MANIFEST_RELATIVE_PATH, AutomationInstallConflictError, AutomationUnsupportedHookBundleError, CODING_INTELLIGENCE_LEDGER_VERSION, COLLABORATION_STATE_RELATIVE_PATH, ENGINEERING_LEAD_EXECUTION_RECEIPT_STAGES, ENGINEERING_LEAD_EXECUTION_RECEIPT_STATUSES, ENGINEERING_LEAD_POSTURES, ENGINEERING_LEAD_PROOF_VERIFICATION_SOURCES, ENGINEERING_LEAD_PROOF_VERIFICATION_STATUSES, ENGINEERING_LEAD_ROUTING_MODES, ENGINEERING_LEAD_STATUSES, ENGINEERING_LEAD_SUPERVISION_STATUSES, ENGINEERING_LEAD_WORKER_ROLES, ENGINEERING_LEAD_WORK_PACKAGE_STATUSES, ORCHESTRATOR_HANDOFF_RELATIVE_PATH, POLICY_LEDGER_SYNC_REPORT_VERSION, PRODUCER_LOOP_ARTIFACT_VERSION, PRODUCER_LOOP_RELATIVE_DIR, PRODUCER_LOOP_REPORT_VERSION, TEAM_SYNC_STATE_RELATIVE_PATH, WHY_OUTCOME_CAPTURE_VERSION, WORKFLOW_PLANS_RELATIVE_DIR, WORKFLOW_STATE_RELATIVE_PATH, addLocalWorker, agentReadinessAuditCommand, appendActivityEvent, archiveInactiveTeamSyncWork, attachLocalContextPackReceipts, autoArchiveTeamSyncState, buildAdaptiveWorkRoutingRecommendation, buildAgentReadinessAuditReport, buildAgenticHandoffMarkdown, buildAgenticTimeline, buildAgenticWorkStatus, buildAutomationInstallPlan, buildCanonicalEvent, buildCodeHooksInstallPlan, buildCodePromotionResult, buildCodeStatusResult, buildCodeSyncResult, buildCodingIntelligenceLedger, buildCollaborationActor, buildCollaborationGuardActionCards, buildCollaborationHooksInstallPlan, buildCompanionEngineeringLeadPlanReport, buildContextPackStats, buildEvalCaseArtifact, buildGeneratedWorkflowPlanDocument, buildHostedCodeOverlayUploadPayload, buildHostedGuardPayload, buildJournalCheckpointEntry, buildLocalCallersResult, buildLocalCodeOverlay, buildLocalContextPackReceipt, buildLocalContextPackReceipts, buildLocalImpactResult, buildLocalImportsResult, buildLocalNeighborsResult, buildLocalProjectRealityCheck, buildLocalShortestPathResult, buildLocalSourceSnapshot, buildLocalSourceStatus, buildLocalSourceSyncResult, buildMemoryAudit, buildOnboardFolderManifest, buildOrchestratorHandoff, buildPolicyLedgerSyncReport, buildProducerLoopReport, buildProjectIntelligenceBrief, buildProjectIntelligenceRun, buildProjectJudgmentCard, buildSessionBootstrapBrief, buildSessionBootstrapQuality, buildSessionSnapshot, buildSyncDocumentsDryRun, buildTeamSyncHandoffRecord, buildTeamSyncStartWorkRecord, buildTeamSyncSummary, buildToolCallPayload, buildToolResultPayload, buildVerificationPlan, buildWhyOutcomeCaptureReport, buildWorkflowImpactGate, buildWorkflowPhaseCommitSummary, buildWorkflowPlanScaffold, categoryFromGuardTag, classifyToolResult, cleanContextPacks, codingLedgerExportCommand, collaborationIdeStatusCommand, collectAgentReadinessLocalSignals, collectPolicyLedgerSyncArtifacts, collectSyncDocuments, collectSyncDocumentsInput, compactHostedGuardResources, compareLocalSourceSnapshots, completeTeamSyncStateFromEvidence, completeTeamSyncWorkFromEvidence, contextPackCleanCommand, contextPackPackCommand, contextPackRetrieveCommand, contextPackStatsCommand, controlledWorkerExecuteCommand, createClient, createEmptyCollaborationState, createEmptyTeamSyncState, createLocalQueryCache, deriveLocalCollaborationResourcesFromFiles, detectReleaseSurfacesFromFiles, detectRuntimeEnvironment, evalExportCommand, evalRunCommand, evaluateProjectPolicyGates, extractCommandFromToolInput, extractFilesFromToolInput, formatAgentReadinessAuditReport, formatCompanionEngineeringLeadPlanReport, formatOrchestratorRecommendationReason, formatPolicyGateDecision, formatProjectJudgmentCard, formatStuckGuardDecision, getAutomationManifestPath, getAutomationStatus, getCollaborationStatePath, getConfigPath, getContextPackStoragePaths, getLocalCodeOverlayCachePath, getLocalCodePromotionStatePath, getLocalSourceSnapshotPath, getOrchestratorRecommendation, getPlanStepDisplayTitle, getStagedFiles, getStuckGuardInjection, getTeamSyncStatePath, ingestReferences, installAutomationBundle, leadPlanCommand, listProjectsForApiKey, loadAutomationManifest, loadCollaborationState, loadConfig, loadTeamSyncState, memoryAuditCommand, memoryCleanCandidatesCommand, memoryCompactCommand, memoryHealthCommand, memoryLocalCommand, memoryReviewsCommand, normalizeCollaborationFiles, normalizeGuardTag, normalizeWorkflowPlanInput, outcomeCapturePreviewCommand, packContext, parseCollaborationResources, projectIntelligenceBriefCommand, projectIntelligenceRunCommand, readActivityTimeline, readLocalCodeOverlayCache, readLocalCodePromotionState, readLocalSourceSnapshot, readLocalWorkersConfig, readSessionSnapshot, realityCheckCommand, referencesIngestCommand, referencesScanCommand, resolveAutoWorkflowMode, resolveContextPackRecord, resolveFullWorkflowTokenBudget, resolveLocalWorkerRoutingDefaults, resolveQueryFromToolInput, retrieveContextPack, runMemoryGuardCheck, saveCollaborationState, saveConfig, saveTeamSyncState, scanReferences, shouldFailCollaborationGuard, shouldSuggestOrchestratorForWorkflow, shouldSuggestRuntimeForWorkflow, summarizeLocalCodeOverlay, teamSyncSweepCommand, validatePlanResult, verifyCommand, workersLocalAddCommand, workersLocalListCommand, workersLocalProbePrintCommand, workersLocalRemoveCommand, workersLocalStatusCommand, workflowSyncPolicyLedgerCommand, writeLocalCodeOverlayCache, writeLocalCodePromotionState, writeLocalSourceSnapshot, writeOrchestratorHandoff, writeProducerLoopArtifact, writeSessionSnapshot };