@dudko.dev/agent-web 0.0.1 → 0.0.3

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as ai from 'ai';
-import { LanguageModel, ToolSet, Tool, ModelMessage, generateText, streamText, tool } from 'ai';
+import { LanguageModel, ToolSet, Tool, ModelMessage, generateText, streamText } from 'ai';
 import { z, ZodType } from 'zod';
 import { IDBPDatabase } from 'idb';
 
@@ -105,6 +105,11 @@ interface PlannerPromptContext {
     state?: string;
     toolCatalog: string;
     mode: ToolCallMode;
+    /** Prior session messages (oldest first), for resolving references to earlier turns. */
+    history?: {
+        role: string;
+        content: string;
+    }[];
 }
 interface ExecutorPromptContext {
     goal: string;
@@ -242,7 +247,9 @@ interface BrowserAgentConfig {
     clientName?: string;
     /** Host tools the executor may call (an AI SDK ToolSet; use defineTool). */
     tools?: AgentToolSet;
+    /** Whitelist: only these tool names from `tools` are mounted (default: all). */
     availableTools?: string[];
+    /** Blacklist: these tool names are removed after the whitelist is applied. */
     excludedTools?: string[];
     /** Force native/prompted tool-calling; 'auto' picks per model (default 'auto'). */
     toolMode?: ToolMode;
@@ -253,7 +260,11 @@ interface BrowserAgentConfig {
     prompts?: Partial<Prompts>;
     /** Serialize the host's current world state into prompt context (grounding). */
     describeState?: () => string | Promise<string>;
-    /** Persist the transcript (e.g. new IndexedDBStore()). */
+    /**
+     * Persist the transcript (e.g. new IndexedDBStore()). The last few messages
+     * are also read back into the planner prompt, so follow-up goals can refer
+     * to earlier turns.
+     */
     memory?: ContextStore;
     sessionId?: string;
     /** Hard cap on executed steps incl. replans (default 8). */
@@ -486,6 +497,8 @@ interface AgentContext {
     signal?: AbortSignal;
     /** Current world state for grounding, or undefined when no describeState is configured. */
     state: () => Promise<string | undefined>;
+    /** Session transcript loaded from memory BEFORE this run's goal was appended. */
+    history?: StoredMessage[];
 }
 
 /**
@@ -570,8 +583,10 @@ interface ReplanOutcome {
 declare const decideReplan: (ctx: AgentContext, goal: string, done: string[], remaining: string[]) => Promise<ReplanOutcome>;
 
 /**
- * Write the final natural-language summary of what the run accomplished. Plain
- * text only (parsePlainText strips any stray JSON). Falls back to a default
+ * Write the final natural-language summary of what the run accomplished,
+ * streaming it as `final.text-delta` events. Plain text only (parsePlainText
+ * strips any stray JSON; deltas are suppressed entirely when the model drifts
+ * into JSON, so raw structure never reaches a UI). Falls back to a default
  * sentence if the model returns nothing usable.
  */
 declare const synthesizeAnswer: (ctx: AgentContext, goal: string, done: string[]) => Promise<{
@@ -646,6 +661,10 @@ declare const directBrowserOk: (p: ProviderType) => boolean;
  * ever being exposed to JavaScript. Not even in-page script can read it out; it
  * can only be used to encrypt / decrypt. That is what makes at-rest storage of
  * the secrets meaningful (see IndexedDBVault's threat model).
+ *
+ * Concurrent callers share one in-flight promise per DB, and creation is
+ * double-checked in a single IDB transaction, so two racing writers can never
+ * end up encrypting under different keys.
  */
 declare const getOrCreateVaultKey: (dbName?: string) => Promise<CryptoKey>;
 interface EncryptedBlob {
@@ -716,7 +735,10 @@ interface ToolLoopOptions {
     messages?: ModelMessage[];
     /** In native mode: the callable tools. In prompted mode: used to dispatch salvaged calls. */
     tools: ToolSet;
-    /** Native mode: restrict callable tools to these names (plan-narrowed). */
+    /**
+     * Restrict callable tools to these names (plan-narrowed). Native mode passes
+     * them to the SDK's `activeTools`; prompted mode bounds `dispatch` to them.
+     */
     activeTools?: string[];
     /** Native mode: cap on internal tool-calling steps (default 4). */
     maxSteps?: number;
@@ -747,13 +769,17 @@ declare const normalizeUsage: (u?: {
     totalTokens?: number;
 }) => IUsage;
 
-type ToolConfig = Parameters<typeof tool>[0];
 /**
  * Define a host tool. Thin wrapper over the AI SDK `tool()`: pass a
  * `description`, an `inputSchema` (a Zod schema or the result of `jsonSchema()`),
  * and an `execute` function. The returned tool works unchanged on the native
  * tool-calling path.
  *
+ * Generic over INPUT/OUTPUT so the schema's inferred type flows into
+ * `execute(input)` — `Parameters<typeof tool>[0]` must NOT be used here: with
+ * an overloaded `tool()` it resolves to the last overload (`Tool<never, never>`),
+ * which rejects every real schema and types `execute` as `undefined`.
+ *
  * Optionally add `promptHint` — a short parameter hint like
  * "{ text: string, x?: number }" — which the prompted/salvage path shows to
  * weak local models that can't do native function-calling.
@@ -768,7 +794,7 @@ type ToolConfig = Parameters<typeof tool>[0];
  *     }),
  *   }
  */
-declare const defineTool: (config: ToolConfig & {
+declare const defineTool: <INPUT = unknown, OUTPUT = unknown>(config: Tool<INPUT, OUTPUT> & {
     promptHint?: string;
 }) => AgentTool;
 
@@ -795,6 +821,8 @@ declare const dispatch: (action: RawAction, tools: ToolSet, ctx?: DispatchContex
  * Decide the tool-calling strategy for a resolved model. An explicit
  * config.toolMode of 'native'/'prompted' always wins; 'auto' (default) inspects
  * the model's provider id — local/on-device runtimes → 'prompted', cloud → 'native'.
+ * A string model is a gateway model id ("openai/gpt-4o") — always cloud; the
+ * LOCAL_RE must not see it, or model names like "gpt-5-nano" would match `nano`.
  */
 declare const selectToolMode: (model: LanguageModel, mode?: ToolMode) => "native" | "prompted";
 
@@ -823,6 +851,9 @@ interface CompressOptions {
     maxChars?: number;
     /** How many most-recent messages to keep verbatim. */
     keepRecent?: number;
+    /** Time-box the summarisation call so it can never hang the caller. */
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
 }
 /**
  * When the transcript grows too long, summarise everything except the last

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as ai from 'ai';
-import { LanguageModel, ToolSet, Tool, ModelMessage, generateText, streamText, tool } from 'ai';
+import { LanguageModel, ToolSet, Tool, ModelMessage, generateText, streamText } from 'ai';
 import { z, ZodType } from 'zod';
 import { IDBPDatabase } from 'idb';
 
@@ -105,6 +105,11 @@ interface PlannerPromptContext {
     state?: string;
     toolCatalog: string;
     mode: ToolCallMode;
+    /** Prior session messages (oldest first), for resolving references to earlier turns. */
+    history?: {
+        role: string;
+        content: string;
+    }[];
 }
 interface ExecutorPromptContext {
     goal: string;
@@ -242,7 +247,9 @@ interface BrowserAgentConfig {
     clientName?: string;
     /** Host tools the executor may call (an AI SDK ToolSet; use defineTool). */
     tools?: AgentToolSet;
+    /** Whitelist: only these tool names from `tools` are mounted (default: all). */
     availableTools?: string[];
+    /** Blacklist: these tool names are removed after the whitelist is applied. */
     excludedTools?: string[];
     /** Force native/prompted tool-calling; 'auto' picks per model (default 'auto'). */
     toolMode?: ToolMode;
@@ -253,7 +260,11 @@ interface BrowserAgentConfig {
     prompts?: Partial<Prompts>;
     /** Serialize the host's current world state into prompt context (grounding). */
     describeState?: () => string | Promise<string>;
-    /** Persist the transcript (e.g. new IndexedDBStore()). */
+    /**
+     * Persist the transcript (e.g. new IndexedDBStore()). The last few messages
+     * are also read back into the planner prompt, so follow-up goals can refer
+     * to earlier turns.
+     */
     memory?: ContextStore;
     sessionId?: string;
     /** Hard cap on executed steps incl. replans (default 8). */
@@ -486,6 +497,8 @@ interface AgentContext {
     signal?: AbortSignal;
     /** Current world state for grounding, or undefined when no describeState is configured. */
     state: () => Promise<string | undefined>;
+    /** Session transcript loaded from memory BEFORE this run's goal was appended. */
+    history?: StoredMessage[];
 }
 
 /**
@@ -570,8 +583,10 @@ interface ReplanOutcome {
 declare const decideReplan: (ctx: AgentContext, goal: string, done: string[], remaining: string[]) => Promise<ReplanOutcome>;
 
 /**
- * Write the final natural-language summary of what the run accomplished. Plain
- * text only (parsePlainText strips any stray JSON). Falls back to a default
+ * Write the final natural-language summary of what the run accomplished,
+ * streaming it as `final.text-delta` events. Plain text only (parsePlainText
+ * strips any stray JSON; deltas are suppressed entirely when the model drifts
+ * into JSON, so raw structure never reaches a UI). Falls back to a default
  * sentence if the model returns nothing usable.
  */
 declare const synthesizeAnswer: (ctx: AgentContext, goal: string, done: string[]) => Promise<{
@@ -646,6 +661,10 @@ declare const directBrowserOk: (p: ProviderType) => boolean;
  * ever being exposed to JavaScript. Not even in-page script can read it out; it
  * can only be used to encrypt / decrypt. That is what makes at-rest storage of
  * the secrets meaningful (see IndexedDBVault's threat model).
+ *
+ * Concurrent callers share one in-flight promise per DB, and creation is
+ * double-checked in a single IDB transaction, so two racing writers can never
+ * end up encrypting under different keys.
  */
 declare const getOrCreateVaultKey: (dbName?: string) => Promise<CryptoKey>;
 interface EncryptedBlob {
@@ -716,7 +735,10 @@ interface ToolLoopOptions {
     messages?: ModelMessage[];
     /** In native mode: the callable tools. In prompted mode: used to dispatch salvaged calls. */
     tools: ToolSet;
-    /** Native mode: restrict callable tools to these names (plan-narrowed). */
+    /**
+     * Restrict callable tools to these names (plan-narrowed). Native mode passes
+     * them to the SDK's `activeTools`; prompted mode bounds `dispatch` to them.
+     */
     activeTools?: string[];
     /** Native mode: cap on internal tool-calling steps (default 4). */
     maxSteps?: number;
@@ -747,13 +769,17 @@ declare const normalizeUsage: (u?: {
     totalTokens?: number;
 }) => IUsage;
 
-type ToolConfig = Parameters<typeof tool>[0];
 /**
  * Define a host tool. Thin wrapper over the AI SDK `tool()`: pass a
  * `description`, an `inputSchema` (a Zod schema or the result of `jsonSchema()`),
  * and an `execute` function. The returned tool works unchanged on the native
  * tool-calling path.
  *
+ * Generic over INPUT/OUTPUT so the schema's inferred type flows into
+ * `execute(input)` — `Parameters<typeof tool>[0]` must NOT be used here: with
+ * an overloaded `tool()` it resolves to the last overload (`Tool<never, never>`),
+ * which rejects every real schema and types `execute` as `undefined`.
+ *
  * Optionally add `promptHint` — a short parameter hint like
  * "{ text: string, x?: number }" — which the prompted/salvage path shows to
  * weak local models that can't do native function-calling.
@@ -768,7 +794,7 @@ type ToolConfig = Parameters<typeof tool>[0];
  *     }),
  *   }
  */
-declare const defineTool: (config: ToolConfig & {
+declare const defineTool: <INPUT = unknown, OUTPUT = unknown>(config: Tool<INPUT, OUTPUT> & {
     promptHint?: string;
 }) => AgentTool;
 
@@ -795,6 +821,8 @@ declare const dispatch: (action: RawAction, tools: ToolSet, ctx?: DispatchContex
  * Decide the tool-calling strategy for a resolved model. An explicit
  * config.toolMode of 'native'/'prompted' always wins; 'auto' (default) inspects
  * the model's provider id — local/on-device runtimes → 'prompted', cloud → 'native'.
+ * A string model is a gateway model id ("openai/gpt-4o") — always cloud; the
+ * LOCAL_RE must not see it, or model names like "gpt-5-nano" would match `nano`.
  */
 declare const selectToolMode: (model: LanguageModel, mode?: ToolMode) => "native" | "prompted";
 
@@ -823,6 +851,9 @@ interface CompressOptions {
     maxChars?: number;
     /** How many most-recent messages to keep verbatim. */
     keepRecent?: number;
+    /** Time-box the summarisation call so it can never hang the caller. */
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
 }
 /**
  * When the transcript grows too long, summarise everything except the last