@tduyng/pi-session 0.0.2 → 0.0.4

package/README.md

@@ -1,36 +1,37 @@
 # @tduyng/pi-session
 
-Session lifecycle: sessions name themselves and resume once a provider quota resets. No more `untitled` rows in the picker, no more waiting out a usage limit by hand.
+Two gaps in session handling, both filled from what is already on disk. A session names itself from the first user message. A turn killed by a usage limit resumes when the limit resets.
 
-## Auto-name
+Nothing is configured and no tool is registered.
 
-A new session starts unnamed. On `agent_end`, the extension reads the first user message and uses it as the name. It takes the first line, strips a leading `/` or `#`, collapses whitespace, and limits the result to 60 characters, cutting at a word boundary.
+## Naming
 
-An expanded skill uses its argument when one is present, or the skill name when it has no argument. The extension ignores the expanded instructions and the skill's filesystem path. A `/skill:name task` command follows the same rule and uses `task` when present. A `Skill invocation protocol` message without a skill block is skipped because an extension injected it. A name you set with `/name` always wins. Naming runs last and swallows its own errors. It is cosmetic and never blocks the turn.
+A new session starts unnamed, so a picker fills with `2026-09-01 14:22` rows and the session wanted is the one that cannot be identified.
 
-The extension finds the first user-role message in the `event.messages` array. If the message content is a block array, it extracts text blocks and joins them with spaces. When no user message exists, naming is skipped silently.
+On `agent_end` the extension reads the first user message and uses it: first line, a leading `/` or `#` stripped, whitespace collapsed, 60 characters at most, cut at a word boundary.
 
-Before: a week of `2026-09-01 14:22`, `2026-09-01 14:47`, `2026-09-02 09:03`. After: `fix retry backoff`, `review auth diff`, `migrate schema`.
+A week of timestamps becomes `fix retry backoff`, `review auth diff`, `migrate schema`.
 
-## Autoresume
+An expanded skill uses its argument when there is one, otherwise the skill name. A `/skill:name task` command uses `task`. A name set with `/name` always wins, and naming runs last and swallows its own errors, because it is cosmetic and must never block a turn.
 
-When a provider quota exhaustion kills a turn, the extension parses a reset time from the error text. Formats it accepts:
+## Resuming after a quota reset
 
-- Epoch timestamps: `limit reached|1757193000`
-- ISO timestamps: `resets at 2026-09-06T23:30:00+02:00`
-- Relative times: `try again in 2h 15m`, `retry after 3600 seconds`
-- Clock times: `resets 11:30pm (Europe/Paris)`, `reset at 23:30`
-- Retry-after headers: `retry-after: 3600`
+When a provider quota kills a turn, the error usually carries a reset time. The parser accepts the shapes that appear in practice: epoch, ISO, `try again in 2h 15m`, `resets 11:30pm (Europe/Paris)`, `retry-after: 3600`.
 
-For claude-bridge sessions where the error carries no reset time, autoresume queries the Anthropic OAuth usage endpoint and picks the latest reset among all exhausted windows, with the credential from the macOS keychain (`Claude Code-credentials`) or `~/.claude/.credentials.json`.
+For a `claude-bridge` session with no time in the error, it asks the Anthropic OAuth usage endpoint and takes the latest reset among the exhausted windows. The usage API wins over the error text, since the error is a snapshot and the API is the current state.
 
-A 5-second safety delay is added past the reset time. The timer caps at 24 hours. A parsed reset further than 24 hours out schedules nothing and posts a warning: Usage limit resets in over 24h, auto-resume not scheduled. Any user turn or session shutdown cancels it. The resume sends a real user message: "The usage limit has reset. Continue the previous task from where it stopped."
+The resume is a real user message on the same session: "The usage limit has reset. Continue the previous task from where it stopped." Nothing is replayed and nothing is stored.
 
-Commands: `/autoresume`, `/autoresume status`, `/autoresume on`, `/autoresume off`, `/autoresume cancel`.
+A scheduled resume adds a 5 second safety delay past the reset and caps at 24 hours. Further out than that it warns and schedules nothing. Any user turn or session shutdown cancels it, so a timer never fires over work already resumed by hand.
 
-## Design
+```
+/autoresume            status, including the pending resume time
+/autoresume on
+/autoresume off
+/autoresume cancel
+```
 
-Auto-naming reads at `agent_end`, when real conversation content exists. Autoresume touches no session storage and adds no tools beyond the one command. Session creation, storage, and selection stay with pi.
+The quota lookup reads the Claude Code OAuth credential from the macOS keychain item `Claude Code-credentials`, or from `~/.claude/.credentials.json`. Nothing else is read, and no value is logged.
 
 ## Install
 
@@ -40,6 +41,11 @@ pi install npm:@tduyng/pi-session
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-session`
 
-## Configure
+Naming needs nothing. The quota lookup needs network access to `api.anthropic.com` and either keychain access (macOS may prompt once) or the credentials file.
+
+## Limits
 
-None. It works out of the box.
+- Names are cut at 60 characters on a word boundary.
+- The resume polls its timer every 10 seconds, so it can fire up to 10 seconds late.
+- The quota lookup is Anthropic only. Other providers get the error-text path.
+- A provider that changes its error wording gets no resume.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tduyng/pi-session",
-  "version": "0.0.2",
-  "description": "Session lifecycle: name an unnamed session after its first message, and resume once a provider quota resets.",
+  "version": "0.0.4",
+  "description": "Sessions name themselves, and a turn killed by a usage limit resumes when the limit resets.",
   "keywords": [
     "pi",
     "pi-package",