@inixiative/agent-session 0.6.8 → 0.8.0

package/README.md

@@ -74,24 +74,37 @@ arrive as `rate_limit` events.
 ```ts
 import { createSession, TRANSPORTS } from "@inixiative/agent-session";
 
-const kind = "codex-app-server";            // or claude-cli, claude-agent-sdk
+const kind = "codex-app-server";            // or claude-cli, claude-agent-sdk, muse-serve
 if (TRANSPORTS[kind].capabilities.interrupt === "acknowledged") { /* … */ }
 const session = createSession(kind, { cwd, model: "gpt-6-luna", env: { CODEX_HOME: profile } });
 ```
 
-| | claude-cli | codex-app-server | claude-agent-sdk | acp | api |
-|---|---|---|---|---|---|
-| Status | ✅ live | ✅ live | ✅ live | stub | stub |
-| Resume / fork | native / native | native / – | native / native | – | – |
-| Interrupt | acknowledged | acknowledged | acknowledged | – | – |
-| Push | – | steer | – | – | – |
-| Approvals | callback | callback | callback | – | – |
-| Limits stream / poll | ✅ / ✅ | ✅ / ✅ | ✅ / – | – | – |
-| Primed reset | fork | fork | – | – | – |
+| | claude-cli | codex-app-server | muse-serve | claude-agent-sdk | acp | api |
+|---|---|---|---|---|---|---|
+| Status | ✅ live | ✅ live | ✅ live | ✅ live | stub | stub |
+| Resume / fork | native / native | native / – | native / native | native / native | – | – |
+| Interrupt | acknowledged | acknowledged | acknowledged | acknowledged | – | – |
+| Push | – | steer | steer | – | – | – |
+| Approvals | callback | callback | callback | callback | – | – |
+| Limits stream / poll | ✅ / ✅ | ✅ / ✅ | ✅ / ✅ | ✅ / – | – | – |
+| Primed reset | fork | fork | – | – | – | – |
 
 Codex runs only over `codex app-server --listen stdio://` (`CodexAppServerSession`);
 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
+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
+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
+(cron firings, monitors, goals, reminder agents) is emitted too, marked
+`unattributedReason: "task"` with a `task` lifecycle typed `muse-cron`, `muse-monitor`, ….
+
 Full matrix, notes and what is stubbed: [docs/transports-pools-routing.md](docs/transports-pools-routing.md).
 
 ### Tool gate
@@ -254,6 +267,7 @@ snapshots in the artifact but do not fabricate a completed-turn total.
 | Claude Code | ✅ shipped |
 | Codex app-server | ✅ shipped (`CodexAppServerSession`, `CodexPrimedSessions`) |
 | Claude Agent SDK | ✅ shipped (`ClaudeAgentSdkSession`; caller supplies `query`) |
+| Muse Code | ✅ shipped (`MuseSession`, through `@muse-code/sdk`) |
 | ACP agents / direct API | typed stubs |
 | Gemini CLI | planned |
 | Grok CLI | planned (when its headless/stream mode matures) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.6.8",
+  "version": "0.8.0",
   "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",
@@ -36,18 +36,19 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inixiative/json-rules": "^3.5.4"
+    "@inixiative/json-rules": "^3.16.0",
+    "@muse-code/sdk": "1.4.14"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.118",
-    "@types/bun": "1.4.2",
+    "@inixiative/config": "^0.5.173",
+    "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"
   },
-  "packageManager": "bun@1.4.2",
+  "packageManager": "bun@1.4.4",
   "engines": {
-    "bun": ">=1.4.2"
+    "bun": ">=1.4.4"
   },
   "repository": {
     "type": "git",

package/src/claude-code-session.ts

@@ -59,6 +59,7 @@ import type {
   SessionSendOptions,
   SessionTokens,
   SubagentLifecycle,
+  TaskLifecycle,
   ToolDecision,
   ToolGate,
   ToolRequest,
@@ -385,6 +386,8 @@ export class ClaudeCodeSession implements HarnessSession {
   private _seenBoundaries = new Set<string>();
   /** Task ids whose task_started was a subagent (local_agent); later task frames carry no type. */
   private _agentTasks = new Set<string>();
+  /** Task ids whose task_started was another task type (a background shell, a monitor): id → type. */
+  private _otherTasks = new Map<string, string>();
 
   // -- Turn queue --
   private _queue: QueuedTurn[] = [];
@@ -829,6 +832,11 @@ export class ClaudeCodeSession implements HarnessSession {
     return turn.evidence.nativeOutcome === 'unknown' ? 'unacknowledged' : 'acknowledged';
   }
 
+  /** Stop a background task via the CLI control protocol (`stop_task`); its end comes as lifecycle. */
+  async stopTask(taskId: string, opts?: { timeoutMs?: number }): Promise<void> {
+    await this._controlRequest({ subtype: 'stop_task', task_id: taskId }, opts?.timeoutMs ?? 5_000);
+  }
+
   /** Account limits via the CLI control protocol (`get_usage`); no model turn. Requires a started session. */
   async readLimits(opts?: { timeoutMs?: number }): Promise<LimitSnapshot | undefined> {
     const response = await this._controlRequest(
@@ -1297,6 +1305,20 @@ export class ClaudeCodeSession implements HarnessSession {
         ? raw.parent_tool_use_id
         : undefined;
     const lifecycle = this._subagentLifecycle(raw);
+    // A background task (a shell, a monitor) outlives its turn like a subagent: never an admission's.
+    const task = lifecycle || parentToolUseId ? undefined : this._taskLifecycle(raw);
+    if (task) {
+      this._emit({
+        kind: 'task',
+        timestamp: Date.now(),
+        task,
+        raw,
+        correlation: 'unknown',
+        unattributedReason: 'task',
+        nativeSessionId: typeof raw.session_id === 'string' ? raw.session_id : undefined,
+      });
+      return;
+    }
     if (parentToolUseId || lifecycle) {
       const message = raw.message as Record<string, unknown> | undefined;
       const events: SessionEvent[] = lifecycle
@@ -1669,6 +1691,40 @@ export class ClaudeCodeSession implements HarnessSession {
     return claudeSubagentLifecycle(msg, phase, taskId);
   }
 
+  /**
+   * A Claude Code `system` task frame for a task that is not a subagent (`task_type` other than
+   * `local_agent`), as lifecycle. Later phases carry no task type: the session remembers it.
+   */
+  private _taskLifecycle(msg: Record<string, unknown>): TaskLifecycle | undefined {
+    if (msg.type !== 'system' || typeof msg.subtype !== 'string') return undefined;
+    const phase = CLAUDE_TASK_PHASES[msg.subtype];
+    const taskId = typeof msg.task_id === 'string' && msg.task_id ? msg.task_id : undefined;
+    if (!phase || !taskId) return undefined;
+    if (phase === 'started') {
+      if (typeof msg.task_type !== 'string' || msg.task_type === 'local_agent') return undefined;
+      this._otherTasks.set(taskId, msg.task_type);
+    }
+    const taskType = this._otherTasks.get(taskId);
+    if (!taskType) return undefined;
+    if (phase === 'ended') this._otherTasks.delete(taskId);
+    const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+    const patch =
+      msg.patch && typeof msg.patch === 'object' && !Array.isArray(msg.patch)
+        ? (msg.patch as Record<string, unknown>)
+        : undefined;
+    const status = text(msg.status) ?? text(patch?.status);
+    return {
+      phase,
+      taskId,
+      taskType,
+      ...(text(msg.tool_use_id) ? { toolUseId: text(msg.tool_use_id) } : {}),
+      ...(text(msg.description) ? { description: text(msg.description) } : {}),
+      ...(status ? { status } : {}),
+      ...(text(msg.reason) ? { reason: text(msg.reason) } : {}),
+      ...(text(msg.summary) ? { summary: text(msg.summary) } : {}),
+    };
+  }
+
   private _classify(msg: Record<string, unknown>, parentToolUseId?: string): SessionEvent[] {
     return this._classifyFrame(msg).map((event) =>
       parentToolUseId ? { ...event, parentToolUseId } : event,

package/src/harness-session.ts

@@ -11,7 +11,7 @@
 // captures every event for Oracle, and supports fork/interrupt.
 //
 // Implementations: ClaudeCodeSession, CodexAppServerSession,
-// ClaudeAgentSdkSession. How a model is reached is the session's transport
+// ClaudeAgentSdkSession, MuseSession. How a model is reached is the session's transport
 // (see transport.ts); every transport implements this one contract.
 // ---------------------------------------------------------------------------
 
@@ -84,12 +84,13 @@ export class SessionTurnError extends Error {
  * session's cwd and config home: Claude found no transcript ("No conversation found with session
  * ID": cleaned up, deleted, or kept under another project directory or `CLAUDE_CONFIG_DIR`), or
  * Codex found no rollout ("no rollout found for thread id": deleted, or under another
- * `CODEX_HOME`). No turn ran. The caller decides what comes next, typically a fresh session seeded
+ * `CODEX_HOME`), or Muse answered `sessionNotFound` (deleted, under another `XDG_DATA_HOME`, or
+ * an ephemeral host that died with it). No turn ran. The caller decides what comes next, typically a fresh session seeded
  * from its own record of the conversation; `cwd` says where the lookup was made.
  */
 export class NativeBindingMissingError extends Error {
   constructor(
-    readonly runtime: 'claude-code' | 'codex-app-server',
+    readonly runtime: 'claude-code' | 'codex-app-server' | 'muse',
     readonly binding: string,
     message: string,
     readonly cwd?: string,
@@ -122,7 +123,8 @@ export type SessionEventKind =
   | 'rate_limit'
   | 'result'
   | 'error'
-  | 'subagent';
+  | 'subagent'
+  | 'task';
 
 /**
  * A subagent's lifecycle as the native runtime reports it (kind `subagent`). Claude Code: its
@@ -154,6 +156,26 @@ export interface SubagentLifecycle {
   };
 }
 
+/**
+ * A background task that is not a subagent (kind `task`): Claude Code's `system` task frames for a
+ * background shell (`local_bash`), a monitor or a workflow. Like a subagent it can outlive the turn
+ * that started it, so its events belong to no admission (`unattributedReason: "task"`).
+ */
+export interface TaskLifecycle {
+  readonly phase: 'started' | 'progress' | 'updated' | 'ended';
+  /** The native task id (the id the agent's own task tools name). */
+  readonly taskId: string;
+  /** The runtime's task type, e.g. `local_bash`. */
+  readonly taskType: string;
+  /** The tool call that started it, in the session's stream (its command is that call's input). */
+  readonly toolUseId?: string;
+  readonly description?: string;
+  /** The native status at the end (completed, failed, stopped, killed). */
+  readonly status?: string;
+  readonly reason?: string;
+  readonly summary?: string;
+}
+
 /** Input excludes cache reads/writes when those disjoint counters are supplied.
  * Thinking is a subset of output; TTL counters are subsets of cacheWrite.
  * Missing optional counters mean the runtime did not report them.
@@ -191,7 +213,8 @@ export interface SessionEvent extends SessionIdentity {
     | 'unmatched-tool'
     | 'malformed-tool'
     | 'account-status'
-    | 'subagent';
+    | 'subagent'
+    | 'task';
   /** Local transport observation, not a native terminal acknowledgment. */
   readonly transportOutcome?: SessionAttempt['transportOutcome'];
   readonly nativeOutcome?: NativeOutcome;
@@ -243,6 +266,8 @@ export interface SessionEvent extends SessionIdentity {
   readonly parentToolUseId?: string;
   /** A subagent's lifecycle (kind `subagent`). */
   readonly subagent?: SubagentLifecycle;
+  /** A background task's lifecycle (kind `task`). */
+  readonly task?: TaskLifecycle;
 }
 
 /** Result of a single send() — the turn's content plus all classified events. */
@@ -398,6 +423,11 @@ export interface HarnessSession {
   interruptNative?(opts?: { timeoutMs?: number }): Promise<NativeInterruptOutcome>;
   /** Poll account usage limits without a model turn. Present where the transport declares `limits.poll`. */
   readLimits?(opts?: { timeoutMs?: number }): Promise<LimitSnapshot | undefined>;
+  /**
+   * Stop one background task (a `task` lifecycle's `taskId`) through the runtime's own control
+   * channel. Its end arrives as the task's `ended` lifecycle. Claude Code: the `stop_task` request.
+   */
+  stopTask?(taskId: string, opts?: { timeoutMs?: number }): Promise<void>;
   /** One immutable admission snapshot, without copying unrelated session history. */
   inspectAttempt?(admissionId: string): SessionAttempt | undefined;
   readonly admissionProtocol?: 'prewrite-v1';

package/src/index.ts

@@ -67,8 +67,28 @@ export {
   type LimitWindow,
   limitUtilization,
   mergeLimits,
+  museLimitSnapshot,
 } from './limits';
 export { type LimitProbeOptions, probeClaudeLimits, probeCodexLimits } from './limits-probe';
+// Muse Code adapter: one `muse serve` host per session through Meta's @muse-code/sdk.
+export {
+  MUSE_SDK_VERSION,
+  type MuseApprovalMode,
+  type MuseConnect,
+  type MuseHost,
+  type MuseInitializeResult,
+  type MuseLaunch,
+  type MusePermissionProfile,
+  type MusePermissions,
+  type MuseReasoningEffort,
+  MuseSession,
+  type MuseSessionConfig,
+  type MuseUserInputAnswer,
+  type MuseUserInputHandler,
+  type MuseUserInputQuestion,
+  type MuseUserInputRequest,
+  musePermissions,
+} from './muse-session';
 export {
   ContinuityError,
   type ContinuityRefusal,

package/src/limits.ts

@@ -1,10 +1,10 @@
 // Subscription usage limits, normalized across runtimes. Account identity
 // (email, account/organization IDs) is never read into a snapshot.
 
-export type LimitRuntime = 'claude' | 'codex';
+export type LimitRuntime = 'claude' | 'codex' | 'muse';
 
 export interface LimitWindow {
-  /** Stable per runtime: Claude `five_hour`/`seven_day`/…, Codex `primary`/`secondary`. */
+  /** Stable per runtime: Claude `five_hour`/`seven_day`/…, Codex `primary`/`secondary`, Muse `window`/`weekly`. */
   readonly id: string;
   /** 0–100. */
   readonly usedPercent: number;
@@ -104,6 +104,42 @@ export function codexLimitSnapshot(
   };
 }
 
+/**
+ * Muse `usage/read` result (`{ usage }`) or `usage/changed` params (the usage itself): the plan's
+ * rolling `window` (five hours) and `weekly` windows, in percent used. Meta reports the windows from
+ * its latest model response, so a host that has not served a turn yet reports none. `tier` is not read:
+ * on the wire it is a numeric id (the CLI shows the plan's name), not a label known to be account-free.
+ */
+export function museLimitSnapshot(
+  value: unknown,
+  source: LimitSnapshot['source'],
+  observedAt = Date.now(),
+): LimitSnapshot | undefined {
+  const outer = object(value);
+  const usage = object(outer?.usage) ?? outer;
+  const rolling = object(usage?.window),
+    weekly = object(usage?.weekly);
+  const ms = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : undefined);
+  const windows = [
+    ...window(
+      'window',
+      percent(rolling?.usedPercent),
+      ms(rolling?.resetsAtMs),
+      typeof rolling?.windowDurationMins === 'number' ? rolling.windowDurationMins : undefined,
+    ),
+    ...window('weekly', percent(weekly?.usedPercent), ms(weekly?.resetsAtMs), 10_080),
+  ];
+  if (!windows.length) return undefined;
+  return {
+    runtime: 'muse',
+    source,
+    observedAt: ms(usage?.observedAtMs) ?? observedAt,
+    windows,
+    // Explicit both ways, so a later report clears a block an earlier one (or a quota stop) set.
+    blocked: windows.some((w) => w.usedPercent >= 100),
+  };
+}
+
 /** Claude CLI stream-json `rate_limit_event.rate_limit_info`. Utilization is a 0–1 fraction. */
 export function claudeRateLimitSnapshot(
   info: unknown,