Skip to content

Add cliInitMs to session_start event for CLI startup observability #44

@byapparov

Description

@byapparov

Problem

When measuring task executor launch latency end-to-end, we need to know how long the aictrl CLI itself takes to initialise — from process start to "ready to send the first instruction to the model". Currently the only timing signal we have post-startup is session_start, but it has no duration field, so consumers (the executor entrypoint, BigQuery dashboards) can't compute CLI startup overhead.

The session_start event is emitted at packages/cli/src/cli/cmd/run.ts:671, which fires after:

  • Bun runtime + import graph load
  • yargs handler entered
  • bootstrap()InstanceBootstrap() (Plugin.init, LSP.init, FileWatcher.init, etc.)
  • Session create / fork / share

…and before the first prompt dispatch (sdk.session.prompt()). That's exactly the boundary we want for "CLI ready". We just can't currently measure how long getting there took.

Why it matters

We're trying to drive task executor launch latency toward <1s aspirationally. Today P50 launch is ~104s (Cloud Run Jobs gen2 microVM boot dominates), and once we eliminate the cold-start path, the next bottleneck will likely be CLI startup. We need this number to (a) baseline it, (b) decide whether Bun import time / plugin init is worth optimising, (c) track regressions over time.

Proposed change

  1. Capture a process-start timestamp at the very top of the CLI entry point (before any other imports if practical, or as the first statement in the entry script).
  2. Add a cliInitMs field to the session_start event payload, computed as Date.now() - processStartTime.
  3. Update EVENTS.md to document session_start semantics precisely:

    Fires after plugin/LSP/session initialisation, before the first prompt dispatch — represents the moment the CLI is ready to send the first instruction to the model. cliInitMs measures process start → this event.

Acceptance criteria

  • session_start NDJSON event contains a numeric cliInitMs field
  • cliInitMs accurately reflects time from process start to event emission (verifiable by manual timing)
  • EVENTS.md documents the boundary session_start represents and the meaning of cliInitMs
  • No measurable performance regression from adding the timestamp capture

Files

  • packages/cli/src/cli/cmd/run.ts — line 671 emit call
  • The CLI entry point file (top of process) — capture timestamp
  • EVENTS.md — documentation update

Out of scope

  • Optimising Bun import time / plugin init (separate investigation, gated on having this measurement)
  • Measuring time after session_start (first model token, etc.) — that's user workload, not CLI startup

Related

  • aictrl-dev/aictrl#883 — Bootstrap bundle caching (executor side)
  • aictrl-dev/aictrl#895 — Tiered bootstrap (executor side)
  • A companion executor-side instrumentation issue will be filed in aictrl-dev/aictrl that consumes cliInitMs from this event.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions