clinkx 0.2.3 → 1.0.0

package/dist/context-builder/delegate-packet.d.ts

@@ -0,0 +1,219 @@
+import { type ContextBuilderOmission } from "./diagnostics.js";
+import { type ContextBuilderContentCandidate, type ContextBuilderDiscoveryMetrics, type ContextBuilderSearchRecord, type ContextBuilderSliceRecord, type ContextBuilderTreeFile } from "./discovery.js";
+import { type ContextBuilderResolvedFocusPath } from "./paths.js";
+import { type ContextBuilderPublicBudget } from "./schema.js";
+import { ContextCoveragePolicy, ContextEvidenceClass, type ContextReviewObligationModel } from "./review-coverage.js";
+import { type ContextBuilderSelectionMetrics, type ContextBuilderSelectionResult } from "./selection.js";
+export type ContextBuilderDelegatePacketPurpose = "curator" | "finalizer";
+export type ContextBuilderDelegatePacketCaps = {
+    max_candidates: number;
+    max_search_records: number;
+    max_slice_records: number;
+    max_omissions: number;
+    max_paths_per_omission: number;
+    max_total_evidence_bytes: number;
+    max_preview_bytes: number;
+    max_slice_excerpt_bytes: number;
+    max_task_chars: number;
+    max_packet_estimated_tokens: number;
+};
+export declare const CONTEXT_BUILDER_DELEGATE_PACKET_CAP_DEFAULTS: Readonly<{
+    max_candidates: number;
+    max_search_records: number;
+    max_slice_records: number;
+    max_omissions: number;
+    max_paths_per_omission: number;
+    max_total_evidence_bytes: number;
+    max_preview_bytes: number;
+    max_slice_excerpt_bytes: number;
+    max_task_chars: number;
+    max_packet_estimated_tokens: number;
+}>;
+export declare const CONTEXT_BUILDER_DELEGATE_PACKET_CAP_PROFILE_DEFAULTS: Readonly<{
+    handoff_small: {
+        max_candidates: number;
+        max_search_records: number;
+        max_slice_records: number;
+        max_total_evidence_bytes: number;
+        max_preview_bytes: number;
+        max_slice_excerpt_bytes: number;
+        max_packet_estimated_tokens: number;
+    };
+    implementation_medium: {
+        max_candidates: number;
+        max_search_records: number;
+        max_slice_records: number;
+        max_total_evidence_bytes: number;
+        max_preview_bytes: number;
+        max_slice_excerpt_bytes: number;
+        max_packet_estimated_tokens: number;
+    };
+    review_deep: {
+        max_candidates: number;
+        max_search_records: number;
+        max_slice_records: number;
+        max_total_evidence_bytes: number;
+        max_preview_bytes: number;
+        max_slice_excerpt_bytes: number;
+        max_packet_estimated_tokens: number;
+    };
+}>;
+export type ContextBuilderDelegatePacketCandidate = {
+    id: string;
+    root_index: number;
+    path: string;
+    line_count: number;
+    size_bytes: number;
+    estimated_tokens: number;
+    discovery_reason: "focus_path" | "search_hit" | "eligible_candidate";
+    evidence_classes: ContextEvidenceClass[];
+    focus_requested?: boolean;
+    required_focus_ranges?: ContextBuilderDelegatePacketSelectedRange[];
+    deterministic_selected: boolean;
+    deterministic_coverage?: "none" | "partial" | "complete";
+    deterministic_ranges?: ContextBuilderDelegatePacketSelectedRange[];
+    uncovered_packet_ranges?: ContextBuilderDelegatePacketSelectedRange[];
+    ranges: ContextBuilderDelegatePacketRange[];
+    search_hits: ContextBuilderDelegatePacketSearchHit[];
+};
+export type ContextBuilderDelegatePacketCoveragePolicy = {
+    policy_id: "review_deep_v1" | null;
+    required_when_available: ContextEvidenceClass[];
+    obligations?: ContextReviewObligationModel;
+};
+export type ContextBuilderDelegatePacketRange = {
+    id: string;
+    start_line: number;
+    end_line: number;
+    source: "focus" | "search";
+    estimated_tokens: number;
+    excerpt: string;
+    excerpt_truncated: boolean;
+};
+export type ContextBuilderDelegatePacketSearchHit = {
+    line: number;
+    column: number;
+    search_term_index: number;
+    preview: string;
+    preview_truncated: boolean;
+};
+export type ContextBuilderDelegatePacketSelectedRange = {
+    id: string;
+    start_line: number;
+    end_line: number;
+};
+export type ContextBuilderDelegatePacketSelection = {
+    candidate_id: string;
+    root_index: number;
+    path: string;
+    ranges: ContextBuilderDelegatePacketSelectedRange[];
+    source: "focus" | "search";
+    bytes: number;
+    estimated_tokens: number;
+};
+export type ContextBuilderCuratorProposalRange = {
+    start_line: number;
+    end_line: number;
+    reason: string;
+};
+export type ContextBuilderCuratorProposalSelection = {
+    candidate_id: string;
+    ranges: ContextBuilderCuratorProposalRange[];
+    reason: string;
+};
+export type ContextBuilderCuratorProposal = {
+    selected: ContextBuilderCuratorProposalSelection[];
+    warnings: string[];
+    open_questions: string[];
+};
+export type ContextBuilderDelegatePacketCompactionMetrics = {
+    candidates_before_compaction: number;
+    candidates_after_compaction: number;
+    candidates_evicted_by_compaction: number;
+    evidence_bytes_before_compaction: number;
+    evidence_bytes_after_compaction: number;
+    search_records_before_compaction: number;
+    search_records_after_compaction: number;
+    slice_records_before_compaction: number;
+    slice_records_after_compaction: number;
+    all_non_focus_candidates_evidence_free: boolean;
+};
+export type ContextBuilderDelegatePacketEvidenceWarning = {
+    code: "all_non_focus_candidates_evidence_free";
+    message: string;
+    non_focus_candidate_count: number;
+};
+export type ContextBuilderDelegatePacketMetrics = {
+    discovery: ContextBuilderDiscoveryMetrics;
+    selection: ContextBuilderSelectionMetrics;
+    candidates_included: number;
+    candidates_omitted_by_packet_cap: number;
+    search_records_included: number;
+    search_records_omitted_by_packet_cap: number;
+    slice_records_included: number;
+    slice_records_omitted_by_packet_cap: number;
+    evidence_bytes: number;
+    evidence_byte_cap_hit: boolean;
+    packet_estimated_tokens: number;
+    packet_token_cap_hit: boolean;
+    compaction: ContextBuilderDelegatePacketCompactionMetrics;
+};
+export type ContextBuilderDelegatePacket = {
+    version: "context-builder.delegate-packet.v1";
+    purpose: ContextBuilderDelegatePacketPurpose;
+    task: string;
+    rules: {
+        local_candidate_universe_only: true;
+        provider_must_not_discover_paths: true;
+        source_authority: "server";
+        absolute_paths_included: false;
+        raw_full_content_included: false;
+    };
+    budget: ContextBuilderPublicBudget;
+    coverage_policy: ContextBuilderDelegatePacketCoveragePolicy;
+    candidates: ContextBuilderDelegatePacketCandidate[];
+    deterministic_selection: {
+        metrics: ContextBuilderSelectionMetrics;
+        selected: ContextBuilderDelegatePacketSelection[];
+    };
+    omissions: ContextBuilderOmission[];
+    metrics: ContextBuilderDelegatePacketMetrics;
+    evidence_warning?: ContextBuilderDelegatePacketEvidenceWarning;
+    curator_proposal?: ContextBuilderCuratorProposal;
+    local_selection_summary?: {
+        selected: ContextBuilderDelegatePacketSelection[];
+    };
+};
+export type ContextBuilderDelegatePacketDiscoveryInput = {
+    tree: readonly ContextBuilderTreeFile[];
+    content_candidates: readonly ContextBuilderContentCandidate[];
+    search: readonly ContextBuilderSearchRecord[];
+    slices: readonly ContextBuilderSliceRecord[];
+    omissions: readonly ContextBuilderOmission[];
+    metrics: ContextBuilderDiscoveryMetrics;
+    review_obligations?: ContextReviewObligationModel;
+};
+export type ContextBuilderDelegatePacketInput = {
+    task: string;
+    allowSecrets?: boolean;
+    discovery: ContextBuilderDelegatePacketDiscoveryInput;
+    selection: ContextBuilderSelectionResult;
+    budget: ContextBuilderPublicBudget;
+    focus_paths?: readonly ContextBuilderResolvedFocusPath[];
+    /**
+     * Caller-supplied `search_terms` from the public request. Optional and
+     * additive: when absent, exact-caller-hit compaction protection is simply
+     * not applied (legacy behavior). Used only to classify candidates whose
+     * search records match a caller term verbatim.
+     */
+    caller_search_terms?: readonly string[];
+    coveragePolicy?: ContextCoveragePolicy;
+    caps?: Partial<ContextBuilderDelegatePacketCaps>;
+};
+export type ContextBuilderFinalizerPacketInput = ContextBuilderDelegatePacketInput & {
+    curator_proposal: ContextBuilderCuratorProposal;
+};
+export declare function buildContextBuilderCuratorPacket(input: ContextBuilderDelegatePacketInput): ContextBuilderDelegatePacket;
+export declare function buildContextBuilderFinalizerPacket(input: ContextBuilderFinalizerPacketInput): ContextBuilderDelegatePacket;
+export declare function contextBuilderCandidateId(rootIndex: number, path: string): string;
+export declare function contextBuilderRangeId(candidateId: string, startLine: number, endLine: number): string;