@inixiative/agent-session 0.10.0 → 0.11.1

package/README.md

@@ -1,17 +1,19 @@
 # @inixiative/agent-session
 
-Drive coding-agent CLIs as **persistent, streaming, event-captured sessions** —
-one interface, any agent, over interchangeable **transports**. Claude Code
-(CLI or Agent SDK) and Codex (app-server) today; Gemini and Grok planned.
-Also: warm **primed decision sessions**, **subscription pools** with
+> Part of [inixiative](https://www.inixiative.com), technology for cooperation. See [all the projects](https://github.com/inixiative).
+
+Drive Claude Code, Codex and Muse as persistent streaming sessions behind one
+interface. Claude Code runs over its CLI or the Agent SDK, Codex over its
+app-server and Muse over `muse serve`; Gemini and Grok are planned. The package
+also holds warm **primed decision sessions**, **subscription pools** with
 deterministic routing, **limit polling** and **session continuity**.
 
-Most ways to script a coding agent are one-shot (`claude -p "…"`) and lose the
-process. `agent-session` keeps a single long-lived agent process, streams turns
-in over stdin, and classifies **every** event coming back — text, thinking,
-tool calls, tool results, usage — so you can drive multi-turn work and capture
-exactly what the agent did. Built for eval harnesses, agent comparisons, and
-multi-agent orchestration.
+A one-shot call (`claude -p "…"`) ends the process after one answer.
+`agent-session` keeps one long-lived agent process per session, sends each turn
+in over stdin, and classifies each event that comes back (text, thinking, tool
+calls, tool results, usage), so you can drive multi-turn work and record what
+the agent did. Foundry, Oracle and Archive run their agent sessions on it, as do
+our eval harnesses and agent comparisons.
 
 ```ts
 import { ClaudeCodeSession } from "@inixiative/agent-session";
@@ -33,23 +35,23 @@ for (const e of result.events) {      // full classified event stream
 session.kill();
 ```
 
-## Why it's different
+## What you get
 
 - **Persistent, multi-turn.** One process per session; `send()` per turn,
-  resolves on the runtime's `result` event. Not one-shot `-p`.
+  resolves on the runtime's `result` event.
 - **Full event capture.** A normalized `SessionEvent` taxonomy
   (`text` / `thinking` / `tool_use` / `tool_result` / `result` / `error` /
-  `session_compact`) — the same shape regardless of runtime.
+  `session_compact`), the same shape for every runtime.
 - **Subscription auth, no API billing.** The Claude Code adapter strips
   `ANTHROPIC_API_KEY` and authenticates via the CLI's subscription / an
-  `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token` — works headless and in
+  `CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`; it works headless and in
   containers.
 - **Images with a turn.** `send(text, { images: [{ mediaType, data }] })` (png, jpeg, gif or
   webp, base64) where the transport declares `capabilities.images`: Claude gets base64 `image`
   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 — e.g. inject just-in-time context per turn).
+  message, for example to add context for that turn).
 - **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
@@ -57,9 +59,10 @@ session.kill();
   with the `cwd` the lookup ran in). No turn ran, so the attempt settles as a no-send instead of
   uncertain native work, and the caller can start fresh from its own record.
 - **Transports with declared capabilities.** How a model is reached is a
-  pluggable transport; switching it is a routing change, not a rewrite.
-- **Zero dependencies.** Just Bun + the agent CLI you're driving. The Agent SDK
-  transport takes the SDK's `query` from the caller.
+  pluggable transport; switching it is a routing change.
+- **Two dependencies.** `@inixiative/json-rules` and Meta's `@muse-code/sdk`
+  (for the Muse transport), plus Bun and the agent CLI you're driving. The Agent
+  SDK transport takes the SDK's `query` from the caller.
 
 ## Interface
 
@@ -272,15 +275,15 @@ snapshots in the artifact but do not fabricate a completed-turn total.
 | Gemini CLI | planned |
 | Grok CLI | planned (when its headless/stream mode matures) |
 
-Opaque runtimes degrade gracefully — fewer event types, never a hard failure.
+A runtime that reports less produces fewer event types; it never fails a turn for that.
 
 [Subscription pooling goals](tickets/README.md) (AS-001…005) are implemented as described in [docs/transports-pools-routing.md](docs/transports-pools-routing.md); each ticket lists what remains.
 
 ## Provenance
 
 Extracted from [`inixiative/foundry`](https://github.com/inixiative/foundry),
-where this drives the Artificer session. Consumed by foundry, oracle,
-and the inixiative bench.
+where it runs Foundry's agent sessions. Foundry, Oracle, Archive and the
+inixiative bench use it.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.10.0",
+  "version": "0.11.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",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.183",
+    "@inixiative/config": "^0.5.186",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/claude-agent-sdk-session.ts

@@ -187,7 +187,7 @@ function bridge(
     const awaiting = new Map<string, (response: unknown) => void>();
     const ask = (request: Record<string, unknown>, signal?: AbortSignal) =>
       new Promise<unknown>((resolve) => {
-        const id = `sdk-bridge-${crypto.randomUUID()}`;
+        const id = `sdk-bridge-${Bun.randomUUIDv7()}`;
         awaiting.set(id, resolve);
         signal?.addEventListener(
           'abort',

package/src/claude-code-session.ts

@@ -379,7 +379,7 @@ export class ClaudeCodeSession implements HarnessSession {
   private _steerAcks = new Map<string, (state: SteerState) => void>();
   /** Steers written and not yet ended natively: a late `completed` after their turn settled is theirs. */
   private _steerUuids = new Set<string>();
-  private readonly _hookCallbackId = `agent-session-pre-tool-${crypto.randomUUID()}`;
+  private readonly _hookCallbackId = `agent-session-pre-tool-${Bun.randomUUIDv7()}`;
   private _limits?: LimitSnapshot;
   private _controlSeq = 0;
   private _control = new Map<
@@ -555,7 +555,7 @@ export class ClaudeCodeSession implements HarnessSession {
     if (!turn || !a || a.dispatch !== 'attempted' || a.nativeOutcome !== 'unknown')
       return ignored('no owned in-flight turn');
     if (!this._proc || !this._alive) return ignored('session not running');
-    const uuid = crypto.randomUUID();
+    const uuid = Bun.randomUUIDv7();
     turn.steers ??= new Map();
     const steers = turn.steers;
     steers.set(uuid, 'written');
@@ -999,7 +999,7 @@ export class ClaudeCodeSession implements HarnessSession {
     timeoutMs: number,
   ): Promise<Record<string, unknown>> {
     if (!this._proc || !this._alive) return Promise.reject(new Error('Session not running'));
-    const requestId = `agent-session-${++this._controlSeq}-${crypto.randomUUID()}`;
+    const requestId = `agent-session-${++this._controlSeq}-${Bun.randomUUIDv7()}`;
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this._control.delete(requestId);

package/src/claude-in-session.ts

@@ -1068,7 +1068,7 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
   }
 
   private async _admit(member: Member): Promise<boolean> {
-    member.admissionId ??= crypto.randomUUID();
+    member.admissionId ??= Bun.randomUUIDv7();
     if (member.admitted) return true;
     try {
       await Promise.race([

package/src/claude-subagents.ts

@@ -472,7 +472,7 @@ export class ClaudeSubagentSessions implements PrimedSessions {
 
   /** Admit a decision onto its spare; the input goes out when the spare's moment call is held. */
   private async _reserve(spare: Spare, member: Member): Promise<void> {
-    member.admissionId = crypto.randomUUID();
+    member.admissionId = Bun.randomUUIDv7();
     const ours = () => spare.member === member && member.spare === spare;
     try {
       await Promise.race([
@@ -789,7 +789,7 @@ export class ClaudeSubagentSessions implements PrimedSessions {
       return;
     }
     const spares = [...side.spares.values()];
-    const uuid = crypto.randomUUID();
+    const uuid = Bun.randomUUIDv7();
     const turnEnded = new Promise<void>((resolve) => {
       side.onResult = resolve;
     });
@@ -1041,7 +1041,7 @@ export class ClaudeSubagentSessions implements PrimedSessions {
   }
 
   private _control(side: Side, request: Record<string, unknown>, timeoutMs = 30_000) {
-    const id = `c-${crypto.randomUUID()}`;
+    const id = `c-${Bun.randomUUIDv7()}`;
     return new Promise<Record<string, unknown>>((resolve, reject) => {
       const timer = setTimeout(() => {
         side.control.delete(id);
@@ -1417,7 +1417,7 @@ export class ClaudeSubagentSessions implements PrimedSessions {
     await Promise.all(
       chunk.map(async (m) => {
         if (m.settled) return;
-        m.admissionId ??= crypto.randomUUID();
+        m.admissionId ??= Bun.randomUUIDv7();
         try {
           if (!retry && !m.admitted)
             await Promise.race([
@@ -1463,7 +1463,7 @@ export class ClaudeSubagentSessions implements PrimedSessions {
       m.token = `m${i + 1}`;
     });
     side.members = new Map(admitted.map((m) => [m.token, m]));
-    const uuid = crypto.randomUUID();
+    const uuid = Bun.randomUUIDv7();
     const turnEnded = new Promise<void>((resolve) => {
       side.onResult = resolve;
     });

package/src/codex-primed.ts

@@ -1335,7 +1335,7 @@ export class CodexPrimedSessions implements PrimedSessions {
       if (session) session.model ??= model;
       const branchMs = Math.round(performance.now() - t1);
       let branch = opened.branch;
-      admissionId = crypto.randomUUID();
+      admissionId = Bun.randomUUIDv7();
       try {
         await request.onAdmission?.({ admissionId, key: spec.key, runtime: 'codex', threadId });
       } catch (cause) {

package/src/pool.ts

@@ -584,7 +584,7 @@ export class SubscriptionPool {
     utilizationPercent: number | null,
     rank: number,
   ): Lease {
-    const leaseId = crypto.randomUUID();
+    const leaseId = Bun.randomUUIDv7();
     state.leases.add(leaseId);
     let released = false;
     const lease: Lease = {

package/src/secret-scratch.ts

@@ -208,27 +208,66 @@ export class SecretScratchPad {
     return this._dir;
   }
 
-  /** Lift every `$$word` out of `text` into `thread`'s pad, under the dagger for `message`. */
+  /**
+   * Lift every `$$word` out of `text` into `thread`'s pad, under the dagger for `message`. With
+   * `patterns` (global regexes, e.g. a caller's known token shapes), every match is lifted too, the
+   * person having forgotten the marker; a match may span lines (a private key). Positions follow the
+   * text's order; a match inside another lifted span is left to it. `recognised` counts the matches.
+   */
   lift(
     text: string,
     at: { thread: string; message: string; now?: Date },
-  ): { text: string; refs: string[] } {
-    const values = [...text.matchAll(MARKED)].map((match) => match[2] ?? '');
-    if (!values.length) return { text, refs: [] };
+    options: { patterns?: readonly RegExp[] } = {},
+  ): { text: string; refs: string[]; recognised: number } {
+    const spans: Array<{
+      start: number;
+      end: number;
+      value: string;
+      marked: boolean;
+    }> = [];
+    for (const match of text.matchAll(MARKED)) {
+      const lead = match[1] ?? '';
+      spans.push({
+        start: (match.index ?? 0) + lead.length,
+        end: (match.index ?? 0) + match[0].length,
+        value: match[2] ?? '',
+        marked: true,
+      });
+    }
+    for (const pattern of options.patterns ?? []) {
+      if (!pattern.global) throw new SecretScratchError('A lift pattern must be global (/g).');
+      for (const match of text.matchAll(pattern)) {
+        if (!match[0]) continue;
+        const start = match.index ?? 0;
+        spans.push({
+          start,
+          end: start + match[0].length,
+          value: match[0],
+          marked: false,
+        });
+      }
+    }
+    if (!spans.length) return { text, refs: [], recognised: 0 };
+    // Earliest first, the longer of two at one place; a span overlapping a kept one is dropped.
+    spans.sort((a, b) => a.start - b.start || b.end - a.end);
+    const kept: typeof spans = [];
+    for (const span of spans)
+      if (!kept.length || span.start >= kept[kept.length - 1]!.end) kept.push(span);
     checkId(at.thread, 'thread');
     checkId(at.message, 'message');
     const daggers = this._read(at.thread);
     let dagger = daggers.find((d) => d.message === at.message);
     const first = dagger ? Math.max(0, ...dagger.blocks.keys()) + 1 : 1;
-    const refs: string[] = [];
-    const lifted = text.replace(MARKED, (_whole, lead: string) => {
-      const ref = formatScratchRef(
-        { thread: at.thread, message: at.message, position: first + refs.length },
-        at.thread,
-      );
-      refs.push(ref);
-      return `${lead}${ref}`;
+    const refs = kept.map((_, i) =>
+      formatScratchRef({ thread: at.thread, message: at.message, position: first + i }, at.thread),
+    );
+    let lifted = '';
+    let cursor = 0;
+    kept.forEach((span, i) => {
+      lifted += text.slice(cursor, span.start) + refs[i];
+      cursor = span.end;
     });
+    lifted += text.slice(cursor);
     if (!dagger) {
       dagger = {
         message: at.message,
@@ -238,9 +277,9 @@ export class SecretScratchPad {
       };
       daggers.push(dagger);
     }
-    for (const [i, value] of values.entries()) dagger.blocks.set(first + i, value);
+    for (const [i, span] of kept.entries()) dagger.blocks.set(first + i, span.value);
     this._write(at.thread, daggers);
-    return { text: lifted, refs };
+    return { text: lifted, refs, recognised: kept.filter((span) => !span.marked).length };
   }
 
   /** Every pad here (or one thread's) with what it holds pending, never the values. */

package/src/turn-state.ts

@@ -9,7 +9,7 @@ import {
 import { retainEvidence } from './retained-evidence';
 /** Per-admission evidence. Caller settlement never transfers native ownership. */
 export class TurnState {
-  readonly admissionId = crypto.randomUUID();
+  readonly admissionId = Bun.randomUUIDv7();
   identity: SessionIdentity = {};
   nativeOutcome: SessionAttempt['nativeOutcome'] = 'unknown';
   localOutcome: SessionAttempt['localOutcome'] = 'pending';