@inixiative/agent-session 0.12.0 → 0.12.1

package/README.md

@@ -51,7 +51,8 @@ session.kill();
   blocks in the same user message, Codex `image` inputs with a `data:` URL. Anything else is
   refused before a byte is written.
 - **fork / resume / interrupt** and pre-send hooks (rewrite the outgoing
-  message, for example to add context for that turn).
+  message, for example to add context for that turn). Resume is configuration, not a
+  method: build the session with `externalSessionId`.
 - **A resume whose native conversation is not found is typed.** Claude finding no transcript
   ("No conversation found with session ID": cleaned up, deleted, or under another project
   directory or config home) and Codex finding no rollout ("no rollout found for thread id") both
@@ -96,12 +97,13 @@ Codex runs only over `codex app-server --listen stdio://` (`CodexAppServerSessio
 Codex CLI 0.155 has no `mcp-server` subcommand.
 
 Muse Code runs over `muse serve` through Meta's `@muse-code/sdk` (`MuseSession`), pinned to
-the CLI's version (1.4.14): a host serving another version is refused at start. It bills the
+the CLI's version (1.4.20): a host serving another version is refused at start. It bills the
 saved Muse login: metered keys and endpoints never reach it (nor Muse's own tool runs, which
 inherit its environment: a repo command needing `OPENAI_API_KEY` will not see it under Muse),
 and a resumed session must be on provider `meta`. Per-login isolation is `env: { XDG_CONFIG_HOME, XDG_DATA_HOME }` (login and
-sessions). `musePermissions(mode)` maps the host modes to an explicit permission profile, because
-the host default lets Muse's AI reviewer answer approvals instead of the gates. Questions arrive
+sessions). The session's `permissionMode` (default `default`, gated) goes through `musePermissions(mode)`
+to an explicit permission profile, because the host default lets Muse's AI reviewer answer
+approvals instead of the gates. Questions arrive
 through `onUserInput()`; unanswered ones are cancelled with a reason. An approval offering
 no approve-once or reject choice is reported as an `error` event and left open (the turn ends
 at its timeout). Work Muse starts itself
@@ -233,9 +235,11 @@ const result = await decisions.decide(spec, { input, standby });
   main thread, which wakes the main model (Claude Code 2.1.300). Members of a
   dispatcher that ended unasked are therefore never retired or stopped, and an
   orphan's `answer` call is held for the session's life. Past `maxOrphans`
-  (40) the host stops serving and its caller falls back.
+  (40) `serving()` turns false and `setup` reports `degraded`; `decide()` does
+  not refuse on its own, so the caller checks `serving()` and falls back.
 - **Limits.** Claude Code runs 20 subagents at once by default; the launch
-  raises `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` (`maxSubagents`, 96). The
+  raises `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` to the user's own cap (20 when
+  unset) plus `maxSubagents` (76), so 96 by default. The
   session declares `perTaskStopAffordance`, so the user's Stop spares
   background agents.
 
@@ -251,9 +255,12 @@ const pool = new SubscriptionPool({ instances: [
 const { session, lease } = await pool.open({ runtime: "claude", model: "sonnet", organizationId: "org", preferredInstanceId: "work" });
 ```
 
-Routing is deterministic (quartile-balanced, owner-first or pinned) over
-observed limits, leases and health; stale or unknown limits exclude an instance
-and every exclusion has a reason. `continueOn` moves a thread only between
+Routing is deterministic over observed limits, priority, leases and health, by a
+named strategy (`quartile-balanced` by default, `owner-first`, `priority-balanced`,
+`priority-strict`, `least-used`) or an explicit term list; `pinned` restricts it to
+the preferred instance. By default stale or unknown limits exclude an instance
+(`unknownUtilization: 'rank-last'` ranks it last instead), and every exclusion has a
+reason. `continueOn` moves a thread only between
 instances that share native history, and says why when it cannot.
 
 ## Usage telemetry
@@ -271,6 +278,33 @@ model and tags) in `raw`; they may repeat across content blocks. Do not sum
 request snapshots together with result totals. Interrupted turns retain request
 snapshots in the artifact but do not fabricate a completed-turn total.
 
+## Secret scratch pad
+
+A person can hand an agent a secret as `$$word`. `SecretScratchPad(dir)` lifts it out
+of the message before the agent sees it (`lift`), into a private pad per thread
+(`<thread>.pad`, 0600 in a 0700 directory), and leaves a reference in its place:
+`†<message>.<n>` inside its thread, `†<thread>/<message>.<n>` from anywhere else.
+`lift(text, at, { patterns })` also lifts matches of the caller's global regexes, for
+tokens the person forgot to mark, and counts them as `recognised`.
+
+The agent uses a value without reading it. `env` sets `KEY=value` in an env file,
+`write` puts it in a file, and `pipe` runs a command with the value on its stdin,
+from a reference or a key already in an env file; only the exit code comes back, and
+a timeout kills the whole process group. `consume` (or `consume: true` on a use)
+removes a block, `list` shows what is pending without values, `scrub` swaps held
+values in text back to references, and `clear` deletes a pad.
+
+Files `env` and `write` touched are recorded (`heldFiles()`). `privatePathGate`
+(or `privatePathDenial` inside your own gate) denies a tool call naming one of them,
+a `.private` path, a `privatePaths` glob or the pad directory; `isOwnTool` exempts the
+scratch tool's own calls. A `privatePathGate` keeps the `heldFiles` list it was built
+with: rebuild it after `env` or `write`, or call
+`privatePathDenial(request, { scratchDir: pad.dir, heldFiles: pad.heldFiles() })` in your
+own gate on each request. `SECRET_SCRATCH_GUIDANCE` is the text to give the agent.
+The gate reads names, not contents, and a pipe command can still copy a value out:
+it keeps honest agents from reading secrets, it is not a sandbox. Design and
+limits: [tickets/AS-009](tickets/AS-009-secret-scratch-pad.md).
+
 ## Roadmap
 
 | Runtime | Status |
@@ -299,4 +333,4 @@ MIT
 
 ## Runtime
 
-Development and new continuation captures use Bun 1.4.2, pinned in `.bun-version` and `package.json`. Historical S0 recordings retain their original Bun 1.3.14 evidence; they are not new 1.4.2 captures.
+Development and new continuation captures use Bun 1.4.4, pinned in `.bun-version` and `package.json`. Historical S0 recordings retain their original Bun 1.3.14 evidence; they are not new 1.4.4 captures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "Drive coding-agent CLIs as persistent, streaming, event-captured sessions over interchangeable transports, with primed decision sessions, subscription pools, routing, limit polling and continuity.",
   "type": "module",
   "main": "src/index.ts",
@@ -18,6 +18,7 @@
     "check": "bun run typecheck && bun run lint && bun run test",
     "prepublishOnly": "bun run check",
     "measure:primed": "bun scripts/measure-primed.ts",
+    "record:muse": "bun scripts/record-muse.ts",
     "lint": "biome check .",
     "prepare": "if git rev-parse --git-dir >/dev/null 2>&1; then lefthook install; fi"
   },
@@ -36,12 +37,12 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inixiative/json-rules": "^3.16.0",
-    "@muse-code/sdk": "1.4.14"
+    "@inixiative/json-rules": "^3.22.0",
+    "@muse-code/sdk": "1.4.20"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.187",
+    "@inixiative/config": "^0.5.212",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/muse-session.ts

@@ -40,17 +40,18 @@ import { TurnState } from './turn-state';
 // ---------------------------------------------------------------------------
 // MuseSession — one `muse serve` host per session, driven through Meta's
 // `@muse-code/sdk` MuseClient (Muse Session Protocol). The facade opens the
-// session, submits turns, answers approvals and folds the view; the calls it
-// lacks (turn/interrupt, turn/steer, session/fork, session/setApprovalMode,
-// usage/read, userInput/cancel) go through the same connection's `command`.
+// session, submits turns, answers approvals and folds the view. turn/interrupt,
+// turn/steer, session/fork, session/setApprovalMode, usage/read and
+// userInput/cancel go through the same connection's `command`, written before
+// the facade had them (1.4.14) and kept on the raw wire, whose types 1.4.20 keeps.
 // Every view notification is classified into the shared SessionEvent taxonomy.
 // The Muse session id is the externalSessionId used for cold resume.
 //
-// Wire contract: Muse Code 1.4.14 / @muse-code/sdk 1.4.14 (lockstep).
+// Wire contract: Muse Code 1.4.20 / @muse-code/sdk 1.4.20 (lockstep).
 // ---------------------------------------------------------------------------
 
 /** The SDK version this session is built against; the served CLI must report the same. */
-export const MUSE_SDK_VERSION = '1.4.14';
+export const MUSE_SDK_VERSION = '1.4.20';
 
 export type MuseApprovalMode = 'allowAll' | 'promptUnmatched';
 export type MusePermissionProfile = ':ask-me' | ':read-only' | ':unrestricted';
@@ -226,13 +227,15 @@ const CLIENT_INFO = { name: 'agent_session', title: 'agent-session', version: '1
 
 /**
  * Inherited variables that would bill, route or loosen Muse away from its saved subscription login
- * and the gates, by the names the 1.4.14 binary reads: metered keys and endpoints (META_, LLM_,
+ * and the gates, by the names the 1.4.20 binary reads: metered keys and endpoints (META_, LLM_,
  * MODEL_, LLAMA_, OPENROUTER_, ANTHROPIC_, OPENAI_), Meta's auth and key-mint endpoints, and MUSE_
- * switches for the model, experiments, contributor mode, the approval judge and a fail-open
- * profile. Muse's own tool runs inherit this environment, so they do not see these either.
+ * switches for the model, experiments, contributor mode, the approval judge, a fail-open profile,
+ * request routing and custom headers, the computer-use dev policy and identity skip, the launcher's
+ * channel and install switches, the credential backend, and the eval and test hooks (prompt injection,
+ * policy and grant overrides). The CA and TLS roots stay: a machine behind a proxy needs them. Muse's own tool runs inherit this environment, so they do not see these either.
  */
 const COMPETING_ENV =
-  /^(META_|LLM_|MODEL_|LLAMA_|OPENROUTER_|ANTHROPIC_|OPENAI_|TBH_(AUTH|MINT)_BASE_URL$|MUSE_EXPERIMENTAL_|MUSE_(MODEL|CONTRIBUTOR_MODE|DISABLE_APPROVAL_JUDGE|PERMISSION_PROFILE_FAIL_OPEN)$)/;
+  /^(META_|LLM_|MODEL_|LLAMA_|OPENROUTER_|ANTHROPIC_|OPENAI_|TBH_(AUTH|MINT)_BASE_URL$|MUSE_EXPERIMENTAL_|TBH_(CREDENTIAL_BACKEND$|EVAL_|TEST_)|MUSE_CUA_DEV_|MUSE_(MODEL|CHANNEL|LAUNCHER_INSTALL|CONTRIBUTOR_MODE|DISABLE_APPROVAL_JUDGE|PERMISSION_PROFILE_FAIL_OPEN|WWW_ROUTING|CUSTOM_HEADERS)$)/;
 
 export class MuseSession implements HarnessSession {
   get transport() {
@@ -1914,10 +1917,10 @@ export class MuseSession implements HarnessSession {
 }
 
 // ---------------------------------------------------------------------------
-// Default host: `muse serve` through the SDK's owned-process handshake
+// Default host: `muse serve` through the SDK's owned-process handshake; exported for scripts/record-muse.ts
 // ---------------------------------------------------------------------------
 
-async function spawnMuseHost(launch: MuseLaunch): Promise<MuseHost> {
+export async function spawnMuseHost(launch: MuseLaunch): Promise<MuseHost> {
   const handshake = spawnMspConnection({
     command: launch.museBin,
     args: launch.args,

package/src/transport.ts

@@ -143,12 +143,12 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
     },
     notes: [
       "`muse serve --trust-workspace` (plus `--disable-sandbox` under bypassPermissions) driven through Meta's `@muse-code/sdk` MuseClient, pinned to the installed CLI's version.",
-      'Billing is the saved Muse Code login: metered keys and endpoints (META_, LLM_, MODEL_, LLAMA_, OPENROUTER_, ANTHROPIC_, OPENAI_), Meta auth endpoints (TBH_) and the MUSE_ model, experiment, contributor, approval-judge and fail-open switches are removed from the child environment; a resumed or forked session must report provider `meta`.',
+      'Billing is the saved Muse Code login: metered keys and endpoints (META_, LLM_, MODEL_, LLAMA_, OPENROUTER_, ANTHROPIC_, OPENAI_), Meta auth endpoints (TBH_) and the MUSE_ model, experiment, contributor, approval-judge, fail-open, routing, custom-header, computer-use dev, channel and install switches, and the TBH_ credential backend and eval/test hooks are removed from the child environment; a resumed or forked session must report provider `meta`.',
       'Approvals use an explicit permission profile (`:ask-me` supervised, `:read-only` plan, `:unrestricted` bypass), never the host default `:auto-review`, whose AI reviewer would decide instead of the gates; the committed profile, approval mode and (gated) a human reviewer are read back before any turn.',
       "Work Muse starts itself (cron firings, monitor and background-terminal wakes, goals, reminder agents, workflows, another client's messages) is folded like a turn's and emitted with `unattributedReason: 'task'`, plus a `task` lifecycle typed `muse-cron`, `muse-monitor`, `muse-goal`, `muse-reminder`, `muse-workflow` or `muse-turn`; it is seen only while this host has the session loaded.",
       "interruptNative() sends turn/interrupt; push() sends turn/steer; fork() runs session/fork on the new session's own host; readLimits() sends usage/read.",
       'userInput/request questions go to onUserInput(); without an answer they are cancelled with a reason, so a turn never waits on them.',
-      'Live-verified (muse 1.4.14): start, profile read-back, multi-stage shell and network approvals, text and tool events, token usage, usage/changed and usage/read (recorded in fixtures/muse); fork, resume with setApprovalMode and sessionNotFound were checked live without a model turn (not recorded). A steer (`turn/steer` into a running shell turn, answered in that turn) was checked live 2026-11-02 (not recorded). Images, interrupt, questions and Muse-initiated turns follow the SDK wire types without a live run.',
+      'Live-verified (muse 1.4.20, 2026-11-15): start, profile read-back, multi-stage shell and network approvals, text and tool events, token usage, usage/changed and usage/read (recorded in fixtures/muse); fork, resume with setApprovalMode and sessionNotFound were checked live on 1.4.14 without a model turn (not recorded). A steer (`turn/steer` into a running shell turn, answered in that turn) and an interrupt (`turn/interrupt`, terminal `cancelled`) were checked live on 1.4.20, 2026-11-15 (not recorded). Images, questions and Muse-initiated turns follow the SDK wire types without a live run.',
     ],
   },
   'claude-agent-sdk': {