@moxxy/plugin-channel-http 0.26.0

package/src/channel.test.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Server } from 'node:http';
+import { z } from 'zod';
+import {
+  Session,
+  autoAllowResolver,
+  silentLogger,
+} from '@moxxy/core';
+import { defineProvider, definePlugin, defineTool } from '@moxxy/sdk';
+import type { LLMProvider, ProviderEvent } from '@moxxy/sdk';
+import { HttpChannel } from './channel.js';
+
+class FakeProvider implements LLMProvider {
+  readonly name = 'fake';
+  readonly models = [{ id: 'fake', contextWindow: 1000, maxOutputTokens: 100, supportsTools: false, supportsStreaming: true }];
+  constructor(private readonly scripts: ReadonlyArray<ReadonlyArray<ProviderEvent>>) {}
+  private cursor = 0;
+  async *stream(): AsyncIterable<ProviderEvent> {
+    const reply = this.scripts[this.cursor++];
+    if (!reply) throw new Error('out of fake replies');
+    for (const e of reply) yield e;
+  }
+  async countTokens(): Promise<number> { return 0; }
+}
+
+function buildSession(): Session {
+  const provider = new FakeProvider([
+    [
+      { type: 'message_start', model: 'fake' },
+      { type: 'text_delta', delta: 'pong' },
+      { type: 'message_end', stopReason: 'end_turn' },
+    ],
+  ]);
+  const session = new Session({
+    cwd: process.cwd(),
+    logger: silentLogger,
+    permissionResolver: autoAllowResolver,
+  });
+  session.pluginHost.registerStatic(
+    definePlugin({
+      name: 'http-test-shim',
+      providers: [
+        defineProvider({
+          name: provider.name,
+          models: [...provider.models],
+          createClient: () => provider,
+        }),
+      ],
+      tools: [
+        defineTool({
+          name: 'noop',
+          description: 'no-op',
+          inputSchema: z.object({}),
+          handler: () => null,
+        }),
+      ],
+    }),
+  );
+  session.providers.setActive(provider.name);
+  // Register a minimal loop strategy so runTurn works.
+  // Easier: register the default loop-tool-use plugin if it's available.
+  return session;
+}
+
+describe('HttpChannel', () => {
+  it('starts and stops cleanly on an ephemeral port', async () => {
+    const channel = new HttpChannel({ port: 0, authToken: 'test', allowedTools: ['noop'] });
+    expect(channel.name).toBe('http');
+    expect(channel.permissionResolver.name).toBe('allow-list');
+    // Don't actually start (would require a loop strategy registered).
+    // Just verify the channel object shape.
+  });
+
+  it('defaults to deny-by-default resolver when no allow-list given', () => {
+    const channel = new HttpChannel({ authToken: 'test' });
+    expect(channel.permissionResolver.name).toBe('deny-by-default');
+  });
+
+  // Note: full request/response is exercised through the router-level tests.
+  // Verifying the server boots and binds is enough at this level.
+  void buildSession;
+
+  it('rejects the running promise + logs when the server errors after listen (u70-2)', async () => {
+    const warn = vi.fn();
+    const channel = new HttpChannel({
+      port: 0,
+      authToken: 'test',
+      allowedTools: ['noop'],
+      logger: { info: () => {}, warn },
+    });
+    const session = new Session({
+      cwd: process.cwd(),
+      logger: silentLogger,
+      permissionResolver: autoAllowResolver,
+    });
+    const handle = await channel.start({ session } as never);
+    expect(channel.boundPort).toBeGreaterThan(0);
+
+    // Reach the bound server (private) to emit a synthetic runtime error — the
+    // same surface a real post-listen socket failure would hit.
+    const server = (channel as unknown as { server: Server }).server;
+    const boom = new Error('socket exploded');
+    queueMicrotask(() => server.emit('error', boom));
+
+    await expect(handle.running).rejects.toThrow('socket exploded');
+    expect(warn).toHaveBeenCalledWith('http server error', expect.objectContaining({}));
+    await handle.stop();
+  });
+
+  it('refuses to bind a non-loopback host with no authToken', async () => {
+    const channel = new HttpChannel({ port: 0, host: '0.0.0.0', allowedTools: ['noop'] });
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger, permissionResolver: autoAllowResolver });
+    await expect(channel.start({ session } as never)).rejects.toThrow(/non-loopback/);
+    expect(channel.boundPort).toBe(0);
+  });
+
+  it('allows a non-loopback bind once an authToken is set', async () => {
+    const channel = new HttpChannel({ port: 0, host: '0.0.0.0', authToken: 'tok', allowedTools: ['noop'], logger: { info: () => {}, warn: () => {} } });
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger, permissionResolver: autoAllowResolver });
+    const handle = await channel.start({ session } as never);
+    expect(channel.boundPort).toBeGreaterThan(0);
+    await handle.stop();
+  });
+
+  it('a post-listen server error does not escalate to an unhandledRejection when running is unobserved', async () => {
+    const channel = new HttpChannel({ port: 0, authToken: 'test', allowedTools: ['noop'], logger: { info: () => {}, warn: () => {} } });
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger, permissionResolver: autoAllowResolver });
+    const handle = await channel.start({ session } as never);
+
+    let unhandled: unknown;
+    const onUnhandled = (reason: unknown): void => { unhandled = reason; };
+    process.on('unhandledRejection', onUnhandled);
+    try {
+      const server = (channel as unknown as { server: Server }).server;
+      // Intentionally do NOT await handle.running (fire-and-forget caller).
+      server.emit('error', new Error('boom'));
+      // Let the microtask/macrotask queue flush so any unhandled rejection fires.
+      await new Promise((r) => setTimeout(r, 10));
+      expect(unhandled).toBeUndefined();
+    } finally {
+      process.off('unhandledRejection', onUnhandled);
+      await handle.stop();
+    }
+  });
+
+  it('rejects a double start, and allows a fresh start after stop (u70-5)', async () => {
+    const channel = new HttpChannel({ port: 0, authToken: 'test', allowedTools: ['noop'], logger: { info: () => {}, warn: () => {} } });
+    const session = new Session({ cwd: process.cwd(), logger: silentLogger, permissionResolver: autoAllowResolver });
+
+    const handle = await channel.start({ session } as never);
+    expect(channel.boundPort).toBeGreaterThan(0);
+
+    // A second start while running must not silently orphan the first server.
+    await expect(channel.start({ session } as never)).rejects.toThrow(/already started/);
+
+    // After stop(), the handle is cleared and the port no longer considered held.
+    await handle.stop();
+    expect(channel.boundPort).toBe(0);
+
+    // A fresh start now succeeds (no leaked handle blocking it).
+    const handle2 = await channel.start({ session } as never);
+    expect(channel.boundPort).toBeGreaterThan(0);
+    await handle2.stop();
+  });
+});

package/src/channel.ts

@@ -0,0 +1,211 @@
+import { createServer, type Server } from 'node:http';
+import { createAllowListResolver, denyByDefaultResolver } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type {
+  Channel,
+  ChannelHandle,
+  ChannelStartOptsBase,
+  PermissionResolver,
+} from '@moxxy/sdk';
+import { routeRequest, TurnLimiter, type RouterContext } from './router.js';
+
+/** Hosts auth-disabled mode is only safe to bind on. A non-loopback bind with
+ *  no token would expose an unauthenticated agent endpoint to the network. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost', '::ffff:127.0.0.1']);
+
+export interface HttpChannelOptions {
+  readonly port?: number;
+  readonly host?: string;
+  /** Bearer token required on every protected route. If unset, auth is disabled (dev-only). */
+  readonly authToken?: string;
+  /** Max turns running concurrently on the shared session; excess requests get
+   *  a 429. Bounds provider-stream fan-out and history interleaving. */
+  readonly maxConcurrentTurns?: number;
+  /** Abort an SSE turn whose consumer has stalled (socket open but not reading)
+   *  for this many ms, so a half-open client can't keep a provider stream alive
+   *  forever. A live-but-slow consumer resets the timer on every flushed write.
+   *  Defaults to 120_000; set <= 0 to disable (not recommended for a network
+   *  bind). */
+  readonly streamStallMs?: number;
+  /**
+   * Tool names that the model is allowed to call without further interaction.
+   * This is the entire permission story for HTTP — there's no human in the
+   * loop to click "allow", so the operator declares trust upfront. Anything
+   * not in this list is denied.
+   */
+  readonly allowedTools?: ReadonlyArray<string>;
+  readonly logger?: {
+    info?(msg: string, meta?: Record<string, unknown>): void;
+    warn?(msg: string, meta?: Record<string, unknown>): void;
+  };
+}
+
+export interface HttpStartOpts extends ChannelStartOptsBase {
+  readonly session: Session;
+}
+
+export class HttpChannel implements Channel<HttpStartOpts> {
+  readonly name = 'http';
+  readonly permissionResolver: PermissionResolver;
+  private readonly port: number;
+  private readonly host: string;
+  private readonly authToken: string | null;
+  private readonly maxConcurrentTurns: number;
+  private readonly streamStallMs: number | undefined;
+  private readonly logger: HttpChannelOptions['logger'];
+  private server: Server | null = null;
+  private boundPortValue = 0;
+
+  /** The actual TCP port the server bound to after {@link start}. Equals the
+   *  configured port, or the OS-assigned one when `port: 0` (ephemeral) — so
+   *  callers (and tests) can address the server without guessing a free port. */
+  get boundPort(): number {
+    return this.boundPortValue;
+  }
+
+  constructor(opts: HttpChannelOptions = {}) {
+    this.port = opts.port ?? 3737;
+    this.host = opts.host ?? '127.0.0.1';
+    this.authToken = opts.authToken ?? null;
+    this.maxConcurrentTurns =
+      typeof opts.maxConcurrentTurns === 'number' && opts.maxConcurrentTurns > 0
+        ? Math.floor(opts.maxConcurrentTurns)
+        : 4;
+    // undefined => router uses its DEFAULT_STREAM_STALL_MS; a finite number
+    // (including <= 0 to disable) is honored as-is.
+    this.streamStallMs =
+      typeof opts.streamStallMs === 'number' && Number.isFinite(opts.streamStallMs)
+        ? opts.streamStallMs
+        : undefined;
+    this.logger = opts.logger;
+    this.permissionResolver = opts.allowedTools && opts.allowedTools.length > 0
+      ? createAllowListResolver([...opts.allowedTools])
+      : denyByDefaultResolver;
+  }
+
+  async start(startOpts: HttpStartOpts): Promise<ChannelHandle> {
+    // Guard against a double-start: unconditionally reassigning `this.server`
+    // would orphan the first server (its port stays bound, sockets stay open)
+    // since `stop()` only ever closes the most-recently-assigned one.
+    if (this.server) {
+      throw new Error('HttpChannel is already started — call stop() before starting again.');
+    }
+
+    // Refuse to expose an unauthenticated agent endpoint to the network. With
+    // no token the only gate is the deny-by-default tool resolver; a
+    // non-loopback bind would still let anyone reach /v1/turn.
+    if (this.authToken === null && !LOOPBACK_HOSTS.has(this.host)) {
+      throw new Error(
+        `HttpChannel refuses to bind non-loopback host "${this.host}" without an authToken. ` +
+          'Set authToken (or MOXXY_HTTP_TOKEN), or bind 127.0.0.1.',
+      );
+    }
+
+    const ctx: RouterContext = {
+      session: startOpts.session,
+      authToken: this.authToken,
+      logger: this.logger as RouterContext['logger'],
+      turnLimiter: new TurnLimiter(this.maxConcurrentTurns),
+      ...(this.streamStallMs !== undefined ? { streamStallMs: this.streamStallMs } : {}),
+    };
+
+    const server = createServer(async (req, res) => {
+      const handler = routeRequest(req);
+      if (!handler) {
+        res.writeHead(404, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'not_found', path: req.url }));
+        return;
+      }
+      try {
+        await handler(req, res, ctx);
+      } catch (err) {
+        // Log the full error server-side; return a generic message so internal
+        // paths/provider details can't leak to a (possibly remote) caller.
+        this.logger?.warn?.('http handler threw', { err: String(err) });
+        if (!res.headersSent) {
+          res.writeHead(500, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'internal' }));
+        } else {
+          try { res.end(); } catch { /* ignore */ }
+        }
+      }
+    });
+
+    // Tighten timeouts so a slow-loris client can't tie up sockets by dribbling
+    // headers/bodies. Defaults (requestTimeout 300s) are too generous for an
+    // agent endpoint. Cap total connections so a flood can't exhaust handles.
+    server.headersTimeout = 10_000;
+    server.requestTimeout = 30_000;
+    server.keepAliveTimeout = 5_000;
+    server.maxConnections = 256;
+
+    this.server = server;
+
+    // `running` rejects on a post-listen server error and resolves on a clean
+    // close. Declared up front so the persistent error handler installed below
+    // (after the listen-scoped one is detached) can settle it.
+    let rejectRunning!: (err: unknown) => void;
+    let resolveRunning!: () => void;
+    const running = new Promise<void>((resolve, reject) => {
+      resolveRunning = resolve;
+      rejectRunning = reject;
+    });
+    // A fire-and-forget caller may never attach a .catch; without this default
+    // observer a post-listen server error escalates to a process-level
+    // unhandledRejection (fatal under --unhandled-rejections=strict). Real
+    // awaiters still see the rejection — a settled promise fans out to all.
+    running.catch(() => {});
+
+    const listening = new Promise<void>((resolve, reject) => {
+      // Scoped to the listen handshake only — detached once we're listening so
+      // it can't no-op on the already-settled promise (and swallow runtime
+      // errors). The persistent handler below takes over afterwards.
+      const onListenError = (err: unknown): void => reject(err);
+      server.once('error', onListenError);
+      server.listen(this.port, this.host, () => {
+        server.off('error', onListenError);
+        // A runtime server error after listen would otherwise be unhandled
+        // (Node re-throws an 'error' with no listener). Log it and fail the
+        // `running` promise so callers awaiting it observe the crash instead of
+        // mistaking it for a clean shutdown.
+        server.on('error', (err: unknown) => {
+          this.logger?.warn?.('http server error', { err: String(err) });
+          rejectRunning(err);
+        });
+        const addr = server.address();
+        this.boundPortValue = typeof addr === 'object' && addr ? addr.port : this.port;
+        this.logger?.info?.('http channel listening', {
+          host: this.host,
+          port: this.boundPortValue,
+          authEnabled: this.authToken !== null,
+        });
+        resolve();
+      });
+    });
+
+    await listening;
+
+    server.once('close', () => resolveRunning());
+
+    return {
+      running,
+      stop: async () => {
+        const srv = this.server;
+        // Clear the handle first so a concurrent/double stop() is a no-op rather
+        // than racing two close() calls on the same server (the second close
+        // gets an 'ERR_SERVER_NOT_RUNNING' error in its callback).
+        if (this.server === srv) {
+          this.server = null;
+          this.boundPortValue = 0;
+        }
+        await new Promise<void>((resolve) => {
+          if (!srv) return resolve();
+          srv.close((err) => {
+            if (err) this.logger?.warn?.('http server close error', { err: String(err) });
+            resolve();
+          });
+        });
+      },
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+import { defineChannel, definePlugin, type Plugin } from '@moxxy/sdk';
+import { HttpChannel } from './channel.js';
+
+export { HttpChannel, type HttpChannelOptions, type HttpStartOpts } from './channel.js';
+export {
+  routeRequest,
+  handleHealth,
+  handleTurn,
+  handleTurnStream,
+  handleTurnAudio,
+  turnRequestSchema,
+  type TurnRequest,
+  type RouterContext,
+  type RouteHandler,
+} from './router.js';
+
+export const httpChannelDef = defineChannel({
+  name: 'http',
+  description: 'Request-response HTTP channel. POST /v1/turn + SSE streaming. Bearer-token auth + allow-list perms.',
+  create: (deps) => {
+    const opts = deps.options ?? {};
+    return new HttpChannel({
+      port: typeof opts.port === 'number' ? opts.port : undefined,
+      host: typeof opts.host === 'string' ? opts.host : undefined,
+      authToken: typeof opts.authToken === 'string' ? opts.authToken : process.env.MOXXY_HTTP_TOKEN,
+      allowedTools: Array.isArray(opts.allowedTools) ? (opts.allowedTools as string[]) : undefined,
+      maxConcurrentTurns: typeof opts.maxConcurrentTurns === 'number' ? opts.maxConcurrentTurns : undefined,
+      streamStallMs: typeof opts.streamStallMs === 'number' ? opts.streamStallMs : undefined,
+      logger: deps.logger as never,
+    });
+  },
+  isAvailable: async (deps) => {
+    const tools = deps.options?.['allowedTools'];
+    const authToken = deps.options?.['authToken'] ?? process.env.MOXXY_HTTP_TOKEN;
+    if (!authToken) {
+      return {
+        ok: false,
+        reason: "No auth token. Set MOXXY_HTTP_TOKEN or pass channels.http.authToken in moxxy.config.ts.",
+      };
+    }
+    if (!Array.isArray(tools) || tools.length === 0) {
+      return {
+        ok: false,
+        reason:
+          'No allowed-tools list. The HTTP channel needs an upfront tool allow-list since there is no human in the loop. Set channels.http.allowedTools in moxxy.config.ts.',
+      };
+    }
+    return { ok: true };
+  },
+});
+
+export const httpChannelPlugin: Plugin = definePlugin({
+  name: '@moxxy/plugin-channel-http',
+  version: '0.0.0',
+  channels: [httpChannelDef],
+});
+
+export default httpChannelPlugin;

package/src/integration.test.ts

@@ -0,0 +1,254 @@
+/**
+ * End-to-end integration test. Boots a real HttpChannel on an ephemeral port
+ * against a Session wired with FakeProvider + tool-use loop, then drives
+ * actual HTTP requests via fetch.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+  Session,
+  autoAllowResolver,
+  silentLogger,
+} from '@moxxy/core';
+import { defineProvider, definePlugin, defineTranscriber } from '@moxxy/sdk';
+import { FakeProvider, textReply } from '@moxxy/testing';
+import { defaultModePlugin } from '@moxxy/mode-default';
+import { builtinToolsPlugin } from '@moxxy/tools-builtin';
+import { HttpChannel } from './channel.js';
+import type { ChannelHandle } from '@moxxy/sdk';
+
+const TOKEN = 'test-token-123';
+
+function buildSession(opts: { withTranscriber?: string } = {}): Session {
+  const provider = new FakeProvider({
+    script: [textReply('hello from the HTTP channel')],
+  });
+  const session = new Session({
+    cwd: process.cwd(),
+    logger: silentLogger,
+    permissionResolver: autoAllowResolver,
+  });
+  const plugins = [
+    definePlugin({
+      name: 'http-integration-shim',
+      providers: [
+        defineProvider({
+          name: provider.name,
+          models: [...provider.models],
+          createClient: () => provider,
+        }),
+      ],
+      ...(opts.withTranscriber !== undefined
+        ? {
+            transcribers: [
+              defineTranscriber({
+                name: 'fake-stt',
+                createClient: () => ({
+                  name: 'fake-stt',
+                  transcribe: async () => ({ text: opts.withTranscriber! }),
+                }),
+              }),
+            ],
+          }
+        : {}),
+    }),
+  ];
+  for (const p of plugins) session.pluginHost.registerStatic(p);
+  session.providers.setActive(provider.name);
+  if (opts.withTranscriber !== undefined) session.transcribers.setActive('fake-stt');
+  session.pluginHost.registerStatic(builtinToolsPlugin);
+  session.pluginHost.registerStatic(defaultModePlugin);
+  return session;
+}
+
+async function startChannel(channel: HttpChannel): Promise<{ baseUrl: string; handle: ChannelHandle }> {
+  // The channel was created with port: 0 — the OS assigns a free ephemeral port,
+  // read back from `boundPort`. No random-port guessing, so no EADDRINUSE flake
+  // when test files run in parallel.
+  const handle = await channel.start({ session: buildSession() });
+  return { baseUrl: `http://127.0.0.1:${channel.boundPort}`, handle };
+}
+
+let channel: HttpChannel;
+let handle: ChannelHandle;
+let baseUrl: string;
+
+beforeEach(async () => {
+  channel = new HttpChannel({
+    port: 0,
+    authToken: TOKEN,
+    allowedTools: ['Read', 'Glob'],
+  });
+  const started = await startChannel(channel);
+  baseUrl = started.baseUrl;
+  handle = started.handle;
+});
+
+afterEach(async () => {
+  await handle.stop();
+});
+
+describe('HttpChannel integration', () => {
+  it('GET /v1/health returns 200 ok without auth', async () => {
+    const res = await fetch(`${baseUrl}/v1/health`);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: 'ok' });
+  });
+
+  it('POST /v1/turn rejects missing Bearer token with 401', async () => {
+    const res = await fetch(`${baseUrl}/v1/turn`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ prompt: 'hi' }),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it('POST /v1/turn rejects wrong Bearer token with 401', async () => {
+    const res = await fetch(`${baseUrl}/v1/turn`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: 'Bearer wrong-token',
+      },
+      body: JSON.stringify({ prompt: 'hi' }),
+    });
+    expect(res.status).toBe(401);
+  });
+
+  it('POST /v1/turn rejects malformed body with 400', async () => {
+    const res = await fetch(`${baseUrl}/v1/turn`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${TOKEN}`,
+      },
+      body: '{"not-prompt": 1}',
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it('POST /v1/turn drives a full turn and returns events + assistant text', async () => {
+    const res = await fetch(`${baseUrl}/v1/turn`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${TOKEN}`,
+      },
+      body: JSON.stringify({ prompt: 'say hi' }),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { events: Array<{ type: string }>; assistant: string };
+    expect(body.assistant).toContain('hello from the HTTP channel');
+    expect(body.events.some((e) => e.type === 'user_prompt')).toBe(true);
+    expect(body.events.some((e) => e.type === 'assistant_message')).toBe(true);
+  });
+
+  it('POST /v1/turn/stream returns Server-Sent Events with [DONE] terminator', async () => {
+    const res = await fetch(`${baseUrl}/v1/turn/stream`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${TOKEN}`,
+      },
+      body: JSON.stringify({ prompt: 'say hi' }),
+    });
+    expect(res.status).toBe(200);
+    expect(res.headers.get('content-type')).toContain('text/event-stream');
+    const text = await res.text();
+    expect(text).toContain('data: ');
+    expect(text).toMatch(/data: \[DONE\]\n\n$/);
+    // Each event is a JSON object — find the user_prompt one
+    const lines = text.split('\n\n').filter((l) => l.startsWith('data: '));
+    const parsed = lines
+      .map((l) => l.slice(6))
+      .filter((s) => s !== '[DONE]')
+      .map((s) => JSON.parse(s) as { type: string });
+    expect(parsed.some((e) => e.type === 'user_prompt')).toBe(true);
+    expect(parsed.some((e) => e.type === 'assistant_chunk')).toBe(true);
+  });
+
+  it('GET on an unknown path returns 404', async () => {
+    const res = await fetch(`${baseUrl}/nonsense`);
+    expect(res.status).toBe(404);
+  });
+});
+
+describe('HttpChannel /v1/turn/audio integration', () => {
+  let audioChannel: HttpChannel;
+  let audioHandle: ChannelHandle;
+  let audioBaseUrl: string;
+
+  beforeEach(async () => {
+    audioChannel = new HttpChannel({
+      port: 0,
+      host: '127.0.0.1',
+      authToken: TOKEN,
+      allowedTools: ['Read', 'Glob'],
+    });
+    audioHandle = await audioChannel.start({
+      session: buildSession({ withTranscriber: 'transcribed voice content' }),
+    });
+    audioBaseUrl = `http://127.0.0.1:${audioChannel.boundPort}`;
+  });
+
+  afterEach(async () => {
+    await audioHandle.stop();
+  });
+
+  it('POST /v1/turn/audio transcribes the body and runs a full turn', async () => {
+    const oggBytes = new Uint8Array([0x4f, 0x67, 0x67, 0x53]); // "OggS"
+    const res = await fetch(`${audioBaseUrl}/v1/turn/audio`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'audio/ogg',
+        authorization: `Bearer ${TOKEN}`,
+      },
+      body: oggBytes,
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      transcript: string;
+      assistant: string;
+      events: Array<{ type: string }>;
+    };
+    expect(body.transcript).toBe('transcribed voice content');
+    expect(body.assistant).toContain('hello from the HTTP channel');
+    expect(body.events.some((e) => e.type === 'user_prompt')).toBe(true);
+    expect(body.events.some((e) => e.type === 'assistant_message')).toBe(true);
+  });
+
+  it('POST /v1/turn/audio rejects non-audio Content-Type with 415', async () => {
+    const res = await fetch(`${audioBaseUrl}/v1/turn/audio`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/octet-stream',
+        authorization: `Bearer ${TOKEN}`,
+      },
+      body: 'bytes',
+    });
+    expect(res.status).toBe(415);
+  });
+});
+
+describe('HttpChannel auth-disabled mode', () => {
+  it('without authToken, /v1/turn does not require Bearer header', async () => {
+    const open = new HttpChannel({
+      port: 0,
+      allowedTools: ['Read'],
+    });
+    const port = 50000 + Math.floor(Math.random() * 10000);
+    const real = new HttpChannel({ port, allowedTools: ['Read'] });
+    Object.assign(open, real);
+    const openHandle = await open.start({ session: buildSession() });
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/v1/turn`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ prompt: 'hi' }),
+      });
+      expect(res.status).toBe(200);
+    } finally {
+      await openHandle.stop();
+    }
+  });
+});