@pedrocivita/tocket 2.6.3 → 2.6.5

package/dist/utils/attention.d.ts

@@ -0,0 +1,155 @@
+/** Meta-attention: Jev (or the stub) scores context chunks and gotcha packs. */
+import { type DecideMode, type DecideSemantics } from "./decide.js";
+export declare const ATTENTION_SCHEMA = "tocket.attention/v0";
+export declare const ATTENTION_DIR = ".context/attention";
+export declare const HANDOFFS_DIR = ".context/handoffs";
+export declare const GOTCHAS_DIR = ".context/gotchas";
+export declare const ACTIVE_PACKS_REL = ".context/active/packs.md";
+export declare const DEFAULT_THRESHOLD = 0.5;
+export declare const SCORE_MIN = 0;
+export declare const SCORE_MAX = 1;
+export declare const MAX_CHUNK_CHARS = 700;
+export declare const DECISION_CHUNK_LIMIT = 5;
+export declare class AttentionError extends Error {
+    constructor(message: string);
+}
+export type AttentionSource = "stub" | "jev";
+export type ChunkIntent = "relevant" | "load";
+export interface ContextChunk {
+    id: string;
+    label: string;
+    source: string;
+    heading: string;
+    text: string;
+    intent: ChunkIntent;
+}
+export interface ScoredChunk extends ContextChunk {
+    noul: number;
+    score: number;
+    kept: boolean;
+    rationale: string;
+}
+export interface AttentionChunk {
+    id: string;
+    label: string;
+    source: string;
+    intent: ChunkIntent;
+    noul: number;
+    score: number;
+    kept: boolean;
+    rationale: string;
+    preview: string;
+}
+export interface AttentionRecord {
+    schema: typeof ATTENTION_SCHEMA;
+    id: string;
+    generated_at: string;
+    query: string;
+    threshold: number;
+    source: AttentionSource;
+    mode: DecideMode;
+    semantics: DecideSemantics;
+    model: string;
+    executes: false;
+    kind: "handoff" | "packs";
+    chunks: AttentionChunk[];
+    packs?: AttentionChunk[];
+}
+export interface JudgeResult {
+    chunks: ScoredChunk[];
+    source: AttentionSource;
+    mode: DecideMode;
+    semantics: DecideSemantics;
+    model: string;
+}
+export declare function parseThreshold(value?: string): number;
+/** Kept when Noul >= threshold OR Score >= the same fraction of the score range (mid at 0.5). */
+export declare function chunkKept(noul: number, score: number, threshold: number, scoreMin?: number, scoreMax?: number): boolean;
+export declare function relevanceTokens(text: string): string[];
+/** Deterministic overlap. No network. Unrelated chunks stay under the default 0.5 cutoff. */
+export declare function stubRelevance(query: string, chunkText: string): {
+    noul: number;
+    score: number;
+    rationale: string;
+};
+/** Split a markdown file into small labeled chunks (## / ###, then paragraphs). */
+export declare function splitMarkdown(source: string, markdown: string, intent?: ChunkIntent, maxChars?: number): ContextChunk[];
+export declare function collectContextChunks(cwd: string): ContextChunk[];
+export declare function collectGotchaPacks(cwd: string): ContextChunk[];
+export declare function queryFromFocus(content: string): string;
+export declare function judgeChunks(options: {
+    query: string;
+    chunks: ContextChunk[];
+    threshold: number;
+    dryRun?: boolean;
+    shadow?: boolean;
+    apiKey?: string | null;
+    fetchImpl?: typeof fetch;
+}): Promise<JudgeResult>;
+export declare function attentionReadme(): string;
+export declare function attentionOutputPath(cwd: string, generatedAt: string, id: string): string;
+export declare function handoffOutputPath(cwd: string, generatedAt: string, id: string): string;
+export declare function activePacksPath(cwd: string): string;
+export declare function buildAwareHandoffMarkdown(input: {
+    projectName: string;
+    query: string;
+    focus: string;
+    branch: string;
+    recentCommits: string[];
+    modifiedFiles: string[];
+    context: ScoredChunk[];
+    packs: ScoredChunk[];
+    threshold: number;
+    source: AttentionSource;
+    mode: DecideMode;
+    attentionRel: string;
+}): string;
+export declare function buildPacksMarkdown(input: {
+    query: string;
+    packs: ScoredChunk[];
+    threshold: number;
+    source: AttentionSource;
+    mode: DecideMode;
+    attentionRel: string;
+}): string;
+export declare function formatAwareSummary(record: AttentionRecord, handoffRel: string, attentionRel: string): string;
+export declare function formatPacksSummary(record: AttentionRecord, packsRel: string): string;
+export interface AwareHandoffInput {
+    cwd: string;
+    query?: string;
+    focus?: string;
+    projectName?: string;
+    branch?: string;
+    recentCommits?: string[];
+    modifiedFiles?: string[];
+    threshold?: number;
+    dryRun?: boolean;
+    shadow?: boolean;
+    apiKey?: string | null;
+    id?: string;
+    now?: () => string;
+    fetchImpl?: typeof fetch;
+}
+export declare function runAwareHandoff(options: AwareHandoffInput): Promise<{
+    markdown: string;
+    record: AttentionRecord;
+    attentionPath: string;
+    handoffPath: string;
+}>;
+export declare function runPacksLoad(options: {
+    cwd: string;
+    query?: string;
+    focus?: string;
+    threshold?: number;
+    dryRun?: boolean;
+    shadow?: boolean;
+    apiKey?: string | null;
+    id?: string;
+    now?: () => string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    markdown: string;
+    record: AttentionRecord;
+    attentionPath: string;
+    packsPath: string;
+}>;