bitfab-cli 0.2.258 → 0.2.259

package/dist/index.js

@@ -28415,13 +28415,13 @@ var saveTemplate = {
 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 callers above the root and ~10 surrounding callees below each leaf as `pure` context nodes), 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.",
+  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.",
   inputSchema: {
     language: external_exports.enum(["python", "typescript", "ruby", "go"]).describe("Source language of the user's code"),
     // 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 callers above the root and ~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."),
+    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."),
     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."),

package/package.json

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