bitfab-cli 0.2.378 → 0.2.380

package/dist/index.js

@@ -23942,10 +23942,11 @@ var deleteAssertionCategory = {
 var generateTraceAssertions = {
   name: "generate_trace_assertions",
   title: "Generate Trace Assertions",
-  description: "Generate review-ready assertion drafts from what one original trace actually did. Call this when the user asks Bitfab to generate assertions, infer expected behavior from a trace, or turn a known root cause into regression checks. Bitfab reads the organization's existing assertion categories, selects the categories supported by trace evidence, and generates assertions one category at a time. The generated assertions are saved awaiting human review, so they are not checked on replays until a person approves them. The call is idempotent by default and returns the assertions from the existing generation run instead of spending model calls again. Set regenerate to true to archive the prior generated drafts and replace them. Human-authored assertions are never replaced. Pass rootCause when the user knows why the trace was wrong; it narrows the evidence and produces smaller assertions. A replay trace id is refused because assertions belong to the original trace.",
+  description: "Generate review-ready assertion drafts from what one original trace actually did. Call this when the user asks Bitfab to generate assertions, infer expected behavior from a trace, or turn a known root cause into regression checks. Bitfab reads the organization's existing assertion categories, selects the categories supported by trace evidence, and generates assertions one category at a time. The generated assertions are saved awaiting human review, so they are not checked on replays until a person approves them. Generation runs on Bitfab and this call waits up to four minutes for it. If it is still running after that, the result says so, and calling again with the same traceId and without regenerate checks on it. A trace has one generation at a time, so a repeat call joins the running or finished generation instead of spending model calls again, and regenerate while one is running joins that one too. Set regenerate to true after it finishes to archive the prior generated drafts and replace them. A failed generation is returned as an error with its reason. Human-authored assertions are never replaced. Pass guidance when the user knows what the assertions should be about, most often a root cause analysis of why the trace was wrong; it narrows the evidence and produces smaller assertions. Pass categoryIds to limit generation to those assertion categories. A replay trace id is refused because assertions belong to the original trace.",
   inputSchema: {
     traceId: external_exports.uuid().describe("The ORIGINAL trace to generate assertions for. A replay trace id is refused, and the error names the original to retry with."),
-    rootCause: external_exports.string().trim().min(1).max(1e4).optional().describe("Optional known cause of the bad behavior. Use it to focus generation on the smallest assertions that would catch this failure."),
+    guidance: external_exports.string().trim().min(1).max(1e4).optional().describe("Optional assertion guidance, such as a root cause analysis of why the trace went wrong. Use it to focus generation on the smallest assertions that would catch this failure."),
+    categoryIds: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.uuid()).min(1)).optional().describe("Optional assertion category ids from list_assertion_categories. Limits generation to these categories. Omit to let Bitfab choose from every category in the organization. An id outside the organization fails the call before any work starts."),
     regenerate: external_exports.preprocess(parseJsonString, external_exports.boolean()).optional().describe("Set true to rerun generation and replace prior generated drafts. Omit or set false to reuse the existing generation result.")
   }
 };
@@ -23973,7 +23974,7 @@ var saveTraceAssertions = {
 var getTraceAssertions = {
   name: "get_trace_assertions",
   title: "Get Trace Assertions",
-  description: `Read what SHOULD happen when one or more traces are replayed: each trace's approved assertions, their pass/fail criteria, people-only human note, who is assigned to review each one, and what part of the evaluated trace each one checks. Only assertions a person has approved are returned, because only those are checked on a replay; a trace whose assertions are all still awaiting review reads the same as one with none. Categorized assertions include category_assertion_id and the category's id, title, and description. A human note is returned so it can be read and edited, but it is never assessment evidence: judge only from the assertion, pass/fail criteria, and evaluated trace. Call this before judging a replay so the verdict is measured against what the user actually asked for rather than a guess, and before save_trace_assertions to find the assertion to edit or to avoid creating a duplicate. No span content is loaded, so one call accepts up to ${GET_TRACE_ASSERTIONS_MAX_IDS} ids. Accepts original trace ids and replay trace ids alike: a replay with no assertions of its own reads its original's, and the response says which original they came from. An assertion whose target cannot be found on the trace being evaluated is errored, never passed, so record it with save_agent_labels \`skip\` rather than a FAIL.`,
+  description: `Read what SHOULD happen when one or more traces are replayed: each trace's approved assertions, their pass/fail criteria, people-only human note, who is assigned to review each one, and what part of the evaluated trace each one checks. Only assertions a person has approved are returned, because only those are checked on a replay; a trace whose assertions are all still awaiting review reads the same as one with none. Each trace also reports its assertion generation, if one ran: running, completed with how many drafts it saved for review, or failed with the reason. Categorized assertions include category_assertion_id and the category's id, title, and description. A human note is returned so it can be read and edited, but it is never assessment evidence: judge only from the assertion, pass/fail criteria, and evaluated trace. Call this before judging a replay so the verdict is measured against what the user actually asked for rather than a guess, and before save_trace_assertions to find the assertion to edit or to avoid creating a duplicate. No span content is loaded, so one call accepts up to ${GET_TRACE_ASSERTIONS_MAX_IDS} ids. Accepts original trace ids and replay trace ids alike: a replay with no assertions of its own reads its original's, and the response says which original they came from. An assertion whose target cannot be found on the trace being evaluated is errored, never passed, so record it with save_agent_labels \`skip\` rather than a FAIL.`,
   inputSchema: {
     traceIds: external_exports.preprocess(parseJsonString, external_exports.array(external_exports.uuid()).min(1).max(GET_TRACE_ASSERTIONS_MAX_IDS)).describe(`Original trace IDs to read assertions for (1-${GET_TRACE_ASSERTIONS_MAX_IDS})`)
   }
@@ -24906,10 +24907,10 @@ var semver3 = __toESM(require_semver2(), 1);
 
 // ../bitfab-plugin-lib/dist/bakedSdkVersions.js
 var BAKED_SDK_VERSIONS = {
-  typescript: "0.58.4",
-  python: "0.58.5",
-  ruby: "0.58.4",
-  go: "0.58.4"
+  typescript: "0.59.0",
+  python: "0.59.0",
+  ruby: "0.59.0",
+  go: "0.59.0"
 };
 
 // ../bitfab-plugin-lib/dist/installedSdk.js
@@ -32324,6 +32325,8 @@ Mark each key as \u2705 traces arriving (with most recent timestamp), \u26A0\uFE
    - **Bare trace-processor keys** ({{traceProcessorNames}} over plain \`run()\`): the processor captures the run but its root span records an empty input, so a processor-only key without the run wrapper {{traceProcessorRootWrappers}} or an application root is NOT replayable. Flag it \u26A0\uFE0F root not replayable and recommend adding a \`withTrace\`/\`trace\` root that takes the run input in supported subtree runtimes, or routing through the run wrapper. Recommend a manual \`withSpan\`/\`@span\` root only when opt-out is technically unavailable. When an application root exists, check its signature like any decorated key (next bullet).
    - **Decorated/wrapped keys**: read the root function signature and confirm it's replayable per Instrument's trace-boundary serializability requirement (serializable inputs). Flag any key whose root takes unserializable inputs (live SDK/DB clients, HTTP \`Request\`/\`Response\`, stream writers, sockets, opaque request contexts) as \u26A0\uFE0F root not replayable, reasoning from the signature, not the function name. This is independent of the replay-registry coverage in sub-step 3 above: a non-replayable root is \u26A0\uFE0F whether or not a registry exists for it (a key can be \u274C no replay registry module AND \u26A0\uFE0F root not replayable at once), so never roll a non-replayable root up into \u2705 just because it has no registry entry.
 
+5. **Subtree capture wiring**: an opt-out \`trace\`/\`withTrace\` root records the root and nothing beneath it unless the runtime support is actually there, which looks like healthy tracing until someone opens a trace and finds one node. Only check this when step {{step:inspect/gather-functions}} found an opt-out root; a repo whose roots are all \`withSpan\`/\`span\` needs none of it. **TypeScript** needs two things, both required: (a) \`@bitfab/transform\` in that workspace's manifest, and (b) an adapter wired into the build that produces the server entrypoint. Grep the build configuration and start scripts for \`@bitfab/transform/\`: \`next.config.*\`, \`vite.config.*\`, \`webpack.config.*\`, \`rspack.config.*\`, \`rsbuild.config.*\`, \`rollup.config.*\`, \`tsup.config.*\`, \`babel.config.*\`, Nest's \`webpackConfigPath\` target, or \`--import @bitfab/transform/register\` on the real start command. Mark \u2705 package present and adapter wired, \u26A0\uFE0F package installed but no adapter in the real build path, or \u274C package missing. **Python** needs 3.12+ instead; read the project's declared version and flag anything below it. The application's own log corroborates a \u274C or \u26A0\uFE0F finding: both SDKs log one \`[bitfab]\` warning when an opt-out root runs without its runtime support.
+
 Hold these results for the report. (If nothing is instrumented, no trace function keys AND no trace-processor registrations, skip both the **replay** and the **replayability** checks, they are per-workflow, so there's nothing to evaluate; report both as \`n/a (nothing instrumented)\`, never \u2705. Still run the **plugin** and **SDK** checks: the SDK may be installed and stale, or on the legacy \`bitfab\` package needing the \`@bitfab/sdk\` rename, independent of whether any trace functions exist in this repo yet.)`,
           next: "inspect/report"
         },
@@ -32338,11 +32341,13 @@ Hold these results for the report. (If nothing is instrumented, no trace functio
 - **Instrumented here**: the list of keys with \u2705 / \u26A0\uFE0F / \u2753 markers from step {{step:inspect/check-traces}}.
 - **Replay**: \u2705 covers all keys / \u26A0\uFE0F missing keys / \u274C none (from the replay-registry check in step {{step:inspect/check-freshness}}).
 - **Replayable**: \u2705 all roots replayable / \u26A0\uFE0F \`<key>\` root not replayable / \`n/a (nothing instrumented)\` (from the per-root replayability check in step {{step:inspect/check-freshness}}; flagged whether or not a replay registry module exists for the key; never \u2705 when nothing is instrumented).
+- **Subtree capture**: \u2705 wired / \u26A0\uFE0F \`@bitfab/transform\` installed but no adapter in the real build path / \u274C \`@bitfab/transform\` missing / \u274C Python below 3.12 / \`n/a (no opt-out roots)\` (from the subtree-capture check in step {{step:inspect/check-freshness}}).
 
 Then, for anything not healthy, name the most likely cause and the fix:
 - **Plugin or SDK out of date, or on the legacy \`bitfab\` package**: apply via the fix prompt below (upgrades the version and/or switches \`bitfab\` \u2192 \`@bitfab/sdk\`; same effect as \`{{cmd}}update\`).
 - **Replay missing or incomplete**: refresh via \`{{cmd}}setup replay\` (non-interactive; creates or extends registry entries to cover every key).
 - **Root not replayable**, two failure modes, with the fix matched to each: **(a) the root takes unserializable inputs** (live SDK/DB clients, HTTP req/res, streams, opaque contexts), with or without a replay registry module: move the trace boundary inward to a serializable-input function or refactor to introduce one; **(b) a bare trace-processor-only key** ({{traceProcessorNames}}) whose root is the processor's empty-input span: add a \`withTrace\`/\`trace\` root that wraps the run and takes its input in a supported subtree runtime, or route the run through the run wrapper ({{traceProcessorRootWrappers}}). Use a manual \`withSpan\`/\`@span\` root only when opt-out is technically unavailable. Either way, re-instrument via \`{{cmd}}setup modify\` (or \`{{cmd}}setup instrument\` for a fresh boundary). This is a code change, recommended here, not applied blanket.
+- **Opt-out roots without subtree capture**: every trace is the root alone, so tracing looks healthy and the traces are useless for per-step diagnosis, replay mocking, and prompt iteration. For TypeScript, install \`@bitfab/transform\` in that workspace and wire the matching adapter into the build behind the server entrypoint, preserving existing config wrappers such as Sentry. For Python, this is a runtime upgrade to 3.12+; report it rather than attempting it.
 - **Instrumented but no traces**: the app hasn't run with tracing enabled, or \`BITFAB_API_KEY\` isn't set in the run environment. Run the app with the key loaded.
 - **Key set but traces aren't visible in the browser**: the API key is bound to a different Clerk org/tenant than the browser session. A key resolves \`API key \u2192 organization_id \u2192 clerk_organization_id \u2192 Clerk tenant\` at creation time; browser visibility requires both to be the same tenant.
 - **Nothing instrumented**: run \`{{cmd}}setup instrument\`.
@@ -32356,7 +32361,7 @@ Then continue to the fix prompt. Inspect does not open Bitfab.`,
           kind: "branch",
           toolCalls: ["ask"],
           title: "Offer to apply the available fixes",
-          body: `If the report surfaced anything stale or missing (plugin behind, SDK out of date or on the legacy \`bitfab\` package, or replay registry modules missing/incomplete), {{askVerb}} whether to apply them, each fix is then confirmed individually in the next step (nothing is changed blanket). If everything is healthy, skip the question and go straight to cleanup.
+          body: `If the report surfaced anything stale or missing (plugin behind, SDK out of date or on the legacy \`bitfab\` package, replay registry modules missing/incomplete, or TypeScript subtree capture not wired), {{askVerb}} whether to apply them, each fix is then confirmed individually in the next step (nothing is changed blanket). If everything is healthy, skip the question and go straight to cleanup.
 
 {{branches}}`,
           branches: [
@@ -32395,6 +32400,7 @@ Then continue to the fix prompt. Inspect does not open Bitfab.`,
 - **SDK out of date** (\`updateAvailable: true\`, \`renameFrom\` null), name the workspace and the \`current \u2192 latest\` jump, then {{askVerb}} to upgrade; if yes, run the package manager's upgrade from that workspace directory (the same commands \`{{cmd}}update\` uses): npm / pnpm / yarn / bun \`add @bitfab/sdk@latest\`; uv / poetry / pip \`bitfab-py@latest\`; \`bundle update bitfab\`; \`go get github.com/Project-White-Rabbit/bitfab-go@latest && go mod tidy\`. Read the manifest afterward to confirm the new version. Each workspace is its own decision.
 - **On the legacy \`bitfab\` package** (\`renameFrom\` non-null), this rewrites import sites, so **preview before touching code**: list every \`from "bitfab"\` / \`require("bitfab")\` site you would change, then {{askVerb}} to proceed. If yes, remove the old package and add the new one in one step (e.g. \`pnpm remove bitfab && pnpm add @bitfab/sdk@latest\`, or the npm / yarn / bun equivalent) and rewrite those imports to \`@bitfab/sdk\`. Do this even when \`current\` already equals \`latest\`, the rename is the fix. (TypeScript-only; Python / Ruby / Go package names don't change.)
 - **Replay missing or incomplete**: {{askVerb}} to refresh; if yes, run \`{{cmd}}setup replay\` to create or extend the scripts so every trace function key is covered (it is non-interactive).
+- **Subtree capture not wired** (TypeScript), this edits a build file, so **preview before touching code**: name the workspace, the adapter you would use, and the exact config file or start script you would change, then {{askVerb}} to proceed. If yes, add \`@bitfab/transform\` as a development dependency in that workspace and wire the matching adapter: \`@bitfab/transform/next\` wrapping the existing \`next.config\`, the \`/vite\`, \`/rollup\`, \`/rolldown\`, \`/esbuild\`, \`/bun\`, \`/webpack\`, \`/rspack\`, \`/rsbuild\`, \`/babel\`, \`/nest\`, or \`/typescript\` entry in the existing build config, or \`--import @bitfab/transform/register\` on the real start command. Preserve every existing wrapper; never replace or bypass one. Python below 3.12 is a runtime upgrade, report it and do not attempt it.
 
 For unusual monorepos or private registries, defer to \`{{cmd}}update\`. Report what was applied and what the user declined. Do not open Bitfab.`,
           next: "cleanup/finish"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bitfab-cli",
-  "version": "0.2.378",
+  "version": "0.2.380",
   "description": "Install and configure the Bitfab plugin in Claude Code, Codex, or Cursor, or the Bitfab skill pack in Amp (Alpha).",
   "type": "module",
   "main": "dist/index.js",