@dudko.dev/agent-web 0.0.3 → 0.0.5

package/dist/index.d.cts

@@ -24,6 +24,29 @@ declare class MemoryStore implements ContextStore {
     clear(sessionId: string): Promise<void>;
 }
 
+/**
+ * Leveled logging for the agent. The host passes a console-like sink and a
+ * level; everything below the level is a no-op. Default: 'warn' onto the
+ * global console — silent in normal operation, but salvage fallbacks, empty
+ * plans, degraded tool modes and failed tool calls stay visible.
+ *
+ * Set `logLevel: 'debug'` to see every phase's raw model output, parsed
+ * results and tool dispatches — the first thing to reach for when the agent
+ * "says it did something but nothing happened".
+ */
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/** Console-compatible sink (pass `console`, or your own collector). */
+interface AgentLoggerSink {
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+interface AgentLogger extends AgentLoggerSink {
+    readonly level: LogLevel;
+}
+declare const createLogger: (level?: LogLevel, sink?: AgentLoggerSink) => AgentLogger;
+
 /**
  * Providers the browser registry can resolve from a spec. This is deliberately
  * a browser-safe subset of the Node sibling's list: Amazon Bedrock (SigV4
@@ -283,6 +306,10 @@ interface BrowserAgentConfig {
     synthesize?: boolean;
     /** Compress stored history past this many chars (0 = off, default 12000). */
     compressAfterChars?: number;
+    /** Verbosity: 'silent' | 'error' | 'warn' (default) | 'info' | 'debug'. */
+    logLevel?: LogLevel;
+    /** Console-like sink the logs go to (default: the global console). */
+    logger?: AgentLoggerSink;
 }
 interface ResolvedConfig {
     clientName: string;
@@ -298,6 +325,7 @@ interface ResolvedConfig {
     replan: boolean;
     synthesize: boolean;
     compressAfterChars: number;
+    logLevel: LogLevel;
 }
 declare const resolveConfig: (c: BrowserAgentConfig) => ResolvedConfig;
 
@@ -494,6 +522,8 @@ interface AgentContext {
     toolCatalog: string;
     prompts: Prompts;
     emit: (event: AgentEvent) => void;
+    /** Leveled logger (config.logLevel over config.logger ?? console). */
+    log: AgentLogger;
     signal?: AbortSignal;
     /** Current world state for grounding, or undefined when no describeState is configured. */
     state: () => Promise<string | undefined>;
@@ -508,7 +538,9 @@ interface AgentContext {
  * throwing, so the run degrades gracefully. An empty `steps` list signals the
  * runner to answer directly (greeting / question / unclear).
  */
-declare const createPlan: (ctx: AgentContext, goal: string) => Promise<{
+declare const createPlan: (ctx: AgentContext, goal: string, 
+/** Extra instruction appended to the goal (used by the empty-plan retry). */
+nudge?: string) => Promise<{
     plan: IPlan;
     usage: IUsage;
 }>;
@@ -624,14 +656,45 @@ interface WebLLMModelOptions {
         progress: number;
         text: string;
     }) => void;
+    /**
+     * Download the weights and initialize the engine NOW (default true).
+     *
+     * The underlying provider initializes lazily on the first generation — with
+     * a multi-GB model that means the download would silently happen on the
+     * user's first message, with `initProgressCallback` never firing at a moment
+     * the host can show it. Preloading runs a 1-token warm-up so the returned
+     * model is truly ready and progress is reported during creation. Re-creating
+     * an already-downloaded model is fast (weights live in the browser cache).
+     *
+     * Set to `false` to keep the lazy behavior.
+     */
+    preload?: boolean;
     /** Any other @browser-ai/web-llm setting (temperature, worker handler, …). */
     [k: string]: unknown;
 }
+/**
+ * Force a model to download its weights and initialize its engine by running
+ * a 1-token generation. Exposed for hosts that create models with
+ * `preload: false` and want to warm them up later (e.g. behind their own UI).
+ */
+declare const preloadWebLLMModel: (model: LanguageModel) => Promise<void>;
+/**
+ * Best-effort release of a model's GPU memory (call when switching models —
+ * an abandoned engine otherwise holds its buffers until the page reloads).
+ *
+ * `@browser-ai/web-llm` keeps its MLCEngine private and exposes no public
+ * `unload()`, so this reaches into the instance defensively; it is a no-op on
+ * an uninitialized model or if the provider's internals change shape.
+ */
+declare const unloadWebLLMModel: (model: LanguageModel) => Promise<void>;
 /**
  * Build an AI SDK `LanguageModel` backed by WebLLM (WebGPU) via the community
  * provider `@browser-ai/web-llm` (an optional peer, dynamically imported so it
  * is code-split and never loads until a local model is actually used). Accepts
  * any WebLLM prebuilt model id, e.g. "Llama-3.2-3B-Instruct-q4f16_1-MLC".
+ *
+ * By default the weights are downloaded eagerly with progress (see
+ * `WebLLMModelOptions.preload`).
  */
 declare const createWebLLMModel: (model: string, options?: WebLLMModelOptions) => Promise<LanguageModel>;
 
@@ -863,4 +926,4 @@ interface CompressOptions {
  */
 declare const compressHistory: (messages: StoredMessage[], model: LanguageModel, opts?: CompressOptions) => Promise<StoredMessage[]>;
 
-export { type Agent, type AgentContext, type AgentEvent, type AgentEventHandler, type AgentTool, type AgentToolSet, type AgentWebDBOptions, type BrowserAgentConfig, type CompressOptions, type ContextStore, type CredentialStore, type EncryptedBlob, type ExecutorPromptContext, type ExecutorResult, type GenerateOptions, type IPlan, type IPlanStep, type IStepResult, type IToolCall, type IUsage, IndexedDBStore, type IndexedDBStoreOptions, IndexedDBVault, KEYS_STORE, MemoryCredentialStore, MemoryStore, type ModelInput, type Phase, type PhaseBudgets, PlanSchema, type PlanShape, PlanStepSchema, type PlannerPromptContext, type PlannerResult, type PromptParts, type Prompts, type ProviderModelSpec, type ProviderType, type RawAction, type ReplanDecision, type ReplanMode, ReplanSchema, type ReplanShape, type ReplannerPromptContext, type ReplannerResult, type ResolvedConfig, type ResolvedStage, type RunOptions, type RunResult, SECRETS_STORE, SESSIONS_STORE, type StageInput, type StageOverride, type StoredMessage, type SynthesizerPromptContext, type ToolCallMode, type ToolLoopCallbacks, type ToolLoopOptions, type ToolLoopResult, type ToolMode, type ToolSelectionStrategy, VaultCredentialStore, type VaultOptions, type WebLLMModelOptions, buildModelFromStage, compressHistory, createAgent, createPlan, createWebLLMModel, decideReplan, decryptJSON, defaultPrompts, defineTool, directBrowserOk, dispatch, encryptJSON, executeStep, generate, generateStructured, getOrCreateVaultKey, isDirectModel, isProviderSpec, isWebGPUAvailable, looksLikeJson, normalizeSteps, normalizeUsage, openAgentWebDB, parseExecutorResponse, parsePlainText, parsePlannerResponse, parseReplannerResponse, promptHintOf, renderCatalog, resolveConfig, resolveModel, resolveStage, runToolLoop, selectToolMode, shouldReplan, splitBlocker, stream, supportsNativeTools, supportsStructuredOutput, synthesizeAnswer, withSystem };
+export { type Agent, type AgentContext, type AgentEvent, type AgentEventHandler, type AgentLogger, type AgentLoggerSink, type AgentTool, type AgentToolSet, type AgentWebDBOptions, type BrowserAgentConfig, type CompressOptions, type ContextStore, type CredentialStore, type EncryptedBlob, type ExecutorPromptContext, type ExecutorResult, type GenerateOptions, type IPlan, type IPlanStep, type IStepResult, type IToolCall, type IUsage, IndexedDBStore, type IndexedDBStoreOptions, IndexedDBVault, KEYS_STORE, type LogLevel, MemoryCredentialStore, MemoryStore, type ModelInput, type Phase, type PhaseBudgets, PlanSchema, type PlanShape, PlanStepSchema, type PlannerPromptContext, type PlannerResult, type PromptParts, type Prompts, type ProviderModelSpec, type ProviderType, type RawAction, type ReplanDecision, type ReplanMode, ReplanSchema, type ReplanShape, type ReplannerPromptContext, type ReplannerResult, type ResolvedConfig, type ResolvedStage, type RunOptions, type RunResult, SECRETS_STORE, SESSIONS_STORE, type StageInput, type StageOverride, type StoredMessage, type SynthesizerPromptContext, type ToolCallMode, type ToolLoopCallbacks, type ToolLoopOptions, type ToolLoopResult, type ToolMode, type ToolSelectionStrategy, VaultCredentialStore, type VaultOptions, type WebLLMModelOptions, buildModelFromStage, compressHistory, createAgent, createLogger, createPlan, createWebLLMModel, decideReplan, decryptJSON, defaultPrompts, defineTool, directBrowserOk, dispatch, encryptJSON, executeStep, generate, generateStructured, getOrCreateVaultKey, isDirectModel, isProviderSpec, isWebGPUAvailable, looksLikeJson, normalizeSteps, normalizeUsage, openAgentWebDB, parseExecutorResponse, parsePlainText, parsePlannerResponse, parseReplannerResponse, preloadWebLLMModel, promptHintOf, renderCatalog, resolveConfig, resolveModel, resolveStage, runToolLoop, selectToolMode, shouldReplan, splitBlocker, stream, supportsNativeTools, supportsStructuredOutput, synthesizeAnswer, unloadWebLLMModel, withSystem };

package/dist/index.d.ts

@@ -24,6 +24,29 @@ declare class MemoryStore implements ContextStore {
     clear(sessionId: string): Promise<void>;
 }
 
+/**
+ * Leveled logging for the agent. The host passes a console-like sink and a
+ * level; everything below the level is a no-op. Default: 'warn' onto the
+ * global console — silent in normal operation, but salvage fallbacks, empty
+ * plans, degraded tool modes and failed tool calls stay visible.
+ *
+ * Set `logLevel: 'debug'` to see every phase's raw model output, parsed
+ * results and tool dispatches — the first thing to reach for when the agent
+ * "says it did something but nothing happened".
+ */
+type LogLevel = 'silent' | 'error' | 'warn' | 'info' | 'debug';
+/** Console-compatible sink (pass `console`, or your own collector). */
+interface AgentLoggerSink {
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+interface AgentLogger extends AgentLoggerSink {
+    readonly level: LogLevel;
+}
+declare const createLogger: (level?: LogLevel, sink?: AgentLoggerSink) => AgentLogger;
+
 /**
  * Providers the browser registry can resolve from a spec. This is deliberately
  * a browser-safe subset of the Node sibling's list: Amazon Bedrock (SigV4
@@ -283,6 +306,10 @@ interface BrowserAgentConfig {
     synthesize?: boolean;
     /** Compress stored history past this many chars (0 = off, default 12000). */
     compressAfterChars?: number;
+    /** Verbosity: 'silent' | 'error' | 'warn' (default) | 'info' | 'debug'. */
+    logLevel?: LogLevel;
+    /** Console-like sink the logs go to (default: the global console). */
+    logger?: AgentLoggerSink;
 }
 interface ResolvedConfig {
     clientName: string;
@@ -298,6 +325,7 @@ interface ResolvedConfig {
     replan: boolean;
     synthesize: boolean;
     compressAfterChars: number;
+    logLevel: LogLevel;
 }
 declare const resolveConfig: (c: BrowserAgentConfig) => ResolvedConfig;
 
@@ -494,6 +522,8 @@ interface AgentContext {
     toolCatalog: string;
     prompts: Prompts;
     emit: (event: AgentEvent) => void;
+    /** Leveled logger (config.logLevel over config.logger ?? console). */
+    log: AgentLogger;
     signal?: AbortSignal;
     /** Current world state for grounding, or undefined when no describeState is configured. */
     state: () => Promise<string | undefined>;
@@ -508,7 +538,9 @@ interface AgentContext {
  * throwing, so the run degrades gracefully. An empty `steps` list signals the
  * runner to answer directly (greeting / question / unclear).
  */
-declare const createPlan: (ctx: AgentContext, goal: string) => Promise<{
+declare const createPlan: (ctx: AgentContext, goal: string, 
+/** Extra instruction appended to the goal (used by the empty-plan retry). */
+nudge?: string) => Promise<{
     plan: IPlan;
     usage: IUsage;
 }>;
@@ -624,14 +656,45 @@ interface WebLLMModelOptions {
         progress: number;
         text: string;
     }) => void;
+    /**
+     * Download the weights and initialize the engine NOW (default true).
+     *
+     * The underlying provider initializes lazily on the first generation — with
+     * a multi-GB model that means the download would silently happen on the
+     * user's first message, with `initProgressCallback` never firing at a moment
+     * the host can show it. Preloading runs a 1-token warm-up so the returned
+     * model is truly ready and progress is reported during creation. Re-creating
+     * an already-downloaded model is fast (weights live in the browser cache).
+     *
+     * Set to `false` to keep the lazy behavior.
+     */
+    preload?: boolean;
     /** Any other @browser-ai/web-llm setting (temperature, worker handler, …). */
     [k: string]: unknown;
 }
+/**
+ * Force a model to download its weights and initialize its engine by running
+ * a 1-token generation. Exposed for hosts that create models with
+ * `preload: false` and want to warm them up later (e.g. behind their own UI).
+ */
+declare const preloadWebLLMModel: (model: LanguageModel) => Promise<void>;
+/**
+ * Best-effort release of a model's GPU memory (call when switching models —
+ * an abandoned engine otherwise holds its buffers until the page reloads).
+ *
+ * `@browser-ai/web-llm` keeps its MLCEngine private and exposes no public
+ * `unload()`, so this reaches into the instance defensively; it is a no-op on
+ * an uninitialized model or if the provider's internals change shape.
+ */
+declare const unloadWebLLMModel: (model: LanguageModel) => Promise<void>;
 /**
  * Build an AI SDK `LanguageModel` backed by WebLLM (WebGPU) via the community
  * provider `@browser-ai/web-llm` (an optional peer, dynamically imported so it
  * is code-split and never loads until a local model is actually used). Accepts
  * any WebLLM prebuilt model id, e.g. "Llama-3.2-3B-Instruct-q4f16_1-MLC".
+ *
+ * By default the weights are downloaded eagerly with progress (see
+ * `WebLLMModelOptions.preload`).
  */
 declare const createWebLLMModel: (model: string, options?: WebLLMModelOptions) => Promise<LanguageModel>;
 
@@ -863,4 +926,4 @@ interface CompressOptions {
  */
 declare const compressHistory: (messages: StoredMessage[], model: LanguageModel, opts?: CompressOptions) => Promise<StoredMessage[]>;
 
-export { type Agent, type AgentContext, type AgentEvent, type AgentEventHandler, type AgentTool, type AgentToolSet, type AgentWebDBOptions, type BrowserAgentConfig, type CompressOptions, type ContextStore, type CredentialStore, type EncryptedBlob, type ExecutorPromptContext, type ExecutorResult, type GenerateOptions, type IPlan, type IPlanStep, type IStepResult, type IToolCall, type IUsage, IndexedDBStore, type IndexedDBStoreOptions, IndexedDBVault, KEYS_STORE, MemoryCredentialStore, MemoryStore, type ModelInput, type Phase, type PhaseBudgets, PlanSchema, type PlanShape, PlanStepSchema, type PlannerPromptContext, type PlannerResult, type PromptParts, type Prompts, type ProviderModelSpec, type ProviderType, type RawAction, type ReplanDecision, type ReplanMode, ReplanSchema, type ReplanShape, type ReplannerPromptContext, type ReplannerResult, type ResolvedConfig, type ResolvedStage, type RunOptions, type RunResult, SECRETS_STORE, SESSIONS_STORE, type StageInput, type StageOverride, type StoredMessage, type SynthesizerPromptContext, type ToolCallMode, type ToolLoopCallbacks, type ToolLoopOptions, type ToolLoopResult, type ToolMode, type ToolSelectionStrategy, VaultCredentialStore, type VaultOptions, type WebLLMModelOptions, buildModelFromStage, compressHistory, createAgent, createPlan, createWebLLMModel, decideReplan, decryptJSON, defaultPrompts, defineTool, directBrowserOk, dispatch, encryptJSON, executeStep, generate, generateStructured, getOrCreateVaultKey, isDirectModel, isProviderSpec, isWebGPUAvailable, looksLikeJson, normalizeSteps, normalizeUsage, openAgentWebDB, parseExecutorResponse, parsePlainText, parsePlannerResponse, parseReplannerResponse, promptHintOf, renderCatalog, resolveConfig, resolveModel, resolveStage, runToolLoop, selectToolMode, shouldReplan, splitBlocker, stream, supportsNativeTools, supportsStructuredOutput, synthesizeAnswer, withSystem };
+export { type Agent, type AgentContext, type AgentEvent, type AgentEventHandler, type AgentLogger, type AgentLoggerSink, type AgentTool, type AgentToolSet, type AgentWebDBOptions, type BrowserAgentConfig, type CompressOptions, type ContextStore, type CredentialStore, type EncryptedBlob, type ExecutorPromptContext, type ExecutorResult, type GenerateOptions, type IPlan, type IPlanStep, type IStepResult, type IToolCall, type IUsage, IndexedDBStore, type IndexedDBStoreOptions, IndexedDBVault, KEYS_STORE, type LogLevel, MemoryCredentialStore, MemoryStore, type ModelInput, type Phase, type PhaseBudgets, PlanSchema, type PlanShape, PlanStepSchema, type PlannerPromptContext, type PlannerResult, type PromptParts, type Prompts, type ProviderModelSpec, type ProviderType, type RawAction, type ReplanDecision, type ReplanMode, ReplanSchema, type ReplanShape, type ReplannerPromptContext, type ReplannerResult, type ResolvedConfig, type ResolvedStage, type RunOptions, type RunResult, SECRETS_STORE, SESSIONS_STORE, type StageInput, type StageOverride, type StoredMessage, type SynthesizerPromptContext, type ToolCallMode, type ToolLoopCallbacks, type ToolLoopOptions, type ToolLoopResult, type ToolMode, type ToolSelectionStrategy, VaultCredentialStore, type VaultOptions, type WebLLMModelOptions, buildModelFromStage, compressHistory, createAgent, createLogger, createPlan, createWebLLMModel, decideReplan, decryptJSON, defaultPrompts, defineTool, directBrowserOk, dispatch, encryptJSON, executeStep, generate, generateStructured, getOrCreateVaultKey, isDirectModel, isProviderSpec, isWebGPUAvailable, looksLikeJson, normalizeSteps, normalizeUsage, openAgentWebDB, parseExecutorResponse, parsePlainText, parsePlannerResponse, parseReplannerResponse, preloadWebLLMModel, promptHintOf, renderCatalog, resolveConfig, resolveModel, resolveStage, runToolLoop, selectToolMode, shouldReplan, splitBlocker, stream, supportsNativeTools, supportsStructuredOutput, synthesizeAnswer, unloadWebLLMModel, withSystem };

package/dist/index.js

@@ -1,7 +1,9 @@
 import {
   createWebLLMModel,
-  isWebGPUAvailable
-} from "./chunk-R7H4HSYT.js";
+  isWebGPUAvailable,
+  preloadWebLLMModel,
+  unloadWebLLMModel
+} from "./chunk-IT65EW77.js";
 
 // src/config.ts
 var resolveConfig = (c) => ({
@@ -22,7 +24,8 @@ var resolveConfig = (c) => ({
   temperature: c.temperature,
   replan: c.replan ?? true,
   synthesize: c.synthesize ?? true,
-  compressAfterChars: c.compressAfterChars ?? 12e3
+  compressAfterChars: c.compressAfterChars ?? 12e3,
+  logLevel: c.logLevel ?? "warn"
 });
 
 // src/llm/generate.ts
@@ -130,6 +133,7 @@ var PROVIDER_PACKAGE = {
 var loadProvider = async (pkg) => {
   try {
     return await import(
+      /* webpackIgnore: true */
       /* @vite-ignore */
       pkg
     );
@@ -210,7 +214,7 @@ var buildModelFromStage = async (resolved, credentials, clientName = "agent-web"
   const apiKey = await resolveApiKey(spec, credentials);
   switch (spec.providerType) {
     case "web-llm": {
-      const { createWebLLMModel: createWebLLMModel2 } = await import("./webllm-IM3UD6YI.js");
+      const { createWebLLMModel: createWebLLMModel2 } = await import("./webllm-XUBUNKFN.js");
       return createWebLLMModel2(spec.model, providerOptions);
     }
     case "gateway": {
@@ -740,10 +744,17 @@ var executeStep = async (ctx, goal, step, index, total, done) => {
     timeoutMs: ctx.config.chatTimeoutMs,
     callbacks: {
       onTextDelta: (delta) => ctx.emit({ type: "step.text-delta", step, delta }),
-      onToolCall: (name, input) => ctx.emit({ type: "step.tool-call", step, name, input }),
-      onToolResult: (name, output, ok) => ctx.emit({ type: "step.tool-result", step, name, output, ok })
+      onToolCall: (name, input) => {
+        ctx.log.info(`tool call: ${name}`, input);
+        ctx.emit({ type: "step.tool-call", step, name, input });
+      },
+      onToolResult: (name, output, ok) => {
+        ctx.log.debug(`tool result: ${name} ${ok ? "ok" : "FAILED"}`, output);
+        ctx.emit({ type: "step.tool-result", step, name, output, ok });
+      }
     }
   });
+  ctx.log.debug("executor text:", loop.text);
   const { summary, blocked } = splitBlocker(loop.text);
   return {
     result: {
@@ -791,11 +802,14 @@ var toSteps = (raw) => raw.filter((s) => s.description && s.description.trim()).
   expectedOutcome: s.expectedOutcome,
   suggestedTools: s.suggestedTools
 }));
-var createPlan = async (ctx, goal) => {
+var createPlan = async (ctx, goal, nudge) => {
   const state = await ctx.state();
+  const effectiveGoal = nudge ? `${goal}
+
+${nudge}` : goal;
   const commonFor = (mode) => {
     const parts = ctx.prompts.planner({
-      goal,
+      goal: effectiveGoal,
       state,
       toolCatalog: ctx.toolCatalog,
       mode,
@@ -813,16 +827,20 @@ var createPlan = async (ctx, goal) => {
   if (ctx.plannerMode === "native") {
     try {
       const result2 = await generateStructured(ctx.plannerModel, PlanSchema, commonFor("native"));
+      ctx.log.debug("planner (native):", result2.object);
       return {
         plan: { thought: result2.object.thought, steps: toSteps(result2.object.steps) },
         usage: normalizeUsage(result2.usage)
       };
     } catch (err) {
+      ctx.log.warn("planner: native structured output failed, salvaging:", asMessage(err));
       ctx.emit({ type: "retry", phase: "plan", attempt: 1, error: asMessage(err) });
     }
   }
   const result = await generate(ctx.plannerModel, commonFor("prompted"));
   const parsed = parsePlannerResponse(result.text);
+  ctx.log.debug("planner (prompted) raw:", result.text);
+  ctx.log.debug("planner (prompted) parsed:", parsed);
   return {
     plan: {
       thought: parsed.reply,
@@ -905,6 +923,27 @@ var synthesizeAnswer = async (ctx, goal, done) => {
   };
 };
 
+// src/logger.ts
+var WEIGHT = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4
+};
+var PREFIX = "[agent-web]";
+var noop = () => void 0;
+var createLogger = (level = "warn", sink = console) => {
+  const at = (min, fn) => WEIGHT[level] >= WEIGHT[min] ? (...args) => fn.call(sink, PREFIX, ...args) : noop;
+  return {
+    level,
+    error: at("error", sink.error),
+    warn: at("warn", sink.warn),
+    info: at("info", sink.info),
+    debug: at("debug", sink.debug)
+  };
+};
+
 // src/agent/runner.ts
 var errMessage = (err) => err instanceof Error ? err.message : String(err);
 var filterTools = (all, available, excluded) => {
@@ -935,6 +974,10 @@ var createAgent = async (config) => {
   );
   const toolCatalog = renderCatalog(tools);
   const prompts = { ...defaultPrompts, ...config.prompts };
+  const log = createLogger(cfg.logLevel, config.logger);
+  log.info(
+    `agent ready \u2014 tools: [${Object.keys(tools).join(", ") || "none"}], planner mode: ${plannerMode}, executor mode: ${executorMode}`
+  );
   const run = async (goal, opts = {}) => {
     const emit = (event) => {
       try {
@@ -990,14 +1033,34 @@ var createAgent = async (config) => {
       toolCatalog,
       prompts,
       emit,
+      log,
       signal: opts.signal,
       state,
       history
     };
     await remember({ role: "user", content: text });
+    log.info("run:", text);
     try {
-      const planned = await createPlan(ctx, text);
+      let planned = await createPlan(ctx, text);
       bumpUsage(planned.usage, "plan");
+      if (isAborted()) {
+        emit({ type: "stopped" });
+        result.stopped = true;
+        return result;
+      }
+      if (planned.plan.steps.length === 0 && text.split(/\s+/).length > 2) {
+        log.warn(
+          "planner returned no steps for a multi-word goal \u2014 retrying with a nudge. thought:",
+          planned.plan.thought
+        );
+        const retried = await createPlan(
+          ctx,
+          text,
+          "NOTE: If the message above asks to build, add, change, clear or delete ANYTHING, you MUST output 1-6 concrete steps. Output an empty plan ONLY for a pure greeting or question."
+        );
+        bumpUsage(retried.usage, "plan");
+        if (retried.plan.steps.length > 0) planned = retried;
+      }
       result.plan = planned.plan;
       if (isAborted()) {
         emit({ type: "stopped" });
@@ -1005,12 +1068,17 @@ var createAgent = async (config) => {
         return result;
       }
       if (planned.plan.steps.length === 0) {
+        log.info("no plan \u2014 answering directly (no tools will run)");
         const answer = planned.plan.thought.trim() || "Tell me what you'd like to do.";
         emit({ type: "final", text: answer });
         await remember({ role: "assistant", content: answer });
         result.final = answer;
         return result;
       }
+      log.info(
+        `plan (${planned.plan.steps.length} steps):`,
+        planned.plan.steps.map((s) => s.description)
+      );
       emit({ type: "plan.created", plan: planned.plan });
       planned.plan.steps.forEach((step, index) => emit({ type: "plan.step-added", step, index }));
       const done = [];
@@ -1047,6 +1115,14 @@ var createAgent = async (config) => {
         const failed = stepResult.toolCalls.length - applied;
         result.applied += applied;
         result.steps = stepNo;
+        log.info(
+          `step ${stepNo}/${total} "${step.description}" \u2014 ${stepResult.toolCalls.length} tool call(s), ${applied} ok${failed ? `, ${failed} FAILED` : ""}${stepResult.blocked ? ", BLOCKED" : ""}`
+        );
+        if (stepResult.toolCalls.length === 0) {
+          log.warn(`step ${stepNo} made no tool calls \u2014 nothing changed in this step`);
+        }
+        stepResult.toolCalls.filter((c) => !c.ok).forEach((c) => log.warn(`tool ${c.name} failed:`, c.output));
+        log.debug(`step ${stepNo} detail:`, stepResult);
         emit({ type: "step.complete", step, result: stepResult });
         done.push(
           `${step.description} \u2014 ${applied} applied${failed ? `, ${failed} failed` : ""}${stepResult.blocked ? ", blocked" : ""}`
@@ -1086,6 +1162,7 @@ var createAgent = async (config) => {
         } catch {
         }
       }
+      log.info(`done \u2014 ${result.applied} tool call(s) applied over ${result.steps} step(s)`);
       emit({ type: "final", text: summary });
       await remember({ role: "assistant", content: summary });
       result.final = summary;
@@ -1347,6 +1424,7 @@ export {
   buildModelFromStage,
   compressHistory,
   createAgent,
+  createLogger,
   createPlan,
   createWebLLMModel,
   decideReplan,
@@ -1371,6 +1449,7 @@ export {
   parsePlainText,
   parsePlannerResponse,
   parseReplannerResponse,
+  preloadWebLLMModel,
   promptHintOf,
   renderCatalog,
   resolveConfig,
@@ -1384,6 +1463,7 @@ export {
   supportsNativeTools,
   supportsStructuredOutput,
   synthesizeAnswer,
+  unloadWebLLMModel,
   withSystem
 };
 //# sourceMappingURL=index.js.map