bitfab-cli 0.2.259 → 0.2.261

package/dist/index.js

@@ -28412,20 +28412,24 @@ var saveTemplate = {
     description: external_exports.string().optional().describe("Optional description. Pass an empty string to clear an existing description.")
   }
 };
-var createTracePlan = {
-  name: "create_trace_plan",
-  title: "Create Trace Plan",
-  description: "Post a tracing instrumentation plan and get back a URL the user opens to review or adjust it. Send the full call tree (root + children + framework spans + ~10 surrounding callees below each leaf as `pure` context nodes, all of them descendants of the root), the initial recommended captured node ids, replay `analysis` (classification + kind) on every node, and any sample input/output stored on the relevant nodes. Pass `traceFunctionKey` so future Modify cycles for this same key can bootstrap from this plan via get_trace_plan. Returns a URL the user opens in the browser; after they close or update the plan there, call get_trace_plan to read the final captured set and the per-node replay/mock decisions, then act on them.",
+var saveTracePlan = {
+  name: "save_trace_plan",
+  title: "Save Trace Plan",
+  description: "Create or update a tracing instrumentation plan. CREATE: omit `planId` and send `language`, the full `tree`, `capturedNodeIds`, and usually `traceFunctionKey`; this creates a reviewable plan and returns its id, Studio URL, initial capture count, and expiry. UPDATE: pass `planId`; use targeted `capture` / `uncapture` and/or `mockOnReplayByNodeId` changes without restating the tree, or send `tree` plus `capturedNodeIds` together for a structural replacement. Targeted changes preserve status; a structural change to a confirmed plan reopens it to `awaiting`. Never create a second plan when one already exists for the work in hand: save it by `planId` instead. The captured set must stay one connected sub-tree with exactly one entry point, and that entry point always re-runs live and can never be mocked. Updates return the current plan summary, including the final captured set and replay/mock decisions.",
   inputSchema: {
-    language: external_exports.enum(["python", "typescript", "ruby", "go"]).describe("Source language of the user's code"),
+    planId: external_exports.string().optional().describe("Existing trace plan id to update. Omit to create a new plan. Do not send creation-only fields `language`, `source`, or `agentRunId` when this is supplied."),
+    language: external_exports.enum(["python", "typescript", "ruby", "go"]).optional().describe("CREATE mode. Source language of the user's code. Required when `planId` is omitted."),
     // Structured (not z.unknown()) so the tool's JSON Schema shows the agent
     // the per-node `analysis` field instead of burying it in prose, which is
     // how plans arrived with every node unclassified.
-    tree: external_exports.preprocess(parseJsonString, tracePlanTreeShape).describe("TracePlanTree: { rootId, nodes: { [id]: TraceNode } }. Each TraceNode has id, name, kind ('manual' | 'auto' | 'pure'), file, line, signature, parentId, childIds, plus optional framework, fields, sampleInput, sampleOutput. Every node, including uncaptured context nodes, must carry `analysis` describing WHAT THAT NODE DOES: { classification, sideEffectKind?, readKind?, innerCall?, mockable?, unmockableReason?, inputSerializable?, outputSerializable? }. Set `mockable` mechanically from the node's `kind`: `kind: 'manual'` (a hand-written `withSpan`/`@span`) is mockable, omit `mockable`; `kind: 'auto'` (captured by a framework handler/processor/stream/collector) gets `mockable: false` + `unmockableReason`, the ONE exception being Vercel AI SDK model spans (its `wrapLanguageModel` middleware routes the call through `withSpan`), which are mockable, omit; the root gets omit (never mockable). Rationale: mocking returns a span's recorded output instead of running the call, which only works when the call goes through a `withSpan` wrapper; `auto` framework spans are observed, not wrapped. Key hazard: an `auto` `external_read`/`side_effect` (a framework tool hitting a DB/HTTP) left mockable promises a mock replay can't deliver; its fix is a manual `withSpan` around that call or a db-snapshot, never a mock. Serializability is two raw facts, distinct from `mockable`: set `outputSerializable: false` when the recorded OUTPUT does not round-trip through serialization, and set `inputSerializable: false` when the recorded INPUT does not (its arguments hold a DB client, an open stream, a callback, or a class instance with no JSON form); omit either when it serializes (the default). Two rules follow. (1) Do NOT choose a root whose input is not serializable: replay re-runs the root against its recorded input, so a non-serializable-input root is not replayable, promote the root to a caller that takes a serializable input instead. (2) Do NOT mock a node whose output is not serializable (replay has no recorded value to return); the server enforces this by forcing any `outputSerializable: false` node unmockable, so you don't need to also set `mockable` for that reason. classification is 'pure' (deterministic local compute), 'model_call' (the span that IS the actual LLM/model call; a wrapper/orchestrator whose model call is represented by a child node, e.g. a LangChain chain.invoke or the root, is 'pure', not 'model_call'; never bubble a child's model_call up to its parent), 'external_read' (reads external mutable state: DB SELECT, outbound GET, vector search, cache read; set readKind), or 'side_effect' (mutates external state: DB write, outbound POST/PUT/DELETE, email, queue, payment, filesystem; set sideEffectKind). The server derives the replay disposition (`mockOnReplay`) and the whole validation summary from this classification and mockability, so do NOT send them. Include ~10 surrounding callees below each leaf as `pure` (uncaptured) context nodes so the user can see what's adjacent in the codebase when they edit in the UI. Every node MUST be a descendant of `rootId`: the plan tree renders downward from the root, so a node above the root or on a side branch off one of those ancestors is stored and counted but never drawn. Never send callers above the root."),
-    capturedNodeIds: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.string())).describe("Initial recommended captured set. Must reference ids present in tree.nodes. Must form a connected sub-tree rooted at one of the nodes (selecting any descendant implies its ancestors). Surrounding `pure` context nodes are not captured by default."),
+    tree: external_exports.preprocess(parseJsonString, tracePlanTreeShape).optional().describe("TracePlanTree: { rootId, nodes: { [id]: TraceNode } }. Each TraceNode has id, name, kind ('manual' | 'auto' | 'pure'), file, line, signature, parentId, childIds, plus optional framework, fields, sampleInput, sampleOutput. Every node, including uncaptured context nodes, must carry `analysis` describing WHAT THAT NODE DOES: { classification, sideEffectKind?, readKind?, innerCall?, mockable?, unmockableReason?, inputSerializable?, outputSerializable? }. Set `mockable` mechanically from the node's `kind`: `kind: 'manual'` (a hand-written `withSpan`/`@span`) is mockable, omit `mockable`; `kind: 'auto'` (captured by a framework handler/processor/stream/collector) gets `mockable: false` + `unmockableReason`, the ONE exception being Vercel AI SDK model spans (its `wrapLanguageModel` middleware routes the call through `withSpan`), which are mockable, omit; the root gets omit (never mockable). Rationale: mocking returns a span's recorded output instead of running the call, which only works when the call goes through a `withSpan` wrapper; `auto` framework spans are observed, not wrapped. Key hazard: an `auto` `external_read`/`side_effect` (a framework tool hitting a DB/HTTP) left mockable promises a mock replay can't deliver; its fix is a manual `withSpan` around that call or a db-snapshot, never a mock. Serializability is two raw facts, distinct from `mockable`: set `outputSerializable: false` when the recorded OUTPUT does not round-trip through serialization, and set `inputSerializable: false` when the recorded INPUT does not (its arguments hold a DB client, an open stream, a callback, or a class instance with no JSON form); omit either when it serializes (the default). Two rules follow. (1) Do NOT choose a root whose input is not serializable: replay re-runs the root against its recorded input, so a non-serializable-input root is not replayable, promote the root to a caller that takes a serializable input instead. (2) Do NOT mock a node whose output is not serializable (replay has no recorded value to return); the server enforces this by forcing any `outputSerializable: false` node unmockable, so you don't need to also set `mockable` for that reason. classification is 'pure' (deterministic local compute), 'model_call' (the span that IS the actual LLM/model call; a wrapper/orchestrator whose model call is represented by a child node, e.g. a LangChain chain.invoke or the root, is 'pure', not 'model_call'; never bubble a child's model_call up to its parent), 'external_read' (reads external mutable state: DB SELECT, outbound GET, vector search, cache read; set readKind), or 'side_effect' (mutates external state: DB write, outbound POST/PUT/DELETE, email, queue, payment, filesystem; set sideEffectKind). The server derives the replay disposition (`mockOnReplay`) and the whole validation summary from this classification and mockability, so do NOT send them. Include ~10 surrounding callees below each leaf as `pure` (uncaptured) context nodes so the user can see what's adjacent in the codebase when they edit in the UI. Every node MUST be a descendant of `rootId`: the plan tree renders downward from the root, so a node above the root or on a side branch off one of those ancestors is stored and counted but never drawn. Never send callers above the root."),
+    capturedNodeIds: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.string())).optional().describe("CREATE or STRUCTURAL update mode. Absolute captured set for `tree`. Required with `tree`; must reference ids in the tree and form one connected sub-tree."),
+    capture: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.string())).optional().describe("TARGETED update mode. Node ids to add to the existing captured set. Requires `planId`; cannot be combined with `tree` / `capturedNodeIds`."),
+    uncapture: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.string())).optional().describe("TARGETED update mode. Node ids to remove from the existing captured set. Requires `planId`; cannot be combined with `tree` / `capturedNodeIds`."),
+    mockOnReplayByNodeId: external_exports.preprocess(parseJsonString, external_exports.record(external_exports.string(), external_exports.boolean())).optional().describe("UPDATE mode. Per-node replay/mock overrides. Only listed nodes change. The replay entry point and framework-observed spans cannot be mocked."),
     stats: external_exports.preprocess(parseJsonString, external_exports.unknown()).optional().describe("Optional sample-run stats: { durationMs?, tokens?, cost? }"),
-    traceFunctionKey: external_exports.string().min(1).optional().describe("Optional trace function key (the string passed to getFunction / get_function / bitfab_function / WithFunctionName). Persisted on the plan so Modify cycles can fetch this plan as the `before` tree via get_trace_plan with the same key."),
-    source: external_exports.enum(["interactive", "analyze_repo"]).optional().describe("How this plan was produced. Omit (defaults to 'interactive') for a normal Instrument/Modify cycle the user confirms in the browser. Set 'analyze_repo' ONLY from the non-interactive `analyze-repo` batch mode, so these auto-drafted, unconfirmed plans are marked distinctly from interactively-confirmed ones."),
+    traceFunctionKey: external_exports.string().min(1).optional().describe("Trace function key. Recommended when creating; when updating, pass only to rename a key that was wrong or changed."),
+    source: external_exports.enum(["interactive", "analyze_repo"]).optional().describe("CREATE mode. How this plan was produced. Omit for a normal interactive plan; set 'analyze_repo' only from analyze-repo batch mode."),
     agentRunId: external_exports.uuid().optional()
   }
 };
@@ -28434,32 +28438,17 @@ var confirmTracePlan = {
   title: "Confirm Trace Plan",
   description: "Confirm a trace plan WITHOUT the browser, for the continue path where the user accepted the ASCII plan in chat, or left the Studio plan page without saving. Persists the plan as the latest *confirmed* plan for its traceFunctionKey (so later get_trace_plan by key, setup view, and setup modify can find it) and returns the final captured set plus per-node replay/mock decisions, exactly like get_trace_plan. Studio's Close/Update button does this for the browser path; call this only when the user continues without Studio, or leaves the plan page without saving. Pass the recommended capturedNodeIds; omit mockOnReplayByNodeId to accept the analysis-derived replay decisions (only pass it to override specific nodes the way a Studio toggle would).",
   inputSchema: {
-    planId: external_exports.string().describe("The trace plan id returned by create_trace_plan."),
+    planId: external_exports.string().describe("The trace plan id returned by save_trace_plan."),
     capturedNodeIds: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.string()).min(1)).describe("The captured set to confirm. Must reference ids present in the plan's tree and form a single connected sub-tree with one entry point (its top-most captured span). The entry point does NOT have to be the plan's tree root: untracing the tree root and rooting at a captured descendant is honored and persisted as-is."),
     mockOnReplayByNodeId: external_exports.preprocess(parseJsonString, external_exports.record(external_exports.string(), external_exports.boolean())).optional().describe("Optional per-node overrides of the replay/mock decision (the equivalent of a Studio toggle). Omit to accept the server's analysis-derived defaults. The replay entry point (the top-most captured span) always re-runs live and cannot be mocked.")
   }
 };
-var updateTracePlan = {
-  name: "update_trace_plan",
-  title: "Update Trace Plan",
-  description: "Change an EXISTING trace plan in place. Use this instead of create_trace_plan whenever a plan already exists for the work in hand (a Modify cycle bootstrapped via get_trace_plan, or an adjustment to a plan you just created): re-uploading produces a second plan competing for the same traceFunctionKey. Two mutually exclusive modes. TARGETED: pass `capture` / `uncapture` (node ids to add to or remove from the captured set) and/or `mockOnReplayByNodeId` (per-node replay/mock overrides) to adjust dispositions without restating the tree; deltas apply to the plan's current state, so they do not clobber a capture the user just saved in Studio. STRUCTURAL: pass `tree` plus `capturedNodeIds` together to replace the plan's whole node tree, for when the code changed and nodes must be added or removed. Sending both modes at once is an error. A structural update on a CONFIRMED plan reopens it to `awaiting`, because replacing the tree invalidates the user's acceptance, so you must confirm_trace_plan again afterwards or `setup view`/`setup modify` will not find a confirmed plan for that key; a targeted update leaves the status alone. Any update refreshes the plan's expiry, so it also revives an expired plan. The captured set must stay one connected sub-tree with exactly one entry point, and that entry point always re-runs live and can never be mocked. Returns the resulting plan exactly as get_trace_plan does, including the final captured set and per-node replay/mock decisions.",
-  inputSchema: {
-    planId: external_exports.string().describe("The trace plan id returned by create_trace_plan."),
-    capture: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.string())).optional().describe("TARGETED mode. Node ids to add to the captured set. Must reference ids present in the plan's tree. Cannot be combined with `tree` / `capturedNodeIds`."),
-    uncapture: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.string())).optional().describe("TARGETED mode. Node ids to remove from the captured set. Must reference ids present in the plan's tree. Removing a node that joins two captured branches leaves a disconnected capture set and is rejected. Cannot be combined with `tree` / `capturedNodeIds`."),
-    mockOnReplayByNodeId: external_exports.preprocess(parseJsonString, external_exports.record(external_exports.string(), external_exports.boolean())).optional().describe("Per-node overrides of the replay/mock decision (the equivalent of a Studio toggle): true serves the span's recorded output on replay, false re-runs it live. Only the listed nodes change. Valid in either mode. The replay entry point cannot be mocked, and neither can a framework-observed (`kind: 'auto'`) span, since replay cannot short-circuit one."),
-    tree: external_exports.preprocess(parseJsonString, tracePlanTreeShape).optional().describe("STRUCTURAL mode. The full replacement TracePlanTree, same shape and the same per-node `analysis` requirements as create_trace_plan. Send this only when the plan's nodes themselves change (code moved, a call was added or removed); to merely capture or mock differently use `capture` / `uncapture` / `mockOnReplayByNodeId`. Must be sent together with `capturedNodeIds`. `rootId` cannot be changed; to move the replay entry point, change which nodes are captured instead, an uncaptured tree root is honored and the top-most captured span becomes the entry."),
-    capturedNodeIds: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.string())).optional().describe("STRUCTURAL mode. The absolute captured set for the replacement `tree`, restated in full. Must reference ids present in that tree and form a single connected sub-tree with one entry point. Required with `tree`, and invalid without it."),
-    traceFunctionKey: external_exports.string().min(1).optional().describe("Optional replacement trace function key, for when the key the plan was created with was wrong or is being renamed."),
-    stats: external_exports.preprocess(parseJsonString, external_exports.unknown()).optional().describe("Optional sample-run stats: { durationMs?, tokens?, cost? }")
-  }
-};
 var getTracePlan = {
   name: "get_trace_plan",
   title: "Get Trace Plan",
-  description: "Read a trace plan. Two modes: pass `planId` to read a specific plan (use this after create_trace_plan + browser confirmation to learn whether the user confirmed, cancelled, or is still pending); or pass `traceFunctionKey` to fetch the latest *confirmed* plan for that key (use this at the start of a Modify cycle to bootstrap the `before` tree from the prior plan, so you don't have to re-derive it from the code). Returns the full plan including the tree as JSON.",
+  description: "Read a trace plan. Two modes: pass `planId` to read a specific plan (use this after save_trace_plan + browser confirmation to learn whether the user confirmed, cancelled, or is still pending); or pass `traceFunctionKey` to fetch the latest *confirmed* plan for that key. At the start of a Modify cycle, treat that confirmed plan as historical intent and reconcile its tree and captured nodes with current code; never assume the stored snapshot proves current instrumentation or use it to skip rereading code. Returns the full plan including the tree as JSON.",
   inputSchema: {
-    planId: external_exports.string().optional().describe("The trace plan id returned by create_trace_plan."),
+    planId: external_exports.string().optional().describe("The trace plan id returned by save_trace_plan."),
     traceFunctionKey: external_exports.string().optional().describe("Trace function key. Returns the latest confirmed plan for this key in the caller's organization, or a 'no prior plan' message if none exists.")
   }
 };
@@ -28536,9 +28525,8 @@ var ALL_TOOL_CONTRACTS = [
   getTemplateReference,
   getTemplate,
   saveTemplate,
-  createTracePlan,
+  saveTracePlan,
   confirmTracePlan,
-  updateTracePlan,
   getTracePlan,
   listTracePlans
 ];
@@ -29630,7 +29618,7 @@ function activityLabelFromEvent(event) {
 }
 function friendlyToolLabel(block) {
   const name = typeof block.name === "string" ? block.name : "";
-  if (name.includes("create_trace_plan")) {
+  if (name.includes("save_trace_plan") || name.includes("create_trace_plan")) {
     return "Uploading a draft trace plan";
   }
   if (name.includes("get_bitfab_api_key")) {
@@ -29681,7 +29669,7 @@ function countUploadedTracePlans(logText) {
         continue;
       }
       const b = block;
-      if (b.type === "tool_use" && typeof b.id === "string" && typeof b.name === "string" && b.name.includes("create_trace_plan")) {
+      if (b.type === "tool_use" && typeof b.id === "string" && typeof b.name === "string" && (b.name.includes("save_trace_plan") || b.name.includes("create_trace_plan"))) {
         planToolUseIds.add(b.id);
       }
       if (b.type === "tool_result" && typeof b.tool_use_id === "string" && b.is_error !== true) {
@@ -29962,7 +29950,7 @@ function codexActivityLabelFromEvent(event) {
   if (!item) {
     return null;
   }
-  if (isMcpToolItem(item, "create_trace_plan")) {
+  if (isMcpToolItem(item, "save_trace_plan") || isMcpToolItem(item, "create_trace_plan")) {
     return "Uploading a draft trace plan";
   }
   if (isMcpToolItem(item, "get_bitfab_api_key")) {
@@ -29995,7 +29983,7 @@ function countUploadedTracePlans2(logText) {
       continue;
     }
     const item = eventItem(event);
-    if (item && isMcpToolItem(item, "create_trace_plan")) {
+    if (item && (isMcpToolItem(item, "save_trace_plan") || isMcpToolItem(item, "create_trace_plan"))) {
       const status = typeof item.status === "string" ? item.status : "";
       if (status === "completed" || status === "" && eventType(event) === "item.completed") {
         completedPlanCalls++;
@@ -30006,7 +29994,7 @@ function countUploadedTracePlans2(logText) {
         continue;
       }
       const b = block;
-      if (b.type === "tool_use" && typeof b.id === "string" && typeof b.name === "string" && b.name.includes("create_trace_plan")) {
+      if (b.type === "tool_use" && typeof b.id === "string" && typeof b.name === "string" && (b.name.includes("save_trace_plan") || b.name.includes("create_trace_plan"))) {
         planToolUseIds.add(b.id);
       }
       if (b.type === "tool_result" && typeof b.tool_use_id === "string" && b.is_error !== true) {
@@ -30343,7 +30331,7 @@ function cursorActivityLabelFromEvent(event) {
     return null;
   }
   const mcpToolName = mcpToolCallName(toolCall);
-  if (mcpToolName?.includes("create_trace_plan")) {
+  if (mcpToolName?.includes("save_trace_plan") || mcpToolName?.includes("create_trace_plan")) {
     return "Uploading a draft trace plan";
   }
   if (mcpToolName?.includes("get_bitfab_api_key")) {
@@ -30390,7 +30378,7 @@ function countUploadedTracePlans3(logText) {
     } catch {
       continue;
     }
-    if (isSuccessfulCreateTracePlanEvent(event)) {
+    if (isSuccessfulSaveTracePlanEvent(event)) {
       completedPlanCalls++;
     }
   }
@@ -30399,7 +30387,7 @@ function countUploadedTracePlans3(logText) {
   }
   return 0;
 }
-function isSuccessfulCreateTracePlanEvent(event) {
+function isSuccessfulSaveTracePlanEvent(event) {
   if (typeof event !== "object" || event === null) {
     return false;
   }
@@ -30423,7 +30411,7 @@ function isSuccessfulCreateTracePlanEvent(event) {
     typeof args === "object" && args !== null ? args.name : void 0
   ];
   return names.some(
-    (name) => typeof name === "string" && name.includes("create_trace_plan")
+    (name) => typeof name === "string" && (name.includes("save_trace_plan") || name.includes("create_trace_plan"))
   ) && hasSuccessfulToolResult(call.result);
 }
 function hasSuccessfulToolResult(result) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitfab-cli",
-  "version": "0.2.259",
+  "version": "0.2.261",
   "description": "Install and configure the Bitfab plugin in Claude Code, Codex, or Cursor.",
   "type": "module",
   "main": "dist/index.js",