threadwire 0.1.6 → 0.1.9

package/src/model-broker.js

@@ -0,0 +1,313 @@
+// @ts-nocheck
+/* eslint-disable jsdoc/require-jsdoc */
+
+import {constants} from "node:fs"
+import {open} from "node:fs/promises"
+import {createServer} from "node:http"
+import {bearerToken, createGrantStore, validateBrokerRequest, validateResponsesBody} from "./model-broker-policy.js"
+import {abortable, readResponseCapped} from "./absolute-deadline.js"
+
+const MAX_BODY_BYTES = 2_097_152
+const MAX_SECRET_BYTES = 65_536
+
+/** @param {{environment?: NodeJS.ProcessEnv, fetchImplementation?: typeof fetch}} [options] */
+export async function startModelBroker(options = {}) {
+  const environment = options.environment ?? process.env
+  const host = environment.THREADWIRE_MODEL_BROKER_HOST ?? "0.0.0.0"
+  const port = portValue(environment.THREADWIRE_MODEL_BROKER_PORT, 8789)
+  const adminToken = safeSetting(environment.THREADWIRE_MODEL_BROKER_ADMIN_TOKEN, "THREADWIRE_MODEL_BROKER_ADMIN_TOKEN")
+  const upstream = upstreamUrl(environment.THREADWIRE_CODEX_UPSTREAM_URL)
+  let credential = await readSecretFile(environment.THREADWIRE_CODEX_CREDENTIAL_FILE)
+  let generation = 1
+  let reloading = false
+  let stopping = false
+  const shutdown = new AbortController()
+  const controlSockets = new Set()
+  const grants = createGrantStore()
+  /** @type {Map<string, import("node:http").Server>} */
+  const listeners = new Map()
+  /** @type {Map<string, {controller: AbortController, timer: NodeJS.Timeout, sockets: Set<import("node:net").Socket>}>} */
+  const grantRuntimes = new Map()
+  const fetchImplementation = options.fetchImplementation ?? fetch
+  const revokeGrant = async (token) => {
+    grants.revoke(token)
+    const runtime = grantRuntimes.get(token)
+    grantRuntimes.delete(token)
+    if (runtime !== undefined) {
+      clearTimeout(runtime.timer)
+      runtime.controller.abort(new Error("Broker grant expired"))
+      for (const socket of runtime.sockets) socket.destroy()
+      runtime.sockets.clear()
+    }
+    await closeListener(listeners, token, 1000)
+  }
+
+  const server = createServer(async (request, response) => {
+    try {
+      if (stopping) throw new Error("Model broker is shutting down")
+      if (request.method === "GET" && request.url === "/healthz") {
+        response.writeHead(200, {"content-type": "application/json"})
+        response.end(JSON.stringify({ok: true, generation}))
+        return
+      }
+      if (request.url === "/admin/grants" && request.method === "POST") {
+        requireAdmin(request.headers.authorization, adminToken)
+        if (reloading) throw new Error("Model broker reload is active")
+        const body = await readJson(request, shutdown.signal)
+        const grant = parseGrant(body)
+        const expiresAt = Date.now() + grant.ttlMs
+        const token = grants.issue(grant)
+        const controller = new AbortController()
+        const sockets = new Set()
+        const listener = createServer((workerRequest, workerResponse) => {
+          proxyWorkerRequest(workerRequest, workerResponse, {
+            grants, token, grant, credential: () => credential, upstream, fetchImplementation,
+            signal: controller.signal
+          }).catch((error) => {
+            if (workerResponse.destroyed) return
+            process.stderr.write(`threadwire-model-broker: ${error instanceof Error ? error.message : "request failed"}\n`)
+            const status = isClientError(error) ? 403 : 502
+            sendJson(workerResponse, status, {error: status === 403 ? "request denied" : "model broker unavailable"})
+          })
+        })
+        listener.on("connection", (socket) => {
+          if (controller.signal.aborted) {
+            socket.destroy()
+            return
+          }
+          sockets.add(socket)
+          socket.once("close", () => sockets.delete(socket))
+        })
+        try {
+          await listen(listener, 0, grant.brokerAddress)
+        } catch (error) {
+          grants.revoke(token)
+          throw error
+        }
+        listeners.set(token, listener)
+        const expiryTimer = setTimeout(() => { void revokeGrant(token) }, Math.max(1, expiresAt - Date.now()))
+        expiryTimer.unref()
+        grantRuntimes.set(token, {controller, timer: expiryTimer, sockets})
+        const address = listener.address()
+        if (address === null || typeof address === "string") throw new Error("Invalid broker listener")
+        sendJson(response, 201, {token, generation, port: address.port})
+        return
+      }
+      if (request.url?.startsWith("/admin/grants/") && request.method === "DELETE") {
+        requireAdmin(request.headers.authorization, adminToken)
+        const token = decodeURIComponent(request.url.slice("/admin/grants/".length))
+        await revokeGrant(token)
+        response.writeHead(204)
+        response.end()
+        return
+      }
+      if (request.url?.startsWith("/admin/grants/") && request.url.endsWith("/activate") && request.method === "POST") {
+        requireAdmin(request.headers.authorization, adminToken)
+        const token = decodeURIComponent(request.url.slice("/admin/grants/".length, -"/activate".length))
+        grants.activate(token)
+        sendJson(response, 200, {ok: true})
+        return
+      }
+      if (request.url === "/admin/reload" && request.method === "POST") {
+        requireAdmin(request.headers.authorization, adminToken)
+        if (reloading) throw new Error("Model broker reload is active")
+        reloading = true
+        try {
+          const replacement = await readSecretFile(environment.THREADWIRE_CODEX_CREDENTIAL_FILE)
+          grants.clear()
+          await Promise.all([...listeners.keys()].map(revokeGrant))
+          credential = replacement
+          generation += 1
+        } finally {
+          reloading = false
+        }
+        sendJson(response, 200, {ok: true, generation})
+        return
+      }
+      sendJson(response, 403, {error: "request denied"})
+    } catch (error) {
+      const status = isClientError(error) ? 403 : 502
+      sendJson(response, status, {error: status === 403 ? "request denied" : "model broker unavailable"})
+    }
+  })
+  server.on("connection", (socket) => {
+    if (shutdown.signal.aborted) return socket.destroy()
+    controlSockets.add(socket)
+    socket.once("close", () => controlSockets.delete(socket))
+  })
+  await listen(server, port, host)
+  return {
+    server,
+    close: async () => {
+      stopping = true
+      shutdown.abort(new Error("Model broker is shutting down"))
+      for (const socket of controlSockets) socket.destroy()
+      await Promise.all([...listeners.keys()].map(revokeGrant))
+      await Promise.race([
+        new Promise((resolve) => server.close(() => resolve(undefined))),
+        new Promise((resolve) => {
+          const timer = setTimeout(resolve, 1000)
+          timer.unref()
+        })
+      ])
+    },
+    activeListeners: () => listeners.size,
+    config: {host, port, upstream: upstream.toString()}
+  }
+}
+
+/** @param {unknown} value */
+function parseGrant(value) {
+  if (!isRecord(value) || value.provider !== "codex" || typeof value.runId !== "string" || typeof value.networkId !== "string" || typeof value.model !== "string" || typeof value.brokerAddress !== "string") {
+    throw new Error("Invalid broker grant")
+  }
+  if (!/^(?:\d{1,3}\.){3}\d{1,3}$/u.test(value.brokerAddress)) throw new Error("Invalid broker grant")
+  const ttlMs = value.ttlMs
+  if (typeof ttlMs !== "number") throw new Error("Invalid broker grant")
+  return {provider: "codex", runId: value.runId, networkId: value.networkId, model: value.model, brokerAddress: value.brokerAddress, ttlMs}
+}
+
+async function proxyWorkerRequest(request, response, options) {
+  throwIfAborted(options.signal)
+  const policyHeaders = {...request.headers}
+  delete policyHeaders.host
+  delete policyHeaders.connection
+  delete policyHeaders["transfer-encoding"]
+  validateBrokerRequest({method: request.method, path: request.url, headers: policyHeaders})
+  const suppliedToken = bearerToken(request.headers.authorization)
+  if (suppliedToken !== options.token) throw new Error("Broker grant token mismatch")
+  const grant = options.grants.authorize(suppliedToken, {
+    provider: "codex", networkId: options.grant.networkId, runId: options.grant.runId
+  })
+  const body = await readBody(request, options.signal)
+  throwIfAborted(options.signal)
+  options.grants.authorize(suppliedToken, {
+    provider: "codex", networkId: options.grant.networkId, runId: options.grant.runId
+  })
+  validateResponsesBody(body, grant.model)
+  throwIfAborted(options.signal)
+  const upstreamResponse = await abortable(options.fetchImplementation(new URL("/v1/responses", options.upstream), {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      authorization: `Bearer ${options.credential()}`,
+      "content-type": "application/json",
+      "user-agent": "threadwire-model-broker/1"
+    },
+    body,
+    signal: options.signal
+  }), options.signal)
+  throwIfAborted(options.signal)
+  const bytes = await readResponseCapped(upstreamResponse, MAX_BODY_BYTES, options.signal)
+  throwIfAborted(options.signal)
+  response.writeHead(upstreamResponse.status, {"content-type": safeContentType(upstreamResponse.headers.get("content-type"))})
+  response.end(bytes)
+}
+
+async function closeListener(listeners, token, timeoutMs) {
+  const listener = listeners.get(token)
+  listeners.delete(token)
+  if (listener === undefined) return
+  await Promise.race([
+    new Promise((resolve) => listener.close(() => resolve(undefined))),
+    new Promise((resolve) => {
+      const timer = setTimeout(resolve, timeoutMs)
+      timer.unref()
+    })
+  ])
+}
+
+async function readSecretFile(path) {
+  const safePath = safeSetting(path, "THREADWIRE_CODEX_CREDENTIAL_FILE")
+  let handle
+  try {
+    handle = await open(safePath, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+    const metadata = await handle.stat()
+    if (!metadata.isFile() || metadata.size < 1 || metadata.size > MAX_SECRET_BYTES || (metadata.mode & 0o022) !== 0) throw new Error()
+    const value = (await handle.readFile("utf8")).replace(/[\r\n]+$/u, "")
+    if (value.length === 0 || /[\r\n]/u.test(value)) throw new Error()
+    return value
+  } catch {
+    throw new Error("Codex credential file is unavailable")
+  } finally {
+    await handle?.close().catch(() => {})
+  }
+}
+
+async function readJson(request, signal) {
+  const body = await readBody(request, signal)
+  try {
+    return JSON.parse(body.toString("utf8"))
+  } catch {
+    throw new Error("Invalid request")
+  }
+}
+
+async function readBody(request, signal) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of request) {
+    throwIfAborted(signal)
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    size += buffer.length
+    if (size > MAX_BODY_BYTES) throw new Error("Request exceeded capacity")
+    chunks.push(buffer)
+  }
+  throwIfAborted(signal)
+  return Buffer.concat(chunks)
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("Broker grant expired")
+}
+
+function requireAdmin(value, expected) {
+  if (value !== `Bearer ${expected}`) throw new Error("Request denied")
+}
+
+function upstreamUrl(value) {
+  const url = new URL(safeSetting(value, "THREADWIRE_CODEX_UPSTREAM_URL"))
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error("THREADWIRE_CODEX_UPSTREAM_URL is invalid")
+  }
+  return url
+}
+
+function safeSetting(value, name) {
+  if (typeof value !== "string" || value.length === 0 || /[\r\n]/u.test(value)) throw new Error(`${name} is required`)
+  return value
+}
+
+function portValue(value, fallback) {
+  if (value === undefined) return fallback
+  const number = Number(value)
+  if (!/^\d+$/u.test(value) || !Number.isSafeInteger(number) || number < 1 || number > 65535) throw new Error("Invalid model broker port")
+  return number
+}
+
+function safeContentType(value) {
+  return value && /^[\w.+-]+\/[\w.+-]+(?:;\s*charset=[\w-]+)?$/u.test(value) ? value : "application/json"
+}
+
+function sendJson(response, status, value) {
+  response.writeHead(status, {"content-type": "application/json"})
+  response.end(JSON.stringify(value))
+}
+
+function isClientError(error) {
+  return error instanceof Error && /denied|grant|Invalid request|capacity/u.test(error.message)
+}
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+function listen(server, port, host) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject)
+    server.listen(port, host, () => {
+      server.removeListener("error", reject)
+      resolve(undefined)
+    })
+  })
+}

package/src/mount-policy.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+import {readFile} from "node:fs/promises"
+import {isAbsolute, relative} from "node:path"
+
+/** @param {string} root @param {(path: string, encoding: "utf8") => Promise<string>} [reader] */
+export async function assertNoNestedMounts(root, reader = readFile) {
+  const mountinfo = await reader("/proc/self/mountinfo", "utf8")
+  for (const line of mountinfo.split("\n")) {
+    if (line.length === 0) continue
+    const fields = line.split(" ")
+    const encoded = fields[4]
+    if (encoded === undefined) throw new Error("Mount topology unavailable")
+    const mountpoint = decodeMountinfo(encoded)
+    if (mountpoint !== root && within(root, mountpoint)) throw new Error("Nested worktree mounts are forbidden")
+  }
+}
+
+/** @param {string} root @param {string} child */
+function within(root, child) {
+  const path = relative(root, child)
+  return path !== "" && !path.startsWith("..") && !isAbsolute(path)
+}
+
+/** @param {string} value */
+function decodeMountinfo(value) {
+  return value.replace(/\\(040|011|012|134)/gu, (_, octal) => String.fromCharCode(Number.parseInt(octal, 8)))
+}

package/src/normalized-output.js

@@ -0,0 +1,68 @@
+// @ts-check
+
+import {closeSync, fsyncSync, openSync, writeSync} from "node:fs"
+import {dirname} from "node:path"
+
+const filesystemOperations = {closeSync, fsyncSync, openSync, writeSync}
+
+/**
+ * @typedef {object} FilesystemOperations
+ * @property {(fileDescriptor: number) => void} closeSync Close a transcript.
+ * @property {(fileDescriptor: number) => void} fsyncSync Sync a transcript.
+ * @property {(path: string, flags: string, mode?: number) => number} openSync Open a transcript or directory.
+ * @property {(fileDescriptor: number, buffer: Buffer, offset: number, length: number) => number} writeSync
+ * Write transcript bytes.
+ */
+
+export class NormalizedOutput {
+  /**
+   * @param {Pick<NodeJS.WritableStream, "write">} output
+   * @param {string | undefined} transcriptPath
+   * @param {FilesystemOperations} [filesystem]
+   */
+  constructor(output, transcriptPath, filesystem = filesystemOperations) {
+    this.output = output
+    this.filesystem = filesystem
+    this.transcriptDirectory = transcriptPath === undefined ? undefined : dirname(transcriptPath)
+    this.fileDescriptor = transcriptPath === undefined
+      ? undefined
+      : this.filesystem.openSync(transcriptPath, "wx", 0o600)
+    this.closed = false
+  }
+
+  /** @param {string} record */
+  write(record) {
+    if (this.closed) throw new Error("Normalized output is closed")
+    if (this.fileDescriptor !== undefined) {
+      const bytes = Buffer.from(record)
+      let offset = 0
+      while (offset < bytes.length) {
+        const written = this.filesystem.writeSync(
+          this.fileDescriptor,
+          bytes,
+          offset,
+          bytes.length - offset
+        )
+        if (written === 0) throw new Error("Transcript write made zero bytes of progress")
+        offset += written
+      }
+      this.filesystem.fsyncSync(this.fileDescriptor)
+      const directoryDescriptor = this.filesystem.openSync(
+        /** @type {string} */ (this.transcriptDirectory),
+        "r"
+      )
+      try {
+        this.filesystem.fsyncSync(directoryDescriptor)
+      } finally {
+        this.filesystem.closeSync(directoryDescriptor)
+      }
+    }
+    this.output.write(record)
+  }
+
+  close() {
+    if (this.closed) return
+    this.closed = true
+    if (this.fileDescriptor !== undefined) this.filesystem.closeSync(this.fileDescriptor)
+  }
+}

package/src/providers/index.js

@@ -2,14 +2,15 @@
 
 import {buildClaudeCommand, claudeSessionId, createClaudeParser} from "./claude.js"
 import {buildCodexCommand, codexSessionId, parseCodexEvent} from "./codex.js"
+import {buildKimiCommand, createKimiParser, createKimiSessionId} from "./kimi.js"
 import {buildOpenCodeCommand, createOpenCodeParser, createOpenCodeSessionId} from "./opencode.js"
 
 /**
- * @typedef {{name: "codex" | "claude" | "opencode", executable: string, arguments: string[], parse: (record: unknown) => import("../types.js").WorkerEvent[], sessionId: (record: unknown) => string | undefined}} Provider
+ * @typedef {{name: "codex" | "claude" | "kimi" | "opencode", executable: string, arguments: string[], parse: (record: unknown) => import("../types.js").WorkerEvent[], sessionId: (record: unknown) => string | undefined}} Provider
  */
 
-/** @type {readonly ["codex", "claude", "opencode"]} */
-export const PROVIDERS = ["codex", "claude", "opencode"]
+/** @type {readonly ["codex", "claude", "kimi", "opencode"]} */
+export const PROVIDERS = ["codex", "claude", "kimi", "opencode"]
 
 /** @param {string} name @param {string[]} providerArguments @param {string} prompt @param {string | undefined} resumeSession @param {NodeJS.ProcessEnv} [environment] @returns {Provider} */
 export function createProvider(name, providerArguments, prompt, resumeSession, environment = process.env) {
@@ -25,5 +26,9 @@ export function createProvider(name, providerArguments, prompt, resumeSession, e
     const command = buildOpenCodeCommand(providerArguments, prompt, resumeSession, environment)
     return {...command, name: "opencode", parse: createOpenCodeParser(), sessionId: createOpenCodeSessionId()}
   }
+  if (name === "kimi") {
+    const command = buildKimiCommand(providerArguments, prompt, resumeSession)
+    return {...command, name: "kimi", parse: createKimiParser(), sessionId: createKimiSessionId()}
+  }
   throw new Error(`--provider must be one of: ${PROVIDERS.join(", ")}`)
 }

package/src/providers/kimi.js

@@ -0,0 +1,165 @@
+// @ts-check
+
+const EXECUTABLE = "/usr/local/bin/kimi"
+const ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u
+const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,511}$/u
+const TOOL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/u
+const TOOL_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_.:-]{0,127}$/u
+
+/** @typedef {import("../types.js").WorkerEvent} WorkerEvent */
+/** @typedef {{started: boolean, sessionEmitted: boolean, tools: Map<string, string>}} KimiRecordState */
+/** @typedef {{trusted: boolean, sessionId: string | undefined, events: WorkerEvent[]}} KimiRecognition */
+
+/** @param {string[]} providerArguments */
+export function validateKimiProviderArguments(providerArguments) {
+  if (providerArguments.length === 0) return {modelAlias: "default", arguments: []}
+  if (providerArguments.length === 2 && (providerArguments[0] === "--model" || providerArguments[0] === "-m")
+    && ALIAS_PATTERN.test(providerArguments[1] ?? "")) {
+    return {modelAlias: /** @type {string} */ (providerArguments[1]), arguments: ["--model", /** @type {string} */ (providerArguments[1])]}
+  }
+  throw new Error("Threadwire owns Kimi prompt, output, session, model configuration, permissions, and extensions")
+}
+
+/** @param {string[]} providerArguments @param {string} prompt @param {string | undefined} [resumeSession] */
+export function buildKimiCommand(providerArguments, prompt, resumeSession) {
+  const selection = validateKimiProviderArguments(providerArguments)
+  if (resumeSession !== undefined && !SESSION_PATTERN.test(resumeSession)) throw new Error("Kimi session ID is invalid")
+  return {
+    executable: EXECUTABLE,
+    arguments: [
+      "--model", selection.modelAlias,
+      ...(resumeSession === undefined ? [] : ["--session", resumeSession]),
+      "--prompt", prompt,
+      "--output-format", "stream-json"
+    ]
+  }
+}
+
+/** @returns {(record: unknown) => string | undefined} */
+export function createKimiSessionId() {
+  let emitted = false
+  return (record) => {
+    if (emitted) return undefined
+    const recognized = recognizeKimiRecord(record, undefined)
+    if (recognized.sessionId === undefined) return undefined
+    emitted = true
+    return recognized.sessionId
+  }
+}
+
+/** @returns {(record: unknown) => import("../types.js").WorkerEvent[]} */
+export function createKimiParser() {
+  const state = createKimiRecordState()
+  return (record) => recognizeKimiRecord(record, state).events
+}
+
+/** @param {unknown} record @returns {import("../types.js").WorkerEvent[]} */
+export function parseKimiEvent(record) {
+  return recognizeKimiRecord(record, createKimiRecordState()).events
+}
+
+/** @returns {KimiRecordState} */
+export function createKimiRecordState() {
+  return {started: false, sessionEmitted: false, tools: new Map()}
+}
+
+/** @param {unknown} record */
+export function kimiSessionEnvelopeId(record) {
+  return isRecord(record) && exactKeys(record, ["type", "sessionId"])
+    && record.type === "session" && typeof record.sessionId === "string" && SESSION_PATTERN.test(record.sessionId)
+    ? record.sessionId
+    : undefined
+}
+
+/**
+ * Convert one pinned Kimi stream-json record into the only envelopes the
+ * isolated worker may expose. Raw arguments, results, metadata, and stderr are
+ * never represented in the return value.
+ * @param {unknown} record
+ * @param {ReturnType<typeof createKimiRecordState>} state
+ */
+export function sanitizeKimiRecord(record, state) {
+  const recognized = recognizeKimiRecord(record, state)
+  /** @type {({type: "worker-event", event: WorkerEvent} | {type: "session", sessionId: string})[]} */
+  const output = recognized.events.map((event) => ({type: /** @type {const} */ ("worker-event"), event}))
+  if (recognized.sessionId !== undefined && !state.sessionEmitted) {
+    state.sessionEmitted = true
+    output.push({type: "session", sessionId: recognized.sessionId})
+  }
+  return output
+}
+
+/** @param {unknown} record @param {KimiRecordState | undefined} state @returns {KimiRecognition} */
+function recognizeKimiRecord(record, state) {
+  if (!isRecord(record)) return emptyRecognition()
+  if (record.role === "assistant" && exactOptionalKeys(record, ["role"], ["content", "tool_calls"])) {
+    /** @type {WorkerEvent[]} */
+    const events = []
+    if (record.content !== undefined) {
+      if (typeof record.content !== "string") return emptyRecognition()
+      events.push({type: "text-delta", text: record.content, streamId: "kimi:assistant"})
+    }
+    if (record.tool_calls !== undefined) {
+      if (!Array.isArray(record.tool_calls)) return emptyRecognition()
+      for (const toolCall of record.tool_calls) {
+        const parsed = parseToolCall(toolCall)
+        if (parsed === undefined) return emptyRecognition()
+        state?.tools.set(parsed.id, parsed.name)
+        events.push({type: "tool", phase: "started", name: parsed.name, key: `tool:${parsed.id}`})
+      }
+    }
+    if (events.length === 0) return emptyRecognition()
+    return {trusted: true, sessionId: undefined, events: withStarted(events, state)}
+  }
+  if (record.role === "tool" && exactKeys(record, ["role", "tool_call_id", "content"])
+    && typeof record.tool_call_id === "string" && TOOL_ID_PATTERN.test(record.tool_call_id)
+    && typeof record.content === "string") {
+    const name = state?.tools.get(record.tool_call_id)
+    if (name === undefined || state === undefined) return emptyRecognition()
+    state.tools.delete(record.tool_call_id)
+    return {
+      trusted: true,
+      sessionId: undefined,
+      events: withStarted([{type: "tool", phase: "finished", name, key: `tool:${record.tool_call_id}`}], state)
+    }
+  }
+  if (record.role === "meta" && record.type === "session.resume_hint"
+    && exactKeys(record, ["role", "type", "session_id", "command", "content"])
+    && typeof record.session_id === "string" && SESSION_PATTERN.test(record.session_id)
+    && typeof record.command === "string" && typeof record.content === "string") {
+    return {trusted: true, sessionId: record.session_id, events: withStarted([], state)}
+  }
+  return emptyRecognition()
+}
+
+/** @param {unknown} value @returns {{id: string, name: string} | undefined} */
+function parseToolCall(value) {
+  if (!isRecord(value) || !exactKeys(value, ["type", "id", "function"])
+    || value.type !== "function" || typeof value.id !== "string" || !TOOL_ID_PATTERN.test(value.id)
+    || !isRecord(value.function) || !exactKeys(value.function, ["name", "arguments"])
+    || typeof value.function.name !== "string" || !TOOL_NAME_PATTERN.test(value.function.name)
+    || typeof value.function.arguments !== "string") return undefined
+  return {id: value.id, name: value.function.name}
+}
+
+/** @param {WorkerEvent[]} events @param {KimiRecordState | undefined} state @returns {WorkerEvent[]} */
+function withStarted(events, state) {
+  if (state === undefined || state.started) return events
+  state.started = true
+  return [{type: "lifecycle", phase: "started", summary: "Kimi worker started"}, ...events]
+}
+/** @returns {KimiRecognition} */
+function emptyRecognition() { return {trusted: false, sessionId: undefined, events: []} }
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) { return typeof value === "object" && value !== null && !Array.isArray(value) }
+/** @param {Record<string, unknown>} value @param {readonly string[]} expected @returns {boolean} */
+function exactKeys(value, expected) {
+  const actual = Object.keys(value).sort()
+  const wanted = [...expected].sort()
+  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index])
+}
+/** @param {Record<string, unknown>} value @param {readonly string[]} required @param {readonly string[]} optional @returns {boolean} */
+function exactOptionalKeys(value, required, optional) {
+  const actual = Object.keys(value)
+  return required.every((key) => actual.includes(key)) && actual.every((key) => required.includes(key) || optional.includes(key))
+}

package/src/relay-write.js

@@ -0,0 +1,44 @@
+// @ts-check
+
+const MODEL_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u
+const COLORS = new Set(["always", "never", "auto"])
+
+/** @param {string[]} arguments_ */
+export function validateRelayWriteProviderArguments(arguments_) {
+  /** @type {string[]} */
+  const normalized = []
+  let model = "gpt-5-codex"
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = /** @type {string} */ (arguments_[index])
+    if (argument === "--model" || argument === "-m") {
+      const value = arguments_[index + 1]
+      if (value === undefined || !MODEL_PATTERN.test(value)) throw new Error("Provider argument is unavailable in relay write mode")
+      model = value
+      normalized.push("--model", value)
+      index += 1
+      continue
+    }
+    if (argument.startsWith("--model=")) {
+      const value = argument.slice("--model=".length)
+      if (!MODEL_PATTERN.test(value)) throw new Error("Provider argument is unavailable in relay write mode")
+      model = value
+      normalized.push("--model", value)
+      continue
+    }
+    if (argument === "--color") {
+      const value = arguments_[index + 1]
+      if (value === undefined || !COLORS.has(value)) throw new Error("Provider argument is unavailable in relay write mode")
+      normalized.push("--color", value)
+      index += 1
+      continue
+    }
+    if (argument.startsWith("--color=")) {
+      const value = argument.slice("--color=".length)
+      if (!COLORS.has(value)) throw new Error("Provider argument is unavailable in relay write mode")
+      normalized.push("--color", value)
+      continue
+    }
+    throw new Error("Provider argument is unavailable in relay write mode")
+  }
+  return {arguments: normalized, model}
+}

package/src/telegram-ingress/command.js

@@ -2,16 +2,16 @@
 
 import {PROVIDERS} from "../providers/index.js"
 
-const COMMAND_PATTERN = /^\/code(?:@[A-Za-z0-9_]+)?\s+(codex|claude|opencode)\s+(\S[\s\S]*)$/u
+const COMMAND_PATTERN = /^\/code(?:@[A-Za-z0-9_]+)?\s+(codex|claude|kimi|opencode)\s+(\S[\s\S]*)$/u
 const EVIDENCE_PATTERN = /^\/evidence(?:@[A-Za-z0-9_]+)?\s+(evidence_[A-Za-z0-9_-]{43})\s+(bytes|lines)\s+(\d+):(\d+)$/u
 
 /**
- * @typedef {{provider: "codex" | "claude" | "opencode", prompt: string}} CodeCommand
+ * @typedef {{provider: "codex" | "claude" | "kimi" | "opencode", prompt: string}} CodeCommand
  */
 
 /**
  * Parse the exact ingress command grammar:
- * `/code[optional @bot] <codex|claude|opencode> <nonblank prompt>`
+ * `/code[optional @bot] <codex|claude|kimi|opencode> <nonblank prompt>`
  * @param {string} text
  * @returns {CodeCommand | null}
  */
@@ -24,7 +24,7 @@ export function parseCodeCommand(text) {
   if (prompt.length === 0) return null
   if (!PROVIDERS.includes(/** @type {(typeof PROVIDERS)[number]} */ (providerName))) return null
   return {
-    provider: /** @type {"codex" | "claude" | "opencode"} */ (providerName),
+    provider: /** @type {"codex" | "claude" | "kimi" | "opencode"} */ (providerName),
     prompt
   }
 }