@frontera-sdk/cli 1.52.22 → 1.52.24

package/src/local/local-test-runner.ts

@@ -0,0 +1,191 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+import { parse } from 'yaml'
+
+import type { LocalCredentials } from './local-state'
+
+/**
+ * Run an Agent's saved regression cases against the local runtime.
+ *
+ * Each case in `agents/<slug>/evals/*.yaml` is a conversation and the reply it
+ * should end with. The runner opens a fresh conversation with the Agent's
+ * draft (or the live version), sends the person's turns in order through the
+ * same chat endpoint the platform uses, and compares the final reply with the
+ * expectation.
+ */
+
+export interface TestCase {
+  name: string
+  conversation: Array<Record<string, string>>
+  expected?: string
+  /** Pass when the reply contains each of these, instead of matching exactly. */
+  expectedContains?: string[]
+}
+
+export interface CaseResult {
+  agent: string
+  file: string
+  name: string
+  passed: boolean
+  reply: string
+  reason?: string
+  ms: number
+  /** The Agent's config id and the conversation the case ran in, so Studio can open it. */
+  agentId?: string
+  conversationId?: string
+}
+
+export interface CaseFile {
+  agent: string
+  file: string
+  cases: TestCase[]
+}
+
+export function findCaseFiles(root: string, agent?: string): CaseFile[] {
+  const agentsDir = join(root, 'agents')
+  if (!existsSync(agentsDir)) return []
+  const out: CaseFile[] = []
+  for (const slug of readdirSync(agentsDir)) {
+    if (agent && slug !== agent) continue
+    const evalsDir = join(agentsDir, slug, 'evals')
+    if (!existsSync(evalsDir)) continue
+    for (const name of readdirSync(evalsDir)) {
+      if (!/\.ya?ml$/.test(name)) continue
+      const path = join(evalsDir, name)
+      const doc = parse(readFileSync(path, 'utf8')) as { cases?: TestCase[] } | null
+      out.push({ agent: slug, file: relative(root, path), cases: doc?.cases ?? [] })
+    }
+  }
+  return out
+}
+
+function normalise(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+export function judge(c: TestCase, reply: string): { passed: boolean; reason?: string } {
+  if (c.expectedContains?.length) {
+    const missing = c.expectedContains.filter((s) => !normalise(reply).toLowerCase().includes(normalise(s).toLowerCase()))
+    return missing.length ? { passed: false, reason: `reply does not mention: ${missing.join(', ')}` } : { passed: true }
+  }
+  if (c.expected === undefined) return { passed: false, reason: 'the case has no `expected` or `expectedContains`' }
+  return normalise(reply) === normalise(c.expected) ? { passed: true } : { passed: false, reason: 'reply differs from `expected`' }
+}
+
+interface Api {
+  serviceUrl: string
+  creds: LocalCredentials
+}
+
+async function call<T>(api: Api, path: string, init: { method?: string; body?: unknown } = {}): Promise<T> {
+  const res = await fetch(new URL(path, api.serviceUrl), {
+    method: init.method ?? (init.body === undefined ? 'GET' : 'POST'),
+    headers: {
+      authorization: `Bearer ${api.creds.session}`,
+      'x-org-id': api.creds.organizationId,
+      'x-workspace-id': api.creds.workspaceId,
+      'content-type': 'application/json',
+    },
+    body: init.body === undefined ? undefined : JSON.stringify(init.body),
+    signal: AbortSignal.timeout(60_000),
+  })
+  const text = await res.text()
+  if (!res.ok) throw new Error(`${path} answered ${res.status}: ${text.slice(0, 200)}`)
+  const parsed = text ? (JSON.parse(text) as { data?: T }) : {}
+  return (parsed.data ?? parsed) as T
+}
+
+const TURN_TIMEOUT_MS = 180_000
+
+/** Send one person turn and collect the streamed reply's text. */
+async function sendTurn(api: Api, conversationId: string, agentName: string, text: string): Promise<string> {
+  const res = await fetch(new URL('/v1/chat', api.serviceUrl), {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${api.creds.session}`,
+      'x-org-id': api.creds.organizationId,
+      'x-workspace-id': api.creds.workspaceId,
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      conversationId,
+      agentName,
+      messages: [{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text }] }],
+    }),
+    // A reply that never finishes (the stream's keepalives hold it open) fails the case, not the whole run.
+    signal: AbortSignal.timeout(TURN_TIMEOUT_MS),
+  })
+  if (!res.ok || !res.body) throw new Error(`chat answered ${res.status}: ${(await res.text()).slice(0, 200)}`)
+  let reply = ''
+  let buffer = ''
+  const decoder = new TextDecoder()
+  for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
+    buffer += decoder.decode(chunk, { stream: true })
+    let newline: number
+    while ((newline = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newline).trim()
+      buffer = buffer.slice(newline + 1)
+      if (!line.startsWith('data:')) continue
+      const payload = line.slice(5).trim()
+      if (payload === '[DONE]') continue
+      try {
+        const event = JSON.parse(payload) as { type?: string; delta?: string; errorText?: string }
+        if (event.type === 'text-delta' && typeof event.delta === 'string') reply += event.delta
+        if (event.type === 'error') throw new Error(event.errorText ?? 'the turn failed')
+      } catch (err) {
+        if (err instanceof SyntaxError) continue
+        throw err
+      }
+    }
+  }
+  return reply
+}
+
+export async function runCases(args: {
+  serviceUrl: string
+  creds: LocalCredentials
+  files: CaseFile[]
+  live: boolean
+  onResult: (r: CaseResult) => void
+}): Promise<CaseResult[]> {
+  const api: Api = { serviceUrl: args.serviceUrl, creds: args.creds }
+  const results: CaseResult[] = []
+  for (const file of args.files) {
+    let agentName = file.agent
+    let agentId: string | undefined
+    let setupError: string | undefined
+    try {
+      const agent = await call<{ id: string }>(api, `/v1/config/agents/${encodeURIComponent(file.agent)}`)
+      agentId = agent.id
+      if (!args.live) {
+        const preview = await call<{ previewAgentSlug: string }>(api, `/v1/config/agents/${agent.id}/test-session`, { body: {} })
+        agentName = preview.previewAgentSlug
+      }
+    } catch (err) {
+      // An Agent that is missing or whose draft cannot be tried fails its cases, not the run.
+      setupError = (err as Error).message
+    }
+    for (const c of file.cases) {
+      const started = Date.now()
+      let result: CaseResult
+      let conversationId: string | undefined
+      try {
+        if (setupError) throw new Error(setupError)
+        const session = await call<{ id: string }>(api, '/v1/sessions', { body: { agentName, workspaceId: args.creds.workspaceId } })
+        conversationId = session.id
+        let reply = ''
+        for (const turn of c.conversation) {
+          if (typeof turn.user === 'string') reply = await sendTurn(api, session.id, agentName, turn.user)
+        }
+        const verdict = judge(c, reply)
+        result = { agent: file.agent, file: file.file, name: c.name, passed: verdict.passed, reply, reason: verdict.reason, ms: Date.now() - started, agentId, conversationId }
+      } catch (err) {
+        result = { agent: file.agent, file: file.file, name: c.name, passed: false, reply: '', reason: (err as Error).message, ms: Date.now() - started, agentId, conversationId }
+      }
+      results.push(result)
+      args.onResult(result)
+    }
+  }
+  return results
+}

package/src/local/local-test-runs.ts

@@ -0,0 +1,75 @@
+import type { LocalProject } from './local-project'
+import { readState } from './local-state'
+import { findCaseFiles, runCases, type CaseResult } from './local-test-runner'
+
+/**
+ * Test runs started from Studio: the same runner as `frontera local test`,
+ * run in the supervisor so the page can follow progress. Kept in memory,
+ * newest first; the case files in the solution are the record that matters.
+ */
+
+export interface TestRun {
+  id: string
+  status: 'running' | 'passed' | 'failed' | 'error'
+  agent: string | null
+  live: boolean
+  startedAt: string
+  finishedAt: string | null
+  total: number
+  results: CaseResult[]
+  error: string | null
+}
+
+const KEEP = 20
+
+export function createTestRuns(project: LocalProject, serviceUrl: string) {
+  const runs: TestRun[] = []
+
+  return {
+    list: (): TestRun[] => runs,
+
+    get: (id: string): TestRun | undefined => runs.find((r) => r.id === id),
+
+    /** Start a run; refused while another is running, so a double click cannot run everything twice. */
+    start(args: { agent?: string; live?: boolean }): { run: TestRun } | { error: string; status: number } {
+      if (runs.some((r) => r.status === 'running')) return { error: 'a test run is already running', status: 409 }
+      const creds = readState(project)?.credentials
+      if (!creds?.session) return { error: 'the runtime is not seeded yet', status: 409 }
+      let files: ReturnType<typeof findCaseFiles>
+      try {
+        files = findCaseFiles(project.root, args.agent)
+      } catch (err) {
+        return { error: `a case file could not be read: ${(err as Error).message}`, status: 422 }
+      }
+      const total = files.reduce((n, f) => n + f.cases.length, 0)
+      if (total === 0) return { error: 'no test cases to run', status: 400 }
+
+      const run: TestRun = {
+        id: crypto.randomUUID(),
+        status: 'running',
+        agent: args.agent ?? null,
+        live: !!args.live,
+        startedAt: new Date().toISOString(),
+        finishedAt: null,
+        total,
+        results: [],
+        error: null,
+      }
+      runs.unshift(run)
+      runs.splice(KEEP)
+
+      void runCases({ serviceUrl, creds, files, live: run.live, onResult: (r) => run.results.push(r) })
+        .then((results) => {
+          run.status = results.every((r) => r.passed) ? 'passed' : 'failed'
+        })
+        .catch((err: Error) => {
+          run.status = 'error'
+          run.error = err.message
+        })
+        .finally(() => {
+          run.finishedAt = new Date().toISOString()
+        })
+      return { run }
+    },
+  }
+}

package/src/local/local-traces.ts

@@ -0,0 +1,322 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+
+/**
+ * Local traces: the part of a tracing backend the platform uses, kept on this
+ * machine. The service exports its spans (OTLP JSON, as its tracing exporter
+ * sends them) and reads traces back through the same public API it uses in a
+ * deployment, so Studio's trace views work locally with no tracing service.
+ *
+ * Spans are kept in memory and appended to a JSONL file in the runtime's
+ * state folder, which is compacted to the newest traces as it grows.
+ */
+
+/** Local keys the service is configured with; nothing leaves this machine. */
+export const LOCAL_TRACE_KEYS = { publicKey: 'pk-lf-frontera-local', secretKey: 'sk-lf-frontera-local' } as const
+
+const MAX_TRACES = 300
+
+export interface StoredSpan {
+  traceId: string
+  spanId: string
+  parentSpanId: string | null
+  name: string
+  startMs: number
+  endMs: number | null
+  attributes: Record<string, unknown>
+  statusCode: number
+  statusMessage: string | null
+}
+
+interface OtlpValue {
+  stringValue?: string
+  boolValue?: boolean
+  intValue?: number | string
+  doubleValue?: number
+  arrayValue?: { values?: OtlpValue[] }
+  kvlistValue?: { values?: Array<{ key: string; value: OtlpValue }> }
+}
+
+function otlpValue(v: OtlpValue | undefined): unknown {
+  if (!v) return null
+  if (v.stringValue !== undefined) return v.stringValue
+  if (v.boolValue !== undefined) return v.boolValue
+  if (v.intValue !== undefined) return Number(v.intValue)
+  if (v.doubleValue !== undefined) return v.doubleValue
+  if (v.arrayValue) return (v.arrayValue.values ?? []).map(otlpValue)
+  if (v.kvlistValue) return Object.fromEntries((v.kvlistValue.values ?? []).map((kv) => [kv.key, otlpValue(kv.value)]))
+  return null
+}
+
+/** OTLP ids arrive as hex (the JSON exporter) or base64; traces use lowercase hex. */
+function hexId(id: unknown): string {
+  if (typeof id !== 'string' || id === '') return ''
+  if (/^[0-9a-f]+$/i.test(id)) return id.toLowerCase()
+  return Buffer.from(id, 'base64').toString('hex')
+}
+
+const nanosToMs = (n: unknown) => (n === undefined || n === null || n === '' || n === '0' || n === 0 ? null : Number(BigInt(String(n)) / 1_000_000n))
+
+/** The spans of an OTLP JSON export request. */
+export function parseOtlp(body: unknown): StoredSpan[] {
+  const out: StoredSpan[] = []
+  const resources = (body as { resourceSpans?: unknown[] })?.resourceSpans ?? []
+  for (const rs of resources as Array<{ scopeSpans?: Array<{ spans?: unknown[] }> }>) {
+    for (const ss of rs.scopeSpans ?? []) {
+      for (const raw of (ss.spans ?? []) as Array<Record<string, unknown>>) {
+        const traceId = hexId(raw.traceId)
+        const spanId = hexId(raw.spanId)
+        if (!traceId || !spanId) continue
+        const attributes: Record<string, unknown> = {}
+        for (const a of (raw.attributes ?? []) as Array<{ key: string; value: OtlpValue }>) attributes[a.key] = otlpValue(a.value)
+        const status = (raw.status ?? {}) as { code?: number; message?: string }
+        out.push({
+          traceId,
+          spanId,
+          parentSpanId: hexId(raw.parentSpanId) || null,
+          name: String(raw.name ?? ''),
+          startMs: nanosToMs(raw.startTimeUnixNano) ?? Date.now(),
+          endMs: nanosToMs(raw.endTimeUnixNano),
+          attributes,
+          statusCode: Number(status.code ?? 0),
+          statusMessage: status.message ?? null,
+        })
+      }
+    }
+  }
+  return out
+}
+
+/** A JSON-encoded attribute (the tracing SDK serializes objects) as its value. */
+function decoded(value: unknown): unknown {
+  if (typeof value !== 'string') return value ?? null
+  const t = value.trim()
+  const quoted = t.length >= 2 && t.startsWith('"') && t.endsWith('"')
+  if (!(t.startsWith('{') || t.startsWith('[') || quoted)) return value
+  try {
+    return JSON.parse(t)
+  } catch {
+    return value
+  }
+}
+
+const first = (attrs: Record<string, unknown>, keys: string[]) => {
+  for (const k of keys) if (attrs[k] !== undefined && attrs[k] !== null && attrs[k] !== '') return attrs[k]
+  return undefined
+}
+
+const num = (v: unknown) => (typeof v === 'number' ? v : typeof v === 'string' && v !== '' && !Number.isNaN(Number(v)) ? Number(v) : undefined)
+
+const prefixed = (attrs: Record<string, unknown>, prefix: string) => {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(attrs)) if (k.startsWith(`${prefix}.`)) out[k.slice(prefix.length + 1)] = decoded(v)
+  const whole = decoded(attrs[prefix])
+  return whole && typeof whole === 'object' && !Array.isArray(whole) ? { ...(whole as Record<string, unknown>), ...out } : out
+}
+
+const iso = (ms: number | null) => (ms === null ? null : new Date(ms).toISOString())
+
+/** A span as an observation: a model call (generation), a tool, or a span. */
+export function toObservation(span: StoredSpan) {
+  const a = span.attributes
+  const declared = typeof a['langfuse.observation.type'] === 'string' ? (a['langfuse.observation.type'] as string) : null
+  const model = first(a, ['langfuse.observation.model.name', 'gen_ai.response.model', 'gen_ai.request.model', 'ai.response.model', 'ai.model.id'])
+  const type = (declared ?? (model ? 'generation' : 'span')).toUpperCase()
+  const usageDetails = decoded(a['langfuse.observation.usage_details']) as Record<string, number> | null
+  const input = num(usageDetails?.input) ?? num(first(a, ['gen_ai.usage.input_tokens', 'gen_ai.usage.prompt_tokens', 'ai.usage.inputTokens', 'ai.usage.promptTokens']))
+  const output = num(usageDetails?.output) ?? num(first(a, ['gen_ai.usage.output_tokens', 'gen_ai.usage.completion_tokens', 'ai.usage.outputTokens', 'ai.usage.completionTokens']))
+  const total = num(usageDetails?.total) ?? (input !== undefined || output !== undefined ? (input ?? 0) + (output ?? 0) : undefined)
+  const costDetails = decoded(a['langfuse.observation.cost_details']) as Record<string, number> | null
+  const cost = num(costDetails?.total)
+  const level = (first(a, ['langfuse.observation.level']) as string | undefined) ?? (span.statusCode === 2 ? 'ERROR' : 'DEFAULT')
+  return {
+    id: span.spanId,
+    traceId: span.traceId,
+    type,
+    name: span.name,
+    startTime: iso(span.startMs),
+    endTime: iso(span.endMs),
+    parentObservationId: span.parentSpanId,
+    level,
+    statusMessage: (first(a, ['langfuse.observation.status_message']) as string | undefined) ?? span.statusMessage,
+    model: typeof model === 'string' ? model : null,
+    modelParameters: decoded(a['langfuse.observation.model.parameters']) ?? null,
+    input: decoded(first(a, ['langfuse.observation.input', 'ai.prompt.messages', 'ai.prompt', 'gen_ai.prompt'])) ?? null,
+    output: decoded(first(a, ['langfuse.observation.output', 'ai.response.text', 'ai.response.toolCalls', 'gen_ai.completion'])) ?? null,
+    metadata: prefixed(a, 'langfuse.observation.metadata'),
+    usage: total === undefined ? null : { input: input ?? 0, output: output ?? 0, total, unit: 'TOKENS' },
+    usageDetails: usageDetails ?? (total === undefined ? {} : { input: input ?? 0, output: output ?? 0, total }),
+    costDetails: costDetails ?? {},
+    calculatedTotalCost: cost ?? null,
+    latency: span.endMs === null ? null : (span.endMs - span.startMs) / 1000,
+  }
+}
+
+/** The spans of one trace as a trace with its observations. */
+export function toTrace(spans: StoredSpan[]) {
+  const ids = new Set(spans.map((s) => s.spanId))
+  const ordered = [...spans].sort((a, b) => a.startMs - b.startMs)
+  const roots = ordered.filter((s) => !s.parentSpanId || !ids.has(s.parentSpanId))
+  const root = roots[0] ?? ordered[0]
+  if (!root) throw new Error('a trace has at least one span')
+  // Trace-level attributes may sit on any span (they propagate to children).
+  const attr = (key: string) => {
+    for (const s of ordered) if (s.attributes[key] !== undefined) return s.attributes[key]
+    return undefined
+  }
+  const metadata: Record<string, unknown> = {}
+  for (const s of ordered) Object.assign(metadata, prefixed(s.attributes, 'langfuse.trace.metadata'))
+  const tags = new Set<string>()
+  for (const s of ordered) {
+    const t = decoded(s.attributes['langfuse.trace.tags'])
+    if (Array.isArray(t)) for (const tag of t) if (typeof tag === 'string') tags.add(tag)
+  }
+  const observations = ordered.map(toObservation)
+  const start = Math.min(...ordered.map((s) => s.startMs))
+  const end = Math.max(...ordered.map((s) => s.endMs ?? s.startMs))
+  const totalCost = observations.reduce((n, o) => n + (o.calculatedTotalCost ?? 0), 0)
+  const rootObservation = observations.find((o) => o.id === root.spanId)
+  const level = observations.some((o) => o.level === 'ERROR') ? 'ERROR' : observations.some((o) => o.level === 'WARNING') ? 'WARNING' : 'DEFAULT'
+  return {
+    id: root.traceId,
+    name: (attr('langfuse.trace.name') as string | undefined) ?? root.name,
+    timestamp: new Date(start).toISOString(),
+    userId: (attr('user.id') ?? attr('langfuse.user.id') ?? null) as string | null,
+    sessionId: (attr('session.id') ?? attr('langfuse.session.id') ?? null) as string | null,
+    tags: [...tags],
+    metadata,
+    environment: (attr('langfuse.environment') as string | undefined) ?? 'local',
+    input: decoded(attr('langfuse.trace.input')) ?? rootObservation?.input ?? null,
+    output: decoded(attr('langfuse.trace.output')) ?? rootObservation?.output ?? null,
+    latency: (end - start) / 1000,
+    totalCost,
+    level,
+    htmlPath: '',
+    observations,
+    scores: [],
+  }
+}
+
+type LocalTrace = ReturnType<typeof toTrace>
+type Condition = { type?: string; column?: string; key?: string; operator?: string; value?: unknown }
+
+/** The subset of the trace list filter the service sends: time bounds, a metadata key, the level. */
+export function matchesFilter(trace: LocalTrace, filter: Condition[]): boolean {
+  for (const c of filter) {
+    if (c.column === 'timestamp' && typeof c.value === 'string') {
+      const at = Date.parse(trace.timestamp)
+      const bound = Date.parse(c.value)
+      if (c.operator === '>=' && at < bound) return false
+      if (c.operator === '<=' && at > bound) return false
+      if (c.operator === '>' && at <= bound) return false
+      if (c.operator === '<' && at >= bound) return false
+    } else if (c.column === 'metadata' && c.key && c.operator === '=') {
+      if (String(trace.metadata[c.key] ?? '') !== String(c.value)) return false
+    } else if (c.column === 'level' && c.operator === '=') {
+      if (trace.level !== c.value) return false
+    }
+  }
+  return true
+}
+
+export function createTraceStore(file: string | null) {
+  const byTrace = new Map<string, Map<string, StoredSpan>>()
+  let written = 0
+
+  const add = (span: StoredSpan) => {
+    const spans = byTrace.get(span.traceId) ?? new Map<string, StoredSpan>()
+    // Re-inserting moves the trace to the newest end of the map.
+    byTrace.delete(span.traceId)
+    spans.set(span.spanId, span)
+    byTrace.set(span.traceId, spans)
+  }
+  const prune = () => {
+    while (byTrace.size > MAX_TRACES) byTrace.delete(byTrace.keys().next().value!)
+  }
+
+  if (file && existsSync(file)) {
+    for (const line of readFileSync(file, 'utf8').split('\n')) {
+      if (!line.trim()) continue
+      try {
+        add(JSON.parse(line) as StoredSpan)
+      } catch {
+        // A torn last line from a crash; the rest stands.
+      }
+    }
+    prune()
+  }
+
+  const compact = () => {
+    if (!file) return
+    const lines: string[] = []
+    for (const spans of byTrace.values()) for (const s of spans.values()) lines.push(JSON.stringify(s))
+    writeFileSync(file, lines.length ? `${lines.join('\n')}\n` : '')
+    written = lines.length
+  }
+
+  return {
+    ingest(spans: StoredSpan[]) {
+      for (const s of spans) add(s)
+      prune()
+      if (!file || spans.length === 0) return
+      appendFileSync(file, `${spans.map((s) => JSON.stringify(s)).join('\n')}\n`)
+      written += spans.length
+      // Rewrite with only what is kept once the file is well past it.
+      let kept = 0
+      for (const t of byTrace.values()) kept += t.size
+      if (written > kept * 2 + 500) compact()
+    },
+    list(opts: { page?: number; limit?: number; filter?: Condition[] } = {}) {
+      const all = [...byTrace.values()].map((m) => toTrace([...m.values()])).filter((t) => matchesFilter(t, opts.filter ?? []))
+      all.sort((a, b) => Date.parse(b.timestamp) - Date.parse(a.timestamp))
+      const limit = Math.max(1, Math.min(opts.limit ?? 50, 100))
+      const page = Math.max(1, opts.page ?? 1)
+      const data = all.slice((page - 1) * limit, page * limit)
+      return { data, meta: { page, limit, totalItems: all.length, totalPages: Math.ceil(all.length / limit) } }
+    },
+    get(traceId: string): LocalTrace | null {
+      const spans = byTrace.get(traceId.toLowerCase())
+      return spans ? toTrace([...spans.values()]) : null
+    },
+  }
+}
+
+export function startLocalTraces(opts: { port: number; file: string | null; log?: (line: string) => void }) {
+  const store = createTraceStore(opts.file)
+  const json = (data: unknown, status = 200) => new Response(JSON.stringify(data), { status, headers: { 'content-type': 'application/json' } })
+  let warnedFormat = false
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: opts.port,
+    async fetch(req) {
+      const url = new URL(req.url)
+      const path = url.pathname
+      if (req.method === 'POST' && path === '/api/public/otel/v1/traces') {
+        if (!(req.headers.get('content-type') ?? '').includes('json')) {
+          if (!warnedFormat) opts.log?.(`spans arrived as ${req.headers.get('content-type')}; only OTLP JSON is kept`)
+          warnedFormat = true
+          return json({ message: 'OTLP JSON only' }, 415)
+        }
+        const spans = parseOtlp(await req.json().catch(() => null))
+        store.ingest(spans)
+        return json({ partialSuccess: {} })
+      }
+      if (req.method === 'GET' && path === '/api/public/traces') {
+        let filter: Condition[] = []
+        try {
+          filter = JSON.parse(url.searchParams.get('filter') ?? '[]') as Condition[]
+        } catch {
+          filter = []
+        }
+        return json(store.list({ page: Number(url.searchParams.get('page') ?? 1), limit: Number(url.searchParams.get('limit') ?? 50), filter }))
+      }
+      const one = path.match(/^\/api\/public\/traces\/([^/]+)$/)
+      if (req.method === 'GET' && one?.[1]) {
+        const trace = store.get(decodeURIComponent(one[1]))
+        return trace ? json(trace) : json({ message: 'Trace not found' }, 404)
+      }
+      if (req.method === 'GET' && path === '/api/public/health') return json({ status: 'OK', version: 'frontera-local' })
+      return json({ message: `${req.method} ${path} is not part of local traces` }, 404)
+    },
+  })
+  return { server, store }
+}

package/src/main.ts

@@ -117,7 +117,7 @@ async function main(): Promise<number> {
   // `frontera agent --help`, or a bare `frontera agent`: list the noun's
   // commands. Without this the CLI's own hints dead-ended, since a reserved
   // verb tells the caller to run exactly this.
-  if (!command && nouns().includes(noun)) {
+  if (!command && nouns(true).includes(noun)) {
     const askedForHelp =
       maybeVerb === undefined ||
       maybeVerb === '--help' ||

package/src/packaging.ts

@@ -45,6 +45,11 @@ export function isExcluded(rel: string): boolean {
   // machine, not source: packaging it would push a few hundred KB of PNG into
   // every `app pull` for a picture the platform already stores per version.
   if (rel === '.frontera/last-render.png') return true
+  // The rest of `.frontera/` is this machine's tool state: the CLI's binding,
+  // and in a local project the runtime's keys, owner session and secrets
+  // (`.frontera/local/`). None of it is source and some of it is credentials,
+  // so only the render evidence the platform reads from an App's archive goes.
+  if (segments[0] === '.frontera' && segments.length > 1 && rel !== '.frontera/last-render.json') return true
   return false
 }