trim comments

Author: edwinyjlim

src/lib/agent/__tests__/run-tags.test.ts

@@ -22,9 +22,8 @@ describe('buildRunTags', () => {
   });
 
   it('marks every run as agent work rather than leaving call_type unset', () => {
-    // Scan triage overrides this to `yara-triage`. Both sides are stamped so a
-    // missing `call_type` means "an old build sent none", not "agent work" —
-    // the two would otherwise be indistinguishable in cost breakdowns.
+    // Triage and detection override this; stamping both sides means a missing
+    // value is an old build, not agent work.
     expect(
       buildRunTags({
         programId: 'posthog-integration',

src/lib/agent/__tests__/triage-provider.test.ts

@@ -91,9 +91,7 @@ describe('createTriageLLMProvider', () => {
   });
 
   it('attributes its spend to the program that triggered the scan', async () => {
-    // Triage fires per tool call. Before it carried run tags, every scan's
-    // gateway spend landed in the unattributed bucket; `call_type` keeps it
-    // separable from the agent work inside the same program.
+    // Triage fires per tool call; untagged it billed to no program at all.
     complete.mockResolvedValue(reply(''));
     const provider = createTriageLLMProvider(
       {

src/lib/agent/agent-interface.ts

@@ -346,9 +346,7 @@ export function buildRunTags(args: {
     integration: args.integration,
     run_id: args.runId,
     build: args.build,
-    // Every caller is agent work; the triage provider spreads these tags and
-    // overrides this one. Sent explicitly so a missing value never has to be
-    // read as "agent" — old builds send none at all.
+    // Triage and detection spread these tags and override this one.
     call_type: CallType.agent,
     ...(args.skillId ? { skill_id: args.skillId } : {}),
   };
@@ -530,12 +528,9 @@ export async function initializeAgent(
     process.env.CLAUDE_CODE_OAUTH_TOKEN = config.posthogApiKey;
 
     // Same values the env vars above carry, handed over explicitly so triage
-    // never has to read them back out of the environment.
-    //
-    // The run tags ride along too: triage fires per tool call, so leaving them
-    // off put every scan's gateway spend in the unattributed bucket. Tagged
-    // here it folds into the program that triggered it, and `call_type` keeps
-    // it separable — security scanning is its own cost line, not agent work.
+    // never has to read them back out of the environment. The run tags ride
+    // along so scan spend bills to this program, with `call_type` keeping it
+    // separable from the agent's own calls.
     const triageProvider = createTriageLLMProvider(
       {
         baseURL: gatewayUrl,

src/lib/agent/mcp-prompt-streaming.ts

@@ -174,16 +174,9 @@ function buildTerminalFitPrompt(): string {
 }
 
 /**
- * Gateway trace tags for a tutorial prompt run.
- *
- * The gateway attributes each `$ai_generation` it emits from the
- * `X-POSTHOG-PROPERTY-*` headers on the request, so a run with no tags lands
- * in the unattributed bucket — which is where every tutorial generation went
- * before this existed. Exported so that contract is testable without booting
- * the SDK.
- *
- * Returns `{}` when the caller supplies no program, keeping the tagless
- * behavior explicit rather than silently emitting a half-populated bag.
+ * Gateway trace tags for a tutorial prompt run — without them the gateway has
+ * nothing to attribute its `$ai_generation` events to. Returns `{}` when no
+ * program is supplied. Exported so the contract is testable without the SDK.
  */
 export function buildTutorialRunTags(args: {
   programId?: string;
@@ -192,9 +185,8 @@ export function buildTutorialRunTags(args: {
   if (!args.programId) return {};
   return buildRunTags({
     programId: args.programId,
-    // The tutorial runs against a project, not a codebase, so there's usually
-    // no detected framework — fall back to the program so the axis is never
-    // an empty string in the gateway's breakdowns.
+    // The tutorial usually has no detected framework; fall back to the
+    // program so the axis is never an empty string.
     integration: args.integration ?? args.programId,
     runId: analytics.runId,
     build: analytics.build,
@@ -209,10 +201,8 @@ export async function* runMcpPromptViaSdk(args: {
    *  context so the follow-up prompt can reference what the agent
    *  already showed. */
   resumeSessionId?: string;
-  /** Program this run's gateway spend attributes to. Resolved by the caller
-   *  (`store.analyticsProgramId`) so both tutorial entry points report as
-   *  one program. Omitting it makes the spend unattributable — see the
-   *  `ANTHROPIC_CUSTOM_HEADERS` note below. */
+  /** Program this run's gateway spend attributes to; omitting it leaves the
+   *  spend unattributed. */
   programId?: string;
   /** Integration label for the trace tags; the tutorial usually has none. */
   integration?: string;
@@ -378,13 +368,9 @@ export async function* runMcpPromptViaSdk(args: {
           // default; without this the agent may try to call tools
           // before posthog-wizard is connected on turn 1.
           MCP_CONNECTION_NONBLOCKING: '0',
-          // Same Bedrock-fallback + telemetry-friendly headers as the main
-          // runner, plus this run's trace tags. The gateway reads
-          // `X-POSTHOG-PROPERTY-*` off the request to attribute each
-          // `$ai_generation` it emits, so sending none put every tutorial
-          // generation in the unattributed bucket — `posthog.capture` events
-          // carry a program id but nothing joins them to gateway spend.
-          // Flags stay empty: the tutorial doesn't fork on any.
+          // Bedrock fallback plus this run's trace tags — the gateway reads
+          // these to attribute its `$ai_generation` events. Flags stay empty:
+          // the tutorial doesn't fork on any.
           ANTHROPIC_CUSTOM_HEADERS: buildAgentEnv(wizardMetadata ?? {}, {}),
         },
       },

src/lib/agent/triage-provider.ts

@@ -24,12 +24,8 @@ export interface TriageGatewayAuth {
   baseURL: string;
   /** The run's OAuth access token. */
   authToken: string;
-  /**
-   * The run's gateway trace tags. Pass the run's own `wizardMetadata` with
-   * `call_type` overridden to `CallType.yaraTriage` — that keeps scan spend
-   * attributed to the program that triggered it while staying separable from
-   * the agent work inside it.
-   */
+  /** The run's trace tags, with `call_type` overridden to
+   *  `CallType.yaraTriage` so scan spend is separable from agent work. */
   wizardMetadata?: Record<string, string>;
   wizardFlags?: Record<string, string>;
 }

src/lib/constants.ts

@@ -59,24 +59,15 @@ export enum Sequence {
 
 /**
  * What kind of call produced a gateway generation — the `call_type` trace tag.
- *
- * Splits a program's LLM spend by workload, so security scanning is separable
- * from the work the user asked for. Both members are sent explicitly rather
- * than treating `agent` as the unset default: old wizard builds in the field
- * send no `call_type` at all, so an absent value can't be read as "agent"
- * without conflating the two.
- *
- * Lives here rather than beside the triage provider because `buildRunTags`
- * (agent-interface) sets the default and the triage provider overrides it —
- * agent-interface already imports the provider, so a shared home avoids a
- * module cycle.
+ * Splits a program's LLM spend by workload. Every member is sent explicitly so
+ * an absent value means "old build", not "agent".
  */
 export enum CallType {
   /** The agent doing the work the user asked for. */
   agent = 'agent',
   /** Warlock's classifier deciding whether a YARA match is a true positive. */
   yaraTriage = 'yara-triage',
-  /** The cheap repo scan that classifies which projects a program should act on. */
+  /** The cheap repo scan that classifies which projects a program acts on. */
   detection = 'detection',
 }
 

src/lib/detection/__tests__/project-scope.test.ts

@@ -126,9 +126,7 @@ describe('scopeInstallDirToProject', () => {
   });
 
   it('bills the scan to the program that asked for it', async () => {
-    // The detector drives a real (if cheap) agent through the gateway. It runs
-    // before bootstrap, so nothing upstream supplies run tags — an unattributed
-    // scan is exactly how this spend went missing before.
+    // Runs before bootstrap, so nothing upstream supplies run tags.
     flagsSpy.mockResolvedValue(FLAG_ON);
     scan.mockResolvedValue({ repoType: 'single', projects: [web] });
 

src/lib/detection/agentic.ts

@@ -110,14 +110,9 @@ export type AgenticDetectOptions = {
    * through ordering (e.g. a bundler target before a generic framework target).
    */
   targets: readonly DetectTarget[];
-  /**
-   * The program this scan runs on behalf of, for gateway cost attribution.
-   *
-   * Required, not optional: this scan drives a real (if cheap) agent through
-   * the LLM gateway, and a caller that forgets to say who it's for sends spend
-   * to the unattributed bucket with no way to trace it back. `call_type`
-   * separates it from the program's own agent work.
-   */
+  /** The program this scan bills to. Required, not optional: the scan drives a
+   *  real agent through the gateway, and a caller that forgets leaves that
+   *  spend unattributed. */
   programId: string;
   /** One short clause describing what the scan is for (frames the prompt). */
   purpose?: string;
@@ -349,10 +344,8 @@ export async function detectProjectsWithAgent(
   const cwd = session.installDir;
   const runOptions = sessionToWizardOptions(session);
 
-  // Gateway trace tags. This scan runs before `bootstrapProgram` exists, so
-  // they're built here from the caller's program plus the run's analytics
-  // identity rather than inherited from `boot.wizardMetadata`. Without them
-  // the scan — and the YARA triage it wires up — bill to no program at all.
+  // Built here rather than inherited: this scan runs before
+  // `bootstrapProgram`, so there's no `boot.wizardMetadata` yet.
   const wizardMetadata = {
     ...buildRunTags({
       programId,

src/lib/detection/project-scope.ts

@@ -90,9 +90,8 @@ export async function scopeInstallDirToProject(
   try {
     report = await Promise.race([
       detectIntegrationProjects(session, {
-        // Same literal the `authenticate` call above uses — importing the
-        // program registry here would cycle back through the programs that
-        // import this module.
+        // Literal, like the `authenticate` call above: importing the program
+        // registry here would cycle.
         programId: 'posthog-integration',
         recommend: true,
         onEvent: (line) => logToFile('[agentic detect]', line),

src/lib/programs/mcp/index.ts

@@ -45,12 +45,9 @@ export const mcpAddConfig: ProgramConfig = {
       // talk to from the tutorial.
       show: (s) => s.mcpOutcome === McpOutcome.Installed,
       isComplete: (s) => s.mcpSuggestedPromptsDismissed,
-      // This step *is* the tutorial, so its events belong to the tutorial's
-      // funnel rather than to `mcp-add` — otherwise the same screen reports
-      // under two program ids depending on how the user arrived, and neither
-      // one measures the tutorial. String literal (not `Program.McpTutorial`)
-      // to avoid a runtime cycle with `program-registry.ts`; the `ProgramId`
-      // type on the field still catches a rename at compile time.
+      // This step *is* the tutorial, so it reports there rather than to
+      // `mcp-add`. Literal avoids a runtime cycle with the program registry;
+      // the `ProgramId` type still catches a rename.
       reportsAsProgramId: 'mcp-tutorial',
     },
   ],