@spectrum-ts/terminal 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Photon AI
+
+Permission is hereby granted,
+free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# @spectrum-ts/terminal
+
+Terminal provider for [spectrum-ts](https://github.com/photon-hq/spectrum-ts) — chat with your agent from the command line via the standalone [tuichat](https://github.com/photon-hq/tuichat) binary (auto-downloaded on first use).
+
+## Install
+
+```sh
+bun add spectrum-ts @spectrum-ts/terminal
+```
+
+## Use
+
+```ts
+import { Spectrum } from "spectrum-ts";
+import { terminal } from "@spectrum-ts/terminal";
+
+const spectrum = Spectrum({ providers: [terminal] });
+```
+
+See the [spectrum-ts documentation](https://photon.codes/spectrum) for the full guide.

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import { ChildProcess } from "node:child_process";
+import { Socket } from "node:net";
+import { Content } from "@spectrum-ts/core";
+import z from "zod";
+
+//#region src/protocol.d.ts
+type ProtocolContent = {
+  type: "text";
+  text: string;
+} | {
+  type: "attachment";
+  name: string;
+  mimeType: string;
+  size?: number;
+  bytes?: string;
+  path?: string;
+} | {
+  type: "voice";
+  name?: string;
+  mimeType: string;
+  size?: number;
+  bytes?: string;
+  path?: string;
+} | {
+  type: "contact";
+  name?: {
+    formatted?: string;
+    first?: string;
+    last?: string;
+  };
+  vcard?: string;
+} | {
+  type: "custom";
+  raw: unknown;
+};
+interface ProtocolMessageNotification {
+  content: ProtocolContent;
+  id: string;
+  replyTo?: {
+    messageId: string;
+  };
+  senderId: string;
+  spaceId: string;
+  timestamp: string;
+}
+interface ProtocolReactionNotification {
+  messageId: string;
+  reaction: string;
+  senderId: string;
+  spaceId: string;
+  timestamp: string;
+}
+declare class RpcSession {
+  private readonly decoder;
+  private nextId;
+  private readonly pending;
+  private onNotify;
+  private onClose;
+  private closed;
+  private readonly socket;
+  constructor(socket: Socket);
+  handleNotifications(h: (method: string, params: unknown) => void): void;
+  onClosed(h: () => void): void;
+  request<T = unknown>(method: string, params?: unknown, timeoutMs?: number): Promise<T>;
+  notify(method: string, params?: unknown): void;
+  close(): void;
+  private handle;
+  private shutdown;
+}
+//#endregion
+//#region src/index.d.ts
+interface ConsoleHijack {
+  restore: () => void;
+}
+type InboundEvent = {
+  kind: "message";
+  value: ProtocolMessageNotification;
+} | {
+  kind: "reaction";
+  value: ProtocolReactionNotification;
+};
+interface TerminalClient {
+  events: AsyncIterable<InboundEvent>;
+  hijack: ConsoleHijack;
+  knownChats: Set<string>;
+  nextChatIndex: number;
+  proc: ChildProcess;
+  session: RpcSession;
+}
+type SpectrumContent = Content;
+interface TerminalInboundMessage {
+  content: SpectrumContent;
+  id: string;
+  replyTo?: {
+    messageId: string;
+  };
+  sender: {
+    id: string;
+  };
+  space: {
+    id: string;
+  };
+  timestamp: Date;
+}
+declare const terminal: import("@spectrum-ts/core").Platform<import("@spectrum-ts/core").PlatformDef<"Terminal", z.ZodObject<{
+  commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodType<object, unknown, z.core.$ZodTypeInternals<object, unknown>> | undefined, z.ZodType<object, unknown, z.core.$ZodTypeInternals<object, unknown>> | undefined, z.ZodType<object, unknown, z.core.$ZodTypeInternals<object, unknown>> | undefined, TerminalClient, {
+  id: string;
+}, {
+  id: string;
+}, z.ZodObject<{
+  replyTo: z.ZodOptional<z.ZodObject<{
+    messageId: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>, TerminalInboundMessage, undefined, Record<never, never>, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
+//#endregion
+export { terminal };

package/dist/index.js

@@ -0,0 +1,698 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { inspect } from "node:util";
+import { UnsupportedError, definePlatform, fromVCard, stream, toVCard } from "@spectrum-ts/core";
+import { asAttachment, asContact, asCustom, asVoice, reactionSchema } from "@spectrum-ts/core/authoring";
+import z from "zod";
+import { createHash, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+//#region src/protocol.ts
+const HEADER_TERMINATOR = Buffer.from("\r\n\r\n");
+const CONTENT_LENGTH = "content-length:";
+function encode(message) {
+	const body = Buffer.from(JSON.stringify(message), "utf8");
+	const header = Buffer.from(`Content-Length: ${body.byteLength}\r\n\r\n`);
+	const out = new Uint8Array(header.byteLength + body.byteLength);
+	out.set(header, 0);
+	out.set(body, header.byteLength);
+	return out;
+}
+var Decoder = class {
+	buf = Buffer.alloc(0);
+	push(chunk) {
+		this.buf = this.buf.length === 0 ? Buffer.from(chunk) : Buffer.concat([this.buf, chunk]);
+		const out = [];
+		for (;;) {
+			const msg = this.readOne();
+			if (!msg) break;
+			out.push(msg);
+		}
+		return out;
+	}
+	readOne() {
+		const end = this.buf.indexOf(HEADER_TERMINATOR);
+		if (end < 0) return null;
+		const header = this.buf.subarray(0, end).toString("utf8");
+		let len = -1;
+		for (const line of header.split("\r\n")) if (line.toLowerCase().startsWith(CONTENT_LENGTH)) {
+			const n = Number.parseInt(line.slice(15).trim(), 10);
+			if (!Number.isFinite(n) || n < 0) throw new Error("invalid Content-Length");
+			len = n;
+		}
+		if (len < 0) throw new Error("missing Content-Length header");
+		const bodyStart = end + HEADER_TERMINATOR.length;
+		const bodyEnd = bodyStart + len;
+		if (this.buf.length < bodyEnd) return null;
+		const body = this.buf.subarray(bodyStart, bodyEnd).toString("utf8");
+		this.buf = this.buf.subarray(bodyEnd);
+		return JSON.parse(body);
+	}
+};
+var RpcSession = class {
+	decoder = new Decoder();
+	nextId = 1;
+	pending = /* @__PURE__ */ new Map();
+	onNotify = null;
+	onClose = null;
+	closed = false;
+	socket;
+	constructor(socket) {
+		this.socket = socket;
+		socket.on("data", (chunk) => this.handle(chunk));
+		socket.on("close", () => this.shutdown());
+		socket.on("error", () => this.shutdown());
+	}
+	handleNotifications(h) {
+		this.onNotify = h;
+	}
+	onClosed(h) {
+		this.onClose = h;
+	}
+	async request(method, params, timeoutMs) {
+		if (this.closed) throw new Error("session closed");
+		const id = this.nextId++;
+		const msg = {
+			jsonrpc: "2.0",
+			id,
+			method,
+			params
+		};
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			let timer;
+			const done = () => {
+				settled = true;
+				if (timer) clearTimeout(timer);
+			};
+			this.pending.set(id, {
+				resolve: (v) => {
+					if (settled) return;
+					done();
+					resolve(v);
+				},
+				reject: (e) => {
+					if (settled) return;
+					done();
+					reject(e);
+				}
+			});
+			if (timeoutMs !== void 0 && timeoutMs >= 0) {
+				timer = setTimeout(() => {
+					if (settled) return;
+					settled = true;
+					this.pending.delete(id);
+					reject(/* @__PURE__ */ new Error(`rpc ${method} timed out after ${timeoutMs}ms`));
+				}, timeoutMs);
+				timer.unref?.();
+			}
+			try {
+				this.socket.write(encode(msg));
+			} catch (err) {
+				if (settled) return;
+				done();
+				this.pending.delete(id);
+				reject(err);
+			}
+		});
+	}
+	notify(method, params) {
+		if (this.closed) return;
+		const msg = {
+			jsonrpc: "2.0",
+			method,
+			params
+		};
+		try {
+			this.socket.write(encode(msg));
+		} catch {}
+	}
+	close() {
+		this.shutdown();
+	}
+	handle(chunk) {
+		let msgs;
+		try {
+			msgs = this.decoder.push(chunk);
+		} catch {
+			this.shutdown();
+			return;
+		}
+		for (const m of msgs) {
+			if ("id" in m && "method" in m) continue;
+			if ("id" in m) {
+				const p = this.pending.get(m.id);
+				if (!p) continue;
+				this.pending.delete(m.id);
+				if (m.error) p.reject(new Error(m.error.message));
+				else p.resolve(m.result);
+			} else if ("method" in m) try {
+				this.onNotify?.(m.method, m.params);
+			} catch {}
+		}
+	}
+	shutdown() {
+		if (this.closed) return;
+		this.closed = true;
+		for (const p of this.pending.values()) p.reject(/* @__PURE__ */ new Error("session closed"));
+		this.pending.clear();
+		try {
+			this.socket.end();
+		} catch {}
+		try {
+			this.socket.destroy();
+		} catch {}
+		this.onClose?.();
+	}
+};
+const REPO = "photon-hq/tuichat";
+const VERSION_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+const DOWNLOAD_TIMEOUT_MS = 3e4;
+function targetSuffix() {
+	const key = `${process.platform}-${process.arch}`;
+	const t = {
+		"darwin-arm64": "darwin-arm64",
+		"darwin-x64": "darwin-x64",
+		"linux-x64": "linux-x64",
+		"linux-arm64": "linux-arm64",
+		"win32-x64": "windows-x64"
+	}[key];
+	if (!t) throw new Error(`tuichat: unsupported platform/arch: ${key}`);
+	return t;
+}
+function cacheDir(version) {
+	if (process.platform === "win32") return join(process.env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local"), "tuichat", `v${version}`);
+	if (process.platform === "darwin") return join(homedir(), "Library", "Caches", "tuichat", `v${version}`);
+	return join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tuichat", `v${version}`);
+}
+const LINE_SPLIT = /\r?\n/;
+const CHECKSUM_LINE = /^([a-f0-9]{64})\s+\*?(\S+)$/;
+function parseChecksums(text) {
+	const out = {};
+	for (const line of text.split(LINE_SPLIT)) {
+		const m = line.match(CHECKSUM_LINE);
+		if (m?.[1] && m[2]) out[m[2]] = m[1];
+	}
+	return out;
+}
+async function downloadVerified(version, filename) {
+	const base = `https://github.com/${REPO}/releases/download/v${version}`;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+	let sumsRes;
+	let binRes;
+	try {
+		[sumsRes, binRes] = await Promise.all([fetch(`${base}/SHA256SUMS`, { signal: controller.signal }), fetch(`${base}/${filename}`, { signal: controller.signal })]);
+	} catch (err) {
+		if (err instanceof Error && err.name === "AbortError") throw new Error(`tuichat: timed out fetching v${version} release assets after ${DOWNLOAD_TIMEOUT_MS}ms`);
+		throw err;
+	} finally {
+		clearTimeout(timer);
+	}
+	if (!sumsRes.ok) throw new Error(`tuichat: failed to fetch SHA256SUMS (v${version}): HTTP ${sumsRes.status}`);
+	if (!binRes.ok) throw new Error(`tuichat: failed to fetch ${filename} (v${version}): HTTP ${binRes.status}`);
+	const expected = parseChecksums(await sumsRes.text())[filename];
+	if (!expected) throw new Error(`tuichat: no checksum for ${filename} in SHA256SUMS (v${version})`);
+	const bytes = Buffer.from(await binRes.arrayBuffer());
+	const actual = createHash("sha256").update(bytes).digest("hex");
+	if (actual !== expected) throw new Error(`tuichat: checksum mismatch for ${filename} (expected ${expected}, got ${actual})`);
+	return bytes;
+}
+function writeBinary(path, bytes) {
+	const tmpPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+	try {
+		writeFileSync(tmpPath, bytes);
+		if (process.platform !== "win32") chmodSync(tmpPath, 493);
+		renameSync(tmpPath, path);
+	} catch (err) {
+		const renameErr = err;
+		try {
+			unlinkSync(tmpPath);
+		} catch {}
+		if (process.platform === "win32" && renameErr.code === "EEXIST" && existsSync(path)) return;
+		throw err;
+	}
+}
+async function resolveTuichatBinary(options = {}) {
+	const override = process.env.TUICHAT_BINARY;
+	if (override) {
+		if (!existsSync(override)) throw new Error(`tuichat: TUICHAT_BINARY=${override} does not exist`);
+		return override;
+	}
+	const version = options.version ?? process.env.TUICHAT_VERSION ?? "0.1.4";
+	if (!VERSION_RE.test(version)) throw new Error(`tuichat: invalid version "${version}" — expected semver like 0.1.4`);
+	const target = targetSuffix();
+	const filename = `tuichat-${target}${target.startsWith("windows") ? ".exe" : ""}`;
+	const dir = cacheDir(version);
+	const path = join(dir, filename);
+	if (!options.force && existsSync(path)) return path;
+	const bytes = await downloadVerified(version, filename);
+	mkdirSync(dir, { recursive: true });
+	writeBinary(path, bytes);
+	return path;
+}
+//#endregion
+//#region src/index.ts
+const SHUTDOWN_TIMEOUT_MS = 2e3;
+const SPAWN_CONNECT_TIMEOUT_MS = 1e4;
+const INITIALIZE_TIMEOUT_MS = 1e4;
+const commandSchema = z.object({
+	name: z.string().regex(/^\/[A-Za-z0-9_-]+$/, "command must start with /"),
+	description: z.string().optional()
+});
+const LOG_LEVELS = [
+	"log",
+	"info",
+	"warn",
+	"error",
+	"debug"
+];
+function installConsoleHijack(session) {
+	const originals = {};
+	let forwarding = false;
+	for (const level of LOG_LEVELS) {
+		originals[level] = console[level].bind(console);
+		console[level] = (...args) => {
+			if (forwarding) {
+				originals[level](...args);
+				return;
+			}
+			forwarding = true;
+			try {
+				const text = args.map((a) => typeof a === "string" ? a : inspect(a, {
+					depth: 3,
+					colors: false
+				})).join(" ");
+				session.notify("log", {
+					level,
+					text
+				});
+			} finally {
+				forwarding = false;
+			}
+		};
+	}
+	return { restore: () => {
+		for (const level of LOG_LEVELS) console[level] = originals[level];
+	} };
+}
+function generateChatId(client) {
+	while (client.knownChats.has(`chat-${client.nextChatIndex}`)) client.nextChatIndex += 1;
+	const id = `chat-${client.nextChatIndex}`;
+	client.nextChatIndex += 1;
+	client.knownChats.add(id);
+	return id;
+}
+function makeEventQueue() {
+	const queue = [];
+	const waiters = [];
+	let closed = false;
+	const drain = () => {
+		while (waiters.length > 0) waiters.shift()?.({
+			value: void 0,
+			done: true
+		});
+	};
+	return {
+		iter: { [Symbol.asyncIterator]() {
+			return {
+				next() {
+					if (closed && queue.length === 0) return Promise.resolve({
+						value: void 0,
+						done: true
+					});
+					const buffered = queue.shift();
+					if (buffered !== void 0) return Promise.resolve({
+						value: buffered,
+						done: false
+					});
+					return new Promise((resolve) => waiters.push(resolve));
+				},
+				return() {
+					closed = true;
+					drain();
+					return Promise.resolve({
+						value: void 0,
+						done: true
+					});
+				}
+			};
+		} },
+		push(v) {
+			if (closed) return;
+			const w = waiters.shift();
+			if (w) w({
+				value: v,
+				done: false
+			});
+			else queue.push(v);
+		},
+		close() {
+			closed = true;
+			drain();
+		}
+	};
+}
+async function spawnClient(options) {
+	const binary = await resolveTuichatBinary();
+	const server = createServer();
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen({
+			host: "127.0.0.1",
+			port: 0
+		}, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+	const addr = server.address();
+	if (!addr || typeof addr === "string") {
+		server.close();
+		throw new Error("tuichat: failed to bind adapter listener");
+	}
+	const host = "127.0.0.1";
+	const port = addr.port;
+	const proc = spawn(binary, ["--connect", `${host}:${port}`], { stdio: "inherit" });
+	proc.unref();
+	proc.once("exit", (code) => {
+		if (code !== 0 && code !== null) process.stderr.write(`[tuichat] subprocess exited with code ${code}\n`);
+	});
+	const session = new RpcSession(await new Promise((resolve, reject) => {
+		let settled = false;
+		const cleanup = () => {
+			clearTimeout(timer);
+			server.off("connection", onConnect);
+			server.off("error", onServerError);
+			proc.off("error", onProcError);
+			proc.off("exit", onProcExit);
+		};
+		const fail = (err, killProc) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			server.close();
+			if (killProc && !proc.killed) try {
+				proc.kill();
+			} catch {}
+			reject(err);
+		};
+		const succeed = (sock) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			server.close();
+			resolve(sock);
+		};
+		const onConnect = (sock) => succeed(sock);
+		const onServerError = (err) => fail(err, true);
+		const onProcError = (err) => fail(err, false);
+		const onProcExit = (code, signal) => fail(/* @__PURE__ */ new Error(`tuichat: subprocess exited before connecting (code=${code ?? "null"}, signal=${signal ?? "null"})`), false);
+		const timer = setTimeout(() => {
+			fail(/* @__PURE__ */ new Error(`tuichat: subprocess did not connect within ${SPAWN_CONNECT_TIMEOUT_MS}ms`), true);
+		}, SPAWN_CONNECT_TIMEOUT_MS);
+		server.once("connection", onConnect);
+		server.once("error", onServerError);
+		proc.once("error", onProcError);
+		proc.once("exit", onProcExit);
+	}));
+	const eventsQ = makeEventQueue();
+	session.handleNotifications((method, params) => {
+		if (method === "streamEnd") {
+			eventsQ.close();
+			return;
+		}
+		if (method === "message") {
+			eventsQ.push({
+				kind: "message",
+				value: params
+			});
+			return;
+		}
+		if (method === "reaction") {
+			eventsQ.push({
+				kind: "reaction",
+				value: params
+			});
+			return;
+		}
+	});
+	let hijack;
+	session.onClosed(() => {
+		hijack?.restore();
+		eventsQ.close();
+	});
+	try {
+		await session.request("initialize", {
+			commands: options.commands,
+			clientInfo: {
+				name: "spectrum-ts",
+				version: "terminal-provider"
+			}
+		}, INITIALIZE_TIMEOUT_MS);
+	} catch (err) {
+		session.close();
+		try {
+			proc.kill("SIGTERM");
+		} catch {}
+		throw err;
+	}
+	hijack = installConsoleHijack(session);
+	return {
+		hijack,
+		proc,
+		session,
+		events: eventsQ.iter,
+		knownChats: /* @__PURE__ */ new Set(),
+		nextChatIndex: 1
+	};
+}
+function parseTimestamp(s) {
+	const t = Date.parse(s);
+	return Number.isNaN(t) ? /* @__PURE__ */ new Date() : new Date(t);
+}
+function buildOutboundRecord(result, content, spaceId) {
+	return {
+		id: result.id,
+		content,
+		space: { id: spaceId },
+		timestamp: parseTimestamp(result.timestamp)
+	};
+}
+function reactionTargetFromProtocol(reaction) {
+	return {
+		id: reaction.messageId,
+		content: asCustom({
+			terminal_type: "reaction-target",
+			stub: true
+		}),
+		sender: { id: "__unknown__" },
+		space: { id: reaction.spaceId },
+		timestamp: parseTimestamp(reaction.timestamp)
+	};
+}
+function reactionContentFromProtocol(reaction) {
+	return reactionSchema.parse({
+		type: "reaction",
+		emoji: reaction.reaction,
+		target: reactionTargetFromProtocol(reaction)
+	});
+}
+async function spectrumToProtocol(content) {
+	if (content.type === "text" || content.type === "custom") return content;
+	if (content.type === "attachment") {
+		const buf = await content.read();
+		return {
+			type: "attachment",
+			name: content.name,
+			mimeType: content.mimeType,
+			size: content.size,
+			bytes: buf.toString("base64")
+		};
+	}
+	if (content.type === "voice") {
+		const buf = await content.read();
+		return {
+			type: "voice",
+			name: content.name,
+			mimeType: content.mimeType,
+			size: content.size,
+			bytes: buf.toString("base64")
+		};
+	}
+	if (content.type === "contact") return {
+		type: "contact",
+		name: content.name ? {
+			formatted: content.name.formatted,
+			first: content.name.first,
+			last: content.name.last
+		} : void 0,
+		vcard: await toVCard(content)
+	};
+	if (content.type === "app") return {
+		type: "text",
+		text: await content.url()
+	};
+	throw UnsupportedError.content(content.type, "Terminal");
+}
+function protocolToSpectrum(p) {
+	if (p.type === "text" || p.type === "custom") return p;
+	if (p.type === "attachment" || p.type === "voice") {
+		const path = p.path;
+		const bytesB64 = p.bytes;
+		let cached;
+		const readBytes = () => {
+			if (cached) return cached;
+			if (bytesB64) cached = Promise.resolve(Buffer.from(bytesB64, "base64"));
+			else if (path) cached = import("node:fs/promises").then((m) => m.readFile(path));
+			else cached = Promise.reject(/* @__PURE__ */ new Error(`${p.type} has neither path nor bytes`));
+			return cached;
+		};
+		const stream = async () => {
+			if (path) {
+				const [{ createReadStream }, { Readable }] = await Promise.all([import("node:fs"), import("node:stream")]);
+				return Readable.toWeb(createReadStream(path));
+			}
+			const buf = await readBytes();
+			return new ReadableStream({ start(ctrl) {
+				ctrl.enqueue(new Uint8Array(buf));
+				ctrl.close();
+			} });
+		};
+		if (p.type === "attachment") return asAttachment({
+			name: p.name,
+			mimeType: p.mimeType,
+			size: p.size,
+			read: readBytes,
+			stream
+		});
+		return asVoice({
+			name: p.name,
+			mimeType: p.mimeType,
+			size: p.size,
+			read: readBytes,
+			stream
+		});
+	}
+	if (p.type === "contact") {
+		if (p.vcard) try {
+			return asContact(fromVCard(p.vcard));
+		} catch {}
+		return asContact({ name: p.name });
+	}
+	return {
+		type: "custom",
+		raw: p
+	};
+}
+const terminal = definePlatform("Terminal", {
+	config: z.object({ commands: z.array(commandSchema).optional() }),
+	message: { schema: z.object({ replyTo: z.object({ messageId: z.string() }).optional() }) },
+	lifecycle: {
+		createClient: async ({ config }) => await spawnClient({ commands: config.commands }),
+		destroyClient: async ({ client }) => {
+			client.hijack.restore();
+			try {
+				await client.session.request("shutdown", void 0, SHUTDOWN_TIMEOUT_MS);
+			} catch {}
+			client.session.close();
+			try {
+				client.proc.kill("SIGTERM");
+			} catch {}
+		}
+	},
+	user: { resolve: async ({ input }) => ({ id: input.userID }) },
+	space: {
+		create: async ({ client }) => {
+			const id = generateChatId(client);
+			client.knownChats.add(id);
+			await client.session.request("ensureSpace", { id });
+			return { id };
+		},
+		get: async ({ client, input }) => {
+			client.knownChats.add(input.id);
+			await client.session.request("ensureSpace", { id: input.id });
+			return { id: input.id };
+		}
+	},
+	messages({ client }) {
+		return stream((emit, end) => {
+			const iterator = client.events[Symbol.asyncIterator]();
+			const pump = (async () => {
+				try {
+					let result = await iterator.next();
+					while (!result.done) {
+						const evt = result.value;
+						if (evt.kind === "message") {
+							const msg = evt.value;
+							client.knownChats.add(msg.spaceId);
+							await emit({
+								id: msg.id,
+								content: protocolToSpectrum(msg.content),
+								sender: { id: msg.senderId },
+								space: { id: msg.spaceId },
+								timestamp: parseTimestamp(msg.timestamp),
+								...msg.replyTo ? { replyTo: msg.replyTo } : {}
+							});
+						} else {
+							const r = evt.value;
+							client.knownChats.add(r.spaceId);
+							await emit({
+								id: `reaction:${r.messageId}:${r.reaction}:${r.timestamp}`,
+								content: reactionContentFromProtocol(r),
+								sender: { id: r.senderId },
+								space: { id: r.spaceId },
+								timestamp: parseTimestamp(r.timestamp)
+							});
+						}
+						result = await iterator.next();
+					}
+					end();
+				} catch (error) {
+					end(error);
+				}
+			})();
+			return async () => {
+				await iterator.return?.();
+				await pump.catch(() => void 0);
+			};
+		});
+	},
+	send: async ({ client, content, space }) => {
+		if (content.type === "reply") {
+			const inner = await spectrumToProtocol(content.content);
+			return buildOutboundRecord(await client.session.request("replyToMessage", {
+				spaceId: space.id,
+				messageId: content.target.id,
+				content: inner
+			}), content.content, space.id);
+		}
+		if (content.type === "reaction") {
+			await client.session.request("reactToMessage", {
+				spaceId: space.id,
+				messageId: content.target.id,
+				reaction: content.emoji
+			});
+			const timestamp = /* @__PURE__ */ new Date();
+			return {
+				id: `reaction:${content.target.id}:${content.emoji}:${timestamp.toISOString()}`,
+				content,
+				space: { id: space.id },
+				timestamp
+			};
+		}
+		if (content.type === "typing") {
+			const method = content.state === "start" ? "startTyping" : "stopTyping";
+			await client.session.request(method, { spaceId: space.id });
+			return;
+		}
+		const proto = await spectrumToProtocol(content);
+		return buildOutboundRecord(await client.session.request("send", {
+			spaceId: space.id,
+			content: proto
+		}), content, space.id);
+	}
+});
+//#endregion
+export { terminal };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@spectrum-ts/terminal",
+  "version": "5.0.0",
+  "description": "Terminal (tuichat) provider for spectrum-ts — chat with your agent from the command line.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/photon-hq/spectrum-ts.git",
+    "directory": "packages/terminal"
+  },
+  "homepage": "https://photon.codes/spectrum",
+  "bugs": {
+    "url": "https://github.com/photon-hq/spectrum-ts/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "spectrum": {
+    "key": "terminal",
+    "import": "terminal",
+    "label": "Terminal"
+  },
+  "dependencies": {
+    "zod": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@spectrum-ts/core": "^5.0.0",
+    "typescript": "^5 || ^6.0.0"
+  },
+  "license": "MIT"
+}