aui-agent-builder 0.3.108 → 0.3.110

package/dist/telemetry.js

@@ -17,12 +17,59 @@ import { NodeSDK } from "@opentelemetry/sdk-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
-import { trace, SpanStatusCode } from "@opentelemetry/api";
+import { trace, context, ROOT_CONTEXT, SpanStatusCode, TraceFlags, } from "@opentelemetry/api";
+import { randomBytes, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 // TODO: Replace with your actual Logfire write token
 const LOGFIRE_TOKEN = "pylf_v1_us_1wcYn9Jc6hVmFwPxwTgLnQcktc0HjHq2D0GLjFvp197C";
 const LOGFIRE_OTLP_URL = "https://logfire-api.pydantic.dev/v1/traces";
 let sdk = null;
 let cliVersion = "unknown";
+// ─── Per-process telemetry identifiers ────────────────────────────────
+//
+// Two stable correlators are stamped on every span via `setUserContext`:
+//
+//   - `cli.session_id` (LONG-LIVED) — minted on every successful
+//     `aui login` (see `buildSession` in `services/auth.service.ts`) and
+//     persisted as `cli_session_id` in `~/.aui/session.json`. All CLI
+//     commands run between two logins share it, so Logfire can be
+//     filtered to "everything this user did in this login" with one
+//     attribute. Cleared by `aui logout` (the whole session file gets
+//     unlinked). Callers (notably `agent-builder-bff` shelling out to
+//     `aui` inside E2B sandboxes) can override via `AUI_CLI_SESSION_ID`
+//     to glue multiple invocations to their own session/request id.
+//
+//   - `cli.run_id` (PER-INVOCATION) — a fresh UUID for this process.
+//     Distinguishes individual `aui …` runs inside one login session.
+//     Also overridable via `AUI_CLI_RUN_ID` so the BFF can correlate
+//     a single sandbox command with its outer trace.
+//
+// Plus two pieces of run context everyone wants on every span:
+//
+//   - `cli.command` — the resolved sub-command (e.g. "push", "pull",
+//     "import-agent"). Best-effort parse of `process.argv`.
+//   - `cli.invoked_at` — ISO timestamp at process start. Handy for
+//     "this same command ran 4 times in 10 minutes" hot-spot triage.
+//
+// All four are read once at module load (cheap, deterministic) and
+// re-attached on every `setUserContext` call.
+const cliRunId = process.env.AUI_CLI_RUN_ID || randomUUID();
+const cliInvokedAt = new Date().toISOString();
+/** Best-effort: extract the active sub-command from argv. Commander
+ *  parses lazily, so we mirror its convention — the first non-flag
+ *  positional after argv[1] (the entry script) is the command name.
+ *  Returns "(no-command)" when the CLI was invoked bare (just `aui`). */
+function resolveCliCommand() {
+    const args = process.argv.slice(2);
+    for (const arg of args) {
+        if (!arg.startsWith("-"))
+            return arg;
+    }
+    return "(no-command)";
+}
+const cliCommand = resolveCliCommand();
 /**
  * Returns `false` if any documented opt-out env var is set, otherwise
  * `true`. Exported so tests can pin every documented opt-out path with a
@@ -53,6 +100,11 @@ export function initTelemetry(version) {
         });
         sdk = new NodeSDK({
             traceExporter: exporter,
+            // Pin the `trace_id` of every new trace in this process to the
+            // session-derived value so multiple `aui …` invocations under
+            // the same login share one Logfire trace. Falls back to random
+            // ids when no session is loadable (pre-login / logged-out).
+            idGenerator: sessionAwareIdGenerator,
             resource: resourceFromAttributes({
                 [ATTR_SERVICE_NAME]: "aui-cli",
                 [ATTR_SERVICE_VERSION]: version,
@@ -77,9 +129,698 @@ export async function shutdownTelemetry() {
 export function getTracer() {
     return trace.getTracer("aui-cli");
 }
+/**
+ * Resolve the long-lived CLI telemetry session id.
+ *
+ * Order of precedence:
+ *   1. `AUI_CLI_SESSION_ID` env var — lets `agent-builder-bff` (or any
+ *      harness) pass in its own session/request id so a single BFF
+ *      session correlates across every `aui` invocation in the sandbox.
+ *   2. `cli_session_id` field in `~/.aui/session.json` — minted on
+ *      every `aui login`. Persists across CLI invocations between two
+ *      logins.
+ *   3. `undefined` — no session is loadable (unauthenticated user / no
+ *      session file). Caller skips the attribute rather than emitting
+ *      a confusing fake value.
+ */
+export function getCliSessionId() {
+    if (process.env.AUI_CLI_SESSION_ID)
+        return process.env.AUI_CLI_SESSION_ID;
+    // Read `~/.aui/session.json` synchronously and pluck `cli_session_id`.
+    // We deliberately do NOT import `loadSessionRaw` from `./config/index.js`
+    // here:
+    //   - This file is loaded at process boot by `src/index.ts` BEFORE any
+    //     command imports `config/`. A top-level ESM import would create
+    //     an evaluation cycle.
+    //   - Preflight telemetry in `api-client/index.ts` calls this on a hot
+    //     path; going through a dynamic `import()` would force every API
+    //     call into an extra microtask just to read a small JSON file.
+    // The session file format (just look at `cli_session_id`) is stable;
+    // a one-line `fs.readFileSync` keeps this hot path zero-allocation
+    // on the no-session branch.
+    try {
+        const home = process.env.AUI_HOME || path.join(os.homedir(), ".aui");
+        const sf = path.join(home, "session.json");
+        if (!fs.existsSync(sf))
+            return undefined;
+        const raw = fs.readFileSync(sf, "utf-8");
+        const parsed = JSON.parse(raw);
+        return parsed.cli_session_id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Same as {@link getCliSessionId} but always returns the per-process
+ *  run id (one UUID per CLI invocation, fresh every time). Exported so
+ *  hot paths can attach it as an event attribute without going through
+ *  `setUserContext`. */
+export function getCliRunId() {
+    return cliRunId;
+}
+// ─── Session-scoped trace grouping ────────────────────────────────────
+//
+// `cli.session_id` as an attribute is filterable but Logfire doesn't
+// visually GROUP spans by an arbitrary attribute — it groups by
+// `trace_id`. Each `aui …` invocation is its own process, so by
+// default every command starts a fresh trace and lands as a separate
+// row in the Logfire UI even when they all carry the same
+// `cli.session_id`.
+//
+// To get the "one expandable session" view we do two things:
+//
+//   1. Install a custom OTel `IdGenerator` that returns a deterministic
+//      `trace_id` derived from the session UUID for any new trace
+//      created in this process. UUIDs and OTel trace ids are both
+//      128 bits — drop the dashes and you have a valid trace id —
+//      so two processes running under the same login session
+//      mint the SAME trace id and end up in one Logfire trace.
+//
+//   2. Open a real `aui.session` root span at process start, carrying
+//      the agent code / session id / `.auirc` snapshot. Logfire uses
+//      this real span as the trace's clickable title row (instead of
+//      the "incomplete trace, missing root span" header it renders
+//      when the orphan grouping logic kicks in). Every command span
+//      becomes a child of `aui.session` via the OTel context manager,
+//      so the trace tree is one neat collapsible group.
+//
+// The per-process `cli.run_id` UUID lives on each `aui.session` so
+// individual invocations stay distinguishable within the session.
+/** Lower-case 32-hex trace-id from a UUID. Returns `null` for malformed
+ *  input or for the all-zero trace-id (forbidden by the OTel spec). */
+function uuidToTraceId(uuid) {
+    const hex = uuid.replace(/-/g, "").toLowerCase();
+    if (!/^[0-9a-f]{32}$/.test(hex))
+        return null;
+    if (/^0+$/.test(hex))
+        return null;
+    return hex;
+}
+/**
+ * Custom `IdGenerator` that returns the session-derived trace id for
+ * any new trace started in this process, and falls back to random
+ * trace ids when there's no session. Span ids are always random.
+ *
+ * Object-literal shape (no class) so we don't take a runtime
+ * dependency on `@opentelemetry/sdk-trace-base` — `NodeSDK` accepts
+ * anything that matches the structural `IdGenerator` interface.
+ */
+const sessionAwareIdGenerator = {
+    generateTraceId() {
+        const sessionId = getCliSessionId();
+        if (sessionId) {
+            const t = uuidToTraceId(sessionId);
+            if (t)
+                return t;
+        }
+        return randomBytes(16).toString("hex");
+    },
+    generateSpanId() {
+        return randomBytes(8).toString("hex");
+    },
+};
+// ─── Session-root span: emit-once / reference-thereafter ──────────────
+//
+// We want exactly ONE `aui.session` span at the top of the Logfire
+// trace — no matter how many `aui …` processes the user spawns under
+// one login. Spans can't be shared across processes, so the trick is:
+//
+//   - The FIRST telemetry-enabled invocation after login emits a
+//     real `aui.session` span (root, true OTel root with parent=null),
+//     waits until just before process exit to attach its attributes,
+//     and persists its `span_id` to `~/.aui/session.json` as
+//     `cli_session_root_span_id`.
+//
+//   - Every SUBSEQUENT invocation reads the persisted `span_id`,
+//     builds a synthetic "remote parent" SpanContext from
+//     (session-trace-id, persisted-span-id), and attaches its command
+//     spans as children of that remote parent. It emits NO
+//     `aui.session` of its own.
+//
+// Net result in Logfire:
+//
+//   aui session: <agent code>             ← emitted by invocation 1
+//   ├── aui.import                        ← invocation 1
+//   ├── aui.validate                      ← invocation 2 (remote child)
+//   ├── aui.push                          ← invocation 3 (remote child)
+//   └── …
+//
+// Attribute lifecycle:
+//   - `aui.session`'s attrs (agent code, `.auirc` snapshot, user
+//     identifiers) are attached at `endSessionRootSpan()` time —
+//     i.e. AFTER the first command's body has run. This is the only
+//     way to capture the .auirc state on an `aui import` that
+//     CREATES the file (auirc.present=false at startup, true at end).
+//
+// Edge cases:
+//   - `aui login` skips this whole flow (it BIRTHS the session;
+//     can't be a child of it).
+//   - `aui logout` clears the session file along with the persisted
+//     span_id, so the next login starts fresh.
+//   - When `AUI_CLI_SESSION_ID` env override is used, we don't
+//     write back to `session.json` (the env is per-invocation
+//     scoped). Each invocation re-emits its own `aui.session` in
+//     that mode — acceptable because the env path is typically
+//     a single sandboxed call from the BFF.
+/**
+ * Read both the session id and the persisted session-root span id
+ * from `~/.aui/session.json`. Sync (hot path) and safe to call
+ * before the rest of the config layer initializes.
+ */
+function readSessionTracingState() {
+    if (process.env.AUI_CLI_SESSION_ID) {
+        return { sessionId: process.env.AUI_CLI_SESSION_ID, fromEnv: true };
+    }
+    try {
+        const home = process.env.AUI_HOME || path.join(os.homedir(), ".aui");
+        const sf = path.join(home, "session.json");
+        if (!fs.existsSync(sf))
+            return { fromEnv: false };
+        const raw = fs.readFileSync(sf, "utf-8");
+        const parsed = JSON.parse(raw);
+        return {
+            sessionId: parsed.cli_session_id,
+            rootSpanId: parsed.cli_session_root_span_id,
+            fromEnv: false,
+        };
+    }
+    catch {
+        return { fromEnv: false };
+    }
+}
+/**
+ * Persist `cli_session_root_span_id` back to `~/.aui/session.json`
+ * so the next CLI invocation can attach to the same root span.
+ *
+ * Best-effort, never throws.
+ *
+ * Two reasons we might bail without persisting:
+ *   1. `session.json` doesn't exist yet (very-first-login mid-flight
+ *      where `saveSession` hasn't run yet — `endSessionRootSpan`
+ *      re-tries after the action body completes).
+ *   2. `AUI_CLI_SESSION_ID` is set AND it doesn't match the
+ *      persisted `cli_session_id`. This is the BFF / sandbox cross-
+ *      session-contamination guard: the user's `~/.aui/session.json`
+ *      belongs to login session X, but the env override pins this
+ *      CLI process to session Z (BFF's own correlator). Writing
+ *      Z's span_id back into the X session would link the user's
+ *      future commands to a span that lives in a different trace.
+ *
+ * The `login` pre-mint case looks like (2) AT START — env=newId,
+ * file=oldId — but `saveSession` writes the new id during login,
+ * so by the time `endSessionRootSpan` calls us, file=newId=env and
+ * persistence happens cleanly.
+ */
+function persistSessionRootSpanId(spanId) {
+    try {
+        const home = process.env.AUI_HOME || path.join(os.homedir(), ".aui");
+        const sf = path.join(home, "session.json");
+        if (!fs.existsSync(sf))
+            return;
+        const raw = fs.readFileSync(sf, "utf-8");
+        const parsed = JSON.parse(raw);
+        const envSessionId = process.env.AUI_CLI_SESSION_ID;
+        if (envSessionId &&
+            typeof parsed.cli_session_id === "string" &&
+            parsed.cli_session_id !== envSessionId) {
+            // Env override points at a DIFFERENT login session than what's
+            // on disk — don't clobber the persisted user session.
+            return;
+        }
+        if (parsed.cli_session_root_span_id === spanId)
+            return;
+        parsed.cli_session_root_span_id = spanId;
+        fs.writeFileSync(sf, JSON.stringify(parsed, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // Non-critical: a stale or missing span_id just means the next
+        // invocation re-emits its own `aui.session`. No data loss.
+    }
+}
+/**
+ * State for this process's session-trace integration.
+ *
+ *   - `sessionRootSpan` is non-null iff WE emitted the `aui.session`
+ *     span in this process (first invocation after login). It's the
+ *     span we'll end at `beforeExit`.
+ *   - `sessionParentContext` is non-null in either case (emitted or
+ *     referenced). It's the OTel `Context` whose active span is the
+ *     session root — `withSessionContext` uses it to wrap
+ *     `program.parse()` so command spans become children.
+ */
+let sessionRootSpan = null;
+let sessionParentContext = null;
+// True when this process is the one that emitted the `aui.session`
+// span via the env-override path (typically `aui login` pre-minting
+// its session id before `session.json` exists). Drives a
+// post-command persistence attempt in `endSessionRootSpan` so the
+// next CLI invocation finds the span id we just emitted.
+let sessionEmittedViaEnvOverride = false;
+/**
+ * Start (or attach to) the `aui.session` root span for this login.
+ *
+ * No-op when:
+ *   - telemetry is disabled (opt-out env vars / NODE_ENV=test)
+ *   - no session id is resolvable from either the env override OR
+ *     `~/.aui/session.json` (the pre-very-first-login path)
+ *
+ * Otherwise:
+ *   - If no `cli_session_root_span_id` is persisted yet (and the id
+ *     came from the file, not env) → emit a real `aui.session` span
+ *     here and persist its span_id immediately.
+ *   - If the id came from the env override (BFF correlation OR the
+ *     `aui login` pre-mint hook in `src/index.ts`) → emit a real
+ *     span; persistence is deferred to `endSessionRootSpan` because
+ *     `session.json` may not exist yet (login hasn't run
+ *     `saveSession` yet).
+ *   - If a `cli_session_root_span_id` is already persisted → build a
+ *     synthetic remote-parent context referencing it. No new span
+ *     emitted.
+ *
+ * Either way, `sessionParentContext` is set and `withSessionContext`
+ * will wrap command actions inside it.
+ *
+ * Call from the CLI entry point right after `initTelemetry(...)`.
+ */
+export async function startSessionRootSpan() {
+    if (sessionParentContext)
+        return;
+    if (!isEnabled())
+        return;
+    const { sessionId, rootSpanId, fromEnv } = readSessionTracingState();
+    if (!sessionId)
+        return;
+    const traceId = uuidToTraceId(sessionId);
+    if (!traceId)
+        return;
+    // Subsequent-invocation path: a session-root span already exists
+    // (emitted by an earlier process under this login). Attach to it
+    // via a synthetic remote-parent context. Skip when the session id
+    // came from the env override — in that mode there's no persisted
+    // file state to consult and the env caller (BFF / login pre-mint)
+    // is the one that wants a fresh span.
+    if (rootSpanId && !fromEnv) {
+        const parentSpanContext = {
+            traceId,
+            spanId: rootSpanId,
+            traceFlags: TraceFlags.SAMPLED,
+            isRemote: true,
+        };
+        sessionParentContext = trace.setSpanContext(ROOT_CONTEXT, parentSpanContext);
+        return;
+    }
+    // Fresh-emit path: this process opens the `aui.session` span as a
+    // true OTel root (parent=null). The custom IdGenerator gives it
+    // the session-derived trace id automatically.
+    try {
+        const tracer = getTracer();
+        const span = tracer.startSpan("aui.session", { attributes: { "cli.session.is_session_root": true } }, ROOT_CONTEXT);
+        sessionRootSpan = span;
+        sessionParentContext = trace.setSpan(ROOT_CONTEXT, span);
+        if (fromEnv) {
+            // `session.json` may not exist yet (the common case: this is
+            // the `aui login` process and `saveSession` hasn't run). Defer
+            // persistence of the span id until `endSessionRootSpan` —
+            // login will have finished by then.
+            sessionEmittedViaEnvOverride = true;
+        }
+        else {
+            persistSessionRootSpanId(span.spanContext().spanId);
+        }
+    }
+    catch {
+        sessionRootSpan = null;
+        sessionParentContext = null;
+    }
+}
+/**
+ * End and flush the `aui.session` root span. Idempotent; only the
+ * process that emitted the span does anything here (subsequent
+ * invocations never had a real span object to end).
+ *
+ * Attributes are attached LAZILY at this point — by now the
+ * command's action has run, so a `.auirc` written by `aui import`
+ * is visible and the agent code resolves cleanly. (Attaching them
+ * at start-of-process would lock the span name to
+ * `aui session: <no agent>` for sessions that begin with an
+ * import.)
+ */
+export async function endSessionRootSpan() {
+    if (!sessionRootSpan)
+        return;
+    const span = sessionRootSpan;
+    const emittedViaEnvOverride = sessionEmittedViaEnvOverride;
+    sessionRootSpan = null;
+    sessionEmittedViaEnvOverride = false;
+    try {
+        await setUserContext(span);
+        await setProjectContext(span);
+        // Friendly name + agent attrs — Logfire renders the name as the
+        // trace title row in the timeline. Read .auirc / session AFTER
+        // the command body has run so this reflects the post-command
+        // state (e.g. `aui import` populating .auirc.agent_code).
+        //
+        // `setSessionAgent()` (called by commands like `import-agent`
+        // that DIRECTLY resolve the agent without needing `.auirc`) may
+        // already have set the span name + attrs more authoritatively.
+        // Spans only let us overwrite attributes — they don't reveal
+        // their current name — so we always call updateName here, but
+        // we check the in-memory `lastSetSessionAgentLabel` first so
+        // commands that pushed a real label win over our fallback.
+        //
+        // Fallback chain (when no agent is resolvable):
+        //   1. user email — usually the most actionable identifier
+        //      shown in Logfire (matches Logfire's user-table joins).
+        //   2. short prefix of the session id — guarantees uniqueness
+        //      and matches the trace id derived from it, so the title
+        //      row is still self-identifying.
+        //   3. literal "aui session" — last resort, only reached when
+        //      neither agent nor user nor session id is available
+        //      (essentially impossible under normal flow).
+        try {
+            const { loadProjectConfig, loadSession } = await import("./config/index.js");
+            const projectConfig = loadProjectConfig();
+            const sess = loadSession();
+            const agentLabel = lastSetSessionAgentLabel ||
+                projectConfig?.agent_code ||
+                sess?.network_name ||
+                projectConfig?.agent_management_id ||
+                projectConfig?.agent_id;
+            let title;
+            if (agentLabel) {
+                title = `aui session: ${agentLabel}`;
+            }
+            else {
+                const sessionId = getCliSessionId();
+                const userLabel = sess?.email || (sessionId ? sessionId.slice(0, 8) : undefined);
+                title = userLabel ? `aui session: ${userLabel}` : "aui session";
+            }
+            span.updateName(title);
+            if (projectConfig?.agent_code) {
+                span.setAttribute("agent.code", projectConfig.agent_code);
+            }
+            if (projectConfig?.agent_id) {
+                span.setAttribute("agent.id", projectConfig.agent_id);
+            }
+            if (sess?.network_name) {
+                span.setAttribute("agent.name", sess.network_name);
+            }
+        }
+        catch {
+            // Cosmetic — never block shutdown on it.
+        }
+        // Persist this span's id so the NEXT CLI invocation under the
+        // same login can attach to it as a remote parent. We only do
+        // this when telemetry pre-minted the session id via the env
+        // override (the `aui login` flow): in the regular file-driven
+        // path the id was already persisted at the start of the run.
+        //
+        // `session.json` should exist by now — `aui login` writes it
+        // BEFORE returning from its action. If it doesn't (login
+        // failed before saving), `persistSessionRootSpanId` is a no-op.
+        if (emittedViaEnvOverride) {
+            persistSessionRootSpanId(span.spanContext().spanId);
+        }
+        span.setStatus({ code: SpanStatusCode.OK });
+        span.end();
+    }
+    catch {
+        // Shutdown must not throw.
+    }
+}
+// ─── Late agent-name attachment from inside a command ─────────────────
+//
+// Some commands (notably `aui import-agent`) BIRTH the project layout
+// — they create `.auirc` in a subdirectory of CWD. By the time the
+// process exits, `findProjectRoot()` from the original CWD doesn't
+// see the freshly-written file (it walks UP from CWD, not down), so
+// `endSessionRootSpan`'s `.auirc`-based name resolution falls back
+// to `<no agent>`. `setSessionAgent` is the explicit hook those
+// commands call once they've resolved the agent, pushing the right
+// name + identifiers onto the session span directly.
+//
+// We also stash the last label set so `endSessionRootSpan`'s
+// `loadProjectConfig`-based fallback doesn't accidentally overwrite
+// a real value with the generic literal — see the agentLabel
+// resolution above.
+let lastSetSessionAgentLabel;
+/**
+ * Push an authoritative agent label onto the `aui.session` root span
+ * for this process. Called by commands that resolve the agent
+ * themselves (e.g. `import-agent` from the backend response). Safe
+ * to call multiple times — last call wins.
+ *
+ * No-op when this process doesn't own the session root span
+ * (subsequent invocations attaching as remote children, opt-out
+ * mode, pre-login).
+ */
+export function setSessionAgent(info) {
+    if (!sessionRootSpan)
+        return;
+    try {
+        const label = info.agentCode ||
+            info.agentName ||
+            info.agentManagementId ||
+            info.agentId ||
+            undefined;
+        if (label) {
+            lastSetSessionAgentLabel = label;
+            sessionRootSpan.updateName(`aui session: ${label}`);
+        }
+        if (info.agentCode)
+            sessionRootSpan.setAttribute("agent.code", info.agentCode);
+        if (info.agentName)
+            sessionRootSpan.setAttribute("agent.name", info.agentName);
+        if (info.agentId)
+            sessionRootSpan.setAttribute("agent.id", info.agentId);
+        if (info.agentManagementId) {
+            sessionRootSpan.setAttribute("agent.management_id", info.agentManagementId);
+        }
+        if (info.versionId)
+            sessionRootSpan.setAttribute("agent.version_id", info.versionId);
+        if (info.versionLabel)
+            sessionRootSpan.setAttribute("agent.version_label", info.versionLabel);
+        if (info.projectRoot)
+            sessionRootSpan.setAttribute("auirc.project_root", info.projectRoot);
+    }
+    catch {
+        // Telemetry must never break the CLI.
+    }
+}
+/**
+ * Run `fn` with the `aui.session` parent context active in OTel.
+ * Every span created inside `fn` — including async callbacks reached
+ * via the AsyncHooks ContextManager `NodeSDK` installs — becomes a
+ * child of `aui.session` (whether that span lives in this process or
+ * was emitted by a previous invocation under the same login).
+ *
+ * No-op (`fn()` directly) when no session parent is resolvable — the
+ * pre-login / logged-out / opted-out path.
+ *
+ * Wrap `program.parse()` with this at the CLI entry point.
+ */
+export function withSessionContext(fn) {
+    if (!sessionParentContext)
+        return fn();
+    return context.with(sessionParentContext, fn);
+}
+// ─── Agent-scope span: per-project grouping inside the session ────────
+//
+// Sister to the session-root span, one level finer-grained: every CLI
+// command that operates on the SAME project (.auirc → same
+// agent_code) gets grouped under a single `agent: <code>` span inside
+// the session trace.
+//
+// Visualisation in Logfire:
+//
+//   aui session: alaam@aui.io
+//   ├── aui.login                    ← (no agent yet)
+//   ├── aui.import                   ← (creates .auirc)
+//   ├── agent: amazon-retail-agent   ← emitted by the next command in
+//   │   ├── aui.pull                   the project; persisted in .auirc
+//   │   ├── aui.validate
+//   │   └── aui.push
+//   ├── aui.import                   ← (different agent project)
+//   ├── agent: another-agent
+//   │   └── aui.push
+//
+// Implementation mirrors the session-root pattern:
+//   - First command in a project (no `cli_agent_span_id` in .auirc)
+//     emits a real `agent: <code>` span and persists its span id.
+//   - Every subsequent command reads the span id and attaches as a
+//     remote child — no new span emitted per process.
+//
+// Persistence is in `.auirc.cli_agent_span_id`. The span id never
+// expires; re-running the CLI on the same project months later still
+// nests new commands under the same agent header.
+let agentRootSpan = null;
+let agentParentContext = null;
+/**
+ * Find the project root from CWD and read enough of `.auirc` to
+ * decide whether to emit / attach an agent-scope span. Sync — we run
+ * this once at CLI startup. Best-effort; returns an empty object on
+ * any I/O / parse error so the caller can no-op.
+ */
+function readAgentTracingState() {
+    try {
+        let dir = process.cwd();
+        let projectRoot;
+        while (dir !== path.dirname(dir)) {
+            if (fs.existsSync(path.join(dir, ".auirc")) ||
+                fs.existsSync(path.join(dir, "agent.aui.json"))) {
+                projectRoot = dir;
+                break;
+            }
+            dir = path.dirname(dir);
+        }
+        if (!projectRoot)
+            return {};
+        const auircPath = path.join(projectRoot, ".auirc");
+        if (!fs.existsSync(auircPath))
+            return { projectRoot };
+        const raw = fs.readFileSync(auircPath, "utf-8");
+        if (!raw.trim())
+            return { projectRoot };
+        const parsed = JSON.parse(raw);
+        return {
+            projectRoot,
+            agentCode: parsed.agent_code,
+            agentSpanId: parsed.cli_agent_span_id,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Persist the agent-scope span id back to the project's `.auirc`.
+ * Reads the current file (whatever else is in there), adds the span
+ * id, writes back. Best-effort; never throws.
+ */
+function persistAgentSpanIdToAuirc(projectRoot, spanId) {
+    try {
+        const auircPath = path.join(projectRoot, ".auirc");
+        if (!fs.existsSync(auircPath))
+            return;
+        const raw = fs.readFileSync(auircPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed.cli_agent_span_id === spanId)
+            return;
+        parsed.cli_agent_span_id = spanId;
+        fs.writeFileSync(auircPath, JSON.stringify(parsed, null, 2) + "\n");
+    }
+    catch {
+        // Non-critical: a stale or missing span id just means the next
+        // invocation re-emits its own `agent:` span. No data loss.
+    }
+}
+/**
+ * Run `fn` with the `agent: <code>` parent context active in OTel.
+ * Every span created inside — typically the command's root span
+ * (`aui.push` / `aui.pull` / `aui.validate` / `aui.import`) — becomes
+ * a child of the agent span.
+ *
+ * Behaviour:
+ *   - No `.auirc` in CWD (or no `agent_code` yet) → no-op, just
+ *     `fn()`. Covers `aui login`, `aui --version`, and the initial
+ *     `aui import-agent` before it has written `.auirc`.
+ *   - `.auirc` present + `cli_agent_span_id` persisted → build a
+ *     synthetic remote-parent context referencing the persisted
+ *     span id (nested under the active session context) and run
+ *     `fn` inside it.
+ *   - `.auirc` present + no `cli_agent_span_id` yet → emit a real
+ *     `agent: <code>` span as child of the active context, persist
+ *     its span id to `.auirc`, run `fn` inside its context.
+ *
+ * Call from the CLI entry point, INSIDE `withSessionContext` so the
+ * agent span becomes a child of the session row.
+ */
+export function withAgentContext(fn) {
+    if (!isEnabled())
+        return fn();
+    if (agentParentContext)
+        return context.with(agentParentContext, fn);
+    const state = readAgentTracingState();
+    if (!state.agentCode || !state.projectRoot)
+        return fn();
+    if (state.agentSpanId) {
+        // Subsequent-invocation path: attach via synthetic remote-parent
+        // context referencing the span emitted by an earlier command in
+        // this project. trace_id is inherited from the active (session)
+        // context — the IdGenerator already pinned it to the session
+        // trace id, so we just point at the agent span id.
+        const activeSpanContext = trace
+            .getSpan(context.active())
+            ?.spanContext();
+        const traceId = activeSpanContext?.traceId;
+        if (!traceId)
+            return fn();
+        const agentSpanContext = {
+            traceId,
+            spanId: state.agentSpanId,
+            traceFlags: TraceFlags.SAMPLED,
+            isRemote: true,
+        };
+        agentParentContext = trace.setSpanContext(context.active(), agentSpanContext);
+        return context.with(agentParentContext, fn);
+    }
+    // Fresh-emit path: this is the first command run inside this
+    // project AFTER it was imported. Emit the `agent: <code>` span as
+    // a child of the active session context, persist its span id, and
+    // wrap `fn` in its context.
+    try {
+        const tracer = getTracer();
+        const span = tracer.startSpan(`agent: ${state.agentCode}`, {
+            attributes: {
+                "cli.agent.is_agent_root": true,
+                "agent.code": state.agentCode,
+                "auirc.project_root": state.projectRoot,
+            },
+        });
+        agentRootSpan = span;
+        agentParentContext = trace.setSpan(context.active(), span);
+        persistAgentSpanIdToAuirc(state.projectRoot, span.spanContext().spanId);
+        return context.with(agentParentContext, fn);
+    }
+    catch {
+        return fn();
+    }
+}
+/**
+ * End the `agent: <code>` root span and flush it through the
+ * exporter. Idempotent; only the process that EMITTED the span has
+ * a real span object to end. Call from the `beforeExit` handler
+ * BEFORE `endSessionRootSpan()` (children-before-parents flush).
+ */
+export function endAgentRootSpan() {
+    if (!agentRootSpan)
+        return;
+    const span = agentRootSpan;
+    agentRootSpan = null;
+    agentParentContext = null;
+    try {
+        span.setStatus({ code: SpanStatusCode.OK });
+        span.end();
+    }
+    catch {
+        // Shutdown must not throw.
+    }
+}
 export async function setUserContext(span) {
     try {
         const { loadSession, loadEnvironment } = await import("./config/index.js");
+        // Session/run identifiers are attached BEFORE the early-return so
+        // that even unauthenticated commands (`aui login`, `aui env`) emit
+        // a per-process `cli.run_id` and the active `cli.command`.
+        span.setAttribute("cli.run_id", cliRunId);
+        span.setAttribute("cli.command", cliCommand);
+        span.setAttribute("cli.invoked_at", cliInvokedAt);
+        span.setAttribute("cli.version", cliVersion);
+        const sessionId = getCliSessionId();
+        if (sessionId) {
+            span.setAttribute("cli.session_id", sessionId);
+            span.setAttribute("cli.session_id_source", process.env.AUI_CLI_SESSION_ID ? "env" : "session_file");
+        }
         const session = loadSession();
         if (!session)
             return;
@@ -98,12 +839,76 @@ export async function setUserContext(span) {
         if (session.organization_name)
             span.setAttribute("user.organization_name", session.organization_name);
         span.setAttribute("user.environment", session.environment || loadEnvironment());
-        span.setAttribute("cli.version", cliVersion);
     }
     catch {
         // non-critical
     }
 }
+// ─── .auirc snapshot ──────────────────────────────────────────────────
+//
+// Sister helper to `setUserContext` / `setAgentContext` — attaches the
+// resolved `.auirc` file contents to a span as `auirc.<field>` so
+// Logfire shows exactly what the CLI was working from on disk. Useful
+// when "the same push works for me but fails for them" — usually a
+// stale `agent_management_id`, missing `version_id`, or a mismatched
+// `scope_level` in `.auirc`.
+//
+// Secret-bearing keys (currently only `network_api_key`) are emitted
+// with a `***REDACTED***` placeholder so dashboards still show "the
+// key WAS set" without exposing its value.
+//
+// Best-effort: never throws. If `.auirc` is missing / unreadable, we
+// just attach `auirc.present=false` and move on.
+const AUIRC_REDACTED_KEYS = new Set([
+    "network_api_key",
+]);
+/**
+ * Attach a redacted `.auirc` snapshot to a span. Call after
+ * `setUserContext` on every top-level command span (push, pull,
+ * import-agent, validate) so a single Logfire row shows the on-disk
+ * project state alongside who ran it and against which agent.
+ */
+export async function setProjectContext(span, projectRoot) {
+    try {
+        const { loadProjectConfig, findProjectRoot } = await import("./config/index.js");
+        const root = projectRoot || findProjectRoot() || undefined;
+        const projectConfig = loadProjectConfig(root);
+        if (!projectConfig) {
+            span.setAttribute("auirc.present", false);
+            return;
+        }
+        span.setAttribute("auirc.present", true);
+        if (root)
+            span.setAttribute("auirc.project_root", root);
+        for (const [key, value] of Object.entries(projectConfig)) {
+            if (value === undefined || value === null)
+                continue;
+            const attrKey = `auirc.${key}`;
+            if (AUIRC_REDACTED_KEYS.has(key)) {
+                // Stamp presence-only so dashboards can filter "had an api key
+                // set" without ever shipping the value off the user's machine.
+                span.setAttribute(attrKey, "***REDACTED***");
+                continue;
+            }
+            if (typeof value === "string" ||
+                typeof value === "number" ||
+                typeof value === "boolean") {
+                span.setAttribute(attrKey, value);
+            }
+            else {
+                try {
+                    span.setAttribute(attrKey, JSON.stringify(value));
+                }
+                catch {
+                    // Non-serialisable value (cyclic ref) — skip without breaking.
+                }
+            }
+        }
+    }
+    catch {
+        // .auirc is informational telemetry — never break a command.
+    }
+}
 /**
  * Attach agent-scoped identifiers to a span. Use alongside `setUserContext`
  * on per-task push spans so a single Logfire row tells the on-call exactly:
@@ -151,4 +956,5 @@ export async function setAgentContext(span, ctx) {
     }
 }
 export { SpanStatusCode };
+export { trace };
 //# sourceMappingURL=telemetry.js.map