@moxxy/channel-kit 0.27.0

package/src/plain-turn-renderer.ts

@@ -0,0 +1,31 @@
+import type { MoxxyEvent } from '@moxxy/sdk';
+
+/**
+ * Accumulate streamed assistant text from the event log into a single growing
+ * snapshot — the minimal plain-text turn renderer for channels without a rich
+ * frame format (Slack v1 and future thin adapters). `assistant_chunk` deltas
+ * render live; the final `assistant_message` content (which supersedes the
+ * streamed deltas for the same turn) wins so the last edit always carries the
+ * complete reply.
+ */
+export class PlainTurnRenderer {
+  private streamed = '';
+  private finalText: string | null = null;
+
+  /** Returns true when the event changed the snapshot (schedule an edit). */
+  accept(event: MoxxyEvent): boolean {
+    if (event.type === 'assistant_chunk') {
+      this.streamed += event.delta;
+      return true;
+    }
+    if (event.type === 'assistant_message') {
+      this.finalText = event.content;
+      return true;
+    }
+    return false;
+  }
+
+  snapshot(): string {
+    return (this.finalText ?? this.streamed).trim();
+  }
+}

package/src/secrets.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { resolveSecret, type SecretReader } from './secrets.js';
+
+const ENV = 'MOXXY_CHANNEL_KIT_TEST_SECRET';
+
+function vaultWith(values: Record<string, string | null>): SecretReader {
+  return {
+    async get(name) {
+      return values[name] ?? null;
+    },
+  };
+}
+
+describe('resolveSecret', () => {
+  afterEach(() => {
+    delete process.env[ENV];
+  });
+
+  it('prefers the env override', async () => {
+    process.env[ENV] = 'from-env';
+    const got = await resolveSecret(vaultWith({ key: 'from-vault' }), {
+      envVar: ENV,
+      vaultKey: 'key',
+    });
+    expect(got).toBe('from-env');
+  });
+
+  it('trims the env value', async () => {
+    process.env[ENV] = '  padded  ';
+    expect(await resolveSecret(vaultWith({}), { envVar: ENV, vaultKey: 'key' })).toBe('padded');
+  });
+
+  it('falls through to the vault when the env var is unset or whitespace', async () => {
+    expect(
+      await resolveSecret(vaultWith({ key: 'from-vault' }), { envVar: ENV, vaultKey: 'key' }),
+    ).toBe('from-vault');
+
+    process.env[ENV] = '   ';
+    expect(
+      await resolveSecret(vaultWith({ key: 'from-vault' }), { envVar: ENV, vaultKey: 'key' }),
+    ).toBe('from-vault');
+  });
+
+  it('trims the vault value and treats empty as unset', async () => {
+    expect(await resolveSecret(vaultWith({ key: '  v  ' }), { vaultKey: 'key' })).toBe('v');
+    expect(await resolveSecret(vaultWith({ key: '   ' }), { vaultKey: 'key' })).toBeNull();
+  });
+
+  it('returns null when neither source has a value', async () => {
+    expect(await resolveSecret(vaultWith({}), { envVar: ENV, vaultKey: 'key' })).toBeNull();
+  });
+
+  it('skips the env entirely when no envVar is given', async () => {
+    process.env[ENV] = 'should-not-be-read';
+    expect(await resolveSecret(vaultWith({ key: 'from-vault' }), { vaultKey: 'key' })).toBe(
+      'from-vault',
+    );
+  });
+});

package/src/secrets.ts

@@ -0,0 +1,26 @@
+/** The read slice of the vault a channel secret lookup needs. */
+export interface SecretReader {
+  get(name: string): Promise<string | null>;
+}
+
+export interface SecretSpec {
+  /** Env override — beats the vault, matching every channel's precedence. */
+  readonly envVar?: string;
+  /** Vault key the channel stores the secret under. */
+  readonly vaultKey: string;
+}
+
+/**
+ * Resolve a channel secret: env override first, then the vault. Values are
+ * trimmed and empty strings are treated as unset (an env var set to whitespace
+ * falls through to the vault rather than masking it). Returns null when
+ * neither source has a value.
+ */
+export async function resolveSecret(vault: SecretReader, spec: SecretSpec): Promise<string | null> {
+  if (spec.envVar) {
+    const fromEnv = process.env[spec.envVar]?.trim();
+    if (fromEnv) return fromEnv;
+  }
+  const stored = (await vault.get(spec.vaultKey))?.trim();
+  return stored || null;
+}

package/src/turn.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from 'vitest';
+import { asTurnId } from '@moxxy/sdk';
+import type { MoxxyEvent } from '@moxxy/sdk';
+import { TurnCoordinator, driveTurn, subscribeTurn } from './turn.js';
+
+class FakeLog {
+  private readonly subs = new Set<(e: MoxxyEvent) => void>();
+  subscribe(fn: (e: MoxxyEvent) => void): () => void {
+    this.subs.add(fn);
+    return () => this.subs.delete(fn);
+  }
+  emit(e: MoxxyEvent): void {
+    for (const s of this.subs) s(e);
+  }
+}
+
+function chunk(turnId: string, delta: string): MoxxyEvent {
+  return {
+    id: `e_${Math.random()}`,
+    seq: 0,
+    ts: 0,
+    sessionId: 's1',
+    turnId,
+    source: 'model',
+    type: 'assistant_chunk',
+    delta,
+  } as MoxxyEvent;
+}
+
+function message(turnId: string, content: string): MoxxyEvent {
+  return {
+    id: `e_${Math.random()}`,
+    seq: 0,
+    ts: 0,
+    sessionId: 's1',
+    turnId,
+    source: 'model',
+    type: 'assistant_message',
+    content,
+    stopReason: 'end_turn',
+  } as MoxxyEvent;
+}
+
+describe('subscribeTurn', () => {
+  it('delivers only the matching turnId and unsubscribes cleanly', () => {
+    const log = new FakeLog();
+    const seen: string[] = [];
+    const unsubscribe = subscribeTurn({ log }, asTurnId('own'), (e) => {
+      seen.push(e.type === 'assistant_chunk' ? e.delta : '');
+    });
+
+    log.emit(chunk('foreign', 'NOPE'));
+    log.emit(chunk('own', 'a'));
+    log.emit(chunk('own', 'b'));
+    unsubscribe();
+    log.emit(chunk('own', 'after-unsub'));
+
+    expect(seen).toEqual(['a', 'b']);
+  });
+});
+
+describe('driveTurn', () => {
+  it('forwards turnId, model and signal to runTurn and drains the iterator', async () => {
+    const log = new FakeLog();
+    let receivedOpts: Record<string, unknown> | undefined;
+    let drained = 0;
+    const session = {
+      log,
+      runTurn(_prompt: string, opts: Record<string, unknown>) {
+        receivedOpts = opts;
+        return (async function* () {
+          drained += 1;
+          yield message('t1', 'done');
+        })();
+      },
+    };
+    const controller = new AbortController();
+    await driveTurn(session, {
+      turnId: asTurnId('t1'),
+      prompt: 'hi',
+      model: 'model-x',
+      signal: controller.signal,
+    });
+    expect(drained).toBe(1);
+    expect(receivedOpts).toMatchObject({ turnId: 't1', model: 'model-x' });
+    expect(receivedOpts?.['signal']).toBe(controller.signal);
+  });
+
+  it('omits model when not provided', async () => {
+    let receivedOpts: Record<string, unknown> | undefined;
+    const session = {
+      log: new FakeLog(),
+      runTurn(_prompt: string, opts: Record<string, unknown>) {
+        receivedOpts = opts;
+        return (async function* () {
+          // empty turn
+        })();
+      },
+    };
+    await driveTurn(session, {
+      turnId: asTurnId('t2'),
+      prompt: 'hi',
+      signal: new AbortController().signal,
+    });
+    expect(receivedOpts && 'model' in receivedOpts).toBe(false);
+  });
+});
+
+describe('TurnCoordinator', () => {
+  it('grants a single lease at a time (single-flight)', () => {
+    const turns = new TurnCoordinator();
+    const lease = turns.begin(asTurnId('t1'));
+    expect(lease).not.toBeNull();
+    expect(turns.busy).toBe(true);
+    expect(turns.begin(asTurnId('t2'))).toBeNull();
+
+    lease?.end();
+    expect(turns.busy).toBe(false);
+    expect(turns.begin(asTurnId('t3'))).not.toBeNull();
+  });
+
+  it('exposes the in-flight controller and aborts it on demand', () => {
+    const turns = new TurnCoordinator();
+    expect(turns.controller).toBeNull();
+    turns.abort('noop'); // idle abort is a no-op
+
+    const lease = turns.begin(asTurnId('t1'));
+    expect(turns.controller).toBe(lease?.controller);
+    turns.abort('shutdown');
+    expect(lease?.controller.signal.aborted).toBe(true);
+
+    lease?.end();
+    expect(turns.controller).toBeNull();
+  });
+
+  it('remembers own turnIds beyond the lease (bounded)', () => {
+    const turns = new TurnCoordinator({ maxOwnTurnIds: 2 });
+    turns.begin(asTurnId('t1'))?.end();
+    turns.begin(asTurnId('t2'))?.end();
+    expect(turns.isOwn('t1')).toBe(true);
+    expect(turns.isOwn('t2')).toBe(true);
+    turns.begin(asTurnId('t3'))?.end();
+    // Oldest evicted once the cap is exceeded.
+    expect(turns.isOwn('t1')).toBe(false);
+    expect(turns.isOwn('t3')).toBe(true);
+  });
+
+  it('mirrorText passes only foreign assistant prose while idle', () => {
+    const turns = new TurnCoordinator();
+    const lease = turns.begin(asTurnId('own'));
+
+    // Own turn: never mirrored, even after the lease ends (invariant #8 —
+    // late/replayed events must not be re-mirrored as foreign).
+    expect(turns.mirrorText(message('own', 'mine'))).toBeNull();
+    // Busy: a foreign turn is not mirrored while we render our own.
+    expect(turns.mirrorText(message('foreign', 'other'))).toBeNull();
+
+    lease?.end();
+    expect(turns.mirrorText(message('own', 'mine'))).toBeNull();
+    expect(turns.mirrorText(message('foreign', 'other'))).toBe('other');
+    // Non-message events and empty content are ignored.
+    expect(turns.mirrorText(chunk('foreign', 'delta'))).toBeNull();
+    expect(turns.mirrorText(message('foreign', '   '))).toBeNull();
+  });
+});

package/src/turn.ts

@@ -0,0 +1,162 @@
+import type { MoxxyEvent, RunTurnOptions, TurnId } from '@moxxy/sdk';
+
+/**
+ * Turn machinery shared by messaging channels that multiplex onto ONE shared
+ * Session (AGENTS.md invariant #8: filter event-log subscribers by turnId —
+ * `session.log` fans out to every listener, so concurrent turns on the same
+ * Session cross-contaminate without it).
+ *
+ * Pieces are deliberately composable rather than one monolithic runner so each
+ * channel keeps its exact flush / typing / unwind ordering:
+ *   - {@link TurnCoordinator} — single-flight `busy` guard, per-turn
+ *     AbortController, bounded own-turn-id tracking, foreign-turn mirror gate.
+ *   - {@link subscribeTurn} — turnId-filtered `session.log.subscribe`.
+ *   - {@link driveTurn} — drain `session.runTurn` for a pre-minted turnId.
+ */
+
+/** The slice of a session a channel turn needs: the live event log. */
+export interface TurnEventSource {
+  readonly log: {
+    subscribe(fn: (event: MoxxyEvent) => void | Promise<void>): () => void;
+  };
+}
+
+/** The slice of a session `driveTurn` needs. `ClientSession` satisfies it. */
+export interface TurnSession extends TurnEventSource {
+  runTurn(prompt: string, opts?: RunTurnOptions): AsyncIterable<MoxxyEvent>;
+}
+
+/**
+ * Subscribe to ONLY the given turn's events. Returns the unsubscribe function.
+ * The caller controls unsubscribe placement (channels keep their final flush
+ * inside the subscription window so trailing events still feed the renderer).
+ */
+export function subscribeTurn(
+  source: TurnEventSource,
+  turnId: TurnId,
+  onEvent: (event: MoxxyEvent) => void,
+): () => void {
+  return source.log.subscribe((event) => {
+    if (event.turnId !== turnId) return;
+    onEvent(event);
+  });
+}
+
+export interface DriveTurnOptions {
+  readonly turnId: TurnId;
+  readonly prompt: string;
+  readonly model?: string | undefined;
+  readonly signal: AbortSignal;
+}
+
+/**
+ * Run one turn to completion, draining the `runTurn` iterator. Rendering is
+ * expected to happen via a {@link subscribeTurn} subscription, not the yielded
+ * events (which are identical); errors propagate to the caller.
+ */
+export async function driveTurn(session: TurnSession, opts: DriveTurnOptions): Promise<void> {
+  for await (const _event of session.runTurn(opts.prompt, {
+    turnId: opts.turnId,
+    ...(opts.model ? { model: opts.model } : {}),
+    signal: opts.signal,
+  })) {
+    void _event;
+  }
+}
+
+/** A granted turn slot. Call `end()` in a `finally` to release single-flight. */
+export interface TurnLease {
+  readonly turnId: TurnId;
+  /** Per-turn controller so a /cancel or channel stop aborts ONLY this turn
+   *  without poisoning the session-level signal other channels share. */
+  readonly controller: AbortController;
+  end(): void;
+}
+
+export interface TurnCoordinatorOptions {
+  /**
+   * Bound on remembered own-turn ids so a long-lived channel can't leak; a
+   * handful of recent ids is enough to dedup late/replayed events. Default 64.
+   */
+  readonly maxOwnTurnIds?: number;
+}
+
+/**
+ * Single-flight turn state for a channel: one turn at a time, a per-turn
+ * AbortController, and a bounded set of turnIds THIS channel initiated.
+ *
+ * The own-turn-id set is what {@link mirrorText} filters on (invariant #8)
+ * rather than the coarse `busy` flag alone — so an `assistant_message`
+ * dispatched for our own turn AFTER `busy` flips false (async event ordering /
+ * RemoteSession replay) isn't re-mirrored as foreign.
+ */
+export class TurnCoordinator {
+  private busyFlag = false;
+  private active: AbortController | null = null;
+  private readonly ownTurnIds = new Set<string>();
+  private readonly maxOwnTurnIds: number;
+
+  constructor(opts: TurnCoordinatorOptions = {}) {
+    this.maxOwnTurnIds = opts.maxOwnTurnIds ?? 64;
+  }
+
+  get busy(): boolean {
+    return this.busyFlag;
+  }
+
+  /** The in-flight turn's controller (null when idle) — for /cancel handlers. */
+  get controller(): AbortController | null {
+    return this.active;
+  }
+
+  /**
+   * Atomically claim the single turn slot. Synchronous on purpose: set `busy`
+   * BEFORE any await so a concurrently dispatched second turn can't slip past
+   * the guard. Returns null when a turn is already running (the channel replies
+   * "still working"); otherwise a lease whose `end()` releases the slot.
+   */
+  begin(turnId: TurnId): TurnLease | null {
+    if (this.busyFlag) return null;
+    this.busyFlag = true;
+    const controller = new AbortController();
+    this.active = controller;
+    this.ownTurnIds.add(turnId);
+    if (this.ownTurnIds.size > this.maxOwnTurnIds) {
+      const oldest = this.ownTurnIds.values().next().value;
+      if (oldest !== undefined) this.ownTurnIds.delete(oldest);
+    }
+    return {
+      turnId,
+      controller,
+      end: () => {
+        this.busyFlag = false;
+        if (this.active === controller) this.active = null;
+      },
+    };
+  }
+
+  /** Abort the in-flight turn (stop / cancel paths). No-op when idle. */
+  abort(reason: string): void {
+    if (this.active && !this.active.signal.aborted) this.active.abort(reason);
+  }
+
+  isOwn(turnId: string): boolean {
+    return this.ownTurnIds.has(turnId);
+  }
+
+  /**
+   * Foreign-turn mirror gate: returns the assistant prose to mirror for a turn
+   * this channel did NOT initiate (e.g. a co-attached surface ran one), or null
+   * when the event must not be mirrored — not an `assistant_message`, one of
+   * our own turnIds (invariant #8), a turn of ours currently rendering via the
+   * frame pump (`busy`), or empty content. The channel adds its own
+   * "have I served a target yet" check and does the send.
+   */
+  mirrorText(event: MoxxyEvent): string | null {
+    if (event.type !== 'assistant_message') return null;
+    if (this.ownTurnIds.has(event.turnId)) return null;
+    if (this.busyFlag) return null;
+    const text = event.content.trim();
+    return text ? text : null;
+  }
+}