Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(cloud): report the tokens the map saved on each lookup
Shrish Dwivedi4a730b6fb882
diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex 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 quietconst 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.tsindex 9623bbf6..02d94d14 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -64,6 +64,7 @@ import { beginReviewRead, finishReviewRead, type ReviewFinding } from "./notes/pimport { 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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"]);+});