@usewhisper/sdk 3.5.0 → 3.7.0

package/README.md

@@ -1,6 +1,15 @@
-# @usewhisper/sdk
-
-Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give your AI agents perfect context.
+# @usewhisper/sdk
+
+Official TypeScript SDK for [Whisper Context API](https://usewhisper.dev) - Give your AI agents perfect context.
+
+`WhisperClient` is the primary SDK surface. `WhisperContext` remains available for compatibility, but automatic memory/retrieval behavior now lives in `WhisperClient.createAgentRuntime()`.
+
+## What's New in v3.6
+
+- Automatic runtime for scope resolution, pre-retrieval, session continuity, and background capture.
+- Legacy wrapper turn helpers now run through the automatic runtime by default.
+- Context query responses expose `meta.source_scope`.
+- URL/domain queries automatically narrow to matching sources when possible.
 
 ## Installation
 
@@ -10,64 +19,57 @@ npm install @usewhisper/sdk
 
 ## Quick Start
 
-```typescript
-import { WhisperContext } from '@usewhisper/sdk';
-
-const whisper = new WhisperContext({ 
-  apiKey: 'wsk_your_api_key_here'
-});
-
-// Create a project
-const project = await whisper.createProject({
-  name: 'my-docs',
-  description: 'Documentation context'
-});
-
-// Ingest documents
-await whisper.ingest(project.id, [
-  {
-    title: 'Authentication Guide',
-    content: 'To authenticate users, use JWT tokens...',
-    metadata: { category: 'auth' }
-  }
-]);
-
-// Query context
-const result = await whisper.query({
-  project: 'my-docs',
-  query: 'How do I authenticate users?',
-  top_k: 5
-});
-
-console.log(result.context);
-```
+```typescript
+import { WhisperClient } from '@usewhisper/sdk';
+
+const client = new WhisperClient({
+  apiKey: 'wsk_your_api_key_here',
+  project: 'my-docs'
+});
+
+const runtime = client.createAgentRuntime({
+  workspacePath: process.cwd(),
+  userId: 'user-123',
+  sessionId: 'session-abc',
+  clientName: 'my-agent-host'
+});
+
+const prepared = await runtime.beforeTurn({
+  userMessage: 'How do I authenticate users?'
+});
+
+console.log(prepared.context);
+```
 
 ## Authentication
 
 Get your API key from the [Whisper dashboard](https://usewhisper.dev/dashboard):
 
 ```typescript
-const whisper = new WhisperContext({
-  apiKey: 'wsk_...',  // Your API key
-  baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
-});
-```
+const client = new WhisperClient({
+  apiKey: 'wsk_...',  // Your API key
+  baseUrl: 'https://context.usewhisper.dev'  // Optional, defaults to production
+});
+```
 
 ## Core Features
 
 ### Context Query
 
 ```typescript
-const result = await whisper.query({
-  project: 'my-docs',
-  query: 'Your question here',
-  top_k: 10,              // Number of results
-  include_memories: true,  // Include conversational memory
-  include_graph: true,     // Include knowledge graph
-  hybrid: true,            // Hybrid vector + keyword search
-  rerank: true            // Rerank results for better relevance
-});
-```
+const result = await client.query({
+  project: 'my-docs',
+  query: 'Your question here',
+  top_k: 10,              // Number of results
+  source_ids: ['src_abc'], // Optional explicit source isolation
+  include_memories: true,  // Include conversational memory
+  include_graph: true,     // Include knowledge graph
+  hybrid: true,            // Hybrid vector + keyword search
+  rerank: true            // Rerank results for better relevance
+});
+
+console.log(result.meta.source_scope);
+```
 
 ### Project Management
 

package/index.d.mts

@@ -77,6 +77,7 @@ interface RememberResult {
  */
 declare class Whisper {
     private client;
+    private runtimeClient;
     private options;
     private sessionId?;
     private userId?;
@@ -660,6 +661,13 @@ interface PreparedTurn {
         targetBudgetMs: number;
         hardTimeoutMs: number;
         branchStatus: Record<string, "ok" | "error" | "timeout" | "skipped">;
+        focusedScopeApplied: boolean;
+        focusedSourceIds: string[];
+        focusedFileHints: string[];
+        clientScoped: boolean;
+        fallbackUsed: boolean;
+        droppedBelowFloor: number;
+        dedupedCount: number;
     };
     context: string;
     items: Array<{
@@ -701,8 +709,43 @@ interface AgentRuntimeStatus {
         mergedCount: number;
         droppedCount: number;
         bufferedLowSalience: number;
+        focusedPassHits: number;
+        fallbackTriggers: number;
+        floorDroppedCount: number;
+        injectedItemCount: number;
+        sourceScopedTurns: number;
+        broadScopedTurns: number;
+        totalTurns: number;
     };
 }
+interface AgentRuntimeRankWeights {
+    focusedPassBonus?: number;
+    sourceMatchBonus?: number;
+    touchedFileBonus?: number;
+    clientMatchBonus?: number;
+    highSalienceBonus?: number;
+    mediumSalienceBonus?: number;
+    staleBroadPenalty?: number;
+    unrelatedClientPenalty?: number;
+    lowSaliencePenalty?: number;
+}
+interface AgentRuntimeSourceActivityOptions {
+    maxTurns?: number;
+    maxIdleMs?: number;
+    decayAfterTurns?: number;
+    decayAfterIdleMs?: number;
+    evictOnTaskSwitch?: boolean;
+}
+interface AgentRuntimeRetrievalOptions {
+    focusedTopK?: number;
+    broadTopK?: number;
+    minFocusedResults?: number;
+    minFocusedTopScore?: number;
+    minProjectScore?: number;
+    minMemoryScore?: number;
+    rankWeights?: AgentRuntimeRankWeights;
+    sourceActivity?: AgentRuntimeSourceActivityOptions;
+}
 interface AgentRuntimeOptions extends AgentRunContext {
     topK?: number;
     maxTokens?: number;
@@ -710,6 +753,7 @@ interface AgentRuntimeOptions extends AgentRunContext {
     hardRetrievalTimeoutMs?: number;
     bindingStorePath?: string;
     recentWorkLimit?: number;
+    retrieval?: AgentRuntimeRetrievalOptions;
 }
 interface QueueStatus {
     queued: number;
@@ -786,20 +830,37 @@ interface RuntimeAdapter {
 declare class WhisperAgentRuntime {
     private readonly args;
     private readonly bindingStore;
-    private readonly topK;
+    private readonly focusedTopK;
+    private readonly broadTopK;
     private readonly maxTokens;
     private readonly targetRetrievalMs;
     private readonly hardRetrievalTimeoutMs;
     private readonly recentWorkLimit;
     private readonly baseContext;
     private readonly clientName;
+    private readonly minFocusedResults;
+    private readonly minFocusedTopScore;
+    private readonly minProjectScore;
+    private readonly minMemoryScore;
+    private readonly rankWeights;
+    private readonly sourceActivityOptions;
     private bindings;
     private touchedFiles;
     private recentWork;
+    private recentSourceActivity;
     private bufferedLowSalience;
     private lastPreparedTurn;
     private mergedCount;
     private droppedCount;
+    private focusedPassHits;
+    private fallbackTriggers;
+    private floorDroppedCount;
+    private injectedItemCount;
+    private sourceScopedTurns;
+    private broadScopedTurns;
+    private totalTurns;
+    private currentTurn;
+    private lastTaskSummary;
     private lastScope;
     constructor(args: {
         baseContext: AgentRunContext;
@@ -809,11 +870,24 @@ declare class WhisperAgentRuntime {
     private getBindings;
     private pushTouchedFiles;
     private pushWorkEvent;
+    noteSourceActivity(sourceIds?: string[]): void;
+    private refreshTaskSummary;
+    private activeSourceIds;
+    private focusedScope;
+    private exactFileMetadataFilter;
     private makeTaskFrameQuery;
     private resolveScope;
     private runBranch;
     private contextItems;
     private memoryItems;
+    private stableItemKey;
+    private metadataStrings;
+    private hasSourceMatch;
+    private hasFileMatch;
+    private hasClientMatch;
+    private salienceAdjustment;
+    private narrowFocusedMemories;
+    private applyRelevanceFloor;
     private rerank;
     private buildContext;
     bootstrap(context?: Partial<AgentRunContext>): Promise<PreparedTurn>;
@@ -1178,6 +1252,7 @@ interface QueryParams {
     threshold?: number;
     chunk_types?: string[];
     source_ids?: string[];
+    metadata_filter?: Record<string, any>;
     hybrid?: boolean;
     vector_weight?: number;
     bm25_weight?: number;
@@ -1212,6 +1287,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?: {
@@ -2055,4 +2136,4 @@ declare class WhisperContext {
     };
 }
 
-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 };
+export { type AgentRunContext, type AgentRuntimeOptions, type AgentRuntimeRankWeights, type AgentRuntimeRetrievalOptions, type AgentRuntimeSourceActivityOptions, 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?;
@@ -660,6 +661,13 @@ interface PreparedTurn {
         targetBudgetMs: number;
         hardTimeoutMs: number;
         branchStatus: Record<string, "ok" | "error" | "timeout" | "skipped">;
+        focusedScopeApplied: boolean;
+        focusedSourceIds: string[];
+        focusedFileHints: string[];
+        clientScoped: boolean;
+        fallbackUsed: boolean;
+        droppedBelowFloor: number;
+        dedupedCount: number;
     };
     context: string;
     items: Array<{
@@ -701,8 +709,43 @@ interface AgentRuntimeStatus {
         mergedCount: number;
         droppedCount: number;
         bufferedLowSalience: number;
+        focusedPassHits: number;
+        fallbackTriggers: number;
+        floorDroppedCount: number;
+        injectedItemCount: number;
+        sourceScopedTurns: number;
+        broadScopedTurns: number;
+        totalTurns: number;
     };
 }
+interface AgentRuntimeRankWeights {
+    focusedPassBonus?: number;
+    sourceMatchBonus?: number;
+    touchedFileBonus?: number;
+    clientMatchBonus?: number;
+    highSalienceBonus?: number;
+    mediumSalienceBonus?: number;
+    staleBroadPenalty?: number;
+    unrelatedClientPenalty?: number;
+    lowSaliencePenalty?: number;
+}
+interface AgentRuntimeSourceActivityOptions {
+    maxTurns?: number;
+    maxIdleMs?: number;
+    decayAfterTurns?: number;
+    decayAfterIdleMs?: number;
+    evictOnTaskSwitch?: boolean;
+}
+interface AgentRuntimeRetrievalOptions {
+    focusedTopK?: number;
+    broadTopK?: number;
+    minFocusedResults?: number;
+    minFocusedTopScore?: number;
+    minProjectScore?: number;
+    minMemoryScore?: number;
+    rankWeights?: AgentRuntimeRankWeights;
+    sourceActivity?: AgentRuntimeSourceActivityOptions;
+}
 interface AgentRuntimeOptions extends AgentRunContext {
     topK?: number;
     maxTokens?: number;
@@ -710,6 +753,7 @@ interface AgentRuntimeOptions extends AgentRunContext {
     hardRetrievalTimeoutMs?: number;
     bindingStorePath?: string;
     recentWorkLimit?: number;
+    retrieval?: AgentRuntimeRetrievalOptions;
 }
 interface QueueStatus {
     queued: number;
@@ -786,20 +830,37 @@ interface RuntimeAdapter {
 declare class WhisperAgentRuntime {
     private readonly args;
     private readonly bindingStore;
-    private readonly topK;
+    private readonly focusedTopK;
+    private readonly broadTopK;
     private readonly maxTokens;
     private readonly targetRetrievalMs;
     private readonly hardRetrievalTimeoutMs;
     private readonly recentWorkLimit;
     private readonly baseContext;
     private readonly clientName;
+    private readonly minFocusedResults;
+    private readonly minFocusedTopScore;
+    private readonly minProjectScore;
+    private readonly minMemoryScore;
+    private readonly rankWeights;
+    private readonly sourceActivityOptions;
     private bindings;
     private touchedFiles;
     private recentWork;
+    private recentSourceActivity;
     private bufferedLowSalience;
     private lastPreparedTurn;
     private mergedCount;
     private droppedCount;
+    private focusedPassHits;
+    private fallbackTriggers;
+    private floorDroppedCount;
+    private injectedItemCount;
+    private sourceScopedTurns;
+    private broadScopedTurns;
+    private totalTurns;
+    private currentTurn;
+    private lastTaskSummary;
     private lastScope;
     constructor(args: {
         baseContext: AgentRunContext;
@@ -809,11 +870,24 @@ declare class WhisperAgentRuntime {
     private getBindings;
     private pushTouchedFiles;
     private pushWorkEvent;
+    noteSourceActivity(sourceIds?: string[]): void;
+    private refreshTaskSummary;
+    private activeSourceIds;
+    private focusedScope;
+    private exactFileMetadataFilter;
     private makeTaskFrameQuery;
     private resolveScope;
     private runBranch;
     private contextItems;
     private memoryItems;
+    private stableItemKey;
+    private metadataStrings;
+    private hasSourceMatch;
+    private hasFileMatch;
+    private hasClientMatch;
+    private salienceAdjustment;
+    private narrowFocusedMemories;
+    private applyRelevanceFloor;
     private rerank;
     private buildContext;
     bootstrap(context?: Partial<AgentRunContext>): Promise<PreparedTurn>;
@@ -1178,6 +1252,7 @@ interface QueryParams {
     threshold?: number;
     chunk_types?: string[];
     source_ids?: string[];
+    metadata_filter?: Record<string, any>;
     hybrid?: boolean;
     vector_weight?: number;
     bm25_weight?: number;
@@ -1212,6 +1287,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?: {
@@ -2055,4 +2136,4 @@ declare class WhisperContext {
     };
 }
 
-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 };
+export { type AgentRunContext, type AgentRuntimeOptions, type AgentRuntimeRankWeights, type AgentRuntimeRetrievalOptions, type AgentRuntimeSourceActivityOptions, 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 };