@moxxy/sdk 0.1.0

package/src/channel.ts

@@ -0,0 +1,158 @@
+import type { PermissionResolver } from './permission.js';
+import type { ClientSession } from './client-session.js';
+
+/**
+ * A Channel is a bidirectional surface that drives a Session: it feeds user
+ * prompts in, renders assistant chunks + tool activity out, and implements a
+ * PermissionResolver so it can interrupt tool execution to ask the user.
+ *
+ * The TUI (Ink) and Telegram are both Channels. Future Slack / Discord / HTTP
+ * channels implement this same interface so the moxxy CLI binary (or any
+ * embedded consumer) can dispatch to them uniformly.
+ *
+ * The generic `TStartOpts` is the concrete options shape a given channel
+ * accepts.
+ */
+export interface Channel<TStartOpts = unknown> {
+  /** Stable name (lowercase, single word). Used by dispatchers to look up by string. */
+  readonly name: string;
+
+  /** The PermissionResolver this channel installs on the session. */
+  readonly permissionResolver: PermissionResolver;
+
+  /**
+   * Begin running the channel. Returns a handle whose `running` promise
+   * resolves when the channel exits gracefully.
+   */
+  start(opts: TStartOpts): Promise<ChannelHandle>;
+}
+
+export interface ChannelHandle {
+  /**
+   * Resolves when the channel exits cleanly (user quit, SIGINT caught,
+   * upstream disconnected). Rejects on fatal error.
+   */
+  readonly running: Promise<void>;
+
+  /** Request graceful shutdown. Implementations should abort any in-flight work. */
+  stop(reason?: string): Promise<void>;
+}
+
+/** Common base shape for channel start options. */
+export interface ChannelStartOptsBase {
+  readonly model?: string;
+  readonly systemPrompt?: string;
+}
+
+/**
+ * Standard dependencies that a channel factory receives. Channels pick what
+ * they need from this bag. Production CLI populates all of these; tests may
+ * pass only a subset.
+ */
+export interface ChannelFactoryDeps {
+  /** Working directory for the channel (matches the Session's cwd). */
+  readonly cwd: string;
+  /** Optional encrypted-secret store (typed loosely — plugins import the concrete VaultStore type when needed). */
+  readonly vault?: unknown;
+  /** Optional structured logger. */
+  readonly logger?: {
+    debug?(msg: string, meta?: Record<string, unknown>): void;
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+    error?(msg: string, meta?: Record<string, unknown>): void;
+  };
+  /** Free-form per-channel overrides forwarded from the CLI invocation. */
+  readonly options?: Record<string, unknown>;
+}
+
+/**
+ * A registered, named factory for a Channel. Plugins contribute these via
+ * `definePlugin({ channels: [defineChannel(...)] })`. The CLI looks up by name
+ * and dispatches: `moxxy <name>` calls `def.create(deps).start({session,...})`.
+ */
+export interface ChannelDef<TStartOpts = unknown> {
+  readonly name: string;
+  readonly description: string;
+  create(deps: ChannelFactoryDeps): Channel<TStartOpts>;
+  /**
+   * Optional runtime gate. Lets a channel declare "I can only run if these
+   * preconditions are met" (e.g., Telegram needs a token in the vault; TUI
+   * needs a TTY). The dispatcher uses this to filter the visible channel list
+   * and to give the user a helpful error before construction.
+   *
+   * Default: always available.
+   */
+  isAvailable?(deps: ChannelFactoryDeps): Promise<ChannelAvailability>;
+  /**
+   * One-shot subcommands the channel exposes. Routed as
+   * `moxxy channels <name> <subcommand>` by the CLI. Use this for
+   * channel-specific maintenance commands that don't need to run the channel
+   * (e.g., Telegram's `unpair`, `status`) — or that want to nudge a start with
+   * a flag (e.g., `pair` -> start with options.pair=true).
+   */
+  readonly subcommands?: Readonly<Record<string, ChannelSubcommand>>;
+  /**
+   * Name of a subcommand to run for a bare `moxxy <name>` invocation on a TTY -
+   * e.g. an interactive setup wizard. When absent, a bare invocation just
+   * starts the channel.
+   */
+  readonly interactiveCommand?: string;
+}
+
+export interface ChannelAvailability {
+  readonly ok: boolean;
+  /** Human-readable explanation when ok=false. Shown by `moxxy channels list`. */
+  readonly reason?: string;
+}
+
+/** Positional + flag args handed to a channel subcommand by the CLI. */
+export interface ChannelCommandArgs {
+  readonly positional: ReadonlyArray<string>;
+  readonly flags: Readonly<Record<string, string | boolean | undefined>>;
+}
+
+/**
+ * Context handed to a channel subcommand. The CLI builds `deps` exactly like
+ * it does for `Channel.create()` so subcommands can:
+ *  - inspect `deps.vault` for one-shot ops (unpair, status)
+ *  - mutate `deps.options` and call `startChannel()` to launch the channel
+ *    with extra start opts (e.g., pair=true)
+ */
+export interface ChannelSubcommandContext {
+  readonly deps: ChannelFactoryDeps;
+  readonly args: ChannelCommandArgs;
+  /**
+   * Boot a session and run the channel by name. Returns the process exit code
+   * (0 on clean shutdown). Subcommands that want to "start with twist" call
+   * this with overrides instead of duplicating the start-loop themselves.
+   */
+  startChannel(options?: Readonly<Record<string, unknown>>): Promise<number>;
+  /**
+   * The booted session, so a subcommand can do channel-instance work like
+   * pairing.
+   */
+  readonly session: ClientSession;
+}
+
+export interface ChannelSubcommand {
+  readonly description: string;
+  run(ctx: ChannelSubcommandContext): Promise<number>;
+}
+
+/**
+ * Read-only registry of channels available in a Session. Implementation lives
+ * in @moxxy/core.
+ */
+export interface ChannelRegistry {
+  list(): ReadonlyArray<ChannelDef>;
+  get(name: string): ChannelDef | undefined;
+  has(name: string): boolean;
+  /**
+   * Returns every channel paired with its current availability. Channels
+   * without an `isAvailable` hook are treated as `{ok: true}`.
+   */
+  listWithAvailability(deps: ChannelFactoryDeps): Promise<ReadonlyArray<{
+    readonly def: ChannelDef;
+    readonly availability: ChannelAvailability;
+  }>>;
+}

package/src/client-session.ts

@@ -0,0 +1,88 @@
+import type { AgentDef } from './agent.js';
+import type { CommandDef } from './command.js';
+import type { ModeDef } from './mode.js';
+import type { LLMProvider, ProviderDef } from './provider.js';
+import type { RequirementCheck, MoxxyRequirement } from './requirements.js';
+import type { SessionLike, SessionLogReader } from './session-like.js';
+import type { Skill } from './skill.js';
+import type { ToolDef } from './tool.js';
+import type { Transcriber } from './transcriber.js';
+
+/**
+ * `ClientSession` widens {@link SessionLike} with the read-and-act registry
+ * surface a rich interactive channel (the Ink TUI) actually touches. Both the
+ * in-process `Session` (whose concrete registries are supersets of these
+ * views) and the `RemoteSession` proxy implement it, so the TUI is written
+ * once against `ClientSession` and runs unchanged either way.
+ *
+ * The views are intentionally narrow - only what the TUI calls. Methods are
+ * declared method-style (bivariant) so a concrete `Session` registry satisfies
+ * the view even where its real signature is slightly wider. On a remote
+ * client, the facades behind these views are backed by the runner's `getInfo`
+ * snapshot for reads and by RPCs for the few mutating calls; genuinely
+ * server-only capabilities (voice transcription, MCP admin) degrade rather
+ * than pretend.
+ */
+
+export interface ProvidersClientView {
+  getActive(): LLMProvider;
+  getActiveName(): string | null;
+  list(): ReadonlyArray<ProviderDef>;
+  setActive(name: string, config?: Record<string, unknown>): LLMProvider;
+  replace(def: ProviderDef, instance?: LLMProvider): void;
+}
+
+export interface ModesClientView {
+  list(): ReadonlyArray<ModeDef>;
+  getActive(): ModeDef;
+  setActive(name: string): void;
+}
+
+export interface ToolsClientView {
+  list(): ReadonlyArray<ToolDef>;
+  get(name: string): ToolDef | undefined;
+}
+
+export interface CommandsClientView {
+  get(name: string): CommandDef | undefined;
+  listForChannel(channel: string): ReadonlyArray<CommandDef>;
+}
+
+export interface SkillsClientView {
+  list(): ReadonlyArray<Skill>;
+}
+
+export interface AgentsClientView {
+  list(): ReadonlyArray<AgentDef>;
+}
+
+export interface TranscribersClientView {
+  getActiveName(): string | null;
+  has(name: string): boolean;
+  getActive(): Transcriber;
+  /** Active transcriber or null. Channels guard on this for audio input. */
+  tryGetActive(): Transcriber | null;
+  setActive(name: string, config?: Record<string, unknown>): Transcriber;
+}
+
+export interface RequirementsClientView {
+  check(requirements: ReadonlyArray<MoxxyRequirement>): RequirementCheck;
+}
+
+export interface PermissionsClientView {
+  addAllow(rule: { readonly name: string; readonly reason?: string }): Promise<void>;
+}
+
+export interface ClientSession extends SessionLike {
+  /** The mirror/real log, plus `clear()` for `/new`. */
+  readonly log: SessionLogReader & { clear(): void };
+  readonly providers: ProvidersClientView;
+  readonly modes: ModesClientView;
+  readonly tools: ToolsClientView;
+  readonly commands: CommandsClientView;
+  readonly skills: SkillsClientView;
+  readonly agents: AgentsClientView;
+  readonly transcribers: TranscribersClientView;
+  readonly requirements: RequirementsClientView;
+  readonly permissions: PermissionsClientView;
+}

package/src/command.ts

@@ -0,0 +1,86 @@
+/**
+ * Commands — channel-agnostic actions the user can trigger with a
+ * `/<name>` prefix. Live on the Session's CommandRegistry so every
+ * channel (TUI slash menu, Telegram bot command, future HTTP `/cmd`
+ * endpoint) reads the same set. Plugins contribute commands via
+ * `PluginSpec.commands`.
+ *
+ * Why a registry instead of channel-local switch statements:
+ * /info works the same way whether the user types it in the TUI or
+ * sends `/info` to the Telegram bot. The handler returns a typed
+ * CommandOutput; each channel decides how to render it (TUI as a
+ * systemNotice, Telegram as a chat message, HTTP as JSON).
+ */
+
+import type { SessionId } from './ids.js';
+
+export interface CommandDef {
+  /** Name without the leading `/`. */
+  readonly name: string;
+  /** One-line description shown in `/help` and channel pickers. */
+  readonly description: string;
+  /**
+   * Usage hint for the arguments, e.g. `set <name> <value>`. Interactive
+   * channels may render it as dimmed ghost text after the command name
+   * while the user is typing (autocomplete preview). Placeholders like
+   * `<name>` are illustrative — never inserted into the buffer literally.
+   */
+  readonly argumentHint?: string;
+  /** Alternative names (without leading `/`). */
+  readonly aliases?: ReadonlyArray<string>;
+  /**
+   * When set, the command only surfaces in these channels by name
+   * (e.g. `['tui']` for an overlay-style command that wouldn't make
+   * sense in Telegram). Omit for "all channels".
+   */
+  readonly channels?: ReadonlyArray<string>;
+  /** Optional short status shown by interactive channels while the command runs. */
+  readonly pendingNotice?: string;
+  /** Handler invoked by the channel. Receives raw args after the name. */
+  readonly handler: (ctx: CommandContext) => Promise<CommandOutput> | CommandOutput;
+}
+
+export interface CommandContext {
+  /** Channel that invoked the command — `'tui'`, `'telegram'`, etc. */
+  readonly channel: string;
+  /** Session id the command runs against. */
+  readonly sessionId: SessionId;
+  /** Raw text after the command name (`"hello"` for `/echo hello`). */
+  readonly args: string;
+  /**
+   * The active Session. Loosely typed (`unknown`) so the SDK doesn't
+   * pull in core; handlers cast to `Session` from `@moxxy/core` when
+   * they need registries. The plugin host always passes the real
+   * Session here.
+   */
+  readonly session: unknown;
+}
+
+/**
+ * What a command returns. Channels pick the appropriate UI for each
+ * variant. New variants are additive — channels that don't know a
+ * variant fall back to rendering its `text` field if present.
+ */
+export type CommandOutput =
+  /** Simple text response. Every channel can render this. */
+  | { readonly kind: 'text'; readonly text: string }
+  /**
+   * Structural action that the host channel performs in its UI
+   * (`clear`/`new`/`exit`). Carries an optional message the channel
+   * may surface alongside the action.
+   */
+  | {
+      readonly kind: 'session-action';
+      readonly action: 'new' | 'clear' | 'exit';
+      readonly notice?: string;
+    }
+  /** No-op (handler decided nothing needs surfacing). */
+  | { readonly kind: 'noop' }
+  /**
+   * Handler errored. Channels render this distinctly (red text, etc.).
+   * Use this instead of throwing so the command pipeline never
+   * crashes the channel.
+   */
+  | { readonly kind: 'error'; readonly message: string };
+
+export type CommandHandlerResult = CommandOutput;

package/src/compactor-helpers.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  asEventId,
+  asSessionId,
+  asTurnId,
+  estimateContextTokens,
+  runCompactionIfNeeded,
+  type CompactorDef,
+  type EmittedEvent,
+  type EventLogReader,
+  type LLMProvider,
+  type ModeContext,
+  type MoxxyEvent,
+  type MoxxyEventOfType,
+  type MoxxyEventType,
+  type TurnId,
+} from './index.js';
+
+const sid = asSessionId('s1');
+const tid = asTurnId('t1');
+
+describe('estimateContextTokens', () => {
+  it('counts char/4 over events, honoring compaction', () => {
+    const log = reader([
+      event(0, { type: 'user_prompt', turnId: tid, source: 'user', text: 'x'.repeat(400) }),
+      event(1, {
+        type: 'compaction',
+        turnId: tid,
+        source: 'compactor',
+        compactor: 'summarize',
+        replacedRange: [0, 0],
+        summary: 'y'.repeat(40),
+        tokensSaved: 90,
+      }),
+    ]);
+    // 400-char user_prompt is covered by the compaction; only the 40-char
+    // summary should count.
+    expect(estimateContextTokens(log)).toBe(10);
+  });
+});
+
+describe('runCompactionIfNeeded', () => {
+  it('is a no-op when no compactor is active', async () => {
+    const ctx = makeCtx({ compactor: null });
+    await runCompactionIfNeeded(ctx);
+    expect(ctx.emitted).toHaveLength(0);
+  });
+
+  it('is a no-op when shouldCompact returns false', async () => {
+    const shouldCompact = vi.fn().mockReturnValue(false);
+    const compact = vi.fn();
+    const ctx = makeCtx({
+      compactor: { name: 'fake', shouldCompact, compact },
+    });
+    await runCompactionIfNeeded(ctx);
+    expect(shouldCompact).toHaveBeenCalledOnce();
+    expect(compact).not.toHaveBeenCalled();
+    expect(ctx.emitted).toHaveLength(0);
+  });
+
+  it('passes the real model contextWindow into the budget', async () => {
+    let observedWindow = 0;
+    const compactor: CompactorDef = {
+      name: 'inspect',
+      shouldCompact: (_log, budget) => {
+        observedWindow = budget.contextWindow;
+        return false;
+      },
+      compact: async () => {
+        throw new Error('should not run');
+      },
+    };
+    const ctx = makeCtx({ compactor, model: 'm-200k', contextWindow: 200_000 });
+    await runCompactionIfNeeded(ctx);
+    expect(observedWindow).toBe(200_000);
+  });
+
+  it('emits the compaction event when shouldCompact returns true', async () => {
+    const compactor: CompactorDef = {
+      name: 'fake',
+      shouldCompact: () => true,
+      compact: async () => ({
+        type: 'compaction',
+        sessionId: sid,
+        turnId: tid,
+        source: 'compactor',
+        compactor: 'fake',
+        replacedRange: [0, 0],
+        summary: 'compressed',
+        tokensSaved: 100,
+      }),
+    };
+    const ctx = makeCtx({ compactor });
+    await runCompactionIfNeeded(ctx);
+    expect(ctx.emitted).toHaveLength(1);
+    expect(ctx.emitted[0]).toMatchObject({ type: 'compaction', summary: 'compressed' });
+  });
+
+  it('skips the emit when compact returns an empty/no-op result', async () => {
+    const compactor: CompactorDef = {
+      name: 'fake',
+      shouldCompact: () => true,
+      compact: async () => ({
+        type: 'compaction',
+        sessionId: sid,
+        turnId: tid,
+        source: 'compactor',
+        compactor: 'fake',
+        replacedRange: [0, 0],
+        summary: '',
+        tokensSaved: 0,
+      }),
+    };
+    const ctx = makeCtx({ compactor });
+    await runCompactionIfNeeded(ctx);
+    expect(ctx.emitted).toHaveLength(0);
+  });
+
+  it('emits a non-fatal error event when compact throws — turn must continue', async () => {
+    const compactor: CompactorDef = {
+      name: 'broken',
+      shouldCompact: () => true,
+      compact: async () => {
+        throw new Error('boom');
+      },
+    };
+    const ctx = makeCtx({ compactor });
+    await runCompactionIfNeeded(ctx);
+    expect(ctx.emitted).toHaveLength(1);
+    expect(ctx.emitted[0]).toMatchObject({ type: 'error', kind: 'retryable' });
+  });
+});
+
+interface MakeCtxOpts {
+  readonly compactor: CompactorDef | null;
+  readonly model?: string;
+  readonly contextWindow?: number;
+  readonly events?: ReadonlyArray<MoxxyEvent>;
+}
+
+function makeCtx(opts: MakeCtxOpts): ModeContext & { emitted: EmittedEvent[] } {
+  const events = opts.events ?? [
+    event(0, { type: 'user_prompt', turnId: tid, source: 'user', text: 'hi' }),
+  ];
+  const log = reader(events);
+  const provider = {
+    name: 'fake',
+    models: [
+      {
+        id: opts.model ?? 'fake-model',
+        contextWindow: opts.contextWindow ?? 100_000,
+        supportsTools: true,
+        supportsStreaming: true,
+      },
+    ],
+    stream: async function* () { /* unused */ },
+    countTokens: async () => 0,
+  } as unknown as LLMProvider;
+
+  const emitted: EmittedEvent[] = [];
+  const ctx = {
+    sessionId: sid,
+    turnId: tid,
+    model: opts.model ?? 'fake-model',
+    provider,
+    tools: { list: () => [], get: () => undefined, execute: async () => undefined },
+    skills: { list: () => [], get: () => undefined, byName: () => undefined, filterByTriggers: () => [] },
+    log,
+    compactor: opts.compactor,
+    permissions: { decide: async () => ({ allow: true }) },
+    hooks: {} as ModeContext['hooks'],
+    pluginHost: { list: () => [], reload: async () => {} },
+    signal: new AbortController().signal,
+    emit: async (e: EmittedEvent) => {
+      emitted.push(e);
+      return { ...e, id: asEventId(`e${emitted.length}`), seq: emitted.length, ts: emitted.length, sessionId: sid } as MoxxyEvent;
+    },
+  } as unknown as ModeContext;
+
+  return Object.assign(ctx, { emitted });
+}
+
+function reader(events: ReadonlyArray<MoxxyEvent>): EventLogReader {
+  return {
+    length: events.length,
+    at: (seq) => events[seq],
+    slice: (from = 0, to = events.length) => events.slice(from, to),
+    ofType: <T extends MoxxyEventType>(type: T): ReadonlyArray<MoxxyEventOfType<T>> =>
+      events.filter((e): e is MoxxyEventOfType<T> => e.type === type),
+    byTurn: (turnId: TurnId) => events.filter((e) => e.turnId === turnId),
+    toJSON: () => events,
+  };
+}
+
+function event(
+  seq: number,
+  partial: Omit<MoxxyEvent, 'id' | 'seq' | 'ts' | 'sessionId'>,
+): MoxxyEvent {
+  return {
+    id: asEventId(`e${seq}`),
+    seq,
+    ts: seq,
+    sessionId: sid,
+    ...partial,
+  } as MoxxyEvent;
+}

package/src/compactor-helpers.ts

@@ -0,0 +1,163 @@
+import {
+  computeElisionState,
+  conversationalStub,
+  conversationalStubbed,
+  toolResultBytes,
+  toolResultStub,
+  toolResultStubbed,
+} from './elision-state.js';
+import type { EmittedEvent, MoxxyEvent } from './events.js';
+import type { EventLogReader } from './log.js';
+import type { ModeContext } from './mode.js';
+
+/**
+ * Cheap, no-network estimate of how many tokens the current event log
+ * would consume on the next provider request. Char-based (chars/4) with
+ * compaction events honored — events covered by a CompactionEvent.replacedRange
+ * count as the (much shorter) summary rather than their original bytes — and
+ * elision honored: old tool results (seq ≤ the elision high-water mark) count
+ * as their ~stub size rather than their full payload, matching what
+ * `projectMessagesFromLog` actually sends.
+ *
+ * Used by the auto-compact helper (see `runCompactionIfNeeded`) and by
+ * the TUI's context meter. For perfect accuracy callers can use the
+ * provider's `countTokens(req)`; this is the fast path that doesn't
+ * touch the network and is safe to run on every iteration.
+ */
+export function estimateContextTokens(log: EventLogReader): number {
+  const events = log.slice();
+  // Share the exact stub decision with projection so the estimate matches what
+  // is actually sent — pinned recalls / never-elide / tiny turns counted full,
+  // not undercounted (which would let the context overflow before compaction).
+  const el = computeElisionState(events);
+  let chars = 0;
+  const compactedSeqs = new Set<number>();
+  for (const e of events) {
+    if (e.type === 'compaction') {
+      for (let seq = e.replacedRange[0]; seq <= e.replacedRange[1]; seq++) {
+        compactedSeqs.add(seq);
+      }
+      chars += e.summary.length;
+    }
+  }
+  for (const e of events) {
+    if (compactedSeqs.has(e.seq)) continue;
+    if (e.type === 'tool_result' && toolResultStubbed(e, el)) {
+      const recalled = el.recalledCallIds.has(e.callId) || el.recalledSeqs.has(e.seq);
+      chars += toolResultStub(e.callId, toolResultBytes(e.output), recalled).length;
+      continue;
+    }
+    if ((e.type === 'user_prompt' || e.type === 'assistant_message') && conversationalStubbed(e, el)) {
+      chars += conversationalStub(e.type === 'user_prompt' ? 'user' : 'assistant', e.seq).length;
+      continue;
+    }
+    chars += eventChars(e);
+  }
+  return Math.ceil(chars / 4);
+}
+
+function eventChars(e: MoxxyEvent): number {
+  switch (e.type) {
+    case 'user_prompt':
+      return e.text.length;
+    case 'assistant_message':
+      return e.content.length;
+    case 'tool_call_requested':
+      return e.name.length + safeJsonLen(e.input);
+    case 'tool_result':
+      if (e.error) return (e.error.message?.length ?? 0) + 12;
+      if (typeof e.output === 'string') return e.output.length;
+      return safeJsonLen(e.output);
+    default:
+      return 0;
+  }
+}
+
+function safeJsonLen(v: unknown): number {
+  try {
+    return JSON.stringify(v ?? '').length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Auto-compaction hook every mode calls once per iteration, right
+ * before building messages for the next provider call. Reads the
+ * active model's real `contextWindow` (not a magic max-int sentinel),
+ * estimates current token use, and — if the configured compactor's
+ * `shouldCompact` returns true — runs `compact()` and emits the
+ * resulting CompactionEvent onto the log. `projectMessagesFromLog`
+ * already honors compaction events, so the next provider call sees
+ * the summarized prefix automatically.
+ *
+ * Designed to be tolerant: no compactor, no model descriptor, no
+ * contextWindow, or a compactor throw all degrade to a no-op so a
+ * compactor bug can't kill the turn. Failures emit a non-fatal
+ * `error` event for observability.
+ */
+export async function runCompactionIfNeeded(ctx: ModeContext): Promise<void> {
+  const compactor = ctx.compactor;
+  if (!compactor) return;
+
+  // Resolve the active model's descriptor so we use the *real* context
+  // window. `Number.MAX_SAFE_INTEGER` (the old /compact behavior) made
+  // threshold-based compactors always look comfortable, even at 99%.
+  const descriptor = ctx.provider.models.find((m) => m.id === ctx.model);
+  const contextWindow = descriptor?.contextWindow;
+  if (!contextWindow || contextWindow <= 0) return;
+
+  const events = ctx.log.slice();
+  if (events.length === 0) return;
+
+  const budget = {
+    contextWindow,
+    estimatedTokens: estimateContextTokens(ctx.log),
+    reserveForOutput: descriptor?.maxOutputTokens ?? 0,
+  } as const;
+
+  let shouldRun = false;
+  try {
+    shouldRun = compactor.shouldCompact(ctx.log, budget);
+  } catch (err) {
+    await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: 'retryable',
+      message: `compactor.shouldCompact threw: ${err instanceof Error ? err.message : String(err)}`,
+    });
+    return;
+  }
+  if (!shouldRun) return;
+
+  try {
+    const result = await compactor.compact(events, {
+      log: ctx.log,
+      budget,
+      signal: ctx.signal,
+    });
+    if (result.tokensSaved <= 0 || result.summary.trim().length === 0) return;
+    // `compactor.compact` declares `Omit<CompactionEvent, keyof EventBase>`,
+    // but every shipped compactor (and the SDK examples) fills sessionId /
+    // turnId / source. Defensive-fill from ctx so a compactor that obeyed
+    // the type contract literally still emits a valid event.
+    const emittable: EmittedEvent = {
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'compactor',
+      ...result,
+    } as EmittedEvent;
+    await ctx.emit(emittable);
+  } catch (err) {
+    await ctx.emit({
+      type: 'error',
+      sessionId: ctx.sessionId,
+      turnId: ctx.turnId,
+      source: 'system',
+      kind: 'retryable',
+      message: `compactor.compact threw: ${err instanceof Error ? err.message : String(err)}`,
+    });
+  }
+}