lemura 1.2.0 → 1.4.0

package/dist/index.mjs

@@ -424,9 +424,17 @@ var OpenAICompatibleAdapter = class {
       })
     });
     const data = await response.json();
+    if (data?.error) {
+      throw new LemuraAdapterError(data.error.message || "Image generation failed", "IMAGE_GEN_ERROR");
+    }
+    const first = data?.data?.[0] || {};
+    const imageUrl = first.url || (first.b64_json ? `data:image/png;base64,${first.b64_json}` : null) || (first.image_url?.url || null);
+    if (!imageUrl) {
+      throw new LemuraAdapterError("Image generation returned no image URL or base64 payload", "IMAGE_GEN_EMPTY");
+    }
     return {
-      imageUrl: data.data[0].url,
-      revisedPrompt: data.data[0].revised_prompt
+      imageUrl,
+      revisedPrompt: first.revised_prompt
     };
   }
 };
@@ -454,6 +462,8 @@ var ContextManager = class {
    */
   async prepare(context, safetyMargin = 0.95) {
     let currentCtx = { ...context, turns: [...context.turns] };
+    const systemTokens = currentCtx.systemPrompt ? Math.ceil(currentCtx.systemPrompt.length / 4) : 0;
+    currentCtx.tokenCount = currentCtx.turns.reduce((sum, t) => sum + t.tokenCount, 0) + systemTokens;
     currentCtx.maxTokens * safetyMargin;
     for (const strategy of this.strategies) {
       if (strategy.shouldApply(currentCtx)) {
@@ -474,11 +484,13 @@ var SandwichCompressionStrategy = class {
   constructor(adapter, config) {
     this.adapter = adapter;
     this.config = config;
+    this.priority = config.priority ?? 20;
   }
   name = "sandwich_compression";
-  priority = 20;
+  priority;
   shouldApply(ctx) {
-    return ctx.tokenCount >= ctx.maxTokens * this.config.triggerThreshold && ctx.turns.length > this.config.preserveFirst + this.config.preserveLast;
+    const threshold = this.config.triggerThreshold ?? 0.8;
+    return ctx.tokenCount >= ctx.maxTokens * threshold && ctx.turns.length > this.config.preserveFirst + this.config.preserveLast;
   }
   async apply(ctx) {
     const { preserveFirst, preserveLast } = this.config;
@@ -492,7 +504,8 @@ var SandwichCompressionStrategy = class {
         role: "user",
         content: `Summarize the following conversation history briefly:
 ${middleText}`
-      }]
+      }],
+      ...this.config.summaryMaxTokens ? { maxTokens: this.config.summaryMaxTokens } : {}
     });
     const summaryStr = summaryResponse.content;
     const newCompressionSummary = ctx.compressionSummary ? `${ctx.compressionSummary}
@@ -560,9 +573,10 @@ var HistoryCompressionStrategy = class {
   constructor(adapter, config) {
     this.adapter = adapter;
     this.config = config;
+    this.priority = config.priority ?? 30;
   }
   name = "history_compression";
-  priority = 30;
+  priority;
   shouldApply(ctx) {
     const triggerTokens = ctx.maxTokens * this.config.triggerAtPercent;
     const uncompressedTurns = ctx.turns.filter((t) => t.role !== "system" && !t.compressed);
@@ -594,6 +608,52 @@ ${summaryStr}` : summaryStr;
     };
   }
 };
+
+// src/context/SummaryInjectionStrategy.ts
+var SummaryInjectionStrategy = class {
+  name = "summary_injection";
+  priority;
+  label;
+  constructor(config = {}) {
+    this.priority = config.priority ?? 1;
+    this.label = config.label ?? "Earlier conversation summary";
+  }
+  shouldApply(ctx) {
+    return !!ctx.compressionSummary && ctx.compressionSummary.trim().length > 0;
+  }
+  async apply(ctx) {
+    const summaryContent = `[${this.label}]
+${ctx.compressionSummary}`;
+    const summaryTokenCount = Math.ceil(summaryContent.length / 4);
+    const existingIndex = ctx.turns.findIndex((t) => t.compressed && t.role === "system" && t.turnIndex === -1);
+    let newTurns;
+    if (existingIndex !== -1) {
+      newTurns = ctx.turns.map((t, i) => {
+        if (i !== existingIndex) return t;
+        return {
+          ...t,
+          content: summaryContent,
+          tokenCount: summaryTokenCount
+        };
+      });
+    } else {
+      const summaryTurn = {
+        role: "system",
+        content: summaryContent,
+        tokenCount: summaryTokenCount,
+        turnIndex: -1,
+        compressed: true
+      };
+      newTurns = [summaryTurn, ...ctx.turns];
+    }
+    const newTokenCount = newTurns.reduce((sum, t) => sum + t.tokenCount, 0);
+    return {
+      ...ctx,
+      turns: newTurns,
+      tokenCount: newTokenCount
+    };
+  }
+};
 var ShortTermMemoryRegistry = class {
   storage;
   maxTextTokens;
@@ -716,6 +776,23 @@ var InMemoryStorageAdapter = class {
   }
 };
 
+// src/context/InMemoryScratchpadAdapter.ts
+var InMemoryScratchpadAdapter = class {
+  store = /* @__PURE__ */ new Map();
+  async read(sessionId) {
+    return this.store.get(sessionId);
+  }
+  async write(sessionId, content) {
+    this.store.set(sessionId, content);
+  }
+  async clear(sessionId) {
+    this.store.delete(sessionId);
+  }
+  async healthCheck() {
+    return true;
+  }
+};
+
 // src/tools/SchemaValidator.ts
 function typeOf(value) {
   if (value === null) return "null";
@@ -1053,35 +1130,165 @@ var MediaBridge = class {
 var SkillInjector = class {
   skills = [];
   constructor(skills = []) {
-    this.skills = [...skills];
+    this.skills = skills.map((s) => this._normalise(s));
     this.sortSkills();
   }
+  // -----------------------------------------------------------------------
+  // Registration
+  // -----------------------------------------------------------------------
   register(skill) {
-    this.skills.push(skill);
+    this.skills.push(this._normalise(skill));
     this.sortSkills();
   }
   sortSkills() {
     this.skills.sort((a, b) => a.priority - b.priority);
   }
+  /**
+   * Normalises a skill to ensure consistent defaults.
+   * For dynamic skills, `enabled` defaults to `false` unless explicitly set.
+   * For fixed skills (or those without a strategy), `enabled` is ignored.
+   */
+  _normalise(skill) {
+    const strategy = skill.strategy ?? "fixed";
+    const enabled = strategy === "dynamic" ? skill.enabled ?? false : true;
+    return { ...skill, strategy, enabled };
+  }
+  // -----------------------------------------------------------------------
+  // Dynamic skill activation
+  // -----------------------------------------------------------------------
+  /**
+   * Enable a dynamic skill by name.
+   * Has no effect on fixed skills (they are always active).
+   */
+  enableSkill(name) {
+    const skill = this.skills.find((s) => s.name === name);
+    if (skill && skill.strategy === "dynamic") {
+      skill.enabled = true;
+    }
+  }
+  /**
+   * Disable a dynamic skill by name.
+   * Has no effect on fixed skills.
+   */
+  disableSkill(name) {
+    const skill = this.skills.find((s) => s.name === name);
+    if (skill && skill.strategy === "dynamic") {
+      skill.enabled = false;
+    }
+  }
+  /**
+   * Enable all dynamic skills whose `tags` array intersects with `tags`.
+   */
+  enableByTags(tags) {
+    const tagSet = new Set(tags);
+    for (const skill of this.skills) {
+      if (skill.strategy === "dynamic" && skill.tags?.some((t) => tagSet.has(t))) {
+        skill.enabled = true;
+      }
+    }
+  }
+  /**
+   * Disable all dynamic skills whose `tags` array intersects with `tags`.
+   */
+  disableByTags(tags) {
+    const tagSet = new Set(tags);
+    for (const skill of this.skills) {
+      if (skill.strategy === "dynamic" && skill.tags?.some((t) => tagSet.has(t))) {
+        skill.enabled = false;
+      }
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Queries
+  // -----------------------------------------------------------------------
+  /**
+   * Returns all registered skills (fixed and dynamic, enabled or not).
+   */
+  getAll() {
+    return [...this.skills];
+  }
+  /**
+   * Returns currently active skills — fixed skills always, dynamic skills
+   * only when `enabled === true`.
+   */
+  getActiveSkills() {
+    return this.skills.filter((s) => this._isActive(s));
+  }
+  /**
+   * Returns skills at a given injection position, active only.
+   */
   getSkillsForInjection(position) {
-    return this.skills.filter((s) => s.inject === position);
+    return this.skills.filter((s) => s.inject === position && this._isActive(s));
+  }
+  /**
+   * Returns the union of `requiredTools` from all currently active skills.
+   * Use this to determine which tools the active skill set depends on.
+   *
+   * @since 1.4.0
+   */
+  getRequiredTools() {
+    const tools = /* @__PURE__ */ new Set();
+    for (const skill of this.getActiveSkills()) {
+      for (const t of skill.requiredTools ?? []) {
+        tools.add(t);
+      }
+    }
+    return [...tools];
+  }
+  _isActive(skill) {
+    return skill.strategy !== "dynamic" || skill.enabled === true;
   }
+  // -----------------------------------------------------------------------
+  // Injection block builder
+  // -----------------------------------------------------------------------
   /**
-   * Generates a combined prompt block for all skills targeting a specific injection position.
+   * Builds the combined injection block for all active skills at the given position.
+   *
+   * @param position  - Which injection point to target.
+   * @param tokenBudget - Optional maximum token budget. Skills are added in priority
+   *   order until the budget would be exceeded. When `undefined`, all active skills
+   *   at the position are included.
    */
-  buildInjectionBlock(position) {
+  buildInjectionBlock(position, tokenBudget) {
     const relevantSkills = this.getSkillsForInjection(position);
     if (relevantSkills.length === 0) return "";
     let block = "";
+    let usedTokens = 0;
     for (const skill of relevantSkills) {
-      const content = skill.standard || skill.micro || skill.nano || skill.description;
-      block += `
-[Skill: ${skill.name} (Tier: ${skill.tier})]
+      const content = this._pickContent(skill, tokenBudget !== void 0);
+      if (!content) continue;
+      const tierLabel = skill.tier ?? "standard";
+      const skillEntry = `
+[Skill: ${skill.name} (Tier: ${tierLabel})]
 ${content}
 `;
+      const skillTokens = Math.ceil(skillEntry.length / 4);
+      if (tokenBudget !== void 0 && usedTokens + skillTokens > tokenBudget) {
+        continue;
+      }
+      block += skillEntry;
+      usedTokens += skillTokens;
     }
     return block.trim();
   }
+  // -----------------------------------------------------------------------
+  // Content picking
+  // -----------------------------------------------------------------------
+  /**
+   * Picks the content variant to use for a skill.
+   *
+   * Resolution order when budget-aware (compact first):
+   *   nano → micro → standard → content → description
+   *
+   * Resolution order when not budget-aware (richest first):
+   *   standard → content → micro → nano → description
+   */
+  _pickContent(skill, budgetAware) {
+    if (budgetAware) {
+      return skill.nano || skill.micro || skill.standard || skill.content || skill.description || "";
+    }
+    return skill.standard || skill.content || skill.micro || skill.nano || skill.description || "";
+  }
 };
 
 // src/rag/InMemoryRAGAdapter.ts
@@ -1293,6 +1500,10 @@ var readScratchpadTool = {
   description: "Reads the content from the current agent scratchpad.",
   parameters: { type: "object", properties: {} },
   async execute(_params, context) {
+    if (context.scratchpadAdapter) {
+      const stored = await context.scratchpadAdapter.read(context.sessionId);
+      return stored ?? "";
+    }
     return context.scratchpad ?? "";
   }
 };
@@ -1308,12 +1519,20 @@ var writeScratchpadTool = {
     required: ["content"]
   },
   async execute(params, context) {
-    let newScratchpad = context.scratchpad ?? "";
+    let current = context.scratchpad ?? "";
+    if (context.scratchpadAdapter) {
+      const stored = await context.scratchpadAdapter.read(context.sessionId);
+      if (stored !== void 0) current = stored;
+    }
+    let newScratchpad = current;
     if (params.append) {
       newScratchpad += (newScratchpad ? "\n" : "") + params.content;
     } else {
       newScratchpad = params.content;
     }
+    if (context.scratchpadAdapter) {
+      await context.scratchpadAdapter.write(context.sessionId, newScratchpad);
+    }
     return { status: "success", newScratchpad, note: "Scratchpad updated" };
   }
 };
@@ -1321,7 +1540,10 @@ var removeScratchpadTool = {
   name: "remove_scratchpad",
   description: "Clears or removes content from the scratchpad.",
   parameters: { type: "object", properties: {} },
-  async execute(_params, _context) {
+  async execute(_params, context) {
+    if (context.scratchpadAdapter) {
+      await context.scratchpadAdapter.clear(context.sessionId);
+    }
     return { status: "success", newScratchpad: "", note: "Scratchpad cleared" };
   }
 };
@@ -1502,30 +1724,63 @@ var FinalResponseFormatter = class {
 
 // src/agent/execution/ToolResponseProcessor.ts
 var ToolResponseProcessor = class {
+  smallMax;
+  mediumMax;
+  largeMax;
+  budgetPercent;
+  constructor(config = {}) {
+    this.smallMax = config.smallMaxTokens ?? 200;
+    this.mediumMax = config.mediumMaxTokens ?? 800;
+    this.largeMax = config.largeMaxTokens ?? 2e3;
+    this.budgetPercent = config.budgetPercent;
+  }
   evaluate(response, tool, context) {
-    const length = response.length;
-    const estimatedTokens = length / 4;
+    const estimatedTokens = response.length / 4;
     let sizeClass = "small";
-    if (estimatedTokens > 2e3) sizeClass = "oversized";
-    else if (estimatedTokens > 800) sizeClass = "large";
-    else if (estimatedTokens > 200) sizeClass = "medium";
+    if (estimatedTokens > this.largeMax) sizeClass = "oversized";
+    else if (estimatedTokens > this.mediumMax) sizeClass = "large";
+    else if (estimatedTokens > this.smallMax) sizeClass = "medium";
+    const lc = response.toLowerCase();
+    const errorDetected = lc.includes("error:") || lc.includes("exception:") || lc.includes('"error"') || lc.includes('"status":"error"') || lc.includes('"status": "error"') || lc.includes("failed:") || lc.includes("connection refused") || lc.includes("timed out");
+    const suggestedAction = errorDetected ? "retry" : sizeClass === "oversized" || sizeClass === "large" ? "continue" : "continue";
     return {
       relevanceScore: 1,
       sizeClass,
       shouldCompress: sizeClass === "large" || sizeClass === "oversized",
-      suggestedMaxTokens: 500,
-      answered: true,
-      answeredPartially: false,
-      errorDetected: response.toLowerCase().includes("error"),
-      suggestedAction: "continue"
+      suggestedMaxTokens: this.mediumMax,
+      answered: !errorDetected,
+      answeredPartially: errorDetected,
+      errorDetected,
+      suggestedAction
     };
   }
   compress(response, evaluation) {
     if (!evaluation.shouldCompress || evaluation.errorDetected) {
       return response;
     }
-    if (response.length > 1e3) {
-      return response.substring(0, 1e3) + "\n...[COMPRESSED TO SAVE TOKENS]...";
+    if (evaluation.sizeClass === "oversized") {
+      const headChars = this.largeMax * 4;
+      const tailChars = this.mediumMax * 2;
+      if (response.length > headChars + tailChars) {
+        const skipped = response.length - headChars - tailChars;
+        return response.slice(0, headChars) + `
+
+...[${skipped} characters omitted \u2014 response too large]...
+
+` + response.slice(-tailChars);
+      }
+    }
+    if (evaluation.sizeClass === "large") {
+      const lines = response.split("\n");
+      const keepLines = Math.ceil(this.mediumMax / 10);
+      if (lines.length > keepLines * 2) {
+        const skipped = lines.length - keepLines * 2;
+        return [
+          ...lines.slice(0, keepLines),
+          `... [${skipped} lines omitted] ...`,
+          ...lines.slice(-keepLines)
+        ].join("\n");
+      }
     }
     return response;
   }
@@ -1533,25 +1788,262 @@ var ToolResponseProcessor = class {
 
 // src/agent/execution/GoalInjector.ts
 var GoalInjector = class {
+  goal;
+  turnsSinceInjection = 0;
   constructor(goal) {
-    this.goal = goal;
+    this.goal = {
+      ...goal,
+      completedSubGoals: goal.completedSubGoals ?? []
+    };
   }
-  injectInto(prompt) {
-    const formatting = `[CURRENT GOAL]
-${this.goal.statement}
-
+  /**
+   * Returns the formatted `[CURRENT GOAL]` block string — without caring about
+   * where it will be placed. Callers decide whether to append to a system prompt
+   * or push as a separate message.
+   */
+  getFormattedBlock() {
+    const { statement, successCriteria, decomposition, completedSubGoals = [] } = this.goal;
+    const pending = decomposition.filter((sg) => !completedSubGoals.includes(sg));
+    const completed = decomposition.filter((sg) => completedSubGoals.includes(sg));
+    let block = `[CURRENT GOAL]
+${statement}
+`;
+    if (successCriteria.length > 0) {
+      block += `
 Success criteria:
-${this.goal.successCriteria.map((c) => `- ${c}`).join("\n")}
-[/CURRENT GOAL]`;
-    if (this.goal.injectionPosition === "system_prompt") {
-      return `${prompt}
+${successCriteria.map((c) => `- ${c}`).join("\n")}`;
+    }
+    if (pending.length > 0) {
+      block += `
 
-${formatting}`;
+Sub-goals remaining:
+${pending.map((sg) => `- ${sg} \u2190 pending`).join("\n")}`;
     }
-    return prompt;
+    if (completed.length > 0) {
+      block += `
+
+Sub-goals completed:
+${completed.map((sg) => `- \u2705 ${sg}`).join("\n")}`;
+    }
+    block += "\n[/CURRENT GOAL]";
+    return block;
   }
+  /**
+   * Appends the goal block to the given prompt string (for `system_prompt` position).
+   * For `pre_turn` position, use `getFormattedBlock()` directly.
+   *
+   * @param prompt - The existing system prompt to append to.
+   */
+  injectInto(prompt) {
+    const block = this.getFormattedBlock();
+    return prompt ? `${prompt}
+
+${block}` : block;
+  }
+  /**
+   * Returns true when the goal should be re-injected this turn,
+   * based on `injectionFrequency`.
+   *
+   * @param turnIndex - The current turn index in the ReAct loop (0-based)
+   * @param compressionOccurred - Whether context was compressed this iteration
+   * @param injectionN - The N for 'every_N_turns' frequency (default: 3)
+   */
+  shouldInjectThisTurn(turnIndex, compressionOccurred = false, injectionN = 3) {
+    const { injectionFrequency } = this.goal;
+    if (injectionFrequency === "always") return true;
+    if (injectionFrequency === "every_N_turns") {
+      return turnIndex % injectionN === 0;
+    }
+    if (injectionFrequency === "on_compression") {
+      return compressionOccurred;
+    }
+    return true;
+  }
+  /**
+   * Updates the goal with new sub-goal decomposition and success criteria,
+   * typically populated by the mini-planning LLM call.
+   */
+  updateDecomposition(decomposition, successCriteria) {
+    this.goal = {
+      ...this.goal,
+      decomposition,
+      ...successCriteria ? { successCriteria } : {}
+    };
+  }
+  /**
+   * Marks a sub-goal as completed so it moves to the "completed" section
+   * in subsequent injections.
+   */
+  markSubGoalDone(subGoal) {
+    const completed = this.goal.completedSubGoals ?? [];
+    if (!completed.includes(subGoal)) {
+      this.goal = {
+        ...this.goal,
+        completedSubGoals: [...completed, subGoal]
+      };
+    }
+  }
+  /** Returns a snapshot of the current goal state (safe to store in context.metadata). */
   getGoal() {
-    return { ...this.goal };
+    return { ...this.goal, completedSubGoals: [...this.goal.completedSubGoals ?? []] };
+  }
+  /** Increments the internal turn counter (used for `every_N_turns` frequency). */
+  incrementTurn() {
+    this.turnsSinceInjection++;
+  }
+};
+
+// src/agent/execution/ContinuationPlanner.ts
+var ContinuationPlanner = class {
+  plan;
+  outputs = /* @__PURE__ */ new Map();
+  constructor(plan) {
+    this.plan = { ...plan, steps: plan.steps.map((s) => ({ ...s })) };
+  }
+  // -------------------------------------------------------------------------
+  // State queries
+  // -------------------------------------------------------------------------
+  /** Returns the current plan (deep copy) */
+  getPlan() {
+    return { ...this.plan, steps: this.plan.steps.map((s) => ({ ...s })) };
+  }
+  /** Returns a human-readable status string with icons (injected before each iteration) */
+  getPlanStatusString() {
+    let result = `[CONTINUATION PLAN \u2014 Step ${this.plan.currentStepIndex + 1}/${this.plan.steps.length}]
+`;
+    for (const step of this.plan.steps) {
+      const icon = this._icon(step.status);
+      const statusText = step.status === "pending" && step.dependsOn.length > 0 ? `Waiting on Step ${step.dependsOn.join(", ")}` : step.status.charAt(0).toUpperCase() + step.status.slice(1);
+      result += `${icon} Step ${step.stepId} (${step.toolName}): ${statusText}
+`;
+    }
+    return result;
+  }
+  _icon(status) {
+    switch (status) {
+      case "done":
+        return "\u2705";
+      case "running":
+        return "\u25B6";
+      case "failed":
+        return "\u274C";
+      case "skipped":
+        return "\u23ED";
+      default:
+        return "\u23F3";
+    }
+  }
+  /** Returns all steps whose dependencies are satisfied and that are still pending */
+  getReadySteps() {
+    return this.plan.steps.filter((step) => {
+      if (step.status !== "pending") return false;
+      const depsOk = step.dependsOn.every((depId) => {
+        const dep = this.plan.steps.find((s) => s.stepId === depId);
+        return dep?.status === "done";
+      });
+      if (!depsOk) return false;
+      if (step.condition) {
+        const condDepOutput = this.outputs.get(step.condition.step) ?? "";
+        if (!condDepOutput.includes(step.condition.outputContains)) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+  /** Returns true when all steps have reached a terminal state */
+  isComplete() {
+    return this.plan.steps.every(
+      (s) => s.status === "done" || s.status === "failed" || s.status === "skipped"
+    );
+  }
+  // -------------------------------------------------------------------------
+  // State mutations
+  // -------------------------------------------------------------------------
+  /** Marks a step as running */
+  markStepRunning(stepId) {
+    this._updateStep(stepId, { status: "running" });
+  }
+  /**
+   * Marks a step as done, stores its output under `outputKey` (if set),
+   * and advances `currentStepIndex` to the next pending step.
+   */
+  markStepDone(stepId, output) {
+    const step = this.plan.steps.find((s) => s.stepId === stepId);
+    if (step?.outputKey && output !== void 0) {
+      this.outputs.set(step.outputKey, output);
+    }
+    this._updateStep(stepId, { status: "done" });
+    this._advanceIndex();
+  }
+  /**
+   * Marks a step as failed and propagates `skipped` to all transitively dependent steps.
+   */
+  markStepFailed(stepId) {
+    this._updateStep(stepId, { status: "failed" });
+    this._skipDependants(stepId);
+  }
+  /**
+   * Marks a step as skipped (e.g., condition not met) and propagates to its dependants.
+   */
+  markStepSkipped(stepId) {
+    this._updateStep(stepId, { status: "skipped" });
+    this._skipDependants(stepId);
+  }
+  // -------------------------------------------------------------------------
+  // Output / input mapping helpers
+  // -------------------------------------------------------------------------
+  /** Retrieves an output stored by `outputKey` from a completed step */
+  getOutput(key) {
+    return this.outputs.get(key);
+  }
+  /**
+   * Resolves the `inputMapping` for a step into a concrete parameter map,
+   * substituting `outputKey` values from prior steps. Static (non-key) values
+   * in the mapping are passed through unchanged.
+   */
+  resolveInputs(step, baseArgs = {}) {
+    if (!step.inputMapping) return baseArgs;
+    const resolved = { ...baseArgs };
+    for (const [paramName, outputKey] of Object.entries(step.inputMapping)) {
+      const value = this.outputs.get(outputKey);
+      if (value !== void 0) {
+        resolved[paramName] = value;
+      } else {
+        resolved[paramName] = outputKey;
+      }
+    }
+    return resolved;
+  }
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  _updateStep(stepId, patch) {
+    this.plan.steps = this.plan.steps.map(
+      (s) => s.stepId === stepId ? { ...s, ...patch } : s
+    );
+  }
+  _skipDependants(failedStepId) {
+    const toSkip = /* @__PURE__ */ new Set([failedStepId]);
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const step of this.plan.steps) {
+        if (step.status === "pending" && step.dependsOn.some((d) => toSkip.has(d))) {
+          this._updateStep(step.stepId, { status: "skipped" });
+          toSkip.add(step.stepId);
+          changed = true;
+        }
+      }
+    }
+  }
+  _advanceIndex() {
+    const nextPending = this.plan.steps.findIndex(
+      (s, i) => i > this.plan.currentStepIndex && s.status === "pending"
+    );
+    if (nextPending !== -1) {
+      this.plan.currentStepIndex = nextPending;
+    }
   }
 };
 var MCPClient = class {
@@ -2024,6 +2516,9 @@ var SessionManager = class {
   iterations = 0;
   logger;
   media;
+  sessionId;
+  scratchpadLoaded = false;
+  pendingScratchpadClear = false;
   // Advanced execution state
   stepCounter;
   toolResponseProcessor;
@@ -2031,7 +2526,7 @@ var SessionManager = class {
   continuationPlanner = null;
   // MCP
   mcpRegistry = null;
-  /** Resolves when all MCP servers are connected; used by run() and stream() */
+  /** Resolves when all MCP servers are connected; awaited by run() and stream() */
   mcpReady = null;
   // Tool execution budget tracking
   totalToolCallCount = 0;
@@ -2041,14 +2536,23 @@ var SessionManager = class {
     this.config = config;
     this.adapter = config.adapter;
     this.logger = config.logger || new DefaultLogger();
+    this.sessionId = config.sessionId || "default";
     this.contextManager = new ContextManager();
     this.toolRegistry = new ToolRegistry(config.tools || [], {
       defaultTimeoutMs: config.toolRegistryTimeoutMs ?? 3e4
     });
     this.skillInjector = new SkillInjector(config.skills || []);
+    if (config.activeDynamicSkills && config.activeDynamicSkills.length > 0) {
+      for (const name of config.activeDynamicSkills) {
+        this.skillInjector.enableSkill(name);
+      }
+    }
+    if (config.activeDynamicTags && config.activeDynamicTags.length > 0) {
+      this.skillInjector.enableByTags(config.activeDynamicTags);
+    }
     this.media = new MediaBridge(this.adapter);
     this.stepCounter = new StepCounter(config.maxSteps ?? 20);
-    this.toolResponseProcessor = config.toolResponseProcessor ?? new ToolResponseProcessor();
+    this.toolResponseProcessor = config.toolResponseProcessor instanceof ToolResponseProcessor ? config.toolResponseProcessor : config.toolResponseProcessor ? config.toolResponseProcessor : new ToolResponseProcessor();
     for (const strategy of config.compressionStrategies || []) {
       this.contextManager.registerStrategy(strategy);
     }
@@ -2076,11 +2580,11 @@ var SessionManager = class {
       maxTokens: config.maxTokens,
       metadata: {}
     };
-    this.goalInjector = null;
     if (config.mcpServers && config.mcpServers.length > 0) {
       this.mcpRegistry = new MCPClientRegistry(this.logger);
       this.mcpReady = this._initMCP(config.mcpServers);
     }
+    const activeSkills = this.skillInjector.getActiveSkills();
     this.emitTrace("system", "session_init", {
       config: {
         model: this.config.model,
@@ -2089,9 +2593,29 @@ var SessionManager = class {
         parallelToolCalls: this.config.parallelToolCalls,
         enableGoalPlanning: this.config.enableGoalPlanning,
         enableContinuationPlanning: this.config.enableContinuationPlanning
+      },
+      skills: {
+        total: (config.skills || []).length,
+        active: activeSkills.length,
+        fixed: activeSkills.filter((s) => s.strategy !== "dynamic").length,
+        dynamic: activeSkills.filter((s) => s.strategy === "dynamic").length
       }
     });
+    for (const skill of activeSkills) {
+      this.emitTrace("skill", "skill_load", {
+        name: skill.name,
+        version: skill.version,
+        strategy: skill.strategy ?? "fixed",
+        inject: skill.inject,
+        priority: skill.priority,
+        tags: skill.tags ?? [],
+        requiredTools: skill.requiredTools ?? []
+      });
+    }
   }
+  // -----------------------------------------------------------------------
+  // Trace helper
+  // -----------------------------------------------------------------------
   emitTrace(type, name, metadata, input, output, status = "done") {
     if (this.config.onTrace) {
       this.config.onTrace({
@@ -2105,24 +2629,172 @@ var SessionManager = class {
       });
     }
   }
-  /**
-   * Returns a shallow copy of the current context window.
-   */
+  async ensureScratchpadLoaded() {
+    if (!this.config.scratchpadAdapter) return;
+    if (this.pendingScratchpadClear) {
+      await this.config.scratchpadAdapter.clear(this.sessionId);
+      this.context.scratchpad = "";
+      this.pendingScratchpadClear = false;
+      this.scratchpadLoaded = true;
+      return;
+    }
+    if (this.scratchpadLoaded) return;
+    const stored = await this.config.scratchpadAdapter.read(this.sessionId);
+    this.context.scratchpad = stored ?? "";
+    this.scratchpadLoaded = true;
+  }
+  // -----------------------------------------------------------------------
+  // Public accessors
+  // -----------------------------------------------------------------------
+  /** Returns a shallow copy of the current context window. */
   getContext() {
     return { ...this.context };
   }
-  /**
-   * Returns the current conversation history.
-   */
+  /** Returns the current conversation history. */
   getHistory() {
     return [...this.context.turns];
   }
   /**
-   * Returns the `MediaBridge` for direct ASR / TTS / Vision / Image-gen calls.
+   * Populates the session context with a pre-existing conversation history.
+   *
+   * Turns are assigned sequential `turnIndex` values starting from 0 and the
+   * context `tokenCount` is recalculated automatically. Call this immediately
+   * after construction and before the first `run()` / `stream()`.
+   *
+   * @param history - Raw history entries (role + content, optional toolCalls/toolResults).
+   *
+   * @example
+   * ```typescript
+   * const session = new SessionManager(config);
+   * session.loadHistory(savedMessages);
+   * const answer = await session.run('Continue where we left off.');
+   * ```
    */
+  loadHistory(history) {
+    this.context.turns = history.map((m, i) => ({
+      role: m.role,
+      content: m.content ?? "",
+      tokenCount: this.adapter.estimateTokens(
+        typeof m.content === "string" ? m.content : JSON.stringify(m.content)
+      ),
+      turnIndex: i,
+      compressed: false,
+      ...m.toolCalls ? { toolCalls: m.toolCalls } : {},
+      ...m.toolResults ? { toolResults: m.toolResults } : {}
+    }));
+    this.context.tokenCount = this.context.turns.reduce((sum, t) => sum + t.tokenCount, 0) + this.adapter.estimateTokens(this.context.systemPrompt || "");
+    this.emitTrace("system", "history_loaded", { turnCount: this.context.turns.length });
+  }
+  /** Returns the `MediaBridge` for direct ASR / TTS / Vision / Image-gen calls. */
   getMedia() {
     return this.media;
   }
+  /**
+   * Returns the `ToolRegistry` for runtime tool management.
+   *
+   * Use this to register or unregister tools after session construction:
+   *
+   * ```typescript
+   * // Add a tool after the user authenticates
+   * session.tools.register(paymentTool);
+   *
+   * // Remove a tool when no longer needed
+   * session.tools.unregister('send_payment');
+   *
+   * // Inspect what's registered
+   * const active = session.tools.getAll();
+   * console.log(active.map(t => t.name));
+   * ```
+   *
+   * @since 1.4.0
+   */
+  get tools() {
+    return this.toolRegistry;
+  }
+  /**
+   * Returns the `SkillInjector` for runtime skill management.
+   *
+   * Use this to enable or disable dynamic skills after session construction:
+   *
+   * ```typescript
+   * session.skills.enableSkill('code-review');
+   * session.skills.enableByTags(['debugging']);
+   * session.skills.disableSkill('verbose-mode');
+   * const requiredTools = session.skills.getRequiredTools();
+   * ```
+   *
+   * @since 1.4.0
+   */
+  get skills() {
+    return this.skillInjector;
+  }
+  // -----------------------------------------------------------------------
+  // Continuation planning API
+  // -----------------------------------------------------------------------
+  /**
+   * Sets an explicit multi-step continuation plan that will be tracked and
+   * injected as a status block before each ReAct iteration.
+   *
+   * Dependency tracking, condition evaluation, `outputKey` storage, and
+   * `inputMapping` resolution are all handled automatically by the planner.
+   *
+   * @param steps    - The ordered list of continuation steps.
+   * @param strategy - Execution strategy ('sequential' | 'parallel' | 'conditional'). Default: 'sequential'.
+   *
+   * @example
+   * ```typescript
+   * await session.setPlan([
+   *   { stepId: 'fetch', toolName: 'fetch_data', description: 'Get data', dependsOn: [], outputKey: 'rawData' },
+   *   { stepId: 'analyze', toolName: 'analyze', description: 'Analyze', dependsOn: ['fetch'], inputMapping: { data: 'rawData' } },
+   * ]);
+   * const result = await session.run('Run the data pipeline.');
+   * ```
+   */
+  setPlan(steps, strategy = "sequential") {
+    this.continuationPlanner = new ContinuationPlanner({
+      steps,
+      currentStepIndex: 0,
+      strategy
+    });
+    this.context.metadata["continuationPlan"] = this.continuationPlanner.getPlan();
+    this.logger.debug(`[ContinuationPlanner] Plan set with ${steps.length} steps (strategy: ${strategy})`);
+    this.emitTrace("planning", "plan_set", { stepCount: steps.length, strategy });
+  }
+  // -----------------------------------------------------------------------
+  // Goal planning API
+  // -----------------------------------------------------------------------
+  /**
+   * Manually sets the agent's goal, bypassing the automatic mini-planning LLM call.
+   *
+   * Use this when you already know the goal structure upfront.
+   *
+   * @example
+   * ```typescript
+   * await session.setGoal({
+   *   statement: 'Audit the authentication module',
+   *   decomposition: ['Read src/auth/', 'Identify SQL injection risks', 'Write report'],
+   *   successCriteria: ['Report covers all audit areas', 'Each finding has a severity rating'],
+   * });
+   * const result = await session.run('Begin the security audit.');
+   * ```
+   */
+  setGoal(goal) {
+    this.goalInjector = new GoalInjector({
+      id: "manual",
+      statement: goal.statement,
+      decomposition: goal.decomposition ?? [],
+      successCriteria: goal.successCriteria ?? [],
+      injectionFrequency: this.config.goalInjectionFrequency ?? "always",
+      injectionPosition: this.config.goalInjectionPosition ?? "system_prompt",
+      completedSubGoals: goal.completedSubGoals ?? []
+    });
+    this.context.metadata["goal"] = this.goalInjector.getGoal();
+    this.logger.debug("[GoalInjector] Goal set manually");
+    this.emitTrace("planning", "goal_set_manual", {
+      statement: goal.statement,
+      subGoals: goal.decomposition?.length ?? 0
+    });
+  }
   // -----------------------------------------------------------------------
   // MCP initialisation
   // -----------------------------------------------------------------------
@@ -2160,41 +2832,83 @@ var SessionManager = class {
     });
   }
   // -----------------------------------------------------------------------
+  // Goal mini-planning step (one extra LLM call, gated by enableGoalPlanning)
+  // -----------------------------------------------------------------------
+  /**
+   * Runs a dedicated planning prompt against the LLM to decompose the user's
+   * message into sub-goals and success criteria. Called once at the start of
+   * the first `run()` when `enableGoalPlanning` is true and no goal has been
+   * manually set via `setGoal()`.
+   */
+  async _runMiniPlanningStep(userMessage) {
+    const planningPrompt = `Given this goal: "${userMessage}"
+
+1. List the sub-goals needed to achieve this (max 5, be specific)
+2. List success criteria \u2014 what does "done" look like? (max 3, binary, measurable)
+
+Respond ONLY with valid JSON (no markdown, no explanations):
+{ "subGoals": string[], "successCriteria": string[] }`;
+    try {
+      const response = await this.adapter.complete({
+        model: this.config.model,
+        messages: [{ role: "user", content: planningPrompt }],
+        maxTokens: this.config.maxCompletionTokens ?? 2e3
+      });
+      const raw = response.content.replace(/```json|```/g, "").trim();
+      const parsed = JSON.parse(raw);
+      if (this.goalInjector && Array.isArray(parsed.subGoals)) {
+        this.goalInjector.updateDecomposition(
+          parsed.subGoals,
+          Array.isArray(parsed.successCriteria) ? parsed.successCriteria : void 0
+        );
+        this.context.metadata["goal"] = this.goalInjector.getGoal();
+        this.emitTrace("planning", "mini_plan_done", {
+          subGoals: parsed.subGoals,
+          successCriteria: parsed.successCriteria
+        });
+        this.logger.debug(`[GoalInjector] Mini-plan: ${parsed.subGoals.length} sub-goals`);
+      }
+    } catch (err) {
+      this.logger.warn(`[GoalInjector] Mini-planning step failed: ${err.message ?? String(err)}`);
+    }
+  }
+  // -----------------------------------------------------------------------
   // Internal helpers
   // -----------------------------------------------------------------------
   /** Builds the system prompt, injecting skills and goal if configured. */
-  buildSystemPrompt(userMessage) {
+  buildSystemPrompt(userMessage, iteration = 0) {
     let prompt = this.context.systemPrompt || "";
-    if (this.config.enableGoalPlanning && userMessage) {
-      if (!this.goalInjector) {
-        this.goalInjector = new GoalInjector({
-          id: "main",
-          statement: typeof userMessage === "string" ? userMessage : "[multimodal]",
-          decomposition: [],
-          successCriteria: ["The user request is fully answered"],
-          injectionFrequency: this.config.goalInjectionFrequency ?? "always",
-          injectionPosition: this.config.goalInjectionPosition ?? "system_prompt"
-        });
-        this.logger.debug("Goal injector initialised");
-        const goal = this.goalInjector.getGoal();
-        this.emitTrace("planning", "goal_init", {
-          statement: goal.statement,
-          criteria: goal.successCriteria
-        });
-      }
-      if (this.config.goalInjectionPosition !== "pre_turn") {
+    if (this.goalInjector && this.config.goalInjectionPosition !== "pre_turn") {
+      const shouldInject = this.goalInjector.shouldInjectThisTurn(
+        iteration,
+        false,
+        this.config.goalInjectionN ?? 3
+      );
+      if (shouldInject) {
         prompt = this.goalInjector.injectInto(prompt);
-        this.emitTrace("planning", "goal_injected", { position: this.config.goalInjectionPosition || "system_prompt" });
+        this.emitTrace("planning", "goal_injected", {
+          position: "system_prompt",
+          iteration
+        });
       }
     }
-    const injectedSkills = this.skillInjector.buildInjectionBlock("system_prompt");
+    if (this.continuationPlanner && this.config.enableContinuationPlanning) {
+      const planStatus = this.continuationPlanner.getPlanStatusString();
+      prompt += `
+
+${planStatus}`;
+    }
+    const injectedSkills = this.skillInjector.buildInjectionBlock(
+      "system_prompt",
+      this.config.skillTokenBudget
+    );
     if (injectedSkills) {
       prompt += "\n\n" + injectedSkills;
     }
     return prompt.trim();
   }
-  /** Builds the messages array for the provider from the current context */
-  buildMessages(systemPrompt) {
+  /** Builds the messages array for the provider from the current context. */
+  buildMessages(systemPrompt, iteration = 0) {
     const messages = this.context.turns.map((t) => ({
       role: t.role,
       content: t.content,
@@ -2205,13 +2919,20 @@ var SessionManager = class {
       messages.unshift({ role: "system", content: systemPrompt });
     }
     if (this.goalInjector && this.config.goalInjectionPosition === "pre_turn") {
-      const goalBlock = this.goalInjector.injectInto("");
-      messages.push({ role: "system", content: goalBlock });
-      this.emitTrace("planning", "goal_injected", { position: "pre_turn" });
+      const shouldInject = this.goalInjector.shouldInjectThisTurn(
+        iteration,
+        false,
+        this.config.goalInjectionN ?? 3
+      );
+      if (shouldInject) {
+        const goalBlock = this.goalInjector.getFormattedBlock();
+        messages.push({ role: "system", content: goalBlock });
+        this.emitTrace("planning", "goal_injected", { position: "pre_turn", iteration });
+      }
     }
     return messages;
   }
-  /** Checks the tool execution budget and throws descriptively if exceeded */
+  /** Checks the tool execution budget and throws descriptively if exceeded. */
   checkExecutionBudget(toolName) {
     const budget = this.config.toolExecutionBudget;
     if (!budget) return;
@@ -2229,7 +2950,11 @@ var SessionManager = class {
           `Tool execution budget exceeded: '${toolName}' has reached its per-tool limit of ${budget.maxCallsPerTool[toolName]}`
         );
         this.logger.warn(err.message);
-        this.emitTrace("budget", "tool_limit_exceeded", { toolName, limit: budget.maxCallsPerTool[toolName], totalTokens: this.totalTokens });
+        this.emitTrace("budget", "tool_limit_exceeded", {
+          toolName,
+          limit: budget.maxCallsPerTool[toolName],
+          totalTokens: this.totalTokens
+        });
         throw err;
       }
     }
@@ -2240,11 +2965,80 @@ var SessionManager = class {
       tokenBudgetRemaining: this.config.maxTokens - this.totalTokens
     });
   }
-  /** Records a tool call in budget counters */
+  /** Records a tool call in budget counters. */
   recordToolCall(toolName) {
     this.totalToolCallCount++;
     this.perToolCallCount.set(toolName, (this.perToolCallCount.get(toolName) ?? 0) + 1);
   }
+  // -----------------------------------------------------------------------
+  // Blob detection helpers
+  // -----------------------------------------------------------------------
+  isProbablyBase64(value) {
+    const v = value.trim();
+    if (v.startsWith("data:") && v.includes(";base64,")) return true;
+    if (v.length < 4096) return false;
+    if (/[^A-Za-z0-9+/=]/.test(v)) return false;
+    return true;
+  }
+  isBinaryLike(value) {
+    if (!value) return false;
+    if (typeof ArrayBuffer !== "undefined") {
+      if (value instanceof ArrayBuffer) return true;
+      if (ArrayBuffer.isView(value)) return true;
+    }
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(value)) return true;
+    return false;
+  }
+  async storeBlob(content, metadata) {
+    if (!this.config.stmRegistry) return null;
+    return this.config.stmRegistry.register(content, "blob", metadata);
+  }
+  async scrubBlobFields(value, toolName, depth = 0) {
+    if (!value || typeof value !== "object") return { value, changed: false };
+    if (depth > 2) return { value, changed: false };
+    if (Array.isArray(value)) {
+      let changed2 = false;
+      const out = [];
+      for (const item of value) {
+        const res = await this.scrubBlobFields(item, toolName, depth + 1);
+        out.push(res.value);
+        if (res.changed) changed2 = true;
+      }
+      return { value: out, changed: changed2 };
+    }
+    const obj = { ...value };
+    let changed = false;
+    for (const [key, v] of Object.entries(obj)) {
+      if (typeof v === "string" && this.isProbablyBase64(v)) {
+        const ref = await this.storeBlob(v, {
+          toolName,
+          key,
+          encoding: v.startsWith("data:") ? "data_url" : "base64"
+        });
+        if (ref) {
+          obj[key] = ref;
+          obj[`${key}Note`] = "Stored in STM";
+          changed = true;
+        }
+        continue;
+      }
+      if (this.isBinaryLike(v)) {
+        const ref = await this.storeBlob(v, { toolName, key });
+        if (ref) {
+          obj[key] = ref;
+          obj[`${key}Note`] = "Stored in STM";
+          changed = true;
+        }
+        continue;
+      }
+      if (typeof v === "object" && v !== null) {
+        const nested = await this.scrubBlobFields(v, toolName, depth + 1);
+        obj[key] = nested.value;
+        if (nested.changed) changed = true;
+      }
+    }
+    return { value: obj, changed };
+  }
   /**
    * Processes a firewall decision for a tool call.
    * Returns true to proceed, false to block.
@@ -2279,24 +3073,53 @@ var SessionManager = class {
   }
   /**
    * Executes a single parsed tool call and returns the serialised result string.
+   * Also handles continuation plan tracking (step status + output storage).
    */
   async executeSingleToolCall(tc) {
     this.checkExecutionBudget(tc.name);
-    const args = JSON.parse(tc.arguments);
+    let args = JSON.parse(tc.arguments);
+    if (this.continuationPlanner) {
+      const plan = this.continuationPlanner.getPlan();
+      const matchingStep = plan.steps.find(
+        (s) => s.toolName === tc.name && s.status === "pending"
+      );
+      if (matchingStep) {
+        this.continuationPlanner.markStepRunning(matchingStep.stepId);
+        args = this.continuationPlanner.resolveInputs(matchingStep, args);
+      }
+    }
     const executeContext = {
-      sessionId: "default",
+      sessionId: this.sessionId,
       turnIndex: this.context.turns.length,
       logger: this.logger,
       adapter: this.adapter,
       stmRegistry: this.config.stmRegistry,
-      scratchpad: this.context.scratchpad
+      scratchpad: this.context.scratchpad,
+      scratchpadAdapter: this.config.scratchpadAdapter
     };
     if (this.config.ragAdapter) {
       executeContext["ragAdapter"] = this.config.ragAdapter;
     }
-    this.logger.debug(`Executing tool: ${tc.name}`, { args: tc.arguments });
-    this.emitTrace("tool_call", tc.name, { id: tc.id }, tc.arguments, null, "running");
-    const result = await this.toolRegistry.execute(tc.name, args, executeContext);
+    this.logger.debug(`Executing tool: ${tc.name}`, { args: JSON.stringify(args) });
+    this.emitTrace("tool_call", tc.name, { id: tc.id }, JSON.stringify(args), null, "running");
+    let result;
+    let executionError = null;
+    try {
+      result = await this.toolRegistry.execute(tc.name, args, executeContext);
+    } catch (err) {
+      executionError = err;
+      if (this.continuationPlanner) {
+        const plan = this.continuationPlanner.getPlan();
+        const runningStep = plan.steps.find(
+          (s) => s.toolName === tc.name && s.status === "running"
+        );
+        if (runningStep) {
+          this.continuationPlanner.markStepFailed(runningStep.stepId);
+          this.context.metadata["continuationPlan"] = this.continuationPlanner.getPlan();
+        }
+      }
+      throw executionError;
+    }
     this.recordToolCall(tc.name);
     this.logger.debug(`Tool ${tc.name} returned successfully`);
     let finalResult = result;
@@ -2308,6 +3131,22 @@ var SessionManager = class {
         this.emitTrace("planning", "scratchpad_update", { note: resObj["note"] });
       }
     }
+    if (this.config.stmRegistry) {
+      if (typeof finalResult === "string" && this.isProbablyBase64(finalResult)) {
+        const ref = await this.storeBlob(finalResult, { toolName: tc.name, encoding: "base64" });
+        if (ref) {
+          finalResult = { blobRef: ref, note: "Binary content stored in STM" };
+        }
+      } else if (this.isBinaryLike(finalResult)) {
+        const ref = await this.storeBlob(finalResult, { toolName: tc.name });
+        if (ref) {
+          finalResult = { blobRef: ref, note: "Binary content stored in STM" };
+        }
+      } else if (typeof finalResult === "object" && finalResult !== null) {
+        const scrubbed = await this.scrubBlobFields(finalResult, tc.name);
+        if (scrubbed.changed) finalResult = scrubbed.value;
+      }
+    }
     let content = JSON.stringify(finalResult);
     const tokenCount = this.adapter.estimateTokens(content);
     if (this.config.maxTokensPerTool && tokenCount > this.config.maxTokensPerTool) {
@@ -2324,10 +3163,32 @@ var SessionManager = class {
       content = this.toolResponseProcessor.compress(content, evaluation);
       this.emitTrace("compression", tc.name, { originalSize: evaluation.sizeClass }, null, content);
     }
-    if (this.config.enableContinuationPlanning && evaluation.suggestedAction === "continue") {
-      this.emitTrace("planning", "continuation_detected", { toolName: tc.name, action: evaluation.suggestedAction });
+    if (this.continuationPlanner) {
+      const plan = this.continuationPlanner.getPlan();
+      const runningStep = plan.steps.find(
+        (s) => s.toolName === tc.name && s.status === "running"
+      );
+      if (runningStep) {
+        this.continuationPlanner.markStepDone(runningStep.stepId, content);
+        if (runningStep.outputKey) {
+          const outputs = this.context.metadata["toolOutputs"] ?? {};
+          outputs[runningStep.outputKey] = content;
+          this.context.metadata["toolOutputs"] = outputs;
+        }
+        this.context.metadata["continuationPlan"] = this.continuationPlanner.getPlan();
+        this.emitTrace("planning", "step_done", {
+          stepId: runningStep.stepId,
+          outputKey: runningStep.outputKey
+        });
+      }
+    }
+    if (evaluation.suggestedAction === "continue" && this.config.enableContinuationPlanning) {
+      this.emitTrace("planning", "continuation_detected", {
+        toolName: tc.name,
+        action: evaluation.suggestedAction
+      });
     }
-    this.emitTrace("tool_result", tc.name, { id: tc.id }, tc.arguments, content, "done");
+    this.emitTrace("tool_result", tc.name, { id: tc.id }, JSON.stringify(args), content, "done");
     return content;
   }
   // -----------------------------------------------------------------------
@@ -2336,18 +3197,38 @@ var SessionManager = class {
   /**
    * Runs the full ReAct loop for a user message and returns the final assistant response.
    *
+   * When `enableGoalPlanning` is true and no goal has been manually set, a mini-planning
+   * LLM call is made before the first iteration to decompose the task into sub-goals.
+   *
    * @param userMessage - The user's message (string or multimodal content blocks)
    * @returns The assistant's final response string
    * @throws {LemuraMaxIterationsError} When the loop exceeds `maxIterations`
    */
   async run(userMessage) {
     if (this.mcpReady) await this.mcpReady;
+    await this.ensureScratchpadLoaded();
     const userMessageStr = Array.isArray(userMessage) ? "[Multimodal Content]" : userMessage;
     this.logger.info(`Starting new session run`, {
       model: this.config.model,
       message: userMessageStr
     });
-    const systemPrompt = this.buildSystemPrompt(userMessageStr);
+    if (this.config.enableGoalPlanning && !this.goalInjector) {
+      this.goalInjector = new GoalInjector({
+        id: "auto",
+        statement: typeof userMessage === "string" ? userMessage : "[multimodal]",
+        decomposition: [],
+        successCriteria: ["The user request is fully answered"],
+        injectionFrequency: this.config.goalInjectionFrequency ?? "always",
+        injectionPosition: this.config.goalInjectionPosition ?? "system_prompt"
+      });
+      this.context.metadata["goal"] = this.goalInjector.getGoal();
+      this.logger.debug("Goal injector initialised (auto)");
+      this.emitTrace("planning", "goal_init", {
+        statement: this.goalInjector.getGoal().statement,
+        criteria: this.goalInjector.getGoal().successCriteria
+      });
+      await this._runMiniPlanningStep(userMessageStr);
+    }
     this.context.turns.push({
       role: "user",
       content: userMessage,
@@ -2358,18 +3239,24 @@ var SessionManager = class {
     const maxIts = this.config.maxIterations || 10;
     this.iterations = 0;
     this.stepCounter = new StepCounter(this.config.maxSteps ?? 20);
+    const maxCompletionTokens = this.config.maxCompletionTokens ?? 2e3;
     while (this.iterations < maxIts) {
       this.iterations++;
       this.logger.debug(`ReAct Iteration ${this.iterations}/${maxIts}`);
+      this.context.tokenCount = this.context.turns.reduce((sum, t) => sum + t.tokenCount, 0) + this.adapter.estimateTokens(this.context.systemPrompt || "");
       this.context = await this.contextManager.prepare(this.context);
-      let messages = this.buildMessages(systemPrompt);
+      const systemPrompt = this.buildSystemPrompt(userMessageStr, this.iterations);
+      let messages = this.buildMessages(systemPrompt, this.iterations);
       if (this.stepCounter.isMaxReached()) {
         this.logger.warn(`maxSteps (${this.config.maxSteps ?? 20}) reached \u2014 forcing final response`);
         messages.push({
           role: "system",
           content: this.stepCounter.getForcedConclusionPrompt() + "\n\n" + FinalResponseFormatter.getRequiredStructure()
         });
-        this.emitTrace("planning", "max_steps_reached", { maxSteps: this.config.maxSteps, currentSteps: this.stepCounter.count });
+        this.emitTrace("planning", "max_steps_reached", {
+          maxSteps: this.config.maxSteps,
+          currentSteps: this.stepCounter.count
+        });
       }
       this.logger.debug(`Calling provider adapter (${this.adapter.name})...`);
       this.emitTrace("thinking", "llm_call", {
@@ -2383,7 +3270,7 @@ var SessionManager = class {
           model: this.config.model,
           messages,
           tools: this.stepCounter.isMaxReached() ? [] : this.toolRegistry.getAll(),
-          maxTokens: 1e3
+          maxTokens: maxCompletionTokens
         });
       } catch (err) {
         const e = err;
@@ -2476,13 +3363,14 @@ var SessionManager = class {
           this.context.turns.push(toolTurn);
           if (this.config.onTurn) this.config.onTurn(toolTurn);
         }
+        if (this.goalInjector) this.goalInjector.incrementTurn();
         continue;
       }
       if (response.finishReason === "stop" || response.finishReason === "max_tokens" || response.finishReason === "error") {
         const finalTurn = {
           role: "assistant",
           content: response.content,
-          tokenCount: response.usage.completionTokens,
+          tokenCount: response.usage?.completionTokens ?? this.adapter.estimateTokens(response.content),
           turnIndex: this.context.turns.length,
           compressed: false
         };
@@ -2512,18 +3400,32 @@ var SessionManager = class {
    * @returns An `AsyncIterable<string>` of delta tokens from the final response
    *
    * @example
+   * ```typescript
    * for await (const token of session.stream('Tell me a story')) {
    *   process.stdout.write(token);
    * }
+   * ```
    */
   async *stream(userMessage) {
     if (this.mcpReady) await this.mcpReady;
+    await this.ensureScratchpadLoaded();
     const userMessageStr = Array.isArray(userMessage) ? "[Multimodal Content]" : userMessage;
     this.logger.info(`Starting streaming session run`, {
       model: this.config.model,
       message: userMessageStr
     });
-    const systemPrompt = this.buildSystemPrompt(userMessageStr);
+    if (this.config.enableGoalPlanning && !this.goalInjector) {
+      this.goalInjector = new GoalInjector({
+        id: "auto",
+        statement: typeof userMessage === "string" ? userMessage : "[multimodal]",
+        decomposition: [],
+        successCriteria: ["The user request is fully answered"],
+        injectionFrequency: this.config.goalInjectionFrequency ?? "always",
+        injectionPosition: this.config.goalInjectionPosition ?? "system_prompt"
+      });
+      this.context.metadata["goal"] = this.goalInjector.getGoal();
+      await this._runMiniPlanningStep(userMessageStr);
+    }
     this.context.turns.push({
       role: "user",
       content: userMessage,
@@ -2534,11 +3436,14 @@ var SessionManager = class {
     const maxIts = this.config.maxIterations || 10;
     this.iterations = 0;
     this.stepCounter = new StepCounter(this.config.maxSteps ?? 20);
+    const maxCompletionTokens = this.config.maxCompletionTokens ?? 2e3;
     while (this.iterations < maxIts) {
       this.iterations++;
       this.logger.debug(`[stream] ReAct Iteration ${this.iterations}/${maxIts}`);
+      this.context.tokenCount = this.context.turns.reduce((sum, t) => sum + t.tokenCount, 0) + this.adapter.estimateTokens(this.context.systemPrompt || "");
       this.context = await this.contextManager.prepare(this.context);
-      const messages = this.buildMessages(systemPrompt);
+      const systemPrompt = this.buildSystemPrompt(userMessageStr, this.iterations);
+      const messages = this.buildMessages(systemPrompt, this.iterations);
       if (this.stepCounter.isMaxReached()) {
         messages.push({
           role: "system",
@@ -2551,7 +3456,7 @@ var SessionManager = class {
           model: this.config.model,
           messages,
           tools: this.stepCounter.isMaxReached() ? [] : this.toolRegistry.getAll(),
-          maxTokens: 1e3
+          maxTokens: maxCompletionTokens
         });
       } catch (err) {
         this.logger.fatal(`Provider call failed: ${err.message}`);
@@ -2594,17 +3499,20 @@ var SessionManager = class {
           this.context.turns.push(toolTurn);
           if (this.config.onTurn) this.config.onTurn(toolTurn);
         }
+        if (this.goalInjector) this.goalInjector.incrementTurn();
         continue;
       }
+      this.context.tokenCount = this.context.turns.reduce((sum, t) => sum + t.tokenCount, 0) + this.adapter.estimateTokens(this.context.systemPrompt || "");
       this.context = await this.contextManager.prepare(this.context);
-      const finalMessages = this.buildMessages(systemPrompt);
+      const finalSystemPrompt = this.buildSystemPrompt(userMessageStr, this.iterations);
+      const finalMessages = this.buildMessages(finalSystemPrompt, this.iterations);
       let accumulated = "";
       let finalFinishReason = void 0;
       let finalTokenCount = 0;
       for await (const chunk of this.adapter.stream({
         model: this.config.model,
         messages: finalMessages,
-        maxTokens: 1e3,
+        maxTokens: maxCompletionTokens,
         stream: true
       })) {
         if (chunk.delta) {
@@ -2645,7 +3553,8 @@ var SessionManager = class {
   }
   /**
    * Resets the session: clears conversation history, resets iteration counters,
-   * and resets tool execution budgets. The adapter, config, and tools are retained.
+   * tool execution budget tallies, and goal/plan state.
+   * The adapter, config, compression strategies, and tools are retained.
    */
   reset() {
     this.context = {
@@ -2658,24 +3567,30 @@ var SessionManager = class {
     };
     this.iterations = 0;
     this.totalToolCallCount = 0;
+    this.totalTokens = 0;
     this.perToolCallCount.clear();
     this.stepCounter = new StepCounter(this.config.maxSteps ?? 20);
     this.goalInjector = null;
+    this.continuationPlanner = null;
+    this.scratchpadLoaded = false;
+    this.pendingScratchpadClear = !!this.config.scratchpadAdapter;
     this.logger.debug("Session reset");
   }
   /**
    * Closes the session and disconnects all MCP servers.
    *
-   * Call this when you are done with the session and have registered MCP servers,
-   * to ensure child processes are terminated and HTTP connections are released.
+   * Call this when you are done with the session to ensure child processes are
+   * terminated and HTTP connections are released.
    *
    * @example
+   * ```typescript
    * const session = new SessionManager({ ..., mcpServers: [...] });
    * try {
    *   await session.run('Hello');
    * } finally {
    *   await session.close();
    * }
+   * ```
    */
   async close() {
     if (this.mcpRegistry) {
@@ -2686,37 +3601,6 @@ var SessionManager = class {
   }
 };
 
-// src/agent/execution/ContinuationPlanner.ts
-var ContinuationPlanner = class {
-  constructor(plan) {
-    this.plan = plan;
-  }
-  getPlanStatusString() {
-    let result = `[CONTINUATION PLAN \u2014 Step ${this.plan.currentStepIndex + 1}/${this.plan.steps.length}]
-`;
-    for (const step of this.plan.steps) {
-      const getIcon = (status) => {
-        switch (status) {
-          case "done":
-            return "\u2705";
-          case "running":
-            return "\u25B6";
-          case "failed":
-            return "\u274C";
-          case "skipped":
-            return "\u23ED";
-          default:
-            return "\u23F3";
-        }
-      };
-      const statusText = step.status === "pending" && step.dependsOn.length > 0 ? `Waiting on Step ${step.dependsOn.join(", ")}` : step.status.charAt(0).toUpperCase() + step.status.slice(1);
-      result += `${getIcon(step.status)} Step ${step.stepId} (${step.toolName}): ${statusText}
-`;
-    }
-    return result;
-  }
-};
-
-export { ContextManager, ContinuationPlanner, DefaultLogger, FinalResponseFormatter, GoalInjector, HistoryCompressionStrategy, InMemoryRAGAdapter, InMemoryStorageAdapter, LemuraAdapterError, LemuraContextOverflowError, LemuraError, LemuraMCPConnectionError, LemuraMCPError, LemuraMCPTimeoutError, LemuraMaxIterationsError, LemuraSkillInjectionError, LemuraToolNotFoundError, LemuraToolTimeoutError, LemuraToolValidationError, LogLevel, MCPClient, MCPClientRegistry, MediaBridge, OpenAICompatibleAdapter, SandwichCompressionStrategy, ScratchpadStrategy, SessionManager, ShortTermMemoryRegistry, SkillInjector, StepCounter, ToolRegistry, ToolResponseProcessor, evaluateToolFirewall, validateJsonSchema };
+export { ContextManager, ContinuationPlanner, DefaultLogger, FinalResponseFormatter, GoalInjector, HistoryCompressionStrategy, InMemoryRAGAdapter, InMemoryScratchpadAdapter, InMemoryStorageAdapter, LemuraAdapterError, LemuraContextOverflowError, LemuraError, LemuraMCPConnectionError, LemuraMCPError, LemuraMCPTimeoutError, LemuraMaxIterationsError, LemuraSkillInjectionError, LemuraToolNotFoundError, LemuraToolTimeoutError, LemuraToolValidationError, LogLevel, MCPClient, MCPClientRegistry, MediaBridge, OpenAICompatibleAdapter, SandwichCompressionStrategy, ScratchpadStrategy, SessionManager, ShortTermMemoryRegistry, SkillInjector, StepCounter, SummaryInjectionStrategy, ToolRegistry, ToolResponseProcessor, evaluateToolFirewall, validateJsonSchema };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map