airlok 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to airlok. The format follows Keep a Changelog; versions follow SemVer.
 
+## [0.4.0] - 2026-09-11
+
+### Added
+
+- Interactive sessions: `airlok` with no task opens a REPL with a `<model> <dir>> ` prompt, `/help`, `/clear`, `/compact`, `/cost`, `/redactions`, `/config`, and `/exit`. Ctrl-C cancels the turn in progress and keeps the partial reply marked as interrupted; Ctrl-D saves and quits.
+- Sessions are saved after every turn under `$XDG_DATA_HOME/airlok/sessions/<dir hash>/` (`~/.local/share/airlok` by default), mode 0600 in a 0700 directory, with the config snapshot, provider and model, plaintext history, redaction map, token counts, and timestamps. The provider API key is stored blank. `--resume` continues the latest session for the directory (`--resume=<id>` a particular one), rebuilding the context block and adding a system note with the resume time. `airlok sessions` lists them, `sessions rm <id>` deletes one, `sessions clean --older-than 30d` prunes every directory.
+- Compaction: once the last request used more than `[agent] compact_at` (0.75) of `[provider] context_window` (200k), the next turn replaces everything but the last `[agent] keep_recent_turns` (4) turns with a model-written summary, requested through the redactor with no tools. Shown as a dim `compacted: X -> Y tokens` line and recorded in the session.
+- Token usage from both providers: Anthropic `message_start`/`message_delta` counts, OpenAI `stream_options.include_usage`. Where a provider reports none, requests are estimated at chars/4 and `/cost` says so.
+
+### Changed
+
+- A turn that fails or is aborted no longer leaves its prompt in the history.
+
+## [0.3.1] - 2026-09-11
+
+### Security
+
+- The provider API key could be shown in the terminal: it was an ordinary redaction entry, so when the model echoed its placeholder the display path rehydrated it. Redaction entries now have a class. `rehydrate` entries (secrets found in files and tool output) are restored into files and commands and shown masked in the terminal, with `[redact] show_secrets_in_output = true` to opt into full display. `redact-only` entries, the provider API key, are never restored anywhere: the terminal shows `[redacted: the provider API key]` and a tool call carrying the placeholder is refused. `airlok redactions` lists kinds and classes; `--show-redactions` now shows the class.
+
 ## [0.3.0] - 2026-09-11
 
 ### Added

package/README.md

@@ -15,7 +15,13 @@ brew install airlok-dev/tap/airlok
 ## Usage
 
 ```sh
+airlok                                         # interactive session in the current directory
 airlok "create hello.txt containing hello"     # run one task in the current directory
+airlok --resume                                # continue the latest saved session here (REPL, or with a task)
+airlok --resume=<id> "summarise what we did"   # continue a particular one
+airlok sessions                                # list saved sessions for this directory
+airlok sessions rm <id>                        # delete one
+airlok sessions clean --older-than 30d         # delete old sessions from every directory
 airlok -v "..."                                # debug logs on stderr
 airlok -y "..."                                # no confirmations (prints a warning)
 airlok --provider openai --model gpt-5.5 "..." # override the provider and model for one run
@@ -23,12 +29,33 @@ airlok --show-redactions "..."                 # list what was redacted (kind an
 airlok config init                             # write a commented config to the user path
 airlok config show                             # print the effective config and the key source
 airlok context                                 # print the context block sent with the system prompt, after redaction
+airlok redactions                              # list what the redactor detects and how each kind is treated
 ```
 
 Every `write_file` and `edit_file` call shows a unified diff and asks `Apply? [y]es / [n]o / [a]ll / [q]uit`. Every `bash` call that is not on the allow list shows the command and asks the same way. `y` applies this one, `n` sends a rejection back to the model so it can adapt, `a` approves the rest of that kind for the run, and `q` aborts the run with a non-zero exit. Prompts are read from the terminal, not stdin, so piped input still works; without a terminal, pass `--yes` or turn the confirmations off in the config.
 
 Model output is rendered as markdown (headings, emphasis, lists, tables, highlighted code) when stdout is a terminal; set `NO_COLOR` or redirect stdout for plain text. Runs of read-only tool calls collapse to one `reading N files...` line; `-v` shows every call.
 
+### Sessions
+
+`airlok` with no task opens a session. The prompt shows the model and the directory (`gpt-5.5 airlok> `), each line you type is one turn, and the conversation carries across turns. Ctrl-C during a turn cancels it: the text streamed so far stays in the history marked as interrupted, tool calls that had not run are dropped, and you get the prompt back. Ctrl-D or `/exit` saves and quits.
+
+| Command | What it does |
+|---|---|
+| `/help` | list the commands |
+| `/clear` | start a new session; the current one stays saved |
+| `/compact` | summarise older turns to free context |
+| `/cost` | tokens used so far, and whether they are estimates |
+| `/redactions` | what was redacted before leaving this machine (kind and length only) |
+| `/config` | the effective configuration |
+| `/exit` | save and quit |
+
+Every turn, one-shot or interactive, is saved under `$XDG_DATA_HOME/airlok/sessions/<hash of the directory>/` (`~/.local/share/airlok` by default). `airlok --resume` picks up the latest session for the directory; it rebuilds the context block, so the model sees the current tree and git state, and adds a note with the resume time. `airlok sessions` lists what is there.
+
+A session file holds the plaintext conversation and the real value behind every placeholder, because that is what rehydration on resume needs. That is why the file is written with mode 0600 in a 0700 directory, and why the provider API key is the one thing left out: it is stored blank and re-read from your config on every start.
+
+Long sessions are compacted. Once the last request used more than `compact_at` (default 0.75) of `context_window` (default 200k tokens; set it for your model), the next turn first asks the model for a summary of everything except the last `keep_recent_turns` turns and replaces those older turns with it. The summary request goes through the redactor like every other request. You see a dim `compacted: 180k -> 22k tokens` line; `/compact` does it on demand. Token counts come from the provider; when a provider reports none, airlok estimates at chars/4 and `/cost` says so.
+
 ## Tools
 
 | Tool | Asks? | What it does |
@@ -72,11 +99,14 @@ model = "claude-sonnet-4-6"   # per provider: anthropic "claude-sonnet-4-6", ope
 # base_url = "https://api.openai.com/v1"   # openai only; Azure: "https://<resource>.openai.azure.com/openai/v1"
 # api_key_env = "ANTHROPIC_API_KEY"        # env var holding the key
 # api_key_cmd = "..."                      # shell command whose stdout is the key
+context_window = 200000       # input tokens the model accepts; used to decide when to compact
 
 [agent]
 max_turns = 50           # model round-trips per run
 max_tokens = 8192        # output tokens per model reply
 bash_timeout_secs = 120  # kill a bash tool command after this long
+compact_at = 0.75        # summarise the session once a request uses this fraction of context_window
+keep_recent_turns = 4    # turns kept verbatim after the summary
 
 [safety]
 confirm_writes = true    # show a diff and ask before write_file / edit_file
@@ -86,10 +116,17 @@ bash_denylist = ["rm -rf", "git push --force", "sudo"]
 
 [context]
 max_bytes = 32768        # cap on the context block; tree is cut first, then instructions
+
+[redact]
+show_secrets_in_output = false   # show secrets from files in full in the terminal instead of masked
 ```
 
 For openai, `base_url` falls back to the `OPENAI_BASE_URL` environment variable when the config does not set it.
 
+### What comes back, and what never does
+
+Every placeholder belongs to one of two classes, listed by `airlok redactions`. Secrets found in your files and in tool output are `rehydrate`: the real value is restored into files and commands, so edits keep working, and shown masked in the terminal (first four characters and the length) unless `[redact] show_secrets_in_output = true`. The provider API key is `redact-only`: it is never restored anywhere. If the model echoes its placeholder it prints as `[redacted: the provider API key]`, and a tool call carrying it is refused with a message to the model. `--show-redactions` lists each placeholder's kind, length, and class, never the value.
+
 The key is read from exactly one place. `api_key_cmd` wins if set, then `api_key_env`, then the provider default: `ANTHROPIC_API_KEY` for anthropic, and `AZURE_OPENAI_API_KEY` then `OPENAI_API_KEY` for openai. A command runs once per process and its output is never logged. `airlok config show` prints the env var name or the command, never the value. Whatever key is in use is also added to the redactor, so it can never leave the machine inside a file or command output either.
 
 Allow-list entries match on leading tokens (`git status` allows `git status --short`, not `git push`). Deny-list entries match anywhere, in every part of a chained command, and win over the allow list. Flags are parsed rather than compared as text: the `rm -rf` entry also catches `rm -fr`, `rm -r -f`, `rm -Rf`, and `rm --recursive --force`, and `git push --force` also catches `git push -f`. A command with shell operators (`;`, `&&`, `|`, `>`, `$(`, and so on) always asks, whatever its first word.

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT OR Apache-2.0",
       "name": "airlok",
-      "version": "0.3.0"
+      "version": "0.4.0"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.3.0"
+  "version": "0.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/airlok-dev/airlok/releases/download/v0.3.0"
+    "https://github.com/airlok-dev/airlok/releases/download/v0.4.0"
   ],
   "bin": {
     "airlok": "run-airlok.js"
@@ -60,7 +60,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.3.0",
+  "version": "0.4.0",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"