Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(cloud): report the tokens the map saved on each lookup

Shrish Dwivedi4a730b6fb882
diff --git a/src/ask/ask.ts b/src/ask/ask.ts
index 655fe69f..c11f377c 100644
--- a/src/ask/ask.ts
+++ b/src/ask/ask.ts
@@ -1469,8 +1469,9 @@ function toTokens(chars: number): number {
return Math.round(chars / 4);
}
-/** Render an {@link AskResult} as a compact markdown context pack. */
-export function formatAsk(r: AskResult): string {
+/** The rendered pack, before the savings header: `body` when there are hits to
+ * show, or the finished `text` when there are none (no savings line then). */
+function renderAsk(r: AskResult): { body: string } | { text: string } {
const head = `${cmd("graft ask")} — "${r.query}" (${r.mode})`;
// The note prints as its own prominent line(s) right under the header —
// above every hit — so a loud structural-fallthrough note (or the
@@ -1497,8 +1498,8 @@ export function formatAsk(r: AskResult): string {
if (learned) teamNotes.push(learned, "");
if (r.notesHint) teamNotes.push(r.notesHint, "");
if (r.hits.length === 0) {
- if (r.notes?.length) return `${head}\n\n${teamNotes.join("\n").trimEnd()}\n\n${noteBlock || "no code matches."}${escalationNudge(r)}\n`;
- return `${head}\n\n${noteBlock || "no matches."}${escalationNudge(r)}\n`;
+ if (r.notes?.length) return { text: `${head}\n\n${teamNotes.join("\n").trimEnd()}\n\n${noteBlock || "no code matches."}${escalationNudge(r)}\n` };
+ return { text: `${head}\n\n${noteBlock || "no matches."}${escalationNudge(r)}\n` };
}
const lines = noteBlock ? [head, "", noteBlock, "", ...teamNotes] : [head, "", ...teamNotes];
if (r.mode === "structural") {
@@ -1521,9 +1522,28 @@ export function formatAsk(r: AskResult): string {
});
lines.push(...scopeFooterLines(r));
}
- const body = lines.join("\n").trimEnd();
- const savings = askSavingsLine(r, body);
- return (savings ? `${savings}\n\n${body}` : body) + escalationNudge(r) + "\n";
+ return { body: lines.join("\n").trimEnd() };
+}
+
+/** Render an {@link AskResult} as a compact markdown context pack. */
+export function formatAsk(r: AskResult): string {
+ const out = renderAsk(r);
+ if ("text" in out) return out.text;
+ const savings = askSavingsLine(r, out.body);
+ return (savings ? `${savings}\n\n${out.body}` : out.body) + escalationNudge(r) + "\n";
+}
+
+/** Tokens this lookup's pack saved against reading the files it covers whole:
+ * the number `formatAsk` prints as "tokens saved ≈ N", or 0 when it prints none. */
+export function askSavedTokens(r: AskResult): number {
+ const out = renderAsk(r);
+ return "body" in out ? savedTokens(r, out.body) : 0;
+}
+
+/** Baseline tokens minus pack tokens, or 0 when there is no estimate or no saving to claim. */
+function savedTokens(r: AskResult, body: string): number {
+ if (!r.saved || r.saved.baselineChars <= 0) return 0;
+ return Math.max(0, toTokens(r.saved.baselineChars) - toTokens(body.length));
}
/** When a lexical `ask` returns thin/no results, the productive next move is a
@@ -1546,11 +1566,10 @@ function escalationNudge(r: AskResult): string {
* Header, not footer, for the reason documented on `withSavings`: a trailing
* line dies to `head -N` and to host output truncation. */
function askSavingsLine(r: AskResult, body: string): string {
- if (!r.saved || r.saved.baselineChars <= 0) return "";
+ const saved = savedTokens(r, body);
+ if (saved <= 0 || !r.saved) return ""; // no saving to claim (tiny files); stay quiet
const pack = toTokens(body.length);
const base = toTokens(r.saved.baselineChars);
- if (base <= pack) return ""; // no saving to claim (tiny files); stay quiet
- const saved = base - pack;
const pct = Math.round((saved / base) * 100);
return (
`${tag()} tokens saved ≈ ${saved.toLocaleString()} (${pct}%) — this pack ≈ ` +
diff --git a/src/cli.ts b/src/cli.ts
index 9623bbf6..02d94d14 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -64,6 +64,7 @@ import { beginReviewRead, finishReviewRead, type ReviewFinding } from "./notes/p
import { finishPair, PairRun, validPairCode } from "./cloud/pair.js";
import { currentBranch, noteAuthor, teammatesOn } from "./notes/git-facts.js";
import { confirm, fold, getSkill, learn, listSkills, publish, skillForAgent, skillName, skillStatus, type LearnResult } from "./skills/skills.js";
+import { recordLookup } from "./cloud/lookup-activity.js";
import { clearPending, cloudLines, loginLink, sessionKey, waitForConnect } from "./cloud/nudge.js";
import { addRepo, clearCloud, cloudEnabled, fetchMe, fetchTeam, isError, readCloud, trailUrl, writeCloud, type Cloud } from "./cloud/workspace.js";
import {
@@ -741,38 +742,25 @@ grouped(program.command("build"), GROUP.setup)
}
});
-/** The file part of a hit's `file:Lx-Ly` pointer. */
-function pointerFile(pointer: string): string {
- return pointer.replace(/:L\d+(-L?\d+)?$/, "");
-}
-
/**
* After `ask`, under trail: which shown learnings are a teammate's, and the
- * shown learnings recorded as a use, which is what the team page counts as
- * reuse. Then the background upkeep that keeps branches and the workspace
- * current. Spawns no git itself. Teammates' branches come up after an edit
+ * lookup recorded (the learnings shown are a use, which is what the team page
+ * counts as reuse; the tokens saved ride along). Then the background upkeep
+ * that keeps branches and the workspace current. Spawns no git itself. Teammates' branches come up after an edit
* instead, once there's a function to compare (notes/edit-overlap.ts).
*/
function afterAsk(r: AskResult, repo: string): void {
+ // Every lookup is reported, not only ones that showed a learning: the tokens
+ // the map saved are what the team page's running total counts. A no-op unless
+ // this machine is connected and the repo is the workspace's.
+ recordLookup(r, repo);
if (!r.notesChecked) return;
rememberRepo(repo);
maybeRefreshBranches(repo);
const me = noteAuthor(repo);
- const files = [...new Set(r.hits.map((h) => pointerFile(h.pointer)))];
const shown = r.notes ?? [];
if (shown.length) {
for (const h of shown) h.note.teammate = !!h.note.author && !!me && h.note.author !== me;
- recordActivity({
- repo: repoPlace(repo).key,
- kind: "search",
- asker: me,
- session: sessionKey(repo) ?? `${me}-${new Date().toISOString().slice(0, 10)}`,
- query: r.query,
- files,
- shown_paths: shown.map((h) => noteName(h.note)),
- shown_authors: shown.map((h) => h.note.author),
- at: new Date().toISOString(),
- });
const saved = shown.reduce((sum, h) => sum + savedByNote(h.note), 0);
track("learning_reused", { teammate: String(shown.some((h) => h.note.teammate)), saved_tokens_bucket: savedTokensBucket(saved) }, { repo });
}
diff --git a/src/cloud/lookup-activity.ts b/src/cloud/lookup-activity.ts
new file mode 100644
index 00000000..d0813acd
--- /dev/null
+++ b/src/cloud/lookup-activity.ts
@@ -0,0 +1,48 @@
+/**
+ * What a code lookup tells the workspace: the learnings it showed (a use) and
+ * the tokens the map saved against reading the files whole. Shared by the CLI's
+ * `ask` and the MCP `graft_find_code`, so both report the same event.
+ */
+import { askSavedTokens, type AskResult } from "../ask/ask.js";
+import { repoPlace } from "../notes/home.js";
+import { noteAuthor } from "../notes/git-facts.js";
+import { noteName } from "../notes/notes.js";
+import { sessionKey } from "./nudge.js";
+import { readCloud, type Cloud } from "./workspace.js";
+import { recordActivity } from "./workspace-sync.js";
+
+/** The file part of a hit's `file:Lx-Ly` pointer. */
+function pointerFile(pointer: string): string {
+ return pointer.replace(/:L\d+(-L?\d+)?$/, "");
+}
+
+/**
+ * Queue one search event for `r`, when it showed a learning or saved tokens.
+ * Uses are counted from the learnings shown only; `saved_tokens` rides along.
+ * Never throws.
+ */
+export function recordLookup(r: AskResult, repo: string, cloud: Cloud | null = readCloud()): void {
+ try {
+ const shown = r.notes ?? [];
+ const saved = askSavedTokens(r);
+ if (!shown.length && saved <= 0) return;
+ const me = noteAuthor(repo);
+ recordActivity(
+ {
+ repo: repoPlace(repo).key,
+ kind: "search",
+ asker: me,
+ session: sessionKey(repo) ?? `${me}-${new Date().toISOString().slice(0, 10)}`,
+ query: r.query,
+ files: [...new Set(r.hits.map((h) => pointerFile(h.pointer)))],
+ shown_paths: shown.map((h) => noteName(h.note)),
+ shown_authors: shown.map((h) => h.note.author),
+ ...(saved > 0 ? { saved_tokens: saved } : {}),
+ at: new Date().toISOString(),
+ },
+ cloud,
+ );
+ } catch {
+ /* a lost event undercounts by one */
+ }
+}
diff --git a/src/cloud/workspace.ts b/src/cloud/workspace.ts
index c0fbac58..8a79ce98 100644
--- a/src/cloud/workspace.ts
+++ b/src/cloud/workspace.ts
@@ -259,6 +259,8 @@ export interface ActivityEvent {
/** File names of the learnings it showed. */
shown_paths: string[];
shown_authors: string[];
+ /** Tokens the map saved on this lookup (what `ask` prints as "tokens saved"); absent when unknown. */
+ saved_tokens?: number;
at: string;
}
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 166e5ba3..0be5b3ab 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -26,6 +26,7 @@ import {
readWorkspace,
} from '../graph/workspace.js';
import type { NodeV1 } from '../graph/types.js';
+import { recordLookup } from '../cloud/lookup-activity.js';
import { canonicalToolName } from './tool-names.js';
import { cmd } from '../brand.js';
@@ -260,6 +261,8 @@ async function callSingleTool(
const engine = new Graft({ contextDir: dirOverride });
const inArg = typeof args.in === 'string' && args.in ? args.in : undefined;
const r = engine.ask(root, query, { limit, source: true, full: args.full === true, in: inArg });
+ // Same event the CLI's `ask` reports: the learnings shown and the tokens saved.
+ recordLookup(r, root);
return { text: formatAsk(r), isError: false };
}
case 'graft_file_api': {
diff --git a/test/activity-saved-tokens.test.ts b/test/activity-saved-tokens.test.ts
new file mode 100644
index 00000000..fcb4345e
--- /dev/null
+++ b/test/activity-saved-tokens.test.ts
@@ -0,0 +1,105 @@
+/**
+ * Every lookup that saved tokens is reported to the workspace, even when no
+ * learning was shown: the home's running "tokens saved" counts real lookups.
+ * Uses are still counted from the learnings shown, never from the savings.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BRAND_ENV } from "../src/brand.js";
+
+process.env.DO_NOT_TRACK = "1";
+process.env[BRAND_ENV] = "trail";
+process.env.TRAIL_HOME = mkdtempSync(join(tmpdir(), "saved-tokens-home-"));
+
+const { formatAsk, askSavedTokens } = await import("../src/ask/ask.js");
+type AskResult = import("../src/ask/ask.js").AskResult;
+const { recordLookup } = await import("../src/cloud/lookup-activity.js");
+const { repoPlace } = await import("../src/notes/home.js");
+type Cloud = import("../src/cloud/workspace.js").Cloud;
+
+const outbox = () => join(process.env.TRAIL_HOME!, "outbox.jsonl");
+const queued = (): any[] =>
+ existsSync(outbox()) ? readFileSync(outbox(), "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l)) : [];
+
+function repoAndCloud(): { repo: string; cloud: Cloud } {
+ const repo = mkdtempSync(join(tmpdir(), "saved-tokens-repo-"));
+ const cloud: Cloud = {
+ url: "http://trail.test",
+ token: "trl_x",
+ user: { name: "Anirudh", email: "[email protected]" },
+ workspace: { id: "w", name: "Acme", slug: "acme", url: "http://trail.test/w/acme", invite_url: "http://trail.test/join/x" },
+ repos: [repoPlace(repo).key],
+ linkedAt: 0,
+ };
+ return { repo, cloud };
+}
+
+/** A result whose pack saves exactly `tokens` tokens against reading the file whole. */
+function resultSaving(tokens: number): AskResult {
+ const r: AskResult = {
+ query: "retry count",
+ mode: "structural",
+ hits: [{ id: "n1", title: "Do", kind: "function", pointer: "client.go:L1-L9", score: 1 } as AskResult["hits"][number]],
+ };
+ const pack = Math.round((formatAsk(r).length - 1) / 4);
+ r.saved = { files: 1, baselineChars: 4 * (tokens + pack) };
+ return r;
+}
+
+function reset(): void {
+ rmSync(outbox(), { force: true });
+ mkdirSync(process.env.TRAIL_HOME!, { recursive: true });
+}
+
+test("a lookup that saved tokens is queued with them, though no learning was shown", () => {
+ reset();
+ const { repo, cloud } = repoAndCloud();
+ const r = resultSaving(15392);
+ assert.equal(askSavedTokens(r), 15392);
+ assert.match(formatAsk(r), /tokens saved ≈ 15,392 /, "the number the ask output prints");
+ recordLookup(r, repo, cloud);
+ const events = queued();
+ assert.equal(events.length, 1);
+ assert.equal(events[0].kind, "search");
+ assert.equal(events[0].saved_tokens, 15392);
+ assert.deepEqual(events[0].shown_paths, []);
+ assert.equal(events[0].query, "retry count");
+});
+
+test("no estimate and no learning shown: nothing is queued", () => {
+ reset();
+ const { repo, cloud } = repoAndCloud();
+ const r = resultSaving(15392);
+ delete r.saved;
+ assert.equal(askSavedTokens(r), 0);
+ recordLookup(r, repo, cloud);
+ assert.equal(queued().length, 0);
+});
+
+test("a learning shown without an estimate is still a use, with no saved_tokens", () => {
+ reset();
+ const { repo, cloud } = repoAndCloud();
+ const r = resultSaving(1);
+ delete r.saved;
+ r.notes = [{ note: { path: "/x/.trail/learnings/2026-10-09-jitter-kumar.md", title: "Jitter", author: "Kumar", date: "2026-10-09", touches: [], body: "b" }, score: 1, shared: [] }];
+ recordLookup(r, repo, cloud);
+ const events = queued();
+ assert.equal(events.length, 1);
+ assert.deepEqual(events[0].shown_paths, ["2026-10-09-jitter-kumar.md"]);
+ assert.equal("saved_tokens" in events[0], false);
+});
+
+test("an estimate with a learning shown carries both", () => {
+ reset();
+ const { repo, cloud } = repoAndCloud();
+ const r = resultSaving(900);
+ r.notes = [{ note: { path: "/x/.trail/learnings/2026-10-09-jitter-kumar.md", title: "Jitter", author: "Kumar", date: "2026-10-09", touches: [], body: "b" }, score: 1, shared: [] }];
+ recordLookup(r, repo, cloud);
+ const [e] = queued();
+ assert.equal(e.saved_tokens, askSavedTokens(r), "the learning is in the pack, so it counts against the saving");
+ assert.ok(e.saved_tokens > 0);
+ assert.deepEqual(e.shown_paths, ["2026-10-09-jitter-kumar.md"]);
+});