talking-stick 0.1.0-alpha

package/dist/install.js

@@ -0,0 +1,272 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const SUPPORTED_HARNESSES = ["claude-code", "codex", "gemini", "opencode"];
+export const DEFAULT_SERVER_NAME = "talking-stick";
+export const DEFAULT_SERVER_COMMAND = ["tt", "mcp"];
+function resolveOptions(options = {}) {
+    return {
+        env: options.env ?? process.env,
+        platform: options.platform ?? process.platform,
+        homeDir: options.homeDir ?? os.homedir(),
+        serverName: options.serverName ?? DEFAULT_SERVER_NAME,
+        serverCommand: options.serverCommand ?? DEFAULT_SERVER_COMMAND,
+        hooks: {
+            run: options.run ?? defaultRun,
+            readFile: options.readFile ?? defaultReadFile,
+            writeFile: options.writeFile ?? defaultWriteFile,
+            ensureDir: options.ensureDir ?? defaultEnsureDir,
+            which: options.which ?? defaultWhich
+        }
+    };
+}
+function defaultRun(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], ...options });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        child.stdout?.on("data", (chunk) => stdoutChunks.push(chunk));
+        child.stderr?.on("data", (chunk) => stderrChunks.push(chunk));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            resolve({
+                exitCode: code ?? 0,
+                stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+                stderr: Buffer.concat(stderrChunks).toString("utf8")
+            });
+        });
+    });
+}
+function defaultReadFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function defaultWriteFile(filePath, data) {
+    fs.writeFileSync(filePath, data);
+}
+function defaultEnsureDir(dirPath) {
+    fs.mkdirSync(dirPath, { recursive: true });
+}
+function defaultWhich(binary) {
+    const pathEnv = process.env.PATH ?? "";
+    const separator = process.platform === "win32" ? ";" : ":";
+    const extensions = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+    for (const dir of pathEnv.split(separator)) {
+        if (!dir)
+            continue;
+        for (const ext of extensions) {
+            const candidate = path.join(dir, binary + ext);
+            if (fs.existsSync(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+export function resolveOpencodeConfigPath(options = {}) {
+    const resolved = resolveOptions(options);
+    const xdg = resolved.env.XDG_CONFIG_HOME?.trim();
+    const base = xdg && xdg.length > 0 ? xdg : path.join(resolved.homeDir, ".config");
+    return path.join(base, "opencode", "opencode.json");
+}
+export function planInstall(harness, options = {}) {
+    const resolved = resolveOptions(options);
+    const [serverBin, ...serverArgs] = resolved.serverCommand;
+    if (!serverBin)
+        throw new Error("serverCommand must include at least the binary");
+    switch (harness) {
+        case "claude-code":
+            return {
+                kind: "exec",
+                harness,
+                command: "claude",
+                args: ["mcp", "add", "-s", "user", resolved.serverName, "--", serverBin, ...serverArgs],
+                description: `claude mcp add -s user ${resolved.serverName} -- ${resolved.serverCommand.join(" ")}`
+            };
+        case "codex":
+            return {
+                kind: "exec",
+                harness,
+                command: "codex",
+                args: ["mcp", "add", resolved.serverName, "--", serverBin, ...serverArgs],
+                description: `codex mcp add ${resolved.serverName} -- ${resolved.serverCommand.join(" ")}`
+            };
+        case "gemini":
+            return {
+                kind: "exec",
+                harness,
+                command: "gemini",
+                args: ["mcp", "add", "-s", "user", "-t", "stdio", resolved.serverName, serverBin, ...serverArgs],
+                description: `gemini mcp add -s user -t stdio ${resolved.serverName} ${resolved.serverCommand.join(" ")}`
+            };
+        case "opencode": {
+            const filePath = resolveOpencodeConfigPath(options);
+            return {
+                kind: "file-patch",
+                harness,
+                filePath,
+                description: `merge mcp.${resolved.serverName} into ${filePath}`,
+                apply: () => patchOpencodeConfig(filePath, resolved, "install")
+            };
+        }
+        default:
+            throw new Error(`Unknown harness: ${harness}`);
+    }
+}
+export function planUninstall(harness, options = {}) {
+    const resolved = resolveOptions(options);
+    switch (harness) {
+        case "claude-code":
+            return {
+                kind: "exec",
+                harness,
+                command: "claude",
+                args: ["mcp", "remove", "-s", "user", resolved.serverName],
+                description: `claude mcp remove -s user ${resolved.serverName}`
+            };
+        case "codex":
+            return {
+                kind: "exec",
+                harness,
+                command: "codex",
+                args: ["mcp", "remove", resolved.serverName],
+                description: `codex mcp remove ${resolved.serverName}`
+            };
+        case "gemini":
+            return {
+                kind: "exec",
+                harness,
+                command: "gemini",
+                args: ["mcp", "remove", "-s", "user", resolved.serverName],
+                description: `gemini mcp remove -s user ${resolved.serverName}`
+            };
+        case "opencode": {
+            const filePath = resolveOpencodeConfigPath(options);
+            return {
+                kind: "file-patch",
+                harness,
+                filePath,
+                description: `remove mcp.${resolved.serverName} from ${filePath}`,
+                apply: () => patchOpencodeConfig(filePath, resolved, "uninstall")
+            };
+        }
+        default:
+            throw new Error(`Unknown harness: ${harness}`);
+    }
+}
+function patchOpencodeConfig(filePath, resolved, mode) {
+    const existing = resolved.hooks.readFile(filePath);
+    const config = existing ? parseJsonOrThrow(existing, filePath) : {};
+    const mcp = isPlainObject(config.mcp) ? { ...config.mcp } : {};
+    if (mode === "install") {
+        mcp[resolved.serverName] = {
+            type: "local",
+            command: [...resolved.serverCommand],
+            enabled: true
+        };
+    }
+    else {
+        delete mcp[resolved.serverName];
+    }
+    config.mcp = mcp;
+    resolved.hooks.ensureDir(path.dirname(filePath));
+    resolved.hooks.writeFile(filePath, JSON.stringify(config, null, 2) + "\n");
+}
+function parseJsonOrThrow(raw, filePath) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isPlainObject(parsed)) {
+            throw new Error(`${filePath} is not a JSON object`);
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new Error(`Failed to parse ${filePath} as JSON: ${error.message}`);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function detectHarness(harness, options = {}) {
+    const resolved = resolveOptions(options);
+    switch (harness) {
+        case "claude-code": {
+            const bin = resolved.hooks.which("claude");
+            return { harness, detected: bin !== null, evidence: bin ?? "claude not on PATH" };
+        }
+        case "codex": {
+            const bin = resolved.hooks.which("codex");
+            return { harness, detected: bin !== null, evidence: bin ?? "codex not on PATH" };
+        }
+        case "gemini": {
+            const bin = resolved.hooks.which("gemini");
+            return { harness, detected: bin !== null, evidence: bin ?? "gemini not on PATH" };
+        }
+        case "opencode": {
+            const bin = resolved.hooks.which("opencode");
+            if (bin)
+                return { harness, detected: true, evidence: bin };
+            const configPath = resolveOpencodeConfigPath(options);
+            const existing = resolved.hooks.readFile(configPath);
+            if (existing !== null)
+                return { harness, detected: true, evidence: configPath };
+            return { harness, detected: false, evidence: "opencode not on PATH and no config file" };
+        }
+        default:
+            throw new Error(`Unknown harness: ${harness}`);
+    }
+}
+export async function runAction(action, options = {}) {
+    const resolved = resolveOptions(options);
+    if (action.kind === "exec") {
+        const result = await resolved.hooks.run(action.command, action.args);
+        if (result.exitCode === 0) {
+            return {
+                harness: action.harness,
+                ok: true,
+                action,
+                message: result.stdout.trim() || `${action.command} succeeded`
+            };
+        }
+        return {
+            harness: action.harness,
+            ok: false,
+            action,
+            message: (result.stderr.trim() || result.stdout.trim() || `${action.command} exited with code ${result.exitCode}`)
+        };
+    }
+    try {
+        action.apply();
+        return {
+            harness: action.harness,
+            ok: true,
+            action,
+            message: `Updated ${action.filePath}`
+        };
+    }
+    catch (error) {
+        return {
+            harness: action.harness,
+            ok: false,
+            action,
+            message: error.message
+        };
+    }
+}
+export function parseHarnessList(values) {
+    const result = [];
+    for (const value of values) {
+        if (!SUPPORTED_HARNESSES.includes(value)) {
+            throw new Error(`Unknown harness: ${value}. Supported: ${SUPPORTED_HARNESSES.join(", ")}`);
+        }
+        if (!result.includes(value))
+            result.push(value);
+    }
+    return result;
+}

package/dist/mcp-server.js

@@ -0,0 +1,171 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { isProtocolError } from "./errors.js";
+import { deriveMcpHarnessIdentity } from "./identity.js";
+import { createSystemProcessInspector } from "./process-utils.js";
+import { TalkingStickCommands } from "./commands.js";
+import { TalkingStickService } from "./service.js";
+const handoffSchema = z
+    .object({
+    status: z.string(),
+    next_action: z.string(),
+    artifacts: z
+        .array(z.object({
+        path: z.string(),
+        lines: z.array(z.number().int()).length(2).optional(),
+        role: z.enum(["examine", "review", "edit", "context", "output"]),
+        note: z.string().optional()
+    }))
+        .optional(),
+    open_questions: z.array(z.string()).optional(),
+    do_not: z.array(z.string()).optional()
+})
+    .passthrough();
+export function createMcpServer(service = new TalkingStickService()) {
+    const commands = new TalkingStickCommands(service);
+    const resolveConnectionIdentity = createConnectionIdentityResolver();
+    const server = new McpServer({
+        name: "talking-stick",
+        version: "0.1.0-alpha"
+    });
+    server.registerTool("list_rooms", {
+        title: "List Rooms",
+        description: "List talking-stick rooms, optionally scoped to a path.",
+        inputSchema: {
+            context_path: z.string().optional()
+        }
+    }, async (input) => toolJson(() => service.listRooms(input)));
+    server.registerTool("join_path", {
+        title: "Join Path",
+        description: "Join the room resolved from an invocation context path.",
+        inputSchema: {
+            context_path: z.string().min(1),
+            force_new: z.boolean().optional(),
+            agent_id_override: z.string().min(1).optional()
+        }
+    }, async (input, extra) => toolJson(() => commands.joinPath(resolveConnectionIdentity(extra.sessionId, input.agent_id_override), {
+        context_path: input.context_path,
+        force_new: input.force_new
+    })));
+    server.registerTool("wait_for_turn", {
+        title: "Wait For Turn",
+        description: "Poll until the caller can claim the stick or takeover is available.",
+        inputSchema: {
+            room_id: z.string().min(1),
+            cursor: z.string().optional(),
+            max_wait_ms: z.number().int().nonnegative().optional()
+        }
+    }, async (input, extra) => toolJson(() => commands.waitForTurn(resolveConnectionIdentity(extra.sessionId), input)));
+    server.registerTool("heartbeat", {
+        title: "Heartbeat",
+        description: "Renew the current owner's lease.",
+        inputSchema: ownerMutationSchema()
+    }, async (input, extra) => toolJson(() => commands.heartbeat(resolveConnectionIdentity(extra.sessionId), input)));
+    server.registerTool("release_stick", {
+        title: "Release Stick",
+        description: "Release the stick to the next active member in sequence.",
+        inputSchema: {
+            ...ownerMutationSchema(),
+            handoff: handoffSchema
+        }
+    }, async (input, extra) => toolJson(() => commands.releaseStick(resolveConnectionIdentity(extra.sessionId), input)));
+    server.registerTool("pass_stick", {
+        title: "Pass Stick",
+        description: "Pass the stick to a specific active member.",
+        inputSchema: {
+            ...ownerMutationSchema(),
+            to_agent_id: z.string().min(1),
+            handoff: handoffSchema
+        }
+    }, async (input, extra) => toolJson(() => commands.passStick(resolveConnectionIdentity(extra.sessionId), input)));
+    server.registerTool("takeover_stick", {
+        title: "Takeover Stick",
+        description: "Explicitly take over after claim timeout or owner lease timeout.",
+        inputSchema: {
+            room_id: z.string().min(1),
+            expected_turn_id: z.number().int().nonnegative(),
+            reason: z.string().min(1)
+        }
+    }, async (input, extra) => toolJson(() => commands.takeoverStick(resolveConnectionIdentity(extra.sessionId), input)));
+    server.registerTool("get_room_state", {
+        title: "Get Room State",
+        description: "Read the current projected room state and membership.",
+        inputSchema: {
+            room_id: z.string().min(1)
+        }
+    }, async (input) => toolJson(() => service.getRoomState(input)));
+    server.registerTool("get_room_events", {
+        title: "Get Room Events",
+        description: "Read the append-only event log for a room.",
+        inputSchema: {
+            room_id: z.string().min(1),
+            after_event_seq: z.number().int().nonnegative().optional(),
+            limit: z.number().int().positive().optional()
+        }
+    }, async (input) => toolJson(() => service.getRoomEvents(input)));
+    return server;
+}
+export function createConnectionIdentityResolver(options = {}) {
+    const inspector = options.inspector ?? createSystemProcessInspector({ cacheTtlMs: 60_000 });
+    const connectionOverrides = new Map();
+    const connectionIdentities = new Map();
+    return (sessionId, override) => {
+        const key = sessionId ?? "__stdio__";
+        if (override) {
+            connectionOverrides.set(key, override);
+            connectionIdentities.delete(key);
+        }
+        const cached = connectionIdentities.get(key);
+        if (cached) {
+            return cached;
+        }
+        const identity = deriveMcpHarnessIdentity({
+            sessionId,
+            agentId: connectionOverrides.get(key),
+            inspector
+        });
+        connectionIdentities.set(key, identity);
+        return identity;
+    };
+}
+export async function runStdioServer() {
+    const service = new TalkingStickService();
+    const server = createMcpServer(service);
+    process.on("exit", () => service.close());
+    await server.connect(new StdioServerTransport());
+}
+function ownerMutationSchema() {
+    return {
+        room_id: z.string().min(1),
+        lease_id: z.string().min(1),
+        expected_turn_id: z.number().int().nonnegative()
+    };
+}
+async function toolJson(fn) {
+    try {
+        const result = await fn();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }
+            ]
+        };
+    }
+    catch (error) {
+        if (isProtocolError(error)) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(error.toJSON(), null, 2)
+                    }
+                ]
+            };
+        }
+        throw error;
+    }
+}

package/dist/path-resolution.js

@@ -0,0 +1,101 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+const workspaceMarkers = [
+    "CLAUDE.md",
+    "AGENTS.md",
+    "package.json",
+    "pyproject.toml",
+    "Cargo.toml",
+    "go.mod"
+];
+export function resolveContextPath(contextPath) {
+    const requestedPath = path.resolve(contextPath);
+    const canonicalContextPath = canonicalizeContextPath(requestedPath);
+    const workspaceRoot = resolveWorkspaceRoot(canonicalContextPath);
+    return {
+        requested_path: requestedPath,
+        canonical_context_path: canonicalContextPath,
+        workspace_root: workspaceRoot
+    };
+}
+export function canonicalizeContextPath(contextPath) {
+    const resolved = path.resolve(contextPath);
+    let directoryPath = resolved;
+    try {
+        const stat = fs.statSync(resolved);
+        if (stat.isFile()) {
+            directoryPath = path.dirname(resolved);
+        }
+    }
+    catch {
+        directoryPath = resolved;
+    }
+    try {
+        return fs.realpathSync.native(directoryPath);
+    }
+    catch {
+        return path.normalize(directoryPath);
+    }
+}
+export function resolveWorkspaceRoot(canonicalContextPath) {
+    const gitRoot = resolveGitRoot(canonicalContextPath);
+    if (gitRoot) {
+        return gitRoot;
+    }
+    const markerRoot = findNearestWorkspaceMarker(canonicalContextPath);
+    if (markerRoot) {
+        return markerRoot;
+    }
+    return canonicalContextPath;
+}
+export function ancestorPaths(canonicalContextPath, workspaceRoot) {
+    const ancestors = [];
+    let current = canonicalContextPath;
+    while (true) {
+        ancestors.push(current);
+        if (samePath(current, workspaceRoot)) {
+            break;
+        }
+        const parent = path.dirname(current);
+        if (samePath(parent, current)) {
+            break;
+        }
+        current = parent;
+    }
+    return ancestors.filter((candidate) => isWithinOrSame(candidate, workspaceRoot));
+}
+function resolveGitRoot(canonicalContextPath) {
+    try {
+        const output = execFileSync("git", ["-C", canonicalContextPath, "rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (!output) {
+            return null;
+        }
+        return fs.realpathSync.native(output);
+    }
+    catch {
+        return null;
+    }
+}
+function findNearestWorkspaceMarker(startPath) {
+    let current = startPath;
+    while (true) {
+        for (const marker of workspaceMarkers) {
+            if (fs.existsSync(path.join(current, marker))) {
+                return current;
+            }
+        }
+        const parent = path.dirname(current);
+        if (samePath(parent, current)) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function samePath(left, right) {
+    return path.normalize(left) === path.normalize(right);
+}
+function isWithinOrSame(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));
+}

package/dist/process-utils.js

@@ -0,0 +1,93 @@
+import { execFileSync } from "node:child_process";
+export function terminateKnownProcess(processRef, options) {
+    if (processRef.pid === null ||
+        processRef.pid === undefined ||
+        processRef.process_started_at === null ||
+        processRef.process_started_at === undefined ||
+        processRef.process_started_at.trim() === "") {
+        return false;
+    }
+    const inspection = options.inspector.inspect(processRef.pid);
+    if (!inspection?.startTime) {
+        return false;
+    }
+    if (inspection.startTime !== processRef.process_started_at) {
+        return false;
+    }
+    try {
+        (options.signaler ?? process).kill(processRef.pid, options.signal ?? "SIGTERM");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function createSystemProcessInspector(options = {}) {
+    const cache = new Map();
+    const cacheTtlMs = options.cacheTtlMs ?? 0;
+    return {
+        inspect(pid) {
+            if (!Number.isInteger(pid) || pid <= 0) {
+                return undefined;
+            }
+            const nowMs = Date.now();
+            const cached = cache.get(pid);
+            if (cached && nowMs - cached.checked_at_ms < cacheTtlMs) {
+                return cached.inspection;
+            }
+            const inspection = inspectSystemProcess(pid, options);
+            cache.set(pid, {
+                checked_at_ms: nowMs,
+                inspection
+            });
+            return inspection;
+        }
+    };
+}
+function inspectSystemProcess(pid, options) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32") {
+        return undefined;
+    }
+    const exists = options.processExists ?? processExistsViaSignal;
+    if (!exists(pid)) {
+        return null;
+    }
+    try {
+        const output = (options.execFile ?? defaultExecFile)("ps", ["-o", "ppid=", "-o", "lstart=", "-o", "command=", "-p", String(pid)], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+        }).trimEnd();
+        if (!output.trim()) {
+            return null;
+        }
+        const ppidStr = output.slice(0, 8).trim();
+        const startTime = output.slice(8, 32).trim();
+        const command = output.slice(32).trimStart();
+        const ppid = parseInt(ppidStr, 10);
+        return {
+            pid,
+            ppid: isNaN(ppid) ? null : ppid,
+            startTime: startTime || null,
+            command: command || null
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function processExistsViaSignal(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ESRCH")
+            return false;
+        return true;
+    }
+}
+function defaultExecFile(file, args, options) {
+    return execFileSync(file, args, options);
+}

package/dist/server.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runStdioServer } from "./mcp-server.js";
+await runStdioServer();