@moxxy/core 0.4.0 → 0.5.1

package/src/subagents/run-child.test.ts

@@ -1,8 +1,14 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { ModeContext, ModeDef, MoxxyEvent, ProviderDef } from '@moxxy/sdk';
 import { defineMode, defineProvider, definePlugin } from '@moxxy/sdk';
 import { Session } from '../session.js';
-import { runChildTurn, type SubagentRuntime } from './run-child.js';
+import {
+  continueChildTurn,
+  createSubagentSpawner,
+  runChildTurn,
+  type SubagentRuntime,
+} from './run-child.js';
+import { clearRetainedChildren } from './registry.js';
 
 // A mode that reports the model it was handed — lets tests observe the
 // child's EFFECTIVE model through the returned result text.
@@ -183,3 +189,120 @@ describe('runChildTurn model resolution', () => {
     expect(result.text).toBe('cheap-model');
   });
 });
+
+// A mode that runs instantly on its FIRST invocation but blocks on an external
+// gate on every later turn — lets a test hold a continue() turn mid-flight while
+// a second continue() races it (without hanging the initial spawn).
+function makeGatedMode(gate: Promise<void>): ModeDef {
+  let calls = 0;
+  return defineMode({
+    name: 'gated',
+    run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+      calls += 1;
+      if (calls > 1) await gate;
+      await ctx.emit({
+        type: 'assistant_message',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'assistant',
+        content: 'done',
+        stopReason: 'end_turn',
+      });
+    },
+  });
+}
+
+describe('spawnAll per-child degradation', () => {
+  it('isolates one child setup throw — siblings still resolve, batch never rejects', async () => {
+    const session = buildSession(['parent-model']);
+    const rt = buildRuntime(session, 'parent-model');
+    const spawner = createSubagentSpawner(rt);
+
+    // Force a PRE-`try` setup throw for exactly the SECOND child: buildChildContext
+    // calls appContext() for every child, so throw on its second invocation. With
+    // Promise.all this would reject the whole batch and orphan the first (still
+    // running) child's promise → an unhandledRejection; with allSettled it must
+    // degrade to one error-bearing result while the sibling succeeds.
+    const realAppContext = session.appContext.bind(session);
+    let appCtxCalls = 0;
+    vi.spyOn(session, 'appContext').mockImplementation(() => {
+      appCtxCalls += 1;
+      if (appCtxCalls === 2) throw new Error('boom: provider config gone');
+      return realAppContext();
+    });
+
+    const results = await spawner.spawnAll([
+      { prompt: 'echo', mode: 'echo-model', label: 'good' },
+      { prompt: 'echo', mode: 'echo-model', label: 'doomed' },
+    ]);
+
+    // The batch resolves (never rejects) with one result PER spec, in input order.
+    expect(results).toHaveLength(2);
+    expect(results.map((r) => r.label)).toEqual(['good', 'doomed']);
+    // Exactly one child degraded to an error-bearing result; the sibling succeeded.
+    const errored = results.filter((r) => r.stopReason === 'error');
+    const ok = results.filter((r) => r.stopReason === 'end_turn');
+    expect(errored).toHaveLength(1);
+    expect(ok).toHaveLength(1);
+    expect(errored[0]!.error?.message).toContain('boom');
+    expect(ok[0]!.text).toBe('parent-model');
+    vi.restoreAllMocks();
+  });
+
+  it('returns one result per spec in input order on the all-success path', async () => {
+    const session = buildSession(['parent-model']);
+    const rt = buildRuntime(session, 'parent-model');
+    const spawner = createSubagentSpawner(rt);
+
+    const results = await spawner.spawnAll([
+      { prompt: 'a', mode: 'echo-model', label: 'one' },
+      { prompt: 'b', mode: 'echo-model', label: 'two' },
+      { prompt: 'c', mode: 'echo-model', label: 'three' },
+    ]);
+
+    expect(results.map((r) => r.label)).toEqual(['one', 'two', 'three']);
+    expect(results.every((r) => r.stopReason === 'end_turn')).toBe(true);
+  });
+});
+
+describe('continueChildTurn re-entrancy', () => {
+  it('rejects a concurrent continue() for the same retained child (claim-then-run)', async () => {
+    let openGate!: () => void;
+    const gate = new Promise<void>((resolve) => {
+      openGate = resolve;
+    });
+    const session = new Session({ cwd: '/tmp', silent: true });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'gated-test',
+        version: '0.0.0',
+        providers: [makeProvider(['m'])],
+        modes: [makeGatedMode(gate)],
+      }),
+    );
+    session.providers.setActive('listed');
+    session.modes.setActive('gated');
+
+    const rt = buildRuntime(session, 'm');
+    const first = await runChildTurn({
+      rt,
+      spec: { prompt: 'go', mode: 'gated', retainSession: true },
+      retainSession: true,
+    });
+    const childId = first.childSessionId;
+
+    // Start the first continue (blocks inside the gated mode), then race a
+    // second continue for the same id before the first settles.
+    const p1 = continueChildTurn({ childSessionId: childId, prompt: 'again' });
+    // The entry is claimed synchronously, so the second continue must fail fast.
+    await expect(
+      continueChildTurn({ childSessionId: childId, prompt: 'race' }),
+    ).rejects.toThrow(/no retained subagent session/);
+
+    openGate();
+    const r1 = await p1;
+    expect(r1.text).toBe('done');
+
+    clearRetainedChildren(session.id);
+  });
+});

package/src/subagents/run-child.ts

@@ -46,9 +46,10 @@ import {
 } from './events.js';
 import { buildFilteredToolRegistry } from './tools.js';
 import {
-  getRetainedChild,
+  claimRetainedChild,
   registerRetainedChild,
   releaseRetainedChild,
+  unclaimRetainedChild,
   type RetainedChildSession,
 } from './registry.js';
 
@@ -86,10 +87,13 @@ export async function runChildTurn(args: {
   if ('failure' in resolved) return resolved.failure;
   const { strategy, strategyName } = resolved;
 
+  // `undefined` means "inherit the full parent registry"; a present-but-empty
+  // array means "deny all" (least-privilege). Collapsing the two would turn an
+  // explicit [] into full tool inheritance — the opposite of the caller's intent.
   const toolRegistry: ToolRegistry =
-    spec.allowedTools && spec.allowedTools.length > 0
-      ? buildFilteredToolRegistry(parentSession.tools, new Set(spec.allowedTools))
-      : parentSession.tools;
+    spec.allowedTools === undefined
+      ? parentSession.tools
+      : buildFilteredToolRegistry(parentSession.tools, new Set(spec.allowedTools));
 
   const childModel = await resolveChildModel(rt, spec, label, childSessionId);
 
@@ -122,7 +126,7 @@ export async function runChildTurn(args: {
   });
 
   if (retainSession) {
-    registerRetainedChild({
+    const evicted = registerRetainedChild({
       label,
       childSessionId,
       childTurnId,
@@ -133,53 +137,98 @@ export async function runChildTurn(args: {
       strategyName,
       parentSession,
       parentTurnId,
+      tokensUsed: capture.tokensUsed,
     });
+    // A capped/TTL-expired paused child is now unreachable: its `continue()`
+    // will fail. Surface that on the EVICTED child's own parent log (best-effort
+    // — a warning append must never take this spawn down) so the operator who
+    // started it isn't left waiting on a resume that can no longer happen.
+    await warnEvicted(evicted);
   }
 
   return capture.result;
 }
 
+/**
+ * Emit a `subagent_warning` on each evicted child's OWN parent log so the
+ * operator who spawned a now-unreachable paused child sees why its `continue()`
+ * will fail. Best-effort: a warning-append reject (or a since-closed parent
+ * session) must never propagate out of the spawn that triggered the eviction.
+ */
+async function warnEvicted(evicted: ReadonlyArray<RetainedChildSession>): Promise<void> {
+  for (const e of evicted) {
+    try {
+      await emitSubagentWarning(
+        e.parentSession,
+        e.parentTurnId,
+        e.label,
+        e.childSessionId,
+        `retained subagent "${e.label}" was evicted before resume ` +
+          `(retention cap or TTL reached); its continue() will no longer work`,
+      );
+    } catch {
+      // A closed/failing parent log must not abort the spawn that evicted it.
+    }
+  }
+}
+
 export async function continueChildTurn(args: {
   childSessionId: SessionId;
   prompt: string;
   label?: string;
 }): Promise<SubagentResult> {
-  const retained = getRetainedChild(args.childSessionId);
+  // Claim-then-run: atomically remove the entry from the registry and mark it
+  // busy so a racing continue()/release() for the same id can't observe the
+  // live entry and drive strategy.run over the same childLog/childCtx in
+  // parallel (interleaved appends, double-seeded prompts, double release).
+  const retained = claimRetainedChild(args.childSessionId);
   if (!retained) {
     throw new Error(`no retained subagent session for "${String(args.childSessionId)}"`);
   }
 
-  await retained.childLog.append({
-    type: 'user_prompt',
-    sessionId: retained.childSessionId,
-    turnId: retained.childTurnId,
-    source: 'user',
-    text: args.prompt,
-  });
+  try {
+    await retained.childLog.append({
+      type: 'user_prompt',
+      sessionId: retained.childSessionId,
+      turnId: retained.childTurnId,
+      source: 'user',
+      text: args.prompt,
+    });
 
-  const rt: SubagentRuntime = {
-    parentSession: retained.parentSession,
-    parentTurnId: retained.parentTurnId,
-    parentSignal: retained.childCtx.signal,
-    parentModel: retained.childCtx.model,
-  };
+    const rt: SubagentRuntime = {
+      parentSession: retained.parentSession,
+      parentTurnId: retained.parentTurnId,
+      // Re-derive the resume signal from the still-live owning session rather
+      // than reusing the possibly-already-aborted per-turn signal captured at
+      // first-turn spawn time (which would cancel the resume before any work).
+      parentSignal: retained.parentSession.signal,
+      parentModel: retained.childCtx.model,
+    };
 
-  const capture = await executeChildLoop({
-    rt,
-    spec: retained.spec,
-    label: args.label ?? retained.label,
-    childSessionId: retained.childSessionId,
-    childTurnId: retained.childTurnId,
-    childLog: retained.childLog,
-    childCtx: retained.childCtx,
-    strategy: retained.strategy,
-    strategyName: retained.strategyName,
-    emitCompleted: true,
-    skipStartEvent: true,
-  });
+    const capture = await executeChildLoop({
+      rt,
+      spec: retained.spec,
+      label: args.label ?? retained.label,
+      childSessionId: retained.childSessionId,
+      childTurnId: retained.childTurnId,
+      childLog: retained.childLog,
+      childCtx: retained.childCtx,
+      strategy: retained.strategy,
+      strategyName: retained.strategyName,
+      emitCompleted: true,
+      skipStartEvent: true,
+      // Carry forward the cost accumulated across prior turns so the deferred
+      // subagent_completed reports the retained session's cumulative usage, not
+      // just this last continue's delta.
+      priorTokensUsed: retained.tokensUsed ?? 0,
+    });
 
-  releaseRetainedChild(args.childSessionId);
-  return capture.result;
+    return capture.result;
+  } finally {
+    // The entry was already removed by the claim; just drop the busy marker so
+    // a future continue() (if the session were re-registered) isn't blocked.
+    unclaimRetainedChild(args.childSessionId);
+  }
 }
 
 async function executeChildLoop(args: {
@@ -194,7 +243,8 @@ async function executeChildLoop(args: {
   strategyName: string;
   emitCompleted: boolean;
   skipStartEvent?: boolean;
-}): Promise<{ result: SubagentResult }> {
+  priorTokensUsed?: number;
+}): Promise<{ result: SubagentResult; tokensUsed: number }> {
   const {
     rt,
     spec,
@@ -207,6 +257,7 @@ async function executeChildLoop(args: {
     strategyName,
     emitCompleted,
     skipStartEvent,
+    priorTokensUsed = 0,
   } = args;
   const { parentSession, parentTurnId } = rt;
 
@@ -214,7 +265,7 @@ async function executeChildLoop(args: {
     text: '',
     stopReason: 'end_turn' as StopReason,
     error: null as string | null,
-    tokensUsed: 0,
+    tokensUsed: priorTokensUsed,
   };
 
   const unsubCapture = childLog.subscribe((e) => {
@@ -280,7 +331,7 @@ async function executeChildLoop(args: {
     );
   }
 
-  return { result };
+  return { result, tokensUsed: capture.tokensUsed };
 }
 
 async function resolveStrategy(
@@ -296,23 +347,26 @@ async function resolveStrategy(
   const exact = parentSession.modes.list().find((s) => s.name === requestedStrategy);
   if (exact) return { strategy: exact, strategyName: requestedStrategy };
 
-  // Fall back to the default mode if the model invented a name
-  // (e.g. "react"). Failing the child outright wastes the user's turn —
-  // any reasonable agent task can run on the default mode. We surface the
-  // fallback as a non-fatal warning event so the operator sees it.
-  const fallback = parentSession.modes.list().find((s) => s.name === 'default');
+  // Fall back when the model invented a name (e.g. "react"). Failing the child
+  // outright wastes the user's turn — any reasonable agent task can run on the
+  // session's current strategy. Prefer a mode literally named "default", then
+  // the session's active mode (a host may ship a renamed/alternative default),
+  // surfacing the fallback as a non-fatal warning so the operator sees it.
+  const fallback =
+    parentSession.modes.list().find((s) => s.name === 'default') ??
+    safeActiveMode(parentSession);
   if (fallback) {
     await emitSubagentWarning(
       parentSession,
       parentTurnId,
       label,
       childSessionId,
-      `unknown mode "${requestedStrategy}" — falling back to "default"`,
+      `unknown mode "${requestedStrategy}" — falling back to "${fallback.name}"`,
     );
-    return { strategy: fallback, strategyName: 'default' };
+    return { strategy: fallback, strategyName: fallback.name };
   }
 
-  // No default mode either — that's a config error, not a model mistake.
+  // No fallback mode at all — that's a config error, not a model mistake.
   await emitSubagentStart(parentSession, parentTurnId, label, childSessionId, spec, requestedStrategy);
   const errorMsg = `Subagent failed: unknown mode "${requestedStrategy}" and no fallback available`;
   await emitSubagentCompleted(parentSession, parentTurnId, label, childSessionId, '', 'error', errorMsg, spec.agentType ?? 'default', 0);
@@ -327,6 +381,17 @@ async function resolveStrategy(
   };
 }
 
+/** `modes.getActive()` throws when no mode is active; treat that as "no fallback". */
+function safeActiveMode(
+  parentSession: SessionRuntime,
+): ReturnType<SessionRuntime['modes']['list']>[number] | undefined {
+  try {
+    return parentSession.modes.getActive();
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Resolve the child's effective model. A `spec.model` usually comes from the
  * calling LLM (dispatch_agent's free-form string field), which sometimes
@@ -405,15 +470,53 @@ function buildChildContext(
   };
 }
 
+/**
+ * Build an error-bearing {@link SubagentResult} for a spec whose `runChildTurn`
+ * threw during setup (before it could degrade the error into a result itself).
+ * Keeps `spawnAll` total: one result per spec, in input order, never a thrown
+ * batch. The real child id is unknown here (setup failed before it was captured),
+ * so a fresh placeholder id is minted; the result still carries the failing
+ * spec's label and the error message.
+ */
+function spawnFailureResult(spec: SubagentSpec, reason: unknown): SubagentResult {
+  const message = reason instanceof Error ? reason.message : String(reason);
+  return {
+    label: spec.label ?? 'subagent',
+    childSessionId: newSessionId(),
+    text: '',
+    stopReason: 'error' as StopReason,
+    error: { message },
+  };
+}
+
 export function createSubagentSpawner(rt: SubagentRuntime): SubagentSpawner {
   return {
     async spawn(spec) {
       return runChildTurn({ rt, spec, retainSession: spec.retainSession === true });
     },
     async spawnAll(specs) {
-      return Promise.all(
-        specs.map((s) => runChildTurn({ rt, spec: s, retainSession: s.retainSession === true })),
+      // Per-child degradation: a single child's PRE-`try` setup throw (no active
+      // provider, a `compactors.getActive()` config error, a log-append reject in
+      // `resolveStrategy`) must NOT reject the whole batch. `Promise.all` would do
+      // exactly that, and worse — it would orphan the still-running sibling
+      // promises, whose later settlement surfaces as an `unhandledRejection`.
+      // Convert every spec into one result in input order; a setup throw becomes
+      // an error-bearing `SubagentResult` so a fan-out partially succeeds instead
+      // of taking the parent turn down with it.
+      const settled = await Promise.all(
+        specs.map(async (spec): Promise<SubagentResult> => {
+          try {
+            return await runChildTurn({ rt, spec, retainSession: spec.retainSession === true });
+          } catch (err) {
+            // A PRE-`try` setup throw inside runChildTurn (no active provider, a
+            // failing getActive(), a log-append reject in resolveStrategy) is
+            // caught HERE per-child so it can't reject the batch or orphan a
+            // sibling. The outer Promise.all is now safe: every element resolves.
+            return spawnFailureResult(spec, err);
+          }
+        }),
       );
+      return settled;
     },
     async continue(args: SubagentContinueArgs) {
       return continueChildTurn(args);

package/src/surfaces/host.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
 import {
   defineSurface,
   type SurfaceDataMessage,
@@ -93,6 +93,76 @@ describe('SurfaceHostImpl viewer ref-counting', () => {
   });
 });
 
+describe('SurfaceHostImpl shutdown leak/hang hardening', () => {
+  it('closeAll closes an open() that resolves AFTER teardown (no leaked instance)', async () => {
+    // The open()'s def.open promise resolves only after closeAll has run; the
+    // freshly-created instance must be torn down, not installed as an orphan.
+    let resolveOpen!: () => void;
+    const gate = new Promise<void>((r) => {
+      resolveOpen = r;
+    });
+    const state = { closed: 0, instances: [] as SurfaceInstance[] };
+    const def = defineSurface({
+      kind: 'terminal',
+      open: async () => {
+        await gate;
+        const instance: SurfaceInstance = {
+          id: 'terminal',
+          kind: 'terminal',
+          onData: () => () => {},
+          input: () => {},
+          close: () => {
+            state.closed += 1;
+          },
+        };
+        state.instances.push(instance);
+        return instance;
+      },
+    });
+    const host = makeHost(def);
+
+    const openPromise = host.open('terminal'); // in-flight, parked on the gate
+    const closeAll = host.closeAll(); // sets disposed; awaits the in-flight open
+    resolveOpen(); // open resolves only now, after teardown began
+    await expect(openPromise).rejects.toThrow(/has been closed/);
+    await closeAll;
+
+    // The instance was created — and immediately closed, never installed.
+    expect(state.instances).toHaveLength(1);
+    expect(state.closed).toBe(1);
+    // A stray open() after shutdown is rejected before creating anything.
+    await expect(host.open('terminal')).rejects.toThrow(/has been closed/);
+  });
+
+  it('a wedged instance.close() does not hang closeAll forever', async () => {
+    vi.useFakeTimers();
+    try {
+      const state = { closed: 0 };
+      const def = defineSurface({
+        kind: 'terminal',
+        open: () => ({
+          id: 'terminal',
+          kind: 'terminal',
+          onData: () => () => {},
+          input: () => {},
+          // Never resolves: a wedged PTY/browser teardown.
+          close: () => new Promise<void>(() => {}),
+        }),
+      });
+      const host = makeHost(def);
+      await host.open('terminal');
+
+      const done = host.closeAll();
+      // Without the timeout this would never settle; advance past it.
+      await vi.advanceTimersByTimeAsync(6000);
+      await expect(done).resolves.toBeUndefined();
+      expect(state.closed).toBe(0); // close() never resolved, but we moved on
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
 /**
  * A controllable surface whose instance lets the test PUSH frames (`emit`),
  * record resize calls, and run unsubscribe on close — enough to assert the

package/src/surfaces/host.ts

@@ -25,6 +25,8 @@ import type { SurfaceRegistryImpl } from '../registries/surfaces.js';
  * existing resource and gets its {@link SurfaceInstance.snapshot}.
  */
 export class SurfaceHostImpl implements SurfaceHost {
+  /** Upper bound on a single instance.close() before we give up waiting on it. */
+  private static readonly CLOSE_TIMEOUT_MS = 5000;
   /** Open instances, keyed by kind (one shared instance per kind). */
   private readonly instances = new Map<SurfaceKind, SurfaceInstance>();
   /** Per-instance unsubscribe from its onData, dropped on close. */
@@ -44,6 +46,8 @@ export class SurfaceHostImpl implements SurfaceHost {
    * snapshot, but keystrokes/navigation silently vanish).
    */
   private readonly refs = new Map<SurfaceKind, number>();
+  /** Set once closeAll() runs: rejects/ tears down any open() that races teardown. */
+  private disposed = false;
 
   constructor(
     private readonly registry: SurfaceRegistryImpl,
@@ -77,6 +81,7 @@ export class SurfaceHostImpl implements SurfaceHost {
   }
 
   async open(kind: SurfaceKind): Promise<OpenSurfaceResult> {
+    if (this.disposed) throw new Error('SurfaceHost has been closed');
     const existing = this.instances.get(kind);
     if (existing) {
       this.retain(kind);
@@ -95,6 +100,12 @@ export class SurfaceHostImpl implements SurfaceHost {
 
     const promise = (async (): Promise<OpenSurfaceResult> => {
       const instance = await def.open(this.ctx);
+      // If teardown raced this create, never install the live resource — close
+      // it immediately so we don't leak a PTY/page/child process post-shutdown.
+      if (this.disposed) {
+        await this.safeClose(instance);
+        throw new Error('SurfaceHost has been closed');
+      }
       this.instances.set(kind, instance);
       this.refs.set(kind, 1);
       // Re-emit this instance's frames as multiplexed SurfaceDataMessages.
@@ -138,13 +149,33 @@ export class SurfaceHostImpl implements SurfaceHost {
     this.unsubs.get(surfaceId)?.();
     this.unsubs.delete(surfaceId);
     this.instances.delete(kind);
+    await this.safeClose(instance, surfaceId);
+  }
+
+  /**
+   * Tear an instance down without ever blocking forever: a wedged PTY/browser
+   * whose close() neither resolves nor rejects must not stall session shutdown.
+   * Races close() against a timeout and swallows (logs) any rejection.
+   */
+  private async safeClose(instance: SurfaceInstance, surfaceId = instance.id): Promise<void> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
     try {
-      await instance.close();
+      await Promise.race([
+        Promise.resolve(instance.close()),
+        new Promise<void>((resolve) => {
+          timer = setTimeout(() => {
+            this.logger?.warn?.('SurfaceHost: close timed out', { surfaceId });
+            resolve();
+          }, SurfaceHostImpl.CLOSE_TIMEOUT_MS);
+        }),
+      ]);
     } catch (err) {
       this.logger?.warn?.('SurfaceHost: close failed', {
         surfaceId,
         err: err instanceof Error ? err.message : String(err),
       });
+    } finally {
+      if (timer) clearTimeout(timer);
     }
   }
 
@@ -168,9 +199,15 @@ export class SurfaceHostImpl implements SurfaceHost {
 
   async closeAll(): Promise<void> {
     // Session shutdown: tear every instance down regardless of viewer refs.
+    this.disposed = true;
+    // Drain in-flight opens first. With `disposed` set, each racing open closes
+    // its freshly-created instance itself and rejects, so nothing new lands in
+    // `instances` after this await — no leaked PTY/page/child process.
+    await Promise.allSettled([...this.opening.values()]);
     for (const kind of [...this.instances.keys()]) this.refs.set(kind, 1);
+    // Run closes concurrently so one wedged instance can't block the others.
     const ids = [...this.unsubs.keys()];
-    for (const id of ids) await this.close(id);
+    await Promise.allSettled(ids.map((id) => this.close(id)));
   }
 
   private byId(surfaceId: string): SurfaceInstance | undefined {