@rcrsr/rill-agent-chat 0.20.0

package/README.md

@@ -0,0 +1,53 @@
+# @rcrsr/rill-agent-chat
+
+OpenAI-compatible chat completions harness for [`@rcrsr/rill-agent`](https://www.npmjs.com/package/@rcrsr/rill-agent). Wraps an `AgentRouter` in a Hono server that speaks the OpenAI Chat Completions wire format over Server-Sent Events (SSE). Stateless and provider-independent — no Azure or vendor SDK at runtime. Consumable by the openai SDK, LiteLLM, the Vercel AI SDK, and any HTTP client.
+
+## Install
+
+```bash
+npm install @rcrsr/rill-agent @rcrsr/rill-agent-chat
+```
+
+## Quick Start
+
+```typescript
+import { loadManifest, createRouter } from '@rcrsr/rill-agent';
+import { createChatHarness } from '@rcrsr/rill-agent-chat';
+
+const manifest = await loadManifest('./build');
+const router = await createRouter(manifest);
+
+const harness = createChatHarness(router);
+await harness.listen(3000);
+```
+
+An agent is chat-eligible when its handler returns a stream of OpenAI-shaped chunks. See [the reference](docs/agent-chat.md) for the handler contract and `inspectChatHandler`.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/v1/chat/completions` | OpenAI-compatible; the `model` field selects the agent |
+| `POST` | `/agents/:name/chat` | Per-agent chat |
+| `POST` | `/chat` | Default agent chat |
+| `GET` | `/agents` | List chat-eligible agents |
+| `GET` | `/health` | Liveness (always on) |
+| `GET` | `/metrics` | Request counters (always on) |
+
+Request and response bodies follow the OpenAI Chat Completions format. Set `"stream": true` for an SSE stream of `chat.completion.chunk` events. Toggle the first four routes via `options.routes`.
+
+## API
+
+- `createChatHarness(router, options?)` — returns a `ChatHarness` (`{ app, listen(port), close() }`)
+- `inspectChatHandler(handler)` — reports whether a handler is chat-eligible
+- `validateMessages(messages)` — validates an incoming messages array
+
+The default export is a `RillHarness` adapter consumed by the rill CLI bundle mode (`rill run`) when this package is declared as a bundle harness.
+
+## Documentation
+
+- [Reference](docs/agent-chat.md) — routes, options, the handler contract, streaming, and error shapes
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,222 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { Hono } from 'hono';
+
+export interface HandlerDescription {
+	readonly name: string;
+	readonly description?: string | undefined;
+	readonly params: ReadonlyArray<{
+		readonly name: string;
+		readonly type: string;
+		readonly required: boolean;
+		readonly description?: string | undefined;
+		readonly defaultValue?: unknown;
+	}>;
+	/**
+	 * Handler return type annotation, formatted with the same grammar as
+	 * parameter type strings (e.g. `stream(dict(content: string)):string`).
+	 * Undefined when the handler closure has no `:T` annotation, or when the
+	 * rill-build emitting the handler is too old to expose the field.
+	 */
+	readonly returnType?: string | undefined;
+}
+export interface InitContext {
+	readonly globalVars?: Record<string, string> | undefined;
+	readonly ahiResolver?: ((agentName: string, request: RunRequest) => Promise<RunResponse>) | undefined;
+}
+export interface RunRequest {
+	readonly params?: Record<string, unknown> | undefined;
+	readonly timeout?: number | undefined;
+}
+export interface RunContext {
+	readonly sessionVars?: Record<string, string> | undefined;
+	readonly onLog?: ((message: string) => void) | undefined;
+	readonly onChunk?: ((chunk: unknown) => Promise<void>) | undefined;
+	readonly signal?: AbortSignal | undefined;
+}
+export interface RunResponse {
+	readonly state: "completed" | "error";
+	readonly result: unknown;
+	readonly streamed?: boolean | undefined;
+}
+export interface AgentHandler {
+	describe(): HandlerDescription | null;
+	init(context?: InitContext): Promise<void>;
+	execute(request?: RunRequest, context?: RunContext): Promise<RunResponse>;
+	dispose(): Promise<void>;
+}
+export interface AgentManifest {
+	readonly defaultAgent: string;
+	readonly agents: ReadonlyMap<string, AgentHandler>;
+}
+export interface AgentRouter {
+	readonly manifest: AgentManifest;
+	run(agentName: string, request: RunRequest, context?: RunContext): Promise<RunResponse>;
+	describe(agentName: string): HandlerDescription | null;
+	agents(): string[];
+	defaultAgent(): string;
+	dispose(): Promise<void>;
+}
+export interface ChatMessage {
+	role: "system" | "user" | "assistant";
+	content: string;
+}
+export interface ChatRequest {
+	model?: string | undefined;
+	messages: ChatMessage[];
+	stream?: boolean | undefined;
+}
+export interface UsageMetadata {
+	prompt_tokens?: number | undefined;
+	completion_tokens?: number | undefined;
+	total_tokens?: number | undefined;
+}
+export interface ChatDelta {
+	role?: "assistant" | undefined;
+	content?: string | undefined;
+}
+export interface ChatChunk {
+	id?: string | undefined;
+	object?: "chat.completion.chunk" | undefined;
+	created?: number | undefined;
+	model?: string | undefined;
+	choices: [
+		{
+			index?: number | undefined;
+			delta: ChatDelta;
+			finish_reason?: "stop" | "length" | "error" | null | undefined;
+		}
+	];
+	usage?: UsageMetadata | undefined;
+	/** Present only on in-band error frames (finish_reason: 'error'). */
+	error?: {
+		message: string;
+	} | undefined;
+}
+/**
+ * AHI resolver function — same shape as the resolver produced by createRouter
+ * in @rcrsr/rill-agent. Defined here to avoid importing a runtime value for a
+ * type-only position.
+ */
+export type AhiResolver = (agentName: string, request: RunRequest) => Promise<RunResponse>;
+export interface ChatHarnessOptions {
+	routes?: {
+		openai?: boolean | undefined;
+		perAgent?: boolean | undefined;
+		defaultAgent?: boolean | undefined;
+		discovery?: boolean | undefined;
+	} | undefined;
+	cors?: boolean | undefined;
+	port?: number | undefined;
+}
+export interface ChatHarness {
+	listen(port?: number): Promise<void>;
+	close(): Promise<void>;
+	readonly app: Hono;
+}
+/**
+ * Create a chat harness wrapping an AgentRouter.
+ *
+ * Routes (all configurable via options.routes):
+ *   POST /v1/chat/completions  — OpenAI-compatible; model field selects agent
+ *   POST /agents/:name/chat    — per-agent chat
+ *   POST /chat                 — default agent chat
+ *   GET  /agents               — discovery; chat-eligible agents only
+ *
+ * Always-present routes:
+ *   GET  /health               — returns 200 "OK"
+ *   GET  /metrics              — returns JSON metrics counters
+ *
+ * Throws ChatSignatureError if defaultAgent route is enabled but the default
+ * agent is missing or its declared signature is not chat-eligible (see
+ * inspectChatHandler).
+ */
+export declare function createChatHarness(router: AgentRouter, options?: ChatHarnessOptions): ChatHarness;
+/**
+ * Error thrown at factory time when the default agent route is enabled but
+ * the default agent is missing, or its declared signature is not
+ * chat-eligible. Not mapped to an HTTP status; indicates misconfiguration at
+ * startup.
+ */
+export declare class ChatSignatureError extends Error {
+	constructor(message: string);
+}
+/**
+ * Chat eligibility validates the handler's declared signature via describe().
+ *
+ * The contract: a chat handler is a stream closure with the canonical chat
+ * input shape and the canonical chat chunk shape. Concretely, the handler's
+ * `describe()` must report:
+ *   - exactly one required param named `messages` with type
+ *     `list(dict(role: string, content: string))`;
+ *   - a `returnType` of the form `stream(<EXPECTED_CHUNK_TYPE>)` or
+ *     `stream(<EXPECTED_CHUNK_TYPE>):<resolution>` where the resolution type
+ *     is unconstrained — the harness only consumes chunks via onChunk and
+ *     leaves the closure free to resolve to a string, number, dict, etc.
+ *
+ * Any deviation in either the param shape or the chunk shape rejects the
+ * handler at `createChatHarness()` time rather than failing on the first
+ * request. Both fields are emitted by rill-build ≥ 0.19.6 (paired with
+ * rill ≥ 0.19.3).
+ */
+export declare function inspectChatHandler(handler: AgentHandler): {
+	eligible: true;
+} | {
+	eligible: false;
+	reason: string;
+};
+/**
+ * Validates that value is a non-empty array of well-formed ChatMessage objects.
+ * Returns a discriminated union: success carries the narrowed ChatMessage array,
+ * failure carries a human-readable error string.
+ */
+export declare function validateMessages(value: unknown): {
+	valid: true;
+	messages: ChatMessage[];
+} | {
+	valid: false;
+	error: string;
+};
+export interface RillHarnessLogger {
+	info(...args: unknown[]): void;
+	warn(...args: unknown[]): void;
+	error(...args: unknown[]): void;
+}
+export interface RillCompiledPackage {
+	readonly mount: string;
+	readonly buildOutput: {
+		readonly outputPath: string;
+	};
+}
+export interface RillServeContext {
+	readonly config: Record<string, unknown>;
+	readonly logger: RillHarnessLogger;
+	readonly packages: readonly RillCompiledPackage[];
+	readonly requestedMount: string | undefined;
+	readonly args: readonly string[];
+	readonly onShutdown: (handler: () => void | Promise<void>) => void;
+	readonly onSourceChange: (handler: () => void | Promise<void>) => void;
+}
+export interface RillPostBuildContext {
+	readonly outputDir: string;
+	readonly packages: readonly RillCompiledPackage[];
+	readonly logger: RillHarnessLogger;
+}
+export interface RillHarness {
+	readonly name: string;
+	readonly postBuild?: (ctx: RillPostBuildContext) => Promise<void>;
+	readonly serve?: (ctx: RillServeContext) => Promise<number>;
+}
+/**
+ * Default export consumed by the rill CLI (`rill install --replace`,
+ * `rill run`) when this package is declared as a bundle harness. `serve`
+ * assembles a router from the bundle's compiled packages and hosts it over the
+ * OpenAI-compatible chat harness on `config.port` (default 3000).
+ */
+declare const harness: RillHarness;
+
+export {
+	harness as default,
+};
+
+export {};

package/dist/index.js

@@ -0,0 +1,697 @@
+// src/harness.ts
+import { cors } from "hono/cors";
+
+// ../../shared/hono-kit/src/index.ts
+import { existsSync } from "fs";
+import path from "path";
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+function assertJsonObject(parsed) {
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Request body must be a JSON object");
+  }
+  return parsed;
+}
+function createHarnessLifecycle(options) {
+  const app = new Hono();
+  let server;
+  async function listen(port) {
+    if (server !== void 0) {
+      throw new Error("Server is already listening");
+    }
+    return new Promise((resolve) => {
+      server = serve({ fetch: app.fetch, port }, () => {
+        options?.serverTweaks?.(server);
+        resolve();
+      });
+    });
+  }
+  async function close() {
+    if (server !== void 0) {
+      server.close();
+      server = void 0;
+    }
+  }
+  return { app, listen, close };
+}
+function compiledPackageEntries(ctx) {
+  return ctx.packages.map((p) => ({
+    name: p.mount,
+    dir: p.buildOutput.outputPath
+  }));
+}
+function readHarnessPort(config, fallback) {
+  const p = config["port"];
+  if (typeof p === "number" && Number.isInteger(p)) return p;
+  if (typeof p === "string" && /^\d+$/.test(p)) return Number(p);
+  return fallback;
+}
+function assertCompiledHandlers(ctx) {
+  for (const pkg of ctx.packages) {
+    const handlerPath = path.join(pkg.buildOutput.outputPath, "handler.js");
+    if (!existsSync(handlerPath)) {
+      throw new Error(`missing handler file: ${handlerPath}`);
+    }
+  }
+}
+async function runRillServe(ctx, start) {
+  const handle = await start(compiledPackageEntries(ctx));
+  ctx.onShutdown(async () => {
+    await handle.close();
+  });
+  return new Promise(() => {
+  });
+}
+
+// src/errors.ts
+var ChatSignatureError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChatSignatureError";
+  }
+};
+var ChatChunkError = class extends Error {
+  /** HTTP status code for this error. */
+  statusCode;
+  constructor(message) {
+    super(message);
+    this.name = "ChatChunkError";
+    this.statusCode = 500;
+  }
+};
+
+// src/eligibility.ts
+var EXPECTED_MESSAGES_TYPE = "list(dict(role: string, content: string))";
+var EXPECTED_CHUNK_TYPE = "dict(choices: list(dict(delta: dict(role: string, content: string), finish_reason: string)))";
+function extractStreamChunkType(returnType) {
+  const prefix = "stream(";
+  if (!returnType.startsWith(prefix)) return null;
+  let depth = 1;
+  const start = prefix.length;
+  for (let i = start; i < returnType.length; i++) {
+    const c = returnType[i];
+    if (c === "(") {
+      depth++;
+    } else if (c === ")") {
+      depth--;
+      if (depth === 0) {
+        return returnType.slice(start, i);
+      }
+    }
+  }
+  return null;
+}
+function inspectChatHandler(handler) {
+  const description = handler.describe();
+  if (description === null) {
+    return {
+      eligible: false,
+      reason: "handler.describe() returned null"
+    };
+  }
+  const params = description.params;
+  if (params.length !== 1) {
+    return {
+      eligible: false,
+      reason: `expected exactly one param "messages", got ${params.length}`
+    };
+  }
+  const p = params[0];
+  if (p === void 0) {
+    return {
+      eligible: false,
+      reason: "handler.describe() returned an empty params slot"
+    };
+  }
+  if (p.name !== "messages") {
+    return {
+      eligible: false,
+      reason: `expected param "messages", got "${p.name}"`
+    };
+  }
+  if (!p.required) {
+    return {
+      eligible: false,
+      reason: 'expected param "messages" to be required'
+    };
+  }
+  if (p.type !== EXPECTED_MESSAGES_TYPE) {
+    return {
+      eligible: false,
+      reason: `expected param "messages" of type "${EXPECTED_MESSAGES_TYPE}", got "${p.type}"`
+    };
+  }
+  if (description.returnType === void 0) {
+    return {
+      eligible: false,
+      reason: "handler.describe() did not report a returnType (rebuild with rill-cli >= 0.19.6)"
+    };
+  }
+  const chunkType = extractStreamChunkType(description.returnType);
+  if (chunkType === null) {
+    return {
+      eligible: false,
+      reason: `expected return type "stream(<chunk>)" or "stream(<chunk>):<ret>", got "${description.returnType}"`
+    };
+  }
+  if (chunkType !== EXPECTED_CHUNK_TYPE) {
+    return {
+      eligible: false,
+      reason: `expected stream chunk type "${EXPECTED_CHUNK_TYPE}", got "${chunkType}"`
+    };
+  }
+  return { eligible: true };
+}
+
+// src/stream.ts
+var encoder = new TextEncoder();
+function toAsyncIterable(source) {
+  if (Symbol.asyncIterator in source) {
+    return source;
+  }
+  return source;
+}
+function fillChunk(chunk, defaults) {
+  return {
+    id: chunk.id ?? defaults.id,
+    object: chunk.object ?? "chat.completion.chunk",
+    created: chunk.created ?? defaults.created,
+    model: chunk.model ?? defaults.model,
+    choices: chunk.choices,
+    ...chunk.usage !== void 0 ? { usage: chunk.usage } : {}
+  };
+}
+function encodeChunk(chunk) {
+  return encoder.encode(`data: ${JSON.stringify(chunk)}
+
+`);
+}
+var DONE_FRAME = encoder.encode("data: [DONE]\n\n");
+function buildErrorChunk(defaults) {
+  return {
+    id: defaults.id,
+    object: "chat.completion.chunk",
+    created: defaults.created,
+    model: defaults.model,
+    choices: [{ index: 0, delta: {}, finish_reason: "error" }],
+    error: { message: "Internal server error" }
+  };
+}
+async function createChatStreamResponse(source, options) {
+  const iterable = toAsyncIterable(source);
+  const iter = iterable[Symbol.asyncIterator]();
+  const streamId = `chatcmpl-${crypto.randomUUID()}`;
+  const created = Math.floor(Date.now() / 1e3);
+  const defaults = { id: streamId, created, model: options.model };
+  const firstResult = await iter.next();
+  if (firstResult.done === true) {
+    const body2 = new ReadableStream({
+      start(controller) {
+        controller.enqueue(DONE_FRAME);
+        controller.close();
+      },
+      cancel() {
+        options.abortController.abort();
+      }
+    });
+    return new Response(body2, { status: 200, headers: sseHeaders() });
+  }
+  const firstChunk = fillChunk(firstResult.value, defaults);
+  const body = new ReadableStream({
+    start(controller) {
+      (async () => {
+        controller.enqueue(encodeChunk(firstChunk));
+        let result = await iter.next();
+        while (result.done !== true) {
+          controller.enqueue(encodeChunk(fillChunk(result.value, defaults)));
+          result = await iter.next();
+        }
+        controller.enqueue(DONE_FRAME);
+        controller.close();
+      })().catch((err) => {
+        if (options.abortController.signal.aborted || controller.desiredSize === null) {
+          return;
+        }
+        console.error(err);
+        options.onError?.(err);
+        try {
+          controller.enqueue(encodeChunk(buildErrorChunk(defaults)));
+          controller.enqueue(DONE_FRAME);
+          controller.close();
+        } catch {
+        }
+      });
+    },
+    cancel() {
+      options.abortController.abort();
+    }
+  });
+  return new Response(body, { status: 200, headers: sseHeaders() });
+}
+function checkChunkForError(chunk) {
+  const finishReason = chunk.choices[0]?.finish_reason;
+  if (finishReason === "error" || chunk.error !== void 0) {
+    throw new ChatChunkError(chunk.error?.message ?? "stream error");
+  }
+}
+async function createChatCompletionResponse(source, options) {
+  const iterable = toAsyncIterable(source);
+  const iter = iterable[Symbol.asyncIterator]();
+  const id = `chatcmpl-${crypto.randomUUID()}`;
+  const created = Math.floor(Date.now() / 1e3);
+  const firstResult = await iter.next();
+  let content = "";
+  let lastFinishReason;
+  let usage;
+  if (firstResult.done !== true) {
+    checkChunkForError(firstResult.value);
+    ({ content, lastFinishReason, usage } = accumulateChunk(
+      firstResult.value,
+      content,
+      usage
+    ));
+    let result = await iter.next();
+    while (result.done !== true) {
+      checkChunkForError(result.value);
+      ({ content, lastFinishReason, usage } = accumulateChunk(
+        result.value,
+        content,
+        usage
+      ));
+      result = await iter.next();
+    }
+  }
+  const finishReason = lastFinishReason !== void 0 && lastFinishReason !== null ? lastFinishReason : "stop";
+  const body = {
+    id,
+    object: "chat.completion",
+    created,
+    model: options.model,
+    choices: [
+      {
+        index: 0,
+        message: { role: "assistant", content },
+        finish_reason: finishReason
+      }
+    ],
+    ...usage !== void 0 ? { usage } : {}
+  };
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "Content-Type": "application/json" }
+  });
+}
+function accumulateChunk(chunk, content, usage) {
+  const delta = chunk.choices[0]?.delta.content;
+  const nextContent = delta !== void 0 ? content + delta : content;
+  const nextUsage = chunk.usage !== void 0 ? chunk.usage : usage;
+  return {
+    content: nextContent,
+    lastFinishReason: chunk.choices[0]?.finish_reason,
+    usage: nextUsage
+  };
+}
+function sseHeaders() {
+  return {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache",
+    Connection: "keep-alive"
+  };
+}
+
+// src/validate.ts
+var VALID_ROLES = ["system", "user", "assistant"];
+var MAX_MESSAGES = 1e4;
+var MAX_CONTENT_LENGTH = 32e3;
+function validateMessages(value) {
+  if (!Array.isArray(value)) {
+    return { valid: false, error: "messages must be an array" };
+  }
+  if (value.length === 0) {
+    return { valid: false, error: "messages must be a non-empty array" };
+  }
+  if (value.length > MAX_MESSAGES) {
+    return {
+      valid: false,
+      error: `messages must not exceed ${MAX_MESSAGES} items`
+    };
+  }
+  const messages = [];
+  for (let i = 0; i < value.length; i++) {
+    const item = value[i];
+    if (typeof item !== "object" || item === null || !("role" in item) || !VALID_ROLES.includes(
+      item["role"]
+    )) {
+      return {
+        valid: false,
+        error: `messages[${i}].role must be one of: system, user, assistant`
+      };
+    }
+    const record = item;
+    if (typeof record["content"] !== "string") {
+      return {
+        valid: false,
+        error: `messages[${i}].content must be a string`
+      };
+    }
+    if (record["content"].length > MAX_CONTENT_LENGTH) {
+      return {
+        valid: false,
+        error: `messages[${i}].content must not exceed ${MAX_CONTENT_LENGTH} characters`
+      };
+    }
+    messages.push({
+      role: record["role"],
+      content: record["content"]
+    });
+  }
+  return { valid: true, messages };
+}
+
+// src/harness.ts
+function getHandlerFromRouter(router, name) {
+  return router.manifest.agents.get(name);
+}
+function invokeHandlerAsStream(handler, messages, abortController) {
+  return new ReadableStream({
+    start(controller) {
+      void (async () => {
+        try {
+          await handler.execute(
+            { params: { messages } },
+            {
+              signal: abortController.signal,
+              onChunk: async (chunk) => {
+                if (abortController.signal.aborted) return;
+                controller.enqueue(chunk);
+              }
+            }
+          );
+          controller.close();
+        } catch (err) {
+          controller.error(err);
+        }
+      })();
+    },
+    cancel() {
+      abortController.abort();
+    }
+  });
+}
+function createChatHarness(router, options) {
+  if (router === null || router === void 0) {
+    throw new TypeError("router is required");
+  }
+  const routeFlags = {
+    openai: options?.routes?.openai !== false,
+    perAgent: options?.routes?.perAgent !== false,
+    defaultAgent: options?.routes?.defaultAgent !== false,
+    discovery: options?.routes?.discovery !== false
+  };
+  const eligibleAgents = /* @__PURE__ */ new Set();
+  const ineligibleReasons = /* @__PURE__ */ new Map();
+  for (const name of router.agents()) {
+    const handler = getHandlerFromRouter(router, name);
+    if (handler !== void 0) {
+      const result = inspectChatHandler(handler);
+      if (result.eligible) {
+        eligibleAgents.add(name);
+      } else {
+        ineligibleReasons.set(name, result.reason);
+      }
+    }
+  }
+  const defaultAgentName = router.defaultAgent();
+  if (routeFlags.defaultAgent) {
+    if (defaultAgentName === "" || !router.agents().includes(defaultAgentName)) {
+      throw new ChatSignatureError(
+        `Default agent "${defaultAgentName}" is not a known agent`
+      );
+    }
+    if (!eligibleAgents.has(defaultAgentName)) {
+      const reason = ineligibleReasons.get(defaultAgentName) ?? "unknown reason";
+      throw new ChatSignatureError(
+        `Default agent "${defaultAgentName}" has incompatible chat signature: ${reason}`
+      );
+    }
+  }
+  const lifecycle = createHarnessLifecycle();
+  const app = lifecycle.app;
+  let requests = 0;
+  let errors = 0;
+  let activeConnections = 0;
+  if (options?.cors === true) {
+    app.use("*", cors());
+  }
+  app.get("/health", (c) => c.text("OK", 200));
+  app.get(
+    "/metrics",
+    (c) => c.json({
+      requests,
+      errors,
+      active_connections: activeConnections
+    })
+  );
+  async function streamChatResponse(source, resolvedAgent, abortController) {
+    activeConnections++;
+    const { readable, writable } = new TransformStream();
+    (async () => {
+      const writer = writable.getWriter();
+      try {
+        if (Symbol.asyncIterator in source) {
+          for await (const chunk of source) {
+            if (abortController.signal.aborted) break;
+            await writer.write(chunk);
+          }
+        } else {
+          const reader = source.getReader();
+          try {
+            let result = await reader.read();
+            while (!result.done) {
+              if (abortController.signal.aborted) {
+                await reader.cancel();
+                break;
+              }
+              await writer.write(result.value);
+              result = await reader.read();
+            }
+          } finally {
+            reader.releaseLock();
+          }
+        }
+        if (abortController.signal.aborted) {
+          await writer.abort();
+        } else {
+          await writer.close();
+        }
+      } catch (err) {
+        await writer.abort(err);
+      } finally {
+        activeConnections--;
+        requests++;
+      }
+    })().catch(() => {
+    });
+    try {
+      return await createChatStreamResponse(readable, {
+        model: resolvedAgent,
+        abortController,
+        onError: () => {
+          errors++;
+        }
+      });
+    } catch (err) {
+      console.error(err);
+      errors++;
+      return new Response(
+        JSON.stringify({ error: { message: "Internal server error" } }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    }
+  }
+  async function bufferedChatResponse(source, resolvedAgent) {
+    activeConnections++;
+    try {
+      return await createChatCompletionResponse(source, {
+        model: resolvedAgent
+      });
+    } catch (err) {
+      errors++;
+      if (err instanceof ChatChunkError) {
+        return new Response(
+          JSON.stringify({ error: { message: err.message } }),
+          {
+            status: err.statusCode,
+            headers: { "Content-Type": "application/json" }
+          }
+        );
+      }
+      console.error(err);
+      return new Response(
+        JSON.stringify({ error: { message: "Internal server error" } }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" }
+        }
+      );
+    } finally {
+      activeConnections--;
+      requests++;
+    }
+  }
+  function dispatchChatResponse(source, resolvedAgent, abortController, wantsStream) {
+    return wantsStream ? streamChatResponse(source, resolvedAgent, abortController) : bufferedChatResponse(source, resolvedAgent);
+  }
+  async function parseChatBody(c) {
+    try {
+      const parsed = await c.req.json();
+      return assertJsonObject(parsed);
+    } catch (err) {
+      return c.json(
+        {
+          error: {
+            message: err instanceof Error ? err.message : "Invalid JSON"
+          }
+        },
+        400
+      );
+    }
+  }
+  async function handleChatRequest(c, body, agentName, defaultFallback) {
+    const validation = validateMessages(body["messages"]);
+    if (!validation.valid) {
+      errors++;
+      requests++;
+      return c.json({ error: { message: validation.error } }, 400);
+    }
+    let resolvedAgent = agentName;
+    if (!router.agents().includes(resolvedAgent) || !eligibleAgents.has(resolvedAgent)) {
+      if (defaultFallback && eligibleAgents.has(defaultAgentName)) {
+        resolvedAgent = defaultAgentName;
+      } else if (defaultFallback) {
+        errors++;
+        requests++;
+        return c.json(
+          { error: { message: "No default agent configured" } },
+          500
+        );
+      } else {
+        errors++;
+        requests++;
+        return c.json(
+          { error: { message: `Agent "${agentName}" not found` } },
+          404
+        );
+      }
+    }
+    const chatReq = {
+      messages: validation.messages,
+      ...typeof body["model"] === "string" ? { model: body["model"] } : {},
+      ...typeof body["stream"] === "boolean" ? { stream: body["stream"] } : {}
+    };
+    const abortController = new AbortController();
+    const handler = getHandlerFromRouter(router, resolvedAgent);
+    if (handler === void 0) {
+      errors++;
+      requests++;
+      return c.json(
+        {
+          error: { message: `Agent "${resolvedAgent}" handler not accessible` }
+        },
+        500
+      );
+    }
+    const source = invokeHandlerAsStream(
+      handler,
+      chatReq.messages,
+      abortController
+    );
+    const wantsStream = chatReq.stream === true;
+    return dispatchChatResponse(
+      source,
+      resolvedAgent,
+      abortController,
+      wantsStream
+    );
+  }
+  if (routeFlags.perAgent) {
+    app.post("/agents/:name/chat", async (c) => {
+      const body = await parseChatBody(c);
+      if (body instanceof Response) {
+        errors++;
+        requests++;
+        return body;
+      }
+      const name = c.req.param("name");
+      return handleChatRequest(c, body, name, false);
+    });
+  }
+  if (routeFlags.openai) {
+    app.post("/v1/chat/completions", async (c) => {
+      const body = await parseChatBody(c);
+      if (body instanceof Response) {
+        errors++;
+        requests++;
+        return body;
+      }
+      const agentName = typeof body["model"] === "string" && body["model"] !== "" ? body["model"] : defaultAgentName;
+      return handleChatRequest(c, body, agentName, true);
+    });
+  }
+  if (routeFlags.defaultAgent) {
+    app.post("/chat", async (c) => {
+      const body = await parseChatBody(c);
+      if (body instanceof Response) {
+        errors++;
+        requests++;
+        return body;
+      }
+      return handleChatRequest(c, body, defaultAgentName, true);
+    });
+  }
+  if (routeFlags.discovery) {
+    app.get("/agents", (c) => {
+      requests++;
+      const agents = router.agents().filter((n) => eligibleAgents.has(n)).map((n) => ({
+        name: n,
+        description: router.describe(n)?.description,
+        default: n === defaultAgentName
+      }));
+      return c.json({ agents });
+    });
+  }
+  return {
+    app,
+    listen: (port) => lifecycle.listen(port ?? options?.port ?? 3e3),
+    close: lifecycle.close
+  };
+}
+
+// src/index.ts
+import { createRouter, assembleManifest } from "@rcrsr/rill-agent";
+var HARNESS_NAME = "@rcrsr/rill-agent-chat";
+var harness = {
+  name: HARNESS_NAME,
+  postBuild: async (ctx) => {
+    assertCompiledHandlers(ctx);
+  },
+  serve: (ctx) => runRillServe(ctx, async (entries) => {
+    const router = await createRouter(await assembleManifest(entries));
+    const port = readHarnessPort(ctx.config, 3e3);
+    const server = createChatHarness(router, { port });
+    await server.listen(port);
+    ctx.logger.info(`[${HARNESS_NAME}] listening on :${port}`);
+    return server;
+  })
+};
+var index_default = harness;
+export {
+  ChatSignatureError,
+  createChatHarness,
+  index_default as default,
+  inspectChatHandler,
+  validateMessages
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@rcrsr/rill-agent-chat",
+  "version": "0.20.0",
+  "description": "rill agent chat harness — Hono-based chat endpoint wrapping AgentRouter",
+  "license": "MIT",
+  "author": "Andre Bremer",
+  "type": "module",
+  "rill": {
+    "role": "harness"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup && dts-bundle-generator --config dts-bundle-generator.config.cjs && node -e \"const fs=require('fs');const walk=(d)=>fs.readdirSync(d,{withFileTypes:true}).flatMap(e=>e.isDirectory()?walk(d+'/'+e.name):[d+'/'+e.name]);const hits=walk('dist').filter(f=>fs.readFileSync(f,'utf8').includes('@rcrsr/rill-agent-hono-kit'));if(hits.length){console.error('hono-kit leak in dist:',hits);process.exit(1);}\"",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --config ../../../.oxlintrc.json src/ tests/",
+    "check": "pnpm run build && pnpm run test && pnpm run lint"
+  },
+  "dependencies": {
+    "@rcrsr/rill-agent": "workspace:~",
+    "@hono/node-server": "^2.0.1",
+    "hono": "^4.12.16"
+  },
+  "devDependencies": {
+    "@rcrsr/rill-agent-hono-kit": "workspace:^",
+    "dts-bundle-generator": "^9.5.1",
+    "tsup": "^8.5.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rcrsr/rill-agent.git",
+    "directory": "packages/agent/chat"
+  }
+}