typeclaw 0.1.5 → 0.1.6

package/src/skills/typeclaw-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-config
-description: "Read or edit typeclaw.json: model, port, mounts, plugins, channels (Discord allow rules + engagement), portForward (auto port forwarding policy), docker.file (tmux/gh/python/ffmpeg toggles + append), git.ignore.append. Also: any question about a default value or whether a behavior is already on by default — port forwarding, channel visibility, model choice, container packages (tmux/gh/python on by default; ffmpeg off), anything ending in 'by default', 'automatically', 'out of the box', 'do I need to configure', 'is X on', 'what does X default to', '기본값', '기본적으로', '자동으로', '디폴트'. MUST load before saying you do not know what X defaults to, or proposing to add a field whose default the user is asking about — most fields already default to the behavior the user expects (portForward defaults to forwarding every container LISTEN; tmux/gh/python are pre-installed in the container; no edit needed). Read it before touching typeclaw.json — strict schema, mix of live-reloadable and restart-required fields."
+description: "Read or edit typeclaw.json: model, port, mounts, plugins, channels (per-adapter engagement and history; access control lives in roles — see typeclaw-permissions), portForward (auto port forwarding policy), docker.file (tmux/gh/python/ffmpeg toggles + append), git.ignore.append. Also: any question about a default value or whether a behavior is already on by default — port forwarding, channel visibility, model choice, container packages (tmux/gh/python on by default; ffmpeg off), anything ending in 'by default', 'automatically', 'out of the box', 'do I need to configure', 'is X on', 'what does X default to', '기본값', '기본적으로', '자동으로', '디폴트'. MUST load before saying you do not know what X defaults to, or proposing to add a field whose default the user is asking about — most fields already default to the behavior the user expects (portForward defaults to forwarding every container LISTEN; tmux/gh/python are pre-installed in the container; no edit needed). Read it before touching typeclaw.json — strict schema, mix of live-reloadable and restart-required fields."
 ---
 
 # typeclaw-config
@@ -18,7 +18,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
 - `mounts` — additional host directories the user has chosen to expose to you. Each entry produces a `docker run -v <hostPath>:/agent/mounts/<name>` flag at `typeclaw start` time, so the directory shows up at `mounts/<name>` inside your agent folder. **The launcher reads this; the running container does not.** Editing `mounts` only takes effect on the next `typeclaw start`. **Restart-required.**
 - `plugins` — array of plugin package names loaded at server boot. **Restart-required.**
 - `alias` — additional names the agent answers to when a channel message contains its name in plain text (no `<@id>` mention). The agent folder's directory name (`basename(agentDir)`) is always implicit; `alias` adds further forms (Latin transliteration, nicknames, Korean particles, etc.). Used by the channel engagement layer alongside the structural mention/reply/dm triggers. **Live-reloadable.**
-- `channels` — per-adapter allow rules and engagement triggers that gate which external messenger channels (today: Discord) you can read from and post to. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
+- `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, KakaoTalk). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
 - `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated apt packages (`tmux`, `gh`, `python` default `true`; `ffmpeg` defaults `false`) — set the toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python` is boolean-only). (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. Lives under the `docker` namespace alongside future Docker-related blocks (e.g. `docker.compose`). **Restart-required** (next `typeclaw start` rebuilds the image).
 - `git.ignore.append` — extra `.gitignore` patterns `typeclaw start` splices into the TypeClaw-owned `.gitignore` before the protected TypeClaw rules. The whole `.gitignore` is rewritten and auto-committed on every `start` when it changes; `append` is the supported escape hatch for local ignore patterns without editing the managed file by hand. Lives under the `git` namespace. **Restart-required** (next `typeclaw start` refreshes and commits `.gitignore`).
 - `portForward` — allow/deny policy for the auto port-forwarder (the host-stage `_hostd` daemon's portbroker). When the agent runs a server inside the container that LISTENs on a TCP port, the broker proxies it to the same port number on `127.0.0.1` of the host so the user can hit it directly. `portForward` decides which ports are allowed through. **Restart-required** — the broker captures the policy at register time on `typeclaw start`.
@@ -47,14 +47,14 @@ You yourself cannot run `typeclaw restart` — that is a host-stage command and
 | `mounts`      | no       | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**                                                                                                                                                                                                                    |
 | `plugins`     | no       | array of strings | Plugin package names loaded at server boot. Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                                                         |
 | `alias`       | no       | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Alias** section below. **Live-reloadable.**                                                                                                                       |
-| `channels`    | no       | object           | Per-adapter allow rules and engagement triggers for external messengers. Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds a `discord-bot` block only if the user said yes to "Wire a Discord bot?" during the wizard and supplied a token. **Live-reloadable.** See **Channels** section below.                                                                                                                                               |
+| `channels`    | no       | object           | Per-adapter engagement triggers and history-prefetch knobs for external messengers. Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill. **Live-reloadable.** See **Channels** section below.                                                                   |
 | `portForward` | no       | object           | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.                                                                                                                                                                                      |
 | `docker`      | no       | object           | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`) gate opinionated apt packages; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
 | `git`         | no       | object           | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below.                                                                                                |
 
 > **Top-level keys not in this table are not "ignored unknowns" anymore** — they are reserved for **plugin config blocks**. The schema's `catchall(z.unknown())` preserves them, and the plugin loader hands each block to its owning plugin's `configSchema` for validation. The bundled memory plugin owns `memory` at the top level — see the `typeclaw-memory` skill for that block's semantics. Do not write a top-level key unless you know which plugin owns it.
 
-Within the well-known ten (`$schema`, `port`, `model`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `docker`, `git`), **fields the schema doesn't predeclare are silently dropped**. Legacy top-level `dockerfile` and `gitignore` keys are migrated to `docker.file` / `git.ignore` automatically the first time the CLI loads the file — see **Legacy migration** below. Do not invent runtime fields like `provider`, `apiKey`, `temperature`, `maxTokens`, `systemPrompt`, `tools`, `timeout`, etc. — those are not plugin blocks, they are imaginary. If the user asks for one, say it is not yet supported and (if it makes sense) suggest they file a request.
+Within the well-known ten (`$schema`, `port`, `models`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `docker`, `git`), **fields the schema doesn't predeclare are silently dropped**. Legacy top-level `dockerfile` and `gitignore` keys are migrated to `docker.file` / `git.ignore` automatically the first time the CLI loads the file — see **Legacy migration** below. Do not invent runtime fields like `provider`, `apiKey`, `temperature`, `maxTokens`, `systemPrompt`, `tools`, `timeout`, etc. — those are not plugin blocks, they are imaginary. If the user asks for one, say it is not yet supported and (if it makes sense) suggest they file a request.
 
 A scaffolded `typeclaw.json` looks like:
 
@@ -71,11 +71,11 @@ If the user said yes to "Wire a Discord bot?" during `typeclaw init`, the scaffo
 
 ```json
 "channels": {
-  "discord-bot": { "allow": ["*"] }
+  "discord-bot": {}
 }
 ```
 
-`allow: ["*"]` means "every guild channel and every DM" — appropriate for a single-user dev setup. The wizard asks the user to confirm `["*"]` and warns them when they decline, but the current scaffold writes `["*"]` either way and expects the user to narrow it by hand afterwards. **If the user said they wanted a narrower allow list during init, do not assume the scaffold honored that — read `typeclaw.json` first.** For shared servers, narrow the allow list before joining (see **Channels** below).
+The empty block declares the adapter to the runtime — the schema fills in `enabled: true`, default engagement triggers, and history prefetch. **Access control is separate**: by default an adapter with no `roles` block matching the speaker resolves to `guest` and the router drops every inbound. To let conversations through, declare a `roles` block (see the `typeclaw-permissions` skill). For example, `"roles": { "member": { "match": ["discord:<guild>"] } }` lets every member of that guild reach the agent on the `channel.respond` permission.
 
 ## Mounts
 
@@ -128,39 +128,21 @@ The `mounts/` directory itself is **gitignored** in your agent folder. The mount
 
 ## Channels
 
-`channels` configures which external messenger channels you can read from and post to. **Today the only adapter is `discord-bot`.** The shape is `channels: { "<adapter-id>": { allow, engagement, enabled } }`.
+`channels` configures which external messenger adapters are enabled and how the engagement layer should behave on each. **Access control lives in `roles`, not here** — to admit a chat, declare a role match-rule that covers it (see `typeclaw-permissions`). The shape is `channels: { "<adapter-id>": { engagement, history, enabled } }`. Today the adapters are `discord-bot`, `slack-bot`, `telegram-bot`, and `kakaotalk`.
 
-The channels block is **live-reloadable** — edits take effect on the next `reload`, no container restart. This is intentional: allow-rule changes need to feel immediate, otherwise the user has to restart you every time they want to add a channel.
+The channels block is **live-reloadable** — edits take effect on the next `reload`, no container restart.
 
 ### Adapter block
 
 Each entry in `channels` is keyed by adapter id and has this shape:
 
-| Field        | Required | Type             | Notes                                                                                                                                                        |
-| ------------ | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `allow`      | no       | array of strings | List of allow rules. Defaults to `[]`, which means **the agent cannot post anywhere and the inbound bridge gates every message**. See **Allow rules** below. |
-| `engagement` | no       | object           | When the agent should auto-reply vs. stay silent. Defaults to mention/reply/dm with 5-minute reply stickiness. See **Engagement** below.                     |
-| `enabled`    | no       | boolean          | Defaults to `true`. Set `false` to disable the adapter entirely without removing its config.                                                                 |
+| Field        | Required | Type    | Notes                                                                                                                                                                                    |
+| ------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `engagement` | no       | object  | When the agent should auto-reply vs. stay silent. Defaults to mention/reply/dm with 5-minute reply stickiness. See **Engagement** below.                                                 |
+| `history`    | no       | object  | Cold-start prefetch windows for `(thread.head, thread.tail, channel.tail)`. Set any to `0` to disable that side. Defaults to `{ thread: { head: 3, tail: 10 }, channel: { tail: 10 } }`. |
+| `enabled`    | no       | boolean | Defaults to `true`. Set `false` to disable the adapter entirely without removing its config.                                                                                             |
 
-`allow: []` is **not** the same as "deny everything from being delivered to the agent" — the inbound side may still hand you events for processing depending on engagement, but the `channel_send` tool will refuse to post anywhere. Conversely, `allow: ["*"]` does not turn engagement off; engagement and allow are independent gates.
-
-### Allow rules
-
-Each entry in `allow` is a string matching one of the patterns below. Workspace `@dm` is the literal placeholder for direct messages (Discord doesn't expose a guild id for DMs).
-
-| Rule                   | Matches                                                                |
-| ---------------------- | ---------------------------------------------------------------------- |
-| `*`                    | Every guild channel **and** every DM (full firehose).                  |
-| `guild:*`              | Every channel in every guild. Does **not** include DMs.                |
-| `guild:<id>`           | Every channel in guild `<id>`.                                         |
-| `guild:<id>/<channel>` | Channel `<channel>` in guild `<id>` only.                              |
-| `channel:<id>`         | Channel `<id>` in any guild (Discord channel IDs are globally unique). |
-| `dm:*`                 | Every DM channel. Does **not** include guild channels.                 |
-| `dm:<id>`              | DM channel `<id>` only.                                                |
-
-The schema validates each rule string at load. **Bad rule = config load fails**, the runtime refuses to boot or refuses the reload. Don't fudge this; the regex is strict (numeric IDs only).
-
-`channel:<id>` is the most surgical option and the right default when the user says "let me talk to you in #the-channel-i'm-pointing-at" — channel IDs are globally unique so you don't need the guild id. `guild:<id>` is convenient on a server you fully trust. `*` and `guild:*` are firehose patterns; only set them in single-user setups.
+To stop the agent answering in a specific channel, narrow the `roles` block so the speaking author's role no longer carries `channel.respond` — engagement triggers gate wake-up _given_ the message is admitted; `channel.respond` gates whether the message is admitted at all.
 
 ### Engagement
 
@@ -181,59 +163,51 @@ The schema validates each rule string at load. **Bad rule = config load fails**,
   - `perReply` means: after the agent replies to a user, follow-up messages from that same user in that same channel within the window also wake the loop, even without a mention. The window is bounded server-side (`1` to `86_400_000` ms — 1 ms to 24 hours).
   - `"off"` disables stickiness — the agent only wakes on explicit triggers.
 
-There is also a **solo-human fallback** built into the runtime that is **not configurable** through `engagement`: in any allow-listed channel where the participants cache currently holds at most one distinct human author, every admitted inbound wakes the loop, regardless of `trigger` or `stickiness`. The fallback turns off the moment a second distinct human posts in that channel. This makes "private dev channel with one human and the bot" work without forcing an `@mention` on every message; clearing `trigger` to `[]` does **not** override it. If a user wants strict mention-only behavior in a one-human channel today, the answer is "wait for the post-v0.3 engagement-config work" — not a config edit.
+There is also a **solo-human fallback** built into the runtime that is **not configurable** through `engagement`: in any channel where the participants cache currently holds at most one distinct human author, every admitted inbound wakes the loop, regardless of `trigger` or `stickiness`. The fallback turns off the moment a second distinct human posts in that channel. This makes "private dev channel with one human and the bot" work without forcing an `@mention` on every message; clearing `trigger` to `[]` does **not** override it.
 
-**Engagement does not gate posting.** It gates whether you wake up. If you decide to call `channel_send` to a channel that isn't in `allow`, the tool returns `{ ok: false, error }` regardless of engagement.
-
-To make the agent silent in a channel without removing it from `allow`, the right move is usually `engagement: { trigger: [], stickiness: "off" }`, **not** removing the allow rule — removing the allow rule cuts off both inbound visibility and outbound posting, which is rarely what the user means by "stop replying". Caveat: in a one-human channel the solo-human fallback overrides `trigger: []` and the agent will still wake; the only way to silence the bot in that case is to remove the allow rule (or add a second human to the channel).
+**Engagement does not gate access.** Access is gated by `permissions.has(origin, 'channel.respond')` — see the `typeclaw-permissions` skill. Engagement decides whether an _admitted_ inbound wakes the loop or sits in the context buffer.
 
 ### Example
 
 ```json
 "channels": {
   "discord-bot": {
-    "allow": [
-      "guild:123456789012345678/987654321098765432",
-      "dm:*"
-    ],
     "engagement": {
       "trigger": ["mention", "reply", "dm"],
       "stickiness": { "perReply": { "window": 300000 } }
     },
     "enabled": true
   }
+},
+"roles": {
+  "member": { "match": ["discord:123456789012345678/987654321098765432", "discord:dm/*"] }
 }
 ```
 
-This says: only one specific channel in one specific guild plus all DMs are visible/postable; auto-reply on mentions, replies, or DMs; sticky for 5 minutes after replying to a user.
+This says: the `discord-bot` adapter is enabled with default engagement; one specific channel in one specific guild plus all DMs admit speakers as `member` (which carries `channel.respond` by default).
 
 ### When the user asks "let me talk to you in this channel"
 
-1. **Read `typeclaw.json`.**
-2. **Identify the adapter.** Today this is always `discord-bot`. If `channels["discord-bot"]` is missing, create it: `{ "allow": [], "engagement": { ... defaults ... }, "enabled": true }`.
-3. **Get the channel ID from the user.** Discord channel IDs are 17–20 digit numbers. If they only gave a `#channel-name`, ask for the ID — names aren't unique and the schema needs IDs.
-4. **Pick the rule shape:**
-   - DM: `dm:<channelId>` (or `dm:*` if they want all DMs).
-   - Guild channel they fully trust: `guild:<guildId>/<channelId>` is most explicit; `channel:<channelId>` is shorter and equivalent.
-   - Whole guild: `guild:<guildId>` — confirm explicitly that they want every channel.
-5. **Append to `allow`.** Preserve existing entries.
-6. **Write the file back** (pretty-printed, 2-space indent, trailing newline).
-7. **Commit** with a message naming the rule and why (`typeclaw-git` skill).
-8. **Tell the user the effect:** "Added `<rule>` to `channels.discord-bot.allow`. This is live-reloadable — it takes effect on the next `reload`, no restart needed."
+This is a **`roles`** edit, not a `channels` edit. See the `typeclaw-permissions` skill for the full procedure. Short version:
+
+1. Get the platform ID (Discord channel ID, Slack channel ID, Telegram chat ID, KakaoTalk chat ID).
+2. Append a match-rule to `roles.member.match` using the canonical DSL (`discord:<guild>/<channel>`, `slack:<team>/<channel>`, `telegram:<chat>`, `kakao:<chat>`).
+3. **`roles` is restart-required** — `typeclaw reload` won't apply it; the user needs `typeclaw restart`.
 
 ### When the user asks "stop replying in this channel"
 
 Two interpretations — ask if unclear:
 
-- **"Stop everything"** — remove the matching allow rule. The agent loses both inbound visibility and outbound `channel_send` permission for that channel.
-- **"Just stop auto-replying"** — leave the allow rule, but adjust `engagement` (set `trigger: []` and/or `stickiness: "off"`). The agent can still see the channel and can still post if you tell it to. Caveat: this approach does NOT silence the agent in a channel that currently has only one human posting — the solo-human fallback (see Engagement) overrides `trigger: []`. In that case the only way to go silent today is to remove the allow rule.
+- **"Stop everything"** — remove the match-rule from `roles.<role>.match`. The agent loses both inbound visibility and outbound posting on that channel.
+- **"Just stop auto-replying"** — leave the match-rule, but adjust `engagement` on the adapter (set `trigger: []` and/or `stickiness: "off"`). The agent can still receive the channel and can still post if you tell it to. Caveat: this approach does NOT silence the agent in a channel that currently has only one human posting — the solo-human fallback (see Engagement) overrides `trigger: []`. In that case the only way to go silent today is to remove the match-rule.
 
 The second is usually what people mean by "be quieter".
 
 ### When the user asks "what channels can you see / are you in"
 
-1. **Read `typeclaw.json`**, list each adapter under `channels`: which is enabled, the full `allow` list, the engagement triggers and stickiness window.
-2. Note that the live runtime may have a different view if `typeclaw.json` was edited but `reload` hasn't run yet — say so when relevant.
+1. **Read `typeclaw.json`**, list each adapter under `channels`: which is enabled, the engagement triggers and stickiness window.
+2. Also read `roles.<role>.match` for every role — those are the actual admit lists.
+3. Note that the live runtime may have a different view if `typeclaw.json` was edited but `reload` hasn't run yet — say so when relevant.
 
 ## Alias
 
@@ -517,7 +491,7 @@ What this means for you:
 
 ## Plugin config blocks
 
-Top-level keys in `typeclaw.json` that are **not** in the well-known ten (`$schema`, `port`, `model`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `docker`, `git`) are treated as plugin config blocks. The schema preserves them via `catchall(z.unknown())`, and `extractPluginConfigs` hands each block to the owning plugin's `configSchema` for validation at boot.
+Top-level keys in `typeclaw.json` that are **not** in the well-known ten (`$schema`, `port`, `models`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `docker`, `git`) are treated as plugin config blocks. The schema preserves them via `catchall(z.unknown())`, and `extractPluginConfigs` hands each block to the owning plugin's `configSchema` for validation at boot.
 
 This skill does **not** document individual plugin blocks. For schema, defaults, and reload semantics of a specific plugin's config, defer to that plugin's own skill:
 
@@ -638,9 +612,9 @@ Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitign
 - If `model` is set: exactly one of the values in **Allowed models** above
 - If `plugins` is set: array of non-empty strings
 - If `alias` is set: array of strings, each non-empty after trimming surrounding whitespace
-- If `channels.discord-bot.allow` is set: every entry matches one of the **Allow rules** patterns above (numeric IDs only)
-- If `channels.discord-bot.engagement.trigger` is set: array of `"mention"`, `"reply"`, `"dm"` (any subset, including empty)
-- If `channels.discord-bot.engagement.stickiness` is set: either the literal `"off"` or `{ "perReply": { "window": <int 1..86400000> } }`
+- If `channels.<adapter>.engagement.trigger` is set: array of `"mention"`, `"reply"`, `"dm"` (any subset, including empty)
+- If `channels.<adapter>.engagement.stickiness` is set: either the literal `"off"` or `{ "perReply": { "window": <int 1..86400000> } }`
+- `channels.<adapter>.allow` (legacy) is silently dropped on parse; `migrateLegacyConfigShape` lifts it into `roles.member.match` on load. See the `typeclaw-permissions` skill.
 - If `portForward` is set: `allow` is either `"*"` or an array of integers (1–65535); `deny`, if present, is an array of integers and **only valid when `allow` is `"*"`** (the schema rejects `deny` paired with a number-array `allow`)
 - If `docker.file.append` is set: array of strings, each with no embedded `\n` or `\r` (multi-step shell logic goes in a single `&&`-chained `RUN` entry)
 - If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `python` is boolean only
@@ -657,10 +631,10 @@ Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitign
 - **Do not re-add `"mounts": []` "for clarity" if the user has none.** The scaffold deliberately omits it; defaults live in `configSchema`. Re-emitting it adds maintenance noise (the user has to keep two sources of truth in sync) without changing behavior.
 - **Do not promise to write to a `readOnly: true` mount.** Docker enforces it via `:ro`; writes will fail with EROFS. If the user wants you to edit a read-only mount, the fix is to flip `readOnly` to `false` in `typeclaw.json` and restart, not to retry the write.
 - **Do not invent mount entries the user did not request.** Mounts expose host paths to your container; adding them silently is a security surprise.
-- **Do not add channel allow rules the user did not request, especially `*` or `guild:*`.** Allow rules grant the agent visibility (and, for outbound, posting permission) on real Discord channels with real people in them. Widening the allow list silently is the same class of security surprise as adding a mount.
-- **Do not promise the user that an allow-rule edit took effect immediately just because you wrote the file.** Live-reloadable means "applied on the next `reload`", not "applied the instant the file changes". Until `reload` runs (or the container restarts), the runtime is still using the old `channels` config.
-- **Do not promise to post to a channel that isn't in `allow`.** `channel_send` will refuse with `{ ok: false, error }` regardless of what you tell the user. If they want you to post somewhere new, the prerequisite is an allow-rule edit, not a retry.
-- **Do not conflate "stop replying" with "remove allow rule".** Removing the allow rule cuts off both inbound visibility and outbound posting. If the user just wants quieter behavior, edit `engagement` instead.
+- **Do not add `roles.<role>.match` entries the user did not request, especially `*` or platform-wildcards (`discord:*`, `slack:*`).** Match-rules grant the agent visibility (and, for outbound, posting permission) on real channels with real people in them. Widening them silently is the same class of security surprise as adding a mount. See the `typeclaw-permissions` skill.
+- **Do not promise the user that a `roles` edit took effect immediately just because you wrote the file.** `roles` is **restart-required** — `typeclaw reload` returns it under `restartRequired`; the live runtime keeps the old role table until `typeclaw restart`.
+- **Do not promise to post to a channel the speaker's role does not cover.** The router drops every inbound where the speaking author resolves to a role without `channel.respond`. If the user wants you to post somewhere new, the prerequisite is a `roles` edit + restart, not a retry.
+- **Do not conflate "stop replying" with "remove the role's match-rule".** Removing the match-rule cuts off both inbound visibility and outbound posting. If the user just wants quieter behavior, edit `engagement` instead.
 - **Do not edit the `Dockerfile` directly.** It is autogenerated and rewritten on every `typeclaw start` from `src/init/dockerfile.ts` in the typeclaw repo. Manual edits will be silently overwritten (and auto-committed away if the working tree is dirty). Customizations belong in the `docker.file` block (toggles or `append`).
 - **Do not reach for `docker.file.append` when a toggle covers it.** If the user wants tmux, gh, python, or ffmpeg installed (or removed, or pinned), use the toggle — it's the cache-mounted path. `append` for these is slower and harder to read.
 - **Do not use `docker.file.append` for things that belong in the template.** If the user wants a system package _every_ typeclaw user should have, that's a typeclaw release, not a per-agent `append`. Suggest filing an issue.

package/src/skills/typeclaw-memory/SKILL.md

@@ -74,7 +74,7 @@ If the undreamed tails contain only watermarks, or every new fragment is already
 
 ### What gets injected into your prompt every turn
 
-The plugin's `session.prompt` hook appends a `# Memory` section to your system prompt with:
+Core's `createResourceLoader` appends a `# Memory` section as the LAST block of your system prompt (after `gitNudge`) by calling `loadMemory`. It is pinned to the cache-suffix end so growth in the daily stream invalidates only the memory section itself, not the skills/tools/history above. The section contains:
 
 - `MEMORY.md` (truncated to 12 KB; if larger, the rest is dropped with a `[truncated]` marker)
 - The **undreamed tails** of each `memory/yyyy-MM-dd.md`, with bare watermark lines stripped (they are bookkeeping for the memory-logger, no signal for you)

package/src/skills/typeclaw-permissions/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: typeclaw-permissions
+description: Use this skill whenever the user asks who you talk to, why you went silent in a channel, why a tool call was blocked with `blocked:` / "denied by permissions", how to grant access, what a role can or can't do, or whenever you are about to edit the `roles` block in `typeclaw.json`. Triggers include "who can talk to you", "why aren't you replying in #channel", "add me to the agent", "let X talk to you", "grant trusted to Y", "your role", "what permissions do you have", "blocked", "denied by permissions", "owner", "trusted", "member", "guest", "match rule", "channel.respond", "security.bypass", "scheduledByRole", "spawnedByRole", or any mention of `roles` / `roles[*].match` / `roles[*].permissions` in `typeclaw.json`. Read it before editing `roles` — the file has a strict match-rule DSL, restart semantics, and silent failure modes (a missing role match makes you silently drop every inbound), and the agent's own runtime behavior depends on its role and resolved permissions.
+---
+
+# typeclaw-permissions
+
+You run under an access-control system that gates which sessions wake you, which tools succeed, and which guards you can bypass. This skill exists so you can answer the user's questions about access honestly, edit `roles` without bricking your own inbound channel, and explain `blocked:` messages in terms of the role/permission model rather than the surface-level guard reason.
+
+## The model in one paragraph
+
+Every session you run in has a `SessionOrigin` (TUI / channel / cron / subagent). How the runtime resolves it to a **role** depends on the origin kind:
+
+- **TUI and channel** sessions resolve by walking the `roles` block in `typeclaw.json` in declaration order and picking the first role whose `match` rules cover the origin. This is the only origin shape that match rules actually grant roles to at runtime.
+- **Cron** sessions resolve from `scheduledByRole`, a string stamped on the cron job record itself (in `cron.json` for hand-authored entries, or by the runtime for plugin-contributed cron). Match rules of the form `cron` parse but never grant a role to a running cron session — provenance wins.
+- **Subagent** sessions resolve from `spawnedByRole`, snapshotted from the spawning session's resolved role at spawn time. Same story: `subagent` / `subagent:<name>` rules parse but don't grant roles at runtime; the spawn provenance is the source of truth.
+
+Each role carries a set of **permissions** — opaque dotted strings like `channel.respond`, `cron.schedule`, `security.bypass.gitExfil`. The runtime checks `permissions.has(origin, '<perm>')` at three places: the channel router (gates `channel.respond` before creating a session for an inbound message), the security plugin's `tool.before` hook (gates each `security.bypass.*` so the corresponding guard can be skipped), and plugin code that opts in. There is no other access-control surface — no per-tool ACL, no file-system isolation, no per-author allowlist outside `match` rules.
+
+## The four built-in roles
+
+You always have these four, even if `typeclaw.json` declares zero `roles`. User-declared roles **append** match rules to the built-ins but **replace** the permission list entirely (so `"permissions": []` on a built-in role means "no permissions" — be careful).
+
+| Role      | Built-in `match[]`                                                | Default `permissions[]`                                                                                                   |
+| --------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `owner`   | `["tui"]` (always prepended)                                      | `channel.respond`, `cron.schedule`, `cron.modify`, **all `security.bypass.*` contributed by plugins** (wildcard sentinel) |
+| `trusted` | none                                                              | `channel.respond`, `cron.schedule`, `security.bypass.secretExfilBash`                                                     |
+| `member`  | none                                                              | `channel.respond`                                                                                                         |
+| `guest`   | none (fallback when nothing else matches, or stamped role is bad) | none                                                                                                                      |
+
+A session that doesn't match anything resolves to `guest`. `guest` has no `channel.respond`, so the router silently drops inbound messages whose author resolves to `guest`. **This is the most common cause of "the agent stopped responding"**: the user added a channel but did not add a match rule, so every speaker in that channel is `guest` and every inbound is dropped before you ever see it. There is no message in your session log when this happens — only a host-side line `[channels] <key>: denied by permissions (channel.respond) author=<id>`.
+
+## What your current session sees
+
+When the runtime knows your permissions, it prepends a block under your `## Session origin`:
+
+```
+## Your role in this session
+
+Role: `member`. Permissions: `channel.respond`.
+```
+
+The block renders for cron / channel / subagent sessions. For TUI sessions, the block is omitted **when** the resolved role is the built-in `owner` (the common case, so we save tokens on every interactive session) and rendered when a user-declared role matched TUI first (because the resolver is first-match-wins in declaration order, a custom role with `match: ["tui"]` placed before `owner` will demote TUI). If you don't see the block in a TUI session, treat yourself as `owner`.
+
+**The role line reflects the session at creation time.** For channel sessions, the speaker on subsequent turns may resolve to a different role; the runtime updates that internally for tool gating (the channel router and the security plugin re-resolve on each turn), but the system prompt is not regenerated mid-session. If the user asks "what role am I right now in this channel", read `typeclaw.json` `roles` and match their author id against `match[]` yourself — do not parrot the system-prompt line as if it always applied.
+
+**The permission list is exhaustive at session-creation time** for the resolved role. If a permission you expect isn't listed there, the role doesn't carry it — adding it requires editing `roles.<role>.permissions[]` and restarting.
+
+## The match-rule DSL
+
+`roles.<role>.match[]` is an array of compact strings. The parser is hand-rolled in `src/permissions/match-rule.ts`; the canonical shapes are:
+
+```
+tui                                # any TUI session
+*                                  # any channel session, any platform
+<platform>:*                       # any chat on this platform (slack | discord | telegram | kakao)
+<platform>:<workspace>             # one workspace, any chat
+<platform>:<workspace>/<chat>      # one specific chat
+<platform>:dm/*                    # any DM on this platform
+kakao:group/*                      # any KakaoTalk group chat
+kakao:open/*                       # any KakaoTalk open chat
+<rule> author:<authorId>           # AND-tighten any of the above to one author
+```
+
+`cron`, `subagent`, and `subagent:<name>` are also valid parser shapes (they parse without error), but they do **not** grant a role to a running cron or subagent session — those resolve from stamped provenance (`scheduledByRole` / `spawnedByRole`) instead. Don't write those rules expecting them to admit traffic the way channel rules do.
+
+Within a single string, tokens are **AND**'d. Across multiple strings in `match[]`, they're **OR**'d. The platform names are exactly `slack | discord | telegram | kakao`. Workspace and chat coordinates are platform-native IDs (Slack team `T0123`, Discord guild `123456789012345678`, Telegram chat `42`, KakaoTalk chat hash) — **never** display names. If the user gives you a name, you need to resolve it to an ID before writing the match rule.
+
+Things the DSL rejects (the parser emits actionable errors at boot, but you should not write these in the first place):
+
+- `slack:*/*` — `*/*` is redundant; use `slack:*` for "any Slack chat".
+- `slack:*/C0ABCDE` — workspace-less chat ID is impossible; pick a workspace.
+- `slack:T0123/*` — workspace-only is enough; drop the trailing `/*`.
+- `team:T0123`, `guild:G123`, `tg:42` — these are legacy prefixes from the old `channels.<adapter>.allow[]` field. They are auto-migrated on load but **don't write them in new code** — use `slack:T0123`, `discord:G123`, `telegram:42` directly.
+- `autor:U_ME` — typo of `author:`. The parser will suggest the fix at boot.
+
+## Permission strings you will see
+
+Three sources contribute permission strings:
+
+1. **Core** (always present): `channel.respond`, `cron.schedule`, `cron.modify`.
+2. **Bundled security plugin** (always loaded): `security.bypass.secretExfilBash`, `security.bypass.gitExfil`, `security.bypass.gitRemoteTainted`, `security.bypass.secretExfilRead`, `security.bypass.ssrf`, `security.bypass.sessionSearchSecrets`, `security.bypass.systemPromptLeak`, `security.bypass.outboundSecret`.
+3. **User-declared plugins** (variable): each plugin can contribute its own strings via `definePlugin({ permissions: [...] })`.
+
+`owner` carries every `security.bypass.*` from sources 2 and 3 by default (via a wildcard sentinel expanded at boot). `trusted` carries only `security.bypass.secretExfilBash` by default. `member` and `guest` carry no `security.bypass.*` strings.
+
+User-declared `permissions[]` strings that don't appear in any of the three sources are **logged as warnings at boot** (`[permissions] role "X" declares unknown permission "Y" — did you mean 'Z'?`) but the role still resolves with the unknown string in its list. This is intentional — the runtime is forward-compatible with strings from plugins that aren't loaded yet — but it also means typos silently fail to bypass guards. If you wrote `security.bypass.secretExfilBach` instead of `Bash`, no guard will be skipped and you will only notice when you read the boot logs.
+
+## When a tool is blocked
+
+The security plugin's `tool.before` hook produces block messages of the form:
+
+```
+Guard `<guardName>` blocked <what>. If this is genuinely intentional and the user
+explicitly asked for it, retry with `acknowledgeGuards.<guardName>: true` in the
+<tool> arguments. Or run as a role carrying `<permission>` (owner has all
+security.bypass.*; trusted has security.bypass.secretExfilBash).
+```
+
+Three escape hatches, ordered from least to most invasive:
+
+1. **`acknowledgeGuards.<guardName>: true`** in the tool args. This is a per-call, in-session bypass. Use it when the user has just explicitly told you to run the dangerous thing (e.g. "yes, push the secret to a private gist on purpose"). Never use it without explicit user confirmation — the guard exists for a reason.
+2. **Run as a role with the bypass permission**. If the user wants this pattern to keep working without an ack every time, they edit `roles.<role>.permissions[]` to include the `security.bypass.<X>` string the block message named. This is the right answer for "I'm `trusted` in this Slack channel and I want to be able to run dangerous bash without confirming each time" — give `trusted` the relevant `security.bypass.*` permission.
+3. **Run from a session that already resolves to a role with the bypass**. The TUI is always `owner`, so a guard that blocks in channel sessions for a `member` author will not block at all from the TUI. This is why "the agent can do X in TUI but not in Slack" is normal, not a bug.
+
+When you see a block, tell the user **which permission would skip it** (the block message now names it) and **which built-in roles have that permission**. Do not just relay the guard reason — that loses the access-control framing entirely.
+
+## When the user asks "why aren't you replying in #channel?"
+
+Probable causes, in descending order of frequency:
+
+1. **No match rule covers the speaking author's coordinates.** Read `typeclaw.json` `roles`, compare every `match[]` entry to the channel ID and author ID the user is reporting. If nothing matches, the author resolves to `guest`, which has no `channel.respond`, so every inbound is dropped at the router. The fix is to append a match rule to `roles.<role>.match[]` for that channel (or DM bucket).
+2. **The match rule exists but the role has `permissions: []`** (or otherwise lacks `channel.respond`). A user-declared role replaces the built-in's permissions wholesale. Re-add `channel.respond` or use a built-in role name (`member`, `trusted`, `owner`) that carries it by default.
+3. **Engagement triggers are filtering admitted messages.** This is a different problem — the inbound was admitted by permissions but engagement (`channels.<adapter>.engagement.trigger`) decided not to wake you. See the `typeclaw-config` skill for the engagement model.
+
+To distinguish cause 1/2 from cause 3: if `typeclaw logs <container> -f` (host stage) shows `[channels] ... denied by permissions (channel.respond)`, it's a permissions problem. If it shows the message being admitted but no LLM call follows, it's engagement.
+
+## When the user asks "let X talk to you in this channel"
+
+This is a `roles` edit. The full procedure:
+
+1. **Resolve the coordinates.** Get the platform name (`slack | discord | telegram | kakao`), the workspace ID, the chat ID. If the user gave you names, ask them or look them up in the participants list of a previous inbound from that channel.
+2. **Pick a role.** Default to `member` for "give them normal channel access". Use `trusted` if they should also be able to schedule cron and bypass the bash secret guard. Only use `owner` if they should have full bypass on every security guard — typically the agent's primary operator.
+3. **Edit `typeclaw.json` `roles.<role>.match[]`.** Append the canonical DSL string. Example: `roles.member.match` adds `"slack:T0123/C0ABCDE"`. If the user wants only a specific person in that channel, append `slack:T0123/C0ABCDE author:U_ME` instead.
+4. **Restart.** `roles` is **restart-required** — `typeclaw reload` does not re-evaluate role config. Tell the user: "edited `roles.<role>.match` — restart-required. Run `typeclaw restart` (host stage)."
+5. **Commit the change.** See the `typeclaw-git` skill. The decision context in the commit message should name the role, the channel, and the author/scope ("let @X talk to me as `member` in #foo in workspace bar").
+
+## When the user asks "stop replying to X"
+
+Two interpretations — clarify if ambiguous:
+
+- **"Stop everything"** — remove the match rule from `roles.<role>.match[]`. The author resolves to `guest`, and the channel router silently drops every inbound. You lose all visibility into their messages. Restart-required.
+- **"Just stop auto-replying"** — keep the match rule, but narrow `channels.<adapter>.engagement.trigger` and/or `stickiness`. See `typeclaw-config`. The agent still receives the messages and can still post if you tell it to. The solo-human fallback (single human in a channel) overrides `trigger: []`, so this approach can't fully silence you in a 1:1; only removing the match rule does.
+
+## When the user asks "what role am I in this session?"
+
+Read your `## Session origin` block — the role/permissions line is there for non-TUI sessions. For TUI it's `owner` by definition. If the user is in a channel and asks about themselves, read `typeclaw.json` `roles` and match their `<authorId>` against every `match[]` entry in declaration order; the first hit wins. Do not invent a role they aren't in.
+
+## When the user asks about cron / subagent provenance
+
+Cron and subagent sessions don't resolve their role by matching their own origin — instead, the role is **stamped at creation**:
+
+- **Cron jobs** carry `scheduledByRole` in `cron.json`. The job runs as that role. If `scheduledByRole` is absent on a hand-authored cron entry, **boot fails** with a precise error (there is no implicit fallback). Plugin-contributed cron jobs default to `owner`.
+- **Subagents** carry `spawnedByRole`, snapshotted from the spawning session's resolved role at spawn time. A cron-fired subagent inherits the cron's stamped role.
+
+This forecloses the laundering attack — an attacker who only resolves to `guest` can ask you to schedule a cron, but the cron entry will be stamped `scheduledByRole: 'guest'`, and when it fires it will still be `guest` (with no permissions, including no `channel.respond` or `security.bypass.*`).
+
+If you see a cron job mysteriously failing every fire with `denied by permissions` in logs, check its `scheduledByRole` — it may have been scheduled by a `guest` session at some point in the past.
+
+## Things you must not do
+
+- **Do not write `*` in user-declared `permissions[]`.** The owner wildcard is a runtime sentinel, not part of the user-facing string format. The schema rejects `*` (it's not a valid dotted permission string anyway).
+- **Do not invent permission strings.** Only the three sources above (core, security plugin, declared plugins) contribute valid strings. A string like `bash.execute` looks plausible but is not gated by anything and will only earn a boot warning. If the user asks for a permission the model doesn't have, tell them — don't invent one.
+- **Do not promise that `typeclaw reload` applied a `roles` edit.** `roles` is restart-required. The reload tool will return success on the config file change, but the live `PermissionService` was built at boot and is not swapped on reload.
+- **Do not silently change a built-in role's permission list.** Setting `"permissions": []` on `member` is a wholesale replace, not a merge — you just took `channel.respond` away from every speaker who resolves to `member`. If the user said "give member just `channel.respond` and nothing else", that's fine (it's the same as the default), but say so explicitly: "this matches the default for `member`, no behavior change". If the user said "remove cron from `trusted`", make the change but warn that `trusted` no longer carries `cron.schedule` either.
+- **Do not write match rules using display names** (`#general`, `@user`, channel/user names). Match rules are platform IDs. Display names change; IDs don't. Always look up the ID before writing the rule.
+- **Do not edit `roles` to "fix" a security block** without explaining the alternative. The right first move for a guard block is usually `acknowledgeGuards.<X>: true` for the specific call. Editing `roles` to grant a permanent bypass is a heavier change with security implications — get explicit consent.
+- **Do not interpret a missing `## Session origin` role line as "I have no role".** TUI sessions don't render the line because TUI is always `owner`. If you see no role line and you're not in TUI, something has gone wrong with the system prompt build — flag it, don't fabricate.
+
+## What this skill does not cover
+
+- **The `channels.<adapter>` block** — engagement, history, stickiness, alias. See `typeclaw-config`. Engagement decides whether an _admitted_ inbound wakes the loop; this skill is only about admission.
+- **The full `typeclaw.json` schema** — model, mounts, plugins, docker, git.ignore. See `typeclaw-config`.
+- **Cron job authoring** — schedule syntax, `prompt` vs `exec`, the `reload` tool. See `typeclaw-cron`. This skill only covers the `scheduledByRole` field and its provenance semantics.
+- **Plugin authoring** — `definePlugin`, contributing permissions, custom `tool.before` hooks. See `typeclaw-plugins`. The bundled security plugin is an example of a plugin that contributes `security.bypass.*` strings and uses `permissions.has()` to gate its own guards.
+- **The container vs host stage split** — `typeclaw restart` runs on the host; this skill assumes you know which stage you're in. See `AGENTS.md` for the stage model.

package/src/stream/types.ts

@@ -3,7 +3,13 @@ export type StreamMessageId = string
 export type StreamTarget =
   | { kind: 'broadcast' }
   | { kind: 'session'; sessionId: string }
-  | { kind: 'new-session'; subagent: string }
+  | {
+      kind: 'new-session'
+      subagent: string
+      parentSessionId?: string
+      spawnedByRole?: string
+      spawnedByOriginJson?: string
+    }
   | { kind: 'cron'; jobId: string }
 
 export type StreamMessage = {

package/src/usage/aggregate.ts

@@ -0,0 +1,117 @@
+import type { AssistantRow } from './scan'
+
+export type UsageTotals = {
+  messageCount: number
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  totalTokens: number
+  cost: number
+}
+
+export type DailyUsage = UsageTotals & { date: string; sessionCount: number }
+export type ModelUsage = UsageTotals & { provider: string; model: string }
+export type SessionUsage = UsageTotals & {
+  sessionId: string
+  sessionFile: string
+  firstAt: number
+  lastAt: number
+  models: string[]
+}
+
+export type Aggregation = {
+  total: UsageTotals
+  byDay: DailyUsage[]
+  byModel: ModelUsage[]
+  bySession: SessionUsage[]
+}
+
+export async function aggregate(rows: AsyncIterable<AssistantRow>): Promise<Aggregation> {
+  const total = emptyTotals()
+  const byDay = new Map<string, DailyUsage & { _sessionIds: Set<string> }>()
+  const byModel = new Map<string, ModelUsage>()
+  const bySession = new Map<string, SessionUsage & { _modelSet: Set<string> }>()
+
+  for await (const row of rows) {
+    addInto(total, row)
+
+    const date = isoDate(row.timestamp)
+    const sessionKey = sessionIdFromBasename(row.sessionBasename)
+    const dayBucket = byDay.get(date) ?? {
+      ...emptyTotals(),
+      date,
+      sessionCount: 0,
+      _sessionIds: new Set<string>(),
+    }
+    addInto(dayBucket, row)
+    dayBucket._sessionIds.add(sessionKey)
+    dayBucket.sessionCount = dayBucket._sessionIds.size
+    byDay.set(date, dayBucket)
+
+    const modelKey = `${row.provider}/${row.model}`
+    const modelBucket = byModel.get(modelKey) ?? {
+      ...emptyTotals(),
+      provider: row.provider,
+      model: row.model,
+    }
+    addInto(modelBucket, row)
+    byModel.set(modelKey, modelBucket)
+
+    const sessionBucket = bySession.get(sessionKey) ?? {
+      ...emptyTotals(),
+      sessionId: sessionKey,
+      sessionFile: row.sessionFile,
+      firstAt: row.timestamp,
+      lastAt: row.timestamp,
+      models: [],
+      _modelSet: new Set<string>(),
+    }
+    addInto(sessionBucket, row)
+    sessionBucket.firstAt = Math.min(sessionBucket.firstAt, row.timestamp)
+    sessionBucket.lastAt = Math.max(sessionBucket.lastAt, row.timestamp)
+    sessionBucket._modelSet.add(modelKey)
+    sessionBucket.models = [...sessionBucket._modelSet]
+    bySession.set(sessionKey, sessionBucket)
+  }
+
+  return {
+    total,
+    byDay: [...byDay.values()].map(({ _sessionIds: _, ...rest }) => rest).sort((a, b) => a.date.localeCompare(b.date)),
+    byModel: [...byModel.values()].sort((a, b) => b.cost - a.cost),
+    bySession: [...bySession.values()].map(({ _modelSet: _, ...rest }) => rest).sort((a, b) => b.cost - a.cost),
+  }
+}
+
+function emptyTotals(): UsageTotals {
+  return { messageCount: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: 0 }
+}
+
+function addInto(target: UsageTotals, row: AssistantRow): void {
+  target.messageCount += 1
+  target.input += row.input
+  target.output += row.output
+  target.cacheRead += row.cacheRead
+  target.cacheWrite += row.cacheWrite
+  target.totalTokens += row.totalTokens
+  target.cost += row.cost
+}
+
+function isoDate(ts: number): string {
+  // Local tz so "today" matches the user's wall clock; lexicographic order
+  // matches chronological order.
+  const d = new Date(ts)
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}
+
+// File scheme: `${ISO_TIMESTAMP}_${SESSION_UUID}.jsonl` (pi-coding-agent).
+// Take the segment after the last underscore so a future suffix-before-ext
+// change does not silently regroup messages onto the wrong session.
+function sessionIdFromBasename(basename: string): string {
+  const stem = basename.endsWith('.jsonl') ? basename.slice(0, -'.jsonl'.length) : basename
+  const idx = stem.lastIndexOf('_')
+  return idx === -1 ? stem : stem.slice(idx + 1)
+}

package/src/usage/format.ts

@@ -0,0 +1,30 @@
+export function formatTokens(n: number): string {
+  if (n === 0) return '0'
+  const abs = Math.abs(n)
+  if (abs < 1_000) return String(Math.round(n))
+  if (abs < 1_000_000) return `${(n / 1_000).toFixed(n < 10_000 ? 1 : 0)}k`
+  if (abs < 1_000_000_000) return `${(n / 1_000_000).toFixed(n < 10_000_000 ? 1 : 0)}M`
+  return `${(n / 1_000_000_000).toFixed(2)}B`
+}
+
+export function formatCost(usd: number): string {
+  if (usd === 0) return '$0.00'
+  if (usd < 0.01) return `$${usd.toFixed(4)}`
+  if (usd < 1) return `$${usd.toFixed(3)}`
+  return `$${usd.toFixed(2)}`
+}
+
+export function formatCacheHitRate(input: number, cacheRead: number): string {
+  const total = input + cacheRead
+  if (total <= 0) return '—'
+  const pct = Math.round((cacheRead / total) * 100)
+  return `${pct}%`
+}
+
+export function isoDay(ts: number): string {
+  const d = new Date(ts)
+  const y = d.getFullYear()
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}-${m}-${day}`
+}