talking-stick 0.1.0-alpha

package/dist/commands.js

@@ -0,0 +1,70 @@
+import { TalkingStickService } from "./service.js";
+export class TalkingStickCommands {
+    service;
+    constructor(service = new TalkingStickService()) {
+        this.service = service;
+    }
+    close() {
+        this.service.close();
+    }
+    listRooms(input = {}) {
+        return this.service.listRooms(input);
+    }
+    joinPath(identity, input) {
+        return this.service.joinPath({
+            agent_id: identity.agent_id,
+            context_path: input.context_path,
+            force_new: input.force_new,
+            process_metadata: identity.process_metadata
+        });
+    }
+    waitForTurn(identity, input) {
+        return this.service.waitForTurn({
+            agent_id: identity.agent_id,
+            room_id: input.room_id,
+            cursor: input.cursor,
+            max_wait_ms: input.max_wait_ms
+        });
+    }
+    heartbeat(identity, input) {
+        return this.service.heartbeat({
+            agent_id: identity.agent_id,
+            room_id: input.room_id,
+            lease_id: input.lease_id,
+            expected_turn_id: input.expected_turn_id
+        });
+    }
+    releaseStick(identity, input) {
+        return this.service.releaseStick({
+            agent_id: identity.agent_id,
+            room_id: input.room_id,
+            lease_id: input.lease_id,
+            expected_turn_id: input.expected_turn_id,
+            handoff: input.handoff
+        });
+    }
+    passStick(identity, input) {
+        return this.service.passStick({
+            agent_id: identity.agent_id,
+            room_id: input.room_id,
+            lease_id: input.lease_id,
+            expected_turn_id: input.expected_turn_id,
+            to_agent_id: input.to_agent_id,
+            handoff: input.handoff
+        });
+    }
+    takeoverStick(identity, input) {
+        return this.service.takeoverStick({
+            agent_id: identity.agent_id,
+            room_id: input.room_id,
+            expected_turn_id: input.expected_turn_id,
+            reason: input.reason
+        });
+    }
+    getRoomState(input) {
+        return this.service.getRoomState(input);
+    }
+    getRoomEvents(input) {
+        return this.service.getRoomEvents(input);
+    }
+}

package/dist/config.js

@@ -0,0 +1,31 @@
+import os from "node:os";
+import path from "node:path";
+export const defaultPolicy = {
+    ownerLeaseTtlMs: 45 * 60 * 1000,
+    heartbeatIntervalMs: 5 * 60 * 1000,
+    claimTtlMs: 20 * 60 * 1000,
+    waitForTurnMaxWaitMs: 30 * 1000,
+    waitForTurnPollMs: 250,
+    presenceTtlMs: 4 * 60 * 60 * 1000
+};
+export function resolveDataDir(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const homeDir = options.homeDir ?? os.homedir();
+    const pathModule = platform === "win32" ? path.win32 : path.posix;
+    if (env.TALKING_STICK_DATA_DIR && env.TALKING_STICK_DATA_DIR.trim()) {
+        return path.resolve(env.TALKING_STICK_DATA_DIR);
+    }
+    if (platform === "win32") {
+        const appData = env.APPDATA;
+        if (!appData) {
+            return pathModule.join(homeDir, "AppData", "Roaming", "talking-stick");
+        }
+        return pathModule.join(appData, "talking-stick");
+    }
+    const xdgDataHome = env.XDG_DATA_HOME?.trim();
+    if (xdgDataHome) {
+        return pathModule.join(xdgDataHome, "talking-stick");
+    }
+    return pathModule.join(homeDir, ".local", "share", "talking-stick");
+}

package/dist/db.js

@@ -0,0 +1,177 @@
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import DatabaseConstructor from "better-sqlite3";
+import { resolveDataDir } from "./config.js";
+const migrations = [
+    {
+        id: 1,
+        name: "initial_schema",
+        up: `
+      CREATE TABLE path_rooms (
+        room_id TEXT PRIMARY KEY,
+        canonical_path TEXT NOT NULL,
+        sequence_index INTEGER NOT NULL DEFAULT 0,
+        owner TEXT,
+        reserved_for TEXT,
+        pending_handoff_event_seq INTEGER,
+        turn_id INTEGER NOT NULL DEFAULT 0,
+        lease_id TEXT,
+        lease_expires_at TEXT,
+        claim_expires_at TEXT,
+        state TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        UNIQUE (canonical_path)
+      );
+
+      CREATE INDEX path_rooms_canonical_path_idx
+        ON path_rooms (canonical_path);
+
+      CREATE TABLE room_members (
+        room_id TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
+        ordinal INTEGER NOT NULL,
+        joined_at TEXT NOT NULL,
+        last_seen_at TEXT NOT NULL,
+        status TEXT NOT NULL,
+        PRIMARY KEY (room_id, agent_id),
+        FOREIGN KEY (room_id) REFERENCES path_rooms(room_id)
+      );
+
+      CREATE TABLE room_events (
+        event_seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_id TEXT NOT NULL UNIQUE,
+        room_id TEXT NOT NULL,
+        turn_id INTEGER NOT NULL,
+        event_type TEXT NOT NULL,
+        from_agent_id TEXT,
+        to_agent_id TEXT,
+        handoff_json TEXT,
+        reason TEXT,
+        created_at TEXT NOT NULL,
+        FOREIGN KEY (room_id) REFERENCES path_rooms(room_id)
+      );
+
+      CREATE INDEX room_events_room_seq_idx
+        ON room_events (room_id, event_seq);
+
+      CREATE INDEX room_events_room_turn_idx
+        ON room_events (room_id, turn_id);
+    `
+    },
+    {
+        id: 2,
+        name: "room_member_process_metadata",
+        up: `
+      ALTER TABLE room_members ADD COLUMN host_id TEXT;
+      ALTER TABLE room_members ADD COLUMN pid INTEGER;
+      ALTER TABLE room_members ADD COLUMN process_started_at TEXT;
+      ALTER TABLE room_members ADD COLUMN session_kind TEXT NOT NULL DEFAULT 'mcp_harness';
+      ALTER TABLE room_members ADD COLUMN display_name TEXT;
+    `
+    }
+];
+export function resolveDatabasePath(options = {}) {
+    if (options.dbPath) {
+        return path.resolve(options.dbPath);
+    }
+    const dataDir = options.dataDir
+        ? path.resolve(options.dataDir)
+        : resolveDataDir();
+    return path.join(dataDir, "rooms.sqlite");
+}
+export function openDatabase(options = {}) {
+    const dbPath = resolveDatabasePath(options);
+    assertLocalFilesystem(path.dirname(dbPath), options.filesystemTypeOptions);
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    const db = new DatabaseConstructor(dbPath);
+    applyPragmas(db);
+    migrate(db);
+    return db;
+}
+export function applyPragmas(db) {
+    db.pragma("journal_mode = WAL");
+    db.pragma("synchronous = NORMAL");
+    db.pragma("busy_timeout = 5000");
+    db.pragma("foreign_keys = ON");
+}
+export function migrate(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      applied_at TEXT NOT NULL
+    );
+  `);
+    const applied = new Set(db
+        .prepare("SELECT id FROM schema_migrations")
+        .all()
+        .map((row) => row.id));
+    for (const migration of migrations) {
+        if (applied.has(migration.id)) {
+            continue;
+        }
+        withImmediateTransaction(db, () => {
+            db.exec(migration.up);
+            db.prepare("INSERT INTO schema_migrations (id, name, applied_at) VALUES (?, ?, ?)").run(migration.id, migration.name, new Date().toISOString());
+        });
+    }
+}
+export function withImmediateTransaction(db, fn) {
+    db.prepare("BEGIN IMMEDIATE").run();
+    try {
+        const result = fn();
+        db.prepare("COMMIT").run();
+        return result;
+    }
+    catch (error) {
+        db.prepare("ROLLBACK").run();
+        throw error;
+    }
+}
+export function assertLocalFilesystem(targetPath, options = {}) {
+    const filesystemType = detectFilesystemType(targetPath, options);
+    if (!filesystemType) {
+        return;
+    }
+    if (isRemoteFilesystemType(filesystemType)) {
+        throw new Error(`Talking Stick requires a local filesystem for SQLite state. Detected ${filesystemType} at ${targetPath}. Set TALKING_STICK_DATA_DIR to a local path.`);
+    }
+}
+export function detectFilesystemType(targetPath, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32") {
+        return null;
+    }
+    const existingPath = nearestExistingPath(targetPath);
+    const execFile = options.execFile ??
+        ((file, args, execOptions) => execFileSync(file, args, execOptions));
+    try {
+        const args = platform === "linux"
+            ? ["-f", "-c", "%T", existingPath]
+            : ["-f", "%T", existingPath];
+        return execFile("stat", args, {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+        })
+            .trim()
+            .toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+function nearestExistingPath(targetPath) {
+    let current = path.resolve(targetPath);
+    while (!fs.existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return current;
+        }
+        current = parent;
+    }
+    return current;
+}
+function isRemoteFilesystemType(filesystemType) {
+    return /^(nfs|smbfs|cifs)/.test(filesystemType);
+}

package/dist/errors.js

@@ -0,0 +1,20 @@
+export class ProtocolError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = "ProtocolError";
+        this.code = code;
+        this.details = details;
+    }
+    toJSON() {
+        return {
+            error: this.code,
+            message: this.message,
+            ...this.details
+        };
+    }
+}
+export function isProtocolError(error) {
+    return error instanceof ProtocolError;
+}

package/dist/identity.js

@@ -0,0 +1,184 @@
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { createSystemProcessInspector } from "./process-utils.js";
+export function deriveHumanCliIdentity(options = {}) {
+    const username = options.username ?? safeUsername();
+    const displayName = options.displayName ?? username;
+    const agentId = options.agentId ?? `human:${sanitizeIdentityComponent(username)}`;
+    const sessionKind = options.sessionKind ?? "human_cli";
+    const includesExactProcessIdentity = sessionKind === "human_guardian";
+    let hostId = null;
+    let pid = null;
+    let processStartedAt = null;
+    if (includesExactProcessIdentity) {
+        const inspector = options.inspector ?? createSystemProcessInspector();
+        pid = options.pid ?? process.pid;
+        const inspection = inspector.inspect(pid);
+        hostId = options.hostId ?? os.hostname();
+        processStartedAt = inspection?.startTime ?? null;
+    }
+    return {
+        agent_id: agentId,
+        process_metadata: {
+            host_id: hostId,
+            pid,
+            process_started_at: processStartedAt,
+            session_kind: sessionKind,
+            display_name: displayName
+        }
+    };
+}
+export function deriveMcpHarnessIdentity(options = {}) {
+    const env = options.env ?? process.env;
+    const inspector = options.inspector ?? createSystemProcessInspector();
+    const pid = options.parentPid ?? process.ppid;
+    const hostId = options.hostId ?? os.hostname();
+    const username = options.username ?? safeUsername();
+    const inspection = inspector.inspect(pid);
+    const signal = detectHarnessSignal(env);
+    if (signal) {
+        const sessionId = resolveHarnessSessionId(signal, env, pid, inspection, username, hostId);
+        const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
+        return {
+            agent_id: agentId,
+            process_metadata: {
+                host_id: hostId,
+                pid,
+                process_started_at: inspection?.startTime ?? null,
+                session_kind: "mcp_harness",
+                display_name: signal.harness
+            }
+        };
+    }
+    const displayName = options.displayName ?? deriveCommandLabel(inspection?.command ?? null);
+    const agentId = options.agentId ??
+        `${sanitizeIdentityComponent(displayName)}:${hashIdentityParts([
+            hostId,
+            String(pid),
+            inspection?.startTime ?? "",
+            options.sessionId ?? ""
+        ])}`;
+    return {
+        agent_id: agentId,
+        process_metadata: {
+            host_id: hostId,
+            pid,
+            process_started_at: inspection?.startTime ?? null,
+            session_kind: "mcp_harness",
+            display_name: displayName
+        }
+    };
+}
+export function deriveHarnessCliIdentity(options = {}) {
+    const env = options.env ?? process.env;
+    const signal = detectHarnessSignal(env);
+    if (!signal)
+        return null;
+    const parentPid = options.parentPid ?? process.ppid;
+    const hostId = options.hostId ?? os.hostname();
+    const inspector = options.inspector ?? createSystemProcessInspector();
+    const parentInspection = inspector.inspect(parentPid);
+    const username = options.username ?? safeUsername();
+    const sessionId = resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId);
+    const agentId = options.agentId ?? harnessAgentId(signal.harness, sessionId, hostId, username);
+    return {
+        agent_id: agentId,
+        process_metadata: {
+            host_id: hostId,
+            pid: parentPid,
+            process_started_at: parentInspection?.startTime ?? null,
+            session_kind: "harness_cli",
+            display_name: signal.harness
+        }
+    };
+}
+function harnessAgentId(harness, sessionId, hostId, username) {
+    return `${harness}:${hashIdentityParts([
+        harness,
+        hostId,
+        sessionId,
+        sanitizeIdentityComponent(username)
+    ])}`;
+}
+function resolveHarnessSessionId(signal, env, parentPid, parentInspection, username, hostId) {
+    if (signal.sessionId)
+        return `harness:${signal.sessionId}`;
+    const terminalId = resolveTerminalSessionId(env);
+    if (terminalId)
+        return terminalId;
+    if (parentInspection?.startTime) {
+        return `pid:${parentPid}@${parentInspection.startTime}`;
+    }
+    return `userhost:${sanitizeIdentityComponent(username)}@${hostId}`;
+}
+const TERMINAL_SESSION_ENV_VARS = [
+    "ITERM_SESSION_ID",
+    "CMUX_TAB_ID",
+    "KITTY_WINDOW_ID",
+    "WEZTERM_PANE",
+    "TERMINATOR_UUID",
+    "TMUX_PANE",
+    "STY"
+];
+function resolveTerminalSessionId(env) {
+    for (const key of TERMINAL_SESSION_ENV_VARS) {
+        const value = env[key];
+        if (value && value.trim().length > 0) {
+            return `term:${key}=${value.trim()}`;
+        }
+    }
+    return null;
+}
+function detectHarnessSignal(env) {
+    if (env.CLAUDECODE === "1") {
+        return { harness: "claude", sessionId: nonEmpty(env.CLAUDE_CODE_EXECPATH) };
+    }
+    if (env.CODEX_MANAGED_BY_NPM === "1" || nonEmpty(env.CODEX_THREAD_ID)) {
+        return { harness: "codex", sessionId: nonEmpty(env.CODEX_THREAD_ID) };
+    }
+    if (env.GEMINI_CLI === "1") {
+        return { harness: "gemini", sessionId: null };
+    }
+    if (env.OPENCODE === "1") {
+        return {
+            harness: "opencode",
+            sessionId: nonEmpty(env.OPENCODE_RUN_ID) ?? nonEmpty(env.OPENCODE_PID)
+        };
+    }
+    return null;
+}
+function nonEmpty(value) {
+    return value && value.trim().length > 0 ? value : null;
+}
+function deriveCommandLabel(command) {
+    if (!command) {
+        return "harness";
+    }
+    const token = command.trim().split(/\s+/)[0] ?? "";
+    const basename = path.basename(token).replace(/\.(exe|cmd|bat)$/i, "");
+    const sanitized = sanitizeIdentityComponent(basename);
+    return sanitized || "harness";
+}
+function safeUsername() {
+    try {
+        return os.userInfo().username;
+    }
+    catch {
+        return process.env.USER ?? process.env.LOGNAME ?? "user";
+    }
+}
+function sanitizeIdentityComponent(value) {
+    const sanitized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return sanitized || "anon";
+}
+function hashIdentityParts(parts) {
+    return crypto
+        .createHash("sha256")
+        .update(parts.join("\0"))
+        .digest("hex")
+        .slice(0, 8);
+}

package/dist/index.js

@@ -0,0 +1,12 @@
+export { resolveDataDir, defaultPolicy } from "./config.js";
+export { TalkingStickCommands } from "./commands.js";
+export { applyPragmas, assertLocalFilesystem, detectFilesystemType, migrate, openDatabase, resolveDatabasePath, withImmediateTransaction } from "./db.js";
+export { ProtocolError, isProtocolError } from "./errors.js";
+export { deriveHarnessCliIdentity, deriveHumanCliIdentity, deriveMcpHarnessIdentity } from "./identity.js";
+export { ancestorPaths, canonicalizeContextPath, resolveContextPath, resolveWorkspaceRoot } from "./path-resolution.js";
+export { createMcpServer, runStdioServer } from "./mcp-server.js";
+export { SUPPORTED_HARNESSES, detectHarness, parseHarnessList, planInstall, planUninstall, resolveOpencodeConfigPath, runAction } from "./install.js";
+export { DEFAULT_SKILL_NAME, planSkillInstall, planSkillUninstall, resolveBundledSkillPath, resolveSkillTargetPath } from "./skill-install.js";
+export { createSystemProcessInspector, terminateKnownProcess } from "./process-utils.js";
+export { clearCliSessionLease, findCliSessionByRoom, findCliSessionForContextPath, readCliSessions, resolveCliSessionPath, upsertCliSession, writeCliSessions } from "./session-store.js";
+export { TalkingStickService } from "./service.js";