@usewhisper/sdk 3.4.0 → 3.6.0

package/index.d.mts

@@ -77,6 +77,7 @@ interface RememberResult {
  */
 declare class Whisper {
     private client;
+    private runtimeClient;
     private options;
     private sessionId?;
     private userId?;
@@ -618,6 +619,217 @@ declare class AnalyticsModule {
     queueStatus(): WriteQueueStatus;
 }
 
+interface AgentRunContext {
+    workspacePath?: string;
+    project?: string;
+    userId?: string;
+    sessionId?: string;
+    traceId?: string;
+    clientName?: string;
+}
+interface TurnInput {
+    userMessage: string;
+    taskSummary?: string;
+    touchedFiles?: string[];
+    toolContext?: string;
+}
+type WorkEventKind = "decision" | "constraint" | "outcome" | "failure" | "task_update" | "file_edit" | "tool_result";
+type WorkEventSalience = "low" | "medium" | "high";
+interface WorkEvent {
+    kind: WorkEventKind;
+    summary: string;
+    details?: string;
+    salience?: WorkEventSalience;
+    timestamp?: string;
+    filePaths?: string[];
+    toolName?: string;
+    success?: boolean;
+}
+interface PreparedTurn {
+    scope: AgentRunContext & {
+        project: string;
+        userId: string;
+        sessionId: string;
+    };
+    retrieval: {
+        primaryQuery: string;
+        taskFrameQuery: string | null;
+        warnings: string[];
+        degraded: boolean;
+        degradedReason?: string;
+        durationMs: number;
+        targetBudgetMs: number;
+        hardTimeoutMs: number;
+        branchStatus: Record<string, "ok" | "error" | "timeout" | "skipped">;
+    };
+    context: string;
+    items: Array<{
+        id: string;
+        content: string;
+        type: "project" | "memory";
+        score: number;
+        sourceQuery: "primary" | "task_frame" | "bootstrap";
+        metadata?: Record<string, unknown>;
+    }>;
+}
+interface TurnCaptureResult {
+    success: boolean;
+    sessionIngested: boolean;
+    memoriesCreated: number;
+    relationsCreated: number;
+    invalidatedCount: number;
+    mergedCount: number;
+    droppedCount: number;
+    warnings: string[];
+}
+interface AgentRuntimeStatus {
+    clientName: string;
+    scope: {
+        project?: string;
+        userId?: string;
+        sessionId?: string;
+        source?: "explicit" | "workspace" | "config" | "generated";
+        warning?: string;
+    };
+    queue: {
+        queued: number;
+        flushing: boolean;
+        lastFlushAt?: string;
+        lastFlushCount: number;
+    };
+    retrieval: PreparedTurn["retrieval"] | null;
+    counters: {
+        mergedCount: number;
+        droppedCount: number;
+        bufferedLowSalience: number;
+    };
+}
+interface AgentRuntimeOptions extends AgentRunContext {
+    topK?: number;
+    maxTokens?: number;
+    targetRetrievalMs?: number;
+    hardRetrievalTimeoutMs?: number;
+    bindingStorePath?: string;
+    recentWorkLimit?: number;
+}
+interface QueueStatus {
+    queued: number;
+    flushing: boolean;
+    lastFlushAt?: string;
+    lastFlushCount: number;
+}
+interface RuntimeAdapter {
+    resolveProject(project?: string): Promise<Project>;
+    query(params: QueryParams): Promise<QueryResult>;
+    ingestSession(params: {
+        project?: string;
+        session_id: string;
+        user_id?: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            timestamp: string;
+        }>;
+        async?: boolean;
+        write_mode?: "async" | "sync";
+    }): Promise<{
+        success: boolean;
+        memories_created: number;
+        relations_created: number;
+        memories_invalidated: number;
+        errors?: string[];
+    } & MemoryWriteAck$1>;
+    getSessionMemories(params: {
+        project?: string;
+        session_id: string;
+        include_pending?: boolean;
+        limit?: number;
+    }): Promise<{
+        memories: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    getUserProfile(params: {
+        project?: string;
+        user_id: string;
+        include_pending?: boolean;
+        memory_types?: string;
+    }): Promise<{
+        user_id: string;
+        memories: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    searchMemories(params: {
+        project?: string;
+        query: string;
+        user_id?: string;
+        session_id?: string;
+        top_k?: number;
+        memory_type?: MemoryKind$1;
+        profile?: "fast" | "balanced" | "quality";
+        include_pending?: boolean;
+    }): Promise<MemorySearchResponse$1>;
+    addMemory(params: {
+        project?: string;
+        content: string;
+        memory_type?: MemoryKind$1;
+        user_id?: string;
+        session_id?: string;
+        importance?: number;
+        confidence?: number;
+        metadata?: Record<string, unknown>;
+        event_date?: string;
+        write_mode?: "async" | "sync";
+        async?: boolean;
+    }): Promise<MemoryWriteAck$1>;
+    queueStatus(): QueueStatus;
+    flushQueue(): Promise<void>;
+}
+declare class WhisperAgentRuntime {
+    private readonly args;
+    private readonly bindingStore;
+    private readonly topK;
+    private readonly maxTokens;
+    private readonly targetRetrievalMs;
+    private readonly hardRetrievalTimeoutMs;
+    private readonly recentWorkLimit;
+    private readonly baseContext;
+    private readonly clientName;
+    private bindings;
+    private touchedFiles;
+    private recentWork;
+    private bufferedLowSalience;
+    private lastPreparedTurn;
+    private mergedCount;
+    private droppedCount;
+    private lastScope;
+    constructor(args: {
+        baseContext: AgentRunContext;
+        options: AgentRuntimeOptions;
+        adapter: RuntimeAdapter;
+    });
+    private getBindings;
+    private pushTouchedFiles;
+    private pushWorkEvent;
+    private makeTaskFrameQuery;
+    private resolveScope;
+    private runBranch;
+    private contextItems;
+    private memoryItems;
+    private rerank;
+    private buildContext;
+    bootstrap(context?: Partial<AgentRunContext>): Promise<PreparedTurn>;
+    beforeTurn(input: TurnInput, context?: Partial<AgentRunContext>): Promise<PreparedTurn>;
+    recordWork(event: WorkEvent, context?: Partial<AgentRunContext>): Promise<MemoryWriteAck$1 | {
+        success: true;
+        buffered: true;
+    }>;
+    afterTurn(input: TurnInput & {
+        assistantMessage: string;
+    }, context?: Partial<AgentRunContext>): Promise<TurnCaptureResult>;
+    flush(reason?: string, context?: Partial<AgentRunContext>): Promise<AgentRuntimeStatus>;
+    status(): AgentRuntimeStatus;
+}
+
 interface WhisperClientConfig {
     apiKey: string;
     baseUrl?: string;
@@ -711,8 +923,38 @@ declare class WhisperClient {
     private readonly sessionModule;
     private readonly profileModule;
     private readonly analyticsModule;
+    private readonly projectRefToId;
+    private projectCache;
+    private projectCacheExpiresAt;
     constructor(config: WhisperClientConfig);
     static fromEnv(overrides?: Partial<WhisperClientConfig>): WhisperClient;
+    private createQueueStore;
+    private defaultQueuePersistence;
+    private defaultQueueFilePath;
+    private getRequiredProject;
+    private refreshProjectCache;
+    private fetchResolvedProject;
+    resolveProject(projectRef?: string): Promise<Project>;
+    query(params: QueryParams): Promise<QueryResult>;
+    ingestSession(params: {
+        project?: string;
+        session_id: string;
+        user_id?: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            timestamp: string;
+        }>;
+        async?: boolean;
+        write_mode?: "async" | "sync";
+    }): Promise<{
+        success: boolean;
+        memories_created: number;
+        relations_created: number;
+        memories_invalidated: number;
+        errors?: string[];
+    } & MemoryWriteAck$1>;
+    createAgentRuntime(options?: AgentRuntimeOptions): WhisperAgentRuntime;
     withRunContext(context: RunContext): {
         memory: {
             add: (params: Omit<Parameters<MemoryModule["add"]>[0], "project" | "user_id" | "session_id"> & {
@@ -971,6 +1213,12 @@ interface QueryResult {
         cache_hit: boolean;
         tokens_used: number;
         context_hash: string;
+        source_scope?: {
+            mode: "none" | "explicit" | "auto";
+            source_ids: string[];
+            host?: string;
+            matched_sources?: number;
+        };
         profile?: string;
         compression?: any;
         timing?: {
@@ -1814,4 +2062,4 @@ declare class WhisperContext {
     };
 }
 
-export { type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type MemoryWriteResult, type Project, type QueryParams, type QueryResult, type Source, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };
+export { type AgentRunContext, type AgentRuntimeOptions, type AgentRuntimeStatus, type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type MemoryWriteResult, type PreparedTurn, type Project, type QueryParams, type QueryResult, type Source, type TurnCaptureResult, type TurnInput, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, type WorkEvent, type WorkEventKind, type WorkEventSalience, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };

package/index.d.ts

@@ -77,6 +77,7 @@ interface RememberResult {
  */
 declare class Whisper {
     private client;
+    private runtimeClient;
     private options;
     private sessionId?;
     private userId?;
@@ -618,6 +619,217 @@ declare class AnalyticsModule {
     queueStatus(): WriteQueueStatus;
 }
 
+interface AgentRunContext {
+    workspacePath?: string;
+    project?: string;
+    userId?: string;
+    sessionId?: string;
+    traceId?: string;
+    clientName?: string;
+}
+interface TurnInput {
+    userMessage: string;
+    taskSummary?: string;
+    touchedFiles?: string[];
+    toolContext?: string;
+}
+type WorkEventKind = "decision" | "constraint" | "outcome" | "failure" | "task_update" | "file_edit" | "tool_result";
+type WorkEventSalience = "low" | "medium" | "high";
+interface WorkEvent {
+    kind: WorkEventKind;
+    summary: string;
+    details?: string;
+    salience?: WorkEventSalience;
+    timestamp?: string;
+    filePaths?: string[];
+    toolName?: string;
+    success?: boolean;
+}
+interface PreparedTurn {
+    scope: AgentRunContext & {
+        project: string;
+        userId: string;
+        sessionId: string;
+    };
+    retrieval: {
+        primaryQuery: string;
+        taskFrameQuery: string | null;
+        warnings: string[];
+        degraded: boolean;
+        degradedReason?: string;
+        durationMs: number;
+        targetBudgetMs: number;
+        hardTimeoutMs: number;
+        branchStatus: Record<string, "ok" | "error" | "timeout" | "skipped">;
+    };
+    context: string;
+    items: Array<{
+        id: string;
+        content: string;
+        type: "project" | "memory";
+        score: number;
+        sourceQuery: "primary" | "task_frame" | "bootstrap";
+        metadata?: Record<string, unknown>;
+    }>;
+}
+interface TurnCaptureResult {
+    success: boolean;
+    sessionIngested: boolean;
+    memoriesCreated: number;
+    relationsCreated: number;
+    invalidatedCount: number;
+    mergedCount: number;
+    droppedCount: number;
+    warnings: string[];
+}
+interface AgentRuntimeStatus {
+    clientName: string;
+    scope: {
+        project?: string;
+        userId?: string;
+        sessionId?: string;
+        source?: "explicit" | "workspace" | "config" | "generated";
+        warning?: string;
+    };
+    queue: {
+        queued: number;
+        flushing: boolean;
+        lastFlushAt?: string;
+        lastFlushCount: number;
+    };
+    retrieval: PreparedTurn["retrieval"] | null;
+    counters: {
+        mergedCount: number;
+        droppedCount: number;
+        bufferedLowSalience: number;
+    };
+}
+interface AgentRuntimeOptions extends AgentRunContext {
+    topK?: number;
+    maxTokens?: number;
+    targetRetrievalMs?: number;
+    hardRetrievalTimeoutMs?: number;
+    bindingStorePath?: string;
+    recentWorkLimit?: number;
+}
+interface QueueStatus {
+    queued: number;
+    flushing: boolean;
+    lastFlushAt?: string;
+    lastFlushCount: number;
+}
+interface RuntimeAdapter {
+    resolveProject(project?: string): Promise<Project>;
+    query(params: QueryParams): Promise<QueryResult>;
+    ingestSession(params: {
+        project?: string;
+        session_id: string;
+        user_id?: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            timestamp: string;
+        }>;
+        async?: boolean;
+        write_mode?: "async" | "sync";
+    }): Promise<{
+        success: boolean;
+        memories_created: number;
+        relations_created: number;
+        memories_invalidated: number;
+        errors?: string[];
+    } & MemoryWriteAck$1>;
+    getSessionMemories(params: {
+        project?: string;
+        session_id: string;
+        include_pending?: boolean;
+        limit?: number;
+    }): Promise<{
+        memories: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    getUserProfile(params: {
+        project?: string;
+        user_id: string;
+        include_pending?: boolean;
+        memory_types?: string;
+    }): Promise<{
+        user_id: string;
+        memories: Array<Record<string, unknown>>;
+        count: number;
+    }>;
+    searchMemories(params: {
+        project?: string;
+        query: string;
+        user_id?: string;
+        session_id?: string;
+        top_k?: number;
+        memory_type?: MemoryKind$1;
+        profile?: "fast" | "balanced" | "quality";
+        include_pending?: boolean;
+    }): Promise<MemorySearchResponse$1>;
+    addMemory(params: {
+        project?: string;
+        content: string;
+        memory_type?: MemoryKind$1;
+        user_id?: string;
+        session_id?: string;
+        importance?: number;
+        confidence?: number;
+        metadata?: Record<string, unknown>;
+        event_date?: string;
+        write_mode?: "async" | "sync";
+        async?: boolean;
+    }): Promise<MemoryWriteAck$1>;
+    queueStatus(): QueueStatus;
+    flushQueue(): Promise<void>;
+}
+declare class WhisperAgentRuntime {
+    private readonly args;
+    private readonly bindingStore;
+    private readonly topK;
+    private readonly maxTokens;
+    private readonly targetRetrievalMs;
+    private readonly hardRetrievalTimeoutMs;
+    private readonly recentWorkLimit;
+    private readonly baseContext;
+    private readonly clientName;
+    private bindings;
+    private touchedFiles;
+    private recentWork;
+    private bufferedLowSalience;
+    private lastPreparedTurn;
+    private mergedCount;
+    private droppedCount;
+    private lastScope;
+    constructor(args: {
+        baseContext: AgentRunContext;
+        options: AgentRuntimeOptions;
+        adapter: RuntimeAdapter;
+    });
+    private getBindings;
+    private pushTouchedFiles;
+    private pushWorkEvent;
+    private makeTaskFrameQuery;
+    private resolveScope;
+    private runBranch;
+    private contextItems;
+    private memoryItems;
+    private rerank;
+    private buildContext;
+    bootstrap(context?: Partial<AgentRunContext>): Promise<PreparedTurn>;
+    beforeTurn(input: TurnInput, context?: Partial<AgentRunContext>): Promise<PreparedTurn>;
+    recordWork(event: WorkEvent, context?: Partial<AgentRunContext>): Promise<MemoryWriteAck$1 | {
+        success: true;
+        buffered: true;
+    }>;
+    afterTurn(input: TurnInput & {
+        assistantMessage: string;
+    }, context?: Partial<AgentRunContext>): Promise<TurnCaptureResult>;
+    flush(reason?: string, context?: Partial<AgentRunContext>): Promise<AgentRuntimeStatus>;
+    status(): AgentRuntimeStatus;
+}
+
 interface WhisperClientConfig {
     apiKey: string;
     baseUrl?: string;
@@ -711,8 +923,38 @@ declare class WhisperClient {
     private readonly sessionModule;
     private readonly profileModule;
     private readonly analyticsModule;
+    private readonly projectRefToId;
+    private projectCache;
+    private projectCacheExpiresAt;
     constructor(config: WhisperClientConfig);
     static fromEnv(overrides?: Partial<WhisperClientConfig>): WhisperClient;
+    private createQueueStore;
+    private defaultQueuePersistence;
+    private defaultQueueFilePath;
+    private getRequiredProject;
+    private refreshProjectCache;
+    private fetchResolvedProject;
+    resolveProject(projectRef?: string): Promise<Project>;
+    query(params: QueryParams): Promise<QueryResult>;
+    ingestSession(params: {
+        project?: string;
+        session_id: string;
+        user_id?: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            timestamp: string;
+        }>;
+        async?: boolean;
+        write_mode?: "async" | "sync";
+    }): Promise<{
+        success: boolean;
+        memories_created: number;
+        relations_created: number;
+        memories_invalidated: number;
+        errors?: string[];
+    } & MemoryWriteAck$1>;
+    createAgentRuntime(options?: AgentRuntimeOptions): WhisperAgentRuntime;
     withRunContext(context: RunContext): {
         memory: {
             add: (params: Omit<Parameters<MemoryModule["add"]>[0], "project" | "user_id" | "session_id"> & {
@@ -971,6 +1213,12 @@ interface QueryResult {
         cache_hit: boolean;
         tokens_used: number;
         context_hash: string;
+        source_scope?: {
+            mode: "none" | "explicit" | "auto";
+            source_ids: string[];
+            host?: string;
+            matched_sources?: number;
+        };
         profile?: string;
         compression?: any;
         timing?: {
@@ -1814,4 +2062,4 @@ declare class WhisperContext {
     };
 }
 
-export { type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type MemoryWriteResult, type Project, type QueryParams, type QueryResult, type Source, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };
+export { type AgentRunContext, type AgentRuntimeOptions, type AgentRuntimeStatus, type CanonicalSourceCreateParams, type CanonicalSourceCreateResult, type CanonicalSourceType, type ExtractedMemory, LangChainMemoryAdapter, LangGraphCheckpointAdapter, type Memory, type MemoryExtractionResult, type MemoryKind, type MemoryLatencyBreakdown, type MemorySearchResponse, type MemoryWriteAck, type MemoryWriteResult, type PreparedTurn, type Project, type QueryParams, type QueryResult, type Source, type TurnCaptureResult, type TurnInput, type VideoIngestionStatus, type VideoSourceMetadata, Whisper, WhisperAgentMiddleware, WhisperClient, type WhisperConfig, WhisperContext, Whisper as WhisperDefault, WhisperError, type WhisperErrorCode, WhisperClient as WhisperRuntimeClient, type WorkEvent, type WorkEventKind, type WorkEventSalience, createAgentMiddleware, createLangChainMemoryAdapter, createLangGraphCheckpointAdapter, WhisperContext as default, memoryGraphToMermaid };