What changed, release by release.

Resolves milliseconds since the epoch, now.

() => number() => Promise<number>

Returns the context window's fill, the rate-limit windows and the cost, as the status line has them; with breakdown, by category too.

() => Promise<SessionUsage>(args?: SessionUsageArgs) => Promise<SessionUsage>

The argument of $.session.usage({ breakdown, columns }).

NoArgsSessionUsageArgs

The Box props a hover may override, none of which moves layout, and scope, which names the hover group the Box joins instead of a style.

export type BoxHoverProps = {    scope?: string;    borderStyle?: string;    borderColor?: string;    borderDimColor?: boolean;

The props of Button, every surface's pressable leaf: an address, a label, the closure a press runs, and the label styles a hover overrides.

    key?: string;    label?: string;    hotkey?: string;    action?: string;    plain?: true;    dimColor?: boolean;    autoFocus?: true;    hover?: TextHoverProps;    onPress: () => void;};

The element table a surface module draws with, surface.elements: the terminal's (Elements) less Client (none nests) and Raster (needs $).

export type ClientElements = Omit<Elements['terminal'], 'Client'>;export type ClientElements = Omit<Elements['terminal'], 'Client' | 'Raster'>;

command.run's input as a plugin's $.command.run takes it: args may be left out (/command, bare); origin and presentation the engine sets.

export type CommandRunArgs = Omit<CommandRunInput, 'origin' | 'args'> & {export type CommandRunArgs = Omit<CommandRunInput, 'origin' | 'args' | 'presentation'> & {    args?: string;};

The input of command.run: one slash command about to run, the way the person typed it (/name args), and where the run came from.

    command: string;    args: string;    origin: PromptOrigin;    presentation: CommandPresentation;};

The element constructors each surface draws, by e.surface: what $.ui.resolve(e) returns and a ui.resolve hook passes on; no globals.

        Link: ElementConstructor<LinkProps>;        Code: ElementConstructor<CodeProps>;        Client: ElementConstructor<ClientProps>;        Raster: ElementConstructor<RasterProps>;    };    desktop: {        Box: ElementConstructor<BoxProps>;

The engine's own events as calls on $, one signature each: $.<noun>.<event>(input) resolves to its result, or to its stream.

    ui: {        render: <C extends RenderComponent>(input: RenderInput<C>) => Promise<RenderElement>;        resolve: <E extends ResolveInput>(e: E) => Elements[E['surface']];        scroll: (input: UiScrollArgs) => Promise<UiScrollResult>;        focus: (input: UiFocusArgs) => Promise<UiFocusResult>;    };};

The props of Input, every surface's one-line text field: an address, optional texts, and the closures a change and a submit run. A leaf.

    placeholder?: string;    value?: string;    submitLabel?: string;    autoFocus?: true;    onInput?: (value: string, e: UiInputArgument) => void;    onSubmit: (value: string, e: UiInputArgument) => void;};

What each call on $ answers (the value of its event's result), by event name.

    'ui.invalidate': void;    'ui.open': void;    'ui.close': void;    'ui.blit': UiBlitResult;    'fs.read': string;    'fs.write': void;    'fs.list': FsEntry[];…    'store.set': void;    'store.delete': void;    'store.keys': string[];    'clock.now': number;    'clock.sleep': void;    'clock.after': void;    'clock.every': void;    'http.fetch': HttpResponse;    'process.run': ProcessRunResult;    'settings.read': Settings;

The argument of $.ui.open: which pane, its title, whether it asks the person's keyboard, its dialog manners, and the rows it wants inline.

    id: string;    title?: string;    focus?: true;    closeOnEscape?: true;    holdToasts?: true;    rows?: number;};

Everything ui.render can draw: one name per component that has a render site; a matcher narrows on it.

export type RenderComponent = 'AskUserQuestion' | 'UserMessage' | 'AssistantMessage' | 'ToolUse' | 'ToolResult' | 'ToolGroup' | 'Spinner' | 'TurnDuration' | 'InfoNotice' | 'SessionMode' | 'PromptHint' | 'AbovePrompt' | 'Pane';export type RenderComponent = 'AskUserQuestion' | 'UserMessage' | 'AssistantMessage' | 'ToolUse' | 'ToolResult' | 'ToolGroup' | 'CommandOutput' | 'Spinner' | 'TurnDuration' | 'InfoNotice' | 'SessionMode' | 'PromptHint' | 'AbovePrompt' | 'Pane';

What a render hook returns, and what next(e) resolves to: a plain-data tree of elements (a Box or Text is a StyledElement), strings as children.

export type RenderElement = {    type: 'Box';    props?: Record<string, string | number | boolean>;    hover?: BoxHoverProps;    children?: RenderNode[];} | {    type: 'Text';    props?: Record<string, string | number | boolean>;    hover?: TextHoverProps;    children?: RenderNode[];} | {export type RenderElement = StyledElement<'Box', BoxHoverProps> | StyledElement<'Text', TextHoverProps> | {    type: 'Button';    props: {        key: string;        label: string;        hotkey?: string;        action?: string;        plain?: true;        dimColor?: TextProps['dimColor'];        autoFocus?: true;    };    press: {        plugin: string;…        placeholder?: string;        value?: string;        submitLabel?: string;        autoFocus?: true;    };    press: {        plugin: string;…        label?: string;        options: readonly SelectOption[];        value?: string;        autoFocus?: true;    };    press: {        plugin: string;…    props: SvgProps;    children?: undefined;} | {    type: 'Raster';    props: RasterProps;    raster: {        plugin: string;    };    children?: undefined;} | {    type: 'engine';    ref: number;};

The plain-data props of each renderable component, as ui.render sees them under e.props; a hook rewrites them with next({ ...e, props }).

        isActive: boolean;        isExpanded: boolean;    };    CommandOutput: {        command: string;        args: string;        text: string;        isErrored: boolean;    };    Spinner: {        word: string;        message: string | null;…        hasSurvey: boolean;        isWorking: boolean;        maxRows: number;        bodyColumns: number;        scroll: SiteScroll;        view: SiteView;    };    Pane: {        title: string;…        bodyColumns: number;        placement: 'dock' | 'inline';        scroll: SiteScroll;        view: SiteView;    };};

The props of Select, every surface's one-of-several picker: an address, a label, the options, the one selected, the closure a pick runs. A leaf.

    label?: string;    options: readonly SelectOption[];    value?: string;    autoFocus?: true;    onSelect: (value: string, e: UiSelectArgument) => void;};

The live context window as the status line reads it, and by category as /context breaks it down when the call asked ({ breakdown }).

    tokens?: number;    window: number;    percent?: number;    breakdown?: SessionContextBreakdown;};

The Text props a hover may override (its colors and styles, not its wrapping) and scope, the hover group it joins; a Button's label too.

export type TextHoverProps = {    scope?: string;    color?: string;    backgroundColor?: string;    dimColor?: boolean;

The input of turn.step: one model request inside a turn, at the moment the engine is about to send it; the bottom of the chain sends it.

    model: string;    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number;    messageCount: number;    agentId?: string;};

agent.spawn's input as the call takes it: what the Agent tool's caller says; the engine fills the rest.

export type AgentSpawnArgs = Pick<AgentSpawnInput, 'prompt'> & Partial<Pick<AgentSpawnInput, 'description' | 'subagentType' | 'model' | 'name' | 'cwd' | 'background'>>;export type AgentSpawnArgs = Pick<AgentSpawnInput, 'prompt'> & Partial<Pick<AgentSpawnInput, 'description' | 'subagentType' | 'model' | 'name' | 'cwd'>>;

What an agent.spawn hook returns and what next(e) resolves to: the started subagent's { model, agentId }, or { deny: reason }, refusing it.

export type AgentSpawnResult = {    model: string;    text?: string;    isError?: true;    agentId?: string;    deny?: undefined;} | {    deny: string;    model?: undefined;    text?: undefined;    isError?: undefined;    agentId?: undefined;};

The handler on(...).catch(handler) takes for a hook of type F: the hook's ($, e, next), run afresh when it throws, misreturns or overruns.

export type CatchHandler<F> = F extends ($: infer D, e: infer E, next: infer N) => infer R ? ($: D, e: E, next: N & Caught) => R | undefined | Promise<Awaited<R> | undefined> : never;export type CatchHandler<F> = F extends ($: infer D, e: infer E, next: infer N) => infer R ? [R] extends [AsyncGenerator<unknown, unknown, unknown>] ? ($: D, e: E, next: N & Caught) => R : ($: D, e: E, next: N & Caught) => R | undefined | Promise<Awaited<R> | undefined> : never;

command.run's input as a plugin's $.command.run takes it: args may be left out (/command, bare), and origin is the engine's to set.

export type CommandRunArgs = Omit<CommandRunInput, 'origin'>;export type CommandRunArgs = Omit<CommandRunInput, 'origin' | 'args'> & {    args?: string;};

The engine's own events as calls on $, one signature each: $.<noun>.<event>(input) resolves to its result, or to its stream.

export type EventCalls = {    tool: {        call: ToolCallOverloads;        check: (input: ToolCheckArgs) => Promise<ToolCheckResult>;        describe: (input: ToolDescribeInput) => Promise<ToolDescribeResult>;    };    command: {        run: (input: CommandRunArgs) => Promise<CommandRunResult>;        describe: (input: CommandDescribeInput) => Promise<CommandDescribeResult>;    };    config: {        set: (input: ConfigSetArgs) => Promise<ConfigSetResult>;        describe: (input: ConfigDescribeInput) => Promise<ConfigDescribeResult>;    };    prompt: {        submit: (input: PromptSubmitArgs) => Promise<PromptSubmitResult>;…        start: (input: SessionStartInput) => Promise<SessionStartResult>;        receive: (input: SessionReceiveInput) => Promise<SessionReceiveResult>;        compact: (input?: SessionCompactArgs) => Promise<SessionCompactResult>;        attach: (input: SessionAttachInput) => Promise<SessionAttachResult>;        detach: (input: SessionDetachInput) => Promise<SessionDetachResult>;    };    turn: {        start: (input: TurnStartInput) => Promise<TurnStartResult>;        step: (input: TurnStepInput) => Promise<TurnStepResult>;        step: (input: TurnStepInput) => HookStream<TurnStepChunk, TurnStepResult>;        complete: (input: TurnCompleteInput) => Promise<TurnCompleteResult>;    };    ui: {

The hook signature of each event, ($, e, next), as one mapped type over EventOf; a streaming event's is the generator form (StreamHook).

export type Events = {    [E in keyof EventOf]: ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Frozen<Args<E>>, next: Next<E>) => EventResult<E> | Promise<EventResult<E>>;    [E in keyof EventOf]: E extends StreamingEventName ? StreamHook<E> : ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Frozen<Args<E>>, next: Next<E>) => EventResult<E> | Promise<EventResult<E>>;};

What $.ui.invalidate takes: a render event, or one of the five events whose answers the engine caches for the session.

export type InvalidatableEventName = RenderEventName | 'prompt.section' | 'prompt.context' | 'tool.describe' | 'command.describe';export type InvalidatableEventName = RenderEventName | 'prompt.section' | 'prompt.context' | 'tool.describe' | 'command.describe' | 'config.describe';

The hook on(pattern, matcher, hook) takes: ($, e, next) with e narrowed by the matcher (MatchedEvent), and a tagged result the same way.

export type MatchedHook<P extends Pattern, M> = ($: EngineInterface, e: Frozen<MatchedEvent<P, M>>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {export type MatchedHook<P extends Pattern, M> = P extends StreamingEventName ? MatchedStreamHook<P, M> : ($: EngineInterface, e: Frozen<MatchedEvent<P, M>>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {    [K in MatchedNames<P, M>]: Narrowed<Args<K>, M>;}>) => MatchedResult<P, M> | Promise<MatchedResult<P, M>>;

What each call on $ answers (the value of its event's result), by event name.

    'session.messages': SessionMessage[];    'session.repo': SessionRepo | null;    'session.surface': RenderSurface | null;    'session.surfaces': readonly RenderSurface[];    'session.authorize': SessionAuthorization;    'session.usage': SessionUsage;    'turn.abort': void;…    'command.register': {        command: string;    };    'config.list': ConfigRow[];    'agent.list': AgentInfo[];    'ui.toast': void;    'ui.status': void;

prompt.submit's input as a plugin's call takes it: origin, turnId and wait are the engine's to set, context the hooks' to attach.

export type PromptSubmitArgs = Omit<PromptSubmitInput, 'origin' | 'turnId' | 'wait'>;export type PromptSubmitArgs = Omit<PromptSubmitInput, 'origin' | 'turnId' | 'wait' | 'context'>;

The input of prompt.submit: the prompt as typed, after the input became a user message and before it enters the session.

export type PromptSubmitInput = {    text: string;    attachments?: readonly PromptAttachment[];    context?: readonly string[];    turnId?: string;    wait: boolean;    origin: PromptOrigin;

The plain-data props of each renderable component, as ui.render sees them under e.props; a hook rewrites them with next({ ...e, props }).

        title: string;        isFocused: boolean;        bodyColumns: number;        placement: 'dock' | 'inline';        scroll: SiteScroll;    };};

One settled run of a link beneath the caller, as next.trace lists it: data, not a handle.

    readonly outcome: TraceOutcome;    readonly reason?: string;    readonly ms: number;    readonly chunks?: number;    readonly received: E;    readonly returned: O | undefined;};

What every turn.complete carries whatever its reason: the answer, the duration, the interrupt flag, the turn's id, its loop and what it cost.

    durationMs: number;    isAborted: boolean;    turnId: string;    agentId?: string;    usage?: TurnUsage;};

The input of turn.step: one model request inside a turn, at the moment the engine is about to send it; the bottom of the chain sends it.

export type TurnStepInput = {    turnId: string;    index: number;    answer: string;    toolUses: readonly TurnStepToolUse[];    stopReason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'pause_turn' | 'compaction' | 'refusal' | 'model_context_window_exceeded';    usage?: TurnUsage;    model: string;    effort?: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | number;    messageCount: number;};

What a turn.step hook returns and what next(e) resolves to: the model's response to the step's request, once its blocks are all in.

export type TurnStepResult = {    turnId: string;    index: number;    usage?: TurnUsage;    answer: string;    toolUses: readonly TurnStepToolUse[];    stopReason: TurnStopReason;    usage: TurnUsage | null;};

Runs one tool-less completion over the session's OWN transcript, sharing the main thread's prompt cache; the reply's text and the fork's usage.

(request: ModelForkRequest) => Promise<ModelForkReply | null>(request: ModelForkRequest) => Promise<ModelForkResult | null>

Asks the user question in the engine's own AskUserQuestion dialog and resolves to the label they chose, or the text typed under "Other".

(question: string, options?: readonly string[] | AskProps) => Promise<string>(question: string, options?: readonly string[] | AskOptions) => Promise<string>

Fires when a Button a render hook drew is pressed on a surface; e is { plugin, element, component, surface }, element the button's key.

UiPressInputUiPressArgument

The input of command.describe: how one slash command presents in the typeahead and /help, at the moment the engine lists it.

type CommandDescribeInput = {export type CommandDescribeInput = {    command: string;    description: string;    argumentHint?: string;

What a command.describe hook returns: the description, hint and hidden flag the menu uses; the name, immediate and provider stay as they were.

type CommandDescribeResult = Omit<CommandDescribeInput, 'command' | 'immediate' | 'provider'>;export type CommandDescribeResult = Omit<CommandDescribeInput, 'command' | 'immediate' | 'provider'>;

One slash command as $.command.list() returns it.

type CommandInfo = {export type CommandInfo = {    name: string;    description: string;    source: CommandSource;

command.run's input as a plugin's $.command.run takes it: origin is the engine's to set (the calling plugin's name).

type CommandRunArgs = Omit<CommandRunInput, 'origin'>;export type CommandRunArgs = Omit<CommandRunInput, 'origin'>;

The input of command.run: one slash command about to run, the way the person typed it (/name args), and where the run came from.

type CommandRunInput = {export type CommandRunInput = {    command: string;    args: string;    origin: PromptOrigin;

What a command.run hook returns and what next(e) and $.command.run resolve to: the command's output text, when it has one.

type CommandRunResult = {export type CommandRunResult = {    text?: string;    ref?: number;};

Where a slash command comes from, as $.command.list() tells them apart.

type CommandSource = 'builtin' | 'plugin' | 'user' | 'mcp';export type CommandSource = 'builtin' | 'plugin' | 'user' | 'mcp';

What $.command.register takes: the slash command this plugin serves.

type CommandSpec = {export type CommandSpec = {    name: string;    description: string;    argumentHint?: string;

The element constructors each surface draws, by e.surface: what $.ui.resolve(e) returns and a ui.resolve hook passes on; no globals.

        Code: ElementConstructor<CodeProps>;        Client: ElementConstructor<ClientProps>;    };    mobile: {        Box: ElementConstructor<BoxProps>;        Text: ElementConstructor<TextProps>;        Button: ElementConstructor<ButtonProps>;        Svg: ElementConstructor<SvgProps>;        Link: ElementConstructor<LinkProps>;        Code: ElementConstructor<CodeProps>;    };};

The engine's own events as calls on $, one signature each: $.<noun>.<event>(input) dispatches the event and resolves to its result.

    };    prompt: {        submit: (input: PromptSubmitArgs) => Promise<PromptSubmitResult>;        fill: (input: PromptFillArgs) => Promise<PromptFillResult>;        suggest: (input: PromptSuggestArgs) => Promise<PromptSuggestResult>;        section: (input: PromptSectionInput) => Promise<PromptSectionResult>;        context: (input: PromptContextInput) => Promise<PromptContextResult>;    };

The hook signature of each event, ($, e, next), as one mapped type over EventOf.

export type Events = {    [E in keyof EventOf]: ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Args<E>, next: Next<E>) => EventResult<E> | Promise<EventResult<E>>;    [E in keyof EventOf]: ($: E extends 'engine.create' ? NoEngineInterface : EngineInterface, e: Frozen<Args<E>>, next: Next<E>) => EventResult<E> | Promise<EventResult<E>>;};

The hook on(pattern, hook) takes for a glob or a negation: one function placed on every selected event, e and the result typed as their union.

export type GlobHook<P extends Pattern, N extends EventName = Selected<P>> = ($: EngineInterface, e: Args<N>, next: GlobNext<P>) => EventResult<N> | Promise<EventResult<N>>;export type GlobHook<P extends Pattern, N extends EventName = Selected<P>> = ($: EngineInterface, e: Frozen<Args<N>>, next: GlobNext<P>) => EventResult<N> | Promise<EventResult<N>>;

next in a hook on a glob or a negation: an overload per selected event, then one over their union for an e not yet narrowed.

    (e: Args<N>): Promise<GlobNextResult<N>>;    readonly to: (e: Args<N>, tier: TargetTier) => Promise<GlobNextResult<N>>;    readonly signal: AbortSignal;    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Args<Extract<N, Selected<M>>>;    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Frozen<Args<Extract<N, Selected<M>>>>;    readonly event: N;    readonly origin: Origin;    readonly trace: readonly TraceEntry<N, Args<N>, GlobNextResult<N>>[];

Options of $.http.fetch.

    method?: string;    headers?: Record<string, string>;    body?: string;    auth?: string;};

The hook on(pattern, matcher, hook) takes: ($, e, next) with e narrowed by the matcher (MatchedEvent), and a tagged result the same way.

export type MatchedHook<P extends Pattern, M> = ($: EngineInterface, e: MatchedEvent<P, M>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {export type MatchedHook<P extends Pattern, M> = ($: EngineInterface, e: Frozen<MatchedEvent<P, M>>, next: Next<MatchedNames<P, M>, KeptEvent<P, M>, MatchedResult<P, M>, {    [K in MatchedNames<P, M>]: Narrowed<Args<K>, M>;}>) => MatchedResult<P, M> | Promise<MatchedResult<P, M>>;

The rest of the chain, as one hook receives it: made once per dispatch per hook, frozen; next(e) resolves to the downstream result.

        (e: E, tier: TargetTier): Promise<O>;    };    readonly signal: AbortSignal;    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is S[Extract<N, Selected<M>>];    readonly is: <M extends PatternOver<N>>(pattern: M, e: unknown) => e is Frozen<S[Extract<N, Selected<M>>]>;    readonly event: N;    readonly origin: Origin;    readonly trace: readonly TraceEntry<N, E, O>[];

What each call on $ answers (the value of its event's result), by event name.

export type OpValueOf = {    'model.complete': string;    'model.classify': string | undefined;    'model.fork': ModelForkReply | null;    'model.fork': ModelForkResult | null;    'audio.play': void;    'audio.speak': SpeakResult;    'mcp.call': McpToolResult;    'session.cwd': string;    'session.model': string;    'session.turnCount': number;    'session.turns': number;    'session.id': string;    'session.messages': SessionMessage[];    'session.repo': SessionRepo | null;    'session.surface': RenderSurface | null;    'session.authorize': SessionAuthorization;    'session.usage': SessionUsage;    'turn.abort': void;    'tool.list': ToolInfo[];

Who raised a dispatch, as next.origin holds it: the calling plugin's name and the tier it sits in; the engine reads engine in core.

type Origin = {export type Origin = {    readonly plugin: string;    readonly tier: Tier;};

The argument of $.ui.close: the pane to close ({ id }). origin is the engine's to set: a plugin's call reads plugin at the hooks.

type PaneCloseArgs = Omit<PaneCloseInput, 'origin'>;export type PaneCloseArgs = Omit<PaneCloseInput, 'origin'>;

The input of ui.close: the pane closing and why (PaneCloseOrigin). Closing an id that is not open does nothing.

type PaneCloseInput = {export type PaneCloseInput = {    id: string;    origin: PaneCloseOrigin;};

Why a pane closes, as the engine stamped it at ui.close.

type PaneCloseOrigin = 'plugin' | 'person' | 'unload';export type PaneCloseOrigin = {    kind: 'plugin' | 'person' | 'unload';};

The argument of $.ui.open: which pane, its title, and whether the plugin asks the person's keyboard for it.

type PaneOpenArgs = {export type PaneOpenArgs = {    id: string;    title?: string;    focus?: true;

Options of $.process.run.

type ProcessRunInit = {export type ProcessRunInit = {    cwd?: string;    env?: Record<string, string>;    stdin?: string;

What $.process.run resolves with once the child has exited.

type ProcessRunResult = {export type ProcessRunResult = {    exitCode: number;    stdout: string;    stderr: string;

What an element takes as children, as JSX passes them: a node, a number (drawn as its string), a value the factory drops, or a list that may nest.

export type RenderChildren = RenderNode | readonly RenderChildren[];export type RenderChildren = RenderNode | number | boolean | null | undefined | readonly RenderChildren[];

The plain-data props of each renderable component, as ui.render sees them under e.props; a hook rewrites them with next({ ...e, props }).

export type RenderPropsOf = {    AskUserQuestion: {        toolName: string;        tool: string;        questions: unknown[];        metadataSource?: string;    };…    };    AssistantMessage: {        text: string;        firstOfReply: boolean;        isFirstOfReply: boolean;    };    ToolUse: {        tool_use_id: string;        toolName: string;        tool: string;        input: unknown;        running: boolean;        errored: boolean;        interrupted: boolean;        isRunning: boolean;        isErrored: boolean;        isInterrupted: boolean;        output?: unknown;    };    ToolResult: {        tool_use_id: string;        toolName: string;        tool: string;        output: unknown;        errored: boolean;        isErrored: boolean;    };    ToolGroup: {        calls: ReadonlyArray<ToolGroupCall>;        active: boolean;        expanded: boolean;        isActive: boolean;        isExpanded: boolean;    };    Spinner: {        word: string;…    };    Pane: {        title: string;        focused: boolean;        isFocused: boolean;        bodyColumns: number;        scroll: SiteScroll;    };

Where a render event's component is drawn: terminal is Ink, which draws the hook's whole tree; desktop (Claude Code Desktop) and mobile (the Claude mobile app) are remote surfaces that draw the tree themselves.

export type RenderSurface = 'terminal' | 'desktop';export type RenderSurface = 'terminal' | 'desktop' | 'mobile';

type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens' | 'cloud_credential_error';type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'verification_required' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens' | 'cloud_credential_error';

The live context window as the status line reads it: the last API response's input side against the model's window.

type SessionContextUsage = {export type SessionContextUsage = {    tokens?: number;    window: number;    percent?: number;

What the session has cost, as /cost and the status line total it.

type SessionCost = {export type SessionCost = {    usd: number;};

One rate-limit window as the rate-limit notices read it.

type SessionRateLimit = {export type SessionRateLimit = {    kind: string;    percentUsed: number;    resetsAt?: string;

Where an inbound delivery came from, as the bridge classified it from the server's stamps: prompt.submit's e.origin, less what never arrives.

export type SessionReceiveOrigin = 'bridge' | 'task-notification' | 'scheduled-trigger' | 'peer' | 'peer-send-message' | 'projects-relay' | 'slack-ping' | 'unclassified';export type SessionReceiveOrigin = {    kind: 'bridge' | 'task-notification' | 'scheduled-trigger' | 'peer' | 'peer-send-message' | 'projects-relay' | 'slack-ping' | 'unclassified';};

The input of session.start: the session the process starts with, read the way $.session reads it at that moment.

export type SessionStartInput = {    cwd: string;    surface: RenderSurface | null;    interactive: boolean;    isInteractive: boolean;};

What $.session.usage() answers: the context window's fill, the account's rate-limit windows and the session's cost, as the status line has them.

type SessionUsage = {export type SessionUsage = {    context: SessionContextUsage;    rateLimits: SessionRateLimit[];    cost?: SessionCost;

What $.settings.read answers: an object keyed as a settings.json is (permissions, env, hooks, model, enabledPlugins, ...).

type Settings = Readonly<Record<string, unknown>>;export type Settings = Readonly<Record<string, unknown>>;

What $.settings.read(args) takes.

type SettingsReadArgs = {export type SettingsReadArgs = {    source?: SettingsSource;};

One source of settings by the name a plugin gives it, lowest precedence first; the engine's own name is the same word with Settings appended.

type SettingsSource = 'user' | 'project' | 'local' | 'flag' | 'policy';export type SettingsSource = 'user' | 'project' | 'local' | 'flag' | 'policy';

Where a site's window sits over the tree a hook drew in it (a pane's body, the band): the engine's to move (the person scrolls), the plugin's to read.

type SiteScroll = {export type SiteScroll = {    offset: number;    bodyRows: number;};

next in a * hook: the set of events is open at runtime, so e is unknown until next.is(pattern, e) narrows it to events it knows.

    (e: unknown): Promise<unknown>;    readonly to: (e: unknown, tier: TargetTier) => Promise<unknown>;    readonly signal: AbortSignal;    readonly is: <M extends Pattern>(pattern: M, e: unknown) => e is Args<Selected<M>>;    readonly is: <M extends Pattern>(pattern: M, e: unknown) => e is Frozen<Args<Selected<M>>>;    readonly event: EventName;    readonly origin: Origin;    readonly trace: readonly TraceEntry<EventName, unknown, unknown>[];

The props of Svg, the desktop and mobile surfaces' vector leaf: the markup is the element's data, as a string is a Text's, drawn isolated.

    alt: string;    width?: number;    height?: number;    interactive?: boolean;    isInteractive?: boolean;};

One tool call of a ToolGroup, as ui.render sees it under calls.

export type ToolGroupCall = {    tool_use_id?: string;    toolName: string;    tool: string;    input: unknown;    running: boolean;    errored: boolean;    interrupted: boolean;    isRunning: boolean;    isErrored: boolean;    isInterrupted: boolean;    output?: unknown;};

One tool_result block of a user message.

export type ToolResultSummary = {    id: string;    tool_use_id: string;    text: string;    isError: boolean;    result?: unknown;

One tool_use block of an assistant message, with its outcome once the transcript holds the call's tool_result (paired by tool_use_id).

export type ToolUseSummary = {    id: string;    name: string;    tool_use_id: string;    tool: string;    input: Record<string, unknown>;    result?: unknown;    text?: string;

What the chain decided for one link, as next.trace names it.

type TraceOutcome = 'caught' | 'expired' | 'kept' | 'passed' | 'rejected' | 'returned' | 'skipped';export type TraceOutcome = 'caught' | 'expired' | 'kept' | 'passed' | 'rejected' | 'returned' | 'skipped';

What every turn.complete carries whatever its reason: the answer, the duration, the interrupt flag, the turn's id and what the turn cost.

type TurnCompleteFields = {    answer: string;    durationMs: number;    aborted: boolean;    isAborted: boolean;    turnId: string;    usage?: TurnUsage;};

What a model turn, or one response inside it, cost as the API reported it: the four token counts ($.model.fork's usage shape) and the model's id.

type TurnUsage = ModelForkUsage & {export type TurnUsage = ModelForkUsage & {    model: string;};

The argument of ui.input: a change of, or a submit from, an Input a render hook drew. Flat and frozen like every event's.

type UiInputArgument = {export type UiInputArgument = {    plugin: string;    element: string;    component: RenderComponent;    requestId: string;    surface: RenderSurface;    kind: 'change' | 'submit';    value: string;

What a ui.input hook returns and what next(e) resolves to.

type UiInputResult = {export type UiInputResult = {    element: string;    value: string;};

The argument of ui.select: a pick from a Select a render hook drew. Flat and frozen like every event's.

type UiSelectArgument = {export type UiSelectArgument = {    plugin: string;    element: string;    component: RenderComponent;    requestId: string;    surface: RenderSurface;    value: string;};

What a ui.select hook returns and what next(e) resolves to.

type UiSelectResult = {export type UiSelectResult = {    element: string;    value: string;};