agentfootprint-lens 0.31.1 → 0.32.0

package/README.md

@@ -222,6 +222,142 @@ use `observeRecording`.
 
 ---
 
+## Report a bug with this run
+
+A bug report about an agent is only worth reading with the run attached. A run
+carries prompts, tool arguments and retrieved documents — which is exactly why
+nobody should send one without seeing it first.
+
+`<BugReportButton>` puts the consent step in the way. Clicking it opens a dialog
+that shows every selectable unit of evidence — one row per conversation, one per
+derived file — with its size, its event and turn counts, and the names of every
+state key that was already scrubbed. The reporter's own account (title, steps,
+expected, actual) is in the same dialog, because a report missing either half is
+not one. Nothing leaves until a person ticks it.
+
+The evidence itself is agentfootprint's (9.9.0 or newer): `describeBugReport`
+measures the run, `exportBugReport` bundles the units that were kept. Lens
+renders the offer and hands the ids back — it never assembles a bundle and never
+decides what a unit is.
+
+```tsx
+import { BugReportButton } from 'agentfootprint-lens';
+
+// The whole integration. `source` is whatever this Lens is already showing.
+<BugReportButton
+  source={recording}                                // or a recordRun() handle, a Runner, or an array
+  issuesUrl="https://github.com/acme/agent/issues"  // owner + repo are read from this
+  labels={['bug', 'from-lens']}
+/>;
+```
+
+### What the reporter sees
+
+- **The consent manifest** — one checkbox per unit. The **3 most recent
+  conversations** start ticked, older ones do not (`defaultRecentConversations`
+  changes the number). Derived files — the readable transcript, the narrative,
+  the environment block — are rebuilt over the conversations that survive, so
+  unticking a conversation takes it out of those too.
+- **A live size meter** — `12.4 MB of 24.0 MB`, recomputed on every toggle. Over
+  the ceiling it turns red, submit is refused, and it names what to do about it:
+  *"Untick conv-3 (20.0 MB) to fit."* The number is an estimate and says so — the
+  derived files shrink as conversations come out, so the real zip is that size or
+  smaller.
+- **The redacted keys, by name.** footprintjs scrubbed the values upstream at
+  commit time; the manifest can therefore say *which* secrets were protected
+  without ever carrying one.
+
+### The three submit modes
+
+They stack by what you configured. The first is always there, so the button is
+never a dead end, and a mode you did not configure is simply not offered —
+nothing fails at click time.
+
+| mode | needs | who the issue is from | where the zip goes |
+|---|---|---|---|
+| **Copy report + download zip** | nothing | the reporter, by hand | their machine |
+| **Sign in with GitHub** | `deviceClientId` | the reporter, as themselves | their machine, attached by hand |
+| **File automatically** | `endpoint` | your application | wherever your relay puts it |
+
+**(a) Copy + download** copies the composed issue body to the clipboard, saves
+the evidence zip, and opens the repo's new-issue form prefilled. A body too long
+for a URL is cut at a line break with a sentence pointing at the clipboard,
+never silently shortened.
+
+**(b) Sign in with GitHub** runs the OAuth **device flow** inside the dialog:
+Lens shows the user code and the verification link, GitHub polls in the
+background, and on approval the issue is filed from the browser as *that person*
+— so a maintainer can ask them a follow-up.
+
+```tsx
+<BugReportButton
+  source={recording}
+  issuesUrl="https://github.com/acme/agent/issues"
+  deviceClientId="Iv1.0123456789abcdef"   // an OAuth App with Device Flow enabled
+/>;
+```
+
+The client id is public by design (the device flow has no client secret). The
+token it yields is not: Lens holds it in memory for the life of the modal and
+drops it — never `localStorage`, never a cookie, never a log line, never the
+issue body. Signing in does not give Lens anywhere to push the zip, so the zip
+downloads to the reporter's machine and the issue says plainly that it must be
+attached by hand.
+
+**(c) File automatically** POSTs the finished bundle to your own endpoint, which
+holds the token and files the report with `githubBugReporter`. One click for the
+reporter; nothing about your repository lives in the browser.
+
+```tsx
+<BugReportButton source={recording} issuesUrl={ISSUES} endpoint="/api/bug-report" />;
+```
+
+```ts
+// The server side, in full. The browser already built the bundle — the relay
+// only holds the credential.
+import { githubBugReporter } from 'agentfootprint/observe';
+
+const reporter = githubBugReporter({ issueRepo: 'acme/agent' }); // token: GITHUB_TOKEN
+
+app.post('/api/bug-report', async (req, res) => {
+  const { manifest, filename, zipBase64 } = req.body; // kind: 'agentfootprint-lens.bug-report'
+  const zip = Buffer.from(zipBase64, 'base64');
+  res.json(await reporter.file({ manifest, files: [], zip, filename }));
+});
+```
+
+The response Lens renders is `{ issueUrl, zipUrl }`; anything else — a non-2xx,
+an `error` string — is shown to the reporter exactly as the server wrote it.
+That is the rule for every failure in this flow: agentfootprint's refusals teach
+what to do next, so they are rendered verbatim rather than paraphrased.
+
+### On an older agentfootprint
+
+The substrate shipped in agentfootprint 9.9.0. On 7.x or 8.x the button does not
+render at all — a one-line hint says which version it needs. Lens will not send
+a run it cannot measure first.
+
+### Props
+
+| prop | | |
+|---|---|---|
+| `source` | required | a `Recording`, a `recordRun()` handle, a `Runner`, or an array of them |
+| `issuesUrl` | required | `https://github.com/OWNER/REPO/issues` — owner, repo and API root are read from it (GitHub Enterprise Server works unchanged) |
+| `endpoint` | | your relay URL — offers "File automatically" |
+| `deviceClientId` | | OAuth App client id — offers "Sign in with GitHub" |
+| `labels` | | labels applied to the issue |
+| `defaultRecentConversations` | `3` | how many of the most recent conversations start ticked |
+| `maxBytes` | 24 MB | the ceiling the meter measures against |
+| `appVersion` | | your app's version, for the environment block |
+| `label` | | the button's own text |
+| `api` | | the agentfootprint functions to call — defaults to the installed ones |
+
+The headless half is on `agentfootprint-lens/core` — `defaultSelection`,
+`measureSelection`, `trimHintFor`, `buildIssueBody`, `buildNewIssueUrl`,
+`parseGithubRepo` — so a CLI or a Vue shell can build the same dialog.
+
+---
+
 ## Theming
 
 **Lens inherits theme tokens from your app via CSS variables.** Set `--fp-*`
@@ -376,6 +512,16 @@ exact `formatSlice` text the LLM tool returns. Honest absence stays honest:
 "never written — initial state / args / a closure", and reads-off runs say
 "unknowable, not absent".
 
+### `<BugReportButton>` — report a bug with the run attached, consent first
+
+A small button for a debug UI. The dialog it opens shows every selectable unit
+of evidence with its size and counts, meters the selection live against a 24 MB
+ceiling (naming the unit to untick when it is over), and offers whichever of the
+three submit modes you configured — copy + download, sign in with GitHub, or
+file through your own endpoint. Needs agentfootprint 9.9+; on anything older it
+renders a version hint instead of itself. See
+[Report a bug with this run](#report-a-bug-with-this-run).
+
 ### Headless core
 
 `agentfootprint-lens/core` is React-free: `LensRecorder`, `ChangeNotifier`,

package/dist/{chunk-CJCPL73F.js → chunk-QBSH233H.js}

@@ -2821,6 +2821,180 @@ function layoutLensGraph(output, options = {}) {
   };
 }
 
+// src/core/bugReport/selection.ts
+var DEFAULT_MAX_BYTES = 24 * 1024 * 1024;
+function formatBytes(bytes) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "0 bytes";
+  if (bytes < 1024) return `${Math.round(bytes)} bytes`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function conversationUnits(manifest) {
+  return manifest.units.filter((unit) => unit.kind === "conversation");
+}
+function fileUnits(manifest) {
+  return manifest.units.filter((unit) => unit.kind !== "conversation");
+}
+function defaultSelection(manifest, recent = 3) {
+  const conversations = conversationUnits(manifest);
+  const keep = recent <= 0 ? [] : conversations.slice(Math.max(0, conversations.length - recent));
+  return [...keep.map((unit) => unit.id), ...fileUnits(manifest).map((unit) => unit.id)];
+}
+function measureSelection(manifest, selected, limitBytes = DEFAULT_MAX_BYTES) {
+  const ticked = new Set(selected);
+  const units = manifest.units.filter((unit) => ticked.has(unit.id));
+  const bytes = units.reduce((sum, unit) => sum + (unit.bytes || 0), 0);
+  const over = bytes > limitBytes;
+  const hint = over ? trimHintFor(manifest, ticked, limitBytes) : void 0;
+  return {
+    bytes,
+    limitBytes,
+    over,
+    label: `${formatBytes(bytes)} of ${formatBytes(limitBytes)}`,
+    conversations: units.filter((unit) => unit.kind === "conversation").length,
+    ...hint !== void 0 && { hint }
+  };
+}
+function trimHintFor(manifest, selected, limitBytes = DEFAULT_MAX_BYTES) {
+  const ticked = new Set(selected);
+  const droppable = manifest.units.filter((unit) => ticked.has(unit.id) && unit.kind === "conversation").sort((left, right) => right.bytes - left.bytes);
+  let remaining = manifest.units.filter((unit) => ticked.has(unit.id)).reduce((sum, unit) => sum + (unit.bytes || 0), 0);
+  if (remaining <= limitBytes) return void 0;
+  const named = [];
+  for (const unit of droppable) {
+    if (named.length >= droppable.length - 1) break;
+    remaining -= unit.bytes || 0;
+    named.push(`${unit.id} (${formatBytes(unit.bytes || 0)})`);
+    if (remaining <= limitBytes) break;
+  }
+  if (remaining > limitBytes) {
+    return `Even with one conversation left this is over ${formatBytes(limitBytes)}. Untick a derived file, record a shorter reproduction, or file the issue and attach the zip by hand.`;
+  }
+  return `Untick ${joinWithAnd(named)} to fit.`;
+}
+function joinWithAnd(parts) {
+  if (parts.length <= 1) return parts[0] ?? "";
+  return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+
+// src/core/bugReport/issueBody.ts
+function buildIssueBody(args) {
+  const { fields, manifest, evidence } = args;
+  const selected = new Set(args.selected ?? manifest.selected ?? manifest.units.map((u) => u.id));
+  const lines = [];
+  lines.push("### Steps to reproduce", "", textOr(fields.stepsToReproduce), "");
+  lines.push("### Expected", "", textOr(fields.expected), "");
+  lines.push("### Actual", "", textOr(fields.actual), "");
+  lines.push("### Evidence in this report", "");
+  lines.push("| unit | kind | size | events | turns |");
+  lines.push("| --- | --- | --- | --- | --- |");
+  for (const unit of manifest.units) {
+    if (!selected.has(unit.id)) continue;
+    lines.push(
+      `| \`${unit.id}\` | ${unit.kind} | ${formatBytes(unit.bytes || 0)} | ${unit.eventCount ?? "\u2014"} | ${unit.turnCount ?? "\u2014"} |`
+    );
+  }
+  lines.push("");
+  const left = manifest.units.filter((unit) => !selected.has(unit.id));
+  if (left.length > 0) {
+    lines.push(
+      `The reporter left out ${left.length} unit${left.length === 1 ? "" : "s"}: ${left.map((unit) => `\`${unit.id}\``).join(", ")}. A turn that refers to something not here is referring to one of those.`,
+      ""
+    );
+  }
+  const redacted = manifest.redactedKeys ?? [];
+  if (redacted.length > 0) {
+    lines.push(
+      `**Redacted before recording** (names only \u2014 the values never left the reporter's machine): ${redacted.map((key) => `\`${key}\``).join(", ")}`,
+      ""
+    );
+  }
+  for (const warning of manifest.warnings ?? []) lines.push(`> \u26A0 ${warning}`, "");
+  for (const note of manifest.notes ?? []) lines.push(`> ${note}`, "");
+  if (evidence) {
+    lines.push(
+      evidence.delivery === "by-hand" ? `**Evidence bundle:** \`${evidence.filename}\` (${formatBytes(evidence.bytes)}) \u2014 downloaded to the reporter's machine and attached to this issue by hand. If it is not attached above, ask them for it: nothing was uploaded automatically.` : `**Evidence bundle:** \`${evidence.filename}\` (${formatBytes(evidence.bytes)}) \u2014 sent to the application's bug-report endpoint, which files it with this issue.`,
+      ""
+    );
+  }
+  lines.push("### Environment", "");
+  const env = manifest.environment ?? {};
+  for (const [label, value] of [
+    ["agentfootprint", env.agentfootprint],
+    ["footprintjs", env.footprintjs],
+    ["node", env.node],
+    ["platform", joinPlatform(env.platform, env.arch)],
+    ["app", env.appVersion ?? fields.appVersion]
+  ]) {
+    if (value) lines.push(`- ${label}: \`${value}\``);
+  }
+  lines.push("");
+  lines.push("<sub>Filed from Why Lens \u2014 the manifest above is the library's own.</sub>");
+  return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}
+`;
+}
+var textOr = (value) => value && value.trim() !== "" ? value.trim() : "_(not given)_";
+function joinPlatform(platform, arch) {
+  if (!platform && !arch) return void 0;
+  return [platform, arch].filter(Boolean).join("/");
+}
+
+// src/core/bugReport/github.ts
+function parseGithubRepo(issuesUrl) {
+  let url;
+  try {
+    url = new URL(issuesUrl);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return void 0;
+  const [owner, repo] = url.pathname.split("/").filter(Boolean);
+  if (!owner || !repo) return void 0;
+  const isDotCom = url.hostname === "github.com" || url.hostname === "www.github.com";
+  return {
+    owner,
+    repo: repo.replace(/\.git$/, ""),
+    apiBase: isDotCom ? "https://api.github.com" : `${url.origin}/api/v3`,
+    newIssueUrl: `${url.origin}/${owner}/${repo}/issues/new`
+  };
+}
+var MAX_ISSUE_URL_BYTES = 8e3;
+var TRUNCATION_NOTICE = "\n\n\u2026truncated to fit a URL \u2014 the full report is on the clipboard, paste it over this.\n";
+function buildNewIssueUrl(args) {
+  const limit = args.maxBytes ?? MAX_ISSUE_URL_BYTES;
+  const compose = (body) => {
+    const params = new URLSearchParams();
+    params.set("title", args.title);
+    params.set("body", body);
+    if (args.labels && args.labels.length > 0) params.set("labels", args.labels.join(","));
+    return `${args.target.newIssueUrl}?${params.toString()}`;
+  };
+  const full = compose(args.body);
+  if (full.length <= limit) return { url: full, truncated: false };
+  let keep = args.body.length;
+  let url = full;
+  while (keep > 0 && url.length > limit) {
+    keep = Math.floor(keep * (limit / url.length) * 0.95);
+    url = compose(cutAtLine(args.body, keep) + TRUNCATION_NOTICE);
+  }
+  return { url, truncated: true };
+}
+function cutAtLine(body, keep) {
+  const head = body.slice(0, Math.max(0, keep));
+  const lastBreak = head.lastIndexOf("\n");
+  return lastBreak > keep * 0.5 ? head.slice(0, lastBreak) : head;
+}
+function encodeBase64(bytes) {
+  const maybeBuffer = globalThis.Buffer;
+  if (typeof maybeBuffer?.from === "function") return maybeBuffer.from(bytes).toString("base64");
+  let binary = "";
+  const chunk = 32768;
+  for (let i = 0; i < bytes.length; i += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+  }
+  return btoa(binary);
+}
+
 export {
   ChangeNotifier,
   lensSnapshotRecorder,
@@ -2866,6 +3040,19 @@ export {
   explainableShellPropsFromRunner,
   toReactFlow,
   defaultSize,
-  layoutLensGraph
+  layoutLensGraph,
+  DEFAULT_MAX_BYTES,
+  formatBytes,
+  conversationUnits,
+  fileUnits,
+  defaultSelection,
+  measureSelection,
+  trimHintFor,
+  buildIssueBody,
+  parseGithubRepo,
+  MAX_ISSUE_URL_BYTES,
+  TRUNCATION_NOTICE,
+  buildNewIssueUrl,
+  encodeBase64
 };
-//# sourceMappingURL=chunk-CJCPL73F.js.map
+//# sourceMappingURL=chunk-QBSH233H.js.map