@narumitw/pi-starship 0.65.2 → 0.67.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +9 -2
  3. package/dist/chunks/{chunk-PZWT7OTP.ts → chunk-URY35OTN.ts} +3 -3
  4. package/dist/chunks/{chunk-5YA3XF7S.ts → chunk-VK26JO5L.ts} +31 -3
  5. package/dist/chunks/chunk-VK26JO5L.ts.map +7 -0
  6. package/dist/chunks/{chunk-RQY2AYI2.ts → chunk-WZ2FWJHK.ts} +2 -2
  7. package/dist/chunks/{command-configuration-menu-JHKQ5SDW.ts → command-configuration-menu-3MMJJX4D.ts} +3 -3
  8. package/dist/chunks/{command-settings-chat-RN2GDMF5.ts → command-settings-chat-NB6YCNUD.ts} +4 -4
  9. package/dist/chunks/{commands-XIRYGV7S.ts → commands-HT6MGWJV.ts} +6 -6
  10. package/dist/index.ts +86 -34
  11. package/dist/index.ts.map +2 -2
  12. package/package.json +1 -1
  13. package/skills/configure-pi-starship/SKILL.md +3 -1
  14. package/skills/configure-pi-starship/references/configuration.md +81 -14
  15. package/skills/configure-pi-starship/references/module-catalog.md +22 -4
  16. package/skills/configure-pi-starship/references/modules.md +31 -1
  17. package/src/config.ts +2 -1
  18. package/src/modules/catalog.ts +4 -0
  19. package/src/modules/extension-status.ts +3 -2
  20. package/src/modules/inspection.ts +3 -2
  21. package/src/modules/render.ts +78 -31
  22. package/src/modules/tokens-per-second.ts +14 -0
  23. package/src/modules/types.ts +1 -0
  24. package/src/pi-starship.ts +4 -7
  25. package/src/root-references.ts +15 -0
  26. package/src/usage.ts +25 -0
  27. package/dist/chunks/chunk-5YA3XF7S.ts.map +0 -7
  28. /package/dist/chunks/{chunk-PZWT7OTP.ts.map → chunk-URY35OTN.ts.map} +0 -0
  29. /package/dist/chunks/{chunk-RQY2AYI2.ts.map → chunk-WZ2FWJHK.ts.map} +0 -0
  30. /package/dist/chunks/{command-configuration-menu-JHKQ5SDW.ts.map → command-configuration-menu-3MMJJX4D.ts.map} +0 -0
  31. /package/dist/chunks/{command-settings-chat-RN2GDMF5.ts.map → command-settings-chat-NB6YCNUD.ts.map} +0 -0
  32. /package/dist/chunks/{commands-XIRYGV7S.ts.map → commands-HT6MGWJV.ts.map} +0 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-starship",
3
- "version": "0.65.2",
3
+ "version": "0.67.0",
4
4
  "description": "Native Starship-style TOML statusline and configuration skill for Pi.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -91,7 +91,9 @@ Do not redirect this workflow to `starship.toml`, `pi-statusline.json`, project-
91
91
 
92
92
  Preserve comments, ordering, unknown fields, and unrelated custom settings unless the user explicitly requests a complete replacement.
93
93
 
94
- Keep the root `format` limited to module names and `$all`.
94
+ Keep the root `format` limited to module names, `$all`, and exact `${extension_status.<raw-key>}` references as defined in [individual extension statuses](references/configuration.md#individual-extension-statuses).
95
+
96
+ Do not infer status-key aliases or convert `:` to `.` in raw keys.
95
97
 
96
98
  Keep each module's `format` limited to that module's documented variables and style variables.
97
99
 
@@ -286,18 +286,7 @@ Module-specific options are catalog-owned and type-checked; unknown options warn
286
286
  [Version formats](#version-formats) support raw and numeric component variables.
287
287
  Detection arrays inspect one bounded listing of the current directory; replacement and fallback rules are [module-specific](modules.md#reachability-and-collection-rules).
288
288
  Language and Kubernetes file detectors support leading `!` rejection rules; [environment detectors](modules.md#environment-detection-and-messages) have separate presence rules.
289
- `[extension_status].icons` accepts arbitrary exact Pi status keys and explicit colon namespace wildcards such as `foo:*`; `fallback` controls unmatched statuses.
290
- Icon matching uses the exact key, the longest `:*` wildcard, a leading status emoji, then `fallback`/`🔌`.
291
- An empty configured icon suppresses only the icon.
292
- `foo:*` matches `foo:server` but not `foo`, `foobar`, or `foo/server`.
293
- `[extension_status].styles` applies a Starship style to each complete status (icon and text) by exact raw key, then longest `:*` wildcard, then optional `fallback`; unmatched statuses inherit the module's `style`.
294
- Separators retain the module style. An explicit `none` style removes the inherited module style for that status.
295
-
296
- Pi does not expose status ownership, so exact raw keys are the reliable third-party contract.
297
- pi-starship does not inspect installed packages, infer aliases, assign known-extension icons, or bridge compatibility keys.
298
- Extension authors may use `<extension-id>` or `<extension-id>:<stable-slot>` for interoperability, but pi-starship does not require it.
299
-
300
- **Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons, or compatibility mappings must use an exact raw status key, an explicit namespace wildcard, a leading emoji in the status value, or `fallback`.
289
+ See [individual extension statuses](#individual-extension-statuses) for exact-key placement, aggregate selection, and `[extension_status]` icon/style matching.
301
290
 
302
291
  ## Configuration schema and validation
303
292
 
@@ -307,7 +296,7 @@ A settings document is one TOML table with these accepted root keys:
307
296
 
308
297
  | Key | Type | Behavior |
309
298
  | --- | --- | --- |
310
- | `format` | string | Root layout whose variables are module names or `$all`. |
299
+ | `format` | string | Root layout whose variables are module names, `$all`, or exact `${extension_status.<raw-key>}` references. |
311
300
  | `palette` | string | Selects one exact table name from `[palettes.<name>]`. |
312
301
  | `palettes` | table of tables | Defines direct color names used by style expressions. |
313
302
  | `<module>` | table | Configures one module listed in [the complete module catalog](module-catalog.md). |
@@ -456,11 +445,89 @@ Unknown fields and comments remain in the settings document even though they are
456
445
  - Styled groups: `[format string](style string)`.
457
446
  - Conditional groups: `(format string)` render only when a nested variable has a non-empty value.
458
447
  - Nested groups are supported.
459
- - `$all` expands enabled modules in the default order and omits modules already referenced explicitly.
448
+ - `$all` expands enabled modules in the default order and omits modules already referenced explicitly; individual extension-status references exclude only their selected keys, not the aggregate module.
460
449
 
461
450
  Module formats can use `$style` in a style expression.
462
451
  Module output keeps its own style when embedded in an outer styled group.
463
452
 
453
+ ### Individual extension statuses
454
+
455
+ Use `${extension_status.<raw-key>}` in the root `format` to place one exact key from Pi's public status map.
456
+ Keep the braces and a non-empty suffix; the complete suffix is the raw key, including case, dots, colons, or slashes.
457
+ These references are not module-local variables or style variables, and root references do not support wildcard matching or per-status configuration tables.
458
+ A `*` in a reference is literal raw-key text, not a wildcard.
459
+ Invalid references produce configuration diagnostics; a valid reference to an absent key renders empty without a warning.
460
+ Keys that cannot fit the existing braced-variable grammar remain available through `$extension_status`.
461
+
462
+ This example places `usage` beside Provider/Model, remaining statuses on an optional line, and `sync` on the final optional line:
463
+
464
+ ```toml
465
+ format = """
466
+ $provider$model( ${extension_status.usage})
467
+ $directory$git_branch$git_status(
468
+ $extension_status)(
469
+ ${extension_status.sync})"""
470
+
471
+ [extension_status.styles]
472
+ usage = "bold cyan"
473
+ sync = "yellow"
474
+ lsp = "green"
475
+ ```
476
+
477
+ All explicit status keys are collected from the complete root format, including nested conditional and styled groups, before rendering.
478
+ Every `$extension_status` excludes those keys regardless of their position or whether their containing group is visible.
479
+ When `$all` reaches `extension_status`, it uses the same remaining-status group.
480
+ An individual reference does not remove that aggregate module from `$all`; an explicit `$extension_status` does.
481
+ Repeated individual or aggregate references render at every written occurrence; they do not consume statuses or share an allowance.
482
+
483
+ Empty or whitespace-only values, including values left empty after terminal-control removal, and pi-starship's own `starship` key are filtered before selection and limiting.
484
+ Statuses whose formatted content is empty, such as a prefix-only value with its icon suppressed, are also omitted before the limit and module format are applied.
485
+ Each expansion selects its requested key or the remaining group in public-map order, then applies `[extension_status].max_statuses` independently.
486
+ The default limit is `5`, with an accepted range of `0` through `100`.
487
+ An individual reference selects at most one status and does not use the aggregate's allowance; its position in the original map does not prevent selection.
488
+ `max_statuses = 0` or `[extension_status].disabled = true` hides all individual and aggregate expansions.
489
+
490
+ Every non-empty expansion reuses `[extension_status].format`, `symbol`, `style`, `separator`, `icons`, `styles`, and the selected palette.
491
+ For an individual reference, `$statuses` contains that one formatted status and `$count` is `1`.
492
+ For the aggregate, `$statuses` joins the selected statuses and `$count` is their number after exclusion and limiting.
493
+ An expansion with no visible status is empty before its module format runs, so static labels, symbols, counts, and separators do not remain.
494
+ Put associated whitespace or a newline inside a conditional group, as above, to hide it with the expansion; literals outside the group remain.
495
+
496
+ Both expansion forms use the same raw-key icon and style maps.
497
+ Quote dotted raw keys in TOML maps: an unquoted `example.worker` defines a nested table rather than one exact key.
498
+ For a hypothetical publisher that emits `example.worker`, use `${extension_status.example.worker}` for placement and quote the key in both maps:
499
+
500
+ ```toml
501
+ [extension_status.icons]
502
+ "example.worker" = "◆"
503
+ "foo:*" = "🧪"
504
+ fallback = "•"
505
+
506
+ [extension_status.styles]
507
+ "example.worker" = "bold green"
508
+ "foo:*" = "bold yellow"
509
+ "foo:error" = "bold red"
510
+ fallback = "dimmed white"
511
+ ```
512
+
513
+ Icon matching uses the exact raw key, the longest `:*` namespace wildcard, a leading status emoji, then configured `fallback` or `🔌`.
514
+ An empty configured icon suppresses only the icon.
515
+ `foo:*` matches `foo:server` but not `foo`, `foobar`, `foo/server`, or `foo.server`.
516
+ There is no `.*` wildcard; use quoted exact dotted keys.
517
+ `styles` applies a Starship style to each complete status (icon and text) by exact raw key, then longest `:*` wildcard, then optional `fallback`.
518
+ Unmatched statuses inherit the module's `style`; explicit `none` removes that inherited style for the status.
519
+ Separators retain the module style, and a raw key keeps the same configured icon/style rules in both forms.
520
+
521
+ Pi does not expose status ownership, so exact raw keys are the reliable third-party contract.
522
+ pi-starship does not normalize, split, or rewrite keys, convert `:` to `.`, inspect installed packages, infer aliases, assign known-extension icons, or bridge compatibility keys.
523
+ Repository-owned publishers currently use only bare aggregate keys; `pi-lsp` publishes only `lsp`, not per-language statuses.
524
+ Authors may use `<extension-id>` for one aggregate status or `<extension-id>.<stable-slot>` for independent channels, but pi-starship neither requires this convention nor creates channels from references.
525
+ Status values and configured display text are sanitized at the display boundary before text transforms or layout; raw keys retain their identity for matching.
526
+
527
+ **Icon migration:** configurations that relied on package-ID aliases, built-in known-extension icons, or compatibility mappings must use an exact raw status key, an explicit `:*` namespace wildcard, a leading emoji in the status value, or `fallback`.
528
+ Existing settings, profiles, presets, and history are not rewritten automatically.
529
+ Before downgrading to a release without individual references, remove those references or restore an earlier TOML document.
530
+
464
531
  ## 🎨 Styles and palettes
465
532
 
466
533
  Style expressions support:
@@ -27,7 +27,7 @@ All enum values are case-sensitive.
27
27
 
28
28
  ## Catalog order
29
29
 
30
- `brand` → `provider` → `model` → `thinking` → `directory` → `git_worktree` → `git_branch` → `github_pr` → `git_commit` → `git_state` → `git_metrics` → `git_status` → `jj_bookmark` → `jj_change` → `jj_metrics` → `jj_status` → `package` → `nodejs` → `python` → `rust` → `golang` → `bun` → `deno` → `mise` → `direnv` → `conda` → `pixi` → `nix_shell` → `guix_shell` → `docker_context` → `kubernetes` → `terraform` → `aws` → `gcloud` → `azure` → `openstack` → `os` → `container` → `hostname` → `username` → `memory_usage` → `battery` → `activity` → `context` → `tokens` → `cache` → `cost` → `time` → `turn` → `fill` → `extension_status`
30
+ `brand` → `provider` → `model` → `thinking` → `directory` → `git_worktree` → `git_branch` → `github_pr` → `git_commit` → `git_state` → `git_metrics` → `git_status` → `jj_bookmark` → `jj_change` → `jj_metrics` → `jj_status` → `package` → `nodejs` → `python` → `rust` → `golang` → `bun` → `deno` → `mise` → `direnv` → `conda` → `pixi` → `nix_shell` → `guix_shell` → `docker_context` → `kubernetes` → `terraform` → `aws` → `gcloud` → `azure` → `openstack` → `os` → `container` → `hostname` → `username` → `memory_usage` → `battery` → `activity` → `context` → `tokens` → `tokens_per_second` → `cache` → `cost` → `time` → `turn` → `fill` → `extension_status`
31
31
 
32
32
  ## Module schemas
33
33
 
@@ -1139,6 +1139,22 @@ Accepted style fields:
1139
1139
  | --- | --- |
1140
1140
  | `style` | `"bold cyan"` |
1141
1141
 
1142
+ ### `tokens_per_second`
1143
+
1144
+ Average output tokens per second for the latest completed assistant response on the active branch.
1145
+
1146
+ - Format variables: `$symbol`, `$rate`.
1147
+ - Style variables in `format`: `$style`.
1148
+ - Default `format`: `"[$rate tok/s ]($style)"`.
1149
+ - Default `symbol`: `""`.
1150
+ - Default `disabled`: `true`.
1151
+
1152
+ Accepted style fields:
1153
+
1154
+ | Field | Default |
1155
+ | --- | --- |
1156
+ | `style` | `"bold cyan"` |
1157
+
1142
1158
  ### `cache`
1143
1159
 
1144
1160
  Prompt-cache usage and latest cache hit rate.
@@ -1231,6 +1247,8 @@ Accepted style fields:
1231
1247
  ### `extension_status`
1232
1248
 
1233
1249
  Statuses published through Pi's extension-neutral status map.
1250
+ Use root `$extension_status` for the remaining group or `${extension_status.<raw-key>}` for one exact status; both use this module's settings and format.
1251
+ See [individual extension statuses](configuration.md#individual-extension-statuses) for selection, `$all` exclusions, counts, empty output, and icon/style matching.
1234
1252
 
1235
1253
  - Format variables: `$symbol`, `$statuses`, `$count`.
1236
1254
  - Style variables in `format`: `$style`.
@@ -1249,6 +1267,6 @@ Additional options:
1249
1267
  | Option | Type | Default | Constraints and meaning |
1250
1268
  | --- | --- | --- | --- |
1251
1269
  | `separator` | string | `" • "` | Text inserted between rendered extension statuses. |
1252
- | `max_statuses` | integer | `5` | Inclusive range 0 through 100. Zero hides all status values. |
1253
- | `icons` | string-to-string table | `{}` | Exact raw status keys, explicit namespace wildcards, and optional fallback. |
1254
- | `styles` | string-to-style table | `{}` | Valid Starship styles by exact raw key, namespace wildcard, or fallback. |
1270
+ | `max_statuses` | integer | `5` | Inclusive range 0 through 100. Limit per expansion after selection and exclusion; zero hides all expansions. |
1271
+ | `icons` | string-to-string table | `{}` | Exact raw status keys, `:*` namespace wildcards, and optional `fallback`; quote dotted keys. |
1272
+ | `styles` | string-to-style table | `{}` | Valid Starship styles by exact raw key, `:*` namespace wildcard, or `fallback`; quote dotted keys. |
@@ -27,6 +27,7 @@ Use this authoritative public reference whenever a question or change involves a
27
27
  | `activity` | `$symbol`, `$state`, `$tool`, `$count`, `$kind`, `$title`, `$text` | Extension UI waits, active tools, streaming, completion, or idle |
28
28
  | `context` | `$symbol`, `$percentage`, `$tokens`, `$window` | Context-window use |
29
29
  | `tokens` | `$symbol`, `$input`, `$output`, `$total` | Token totals |
30
+ | `tokens_per_second` | `$symbol`, `$rate` | Latest completed assistant response's average output rate on the active branch; disabled by default |
30
31
  | `cache` | `$symbol`, `$rate`, `$read`, `$write` | Prompt-cache reads, writes, and latest hit rate; disabled by default |
31
32
  | `cost` | `$symbol`, `$cost`, `$subscription`, `$source` | Session cost, provider-total provenance, and optional `(sub)` marker |
32
33
  | `time` | `$symbol`, `$time` | Formatted clock; local `HH:mm` by default |
@@ -62,7 +63,10 @@ For exact default formats, symbols, enabled state, accepted style fields, displa
62
63
  ## Reachability and collection rules
63
64
 
64
65
  A module contributes work only when it is enabled and reachable from the root `format` directly or through `$all`.
65
- Reachability activates that module's collector at module scope, even when its module format references only `$symbol`.
66
+ A valid root `${extension_status.<raw-key>}` also makes `extension_status` reachable without the aggregate variable; it reads Pi's existing status map, not a producer or collector.
67
+ For that module, inspection uses the status expansions that participate in the layout, including individual-only layouts.
68
+ See [individual extension statuses](configuration.md#individual-extension-statuses) for exact-key selection, aggregate exclusions, limits, and shared formatting.
69
+ For modules with a collector, reachability activates it at module scope, even when the module format references only `$symbol`.
66
70
  Omitting a data variable does not prevent the package, deployment, cloud, or execution collectors from reading that reachable module's allowlisted files and environment metadata.
67
71
  Language project detection also runs at module scope. Version commands, requirement-file reads, and optional Python/Rust values are variable-gated, except for explicitly enabled Node.js/Go requirement styling as described below.
68
72
  The mise health, direnv status, Pixi version, and Terraform/OpenTofu version commands are likewise variable-gated, but their module-level detection and non-command metadata reads still occur when reachable.
@@ -229,6 +233,32 @@ These are inert labels, not evidence of cluster access or valid credentials.
229
233
  - Subscription-backed OAuth models and `kimi-coding` set cost `$subscription` to `(sub)`.
230
234
  The dollar value is usage cost, not proof of an amount billed under a subscription.
231
235
 
236
+ ### Tokens per second
237
+
238
+ `tokens_per_second` shows the latest completed assistant response on the active branch, not cumulative session throughput.
239
+ Enable it explicitly and include it in the root format, or use `$all` after enabling it:
240
+
241
+ ```toml
242
+ format = "$model$tokens$tokens_per_second"
243
+
244
+ [tokens_per_second]
245
+ disabled = false
246
+ format = "[$rate tok/s ]($style)"
247
+ style = "bold cyan"
248
+ ```
249
+
250
+ `$rate` is `usage.output / (durationMs / 1000)`, formatted to one decimal place; 85 output tokens over 2 seconds displays `42.5 tok/s`.
251
+ The duration is Pi's recorded full-response duration, including request latency and thinking time, but not subsequent tool execution or time between responses.
252
+ Output tokens use the provider's accounting, which can include reasoning tokens; this is not a visible-text estimate or a decode-only speed measurement.
253
+ Responses ending with `stop`, `length`, or `toolUse` can supply a rate, including tool-calling responses before their tools finish.
254
+
255
+ The latest completed response remains visible while a new response is streaming; partial usage is not estimated.
256
+ A latest failed, aborted, pending, deferred, or untimed response hides the module instead of showing an older response's rate.
257
+ Missing, nonfinite, or negative output counts, nonpositive or nonfinite durations, and nonfinite calculated rates also hide the module; valid zero output shows `0.0 tok/s`.
258
+ Older sessions and some deferred results have no recorded duration.
259
+ Resume, reload, fork, and tree navigation derive the value from the active branch, so abandoned-branch responses, tool results, compactions, branch summaries, and cache-warming usage do not supply the rate.
260
+ This module does not change the cumulative accounting used by `tokens`, `cache`, or `cost`.
261
+
232
262
  ### Directory, Git, and environment contraction
233
263
 
234
264
  These modules keep their display policy local. Existing Pi defaults remain unchanged:
package/src/config.ts CHANGED
@@ -19,6 +19,7 @@ import { type FormatNode, formatVariables, parseFormat, styleVariables } from ".
19
19
  import { type ColorPalette, isValidStyle, parseColor } from "./format/style.js";
20
20
  import { MODULE_DEFINITIONS, MODULE_NAMES, type ModuleName } from "./modules/catalog.js";
21
21
  import type { ModuleDisplayConfig, ModuleOptionSchema, ModuleOptionValue, ModuleStyleRule } from "./modules/types.js";
22
+ import { extensionStatusKey } from "./root-references.js";
22
23
 
23
24
  export const CONFIG_FILE_NAME = "pi-starship.toml";
24
25
  export { MODULE_NAMES, type ModuleName } from "./modules/catalog.js";
@@ -641,7 +642,7 @@ function validateFormatVariables(
641
642
  diagnostics: ConfigDiagnostic[],
642
643
  ) {
643
644
  for (const variable of formatVariables(ast)) {
644
- if (allowed.has(variable)) continue;
645
+ if (allowed.has(variable) || (path === "format" && extensionStatusKey(variable) !== undefined)) continue;
645
646
  diagnostics.push(
646
647
  diagnostic("warning", path, `Unknown variable ${JSON.stringify(variable)} in ${path} was ignored`),
647
648
  );
@@ -26,6 +26,7 @@ import { systemModules } from "./system.js";
26
26
  import { thinkingModule } from "./thinking.js";
27
27
  import { timeModule } from "./time.js";
28
28
  import { tokensModule } from "./tokens.js";
29
+ import { tokensPerSecondModule } from "./tokens-per-second.js";
29
30
  import { turnModule } from "./turn.js";
30
31
  import type { ModuleDefinition } from "./types.js";
31
32
 
@@ -53,6 +54,7 @@ const MODULE_IMPLEMENTATIONS = [
53
54
  activityModule,
54
55
  contextModule,
55
56
  tokensModule,
57
+ tokensPerSecondModule,
56
58
  cacheModule,
57
59
  costModule,
58
60
  timeModule,
@@ -114,6 +116,8 @@ const MODULE_DESCRIPTIONS = {
114
116
  thinking: "Current Pi thinking level or streaming state.",
115
117
  time: "Current local time.",
116
118
  tokens: "Session input and output token totals.",
119
+ tokens_per_second:
120
+ "Average output tokens per second for the latest completed assistant response on the active branch.",
117
121
  turn: "Current user-turn count.",
118
122
  username: "Current user identity when configured to display.",
119
123
  } as const satisfies Record<ModuleName, string>;
@@ -13,8 +13,9 @@ export const extensionStatusModule = defineModule({
13
13
  values: ({ runtime, extensionStatus, palette }) => {
14
14
  const statuses = [...runtime.extensionStatuses.entries()]
15
15
  .filter(([key, value]) => key !== "starship" && value.trim())
16
- .slice(0, extensionStatus.maxStatuses)
17
- .map(([key, value]) => ({ key, text: formatExtensionStatus(key, value, extensionStatus.icons) }));
16
+ .map(([key, value]) => ({ key, text: formatExtensionStatus(key, value, extensionStatus.icons) }))
17
+ .filter(({ text }) => text.trim())
18
+ .slice(0, extensionStatus.maxStatuses);
18
19
  if (statuses.length === 0) return undefined;
19
20
  const { separator, styles } = extensionStatus;
20
21
  const content =
@@ -1,6 +1,7 @@
1
1
  import { stripVTControlCharacters } from "node:util";
2
2
  import type { StarshipConfig } from "../config.js";
3
3
  import { formatVariables } from "../format/formatter.js";
4
+ import { referencesModule } from "../root-references.js";
4
5
  import { MODULE_DEFINITIONS, type ModuleName } from "./catalog.js";
5
6
  import { reachableModuleRequirements, renderStatusline } from "./render.js";
6
7
  import type { StarshipRuntimeSnapshot } from "./types.js";
@@ -52,7 +53,7 @@ export function inspectStatuslineModules(
52
53
  definition,
53
54
  state,
54
55
  preview,
55
- includeAll || rootVariables.has(definition.name),
56
+ includeAll || referencesModule(rootVariables, definition.name),
56
57
  reachable,
57
58
  );
58
59
  });
@@ -76,7 +77,7 @@ export function inspectUnavailableModules(config: StarshipConfig): StatuslineIns
76
77
  definition,
77
78
  state,
78
79
  "",
79
- includeAll || rootVariables.has(definition.name),
80
+ includeAll || referencesModule(rootVariables, definition.name),
80
81
  reachable,
81
82
  );
82
83
  }),
@@ -11,10 +11,12 @@ import {
11
11
  } from "../format/style.js";
12
12
  import { sanitizeFormatText } from "../format/terminal-safety.js";
13
13
  import type { ThemeColors } from "../format/theme-colors.js";
14
+ import { extensionStatusKey, referencesModule } from "../root-references.js";
14
15
  import { MODULE_DEFINITIONS, MODULE_NAMES, type ModuleName } from "./catalog.js";
15
16
  import { directoryAlternateFormat } from "./directory.js";
16
17
  import { resolveStyleRule } from "./style-rules.js";
17
18
  import type {
19
+ ModuleDefinition,
18
20
  ModuleOptionValue,
19
21
  ModuleStyleContext,
20
22
  ModuleValueContext,
@@ -30,6 +32,15 @@ export function renderStatusline(
30
32
  themeColors?: ThemeColors,
31
33
  ): RenderedStatusline<ModuleName> {
32
34
  const palette = activePalette(config);
35
+ const explicitModules = formatVariables(config.formatAst);
36
+ const statusReferences = new Map(
37
+ [...explicitModules].flatMap((reference) => {
38
+ const key = extensionStatusKey(reference);
39
+ return key === undefined ? [] : [[reference, key] as const];
40
+ }),
41
+ );
42
+ const selectedKeys = new Set(statusReferences.values());
43
+ const statusChunks = new Map<string, StyledChunk[]>();
33
44
  const modules = {} as Record<ModuleName, StyledChunk[]>;
34
45
  const layoutModules = {} as Record<ModuleName, LayoutChunk[]>;
35
46
  for (const name of MODULE_NAMES) {
@@ -40,46 +51,47 @@ export function renderStatusline(
40
51
  const name = definition.name;
41
52
  const module = config.modules[name];
42
53
  const context = valueContext(config, name, runtime, palette);
43
- const values = definition.values(context);
44
- if (!values) continue;
45
- const styleContext: ModuleStyleContext = {
46
- runtime,
47
- style: module.style,
48
- styles: module.styles,
49
- display: module.display,
50
- options: context.options,
51
- };
52
- const baseStyleVariables = definition.resolveStyleVariables
53
- ? definition.resolveStyleVariables(styleContext)
54
- : { style: module.style };
55
- if (!baseStyleVariables) continue;
56
- const ruleStyle = definition.styleRuleSelectors
57
- ? resolveStyleRule(module.styleRules, definition.styleRuleSelectors, styleContext)
58
- : undefined;
59
- const styleVariables = ruleStyle === undefined ? baseStyleVariables : { ...baseStyleVariables, style: ruleStyle };
60
- const contentValues: Record<string, FormatValue> = Object.fromEntries(
61
- definition.variables.flatMap((variable) =>
62
- Object.hasOwn(values, variable) ? [[variable, values[variable]]] : [],
63
- ),
64
- );
65
- const alternate = definition.resolveFormat?.(context, values);
66
- const rendered = renderModule(
67
- alternate === undefined ? module : { ...module, formatAst: parseFormat(alternate) },
68
- contentValues,
69
- styleVariables,
70
- palette,
71
- );
54
+ if (name === "extension_status" && statusReferences.size > 0) {
55
+ const statuses = context.runtime.extensionStatuses;
56
+ for (const [reference, key] of statusReferences) {
57
+ const value = statuses.get(key);
58
+ const selected = new Map(value === undefined ? [] : [[key, value]]);
59
+ statusChunks.set(
60
+ reference,
61
+ renderDefinition(
62
+ definition,
63
+ module,
64
+ { ...context, runtime: { ...context.runtime, extensionStatuses: selected } },
65
+ runtime,
66
+ ) ?? [],
67
+ );
68
+ }
69
+ context.runtime = {
70
+ ...context.runtime,
71
+ extensionStatuses: new Map([...statuses].filter(([key]) => !selectedKeys.has(key))),
72
+ };
73
+ }
74
+ const rendered = renderDefinition(definition, module, context, runtime);
75
+ if (!rendered) continue;
72
76
  modules[name] = rendered;
73
77
  layoutModules[name] =
74
78
  definition.layout === "fill" && !module.disabled ? [{ type: "fill", pattern: rendered }] : rendered;
75
79
  }
76
80
 
77
- const explicitModules = formatVariables(config.formatAst);
78
81
  const all = MODULE_NAMES.flatMap((name) =>
79
82
  explicitModules.has(name) || config.modules[name].disabled ? [] : layoutModules[name],
80
83
  );
81
84
  const rootVariables: Record<string, FormatValue> = { all };
82
85
  for (const name of MODULE_NAMES) rootVariables[name] = layoutModules[name];
86
+ for (const [reference, rendered] of statusChunks) rootVariables[reference] = rendered;
87
+ if (statusReferences.size > 0) {
88
+ // Inspection shows participating expansions once, not statuses absent from the layout.
89
+ modules.extension_status = [...explicitModules].flatMap((reference) =>
90
+ reference === "extension_status" || (reference === "all" && !explicitModules.has("extension_status"))
91
+ ? modules.extension_status
92
+ : (statusChunks.get(reference) ?? []),
93
+ );
94
+ }
83
95
  const layout = renderFormat(config.formatAst, { variables: rootVariables, palette });
84
96
  const chunks = resolveFillLayout(layout, width);
85
97
  return {
@@ -89,6 +101,41 @@ export function renderStatusline(
89
101
  };
90
102
  }
91
103
 
104
+ function renderDefinition(
105
+ definition: ModuleDefinition<ModuleName>,
106
+ module: ModuleConfig,
107
+ context: ModuleValueContext,
108
+ runtime: StarshipRuntimeSnapshot,
109
+ ): StyledChunk[] | undefined {
110
+ const values = definition.values(context);
111
+ if (!values) return undefined;
112
+ const styleContext: ModuleStyleContext = {
113
+ runtime,
114
+ style: module.style,
115
+ styles: module.styles,
116
+ display: module.display,
117
+ options: context.options,
118
+ };
119
+ const baseStyleVariables = definition.resolveStyleVariables
120
+ ? definition.resolveStyleVariables(styleContext)
121
+ : { style: module.style };
122
+ if (!baseStyleVariables) return undefined;
123
+ const ruleStyle = definition.styleRuleSelectors
124
+ ? resolveStyleRule(module.styleRules, definition.styleRuleSelectors, styleContext)
125
+ : undefined;
126
+ const styleVariables = ruleStyle === undefined ? baseStyleVariables : { ...baseStyleVariables, style: ruleStyle };
127
+ const contentValues: Record<string, FormatValue> = Object.fromEntries(
128
+ definition.variables.flatMap((variable) => (Object.hasOwn(values, variable) ? [[variable, values[variable]]] : [])),
129
+ );
130
+ const alternate = definition.resolveFormat?.(context, values);
131
+ return renderModule(
132
+ alternate === undefined ? module : { ...module, formatAst: parseFormat(alternate) },
133
+ contentValues,
134
+ styleVariables,
135
+ context.palette,
136
+ );
137
+ }
138
+
92
139
  function valueContext(
93
140
  config: StarshipConfig,
94
141
  name: ModuleName,
@@ -194,7 +241,7 @@ export function reachableModuleRequirements(config: StarshipConfig): ReadonlyMap
194
241
  const requirements = new Map<ModuleName, ReadonlySet<string>>();
195
242
  for (const definition of MODULE_DEFINITIONS) {
196
243
  if (config.modules[definition.name].disabled) continue;
197
- if (!includeAll && !rootVariables.has(definition.name)) continue;
244
+ if (!includeAll && !referencesModule(rootVariables, definition.name)) continue;
198
245
  const variables = formatVariables(config.modules[definition.name].formatAst);
199
246
  if (definition.name === "directory") {
200
247
  const alternate = directoryAlternateFormat(config.modules.directory.options, config.modules.directory.styles);
@@ -0,0 +1,14 @@
1
+ import { defineModule } from "./types.js";
2
+
3
+ export const tokensPerSecondModule = defineModule({
4
+ name: "tokens_per_second",
5
+ variables: ["symbol", "rate"],
6
+ defaults: {
7
+ format: "[$rate tok/s ]($style)",
8
+ symbol: "",
9
+ style: "bold cyan",
10
+ disabled: true,
11
+ },
12
+ values: ({ runtime }) =>
13
+ runtime.tokensPerSecond === undefined ? undefined : { rate: runtime.tokensPerSecond.toFixed(1) },
14
+ });
@@ -112,6 +112,7 @@ export interface StarshipRuntimeSnapshot {
112
112
  costTotalFromProvider?: boolean;
113
113
  latestCacheHitRate?: number;
114
114
  };
115
+ tokensPerSecond?: number;
115
116
  usingSubscription: boolean;
116
117
  gitBranch: string | null;
117
118
  gitBranchDetails?: GitBranchSnapshot;
@@ -29,7 +29,7 @@ import {
29
29
  type WorkspaceRefreshInput,
30
30
  workspaceSnapshotEqual,
31
31
  } from "./runtime/workspace.js";
32
- import { summarizeFooterUsage } from "./usage.js";
32
+ import { latestTokensPerSecond, summarizeFooterUsage } from "./usage.js";
33
33
 
34
34
  const REFRESH_INTERVAL_MS = 30_000;
35
35
  const GITHUB_PR_REFRESH_INTERVAL_MS = 60_000;
@@ -711,19 +711,21 @@ function runtimeSnapshot(
711
711
  footerData: Pick<ReadonlyFooterDataProvider, "getGitBranch" | "getExtensionStatuses">,
712
712
  runtime: RuntimeState,
713
713
  ): StarshipRuntimeSnapshot {
714
+ const branch = ctx.sessionManager.getBranch();
714
715
  return {
715
716
  cwd: ctx.cwd,
716
717
  homeDir: homedir(),
717
718
  gitRoot: runtime.git?.root,
718
719
  model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
719
720
  thinkingLevel: runtime.thinkingLevel,
720
- turnCount: userTurnCount(ctx),
721
+ turnCount: branch.filter((entry) => entry.type === "message" && entry.message.role === "user").length,
721
722
  activeTools: runtime.activeTools,
722
723
  isStreaming: runtime.isStreaming,
723
724
  uiPrompt: runtime.uiPrompt,
724
725
  lastCompletedTool: runtime.lastCompletedTool,
725
726
  contextUsage: ctx.getContextUsage() ?? undefined,
726
727
  tokenTotals: summarizeFooterUsage(ctx.sessionManager.getEntries()),
728
+ tokensPerSecond: latestTokensPerSecond(branch),
727
729
  usingSubscription: isSubscriptionBacked(ctx),
728
730
  gitBranch: runtime.git?.branch?.name ?? footerData.getGitBranch(),
729
731
  gitBranchDetails: runtime.git?.branch,
@@ -739,11 +741,6 @@ function runtimeSnapshot(
739
741
  };
740
742
  }
741
743
 
742
- function userTurnCount(ctx: ExtensionContext): number {
743
- return ctx.sessionManager.getBranch().filter((entry) => entry.type === "message" && entry.message.role === "user")
744
- .length;
745
- }
746
-
747
744
  function isSubscriptionBacked(ctx: ExtensionContext): boolean {
748
745
  const model = ctx.model;
749
746
  return model !== undefined && (model.provider === "kimi-coding" || ctx.modelRegistry.isUsingOAuth(model));
@@ -0,0 +1,15 @@
1
+ const EXTENSION_STATUS_PREFIX = "extension_status.";
2
+
3
+ /** The suffix is an exact public status key, not a path or namespace selector. */
4
+ export function extensionStatusKey(reference: string): string | undefined {
5
+ if (!reference.startsWith(EXTENSION_STATUS_PREFIX)) return undefined;
6
+ const key = reference.slice(EXTENSION_STATUS_PREFIX.length);
7
+ return key.length > 0 ? key : undefined;
8
+ }
9
+
10
+ export function referencesModule(references: ReadonlySet<string>, module: string): boolean {
11
+ return (
12
+ references.has(module) ||
13
+ (module === "extension_status" && [...references].some((reference) => extensionStatusKey(reference) !== undefined))
14
+ );
15
+ }
package/src/usage.ts CHANGED
@@ -18,6 +18,31 @@ export interface FooterUsageSummary {
18
18
  latestCacheHitRate?: number;
19
19
  }
20
20
 
21
+ /** Use the latest assistant only: an untimed or incomplete response must not expose an older rate. */
22
+ export function latestTokensPerSecond(branch: readonly SessionEntry[]): number | undefined {
23
+ for (let index = branch.length - 1; index >= 0; index -= 1) {
24
+ const entry = branch[index];
25
+ if (entry?.type !== "message" || entry.message.role !== "assistant") continue;
26
+ const { stopReason, durationMs, usage } = entry.message;
27
+ if (stopReason !== "stop" && stopReason !== "length" && stopReason !== "toolUse") return undefined;
28
+ const output = usage?.output;
29
+ if (
30
+ typeof durationMs !== "number" ||
31
+ !Number.isFinite(durationMs) ||
32
+ durationMs <= 0 ||
33
+ typeof output !== "number" ||
34
+ !Number.isFinite(output) ||
35
+ output < 0
36
+ ) {
37
+ return undefined;
38
+ }
39
+ // Pi times the complete response, including request latency, not just streamed text.
40
+ const rate = output / (durationMs / 1000);
41
+ return Number.isFinite(rate) ? rate : undefined;
42
+ }
43
+ return undefined;
44
+ }
45
+
21
46
  export function summarizeFooterUsage(entries: readonly SessionEntry[]): FooterUsageSummary {
22
47
  const totals: FooterUsageSummary = {
23
48
  input: 0,