@frontera-sdk/cli 1.53.21 → 1.53.22

package/src/telemetry/agent-events.ts

@@ -0,0 +1,79 @@
+import type { AttributeValue } from './events'
+
+/**
+ * The coding agents' own events, and which of them leave the laptop.
+ *
+ * Forge points the agents it starts (Claude Code, Codex) at its own loopback
+ * relay, never at the collector. The relay keeps what these rules keep and
+ * writes it to the outbox, so the sender posts it with Forge's events. The
+ * Kata collector applies the same rules again
+ * (deployments/kata/telemetry/collector.yaml); a test builds the collector's
+ * statements from this file and fails when the two disagree.
+ */
+
+/** The `service.name` each agent's exporter sends (measured): Claude Code, and the `codex app-server` Forge starts. */
+export const AGENT_SERVICES = ['claude-code', 'codex-app-server'] as const
+export type AgentService = (typeof AGENT_SERVICES)[number]
+
+export const AGENT_EVENTS: Readonly<Record<AgentService, RegExp>> = {
+  'claude-code': /^(user_prompt|api_request|api_error|api_refusal|api_retries_exhausted|tool_result|tool_decision|compaction|subagent_completed|internal_error)$/,
+  'codex-app-server': /^codex\.(conversation_starts|user_prompt|api_request|sse_event|tool_decision|tool_result|turn_cost|turn_ttft)$/,
+}
+
+/**
+ * The record attributes kept from an agent: counts, timings, models and
+ * outcomes. Never prompts, responses, tool input or output, error text, or
+ * the names of people, accounts, hosts, files or MCP servers.
+ */
+export const AGENT_ATTRIBUTES =
+  /^(event\.(name|kind|sequence)|frontera\.session\.id|session\.id|conversation\.id|prompt\.id|turn\.(id|interrupted)|prompt_length|model|query_source|speed|effort|reasoning_effort|model_reasoning_effort|cost_usd|usage\.estimated_usd|duration_ms|ttft_ms|attempt|status_code|success|error_type|decision|decision_type|decision_source|source|tool_name|tool_origin|tool_input_size_bytes|tool_result_size_bytes|arguments_length|output_length|input_tokens|output_tokens|cache_read_tokens|cache_creation_tokens|input_token_count|output_token_count|cached_token_count|cache_write_token_count|reasoning_token_count|tool_token_count|approval_policy|sandbox_policy)$/
+
+export const MAX_AGENT_ATTRIBUTES = 64
+
+/** An MCP tool's name carries its server's, which the person chose: kept only for Frontera's own. */
+export const MCP_TOOL = /^mcp__/
+export const FRONTERA_MCP_TOOL = /^mcp__frontera__/
+/** Codex names an MCP tool by its bare name and its server in `mcp_server` (measured, 0.151): the same rule by the server. */
+export const FRONTERA_MCP_SERVER = 'frontera'
+
+const thirdPartyMcp = ({ tool_name: tool, mcp_server: server }: Readonly<Record<string, unknown>>) =>
+  typeof tool === 'string' && ((MCP_TOOL.test(tool) && !FRONTERA_MCP_TOOL.test(tool)) || (typeof server === 'string' && server !== '' && server !== FRONTERA_MCP_SERVER))
+
+/** Codex's environment for a Forge session (`-c otel.environment="forge:<id>"`), which it sends as the resource attribute `env`. */
+export const FORGE_ENVIRONMENT = /^forge:./
+
+export const isAgentService = (service: unknown): service is AgentService => (AGENT_SERVICES as readonly unknown[]).includes(service)
+
+/**
+ * The Forge session a record belongs to: `frontera.session.id` from
+ * `OTEL_RESOURCE_ATTRIBUTES`, or for Codex its `forge:` environment. Null for
+ * a record from no Forge session (a copied environment, a program an agent
+ * started), which is never kept.
+ */
+export function agentSession(resource: Readonly<Record<string, AttributeValue>>): string | null {
+  const session = resource['frontera.session.id']
+  if (typeof session === 'string' && session) return session
+  const env = resource.env
+  if (resource['service.name'] === 'codex-app-server' && typeof env === 'string' && FORGE_ENVIRONMENT.test(env)) return env.replace(/^forge:/, '')
+  return null
+}
+
+/**
+ * An agent record's attributes as they may leave, or null when the event is
+ * not one that leaves: only the listed keys with plain values, an MCP tool
+ * named `mcp` unless it is Frontera's, at most 64 attributes.
+ */
+export function agentAttributes(service: AgentService, name: string, attributes: Readonly<Record<string, unknown>>): Record<string, AttributeValue> | null {
+  if (!AGENT_EVENTS[service].test(name)) return null
+  // Codex sends one sse_event per streamed event; only the last of a response carries the token counts.
+  if (name === 'codex.sse_event' && attributes['event.kind'] !== 'response.completed') return null
+  const masked = thirdPartyMcp(attributes)
+  const kept: Record<string, AttributeValue> = {}
+  for (const [key, value] of Object.entries(attributes)) {
+    if (Object.keys(kept).length >= MAX_AGENT_ATTRIBUTES) break
+    if (!AGENT_ATTRIBUTES.test(key) || !['string', 'number', 'boolean'].includes(typeof value)) continue
+    if (typeof value === 'number' && !Number.isFinite(value)) continue
+    kept[key] = key === 'tool_name' && masked ? 'mcp' : (value as AttributeValue)
+  }
+  return kept
+}

package/src/telemetry/apply-events.ts

@@ -0,0 +1,142 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import { applyFailureReason } from '../local/local-apply-error'
+import type { SyncTarget } from '../local/local-dev-sync'
+import type { LocalProject } from '../local/local-project'
+import { cliTelemetry } from './cli-telemetry'
+import type { ApplyOutcome, ApplyTrigger, Severity } from './events'
+import type { Recorder } from './recorder'
+import { errorCode, errorFields, outputErrorCode } from './redact'
+
+/** An item failing since `since` (unix ms), after `failures` failed applies. */
+export interface Streak {
+  failures: number
+  since: number
+}
+
+/**
+ * One apply's place in its item's error round trip. A failure starts or
+ * lengthens the streak; the success after it ends the streak and says how many
+ * failed applies and how long it took to go green. An apply that never reached
+ * the item's files (the runtime was down, the watchdog stopped it) leaves the
+ * streak as it is.
+ */
+export function stepStreak(streak: Streak | undefined, outcome: ApplyOutcome, now: number): { next: Streak | undefined; attempt: number; recovered?: { attempts: number; ms: number } } {
+  if (outcome === 'failed') {
+    const next = { failures: (streak?.failures ?? 0) + 1, since: streak?.since ?? now }
+    return { next, attempt: next.failures }
+  }
+  const attempt = (streak?.failures ?? 0) + 1
+  if (outcome !== 'applied') return { next: streak, attempt }
+  return { next: undefined, attempt, ...(streak ? { recovered: { attempts: streak.failures, ms: Math.max(0, now - streak.since) } } : {}) }
+}
+
+/** Kept in the project's local state, so `local dev --once` runs, each its own process, add up to one round trip. */
+export const STREAKS_FILE = 'telemetry-streaks.json'
+
+/**
+ * A streak older than this is forgotten: an item that failed on Friday and
+ * was fixed on Monday says nothing about how long a fix takes, so its success
+ * carries no round trip, and its next failure starts a new streak.
+ */
+export const STREAK_MAX_MS = 8 * 60 * 60_000
+
+function readStreaks(path: string, now: number): Record<string, Streak> {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Record<string, Streak>
+    if (!parsed || typeof parsed !== 'object') return {}
+    return Object.fromEntries(Object.entries(parsed).filter(([, s]) => now - s.since <= STREAK_MAX_MS))
+  } catch {
+    return {}
+  }
+}
+
+/** The strings in a target that are names (its slug, its file, its key): replaced in an error template wherever they appear. */
+export function targetNames(target: SyncTarget): string[] {
+  const values = Object.entries(target).flatMap(([k, v]) => (k !== 'kind' && typeof v === 'string' ? [v] : []))
+  return [...new Set([...values, ...values.map((v) => v.split(/[:/\\]/).pop()!)])].filter((v) => v !== target.kind)
+}
+
+const SEVERITY: Record<ApplyOutcome, Severity> = { applied: 'INFO', failed: 'ERROR', runtime_down: 'WARN', stopped: 'WARN' }
+
+/**
+ * `frontera.cli.apply` and `frontera.cli.apply_round` for one `local dev`.
+ * Item names never leave: only the item's kind and its salted hash.
+ */
+export function applyEvents(project: LocalProject, opts: { recorder?: Recorder; now?: () => number } = {}) {
+  const telemetry = opts.recorder ?? cliTelemetry()
+  const now = opts.now ?? Date.now
+  const on = telemetry.mode.mode !== 'off'
+  const projectHash = on ? telemetry.hash(project.id) : ''
+  const streaksPath = join(project.stateDir, STREAKS_FILE)
+  // Log mode writes nothing into the project: its streaks live as long as this process.
+  const kept = telemetry.mode.mode === 'send'
+  let memory: Record<string, Streak> = {}
+  const read = () => (kept ? readStreaks(streaksPath, now()) : memory)
+  const write = (streaks: Record<string, Streak>) => {
+    if (!kept) memory = streaks
+    // ponytail: read-modify-write without a lock; a watcher and a `--once` stepping the same file at once can drop one step.
+    else writeFileAtomic(streaksPath, `${JSON.stringify(streaks)}\n`)
+  }
+
+  const step = (key: string, outcome: ApplyOutcome) => {
+    const streaks = read()
+    const stepped = stepStreak(streaks[key], outcome, now())
+    if (stepped.next !== streaks[key]) {
+      if (stepped.next) streaks[key] = stepped.next
+      else delete streaks[key]
+      write(streaks)
+    }
+    return stepped
+  }
+
+  return {
+    /** `local dev` starts with these items: the streaks of any other (deleted, renamed), and expired ones, are forgotten. */
+    keep(keys: ReadonlySet<string>): void {
+      if (!on || (kept && !existsSync(streaksPath))) return
+      try {
+        write(Object.fromEntries(Object.entries(read()).filter(([key]) => keys.has(key))))
+      } catch {
+        // Telemetry never fails the watcher.
+      }
+    },
+    item(target: SyncTarget, outcome: ApplyOutcome, trigger: ApplyTrigger, ms: number, failure?: { output: string } | { error: unknown }): void {
+      if (!on) return
+      try {
+        const { attempt, recovered } = step(target.key, outcome)
+        const error = !failure
+          ? undefined
+          : 'output' in failure
+            ? errorFields(outputErrorCode(failure.output), applyFailureReason(failure.output), targetNames(target))
+            : errorFields(errorCode((failure.error as { code?: unknown })?.code), failure.error instanceof Error ? failure.error.message : String(failure.error), targetNames(target))
+        telemetry.record({
+          name: 'frontera.cli.apply',
+          severity: SEVERITY[outcome],
+          attributes: {
+            'frontera.item_kind': target.kind,
+            'frontera.item_hash': telemetry.hash(project.id, target.key),
+            'frontera.outcome': outcome,
+            'frontera.attempt': attempt,
+            'frontera.trigger': trigger,
+            duration_ms: Math.round(ms),
+            'frontera.project.hash': projectHash,
+            ...(recovered ? { 'frontera.recovered_after_attempts': recovered.attempts, 'frontera.recovered_after_ms': recovered.ms } : {}),
+          },
+          ...(error ? { error } : {}),
+        })
+      } catch {
+        // Telemetry never fails an apply.
+      }
+    },
+    round(round: { trigger: ApplyTrigger; queued: number; applied: number; failed: number; ms: number }): void {
+      if (!on) return
+      telemetry.record({
+        name: 'frontera.cli.apply_round',
+        severity: round.failed ? 'ERROR' : 'INFO',
+        attributes: { 'frontera.trigger': round.trigger, 'frontera.queued': round.queued, 'frontera.applied': round.applied, 'frontera.failed': round.failed, duration_ms: Math.round(round.ms), 'frontera.project.hash': projectHash },
+      })
+    },
+  }
+}

package/src/telemetry/cli-telemetry.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+import pkg from '../../package.json' with { type: 'json' }
+import { findSolutionRoot, localProjectAt, PROJECT_FILES } from '../local/local-project'
+import { forgeSessionOf } from '../provenance'
+import { telemetryMode } from './enabled'
+import { failOpen } from './fail-open'
+import { HARNESSES, type ExitWhat, type Harness, type Severity, type Via } from './events'
+import { createRecorder, hostResource, type Recorder } from './recorder'
+
+type Env = Record<string, string | undefined>
+
+/**
+ * The `frontera` process's recorder: made on first use from this process's
+ * environment, `service.name` `frontera-cli`, one invocation id per process.
+ */
+let recorder: Recorder | null = null
+
+export function cliTelemetry(): Recorder {
+  recorder ??= failOpen(() =>
+    createRecorder({
+      mode: telemetryMode(process.env),
+      resource: { 'service.name': 'frontera-cli', ...cliVersion(process.env, import.meta.dir), ...hostResource(process.env) },
+      context: cliContext(process.env),
+    }),
+  )
+  return recorder
+}
+
+/** The version a bug report would name (as `frontera --version` says it), and whether it is a release. */
+export function cliVersion(env: Env, dir: string): { 'service.version': string; 'deployment.environment': 'release' | 'dev' } {
+  const stamped = env.FRONTERA_CLI_VERSION?.trim()
+  if (stamped) return { 'service.version': stamped, 'deployment.environment': 'release' }
+  return dir.includes('/node_modules/') ? { 'service.version': pkg.version, 'deployment.environment': 'release' } : { 'service.version': `${pkg.version}-dev`, 'deployment.environment': 'dev' }
+}
+
+const harnessOf = (value: string | null | undefined): Harness | undefined => (HARNESSES as readonly string[]).includes(value ?? '') ? (value as Harness) : undefined
+
+export function cliContext(env: Env): { 'frontera.invocation.id': string; 'frontera.session.id'?: string; 'frontera.harness'?: Harness } {
+  const session = forgeSessionOf(env)
+  const harness = harnessOf(session?.harness)
+  return { 'frontera.invocation.id': randomUUID(), ...(session ? { 'frontera.session.id': session.id } : {}), ...(harness ? { 'frontera.harness': harness } : {}) }
+}
+
+const truthy = (value: string | undefined) => !!value && !['0', 'false'].includes(value.trim().toLowerCase())
+
+/**
+ * Who ran this command: a coding agent in a Forge session, a person in a Forge
+ * terminal, Forge itself (the runtime and the watcher it starts), CI, or a
+ * person at a terminal.
+ */
+export function invocationVia(env: Env): Via {
+  const session = forgeSessionOf(env)
+  const agent = !!harnessOf(session?.harness) || env.CLAUDECODE === '1'
+  if (session) return agent ? 'agent' : 'terminal'
+  if (env.FORGE_TELEMETRY_OUTBOX?.trim()) return 'forge'
+  if (truthy(env.CI) || truthy(env.GITHUB_ACTIONS)) return 'ci'
+  return agent ? 'agent' : 'terminal'
+}
+
+/** The salted hash of the project `cwd` is in, when it is in one. */
+export function projectHashAt(cwd: string, home: string = homedir()): string | undefined {
+  const telemetry = cliTelemetry()
+  if (telemetry.mode.mode === 'off') return undefined
+  const root = findSolutionRoot(cwd, home)
+  const markers = root === resolve(home) ? PROJECT_FILES : [...PROJECT_FILES, '.frontera']
+  if (!markers.some((m) => existsSync(join(root, m)))) return undefined
+  return telemetry.hash(localProjectAt(root).id)
+}
+
+/** The exit code of a command the person stopped with Ctrl+C (128 + SIGINT), as a shell reports it. */
+export const INTERRUPTED = 130
+
+/** The exit code of a command something else stopped with SIGTERM (128 + SIGTERM): Forge's time limit, an agent's shell timeout. */
+export const TERMINATED = 143
+
+/** INFO for success, WARN for refused (bad input, a conflict, no permission) or stopped (Ctrl+C, SIGTERM), ERROR for failure. */
+export function severityOfExit(code: number): Severity {
+  return code === 0 ? 'INFO' : (code >= 2 && code <= 4) || code === INTERRUPTED || code === TERMINATED ? 'WARN' : 'ERROR'
+}
+
+/** An end nobody asked for is ERROR; one asked for with Ctrl+C is WARN (stopped by the person); any other asked-for end is INFO. */
+export const severityOfEnd = (end: { expected: boolean; signal?: string | null }): Severity => (!end.expected ? 'ERROR' : end.signal === 'SIGINT' ? 'WARN' : 'INFO')
+
+/** Process end of something the CLI watches, never thrown. */
+export function recordExit(what: ExitWhat, end: { startedAt: number; expected: boolean; exitCode?: number | null; signal?: string | null }): void {
+  cliTelemetry().record({
+    name: 'frontera.cli.process_exit',
+    severity: severityOfEnd(end),
+    attributes: {
+      'frontera.what': what,
+      'frontera.expected': end.expected,
+      duration_ms: Math.max(0, Math.round(Date.now() - end.startedAt)),
+      ...(typeof end.exitCode === 'number' ? { 'frontera.exit_code': end.exitCode } : {}),
+      ...(end.signal ? { 'frontera.signal': end.signal } : {}),
+    },
+  })
+  cliTelemetry().roll()
+}

package/src/telemetry/device.ts

@@ -0,0 +1,64 @@
+import { createHmac, randomBytes, randomUUID } from 'node:crypto'
+import { linkSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * This machine's telemetry identity: a random id sent as `frontera.device.id`,
+ * and a salt that never leaves it, for hashing project ids and item names.
+ * Kept in the outbox folder as `device.json`, made on first use.
+ */
+export interface DeviceIdentity {
+  id: string
+  salt: string
+}
+
+export const DEVICE_FILE = 'device.json'
+
+function read(path: string): DeviceIdentity | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Partial<DeviceIdentity>
+    return typeof parsed.id === 'string' && parsed.id && typeof parsed.salt === 'string' && parsed.salt ? { id: parsed.id, salt: parsed.salt } : null
+  } catch {
+    return null
+  }
+}
+
+export function freshIdentity(): DeviceIdentity {
+  return { id: randomUUID(), salt: randomBytes(32).toString('hex') }
+}
+
+/**
+ * Read `device.json`, or make it. Two first runs at once agree on one file: each
+ * writes its own temporary file whole, and only the first link to the real name
+ * wins; the other reads the winner's. A corrupt file is replaced. The folder
+ * must exist (Forge makes it while telemetry is on): this throws without it.
+ */
+export function deviceIdentity(dir: string): DeviceIdentity {
+  const path = join(dir, DEVICE_FILE)
+  const existing = read(path)
+  if (existing) return existing
+  const made = freshIdentity()
+  const tmp = join(dir, `.device-${process.pid}-${randomUUID()}.tmp`)
+  writeFileSync(tmp, `${JSON.stringify(made)}\n`, { mode: 0o600 })
+  try {
+    linkSync(tmp, path)
+    return made
+  } catch (err) {
+    const raced = (err as NodeJS.ErrnoException).code === 'EEXIST' ? read(path) : null
+    if (raced) return raced
+    // A corrupt file, or a filesystem without hard links: replaced whole.
+    renameSync(tmp, path)
+    return made
+  } finally {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      // Renamed into place.
+    }
+  }
+}
+
+/** A salted hash of `parts` (a project id; a project id and an item key): 16 hex characters, the same on this machine every time. */
+export function saltedHash(salt: string, ...parts: string[]): string {
+  return createHmac('sha256', salt).update(parts.join('\0')).digest('hex').slice(0, 16)
+}

package/src/telemetry/enabled.ts

@@ -0,0 +1,49 @@
+import { isAbsolute } from 'node:path'
+
+type Env = Record<string, string | undefined>
+
+/**
+ * Whether this process records telemetry, and why: the rule in the design's
+ * "Who sends". Only Forge puts `FORGE_TELEMETRY_OUTBOX` in a process's
+ * environment, so the same CLI in any other terminal writes nothing.
+ * `FRONTERA_TELEMETRY=log` prints events to stderr and writes nothing, in or
+ * out of Forge, so anyone can see what would be sent.
+ */
+export type TelemetryMode =
+  | { mode: 'send'; reason: 'forge'; outbox: string }
+  | { mode: 'log'; reason: 'log' }
+  | { mode: 'off'; reason: 'do_not_track' | 'switched_off' | 'test_runner' | 'outbox_not_absolute' | 'not_in_forge' }
+
+export const REASON_TEXT: Record<TelemetryMode['reason'], string> = {
+  forge: 'started by Forge (FORGE_TELEMETRY_OUTBOX is set): events are written to the outbox, and Forge sends them to the Frontera team',
+  log: 'FRONTERA_TELEMETRY=log: events are printed to stderr, nothing is written or sent',
+  do_not_track: 'DO_NOT_TRACK is set: nothing is recorded',
+  switched_off: 'FRONTERA_TELEMETRY switches it off: nothing is recorded',
+  test_runner: 'running under a test runner (NODE_ENV=test): nothing is recorded',
+  outbox_not_absolute: 'FORGE_TELEMETRY_OUTBOX is not an absolute path: nothing is recorded',
+  not_in_forge: 'not started by Forge (FORGE_TELEMETRY_OUTBOX is not set): nothing is recorded or sent',
+}
+
+const OFF_WORDS = new Set(['0', 'false', 'off', 'no'])
+
+/**
+ * Set by Forge on the `frontera` calls it makes on its own schedule (a screen's
+ * poll, a timed fetch): such a call records its `frontera.cli.command` only
+ * when it fails, so a poll every minute does not drown what people and agents run.
+ */
+export const BACKGROUND_ENV = 'FORGE_TELEMETRY_BACKGROUND'
+
+export const isBackground = (env: Env): boolean => env[BACKGROUND_ENV]?.trim() === '1'
+
+export function telemetryMode(env: Env): TelemetryMode {
+  const setting = env.FRONTERA_TELEMETRY?.trim().toLowerCase() ?? ''
+  const dnt = env.DO_NOT_TRACK?.trim().toLowerCase() ?? ''
+  if (dnt && !OFF_WORDS.has(dnt)) return { mode: 'off', reason: 'do_not_track' }
+  if (OFF_WORDS.has(setting)) return { mode: 'off', reason: 'switched_off' }
+  if (setting === 'log') return { mode: 'log', reason: 'log' }
+  if (env.NODE_ENV === 'test') return { mode: 'off', reason: 'test_runner' }
+  const outbox = env.FORGE_TELEMETRY_OUTBOX?.trim()
+  if (!outbox) return { mode: 'off', reason: 'not_in_forge' }
+  if (!isAbsolute(outbox)) return { mode: 'off', reason: 'outbox_not_absolute' }
+  return { mode: 'send', reason: 'forge', outbox }
+}