t3code-relay 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nick Breaton
+
+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 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

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# T3 Code Relay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An ACP agent designed to hand off messages from an ACP client, like [Zed](https://zed.dev/), to an open [T3 Code](https://t3.codes/) thread.
+
+![A prompt about selected code in Zed, with a hand-drawn arrow to the same message arriving in a T3 Code thread.](assets/hero.png)
+
+> [!NOTE]
+> This is not designed to implement the full Agent Client Protocol. T3 Code responses will not be returned to the client, as the intent is to continue the conversation within T3 Code.
+
+
+
+## Setup
+
+Run it from npm with `npx`. Here's an example setup for Zed's `settings.json`:
+
+```json
+"agent_servers": {
+  "T3 Code": {
+    "type": "custom",
+    "command": "npx",
+    "args": ["-y", "t3code-relay"]
+  }
+}
+```
+
+### Options
+
+| Option | Description |
+| --- | --- |
+| `--t3-bin <path>` | Use a specific `t3` CLI. |
+| `--no-focus` | Don't bring T3 Code into focus on the target thread when sending a message. |

package/dist/index.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+import * as acp from "@agentclientprotocol/sdk";
+import { spawn } from "node:child_process";
+import { realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, join, sep } from "node:path";
+import { Readable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+const { values: flags } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        "t3-bin": { type: "string" },
+        debug: { type: "boolean", default: false },
+        "dry-run": { type: "boolean", default: false },
+        "no-focus": { type: "boolean", default: false },
+    },
+});
+// T3's installer doesn't put its CLI on PATH, so its install folder is searched last.
+process.env.PATH = [process.env.PATH, join(homedir(), ".t3/bin")].filter(Boolean).join(delimiter);
+const T3 = flags["t3-bin"] ?? "t3";
+const SCRATCH = real(join(process.env.T3CODE_HOME ?? join(homedir(), ".t3"), "scratch"));
+// How many threads to look up at once when matching workspaces.
+const SCAN_BATCH = 5;
+// How many threads to offer when several match; each one becomes a button in the ACP client.
+const MAX_CHOICES = 4;
+const DONT_SEND = "dont-send";
+// Logs go to stderr; stdout carries the ACP protocol.
+const log = (...args) => console.error("[t3code-relay]", ...args);
+// threadId is the thread the user chose for this chat, when they had to choose.
+const sessions = new Map();
+// Run a command to completion and capture its output.
+function run(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { cwd: options.cwd });
+        let out = "";
+        let err = "";
+        child.stdout.setEncoding("utf8").on("data", (chunk) => (out += chunk));
+        child.stderr.setEncoding("utf8").on("data", (chunk) => (err += chunk));
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code, out, err }));
+        // A child that exits without reading stdin surfaces through its exit code,
+        // so the resulting EPIPE must not take the relay down.
+        child.stdin.on("error", (e) => log("stdin write failed:", e));
+        child.stdin.end(options.stdin);
+    });
+}
+async function t3(args, cwd, stdin) {
+    const { code, out, err } = await run(T3, args, { cwd, stdin });
+    if (code !== 0)
+        throw new Error(`t3 ${args.join(" ")} failed (${code}): ${err.trim() || out.trim()}`);
+    return out;
+}
+function real(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+const contains = (root, p) => p === root || p.startsWith(root.endsWith(sep) ? root : root + sep);
+const newestFirst = (a, b) => b.updatedAt.localeCompare(a.updatedAt);
+// Nearest existing directory for a file or directory path.
+function existingDir(p) {
+    for (let d = p;; d = dirname(d)) {
+        try {
+            return real(statSync(d).isDirectory() ? d : dirname(d));
+        }
+        catch { }
+        if (dirname(d) === d)
+            return undefined;
+    }
+}
+async function git(dir, args) {
+    const { code, out } = await run("git", ["-C", dir, ...args]);
+    return code === 0 && out.trim() ? out.trim() : undefined;
+}
+// For a path in a git checkout: the main checkout, and whether the path is in a linked worktree.
+async function gitInfo(dir) {
+    const [top, common] = await Promise.all([
+        git(dir, ["rev-parse", "--show-toplevel"]),
+        git(dir, ["rev-parse", "--path-format=absolute", "--git-common-dir"]),
+    ]);
+    const main = common?.endsWith("/.git") ? real(dirname(common)) : undefined;
+    return { main, inLinkedWorktree: !!top && !!main && real(top) !== main };
+}
+// A thread's worktreePath rarely changes, so cache it briefly to keep sends fast.
+const worktreeCache = new Map();
+async function worktreeOf(t) {
+    const hit = worktreeCache.get(t.threadId);
+    if (hit && Date.now() - hit.at < 60_000)
+        return hit.path;
+    const { thread } = JSON.parse(await t3(["thread", "show", t.threadId, "--messages", "0", "--json"], homedir()));
+    const path = thread.worktreePath ? real(thread.worktreePath) : null;
+    worktreeCache.set(t.threadId, { at: Date.now(), path });
+    return path;
+}
+// Find the threads whose workspace contains the given paths (quoted files first,
+// then the ACP client's cwd), newest first. The first path with any match decides.
+// A path in a T3 worktree or scratch folder matches the thread working there;
+// a path in the main checkout matches threads without a worktree.
+// Workspace matching only considers open (non-settled) threads.
+// No match returns an empty list, so a new thread can start in the project
+// folder. The t3 CLI can't start one in an existing worktree, so that's an error.
+async function findThreads(paths) {
+    let lastError;
+    let firstProject;
+    const seen = new Set();
+    for (const raw of paths) {
+        const dir = existingDir(raw);
+        if (!dir || seen.has(dir))
+            continue;
+        seen.add(dir);
+        const { main, inLinkedWorktree } = await gitInfo(dir);
+        let threads;
+        let projectDir;
+        for (const p of new Set([dir, main].filter((x) => !!x))) {
+            try {
+                threads = JSON.parse(await t3(["thread", "list", "--project", p, "--json"], p));
+                projectDir = p;
+                break;
+            }
+            catch (e) {
+                lastError = e;
+            }
+        }
+        if (!threads || !projectDir)
+            continue;
+        const candidates = threads.filter((t) => !t.parentThreadId).sort(newestFirst);
+        firstProject ??= { dir, projectDir, inLinkedWorktree, latest: candidates[0] };
+        // Scratch folders are named "<date>-<slug>-<last 8 chars of the thread id>".
+        const suffix = t3ScratchSuffix(dir);
+        const owner = suffix && candidates.find((t) => t.threadId.endsWith(suffix));
+        if (owner)
+            return { matches: [{ thread: owner, reason: `owns scratch folder …-${suffix}` }], projectDir };
+        // Only open (non-settled) threads are matched by workspace.
+        const scan = candidates.filter((t) => !t.settled);
+        const matches = [];
+        for (let i = 0; i < scan.length; i += SCAN_BATCH) {
+            const batch = scan.slice(i, i + SCAN_BATCH);
+            const wts = await Promise.all(batch.map((t) => worktreeOf(t).catch(() => undefined)));
+            batch.forEach((thread, idx) => {
+                const wt = wts[idx];
+                if (wt ? contains(wt, dir) : wt === null && !inLinkedWorktree) {
+                    matches.push({ thread, reason: wt ? `works in ${wt}` : "works in the main checkout" });
+                }
+            });
+        }
+        if (matches.length > 0)
+            return { matches, projectDir };
+    }
+    // No project at all (or T3 isn't running): surface the t3 error itself.
+    if (!firstProject && lastError)
+        throw lastError;
+    if (firstProject?.inLinkedWorktree) {
+        throw new Error(`No open T3 thread is working in ${firstProject.dir}, and t3 can't start one in an existing worktree.`);
+    }
+    if (firstProject)
+        return { matches: [], projectDir: firstProject.projectDir, latest: firstProject.latest };
+    throw new Error(`No T3 thread is working in ${[...seen].join(" or ") || "these paths"}.`);
+}
+function t3ScratchSuffix(dir) {
+    if (!contains(SCRATCH, dir) || dir === SCRATCH)
+        return undefined;
+    const folder = dir.slice(SCRATCH.length + 1).split(sep)[0];
+    return /-([0-9a-f]{8})$/.exec(folder)?.[1];
+}
+// Bring the T3 Code desktop app to the thread. Thread links look like
+// https://app.t3.codes/threads/<environmentId>/<threadId>, or without the
+// /threads prefix on a local server; the app only accepts
+// t3code://threads/<environmentId>/<threadId>.
+async function openInT3(thread) {
+    if (flags["no-focus"] || !thread.link)
+        return;
+    const url = `t3code://threads${new URL(thread.link).pathname.replace(/^\/threads(?=\/)/, "")}`;
+    // Opening is best effort and runs alongside the send, so it must never reject.
+    try {
+        const { code } = await run("open", [url]);
+        if (code !== 0)
+            log(`couldn't open ${url} (exit ${code})`);
+    }
+    catch (e) {
+        log(`couldn't open ${url}`, e);
+    }
+}
+async function startThread(projectDir, message, latest) {
+    const start = (model) => t3(["thread", "start", ...model, projectDir, "-"], projectDir, message);
+    let output;
+    try {
+        output = await start([]);
+    }
+    catch (e) {
+        // A project with no default model needs one named, so reuse its latest thread's.
+        // t3 rejects the start before launching anything, so retrying can't duplicate it.
+        if (!String(e).includes("no default model") || !latest?.providerInstanceId || !latest.model)
+            throw e;
+        output = await start(["--provider", latest.providerInstanceId, "--model", latest.model]);
+    }
+    const threadId = output.trim();
+    log(`started ${threadId} in ${projectDir}`);
+    // The message has already landed, so a failure here must not be reported as a failed send.
+    try {
+        if (flags["no-focus"])
+            return;
+        const { thread } = JSON.parse(await t3(["thread", "show", threadId, "--messages", "0", "--json"], projectDir));
+        await openInT3(thread);
+    }
+    catch (e) {
+        log(`couldn't open new thread ${threadId}`, e);
+    }
+}
+function filePath(uri) {
+    return uri.startsWith("file://") ? fileURLToPath(uri.split("#")[0]) : undefined;
+}
+function displayPath(uri, cwd) {
+    let path = uri;
+    if (uri.startsWith("file://")) {
+        const [base, frag] = uri.split("#");
+        path = fileURLToPath(base) + (frag ? `#${frag}` : "");
+    }
+    return path.startsWith(cwd + "/") ? path.slice(cwd.length + 1) : path;
+}
+// Flatten the prompt's content blocks into one markdown message.
+function toMarkdown(blocks, cwd) {
+    const parts = [];
+    for (const b of blocks) {
+        switch (b.type) {
+            case "text":
+                parts.push(b.text);
+                break;
+            case "resource":
+                if ("text" in b.resource) {
+                    parts.push(`\`${displayPath(b.resource.uri, cwd)}\`\n\`\`\`\n${b.resource.text}\n\`\`\``);
+                }
+                else {
+                    parts.push(`\`${displayPath(b.resource.uri, cwd)}\` (binary)`);
+                }
+                break;
+            case "resource_link":
+                parts.push(`\`${displayPath(b.uri, cwd)}\``);
+                break;
+            default:
+                parts.push(`[${b.type} omitted]`);
+        }
+    }
+    return parts.join("\n\n").trim();
+}
+const app = acp
+    .agent({ name: "t3code-relay" })
+    .onRequest(acp.methods.agent.initialize, () => ({
+    protocolVersion: acp.PROTOCOL_VERSION,
+    agentCapabilities: {
+        // Load and resume are accepted so the ACP client can reopen old chats after a restart.
+        // The relay keeps no history, so nothing is replayed and they reopen empty.
+        loadSession: true,
+        sessionCapabilities: { resume: {} },
+        promptCapabilities: { embeddedContext: true, image: false, audio: false },
+    },
+    agentInfo: { name: "t3code-relay", title: "T3 Code Relay", version: "0.1.0" },
+    authMethods: [],
+}))
+    .onRequest(acp.methods.agent.session.new, ({ params }) => {
+    const sessionId = crypto.randomUUID();
+    sessions.set(sessionId, { cwd: params.cwd });
+    return { sessionId };
+})
+    .onRequest(acp.methods.agent.session.load, ({ params }) => {
+    sessions.set(params.sessionId, { cwd: params.cwd });
+    return {};
+})
+    .onRequest(acp.methods.agent.session.resume, ({ params }) => {
+    sessions.set(params.sessionId, { cwd: params.cwd });
+    return {};
+})
+    .onRequest(acp.methods.agent.session.prompt, async ({ params, client }) => {
+    // A chat the ACP client reopened without loading it first still works; the
+    // ACP client starts the relay in the project folder, so that stands in for
+    // the chat's cwd.
+    const session = sessions.get(params.sessionId) ?? { cwd: process.cwd() };
+    sessions.set(params.sessionId, session);
+    if (flags.debug)
+        log("prompt", JSON.stringify(params.prompt));
+    const say = (text) => client.notify(acp.methods.client.session.update, {
+        sessionId: params.sessionId,
+        update: { sessionUpdate: "agent_message_chunk", content: { type: "text", text } },
+    });
+    // ACP has no general "pick one" request that clients reliably support, so
+    // the choice is presented as a permission prompt on a placeholder tool call.
+    const askWhichThread = async (matches) => {
+        const toolCallId = crypto.randomUUID();
+        // The SDK's method-keyed overload infers this response as unknown, so name the types.
+        const { outcome } = await client.request(acp.methods.client.session.requestPermission, {
+            sessionId: params.sessionId,
+            toolCall: {
+                toolCallId,
+                title: "Several T3 threads are open in this workspace. Which one should get this?",
+                kind: "other",
+                status: "pending",
+            },
+            options: [
+                ...matches
+                    .slice(0, MAX_CHOICES)
+                    .map((m) => ({ optionId: m.thread.threadId, name: m.thread.title, kind: "allow_once" })),
+                { optionId: DONT_SEND, name: "Don't send", kind: "reject_once" },
+            ],
+        });
+        const chosen = outcome.outcome === "selected" ? matches.find((m) => m.thread.threadId === outcome.optionId) : undefined;
+        // The client leaves the placeholder running until it's told otherwise.
+        await client.notify(acp.methods.client.session.update, {
+            sessionId: params.sessionId,
+            update: {
+                sessionUpdate: "tool_call_update",
+                toolCallId,
+                status: chosen ? "completed" : "failed",
+                title: chosen ? `Sending to ${chosen.thread.title}` : "Not sent",
+            },
+        });
+        return chosen;
+    };
+    const message = toMarkdown(params.prompt, session.cwd);
+    if (!message) {
+        await say("Nothing to send.");
+        return { stopReason: "end_turn" };
+    }
+    const quoted = params.prompt.flatMap((b) => {
+        const uri = b.type === "resource" ? b.resource.uri : b.type === "resource_link" ? b.uri : undefined;
+        const path = uri && filePath(uri);
+        return path ? [path] : [];
+    });
+    try {
+        const { matches, projectDir, latest } = await findThreads([...quoted, session.cwd]);
+        if (matches.length === 0) {
+            if (flags["dry-run"])
+                await say(`Would start a new thread in ${projectDir}`);
+            else
+                await startThread(projectDir, message, latest);
+            return { stopReason: "end_turn" };
+        }
+        // A choice made earlier in this chat holds for as long as that thread still matches.
+        const match = matches.length === 1
+            ? matches[0]
+            : (matches.find((m) => m.thread.threadId === session.threadId) ?? (await askWhichThread(matches)));
+        if (!match)
+            return { stopReason: "cancelled" };
+        if (matches.length > 1)
+            session.threadId = match.thread.threadId;
+        const { thread, reason } = match;
+        if (flags["dry-run"]) {
+            await say(`Would send to **${thread.title}** (${reason})`);
+        }
+        else {
+            // Jump to the thread as soon as it's known; the message lands a moment later.
+            const opening = openInT3(thread);
+            await t3(["thread", "send", thread.threadId, "-"], projectDir, message);
+            log(`sent to ${thread.title} (${thread.threadId}): ${reason}`);
+            await opening;
+        }
+    }
+    catch (e) {
+        // Only failures get a reply, so the message isn't silently lost.
+        log(e);
+        await say(`Couldn't forward to T3: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return { stopReason: "end_turn" };
+})
+    .onNotification(acp.methods.agent.session.cancel, () => { });
+const stdout = new WritableStream({
+    write: (chunk) => new Promise((resolve) => process.stdout.write(chunk, () => resolve())),
+});
+const stdin = Readable.toWeb(process.stdin);
+app.connect(acp.ndJsonStream(stdout, stdin));

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "t3code-relay",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "An ACP agent that hands off messages from an ACP client, like Zed, to an open T3 Code thread.",
+  "keywords": [
+    "acp",
+    "agent-client-protocol",
+    "t3code",
+    "zed"
+  ],
+  "homepage": "https://github.com/nickbreaton/t3code-relay#readme",
+  "bugs": {
+    "url": "https://github.com/nickbreaton/t3code-relay/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nickbreaton/t3code-relay.git"
+  },
+  "license": "MIT",
+  "author": "Nick Breaton",
+  "type": "module",
+  "bin": {
+    "t3code-relay": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "lint": "oxlint",
+    "prepack": "npm run build",
+    "test": "node --test --experimental-test-module-mocks src/index.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^2.4.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@oxlint/plugins": "1.91.0",
+    "@types/node": "^26.6.6",
+    "oxlint": "1.91.0",
+    "typescript": "^7.0.2"
+  }
+}