@moxxy/core 0.3.0

package/src/run-turn.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it } from 'vitest';
+import type { ModeContext, ModeDef, MoxxyEvent, ProviderDef, ToolCallContext } from '@moxxy/sdk';
+import { defineMode, defineProvider, definePlugin, defineTool, executeToolUses, z } from '@moxxy/sdk';
+import { Session } from './session.js';
+import { runTurn, collectTurn } from './run-turn.js';
+
+// A loop that emits N assistant_message events that include `turnId` in the
+// text, then returns. It does NOT touch the provider, so concurrency is
+// dominated by the awaits inside the loop body (deterministic interleave via
+// the microtask queue).
+function makeMarkerLoop(name: string, n: number): ModeDef {
+  return defineMode({
+    name,
+    run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+      for (let i = 0; i < n; i++) {
+        // Yield to the microtask queue so two concurrent runs interleave.
+        await Promise.resolve();
+        await ctx.emit({
+          type: 'assistant_message',
+          sessionId: ctx.sessionId,
+          turnId: ctx.turnId,
+          source: 'assistant',
+          text: `${ctx.turnId}:${i}`,
+        });
+      }
+    },
+  });
+}
+
+function makeNoopProvider(): ProviderDef {
+  const models = [{ id: 'noop-1' }];
+  return defineProvider({
+    name: 'noop',
+    models,
+    createClient: () => ({
+      name: 'noop',
+      models,
+      stream: async function* () {
+        // unused — the test loop doesn't call into the provider.
+      },
+      countTokens: async () => 0,
+    }),
+  });
+}
+
+function buildSession(): Session {
+  const session = new Session({ cwd: '/tmp', silent: true });
+  session.pluginHost.registerStatic(
+    definePlugin({
+      name: 'test-loop-and-provider',
+      version: '0.0.0',
+      providers: [makeNoopProvider()],
+      modes: [makeMarkerLoop('marker', 3)],
+    }),
+  );
+  session.providers.setActive('noop');
+  session.modes.setActive('marker');
+  return session;
+}
+
+describe('runTurn turnId filtering', () => {
+  it('a single turn surfaces all of its own events', async () => {
+    const session = buildSession();
+    const events = await collectTurn(session, 'hi');
+    const turnIds = new Set(events.map((e) => e.turnId));
+    expect(turnIds.size).toBe(1);
+    expect(events.filter((e) => e.type === 'assistant_message')).toHaveLength(3);
+  });
+
+  it('two concurrent turns do not cross-contaminate', async () => {
+    const session = buildSession();
+    const [eventsA, eventsB] = await Promise.all([
+      collectTurn(session, 'A'),
+      collectTurn(session, 'B'),
+    ]);
+
+    const turnIdA = eventsA[0]?.turnId;
+    const turnIdB = eventsB[0]?.turnId;
+    expect(turnIdA).toBeDefined();
+    expect(turnIdB).toBeDefined();
+    expect(turnIdA).not.toBe(turnIdB);
+
+    // Every event in each result must carry the same turnId as the first
+    // event of that result. Without the filter at run-turn.ts, A's events
+    // would include B's events and vice versa.
+    expect(eventsA.every((e) => e.turnId === turnIdA)).toBe(true);
+    expect(eventsB.every((e) => e.turnId === turnIdB)).toBe(true);
+
+    // Each turn yields user_prompt + 3 assistant_message events.
+    expect(eventsA.filter((e) => e.type === 'assistant_message')).toHaveLength(3);
+    expect(eventsB.filter((e) => e.type === 'assistant_message')).toHaveLength(3);
+  });
+
+  it('does not leak a subscription when startTurn throws after subscribe', async () => {
+    const session = buildSession();
+    // Force startTurn to throw by removing the active loop strategy after
+    // creating the session — getActive() will throw before we touch the log.
+    session.modes.unregister('marker');
+
+    let listenerCountBefore = 0;
+    let listenerCountAfter = 0;
+    // Peek at the listener set size via subscribing/unsubscribing a no-op
+    // (subscribe returns identity-keyed unsubscribers; we infer the leak by
+    // running runTurn many times and checking the log still works normally).
+    const probe = session.log.subscribe(() => {});
+    listenerCountBefore = 1;
+    probe();
+
+    let threw = false;
+    try {
+      for await (const _ of runTurn(session, 'will fail')) {
+        void _;
+      }
+    } catch {
+      threw = true;
+    }
+    expect(threw).toBe(true);
+
+    const probe2 = session.log.subscribe(() => {});
+    listenerCountAfter = 1;
+    probe2();
+
+    // If runTurn leaked its subscription, the EventLog's listener count would
+    // have grown; we can't observe that directly, but we can verify the next
+    // turn still receives a clean event stream (no spurious replays).
+    expect(listenerCountAfter).toBe(listenerCountBefore);
+  });
+});
+
+describe('runTurn threads real cwd/env into onToolCall hooks', () => {
+  it('the dispatchToolCall hook ctx carries the session cwd/env, not empty placeholders', async () => {
+    const captured: { cwd?: string; envFoo?: string } = {};
+    const SESSION_CWD = '/tmp/policy-cwd';
+
+    // A mode that dispatches a single tool use through the shared dispatcher
+    // (the same path default/goal use), so the onToolCall hook fires with the
+    // ModeContext-derived cwd/env.
+    const dispatchMode = defineMode({
+      name: 'dispatch-one',
+      run: async function* (ctx: ModeContext): AsyncIterable<MoxxyEvent> {
+        yield* executeToolUses(ctx, [{ id: 'c1', name: 'noop', input: {} }], 1);
+      },
+    });
+
+    const session = new Session({ cwd: SESSION_CWD, silent: true });
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'cwd-env-probe',
+        version: '0.0.0',
+        providers: [makeNoopProvider()],
+        modes: [dispatchMode],
+        tools: [
+          defineTool({
+            name: 'noop',
+            description: '',
+            inputSchema: z.object({}),
+            handler: () => 'ok',
+          }),
+        ],
+        hooks: {
+          onToolCall: (ctx: ToolCallContext) => {
+            captured.cwd = ctx.cwd;
+            captured.envFoo = ctx.env.PATH; // a real env var that always exists
+          },
+        },
+      }),
+    );
+    session.providers.setActive('noop');
+    session.modes.setActive('dispatch-one');
+
+    await collectTurn(session, 'go');
+
+    // Previously hardcoded '' / {}, which silently defeated path-based policy
+    // hooks. Must now be the real session cwd + a populated env.
+    expect(captured.cwd).toBe(SESSION_CWD);
+    expect(captured.envFoo).toBe(process.env.PATH);
+  });
+});

package/src/run-turn.ts

@@ -0,0 +1,156 @@
+import type { EmittedEvent, ModeContext, MoxxyEvent, RunTurnOptions } from '@moxxy/sdk';
+import type { SessionRuntime } from './session-runtime.js';
+import { createSubagentSpawner } from './subagents.js';
+
+// `RunTurnOptions` now lives in `@moxxy/sdk` so the runner client (which has
+// no `Session`) can reference it. Re-exported here to keep the historical
+// `@moxxy/core` import path working.
+export type { RunTurnOptions } from '@moxxy/sdk';
+
+export async function* runTurn(
+  session: SessionRuntime,
+  prompt: string,
+  opts: RunTurnOptions = {},
+): AsyncIterable<MoxxyEvent> {
+  // Mint the turnId first so the subscriber below can filter by it. Without
+  // the filter, concurrent runTurn() calls on the same Session would each
+  // observe every event from every other turn (the EventLog has one global
+  // listener set), causing cross-talk for hosts like the HTTP channel that
+  // serve multiple turns in parallel.
+  // Use a caller-supplied turnId when present (the runner mints it up front so
+  // it can return the id before the turn runs); otherwise mint one here.
+  const turnId = opts.turnId ?? session.startTurn().turnId;
+  const provider = session.providers.getActive();
+  const model = opts.model ?? provider.models[0]?.id ?? 'default';
+  // Record the resolution so out-of-band spawns (workflow triggers) can
+  // inherit the conversation's current model. Last-writer-wins when turns
+  // run concurrently — see the field's doc in SessionRuntime.
+  session.lastResolvedModel = model;
+
+  const queue: MoxxyEvent[] = [];
+  const waiters: Array<() => void> = [];
+  let done = false;
+  let strategyError: unknown = null;
+  // A mode can ask (via ctx.requestModeSwitch) to hand off to another mode
+  // once this turn finishes — applied after the strategy drains, below.
+  let requestedModeSwitch: string | null = null;
+
+  const wake = (): void => waiters.shift()?.();
+  const unsubscribe = session.log.subscribe((event) => {
+    if (event.turnId !== turnId) return;
+    queue.push(event);
+    wake();
+  });
+
+  let strategyPromise: Promise<void> | null = null;
+
+  try {
+    await session.log.append({
+      type: 'user_prompt',
+      sessionId: session.id,
+      turnId,
+      source: 'user',
+      text: prompt,
+      ...(opts.attachments && opts.attachments.length > 0
+        ? { attachments: opts.attachments }
+        : {}),
+    });
+
+    const strategy = session.modes.getActive();
+    // Combine the session's signal with the per-turn one (if provided)
+    // so either firing cancels the turn.
+    const effectiveSignal = opts.signal
+      ? AbortSignal.any([session.signal, opts.signal])
+      : session.signal;
+    // The session's working dir + environment, mirrored onto the ModeContext
+    // so the shared tool dispatcher can hand onToolCall hooks the real cwd/env
+    // (path-based policy hooks gate on these) instead of empty placeholders.
+    const appCtx = session.appContext();
+    const ctx: ModeContext = {
+      sessionId: session.id,
+      turnId,
+      cwd: appCtx.cwd,
+      env: appCtx.env,
+      model,
+      systemPrompt: opts.systemPrompt,
+      provider,
+      tools: session.tools,
+      skills: session.skills,
+      log: session.log,
+      compactor: session.compactors.getActive(),
+      cacheStrategy: session.cacheStrategies.getActive(),
+      ...(session.elisionSettings ? { elision: session.elisionSettings } : {}),
+      ...(session.lazyTools ? { lazyTools: true } : {}),
+      // Reasoning preference (effort) — honored only by providers/models that
+      // advertise `supportsReasoning` (gated in collectProviderStream).
+      ...(session.reasoning ? { reasoning: session.reasoning } : {}),
+      permissions: session.resolver,
+      ...(session.approvalResolver ? { approval: session.approvalResolver } : {}),
+      hooks: session.dispatcher,
+      pluginHost: session.pluginHost,
+      signal: effectiveSignal,
+      maxIterations: opts.maxIterations,
+      subagents: createSubagentSpawner({
+        parentSession: session,
+        parentTurnId: turnId,
+        parentSignal: effectiveSignal,
+        parentModel: model,
+      }),
+      requestModeSwitch: (modeName: string) => {
+        requestedModeSwitch = modeName;
+      },
+      emit: (event: EmittedEvent) => session.log.append(event),
+    };
+
+    const turnStartCtx = { ...appCtx, turnId, iteration: 0 };
+
+    strategyPromise = (async () => {
+      try {
+        await session.dispatcher.dispatchTurnStart(turnStartCtx);
+        for await (const _ of strategy.run(ctx)) {
+          // Events are surfaced via the log subscription above.
+          void _;
+        }
+        await session.dispatcher.dispatchTurnEnd(turnStartCtx);
+      } catch (err) {
+        strategyError = err;
+      } finally {
+        done = true;
+        wake();
+      }
+    })();
+
+    while (true) {
+      while (queue.length > 0) yield queue.shift() as MoxxyEvent;
+      if (done) break;
+      await new Promise<void>((resolve) => waiters.push(resolve));
+    }
+  } finally {
+    unsubscribe();
+    if (strategyPromise) await strategyPromise;
+    // Apply a mode hand-off the strategy requested, now that the turn has
+    // fully drained. Only on clean completion (a thrown/aborted turn keeps
+    // the current mode); an unknown target is ignored so a bad name can't
+    // wedge the session. The registry's setActive triggers the runner's
+    // InfoChanged broadcast, so channels see the new mode.
+    if (requestedModeSwitch && !strategyError) {
+      try {
+        session.modes.setActive(requestedModeSwitch);
+      } catch {
+        /* unregistered target — leave the active mode unchanged */
+      }
+    }
+  }
+
+  if (strategyError) throw strategyError;
+}
+
+export async function collectTurn(
+  session: SessionRuntime,
+  prompt: string,
+  opts: RunTurnOptions = {},
+): Promise<ReadonlyArray<MoxxyEvent>> {
+  const events: MoxxyEvent[] = [];
+  for await (const event of runTurn(session, prompt, opts)) events.push(event);
+  return events;
+}

package/src/session-runtime.ts

@@ -0,0 +1,75 @@
+import type {
+  AppContext,
+  ApprovalResolver,
+  CacheStrategyDef,
+  CompactorDef,
+  ElisionSettings,
+  HookDispatcher,
+  LLMProvider,
+  ModeDef,
+  PermissionResolver,
+  PluginHostHandle,
+  SessionId,
+  SkillRegistry,
+  TurnId,
+} from '@moxxy/sdk';
+
+import type { EventLog } from './events/log.js';
+// The concrete `Session` carries core's own richer tool registry (extra
+// methods the SDK surface doesn't model); use it here so consumers like
+// `buildFilteredToolRegistry` keep type-checking.
+import type { ToolRegistry } from './registries/tools.js';
+
+/**
+ * The slice of the concrete `Session` that the turn driver (`run-turn.ts`)
+ * and the subagent runtime (`subagents/spawn.ts`, `subagents/events.ts`)
+ * actually consume. Those modules depend on *this* interface rather than
+ * importing the `Session` class directly.
+ *
+ * Why: `session.ts` value-imports `runTurn`, so if `run-turn.ts` (and the
+ * subagent modules it pulls in) imported the `Session` class back, the
+ * package would have an import cycle — flagged by `pnpm check:deps` because
+ * dependency-cruiser tracks type-only edges (`tsPreCompilationDeps`). Routing
+ * through this leaf contract keeps the value graph a DAG
+ * (`session → run-turn → subagents → spawn → events`) with no edges pointing
+ * back at `session.ts`.
+ *
+ * `Session implements SessionRuntime`, so the contract can't silently drift
+ * from the class it abstracts.
+ */
+export interface SessionRuntime {
+  readonly id: SessionId;
+  readonly log: EventLog;
+  readonly signal: AbortSignal;
+  readonly tools: ToolRegistry;
+  readonly skills: SkillRegistry;
+  readonly providers: { getActive(): LLMProvider };
+  readonly modes: {
+    getActive(): ModeDef;
+    list(): ReadonlyArray<ModeDef>;
+    /** Post-turn mode hand-off (one mode handing back to another). Throws on an
+     *  unknown name; run-turn guards the call. */
+    setActive(name: string): void;
+  };
+  readonly compactors: { getActive(): CompactorDef | null };
+  readonly cacheStrategies: { getActive(): CacheStrategyDef | null };
+  readonly resolver: PermissionResolver;
+  readonly approvalResolver: ApprovalResolver | null;
+  readonly elisionSettings: ElisionSettings | null;
+  readonly lazyTools: boolean;
+  /** Reasoning/thinking preference (effort), forwarded to each turn's ModeContext. */
+  readonly reasoning?: { readonly effort?: 'low' | 'medium' | 'high' } | boolean | undefined;
+  readonly dispatcher: HookDispatcher;
+  readonly pluginHost: PluginHostHandle;
+  /**
+   * Model id resolved by the most recent `runTurn()` on this session.
+   * Out-of-band spawns (workflow triggers, schedulers) read this so their
+   * children inherit whatever the user is currently talking to instead of a
+   * stale hardcoded default. Last-writer-wins under concurrent turns — it is
+   * a "current conversation model" hint, not a per-turn record. Null until
+   * the first turn resolves a model.
+   */
+  lastResolvedModel: string | null;
+  startTurn(): { turnId: TurnId };
+  appContext(): AppContext;
+}

package/src/session.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it, vi } from 'vitest';
+import { asSessionId, asToolCallId, defineMode, definePlugin } from '@moxxy/sdk';
+import { Session } from './session.js';
+import {
+  getRetainedChild,
+  registerRetainedChild,
+  releaseRetainedChild,
+  type RetainedChildSession,
+} from './subagents/registry.js';
+
+describe('Session', () => {
+  it('boots with sensible defaults', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    expect(s.id).toMatch(/^[0-9A-Z]+$/);
+    expect(s.cwd).toBe('/tmp');
+    expect(s.log.length).toBe(0);
+    expect(s.signal.aborted).toBe(false);
+  });
+
+  it('abort flips signal', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    s.abort('test');
+    expect(s.signal.aborted).toBe(true);
+  });
+
+  it('startTurn returns a fresh turn id', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const t1 = s.startTurn().turnId;
+    const t2 = s.startTurn().turnId;
+    expect(t1).not.toBe(t2);
+  });
+
+  it('exposes an immutable appContext snapshot', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const ctx = s.appContext();
+    expect(ctx.sessionId).toBe(s.id);
+    expect(ctx.cwd).toBe('/tmp');
+    expect(ctx.log.length).toBe(0);
+  });
+
+  it('fans appended events out to plugin onEvent hooks', async () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const onEvent = vi.fn();
+    s.pluginHost.registerStatic(
+      definePlugin({
+        name: 'observer',
+        version: '0.0.0',
+        hooks: { onEvent },
+      }),
+    );
+    await s.log.append({
+      type: 'user_prompt',
+      sessionId: s.id,
+      turnId: s.startTurn().turnId,
+      source: 'user',
+      text: 'hi',
+    });
+    expect(onEvent).toHaveBeenCalledTimes(1);
+    const arg = onEvent.mock.calls[0]![0] as { type: string; text?: string };
+    expect(arg.type).toBe('user_prompt');
+    expect(arg.text).toBe('hi');
+  });
+
+  it('close() fires plugin onShutdown hooks and aborts the session', async () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const onShutdown = vi.fn();
+    s.pluginHost.registerStatic(
+      definePlugin({ name: 'p', version: '0.0.0', hooks: { onShutdown } }),
+    );
+    await s.close();
+    expect(onShutdown).toHaveBeenCalledTimes(1);
+    expect(s.signal.aborted).toBe(true);
+  });
+
+  it('close() is idempotent', async () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const onShutdown = vi.fn();
+    s.pluginHost.registerStatic(
+      definePlugin({ name: 'p', version: '0.0.0', hooks: { onShutdown } }),
+    );
+    await s.close();
+    await s.close();
+    expect(onShutdown).toHaveBeenCalledTimes(1);
+  });
+
+  it('close() clears only THIS session\'s retained children, not another live session\'s', async () => {
+    const a = new Session({ cwd: '/tmp', silent: true });
+    const b = new Session({ cwd: '/tmp', silent: true });
+    const childId = asSessionId('retained-scope-test');
+    // A workflow awaitInput pause on session A registers a retained child whose
+    // parentSession is A. Closing a DIFFERENT session (B) must NOT wipe it —
+    // otherwise B's close breaks A's pending continue().
+    registerRetainedChild({
+      childSessionId: childId,
+      parentSession: a,
+    } as unknown as RetainedChildSession);
+    expect(getRetainedChild(childId)).toBeDefined();
+    try {
+      await b.close();
+      // Survives B's close — it belongs to A.
+      expect(getRetainedChild(childId)).toBeDefined();
+      // A's own close reclaims it.
+      await a.close();
+      expect(getRetainedChild(childId)).toBeUndefined();
+    } finally {
+      releaseRetainedChild(childId);
+    }
+  });
+
+  it('getInfo returns a serializable snapshot of the registries', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const info = s.getInfo();
+    expect(info.sessionId).toBe(s.id);
+    expect(info.cwd).toBe('/tmp');
+    // Bare session: nothing active yet, all lists empty, no transcriber.
+    expect(info.activeProvider).toBeNull();
+    expect(info.activeMode).toBeNull();
+    expect(info.activeModeBadge).toBeNull();
+    expect(info.providers).toEqual([]);
+    expect(info.modes).toEqual([]);
+    expect(info.tools).toEqual([]);
+    expect(info.commands).toEqual([]);
+    expect(info.readyProviders).toEqual([]);
+    expect(info.hasTranscriber).toBe(false);
+    // The snapshot must survive a JSON round-trip (it crosses the wire).
+    expect(JSON.parse(JSON.stringify(info))).toEqual(info);
+  });
+
+  it('getInfo surfaces the active mode badge (and null for unbadged modes)', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    // First registration auto-activates — a badged mode lights up the snapshot
+    // so channels can render a persistent indicator (e.g. goal mode).
+    s.modes.register(
+      defineMode({
+        name: 'goal',
+        badge: { label: 'GOAL', tone: 'attention' },
+        run: async function* () {},
+      }),
+    );
+    expect(s.getInfo().activeModeBadge).toEqual({ label: 'GOAL', tone: 'attention' });
+
+    // Switching to a mode with no badge clears it back to null.
+    s.modes.register(defineMode({ name: 'plain', run: async function* () {} }));
+    s.modes.setActive('plain');
+    expect(s.getInfo().activeMode).toBe('plain');
+    expect(s.getInfo().activeModeBadge).toBeNull();
+  });
+
+  it('exposes runTurn as a method (SessionLike conformance)', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    expect(typeof s.runTurn).toBe('function');
+    expect(typeof s.getInfo).toBe('function');
+  });
+
+  it('resolver.policyCheck probes policy without falling through to the prompt resolver', async () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    let prompted = 0;
+    s.setPermissionResolver({
+      name: 'counting-prompt',
+      check: async () => {
+        prompted += 1;
+        return { mode: 'allow', reason: 'prompt said yes' };
+      },
+    });
+    await s.permissions.addDeny({ name: 'Bash', reason: 'no shell' });
+
+    const permCtx = { sessionId: String(s.id) };
+    // A matching deny rule decides — prompt-free.
+    const deny = await s.resolver.policyCheck?.(
+      { callId: asToolCallId('c1'), name: 'Bash', input: {} },
+      permCtx,
+    );
+    expect(deny).toEqual({ mode: 'deny', reason: 'no shell' });
+    // No matching rule → null (the caller supplies its own fallback); the
+    // wrapped prompt resolver is NEVER consulted by policyCheck.
+    const undecided = await s.resolver.policyCheck?.(
+      { callId: asToolCallId('c2'), name: 'Other', input: {} },
+      permCtx,
+    );
+    expect(undecided).toBeNull();
+    expect(prompted).toBe(0);
+    // check() keeps its existing behavior: policy first, then fall through.
+    const viaCheck = await s.resolver.check(
+      { callId: asToolCallId('c3'), name: 'Other', input: {} },
+      permCtx,
+    );
+    expect(viaCheck.mode).toBe('allow');
+    expect(prompted).toBe(1);
+  });
+
+  it('resolver passes non-check members (e.g. abortAll) through to the underlying resolver with correct `this`', () => {
+    const s = new Session({ cwd: '/tmp', silent: true });
+    const abortAll = vi.fn();
+    // A resolver carrying an extra member that reads private-ish state via
+    // `this` — the Proxy must forward both the call and the receiver binding.
+    const inner = {
+      name: 'channel-resolver',
+      _closedReason: 'shutting down',
+      check: async () => ({ mode: 'allow' as const }),
+      abortAll,
+      reasonViaThis(): string {
+        return this._closedReason;
+      },
+    };
+    s.setPermissionResolver(inner as never);
+
+    const wrapped = s.resolver as unknown as {
+      abortAll: (reason?: string) => void;
+      reasonViaThis: () => string;
+    };
+    wrapped.abortAll('bye');
+    expect(abortAll).toHaveBeenCalledWith('bye');
+    // `this` is bound through the proxy so a method reading sibling state works.
+    expect(wrapped.reasonViaThis()).toBe('shutting down');
+  });
+});