indusagi-coding-agent 0.2.2 → 0.2.4

package/dist/types/conductor/contract.d.ts

@@ -97,11 +97,20 @@ export declare function conductorFault(kind: FaultKind, message: string, cause?:
  *   - `text`      — a chunk of assistant answer text streamed in.
  *   - `thinking`  — a chunk of reasoning/thinking text streamed in.
  *   - `tool_start`— a tool invocation began (correlate by `id`).
+ *   - `tool_update`— a running tool emitted partial progress (correlate by `id`);
+ *                   `name` is the tool name and `details` is the tool's own typed
+ *                   partial-result detail (e.g. the live `◆ Workflow` snapshot).
  *   - `tool_end`  — a tool invocation finished (`ok` = no error).
  *   - `turn_end`  — the assistant turn settled; `usage` reports token spend.
  *   - `persisted` — the latest node was committed to the transcript (`entryId`).
- *   - `compacted` — the transcript was condensed to fit the context window.
- *   - `fault`     — a typed {@link ConductorFault} occurred.
+ *   - `compacted` — the transcript WAS condensed (emitted on completion, not at
+ *     the start). `manual` marks a user-driven `/compact` — a view may then
+ *     reset its visible transcript — versus mid-turn auto-compaction, where the
+ *     display must keep the in-flight exchange on screen.
+ *   - `fault`     — a typed {@link ConductorFault} occurred. `transient` marks a
+ *     fault surfaced purely as an in-turn notice (e.g. a fallback-model swap on
+ *     provider overload) — the turn keeps running, so a consumer must NOT treat
+ *     it as the turn's end (must not clear a busy/in-flight indicator on it).
  *   - `queue`     — the pending-input queue changed; `count` is its new depth.
  *   - `idle`      — the conductor has no in-flight work and is ready for input.
  */
@@ -118,6 +127,11 @@ export type SessionSignal = {
     readonly kind: "tool_start";
     readonly id: string;
     readonly name: string;
+} | {
+    readonly kind: "tool_update";
+    readonly id: string;
+    readonly name: string;
+    readonly details: unknown;
 } | {
     readonly kind: "tool_end";
     readonly id: string;
@@ -130,9 +144,11 @@ export type SessionSignal = {
     readonly entryId: string;
 } | {
     readonly kind: "compacted";
+    readonly manual?: boolean;
 } | {
     readonly kind: "fault";
     readonly fault: ConductorFault;
+    readonly transient?: boolean;
 } | {
     readonly kind: "queue";
     readonly count: number;
@@ -420,6 +436,18 @@ export interface SessionConductorOptions {
      * the swap entirely (behavior-preserving default).
      */
     readonly fallbackModelId?: string;
+    /**
+     * Per-provider indus-gateway base URLs ("server mode"), keyed by provider slug
+     * (e.g. `{ minimax: "http://host/gateway/minimax", sarvam: "…/gateway/sarvam" }`).
+     * Set by the session runner for every gateway-eligible provider the user has no
+     * local key for but holds a valid server token. At EVERY model bind (including a
+     * runtime `/model` switch) the conductor looks up the BOUND model's provider in
+     * this map and, when present, binds a CLONE of the framework model with its
+     * `baseUrl` swapped to that URL — so any server-tier model routes through the
+     * quota-enforcing server while the session token (via {@link getApiKey})
+     * authenticates it. A provider absent from the map keeps the direct path.
+     */
+    readonly gatewayBaseUrls?: Record<string, string>;
     /** Working directory the session is scoped to (defaults to process cwd). */
     readonly workspace?: string;
     /**
@@ -488,6 +516,11 @@ export interface SessionConductorOptions {
      */
     readonly checkpoint?: CheckpointPort;
 }
+/**
+ * What a manual {@link SessionConductor.condense} run amounted to — the honest
+ * completion vocabulary `/compact` reports from (see the method doc).
+ */
+export type CondenseOutcome = "condensed" | "nothing" | "cancelled" | "failed" | "busy";
 /**
  * The conductor of a single coding-agent session.
  *
@@ -529,6 +562,15 @@ export interface SessionConductor {
     pendingInputs(): readonly QueuedInput[];
     /** Discard every queued input. Emits a `{ kind: "queue" }` signal. */
     clearQueue(): void;
+    /**
+     * Promote the NEWEST queued input to run immediately: the in-flight turn (if
+     * any) is aborted — its work stops — while the rest of the queue is kept, and
+     * the promoted input runs as the very next turn. The user-facing "run my new
+     * message NOW" affordance for a long/stuck turn (issue #19), distinct from
+     * {@link abort} (which stops everything and clears the queue). Returns `false`
+     * when no input is queued.
+     */
+    steerNow(): boolean;
     /**
      * Remove and return the text of the most-recently queued input, or `undefined`
      * when the queue is empty. Lets a UI pop the last entry back into its prompt.
@@ -562,6 +604,20 @@ export interface SessionConductor {
      * @param id canonical id of the model to switch to
      */
     selectModel(id: string): void;
+    /**
+     * Replace the server-tier gateway routing map and immediately re-bind the
+     * currently selected model against it (without changing which model is
+     * selected). Lets an interactive mid-session sign-in (see `/login` ->
+     * "Indus Server") take effect right away: the gateway base-url map is
+     * otherwise frozen at conductor construction, so a login that happens after
+     * boot would silently never route the bound model through the gateway even
+     * though the per-request key resolver already started vending the fresh
+     * session token as the provider key.
+     *
+     * @param map provider id -> gateway base URL, as produced by
+     *   `resolveServerGatewayUrls` for the current vault/token state
+     */
+    updateGatewayBaseUrls(map: Record<string, string>): void;
     /**
      * Replace the agent's tool deck for subsequent turns.
      *
@@ -576,11 +632,27 @@ export interface SessionConductor {
      */
     registerTools(tools: AgentTool[]): void;
     /**
-     * Manually run the same transcript-condense path the auto-compactor uses,
-     * emitting the existing `compacted` signal. Safe to call when idle; a no-op
-     * when the condense hook returns the branch unchanged.
-     */
-    condense(): Promise<void>;
+     * Manually run the transcript-condense path (`/compact`) and report what
+     * happened, so the caller can give honest feedback instead of announcing
+     * "condensed" regardless:
+     *   - `"condensed"` — the branch shrank and was rebound (emits `compacted`).
+     *   - `"nothing"`   — nothing older to fold (single-turn session, or already
+     *                     compacted); the transcript is untouched.
+     *   - `"cancelled"` — {@link cancelCondense} fired mid-run; the digest was
+     *                     discarded and the transcript is untouched.
+     *   - `"failed"`    — the condense hook threw; a typed fault was emitted.
+     *   - `"busy"`      — a turn is in flight; compact after it settles (or abort
+     *                     it first).
+     * While the condense runs, {@link submit} queues instead of racing it, and the
+     * queue drains once the condense settles.
+     */
+    condense(): Promise<CondenseOutcome>;
+    /**
+     * Cancel an in-flight manual {@link condense} (the `/compact` Esc affordance).
+     * The summarizer's result is discarded and the transcript stays untouched; a
+     * no-op when no manual condense is running.
+     */
+    cancelCondense(): void;
     /**
      * Branch the transcript from a prior node. A new branch is opened whose parent
      * is `entryId`; the agent's message list is rebound to that branch's root→leaf

package/dist/types/conductor/index.d.ts

@@ -14,13 +14,13 @@
  * land; consumers import the conductor surface from `src/conductor` rather than
  * reaching into individual modules.
  */
-export type { FaultKind, ConductorFault, SessionSignal, SignalKind, SignalOf, SignalHandler, TranscriptSchema, TranscriptRole, TranscriptEntry, SessionHead, ModelCardRef, MatchQuery, ConductorPhase, ConductorState, QueueMode, QueuedInput, SessionStats, ExecuteBashOptions, BashOutcome, SessionConductor, SessionConductorOptions, AgentMessage, AgentTool, CanUseToolFn, ThinkingLevel, Model, Usage, KnownProvider, PermissionMode, } from "./contract";
+export type { FaultKind, ConductorFault, SessionSignal, SignalKind, SignalOf, SignalHandler, TranscriptSchema, TranscriptRole, TranscriptEntry, SessionHead, ModelCardRef, MatchQuery, ConductorPhase, ConductorState, QueueMode, QueuedInput, SessionStats, ExecuteBashOptions, BashOutcome, SessionConductor, SessionConductorOptions, CondenseOutcome, AgentMessage, AgentTool, CanUseToolFn, ThinkingLevel, Model, Usage, KnownProvider, PermissionMode, } from "./contract";
 export { conductorFault, TRANSCRIPT_SCHEMA } from "./contract";
-export { createSessionConductor, reduceState, noopCondense, type AgentLike, type ConductorDeps, type CondenseFn, type RetryPolicy, } from "./conductor";
+export { createSessionConductor, reduceState, noopCondense, withGatewayBaseUrl, type AgentLike, type ConductorDeps, type CondenseFn, type RetryPolicy, } from "./conductor";
 export { SignalHub, translateAgentEvent, type SignalHubOptions } from "./signal-hub";
 export { ModelCatalog, ModelMatcher, canonicalId, toCardRef, type CatalogCard, type CatalogSource, type ResolveInput, } from "./catalog";
 export { TranscriptStore, memoryBackend, fsBackend, replay, type TranscriptBackend, type TranscriptState, type TranscriptClock, type TranscriptStoreOptions, } from "./transcript-store";
 export { parseSkillInvocation, type SkillInvocation } from "./skill-parse";
-export { resolveRuleDecision, parseRule, makeRule, toolMatchesRule, createPermissionGate, isReadOnlyToolName, isEditToolName, READ_ONLY_TOOL_NAMES, EDIT_TOOL_NAMES, type PermissionBehavior, type PermissionRule, type PermissionDecision, type CanUseToolFn as PermissionCanUseToolFn, type ApprovalChoice, type ApprovalResolver, type PermissionGateConfig, } from "./permissions";
+export { resolveRuleDecision, parseRule, makeRule, toolMatchesRule, createPermissionGate, createSubagentPermissionGate, collectReadOnlyToolNames, allowAlwaysRuleStrings, isReadOnlyToolName, isEditToolName, READ_ONLY_TOOL_NAMES, EDIT_TOOL_NAMES, type PermissionBehavior, type PermissionRule, type PermissionDecision, type CanUseToolFn as PermissionCanUseToolFn, type ApprovalChoice, type ApprovalOutcome, type ApprovalResolver, type PermissionGateConfig, type SessionPermissionPolicy, } from "./permissions";
 export { parseBashCommand, catastrophicReason, isCatastrophicCommand, evaluateCatastrophic, bashSubcommandSubjects, type ParsedCommand, } from "./bash-guard";
 export { DiagnosticsEngine, createDiagnosticKey, deduplicateAndCap, formatDiagnosticsSummary, getSeveritySymbol, parseTscOutput, parseEslintOutput, runTscDiagnostics, runEslintDiagnostics, hasTsConfig, hasEslintConfig, isTypeScriptOrJs, areDiagnosticsEqual, MAX_PER_FILE, MAX_TOTAL, MAX_SUMMARY_CHARS, type Diagnostic, type DiagnosticFile, type DiagnosticSeverity, type DiagnosticsConfig, type DiagnosticRunner, type DedupOptions, type Position, } from "./diagnostics";

package/dist/types/conductor/permissions.d.ts

@@ -74,16 +74,29 @@ export type CanUseToolFn = (toolName: string, input: unknown, opts: {
  *   - `deny`         — block this call.
  */
 export type ApprovalChoice = "allow-once" | "allow-always" | "deny";
+/**
+ * What an {@link ApprovalResolver} may resolve to: a user's {@link ApprovalChoice},
+ * or `"unavailable"` — the conductor's stable delegate answers that when NO
+ * interactive resolver is installed behind it (a headless boot, or the console not
+ * yet mounted). The gate maps `"unavailable"` to the actionable "requires
+ * approval" deny (pointing at `--permission-mode` / settings allow rules) rather
+ * than the "denied by the user" message, which would be false when no user ever
+ * saw a prompt.
+ */
+export type ApprovalOutcome = ApprovalChoice | "unavailable";
 /**
  * The OPTIONAL host approval resolver. When present, an `ask` decision awaits it;
  * the host (an interactive overlay) returns the user's choice. It MUST resolve to
  * `"deny"` on abort so a cancelled turn never hangs on a pending prompt. When the
  * resolver is absent (non-interactive boot / oneshot / link), an `ask` decision
- * deterministically denies.
+ * deterministically denies. A stable pass-through delegate (the conductor's)
+ * resolves `"unavailable"` while no real resolver is installed behind it, so the
+ * gate can surface the actionable non-interactive deny message instead of a
+ * fictitious user denial.
  */
 export type ApprovalResolver = (toolName: string, input: unknown, opts: {
     signal?: AbortSignal;
-}) => Promise<ApprovalChoice>;
+}) => Promise<ApprovalOutcome>;
 /**
  * Tool names known to only inspect state (never mutate). Mirrors the framework's
  * `READ_ONLY_TOOL_NAMES`; matched case-insensitively. A tool the framework marks
@@ -172,6 +185,22 @@ export declare function toolMatchesRule(toolName: string, input: unknown, rule:
  * Pure and total: no I/O, no async, deterministic for a given input.
  */
 export declare function resolveRuleDecision(toolName: string, input: unknown, rules: readonly PermissionRule[], mode: PermissionMode, readOnlyExtra?: ReadonlySet<string>): PermissionBehavior;
+/**
+ * The rule strings an `allow-always` approval mints — i.e. what the session will
+ * REMEMBER for this tool call.
+ *
+ * For the shell tool the remembered rules are scoped to the command: one
+ * `Bash(<sub-command>)` rule per constituent sub-command (so approving
+ * `git status && npm test` remembers both halves, and re-running either — or the
+ * same compound — auto-allows), but approving one command never whitelists the
+ * whole shell. Every other tool remembers the bare tool name (`Edit`), matching
+ * the prompt's "remember the tool for this session" copy.
+ *
+ * Exported so the approval overlay can show the user exactly what "Allow always"
+ * will remember (the `suggestions` line), and so the gate and the UI can never
+ * disagree about it.
+ */
+export declare function allowAlwaysRuleStrings(toolName: string, input: unknown): string[];
 /** Configuration for {@link createPermissionGate}. */
 export interface PermissionGateConfig {
     /**
@@ -188,8 +217,11 @@ export interface PermissionGateConfig {
     readonly requestApproval?: ApprovalResolver;
     /**
      * Append a session-scoped allow rule when the host returns `allow-always`. The
-     * conductor owns the mutable rule list and passes a setter here so the new rule
-     * is visible to subsequent calls within the session.
+     * boot layer owns the mutable rule list (the SAME array instance `rules` refers
+     * to) and passes a push here, so the appended rule is visible to every
+     * subsequent gate consultation within the session — and to every other gate
+     * built over the same list (sub-agent gates included). Session-scoped only:
+     * the rule is never persisted to settings.
      */
     readonly appendAllowRule?: (rule: PermissionRule) => void;
     /**
@@ -215,3 +247,41 @@ export interface PermissionGateConfig {
  * The result is assignable to `indusagi/agent`'s `CanUseToolFn`.
  */
 export declare function createPermissionGate(config: PermissionGateConfig): CanUseToolFn;
+/**
+ * The live permission policy a session shares with its sub-agent runners (the
+ * `task` and `workflow` tools): the SAME mutable rule list the parent gate reads
+ * — so a session-scoped `allow-always` rule and the settings deny/ask rules are
+ * enforced inside delegations too — plus a live getter onto the parent
+ * conductor's permission mode, so a mid-run Shift+Tab (bypass → default, plan,
+ * back to bypass, …) retargets the very next sub-agent tool call.
+ */
+export interface SessionPermissionPolicy {
+    /** The session's ordered rule list — the live array, never a snapshot. */
+    readonly rules: readonly PermissionRule[];
+    /** Live getter onto the parent session's current permission mode. */
+    readonly mode: () => PermissionMode;
+}
+/**
+ * Collect the names of every tool flagged `readOnly: true` (structurally probed,
+ * so any deck/framework/MCP tool shape works). These names are auto-allowed by
+ * the gate in `default`/`acceptEdits`/`plan` beyond the static
+ * {@link READ_ONLY_TOOL_NAMES}.
+ */
+export declare function collectReadOnlyToolNames(tools: ReadonlyArray<{
+    readonly name: string;
+}>): ReadonlySet<string>;
+/**
+ * Build the RESOLVER-LESS gate a sub-agent runs under.
+ *
+ * A sub-agent cannot prompt the user, so no {@link ApprovalResolver} is wired:
+ * an `ask` decision deterministically denies with an actionable message, while
+ * deny rules, plan-mode enforcement, the catastrophic-bash blocklist, read-only
+ * auto-allow, and bypass/acceptEdits behaviour all apply per inner tool call —
+ * against the LIVE parent mode, so mid-run mode switches reach delegations too.
+ *
+ * @param policy the session's shared rules + live mode getter
+ * @param tools  the sub-agent's actual deck, probed for `readOnly: true` flags
+ */
+export declare function createSubagentPermissionGate(policy: SessionPermissionPolicy, tools: ReadonlyArray<{
+    readonly name: string;
+}>): CanUseToolFn;

package/dist/types/conductor/post-edit-diagnostics.test.d.ts

@@ -6,8 +6,13 @@
  * over a scripted in-memory runner (no real tsc spawn). Verifies:
  *   - a turn that introduces a NEW diagnostic enqueues the summary follow-up;
  *   - a clean edit (no new diagnostics) enqueues nothing;
- *   - re-editing a file re-surfaces a previously-cleared diagnostic;
- *   - a non-TS edit never triggers the checker;
- *   - the injected follow-up turn (which edits nothing) does not loop.
+ *   - a still-unfixed diagnostic is delivered AT MOST ONCE per session — a
+ *     follow-up turn whose "fix" edits fail to eliminate the same error must
+ *     NOT be re-prompted with it (the endless self-continuation of issue #15);
+ *   - even genuinely NEW errors per fix attempt stop re-prompting at the
+ *     consecutive follow-up cap, and a fresh user prompt re-arms the budget;
+ *   - `idle` is not emitted between a turn and its auto-drained follow-up (the
+ *     spinner must not drop while the agent keeps working);
+ *   - a non-TS edit never triggers the checker.
  */
 export {};

package/dist/types/conductor/quota-error.d.ts

@@ -0,0 +1,35 @@
+/**
+ * quota-error.ts — maps the indus model-gateway's usage-limit response into a
+ * friendly, user-facing fault message.
+ *
+ * When a no-local-key, logged-in user runs a turn, the framework adapter is
+ * pointed at `${INDUS_SERVER_URL}/gateway/<provider>` (see the conductor's
+ * baseUrl rewrite). If that user is over their monthly token allowance, the
+ * server replies — *before* forwarding upstream — with:
+ *
+ *   HTTP/1.1 429 Too Many Requests
+ *   Content-Type: application/json
+ *
+ *   { "error": "quota_exceeded", "used": <number>, "limit": <number> }
+ *
+ * The provider SDK / raw-fetch adapter turns that 429 into a thrown error. By
+ * the time it reaches the conductor it may be wrapped (an SDK `APIError`, a
+ * generic `Error`, a nested `cause` chain, or a plain string), so detection must
+ * be tolerant and walk the whole error chain rather than trust a single shape.
+ *
+ * This module is intentionally transport-agnostic and dependency-free so it can
+ * be unit-tested in isolation and imported from the conductor's retry chokepoint
+ * without pulling in any network/runtime modules.
+ */
+/** Detects the gateway's 429 quota body anywhere in the error chain. */
+export declare function isQuotaFault(error: unknown): boolean;
+/**
+ * Friendly user-facing text; `undefined` if `error` is not a quota fault.
+ *
+ * Includes the `<used>/<limit>` parenthetical when both numbers are parseable,
+ * and otherwise falls back to the same sentence without it. The `indus signin
+ * <provider>` hint steers the user toward supplying their own key (which takes
+ * the direct, un-metered local-key path), and the upgrade hint covers raising
+ * the server-side allowance.
+ */
+export declare function quotaErrorMessage(error: unknown): string | undefined;

package/dist/types/conductor/signal-hub/translate.d.ts

@@ -24,7 +24,10 @@
  *                                   (the turn is now committed), one `fault` for
  *                                   an errored *assistant* message, else `[]`
  *   - `tool_execution_start`     → one `tool_start`  { id, name }
- *   - `tool_execution_update`    → `[]`  (partial tool progress is not surfaced)
+ *   - `tool_execution_update`    → one `tool_update` { id, name, details } — the
+ *                                   running tool's partial-result detail (e.g. the
+ *                                   live `◆ Workflow` snapshot) re-projected so the
+ *                                   console can update the transcript in place
  *   - `tool_execution_end`       → one `tool_end`    { id, ok: !isError }
  *   - `turn_end`                 → one `turn_end`    { usage }
  *   - `message_update`           → delegated to the inner streaming dispatch on

package/dist/types/console/auth-status.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared "does the user have a usable credential for this provider" probe.
+ *
+ * Used anywhere the console needs to know which providers are actually
+ * callable — the `/model` picker (only list authenticated providers) and the
+ * banner's Session panel (don't display an unauthenticated model as if it were
+ * ready to use) both need the exact same answer, so it lives here once.
+ */
+import type { OverlayServices } from "./contract";
+/**
+ * Load the set of provider ids the user has USABLE credentials for, live, so a
+ * mid-session `/login` (either a local vault sign-in or the "Indus Server"
+ * server-tier device flow) is reflected without a restart.
+ *
+ * Two independent sources count: (1) any saved account in the local vault for a
+ * provider `listLoginProviders()` names, and (2) a valid server session token,
+ * which makes every gateway-eligible provider (`serverTierProviders()` —
+ * minimax, sarvam) usable even though the server tier never writes into the
+ * vault. Returns `null` until the asynchronous probe settles.
+ *
+ * `refreshKey` re-runs the probe whenever it changes by reference/value — a
+ * short-lived overlay (the `/model` picker) can leave it at its default since
+ * it remounts fresh on every open anyway, but a component mounted once for the
+ * whole session (the banner, the status bar) MUST pass something that changes
+ * right when a sign-in completes (e.g. the console's current status toast),
+ * otherwise this only ever reflects whatever was true at session start.
+ */
+export declare function useAuthenticatedProviders(services: OverlayServices | undefined, refreshKey?: unknown): Set<string> | null;

package/dist/types/console/components/AgentsView.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AgentsView — the drill-in sub-agent view, styled to the "IndusCode Saffron ·
+ * Subagent View" design.
+ *
+ * Opened from the main screen (← on an empty prompt while sub-agents are
+ * running), this replaces the transcript with a focused, navigable view of the
+ * delegated sub-agents: ↑/↓ moves the selection through `main` + each sub-agent,
+ * and the panel above the picker live-previews the selected sub-agent's activity
+ * stream — its reasoning and the tools it is using, just like the main screen —
+ * with a running clock and token count. Selecting `main` and pressing Enter (or
+ * Esc) returns to the main session.
+ *
+ * It is fed entirely by props the surface already holds: the derived
+ * {@link AgentRun}s plus the per-sub-agent live activity / token maps captured
+ * from the task tool's streamed progress. Its own {@link useInput} owns the
+ * keyboard while it is mounted (the surface gates its main handler off).
+ */
+import { type InkThemeAdapter } from "indusagi/react-ink";
+import type { AgentRun } from "./BackgroundAgents";
+import type { ActivityLine } from "../../capability-deck/cards/task-card";
+/** What the {@link AgentsView} renders. */
+export interface AgentsViewProps {
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** The delegated sub-agent runs (from `deriveAgentRuns`). */
+    readonly runs: readonly AgentRun[];
+    /** Live activity streams per run id (from the task tool's progress). */
+    readonly activity: Readonly<Record<string, readonly ActivityLine[]>>;
+    /** Live token spend per run id. */
+    readonly tokens: Readonly<Record<string, number>>;
+    /** Current epoch ms, for the run clock. Defaults to `Date.now()`. */
+    readonly now?: number;
+    /** Return to the main session. */
+    readonly onExit: () => void;
+}
+/**
+ * Render the drill-in agents view.
+ *
+ * @param props the theme, runs, live activity/token maps, and the exit callback
+ */
+export declare function AgentsView({ theme, runs, activity, tokens, now, onExit }: AgentsViewProps): JSX.Element;

package/dist/types/console/components/BackgroundAgents.d.ts

@@ -0,0 +1,63 @@
+/**
+ * BackgroundAgents — the live sub-agent panel pinned below the input, styled to
+ * the "IndusCode Saffron · Background Agents" design.
+ *
+ * When the primary agent delegates with the `task` tool, each sub-agent run is
+ * surfaced here as a compact status row (a spinner/● dot, the agent profile name
+ * in saffron, the objective in dim, and a running clock / done / failed status)
+ * under a `● main` header — so a user watching several agents work sees them all
+ * at a glance in the main screen instead of scrolling the transcript. The panel
+ * shows only while at least one run is in flight and hides once they all settle
+ * (their final reports remain inline in the transcript).
+ *
+ * The run list is derived purely from the conversation by {@link deriveAgentRuns}
+ * (the `task` tool calls in the assistant messages, matched against their
+ * `toolResult` messages for status), so the panel needs no extra session state —
+ * it is a projection of `conductor.messages()`.
+ */
+import { type InkThemeAdapter } from "indusagi/react-ink";
+import type { AgentMessage } from "indusagi/agent";
+/** The live status of one delegated sub-agent. */
+export type AgentRunStatus = "running" | "done" | "error";
+/** One delegated sub-agent run, projected from the conversation. */
+export interface AgentRun {
+    /** The `task` tool-call id correlating the call with its result. */
+    readonly id: string;
+    /** The agent profile name (the `agent` arg), or "subagent" when unnamed. */
+    readonly name: string;
+    /** The delegated objective (the `objective` arg), shown as the description. */
+    readonly objective: string;
+    /** Whether the run is in flight, finished, or errored. */
+    readonly status: AgentRunStatus;
+    /** Epoch ms the delegating assistant message was stamped (for the run clock). */
+    readonly startedAt: number;
+}
+/**
+ * Derive the delegated sub-agent runs from the conversation.
+ *
+ * Walks the messages once: every `task` tool call in an assistant message
+ * becomes a run (named by its `agent` arg, described by its `objective`), and a
+ * later `toolResult` with the matching id resolves its status to done/error.
+ * Runs with no result yet are "running". Pure and order-stable — the same
+ * messages always yield the same list, oldest first.
+ *
+ * @param messages the live conversation (`conductor.messages()`)
+ */
+export declare function deriveAgentRuns(messages: readonly AgentMessage[]): AgentRun[];
+/** What the {@link BackgroundAgents} renders. */
+export interface BackgroundAgentsProps {
+    /** The framework adapter that turns token roles into terminal colours. */
+    readonly theme: InkThemeAdapter;
+    /** The derived sub-agent runs (from {@link deriveAgentRuns}). */
+    readonly runs: readonly AgentRun[];
+    /** Live token spend per run, keyed by run id (the task tool-call id). */
+    readonly tokens?: Readonly<Record<string, number>>;
+    /** Current epoch ms, for the run clock. Defaults to `Date.now()`. */
+    readonly now?: number;
+}
+/**
+ * Render the background-agents panel, or nothing when no run is in flight.
+ *
+ * @param props the theme, the derived runs, and the current time
+ */
+export declare function BackgroundAgents({ theme, runs, tokens, now }: BackgroundAgentsProps): JSX.Element | null;

package/dist/types/console/components/BackgroundAgents.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * BackgroundAgents — pure derivation tests.
+ *
+ * Exercises {@link deriveAgentRuns} against hand-built conversations (no Ink):
+ * `task` tool calls become runs, matched `toolResult` messages resolve their
+ * status, non-task calls are ignored, and unnamed agents fall back to a label.
+ */
+export {};

package/dist/types/console/components/Banner.d.ts

@@ -1,18 +1,30 @@
 /**
- * Banner — the masthead the console renders above the transcript.
+ * Banner — the "IndusCode Saffron" masthead the console renders above the
+ * transcript.
  *
- * The startup chrome the surface mounts once at the top of a session: an
- * original block-letter wordmark rendered in the box-drawing palette and tinted
- * with the accent/signal role, a version + brand line beneath it, and a compact
- * bordered "Session" panel of at-a-glance facts (the bound model id and the
- * working directory). It reads nothing but its props, holds no state, and runs
- * no effects — purely presentational Ink primitives themed through the framework
- * {@link InkThemeAdapter}.
+ * The startup chrome the surface mounts at the top of a session. Its loud
+ * (default) mode has two presentations, switched by {@link BannerProps.started}:
  *
- * The wordmark is the "INDUS CODE" brand masthead rendered in the ANSI-Shadow
- * block-figlet style from the `█ ║ ═ ╔ ╗ ╚ ╝` box-drawing family — the same
- * masthead the shipped console shows, so both surfaces share one identity. The
- * glyph rows are plain data tinted with the accent role at render time.
+ *   - **Welcome card** (fresh session, no messages yet): a bordered card in the
+ *     saffron brand look — a compact `● IndusCode v…` brand label, then two
+ *     columns (left: a personalized greeting above a small block-art robot
+ *     mascot and the bound model / working directory; right: a rotating "getting
+ *     started" tip and the "What's new" notes). The mascot expression and the
+ *     tip rotate per session (seeded once at mount and threaded in via
+ *     {@link BannerProps.variantSeed}), so a new session looks a little different
+ *     each time while staying deterministic for tests.
+ *   - **Startup & Chat masthead** (once the user has sent a message): the
+ *     `➜ dir git:(branch) indus` shell line, the block-letter "INDUS CODE"
+ *     wordmark, the `indus console v…` brand line, the welcome line, and a
+ *     bordered "Session" panel (model + cwd). The conversation itself is rendered
+ *     below the banner by the surface's `MessageList`.
+ *
+ * It reads nothing but its props, holds no state, and runs no effects — purely
+ * presentational Ink primitives themed through the framework
+ * {@link InkThemeAdapter}. The {@link BannerProps.quiet} or
+ * {@link BannerProps.compact} flags collapse all of that to a single compact
+ * header line, still carrying the welcome line, the notices, and a condensed
+ * changelog so nothing important is silently dropped.
  */
 import { type InkThemeAdapter } from "indusagi/react-ink";
 import type { StartupChangelog, StartupMap, StartupNotice } from "../startup";
@@ -26,19 +38,27 @@ export interface BannerProps {
     readonly workspace: string;
     /** The product version shown on the brand line (e.g. the package VERSION). */
     readonly version: string;
+    /**
+     * Whether the conversation has begun (the user has sent at least one message).
+     * When `false` the loud banner is the fresh-session welcome card; when `true`
+     * it becomes the Startup & Chat masthead (wordmark + Session panel) that sits
+     * above the transcript. Has no effect in {@link quiet}/{@link compact} modes.
+     */
+    readonly started?: boolean;
+    /** The active VCS branch (for the masthead shell line), or `null`/absent outside a repo. */
+    readonly branch?: string | null;
     /** Whether to render the extra diagnostics line. */
     readonly verbose?: boolean;
     /**
-     * When set, the big wordmark + Startup Map are suppressed in favour of a
-     * single compact header line. Wired from the verbose / quiet-startup flag.
+     * When set, the welcome card is suppressed in favour of a single compact
+     * header line. Wired from the verbose / quiet-startup flag.
      */
     readonly quiet?: boolean;
     /**
      * When set, the masthead auto-condenses to a single emblem + brand + model
-     * line (the repeat-launch presentation): the user has already seen this
-     * version's full masthead, so the big wordmark is skipped. Distinct from
-     * {@link quiet}, which is the manual suppression toggle; either collapses the
-     * banner, but `compact` keeps the small emblem and the welcome line.
+     * line (the repeat-launch presentation). Distinct from {@link quiet}, which is
+     * the manual suppression toggle; either collapses the banner, but `compact`
+     * keeps the small emblem and the welcome line.
      */
     readonly compact?: boolean;
     /**
@@ -47,15 +67,30 @@ export interface BannerProps {
      */
     readonly name?: string;
     /**
-     * Opt-in static colour-sweep flourish: when set, the wordmark and emblem fill
-     * are tinted along a frozen primary→secondary gradient instead of the flat
-     * accent. The caller is responsible for suppressing it under reduced-motion /
-     * non-TTY; this prop is simply the resolved on/off decision.
+     * Opt-in static colour-sweep flourish (legacy; accepted for call-site
+     * compatibility). The saffron welcome card paints from the theme roles and
+     * does not consume this flag.
      */
     readonly sweep?: boolean;
-    /** The gathered session resources rendered as the Startup Map panel. */
+    /**
+     * The per-session variation seed. Selects which mascot expression + "getting
+     * started" tip the card shows; the same seed always yields the same pair, so a
+     * test pins an exact variant. Absent → the first (seed 0) variant.
+     */
+    readonly variantSeed?: number;
+    /**
+     * Optional override for the "What's new" notes (e.g. sourced from a live
+     * changelog). Absent → the shipped {@link WHATS_NEW} copy.
+     */
+    readonly whatsNew?: readonly string[];
+    /**
+     * The gathered session resources (context docs, skills, prompts). Reserved:
+     * the saffron welcome card shows quick-action chips in place of the old
+     * "Startup Map" panel, so this is accepted for call-site compatibility (and to
+     * keep the gathering machinery wired) but not rendered in the card.
+     */
     readonly startup?: StartupMap;
-    /** Out-of-band lines drawn above the wordmark (errors, warnings, info). */
+    /** Out-of-band lines drawn above the card (errors, warnings, info). */
     readonly notices?: readonly StartupNotice[];
     /** The changelog survey rendered as a "What is new" block on a version bump. */
     readonly changelog?: StartupChangelog;
@@ -63,14 +98,13 @@ export interface BannerProps {
 /**
  * Render the console masthead.
  *
- * In the default (loud) mode this is the two-tone emblem beside the block-letter
- * wordmark, the brand / version line, the personalized welcome line, the
- * optional notices region, the bordered Startup Map, and the changelog block.
- * The {@link BannerProps.quiet} or {@link BannerProps.compact} flags collapse
- * all of that to a single compact header line (emblem glyph + brand + version +
- * model), still carrying the welcome line, the notices, and a condensed
- * changelog so nothing important is silently dropped.
+ * In the default (loud) mode this is the saffron welcome card: a `● IndusCode
+ * v…` brand label and a two-column body (greeting + mascot + model/cwd on the
+ * left, a rotating tip + the "What's new" notes on the right). The
+ * {@link BannerProps.quiet} or {@link BannerProps.compact} flags
+ * collapse all of that to a single compact header line, still carrying the
+ * welcome line, the notices, and a condensed changelog.
  *
- * @param props the wordmark context, version, session facts, and startup chrome
+ * @param props the brand/version context, session facts, and startup chrome
  */
-export declare function Banner({ theme, modelId, workspace, version, verbose, quiet, compact, name, sweep, startup, notices, changelog, }: BannerProps): JSX.Element;
+export declare function Banner({ theme, modelId, workspace, version, started, branch, quiet, compact, name, variantSeed, whatsNew, notices, changelog, }: BannerProps): JSX.Element;

package/dist/types/console/components/TerminalConsole.d.ts

@@ -24,9 +24,4 @@
  * `indusagi/react-ink`.
  */
 import type { ConsoleProps } from "../contract";
-/**
- * The interactive console surface.
- *
- * @param props the conductor to drive, the resolved theme, and the slash registry
- */
 export declare function TerminalConsole(props: ConsoleProps): JSX.Element;