@tyvm/knowhow 0.0.142 → 0.0.144

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.142",
+  "version": "0.0.144",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/src/agents/developer/developer.ts

@@ -13,6 +13,10 @@ export class DeveloperAgent extends BaseAgent {
         model: Models.anthropic.Sonnet4_6,
         provider: "anthropic",
       },
+      {
+        model: Models.openai.GPT_56_Sol,
+        provider: "openai",
+      },
     ]);
   }
 
@@ -70,4 +74,3 @@ export class DeveloperAgent extends BaseAgent {
     ] as Message[];
   }
 }
-

package/src/agents/patcher/patcher.ts

@@ -81,7 +81,7 @@ export class PatchingAgent extends BaseAgent {
     this.setModelPreferences([
       { model: Models.anthropic.Sonnet4_6, provider: "anthropic" },
       { model: Models.openai.GPT_56_Sol, provider: "openai" },
-      { model: Models.xai.GrokCodeFast, provider: "xai" },
+      { model: Models.xai.Grok4_5, provider: "xai" },
     ]);
   }
 

package/src/agents/tools/connectAgent.ts

@@ -288,6 +288,7 @@ export const connectAgentDefinition: Tool = {
     parameters: {
       type: "object",
       positional: false,
+      usesContext: true,
       properties: {
         connections: {
           type: "array",
@@ -340,6 +341,7 @@ export const stopConnectionsDefinition: Tool = {
     parameters: {
       type: "object",
       positional: false,
+      usesContext: true,
       properties: {
         id: {
           type: "string",

package/src/agents/tools/observe.ts

@@ -182,6 +182,7 @@ export const observeDefinition: Tool = {
     parameters: {
       type: "object",
       positional: false,
+      usesContext: true,
       properties: {
         toolName: {
           type: "string",
@@ -232,6 +233,7 @@ export const stopObservingDefinition: Tool = {
     parameters: {
       type: "object",
       positional: false,
+      usesContext: true,
       properties: {
         id: {
           type: "string",

package/src/agents/tools/replyToParent.ts

@@ -110,6 +110,7 @@ export const replyToParentDefinition: Tool = {
     parameters: {
       type: "object",
       positional: true,
+      usesContext: true,
       properties: {
         message: {
           type: "string",

package/src/agents/tools/runGenerate.ts

@@ -142,6 +142,7 @@ export const runGenerateDefinition: Tool = {
       "When `sources` is omitted, it runs the sources defined in .knowhow/knowhow.json (optionally scoped by name/filter).",
     parameters: {
       type: "object",
+      usesContext: true,
       properties: {
         sources: {
           type: "array",

package/src/agents/tools/sendAgentMessage.ts

@@ -112,6 +112,7 @@ export const sendAgentMessageDefinition: Tool = {
     parameters: {
       type: "object",
       positional: false,
+      usesContext: true,
       properties: {
         taskId: {
           type: "string",

package/src/agents/tools/startAgentTask.ts

@@ -265,6 +265,7 @@ export const startAgentTaskDefinition: Tool = {
       "The return value includes the taskId and agent directory path when syncFs is used.",
     parameters: {
       type: "object",
+      usesContext: true,
       properties: {
         messageId: {
           type: "string",

package/src/agents/tools/waitForAgentCompleted.ts

@@ -246,6 +246,7 @@ export const waitForAgentCompletedDefinition: Tool = {
     parameters: {
       type: "object",
       positional: false,
+      usesContext: true,
       properties: {
         taskId: {
           type: "string",

package/src/chat/modules/SystemModule.ts

@@ -102,11 +102,12 @@ export class SystemModule extends BaseChatModule {
 
     // Get default model for new provider
     const ChatModelDefaults = {
-      openai: Models.openai.GPT_53_Codex,
+      openai: Models.openai.GPT_56_Sol,
       anthropic: Models.anthropic.Sonnet4_6,
-      google: Models.google.Gemini_3_Flash_Preview,
-      xai: Models.xai.Grok4_1_Fast_NonReasoning,
+      google: Models.google.Gemini_35_Flash_Lite,
+      xai: Models.xai.Grok4_5,
       knowhow: "anthropic/" + Models.anthropic.Sonnet4_6,
+      fireworks: Models.fireworks.KimiK3,
     };
 
     const newModel =

package/src/clients/pricing/fireworks.ts

@@ -1,45 +1,93 @@
 import { ModelPricing } from "./types";
 
 /**
- * Fireworks AI pricing (USD per 1M tokens)
+ * Fireworks AI model IDs, pricing, and catalog.
+ * Single source of truth for all Fireworks models.
  * Source: https://fireworks.ai/pricing
  */
+
+// ─── Model IDs ────────────────────────────────────────────────────────────────
+
+export const FireworksModels = {
+  // Moonshot AI
+  KimiK3:      "accounts/fireworks/models/kimi-k3",
+  KimiK2p7Code: "accounts/fireworks/models/kimi-k2p7-code",
+  KimiK2_6:    "accounts/fireworks/models/kimi-k2-6",
+  KimiK2_5:    "accounts/fireworks/models/kimi-k2-5",
+
+  // MiniMax
+  MinimaxM3:   "accounts/fireworks/models/minimax-m3",
+  MinimaxM2_7: "accounts/fireworks/models/minimax-m2-7",
+  MinimaxM2_5: "accounts/fireworks/models/minimax-m2-5",
+
+  // Qwen
+  Qwen3p7Plus: "accounts/fireworks/models/qwen3p7-plus",
+
+  // Deprecated Qwen Models
+  Qwen3_6Plus:                "accounts/fireworks/models/qwen3-6-plus",
+  Qwen3p6Plus:                "accounts/fireworks/models/qwen3p6-plus",
+  Qwen3Vl30bA3bThinking:      "accounts/fireworks/models/qwen3-vl-30b-a3b-thinking",
+  Qwen3Vl30bA3bInstruct:      "accounts/fireworks/models/qwen3-vl-30b-a3b-instruct",
+  Qwen3_8b:                   "accounts/fireworks/models/qwen3-8b",
+
+  // Z.ai
+  Glm5p2:  "accounts/fireworks/models/glm-5p2",
+  Glm5p1:  "accounts/fireworks/models/glm-5p1",
+  Glm5:    "accounts/fireworks/models/glm-5",
+  Glm4_7:  "accounts/fireworks/models/glm-4-7",
+
+  // DeepSeek AI
+  DeepseekV4Pro:   "accounts/fireworks/models/deepseek-v4-pro",
+  DeepseekV4Flash: "accounts/fireworks/models/deepseek-v4-flash",
+  DeepseekV3_2:    "accounts/fireworks/models/deepseek-v3-2",
+  DeepseekV3_1:    "accounts/fireworks/models/deepseek-v3-1",
+
+  // OpenAI OSS
+  GptOss120b: "accounts/fireworks/models/gpt-oss-120b",
+
+  // Embedding / Reranker
+  Qwen3Embedding8b: "accounts/fireworks/models/qwen3-embedding-8b",
+  Qwen3Reranker8b:  "accounts/fireworks/models/qwen3-reranker-8b",
+} as const;
+
+// ─── Text model pricing (USD per 1M tokens) ───────────────────────────────────
+
 export const FireworksTextPricing: Record<string, ModelPricing> = {
   // Moonshot AI
-  "accounts/fireworks/models/kimi-k3": { input: 3.0, cache_hit: 0.30, output: 15.0 },
-  "accounts/fireworks/models/kimi-k2p7-code": { input: 0.95, cache_hit: 0.19, output: 4.0 },
-  "accounts/fireworks/models/kimi-k2-6": { input: 0.95, cache_hit: 0.16, output: 4.0 },
-  "accounts/fireworks/models/kimi-k2-5": { input: 0.60, cache_hit: 0.10, output: 3.0 },
+  [FireworksModels.KimiK3]:       { input: 3.0, cache_hit: 0.30, output: 15.0 },
+  [FireworksModels.KimiK2p7Code]: { input: 0.95, cache_hit: 0.19, output: 4.0 },
+  [FireworksModels.KimiK2_6]:     { input: 0.95, cache_hit: 0.16, output: 4.0 },
+  [FireworksModels.KimiK2_5]:     { input: 0.60, cache_hit: 0.10, output: 3.0 },
 
   // MiniMax
-  "accounts/fireworks/models/minimax-m3": { input: 0.30, cache_hit: 0.06, output: 1.20 },
-  "accounts/fireworks/models/minimax-m2-7": { input: 0.30, cache_hit: 0.06, output: 1.20 },
-  "accounts/fireworks/models/minimax-m2-5": { input: 0.30, cache_hit: 0.03, output: 1.20 },
+  [FireworksModels.MinimaxM3]:    { input: 0.30, cache_hit: 0.06, output: 1.20 },
+  [FireworksModels.MinimaxM2_7]:  { input: 0.30, cache_hit: 0.06, output: 1.20 },
+  [FireworksModels.MinimaxM2_5]:  { input: 0.30, cache_hit: 0.03, output: 1.20 },
 
   // Qwen
-  "accounts/fireworks/models/qwen3p7-plus": { input: 0.40, cache_hit: 0.08, output: 1.60 },
+  [FireworksModels.Qwen3p7Plus]:  { input: 0.40, cache_hit: 0.08, output: 1.60 },
 
   // Deprecated QWEN Models
-  "accounts/fireworks/models/qwen3-6-plus": { input: 0.50, cache_hit: 0.10, output: 3.0, deprecated: true},
-  "accounts/fireworks/models/qwen3p6-plus": { input: 0.50, cache_hit: 0.10, output: 3.0, deprecated: true},
-  "accounts/fireworks/models/qwen3-vl-30b-a3b-thinking": { input: 0.15, cache_hit: 0.08, output: 0.60, deprecated: true},
-  "accounts/fireworks/models/qwen3-vl-30b-a3b-instruct": { input: 0.15, cache_hit: 0.08, output: 0.60, deprecated: true},
-  "accounts/fireworks/models/qwen3-8b": { input: 0.20, cache_hit: 0.10, output: 0.20, deprecated: true},
+  [FireworksModels.Qwen3_6Plus]:           { input: 0.50, cache_hit: 0.10, output: 3.0, deprecated: true },
+  [FireworksModels.Qwen3p6Plus]:           { input: 0.50, cache_hit: 0.10, output: 3.0, deprecated: true },
+  [FireworksModels.Qwen3Vl30bA3bThinking]: { input: 0.15, cache_hit: 0.08, output: 0.60, deprecated: true },
+  [FireworksModels.Qwen3Vl30bA3bInstruct]: { input: 0.15, cache_hit: 0.08, output: 0.60, deprecated: true },
+  [FireworksModels.Qwen3_8b]:              { input: 0.20, cache_hit: 0.10, output: 0.20, deprecated: true },
 
   // Z.ai
-  "accounts/fireworks/models/glm-5p2": { input: 1.40, cache_hit: 0.26, output: 4.40 },
-  "accounts/fireworks/models/glm-5p1": { input: 1.40, cache_hit: 0.26, output: 4.40 },
-  "accounts/fireworks/models/glm-5": { input: 1.00, cache_hit: 0.20, output: 3.20, deprecated: true },
-  "accounts/fireworks/models/glm-4-7": { input: 0.60, cache_hit: 0.30, output: 2.20, deprecated: true},
+  [FireworksModels.Glm5p2]: { input: 1.40, cache_hit: 0.26, output: 4.40 },
+  [FireworksModels.Glm5p1]: { input: 1.40, cache_hit: 0.26, output: 4.40 },
+  [FireworksModels.Glm5]:   { input: 1.00, cache_hit: 0.20, output: 3.20, deprecated: true },
+  [FireworksModels.Glm4_7]: { input: 0.60, cache_hit: 0.30, output: 2.20, deprecated: true },
 
   // DeepSeek AI
-  "accounts/fireworks/models/deepseek-v4-pro": { input: 1.74, cache_hit: 0.15, output: 3.48 },
-  "accounts/fireworks/models/deepseek-v4-flash": { input: 0.14, cache_hit: 0.03, output: 0.28 },
-  "accounts/fireworks/models/deepseek-v3-2": { input: 0.56, cache_hit: 0.28, output: 1.68, deprecated: true },
-  "accounts/fireworks/models/deepseek-v3-1": { input: 0.56, cache_hit: 0.28, output: 1.68, deprecated: true },
+  [FireworksModels.DeepseekV4Pro]:   { input: 1.74, cache_hit: 0.15, output: 3.48 },
+  [FireworksModels.DeepseekV4Flash]: { input: 0.14, cache_hit: 0.03, output: 0.28 },
+  [FireworksModels.DeepseekV3_2]:    { input: 0.56, cache_hit: 0.28, output: 1.68, deprecated: true },
+  [FireworksModels.DeepseekV3_1]:    { input: 0.56, cache_hit: 0.28, output: 1.68, deprecated: true },
 
   // OpenAI OSS
-  "accounts/fireworks/models/gpt-oss-120b": { input: 0.15, cache_hit: 0.01, output: 0.60 },
+  [FireworksModels.GptOss120b]: { input: 0.15, cache_hit: 0.01, output: 0.60 },
 };
 
 /**
@@ -48,8 +96,8 @@ export const FireworksTextPricing: Record<string, ModelPricing> = {
  */
 export const FireworksEmbeddingPricing: Record<string, ModelPricing> = {
   // Qwen3 Embedding 8B — $0.10/M tokens, context 40k
-  "accounts/fireworks/models/qwen3-embedding-8b": { input: 0.10, output: 0.10 },
+  [FireworksModels.Qwen3Embedding8b]: { input: 0.10, output: 0.10 },
 
   // Qwen3 Reranker 8B — $0.20/M tokens, context 40k
-  "accounts/fireworks/models/qwen3-reranker-8b": { input: 0.20, output: 0.20 },
+  [FireworksModels.Qwen3Reranker8b]: { input: 0.20, output: 0.20 },
 };

package/src/clients/types.ts

@@ -40,6 +40,14 @@ export interface Tool {
     parameters: {
       type: string;
       positional?: boolean;
+      /**
+       * When true, this tool is a local/in-memory (functional) tool that needs
+       * the per-call agent context. ToolsService will inject `_ctx` into the
+       * invocation (last positional arg for positional tools, or the `_ctx` key
+       * for non-positional tools). Tools that don't set this (e.g. MCP tools,
+       * which are serialized over the wire) never receive `_ctx`.
+       */
+      usesContext?: boolean;
       properties: {
         [key: string]: ToolProp;
       };

package/src/commands/sandbox.ts

@@ -60,6 +60,7 @@ interface SandboxSnapshot {
   status: string;
   errorMsg?: string | null;
   statusMessage?: string | null;
+  regenerationSandboxId?: string | null;
   snapshotContent?: string;
   setupScript?: string | null;
 }
@@ -122,6 +123,51 @@ async function resolveSnapshot(
 
 // ─── Polling helpers ──────────────────────────────────────────────────────────
 
+/**
+ * Poll a snapshot's status until regeneration is complete.
+ *
+ * The backend's POST /regenerate endpoint is fire-and-forget — it returns
+ * immediately with regenerationSandboxId set. We poll GET /snapshots/:id
+ * until one of:
+ *   - regenerationSandboxId is null AND status === "ready"  → success
+ *   - status === "error"                                    → failure
+ *   - deadline exceeded                                     → timeout
+ *
+ * statusMessage is printed whenever it changes so the user sees progress.
+ */
+async function pollRegeneration(
+  sandboxId: string,
+  snapshotId: string,
+  timeoutMs: number
+): Promise<SandboxSnapshot> {
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus = "";
+  let lastMessage = "";
+  while (Date.now() < deadline) {
+    const snap = await apiGet<SandboxSnapshot>(
+      `/sandboxes/${sandboxId}/snapshots/${snapshotId}`
+    );
+    if (snap.status !== lastStatus) {
+      console.log(`  [snapshot] status: ${snap.status}`);
+      lastStatus = snap.status;
+    }
+    if (snap.statusMessage && snap.statusMessage !== lastMessage) {
+      console.log(`  [snapshot] ${snap.statusMessage}`);
+      lastMessage = snap.statusMessage;
+    }
+    if (!snap.regenerationSandboxId && snap.status === "ready") return snap;
+    if (snap.status === "error") {
+      throw new Error(
+        `Snapshot regeneration failed: ${snap.errorMsg || snap.statusMessage || "(no details)"}`
+      );
+    }
+    await new Promise((r) => setTimeout(r, 5000));
+  }
+  throw new Error(
+    `Timeout waiting for snapshot regeneration to complete (${timeoutMs}ms). Last status: ${lastStatus}`
+  );
+}
+
 async function pollSandboxStatus(
   sandboxId: string,
   targetStatuses: string[],
@@ -373,7 +419,7 @@ export function addSandboxCommand(program: Command): void {
     .option("--sandbox-name <name>", "Source sandbox name (alternative to --sandbox-id)")
     .option("--snapshot-id <id>", "Snapshot ID to regenerate")
     .option("--snapshot-name <name>", "Snapshot label to regenerate")
-    .option("--no-wait", "Return immediately without waiting for snapshot to be ready")
+    .option("--no-wait", "Trigger regeneration and return immediately (do not poll for completion)")
     .option("--timeout-minutes <min>", "Max time for the full regen cycle", "60")
     .action(
       async (opts: {
@@ -381,20 +427,18 @@ export function addSandboxCommand(program: Command): void {
         sandboxName?: string;
         snapshotId?: string;
         snapshotName?: string;
-        wait: boolean; // commander flips --no-wait → wait=false
+        wait: boolean;
         timeoutMinutes: string;
       }) => {
         const timeoutMs = Number(opts.timeoutMinutes) * 60 * 1000;
-        const deadline = Date.now() + timeoutMs;
 
-        // ── 1. Resolve sandbox ──────────────────────────────────────────────
+        // ── 1. Resolve sandbox & snapshot ──────────────────────────────────
         if (!opts.sandboxId && !opts.sandboxName) {
           throw new Error("Provide --sandbox-id or --sandbox-name");
         }
         const sandboxId =
           opts.sandboxId || (await resolveSandboxId(opts.sandboxName!));
 
-        // ── 2. Resolve snapshot ─────────────────────────────────────────────
         if (!opts.snapshotId && !opts.snapshotName) {
           throw new Error("Provide --snapshot-id or --snapshot-name");
         }
@@ -410,132 +454,113 @@ export function addSandboxCommand(program: Command): void {
         );
         console.log(`   Source sandbox: ${sandboxId}`);
 
-        if (snapshot.status !== "ready") {
+        // ── 2. Validate preconditions ───────────────────────────────────────
+        if (snapshot.status !== "ready" && !snapshot.regenerationSandboxId) {
           throw new Error(
             `Snapshot must be in 'ready' status to regenerate (current: ${snapshot.status})`
           );
         }
-        if (!snapshot.setupScript) {
-          throw new Error(
-            "Snapshot has no setupScript. Add one via the UI before regenerating."
-          );
-        }
 
-        // ── 3. Fork ephemeral sandbox from the snapshot ─────────────────────
-        console.log("\n📦 Step 1/4: Forking ephemeral sandbox from snapshot...");
-        const ephemeralName = `regen-${snapshotId.slice(0, 8)}-${Date.now()}`;
-        const forkResult = await apiPost<{ id?: string; sandboxId?: string }>(
-          "/sandboxes/fork",
-          { snapshotId, name: ephemeralName }
+        // ── 3. Kick off background regeneration via backend API ─────────────
+        // The backend POST /regenerate endpoint returns immediately with the
+        // updated snapshot (regenerationSandboxId set). It runs the full
+        // cycle (fork ephemeral → setupScript → snapshot) in the background.
+        console.log("\n📡 Triggering backend regeneration...");
+        const triggered = await apiPost<SandboxSnapshot>(
+          `/sandboxes/${sandboxId}/snapshots/${snapshotId}/regenerate`
         );
-        const ephemeralId = forkResult.id || forkResult.sandboxId;
-        if (!ephemeralId) {
-          throw new Error(
-            `Fork did not return a sandbox ID: ${JSON.stringify(forkResult)}`
+        console.log(`   regenerationSandboxId: ${triggered.regenerationSandboxId || "(none)"}`);
+
+        if (!opts.wait) {
+          console.log(
+            `\n✅ Regeneration triggered. Monitor with:\n` +
+              `   knowhow sandbox snapshot-status --sandbox-id ${sandboxId} --snapshot-id ${snapshotId}`
           );
+          return;
         }
-        console.log(`   Ephemeral sandbox: ${ephemeralId} (${ephemeralName})`);
-
-        // ── 4. Wait for ephemeral sandbox to be running ─────────────────────
-        console.log("\n⏳ Step 2/4: Waiting for sandbox to start...");
-        await pollSandboxStatus(
-          ephemeralId,
-          ["running"],
-          Math.min(deadline - Date.now(), 10 * 60 * 1000),
-          ephemeralName
+
+        // ── 4. Poll until complete ──────────────────────────────────────────
+        console.log("\n⏳ Waiting for regeneration to complete (Ctrl+C to stop polling)...");
+        const done = await pollRegeneration(sandboxId, snapshotId, timeoutMs);
+
+        console.log(
+          `\n✅ Snapshot regeneration complete!\n` +
+            `   Snapshot ID : ${done.id}\n` +
+            `   Label       : ${done.label || "(none)"}\n` +
+            `   Status      : ${done.status}`
         );
-        console.log("   ✓ Running");
-
-        // ── 5. Execute the setupScript ──────────────────────────────────────
-        console.log("\n🔧 Step 3/4: Executing setupScript...");
-        console.log(`   Script length: ${snapshot.setupScript.length} chars`);
-        let execResult: { stdout?: string; stderr?: string; exitCode?: number };
-        try {
-          execResult = await apiPost<{
-            stdout?: string;
-            stderr?: string;
-            exitCode?: number;
-          }>(`/sandboxes/${ephemeralId}/exec`, {
-            command: "/bin/bash",
-            args: ["-c", snapshot.setupScript],
-            timeoutMs: Math.min(deadline - Date.now(), 25 * 60 * 1000),
-          });
-        } catch (err: any) {
-          console.error(`\n❌ setupScript exec failed: ${err.message}`);
-          await safeDestroy(ephemeralId);
-          throw err;
-        }
+      }
+    );
 
-        if (execResult.stdout) {
-          console.log("--- stdout ---");
-          process.stdout.write(execResult.stdout);
-        }
-        if (execResult.stderr) {
-          console.error("--- stderr ---");
-          process.stderr.write(execResult.stderr);
+  // ── sandbox snapshot-status ──────────────────────────────────────────────────
+  sandboxCmd
+    .command("snapshot-status")
+    .description(
+      "Check and optionally wait for a snapshot's regeneration to complete.\n" +
+        "Useful after triggering regeneration with --no-wait."
+    )
+    .option("--sandbox-id <id>", "Sandbox ID")
+    .option("--sandbox-name <name>", "Sandbox name")
+    .option("--snapshot-id <id>", "Snapshot ID")
+    .option("--snapshot-name <name>", "Snapshot label")
+    .option("--wait", "Poll until regeneration completes (or times out)")
+    .option("--timeout-minutes <min>", "Max poll time in minutes", "60")
+    .option("--json", "Output raw JSON")
+    .action(
+      async (opts: {
+        sandboxId?: string;
+        sandboxName?: string;
+        snapshotId?: string;
+        snapshotName?: string;
+        wait?: boolean;
+        timeoutMinutes: string;
+        json?: boolean;
+      }) => {
+        if (!opts.sandboxId && !opts.sandboxName) {
+          throw new Error("Provide --sandbox-id or --sandbox-name");
         }
-        if (execResult.exitCode != null && execResult.exitCode !== 0) {
-          await safeDestroy(ephemeralId);
-          throw new Error(`setupScript exited with code ${execResult.exitCode}`);
+        const sandboxId =
+          opts.sandboxId || (await resolveSandboxId(opts.sandboxName!));
+
+        if (!opts.snapshotId && !opts.snapshotName) {
+          throw new Error("Provide --snapshot-id or --snapshot-name");
         }
-        console.log("   ✓ setupScript completed");
-
-        // ── 6. Capture new snapshot with the same label ─────────────────────
-        console.log("\n📸 Step 4/4: Capturing new snapshot...");
-        const newLabel = snapshot.label || `regen-${snapshotId.slice(0, 8)}`;
-        let createResult: { snapshot?: SandboxSnapshot; id?: string };
-        try {
-          createResult = await apiPost<{ snapshot?: SandboxSnapshot; id?: string }>(
-            `/sandboxes/${ephemeralId}/snapshots`,
-            {
-              label: newLabel,
-              description: snapshot.description,
-              snapshotContent: snapshot.snapshotContent || "full",
-              snapshotType: "full",
-            }
+        const snapshot = opts.snapshotId
+          ? await apiGet<SandboxSnapshot>(
+              `/sandboxes/${sandboxId}/snapshots/${opts.snapshotId}`
+            )
+          : await resolveSnapshot(sandboxId, opts.snapshotName!);
+
+        if (opts.wait && snapshot.regenerationSandboxId) {
+          console.log("⏳ Waiting for regeneration to complete...");
+          const done = await pollRegeneration(
+            sandboxId,
+            snapshot.id,
+            Number(opts.timeoutMinutes) * 60 * 1000
           );
-        } catch (err: any) {
-          console.error(`\n❌ Snapshot creation failed: ${err.message}`);
-          await safeDestroy(ephemeralId);
-          throw err;
+          if (opts.json) {
+            console.log(JSON.stringify(done, null, 2));
+          } else {
+            console.log(
+              `✅ Done — status: ${done.status}  label: ${done.label || "(none)"}`
+            );
+          }
+          return;
         }
 
-        const newSnapshot = createResult.snapshot || (createResult as SandboxSnapshot);
-        const newSnapshotId = newSnapshot.id;
-        console.log(`   New snapshot ID: ${newSnapshotId}`);
-
-        if (opts.wait) {
-          console.log("   Waiting for snapshot upload...");
-          await pollSnapshotStatus(
-            ephemeralId,
-            newSnapshotId,
-            ["ready"],
-            Math.min(deadline - Date.now(), 20 * 60 * 1000)
+        if (opts.json) {
+          console.log(JSON.stringify(snapshot, null, 2));
+        } else {
+          const regenInfo = snapshot.regenerationSandboxId
+            ? `🔄 regenerating (ephemeral: ${snapshot.regenerationSandboxId})`
+            : `✅ ${snapshot.status}`;
+          console.log(
+            `Snapshot ${snapshot.id}  label=${snapshot.label || "(none)"}  ${regenInfo}`
           );
-          console.log("   ✓ Snapshot ready");
+          if (snapshot.statusMessage) {
+            console.log(`  message: ${snapshot.statusMessage}`);
+          }
         }
-
-        // ── 7. Destroy ephemeral sandbox ────────────────────────────────────
-        console.log("\n🗑  Destroying ephemeral sandbox...");
-        await safeDestroy(ephemeralId);
-        console.log("   ✓ Destroyed");
-
-        console.log(
-          `\n✅ Snapshot regeneration complete!\n` +
-            `   Old snapshot ID : ${snapshotId}\n` +
-            `   New snapshot ID : ${newSnapshotId}\n` +
-            `   Label           : ${newLabel}\n\n` +
-            `ℹ  The old snapshot still exists. Clean it up with:\n` +
-            `   knowhow sandbox delete-snapshot --sandbox-id ${sandboxId} --snapshot-id ${snapshotId}`
-        );
       }
     );
 }
-
-async function safeDestroy(sandboxId: string): Promise<void> {
-  try {
-    await apiDelete(`/sandboxes/${sandboxId}`);
-  } catch (err: any) {
-    console.warn(`⚠ Could not destroy sandbox ${sandboxId}: ${err.message}`);
-  }
-}

package/src/services/Mcp.ts

@@ -442,6 +442,9 @@ export class McpService {
 
     const realName = this.parseToolName(toolName);
     return async (args: any) => {
+      // MCP tools are registered without `usesContext`, so ToolsService.callTool
+      // never injects the per-call `_ctx` here — the args we receive are already
+      // safe to serialize over the wire (no circular BaseAgent/AI-client refs).
       console.log("Calling tool via mcp client", realName, "with args", args);
       const tool = await client.callTool(
         {

package/src/services/Tools.ts

@@ -245,9 +245,15 @@ export class ToolsService {
       const properties = toolDefinition?.function?.parameters?.properties || {};
       const isPositional =
         toolDefinition?.function?.parameters?.positional || false;
+      const usesContext =
+        toolDefinition?.function?.parameters?.usesContext || false;
 
       // Thread the per-call context (`_ctx`) into the invocation so tools can be
       // self-referential (e.g. read the calling agent off `_ctx.caller`).
+      // Only tools that opt-in via `usesContext: true` receive `_ctx`. This keeps
+      // the context (which holds non-serializable, circular references like the
+      // calling agent / AI client) out of tools that don't need it — notably MCP
+      // tools, whose args are serialized to JSON and sent over the wire.
       // - positional tools receive `_ctx` as the LAST positional argument
       // - non-positional tools receive it merged onto the args object as `_ctx`
       const ctx: ToolCallContext = { ...(callContext || {}), Tools: this };
@@ -257,8 +263,12 @@ export class ToolsService {
         : functionArgs;
 
       const fnArgs = isPositional
-        ? [...positionalArgs, ctx]
-        : { ...functionArgs, _ctx: ctx };
+        ? usesContext
+          ? [...positionalArgs, ctx]
+          : positionalArgs
+        : usesContext
+        ? { ...functionArgs, _ctx: ctx }
+        : functionArgs;
 
       // Execute the function
       const rawResponse = isPositional