@moxxy/core 0.3.0

package/src/subagents/events.ts

@@ -0,0 +1,194 @@
+/**
+ * Subagent <-> parent log bridge. Wraps child `MoxxyEvent`s into
+ * `plugin_event` envelopes on the parent log so the TUI / exporters can
+ * render live progress, and emits the start/completed bookend envelopes.
+ */
+
+import type {
+  MoxxyEvent,
+  SessionId,
+  StopReason,
+  SubagentSpec,
+  TurnId,
+} from '@moxxy/sdk';
+import { asPluginId } from '@moxxy/sdk';
+import type { SessionRuntime } from '../session-runtime.js';
+
+export const SUBAGENT_PLUGIN_ID = asPluginId('@moxxy/subagents');
+
+export async function emitSubagentStart(
+  parentSession: SessionRuntime,
+  parentTurnId: TurnId,
+  label: string,
+  childSessionId: SessionId,
+  spec: SubagentSpec,
+  mode: string,
+): Promise<void> {
+  await parentSession.log.append({
+    type: 'plugin_event',
+    sessionId: parentSession.id,
+    turnId: parentTurnId,
+    source: 'plugin',
+    pluginId: SUBAGENT_PLUGIN_ID,
+    subtype: 'subagent_started',
+    payload: {
+      label,
+      childSessionId: String(childSessionId),
+      prompt: spec.prompt,
+      mode,
+      agentType: spec.agentType ?? 'default',
+      ...(spec.model ? { model: spec.model } : {}),
+    },
+  });
+}
+
+export async function emitSubagentCompleted(
+  parentSession: SessionRuntime,
+  parentTurnId: TurnId,
+  label: string,
+  childSessionId: SessionId,
+  text: string,
+  stopReason: StopReason,
+  errorMessage: string | null,
+  agentType: string,
+  tokensUsed: number,
+): Promise<void> {
+  await parentSession.log.append({
+    type: 'plugin_event',
+    sessionId: parentSession.id,
+    turnId: parentTurnId,
+    source: 'plugin',
+    pluginId: SUBAGENT_PLUGIN_ID,
+    subtype: 'subagent_completed',
+    payload: {
+      label,
+      childSessionId: String(childSessionId),
+      text,
+      stopReason,
+      agentType,
+      tokensUsed,
+      ...(errorMessage ? { error: errorMessage } : {}),
+    },
+  });
+}
+
+export async function emitSubagentWarning(
+  parentSession: SessionRuntime,
+  parentTurnId: TurnId,
+  label: string,
+  childSessionId: SessionId,
+  message: string,
+): Promise<void> {
+  await parentSession.log.append({
+    type: 'plugin_event',
+    sessionId: parentSession.id,
+    turnId: parentTurnId,
+    source: 'plugin',
+    pluginId: SUBAGENT_PLUGIN_ID,
+    subtype: 'subagent_warning',
+    payload: {
+      label,
+      childSessionId: String(childSessionId),
+      message,
+    },
+  });
+}
+
+/**
+ * Map each interesting child event to a parent `plugin_event` so the TUI
+ * can render the subagent's progress in real time. Noisy / book-keeping
+ * events (mode_iteration, provider_request, provider_response,
+ * assistant_message — covered by the explicit `subagent_completed`) are
+ * filtered out to keep the parent log lean.
+ */
+export async function streamChildEventToParent(
+  parentSession: SessionRuntime,
+  parentTurnId: TurnId,
+  label: string,
+  childSessionId: SessionId,
+  childEvt: MoxxyEvent,
+): Promise<void> {
+  const mapped = mapChildEvent(label, childSessionId, childEvt);
+  if (!mapped) return;
+  try {
+    await parentSession.log.append({
+      type: 'plugin_event',
+      sessionId: parentSession.id,
+      turnId: parentTurnId,
+      source: 'plugin',
+      pluginId: SUBAGENT_PLUGIN_ID,
+      subtype: mapped.subtype,
+      payload: mapped.payload,
+    });
+  } catch (err) {
+    // Forwarding a child progress event is best-effort: a parent-log append
+    // failure must not abort the subagent run. EventLog.append already swallows
+    // listener errors, so this rejection would otherwise vanish with zero
+    // trace (the surface just stops updating); surface it so a chronic
+    // forwarding failure during a long subagent run is at least diagnosable.
+    process.stderr.write(
+      `moxxy: dropped subagent progress event (${mapped.subtype}) — parent log append failed: ` +
+        `${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+}
+
+function mapChildEvent(
+  label: string,
+  childSessionId: SessionId,
+  childEvt: MoxxyEvent,
+): { subtype: string; payload: Record<string, unknown> } | null {
+  const payload: Record<string, unknown> = {
+    label,
+    childSessionId: String(childSessionId),
+  };
+  switch (childEvt.type) {
+    case 'assistant_chunk':
+      payload.delta = childEvt.delta;
+      return { subtype: 'subagent_chunk', payload };
+    case 'tool_call_requested':
+      payload.name = childEvt.name;
+      payload.input = childEvt.input;
+      payload.callId = String(childEvt.callId);
+      return { subtype: 'subagent_tool_call', payload };
+    case 'tool_result':
+      payload.callId = String(childEvt.callId);
+      payload.ok = childEvt.ok;
+      if (childEvt.ok) payload.output = childEvt.output;
+      else payload.error = childEvt.error;
+      return { subtype: 'subagent_tool_result', payload };
+    case 'error':
+      payload.kind = childEvt.kind;
+      payload.message = childEvt.message;
+      return { subtype: 'subagent_error', payload };
+    case 'abort':
+      payload.reason = childEvt.reason;
+      return { subtype: 'subagent_abort', payload };
+    case 'plugin_event':
+      return mapNestedPluginEvent(label, payload, childEvt);
+    default:
+      return null;
+  }
+}
+
+function mapNestedPluginEvent(
+  label: string,
+  payload: Record<string, unknown>,
+  childEvt: Extract<MoxxyEvent, { type: 'plugin_event' }>,
+): { subtype: string; payload: Record<string, unknown> } | null {
+  // Bubble nested subagent events too, so a grand-child's progress
+  // surfaces all the way up. We strip the nested label-prefix to
+  // keep things compact; payload retains the chain via the embedded
+  // childSessionId.
+  const nestedSubtype = childEvt.subtype;
+  if (typeof nestedSubtype !== 'string' || !nestedSubtype.startsWith('subagent_')) return null;
+  const nestedPayload = childEvt.payload;
+  if (nestedPayload && typeof nestedPayload === 'object') {
+    for (const [k, v] of Object.entries(nestedPayload as Record<string, unknown>)) {
+      if (k !== 'label' && k !== 'childSessionId') payload[k] = v;
+    }
+    // Preserve the chain via a `via` field naming the immediate parent label.
+    payload.via = label;
+  }
+  return { subtype: nestedSubtype, payload };
+}

package/src/subagents/registry.ts

@@ -0,0 +1,62 @@
+/**
+ * Retained-child session registry — backs the `awaitInput` pause/resume flow.
+ *
+ * A subagent spawned with `retainSession: true` keeps its `EventLog` and
+ * `ModeContext` alive after its first turn so a later `continue()` can append
+ * an operator reply and run it again. The registry is a process-local map
+ * keyed by child session id; entries are dropped on `continue` or `release`.
+ *
+ * Each entry records its `parentSession`, so {@link clearRetainedChildren}
+ * drops only the children belonging to the session that is closing. The map is
+ * process-wide (one per module), but a `Session.close()` must NOT wipe another
+ * live session's paused children — that would break their `continue()` in any
+ * host that runs >1 Session per process (the desktop in-process path, tests).
+ */
+
+import type { ModeContext, SessionId, SubagentSpec, TurnId } from '@moxxy/sdk';
+import type { EventLog } from '../events/log.js';
+import type { SessionRuntime } from '../session-runtime.js';
+
+export interface RetainedChildSession {
+  readonly label: string;
+  readonly childSessionId: SessionId;
+  readonly childTurnId: TurnId;
+  readonly childLog: EventLog;
+  readonly childCtx: ModeContext;
+  readonly spec: SubagentSpec;
+  readonly strategy: ReturnType<SessionRuntime['modes']['list']>[number];
+  readonly strategyName: string;
+  readonly parentSession: SessionRuntime;
+  readonly parentTurnId: TurnId;
+}
+
+const retained = new Map<string, RetainedChildSession>();
+
+export function registerRetainedChild(session: RetainedChildSession): void {
+  retained.set(String(session.childSessionId), session);
+}
+
+export function getRetainedChild(childSessionId: SessionId): RetainedChildSession | undefined {
+  return retained.get(String(childSessionId));
+}
+
+export function releaseRetainedChild(childSessionId: SessionId): void {
+  retained.delete(String(childSessionId));
+}
+
+/**
+ * Drop retained children. With a `parentSessionId`, drop ONLY the children
+ * whose `parentSession` is that session — so one session's `close()` can't wipe
+ * another live session's paused `awaitInput` children. Without an id (legacy /
+ * test-teardown callers), clear everything.
+ */
+export function clearRetainedChildren(parentSessionId?: SessionId): void {
+  if (parentSessionId === undefined) {
+    retained.clear();
+    return;
+  }
+  const target = String(parentSessionId);
+  for (const [childId, entry] of retained) {
+    if (String(entry.parentSession.id) === target) retained.delete(childId);
+  }
+}

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

@@ -0,0 +1,185 @@
+import { describe, expect, it } 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';
+
+// A mode that reports the model it was handed — lets tests observe the
+// child's EFFECTIVE model through the returned result text.
+function makeEchoModelMode(): ModeDef {
+  return defineMode({
+    name: 'echo-model',
+    run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+      await ctx.emit({
+        type: 'assistant_message',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'assistant',
+        content: ctx.model,
+        stopReason: 'end_turn',
+      });
+    },
+  });
+}
+
+// A mode that spawns a grandchild (no model override) and reports what model
+// the grandchild ran on — exercises nested-spawner model inheritance.
+function makeNestedSpawnMode(): ModeDef {
+  return defineMode({
+    name: 'nested-spawn',
+    run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+      const result = await ctx.subagents!.spawn({ prompt: 'echo', mode: 'echo-model' });
+      await ctx.emit({
+        type: 'assistant_message',
+        sessionId: ctx.sessionId,
+        turnId: ctx.turnId,
+        source: 'assistant',
+        content: result.text,
+        stopReason: 'end_turn',
+      });
+    },
+  });
+}
+
+function makeProvider(modelIds: ReadonlyArray<string>): ProviderDef {
+  const models = modelIds.map((id) => ({ id }));
+  return defineProvider({
+    name: 'listed',
+    models,
+    createClient: () => ({
+      name: 'listed',
+      models,
+      stream: async function* () {
+        // unused — the test modes don't call into the provider.
+      },
+      countTokens: async () => 0,
+    }),
+  });
+}
+
+function buildSession(modelIds: ReadonlyArray<string>): Session {
+  const session = new Session({ cwd: '/tmp', silent: true });
+  session.pluginHost.registerStatic(
+    definePlugin({
+      name: 'test-subagent-models',
+      version: '0.0.0',
+      providers: [makeProvider(modelIds)],
+      modes: [makeEchoModelMode(), makeNestedSpawnMode()],
+    }),
+  );
+  session.providers.setActive('listed');
+  session.modes.setActive('echo-model');
+  return session;
+}
+
+function buildRuntime(session: Session, parentModel: string): SubagentRuntime {
+  return {
+    parentSession: session,
+    parentTurnId: session.startTurn().turnId,
+    parentSignal: new AbortController().signal,
+    parentModel,
+  };
+}
+
+function collectParentEvents(session: Session): MoxxyEvent[] {
+  const events: MoxxyEvent[] = [];
+  session.log.subscribe((e) => void events.push(e));
+  return events;
+}
+
+function findWarning(events: ReadonlyArray<MoxxyEvent>): string | undefined {
+  const evt = events.find((e) => e.type === 'plugin_event' && e.subtype === 'subagent_warning');
+  return evt?.type === 'plugin_event' ? (evt.payload as { message: string }).message : undefined;
+}
+
+describe('runChildTurn model resolution', () => {
+  it('falls back to the parent model (with a warning) on an unknown model id', async () => {
+    const session = buildSession(['parent-model', 'cheap-model']);
+    const events = collectParentEvents(session);
+    const rt = buildRuntime(session, 'parent-model');
+
+    const result = await runChildTurn({
+      rt,
+      spec: { prompt: 'echo', mode: 'echo-model', model: 'claude-3-5-sonnet' },
+      retainSession: false,
+    });
+
+    expect(result.text).toBe('parent-model');
+    expect(findWarning(events)).toBe(
+      'unknown model "claude-3-5-sonnet" — falling back to parent model "parent-model"',
+    );
+  });
+
+  it('honors a model id the active provider lists, without warning', async () => {
+    const session = buildSession(['parent-model', 'cheap-model']);
+    const events = collectParentEvents(session);
+    const rt = buildRuntime(session, 'parent-model');
+
+    const result = await runChildTurn({
+      rt,
+      spec: { prompt: 'echo', mode: 'echo-model', model: 'cheap-model' },
+      retainSession: false,
+    });
+
+    expect(result.text).toBe('cheap-model');
+    expect(findWarning(events)).toBeUndefined();
+  });
+
+  it('inherits the parent model when no override is given', async () => {
+    const session = buildSession(['parent-model']);
+    const rt = buildRuntime(session, 'parent-model');
+
+    const result = await runChildTurn({
+      rt,
+      spec: { prompt: 'echo', mode: 'echo-model' },
+      retainSession: false,
+    });
+
+    expect(result.text).toBe('parent-model');
+  });
+
+  it('skips validation when the provider publishes no models (sparse providers)', async () => {
+    const session = buildSession([]);
+    const events = collectParentEvents(session);
+    const rt = buildRuntime(session, 'parent-model');
+
+    const result = await runChildTurn({
+      rt,
+      spec: { prompt: 'echo', mode: 'echo-model', model: 'unlisted-but-real' },
+      retainSession: false,
+    });
+
+    expect(result.text).toBe('unlisted-but-real');
+    expect(findWarning(events)).toBeUndefined();
+  });
+
+  it('does not warn when the override IS the parent model, even if unlisted', async () => {
+    const session = buildSession(['some-other-model']);
+    const events = collectParentEvents(session);
+    const rt = buildRuntime(session, 'unlisted-parent');
+
+    const result = await runChildTurn({
+      rt,
+      spec: { prompt: 'echo', mode: 'echo-model', model: 'unlisted-parent' },
+      retainSession: false,
+    });
+
+    expect(result.text).toBe('unlisted-parent');
+    expect(findWarning(events)).toBeUndefined();
+  });
+
+  it('grandchildren inherit the child effective model, not the grandparent model', async () => {
+    const session = buildSession(['parent-model', 'cheap-model']);
+    const rt = buildRuntime(session, 'parent-model');
+
+    const result = await runChildTurn({
+      rt,
+      spec: { prompt: 'spawn nested', mode: 'nested-spawn', model: 'cheap-model' },
+      retainSession: false,
+    });
+
+    // The grandchild echoes its own ctx.model — it must see the child's
+    // resolved model ('cheap-model'), not the original parent's.
+    expect(result.text).toBe('cheap-model');
+  });
+});