@bastani/atomic 0.9.55 → 0.9.56

package/docs/extensions/authoring.md

@@ -632,6 +632,7 @@ pi.registerTool({
 - `toolCallId`, `cwd`, `executionStarted`, `argsComplete`, `isPartial`, `expanded`, `showImages`, `isError`
 - `durationMs` - recorded execution time of the final result; `undefined` while running, when the tool did not run, or for older saved results
 - `outputPad` - configured horizontal padding; renderers with `renderShell: "self"` apply it themselves
+- `keyText()`, `keyHint()` - format the user's configured keybindings, see [Keybinding Hints](#keybinding-hints)
 
 Use `context.state` for cross-slot shared state. Keep slot-local caches on the returned component instance when you want to reuse and mutate the same component across renders.
 
@@ -682,26 +683,24 @@ If a slot intentionally has no visible content, return an empty `Component` such
 
 #### Keybinding Hints
 
-Use `keyHintIfBound()` when an affordance should disappear if the action has no effective keybinding. Add surrounding punctuation only when the helper returns text:
+Use `keyHint()` and `keyText()` from the render context to display keybinding hints that respect the user's keybinding configuration. Test `keyText()` for an empty string when an affordance should disappear if the action has no effective keybinding, and add surrounding punctuation only when there is text:
 
 ```typescript
-import { keyHintIfBound } from "@bastani/atomic";
-
 renderResult(result, { expanded }, theme, context) {
   let text = theme.fg("success", "✓ Done");
-  const expandHint = keyHintIfBound("app.tools.expand", "to expand");
-  if (!expanded && expandHint) {
-    text += ` (${expandHint})`;
+  if (!expanded && context.keyText("app.tools.expand")) {
+    text += ` (${context.keyHint("app.tools.expand", "to expand")})`;
   }
   return new Text(text, 0, 0);
 }
 ```
 
-Available functions:
-- `keyHint(keybinding, description)` - Formats a configured keybinding id such as `"app.tools.expand"` or `"tui.select.confirm"`; use it when the binding is required by the surrounding UI
-- `keyHintIfBound(keybinding, description)` - Formats the hint only when the action has an effective key list; use it for optional affordances and conditionally compose parentheses or separators
-- `keyText(keybinding)` - Returns the raw configured key text for a keybinding id
-- `rawKeyHint(key, description)` - Format a raw key string
+The same functions are available as `options.keyHint()` and `options.keyText()` in message and entry renderers:
+
+- `keyHint(keybinding, description)` - Formats a configured keybinding id such as `"app.tools.expand"` or `"tui.select.confirm"`, followed by the description
+- `keyText(keybinding)` - Returns the raw configured key text for a keybinding id, or `""` if the id has no keys
+
+In renderers, use these instead of importing `keyHint()`, `keyHintIfBound()` or `keyText()` from `@bastani/atomic`. An extension can resolve its own copy of the package, for example from its own `node_modules`, and that copy does not see Atomic's configured keybindings: `app.*` ids then format as `""`. `rawKeyHint(key, description)` formats a literal key string and is safe to import.
 
 Use namespaced keybinding ids:
 - Coding-agent ids use the `app.*` namespace, for example `app.tools.expand`, `app.editor.external`, `app.session.rename`

package/docs/extensions/ui.md

@@ -414,6 +414,8 @@ pi.registerMessageRenderer("my-extension", (message, options, theme) => {
 
   if (expanded && message.details) {
     text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
+  } else if (message.details) {
+    text += ` (${options.keyHint("app.tools.expand", "to expand")})`;
   }
 
   return new Text(text, outputPad, 0);

package/docs/mcp-servers.md

@@ -102,11 +102,11 @@ atomic mcp add <server> [options] -- <command> [args...]
 atomic mcp add <server> [options] --url <url>
 atomic mcp remove <server> [-l]
 atomic mcp list [--json]
-atomic mcp login <server> [--timeout <seconds>]
-atomic mcp logout <server>
+atomic mcp login <server> [-l] [--timeout <seconds>]
+atomic mcp logout <server> [-l]
 ```
 
-`add` replaces an existing entry of the same name. `add` and `remove` accept `--local` (`-l`) for the project file. For stdio, use repeatable `--env KEY=VALUE` and `--cwd`. For HTTP, use repeatable `--header KEY=VALUE`, `--bearer-token-env-var NAME`, and `--oauth-client-id`, `--oauth-client-secret`, `--oauth-callback-port`, or `--oauth-client-name`. Both transports accept `--exposure` and `--description`. Run `atomic mcp --help` for usage.
+`add` replaces an existing entry of the same name. `add` and `remove` accept `--local` (`-l`) for the project file. `login` and `logout` accept `-l` to require that the server is defined in the project's file; without it they find the server in either file. For stdio, use repeatable `--env KEY=VALUE` and `--cwd`. For HTTP, use repeatable `--header KEY=VALUE`, `--bearer-token-env-var NAME`, and `--oauth-client-id`, `--oauth-client-secret`, `--oauth-callback-port`, or `--oauth-client-name`. Both transports accept `--exposure` and `--description`. Run `atomic mcp --help` for usage.
 
 `list` connects to enabled servers and reports state, tools, and errors; it exits with status 1 for invalid configuration or an enabled server that is not connected. `--json` produces a machine-readable report. Login gives up after 300 seconds by default; `--timeout` limits the whole sign-in, including requests to the authorization server, but not the MCP server request timeout. A running session uses new credentials on its next turn.
 

package/docs/reference/cli.md

@@ -35,6 +35,18 @@ These commands manage Atomic packages and `atomic update` can update the Atomic
 
 See [Atomic Packages](/packages) for package sources and security notes.
 
+### Custom update command
+
+If a wrapper or another package manager provides Atomic, set `ATOMIC_SELF_UPDATE_COMMAND` so `atomic update` runs its update command:
+
+```sh
+export ATOMIC_SELF_UPDATE_COMMAND="mise use -g npm:{packageName}@{version}"
+```
+
+`atomic update` runs it only when a newer release exists, replacing `{packageName}`, `{version}`, and `{installSpec}` (`{packageName}@{version}`) with that release. It replaces install-method detection, so it also works for installs Atomic cannot update itself. The value is split on spaces; `PI_SELF_UPDATE_COMMAND` is accepted as an alias. For arguments with spaces, use the `selfUpdateCommand` setting in `~/.atomic/agent/settings.json` instead, an argv array such as `["nix", "profile", "upgrade", "atomic"]`. Project settings are ignored for it.
+
+Afterwards Atomic reports the version it finds installed: the one on disk, or what `atomic --version` prints on `PATH`. A wrapper that installs each version into a new directory therefore still reports success, and a command that exits `0` without installing the new version prints a warning instead.
+
 ## Credential Commands
 
 ```bash
@@ -148,12 +160,12 @@ When a print-mode turn correctly finishes by calling an opt-in terminating struc
 
 | Option | Description |
 |--------|-------------|
-| `-c`, `--continue` | Continue the most recent session |
+| `-c`, `--continue` | Continue the most recent session for the current directory |
 | `-r`, `--resume` | Browse and select a session |
-| `--session <id\|prefix>` | Use an exact ID or unique 8-hex UUID prefix |
+| `--session <id\|prefix>` | Use an exact ID or unique 8-hex UUID prefix, and run it in its working directory. If it only matches a session from another directory, Atomic offers to fork it into the current directory |
 | `--import <file>` | Import a format-4 JSONL export into session storage |
 | `--session-id <id>` | Use an exact project session ID; warn and create it when missing |
-| `--fork <id\|prefix>` | Fork an exact ID or unique 8-hex UUID prefix into a new session |
+| `--fork <id\|prefix>` | Fork an exact ID or unique 8-hex UUID prefix into a new session in the current directory |
 | `--session-dir <dir>` | Custom session storage directory |
 | `--session-store <path>` | Select a SQLite session database; relative paths resolve from the working directory |
 | `--session-prefix <prefix>` | Use a non-default table prefix with `--session-store` |

package/docs/sessions.md

@@ -89,6 +89,16 @@ For the JSONL file format and SessionManager API, see [Session Format](/session-
 
 `/resume` opens an interactive session picker for the current project. `atomic -r` opens the same picker at startup.
 
+Each session records the working directory it was created in and never changes it. Atomic runs a session in its working directory, so tools, `@path` references, project configuration, and context files resolve from there.
+
+| Entry point | Working directory |
+|---|---|
+| `--continue` | The current directory |
+| `--resume`, `/resume`, `--session` | The session's working directory, which can differ from the current directory |
+| `--fork`, or a `--session` ID from another directory that you choose to fork | The current directory, in a new session |
+
+If a session's working directory no longer exists, interactive mode offers to continue in the current directory instead; other modes exit with an error that names both directories.
+
 Sessions written in formats 1, 2, and 3, and early 0.9.38 alpha sessions whose header uses `timestamp`, appear in the picker and upgrade automatically to format 4. In the default store this happens when you first open one. In an explicit JSONL store it happens when you open them, including with `--continue`, `--session`, or `--fork`; browsing the picker does not change session files, and opening an older session rewrites only that file. No flag or confirmation is needed.
 
 If the default store's earlier sessions folder holds several copies of one session, such as conflict copies left by a file-sync tool, the picker lists the copy with the newest message and opening the session imports that copy. Other copies stay on disk unchanged.

package/docs/settings.md

@@ -433,6 +433,7 @@ When `images.autoResize` is enabled, Atomic normalizes images before sending the
 | `search.contextBefore` | number | `1` | Number of context lines before each `search` match. |
 | `search.contextAfter` | number | `3` | Number of context lines after each `search` match. |
 | `npmCommand` | string[] | - | Command argv used for npm package lookup/install operations (e.g., `["mise", "exec", "node@20", "--", "npm"]`) |
+| `selfUpdateCommand` | string[] | - | Command argv `atomic update` runs to update Atomic itself, with `{packageName}`, `{version}`, and `{installSpec}` placeholders. `ATOMIC_SELF_UPDATE_COMMAND` takes precedence. **Read only from the global settings file.** See [Custom update command](/reference/cli#custom-update-command) |
 
 ```json
 {

package/examples/extensions/debug-provider.ts

@@ -6,7 +6,7 @@
  * as expandable custom entries.
  */
 
-import { type ExtensionAPI, keyHint } from "@bastani/atomic";
+import type { ExtensionAPI } from "@bastani/atomic";
 import { Box, Text } from "@earendil-works/pi-tui";
 
 const ENTRY_TYPE = "debug-provider-events";
@@ -24,7 +24,7 @@ export default function (pi: ExtensionAPI) {
 	let activeEvents: unknown[] | undefined;
 	let completedEntry: ProviderDebugEntry | undefined;
 
-	pi.registerEntryRenderer<ProviderDebugEntry>(ENTRY_TYPE, (entry, { expanded }, theme) => {
+	pi.registerEntryRenderer<ProviderDebugEntry>(ENTRY_TYPE, (entry, { expanded, keyHint }, theme) => {
 		const data = entry.data;
 		if (!data) return new Text(theme.fg("warning", "[provider debug] Missing event data"), 0, 0);
 

package/npm-shrinkwrap.json

@@ -1,16 +1,16 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.55",
+	"version": "0.9.56",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.55",
+			"version": "0.9.56",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.55",
-				"@bastani/pi-ai": "0.9.55",
+				"@bastani/atomic-natives": "0.9.56",
+				"@bastani/pi-ai": "0.9.56",
 				"@earendil-works/pi-agent-core": "1.4.0",
 				"@earendil-works/pi-codemode": "1.4.0",
 				"@earendil-works/pi-tui": "1.4.0",
@@ -427,18 +427,18 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.56.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.55",
-				"@bastani/atomic-natives-darwin-x64": "0.9.55",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.55",
-				"@bastani/atomic-natives-linux-arm64-musl": "0.9.55",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.55",
-				"@bastani/atomic-natives-linux-x64-musl": "0.9.55",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.55",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.55"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.56",
+				"@bastani/atomic-natives-darwin-x64": "0.9.56",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.56",
+				"@bastani/atomic-natives-linux-arm64-musl": "0.9.56",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.56",
+				"@bastani/atomic-natives-linux-x64-musl": "0.9.56",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.56",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.56"
 			},
 			"engines": {
 				"bun": ">=1.4.2",
@@ -446,8 +446,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.56.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -458,8 +458,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.56.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -470,8 +470,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.56.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -485,8 +485,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-musl": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.56.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -500,8 +500,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.56.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -515,8 +515,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-musl": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.56.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -530,8 +530,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.56.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -542,8 +542,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.56.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -554,8 +554,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/pi-ai": {
-			"version": "0.9.55",
-			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.55.tgz",
+			"version": "0.9.56",
+			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.56.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.129.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.55",
+  "version": "0.9.56",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -89,8 +89,8 @@
     "prepublishOnly": "bun run clean && bun run build && bun run shrinkwrap"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.55",
-    "@bastani/pi-ai": "0.9.55",
+    "@bastani/atomic-natives": "0.9.56",
+    "@bastani/pi-ai": "0.9.56",
     "@earendil-works/pi-agent-core": "1.4.0",
     "@earendil-works/pi-codemode": "1.4.0",
     "@earendil-works/pi-tui": "1.4.0",

package/schemas/settings.schema.json

@@ -386,6 +386,14 @@
       },
       "description": "Command used for npm package lookup and installation, in argv form such as [\"mise\", \"exec\", \"node@20\", \"--\", \"npm\"]."
     },
+    "selfUpdateCommand": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "minItems": 1,
+      "description": "Command `atomic update` runs to update Atomic itself, in argv form such as [\"mise\", \"use\", \"-g\", \"npm:{packageName}@{version}\"]. Placeholders: {packageName}, {version}, {installSpec}. ATOMIC_SELF_UPDATE_COMMAND takes precedence. Global setting only."
+    },
     "collapseChangelog": {
       "type": "boolean",
       "description": "Show the condensed changelog after update; use /changelog for the full changelog.",