Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

21.2 KB
Raw Blame
import { AUTOMATIC_POLL_ACTIONS, HEALTH_FAILURES, HEALTH_MEASURES, RESUME_PREPARATION_KINDS, type HealthSource, type ResumeReason } from './productHealthContract.js'
import type { MessageOutcome, MessageReceipt } from './sessionInput.js'
import { LAUNCH_ERROR_CODES, PRODUCT_USAGE_FLOWS, PRODUCT_USAGE_LAUNCH_ENGINES, PRODUCT_USAGE_USER_OPENED_ACTIONS, STORE_ERROR_CODES,
  type LaunchErrorCode, type ProductUsageLaunchEngine, type ProductUsageMetric, type StoreErrorCode } from './productUsageContract.js'

const actions = { agent_create: 'create', agent_resume: 'resume', agent_restart: 'restart',
  agent_retarget: 'model_change', agent_recent: 'history',
  agent_fork: 'fork', agent_close: 'close', agent_delete: 'delete',
  session_search: 'search', session_tail: 'history_page',
  dsh_list: 'store_list', dsh_install: 'store_install', dsh_update: 'store_update', dsh_remove: 'store_remove',
  models_list: 'model_list', grid_models_list: 'model_list',
  grid_fleet_model_download: 'model_download', grid_fleet_model_start: 'model_start', grid_fleet_model_stop: 'model_stop',
  browser_open: 'browser_open',
} as const
const unmeasured = (..._args: unknown[]): void => {}
const setup = new Set(['TMUX_UNAVAILABLE', 'PTY_HOST_UNAVAILABLE', 'TMUX_TOO_OLD_FOR_DSH', 'TMUX_TOO_OLD_FOR_GRID',
  'ENGINE_UNAVAILABLE', 'NATIVE_LAUNCH_HELD', 'DSH_MATERIALIZE_FAILED', 'SWARM_SKILL_FAILED', 'SPAWN_FAILED', 'REGISTRATION_FAILED', 'GRID_CONFIG_FAILED'])
const auth = new Set(['UNAUTHORIZED', 'AUTH_REQUIRED', 'LOGIN_REQUIRED', 'OWNER_REQUIRED', 'E2EE_REQUIRED'])
const unavailable = new Set(['SERVICE_UNAVAILABLE', 'SERVICE_FAILED', 'GRID_UNAVAILABLE', 'API_UNAVAILABLE',
  'UNSUPPORTED', 'UNSUPPORTED_ON_REMOTE', 'TIMEOUT', 'NATIVE_UNAVAILABLE', 'SWARM_ROLE_UNAVAILABLE'])
// A history page read for no session, or one this computer's index does not hold (services/search.ts): until
// 2026-10-28 both were `other`, 2,225 that day, a Desktop list re-reading a conversation that had left the index.
const invalid = new Set(['INVALID_ENGINE', 'INVALID_CWD', 'CWD_NOT_FOUND', 'INVALID_GRID', 'INVALID_DSH', 'INVALID_SWARM_ROLE',
  'INVALID_MODEL', 'INVALID_PERMISSION_MODE', 'INVALID_LAUNCH_ARGS', 'INVALID_CREATION_ID', 'INVALID_PROJECT_SOURCE', 'WORKTREE_BUSY',
  'BAD_SESSION', 'NOT_INDEXED'])
/** A Store install's or update's own refusals (dsh/install.ts, dsh/update.ts), by kind. Until 2026-10-28 every one was
 * `other`: that day's 11 failed installs, all on Windows, said nothing of why. For the Store's requests only, so a
 * create's or a resume's totals keep their meaning. Its busy and not-installed refusals are named with the others'. */
const storeFailures = new Map<string, Failure>([
  ['SETUP_FAILED', 'setup'], ['DOCTOR_FAILED', 'setup'], ['GIT_UNAVAILABLE', 'setup'], ['SHELL_UNAVAILABLE', 'setup'],
  ['CLONE_FAILED', 'unavailable'], ['VIEWER_UNAVAILABLE', 'unavailable'],
  ['INVALID_MANIFEST', 'invalid'], ['INVALID_SOURCE', 'invalid'], ['SOURCE_NOT_FOUND', 'invalid'],
  ['PACKAGE_ID_MISMATCH', 'invalid'], ['PACKAGE_KIND_MISMATCH', 'invalid'], ['LINKED_INSTALL', 'invalid'],
  ['BUNDLED_PACKAGE', 'invalid'],
])
const resumeReasons = new Map<string, ResumeReason>([
  ['TMUX_UNAVAILABLE', 'runtime_unavailable'], ['NATIVE_LAUNCH_HELD', 'runtime_unavailable'],
  ['ENGINE_UNAVAILABLE', 'runtime_unavailable'],
  ['AGENT_NOT_FOUND', 'saved_state_missing'], ['RESUME_UNAVAILABLE', 'saved_state_missing'],
  ['CWD_NOT_FOUND', 'project_missing'], ['INVALID_DSH', 'harness_missing'],
  ['GRID_CREDENTIAL_REQUIRED', 'credentials_missing'], ['AUTH_REQUIRED', 'credentials_missing'],
  ['AGENT_BUSY', 'busy'], ['WORKTREE_BUSY', 'busy'], ['PERMISSION_CHANGE_REQUIRES_STOP', 'busy'],
  ['AGENT_CHANGED', 'changed'], ['RESUME_UNCONFIRMED', 'unconfirmed'],
  ['RESUME_PREPARATION_FAILED', 'preparation_failed'], ['RESUME_FAILED', 'launch_failed'],
  ['INVALID_PERMISSION_MODE', 'invalid'], ['INVALID_CREATION_ID', 'invalid'],
  // Codes a resume reply carries that fell to `other` (production counters, 2026-10-16): the engine of a resumed
  // harness that did not start (lib/restoreAgents.ts), a resume while the harness is being deleted (backendSocket.ts)
  // and a request that named no harness.
  ['ENGINE_DID_NOT_START', 'launch_failed'], ['ENGINE_NOT_INSTALLED', 'launch_failed'], ['START_TIMEOUT', 'launch_failed'],
  ['DELETE_IN_PROGRESS', 'busy'], ['MISSING_AGENT_ID', 'invalid'],
])

type Failure = 'setup' | 'auth' | 'unavailable' | 'invalid' | 'other'
/** The fixed kind of a refusal; exported for the guard that keeps every code of core/agents named somewhere. */
export function failureKind(error: unknown): Failure {
  return typeof error !== 'string' ? 'other' : setup.has(error) ? 'setup' : auth.has(error) ? 'auth'
    : unavailable.has(error) ? 'unavailable' : invalid.has(error) ? 'invalid' : 'other'
}
const listedCodes = new Set<string>(LAUNCH_ERROR_CODES.filter(code => code !== 'unlisted' && code !== 'none'))
/** Which listed code an `other` refusal had (`LAUNCH_ERROR_CODES`): the daemon's own name lower-cased, `unlisted`
 * for any other string and `none` for no code at all. Only a name from the fixed list leaves here. */
export function launchErrorCode(error: unknown): LaunchErrorCode {
  if (typeof error !== 'string') return 'none'
  const code = error.length <= 64 ? error.toLowerCase() : ''
  return listedCodes.has(code) ? code as LaunchErrorCode : 'unlisted'
}
const storeCodes = new Set<string>(STORE_ERROR_CODES.filter(code => code !== 'unlisted' && code !== 'none'))
/** Which listed code a Store install's or update's refusal had (`STORE_ERROR_CODES`), as `launchErrorCode` names a
 * launch's: the code lower-cased, `unlisted` for any other string and `none` for no code. Nothing else leaves here. */
export function storeErrorCode(error: unknown): StoreErrorCode {
  if (typeof error !== 'string') return 'none'
  const code = error.length <= 64 ? error.toLowerCase() : ''
  return storeCodes.has(code) ? code as StoreErrorCode : 'unlisted'
}
/** The engine a launch asked for, as one of the fixed names. */
export function launchEngine(engine: unknown): ProductUsageLaunchEngine {
  return (PRODUCT_USAGE_LAUNCH_ENGINES as readonly unknown[]).includes(engine) ? engine as ProductUsageLaunchEngine : 'other'
}
/** A create turned down because the request was wrong, not because Harness failed: opening a conversation that is
 *  already a harness or open elsewhere (core/agents/adopt.ts), a cloud agent with no task or repository
 *  (cloud/service.ts). The Oct 26 report counted them as launch failures. */
export const LAUNCH_REFUSALS: ReadonlySet<string> = new Set(['SESSION_IN_HARNESS', 'SESSION_OPEN_ELSEWHERE', 'SESSION_OPEN_IN_TERMINAL',
  'SESSION_BUSY_IN_TERMINAL', 'INVALID_REQUEST'])
export interface ProductUsageLaunchSignal {
  /** Local RAM only, discarded on stop/choice change; never part of a report or persisted queue. */
  id: string
  phase: 'start' | 'pending' | 'created' | 'failed' | 'refused' | 'cancelled' | 'unconfirmed' | 'work_requested'
  /** On `start`: an agent or a Swarm asked for this launch (the create's `startedBy`), not a person. */
  agentStarted?: true
  origin?: 'interactive' | 'tool'
  failure?: Failure
  /** The listed code of an `other` or setup failure, of a refusal, or of a created launch's late one (`late`). */
  code?: LaunchErrorCode
  wait?: 'install' | 'model' | 'native' | 'other'
  /** The engine a new launch asked for (`start`), as a fixed name: an installation's first launch counts it. */
  engine?: ProductUsageLaunchEngine
  /** The agent a created launch made, still starting: local RAM only, like `id`, so that the gateway can tell its
   *  start failing later (core/agents/newPane.ts) from the agent's other frames. */
  agent?: string
  /** A created launch whose start had already failed when the reply that said so was read (a status poll). */
  late?: true
}

/** A created launch, as its reply's agent frame shows it: still starting (watched by its agent), already
 *  failed (`late`), or ready. The frame is read here and nothing of it but those leaves. */
function createdSignal(agent: unknown): Omit<ProductUsageLaunchSignal, 'id'> {
  const frame = agent && typeof agent === 'object' ? agent as { id?: unknown; launch?: { state?: unknown; error?: unknown } } : null
  const launch = frame?.launch && typeof frame.launch === 'object' ? frame.launch : null
  if (launch?.state === 'failed') return { phase: 'created', late: true, code: launchErrorCode(launch.error) }
  const id = frame?.id
  return { phase: 'created', ...(typeof id === 'string' && id.length > 0 && id.length <= 256 && launch?.state !== 'ready' ? { agent: id } : {}) }
}

/** Observe an actual new-harness receipt through subsequent status polls. Polling adds no attempts.
 * [engine] is the request's `engine`; the reply's [agent] is its agent frame, or whether it had one.
 * [agentStarted]: the create says an agent started it (`startedBy: 'agent'`). */
export function productUsageLaunch(type: string, id: unknown, emit: (signal: ProductUsageLaunchSignal) => void, engine?: unknown, agentStarted = false) {
  const known = ['agent_create', 'agent_create_status', 'agent_create_cancel'].includes(type)
    && typeof id === 'string' && /^[a-zA-Z0-9_-]{16,96}$/.test(id)
  if (!known) return unmeasured
  const send = (signal: Omit<ProductUsageLaunchSignal, 'id'>) => {
    if (known) { try { emit({ id: id as string, ...signal }) } catch { /* Optional measurement. */ } }
  }
  if (type === 'agent_create') send({ phase: 'start', engine: launchEngine(engine), ...(agentStarted ? { agentStarted: true } : {}) })
  return (error: unknown, state: unknown, agent: unknown, held: unknown) => {
    if (typeof error === 'string' && LAUNCH_REFUSALS.has(error)) send({ phase: 'refused', code: launchErrorCode(error) })
    else if (error != null || state === 'failed') {
      const failure = failureKind(error)
      send({ phase: 'failed', failure, ...(failure === 'other' || failure === 'setup' ? { code: launchErrorCode(error) } : {}) })
    }
    else if (state === 'created' || agent) send(createdSignal(agent))
    else if (state === 'pending') send({ phase: 'pending', wait: held === 'install' ? 'install' : held === 'models' ? 'model' : held === 'native' ? 'native' : 'other' })
    else if (state === 'cancelled') send({ phase: 'cancelled' })
    else if (state === 'unconfirmed' || state === 'unavailable' || state === 'missing') send({ phase: 'unconfirmed' })
  }
}

/** Who sent a request, as the counters name it: a tool on this computer, an app here, or a remote app
 * client — the browser, or the phone. Over the relay both are the same E2EE `web` role, so the phone says
 * which it is in the payload (`usageSurface: 'phone'`, as it says `userAction`); a remote frame with no
 * such word is the browser's or an older phone's, counted as `app` as before. */
export function productUsageSource(local: boolean, tool: boolean, role: string | null, payload: unknown): HealthSource {
  if (local) return tool ? 'tool' : 'app'
  if (role !== 'web') return 'unknown'
  return (payload as { usageSurface?: unknown } | undefined)?.usageSurface === 'phone' ? 'phone' : 'app'
}

/** Reduce an RPC at its existing boundary. Only fixed counter names leave this helper.
 * No request, reply, error message, path, agent name or identifier is handed to the collector.
 * A pending durable launch is an acknowledgement, never a successful launch. Status polling is
 * excluded: counting each poll as a launch would turn a slow install into hundreds of attempts.
 * [userAction] is the app saying a person opened the list (the Store, a model list); the same request
 * from a refresh, a probe or a picker carries none, and only the flagged one counts toward reach.
 */
export function productUsageRequest(type: string, emit: (metric: ProductUsageMetric) => void, now = Date.now, source?: HealthSource, userAction = false) {
  const action = type === 'message' ? 'message' : Object.hasOwn(actions, type) ? actions[type as keyof typeof actions] : null
  // In particular, streaming frames and polling do not allocate clocks or observers.
  if (!action) return unmeasured
  const started = now()
  let answered = false
  // A fixed poll is `automatic` whichever app makes it, the phone's included: its own source is for what a
  // person on it asked for.
  const origin = (source === 'app' || source === 'phone') && (AUTOMATIC_POLL_ACTIONS as readonly string[]).includes(action)
    ? 'automatic' : source
  // `automatic` is every app's polls, the Desktop's and the phone's together: the phone's are counted again, apart.
  const phonePoll = source === 'phone' && origin === 'automatic'
  const count = (measure: string) => { if (action && action !== 'message') { try { emit(`${action}_${measure}` as ProductUsageMetric) } catch { /* Optional measurement. */ } } }
  const detail = (measure: string) => {
    if (!source) return
    try { emit(`request_${origin}_${action}_${measure}` as ProductUsageMetric) } catch { /* Optional measurement. */ }
    if (phonePoll) { try { emit(`request_phone_automatic_${action}_${measure}` as ProductUsageMetric) } catch { /* Optional measurement. */ } }
  }
  count('requests'); detail('started')
  if (userAction && (PRODUCT_USAGE_USER_OPENED_ACTIONS as readonly string[]).includes(action)) count('user_requests')
  // [failure]: the kind of a refusal its caller already knows (a message's, [messageReceipt]), not read off a code.
  // [preparation]: the reply's `reason` — for a resume whose history could not be prepared, which check refused it.
  return (error: unknown, state: unknown, hasAgent: boolean, ok?: unknown, failure?: typeof HEALTH_FAILURES[number], preparation?: unknown) => {
    if (!action || answered) return
    answered = true
    if (action === 'resume' && (error != null || ok === false || ['failed', 'cancelled', 'unconfirmed', 'unavailable'].some(value => state === value))) {
      const reason = typeof error === 'string' ? resumeReasons.get(error) : undefined
      detail(`reason_${reason ?? (state === 'unconfirmed' ? 'unconfirmed' : 'other')}`)
      // Only a name from the fixed list leaves here: a kind this build does not know is `other`.
      if (reason === 'preparation_failed' && preparation !== undefined) {
        detail(`preparation_${(RESUME_PREPARATION_KINDS as readonly unknown[]).includes(preparation) ? preparation : 'other'}`)
      }
    }
    // A runtime we cannot verify is unknown; a harness changed during the request is cancelled.
    // Neither proves a launch failure. Older clients classified these two codes as failures.
    if (action === 'resume' && (state === 'unconfirmed' || error === 'RESUME_UNCONFIRMED' || error === 'AGENT_CHANGED')) {
      count('unknown'); detail(error === 'AGENT_CHANGED' ? 'cancelled' : 'unknown')
    } else if (error != null || state === 'failed' || ok === false) {
      count('failed'); detail('failed')
      const store = action === 'store_install' || action === 'store_update'
      const kind = (store && typeof error === 'string' ? storeFailures.get(error) : undefined) ?? failureKind(error)
      count(`error_${kind}`)
      // Which code an `other` refusal of a create or a resume had: 22 creates and 9 resumes were `other` on
      // 2026-10-16 (production counters), with nothing to say why. A fixed name from the list, or unlisted.
      if (kind === 'other' && (action === 'create' || action === 'resume')) count(`error_code_${launchErrorCode(error)}`)
      // The 2026-10-21 setup spike (10 failed launches, 4 phone creates) named no prerequisite. These new
      // families preserve the old `other`-by-code totals and keep the phone's creates apart from Desktop's.
      if (kind === 'setup' && action === 'create') {
        const code = launchErrorCode(error)
        count(`error_setup_code_${code}`)
        if (origin === 'phone') {
          try { emit(`phone_create_error_setup_code_${code}` as ProductUsageMetric) } catch { /* Optional measurement. */ }
        }
      }
      // A delete's or a restart's, whatever its kind: the phone's 3 delete refusals were `other` and its 2 restart
      // refusals `setup` on 2026-10-19, a kind of nine codes, with nothing to say which.
      if (action === 'delete' || action === 'restart') {
        count(`error_code_${launchErrorCode(error)}`)
        // The phone's again, apart: the family above mixes every client of this daemon.
        if (origin === 'phone') {
          try { emit(`phone_${action}_error_code_${launchErrorCode(error)}` as ProductUsageMetric) } catch { /* Optional measurement. */ }
        }
      }
      // A Store install's or update's, whatever its kind: the 11 Windows installs of 2026-10-28 were `other`, and
      // nothing said which refusal. Its family adds up to `store_install_failed` (or `store_update_failed`).
      if (store) count(`error_code_${storeErrorCode(error)}`)
      detail(`error_${failure ? failure : error === 'TIMEOUT' ? 'timeout' : typeof error === 'string' && ['AGENT_NOT_FOUND', 'SESSION_NOT_FOUND', 'NOT_FOUND', 'NOT_INSTALLED', 'NOT_INDEXED'].includes(error) ? 'not_found' : typeof error === 'string' && ['DELETE_IN_PROGRESS', 'WORKTREE_BUSY', 'BUSY', 'DSH_BUSY'].includes(error) ? 'conflict' : kind}`)
    } else if (state === 'pending' || state === 'preparing' || state === 'starting') { count('pending'); detail('pending') }
    else if (state === 'unconfirmed' || state === 'unavailable' || state === 'cancelled') { count('unknown'); detail(state === 'cancelled' ? 'cancelled' : 'unknown') }
    else if (!['create', 'resume', 'restart', 'fork'].includes(action) || hasAgent || state === 'created') { count('ok'); detail('ok') }
    else { count('unknown'); detail('unknown') }
    const elapsed = Math.max(0, now() - started)
    count(elapsed < 1000 ? 'under_1s' : elapsed < 10_000 ? '1s_to_10s' : elapsed < 60_000 ? '10s_to_1m' : 'over_1m')
  }
}

/** Each refusal of a person's message by the kind the person was told (lib/sessionInput.ts `MessageOutcome`). */
const messageFailures = {
  agent_gone: 'not_found', runtime_gone: 'unavailable', held: 'conflict', withheld: 'conflict', queue_full: 'conflict',
  not_submitted: 'timeout', queue_expired: 'timeout', invalid: 'invalid', paste_failed: 'other',
} as const satisfies Partial<Record<MessageOutcome, typeof HEALTH_FAILURES[number]>>

/**
 * A person's message measured by what became of it: until 2026-10-20 a `message` request had its `started` and
 * nothing more, as nothing answers it (2026-10-19: 14 from the phone). `ok` once its engine took it, `failed` by
 * the kind of what the person was told, `unknown` typed and never confirmed, `cancelled` stopped by the person.
 * The request's own counters only (`request_<source>_message_<result>`): no text, agent or reason leaves here.
 */
export function messageReceipt(measured: ReturnType<typeof productUsageRequest>): MessageReceipt {
  return (outcome) => {
    if (outcome === 'started' || outcome === 'taken') measured(undefined, undefined, false)
    else if (outcome === 'cancelled') measured(undefined, 'cancelled', false)
    else if (outcome === 'ambiguous' || outcome === 'prompt_mismatch' || outcome === 'turn_ended') measured(undefined, 'unconfirmed', false)
    else measured(undefined, 'failed', false, undefined, messageFailures[outcome])
  }
}

/** Explicit composer intent only. Never infer a human from keystrokes, text or an open window. */
export function productUsageIntent(type: string, intent: unknown, agent: unknown, source: HealthSource, emit: (signal: ProductUsageLaunchSignal) => void): void {
  if (type !== 'message' || typeof agent !== 'string' || !agent || agent.length > 256) return
  try {
    // A person's composer is interactive work on the phone as in any app.
    if ((source === 'app' || source === 'phone') && intent === 'interactive') emit({ id: agent, phase: 'work_requested', origin: 'interactive' })
    else if (source === 'tool') emit({ id: agent, phase: 'work_requested', origin: 'tool' })
  } catch { /* Optional observation cannot block a message. */ }
}

const OBSERVED_OUTCOMES = ['ok', 'failed', 'cancelled', 'unknown']
/**
 * hn's own observation (`product_observe`), reduced to the counters the Desktop's `begin()` and
 * `milestone()` count, each when it happens: `{flow}` is a flow's start, `{flow, outcome, durationMs}`
 * its outcome and duration bucket, `{measure}` one health measure. Anything else — an unknown name,
 * a bad duration, a field more or less than its shape has — is nothing, so no label, text or number
 * of hn's own becomes a counter.
 */
export function productObservation(payload: unknown): ProductUsageMetric[] {
  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return []
  const p = payload as Record<string, unknown>
  const fields = Object.keys(p).sort().join()
  if (fields === 'measure') {
    return typeof p.measure === 'string' && (HEALTH_MEASURES as readonly string[]).includes(p.measure)
      ? [`health_tui_${p.measure}` as ProductUsageMetric] : []
  }
  if (typeof p.flow !== 'string' || !(PRODUCT_USAGE_FLOWS as readonly string[]).includes(p.flow)) return []
  const prefix = `ui_tui_${p.flow}_`
  if (fields === 'flow') return [`${prefix}started` as ProductUsageMetric]
  if (fields !== 'durationMs,flow,outcome' || typeof p.outcome !== 'string' || !OBSERVED_OUTCOMES.includes(p.outcome)
      || typeof p.durationMs !== 'number' || !Number.isFinite(p.durationMs) || p.durationMs < 0) return []
  const ms = p.durationMs
  return [`${prefix}${p.outcome}`,
    `${prefix}${ms < 1000 ? 'under_1s' : ms < 10_000 ? '1s_to_10s' : ms < 60_000 ? '10s_to_1m' : 'over_1m'}`] as ProductUsageMetric[]
}