talentos 1.0.0 → 1.1.0

package/README.md

@@ -17,6 +17,9 @@ same server over stdio for clients that cannot speak streamable HTTP.
 Every command below pins `talentos@1`, the major that speaks the hosted MCP endpoint.
 The `0.x` releases are the retired stdio wrapper and no longer work.
 
+Release 1.1.0 includes Rooms agent linking, the gateway, and the `create_deck`
+MCP permission. `talentos@1` picks it up automatically after publication.
+
 ```bash
 npx talentos@1 init
 ```
@@ -77,6 +80,34 @@ before it is sent, and stored only once TalentOS accepts it.
 
 ## Commands
 
+### Agents in Rooms
+
+`talentos agent serve --agent <id>` runs the linked provider in its private
+work folder. It keeps one turn active, resumes the same thread from
+`~/.talentos/agents/<id>/sessions.json`, and posts final text automatically.
+The service heartbeats every 20 seconds and stops the child if its lease is
+lost. A required CLI update installs under the agent directory between turns.
+Signing-key provisioning, real staging latency and provider resume proofs are
+tracked in [Agent access](../../docs/features/agent-access/README.md).
+
+Use the setup prompt from TalentOS to link Claude Code or Codex. The fragment
+token is private; never paste it into logs or commits. Provider CLI login is
+required even when its desktop app is signed in. Approve the user service
+installation interactively or pass `--yes` after approval.
+
+Linking waits for a recent gateway heartbeat before reporting Connected. Real
+provider connection, latency and resume proofs remain staged after publication.
+If the service cannot start, use the printed foreground
+`talentos agent serve --agent <id>` command.
+
+`agent status` and `agent list` show agents linked on this machine. Select one
+with `--agent <id>` for `agent logs` or `agent unlink`. Unlink disconnects the
+agent remotely and removes its local service and configuration.
+
+Re-running the same link repairs the install and reuses its key. Keep the
+private pending receipt if a response is lost; it permits recovery after the
+one-use link has been consumed.
+
 ```
 talentos init [--for claude|cursor|codex|all] [--no-pull] [--name <device>]
 

package/dist/agent/adapters.js

@@ -0,0 +1,260 @@
+import { execFile, spawn } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { writePrivateFile } from "../agent-config.js";
+import { redactAgentOutput, } from "../agent-link.js";
+const CHILD_ENV = [
+    "HOME",
+    "PATH",
+    "USER",
+    "LOGNAME",
+    "LANG",
+    "LC_ALL",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "SystemRoot",
+    "XDG_CONFIG_HOME",
+    "XDG_CACHE_HOME",
+    "CODEX_HOME",
+    "CLAUDE_CONFIG_DIR",
+];
+const CLAUDE_VERSION = /^\d+\.\d+\.\d+/u;
+const DONT_ASK = /\bdontAsk\b/u;
+const CLAUDE_TOOLS = [
+    "read_room",
+    "list_room_files",
+    "read_file",
+    "suggest_change",
+    "create_file",
+    "create_deck",
+    "post_message",
+    "share_link",
+]
+    .map((tool) => `mcp__talentos__${tool}`)
+    .join(",");
+export function childEnvironment(source = process.env) {
+    return Object.fromEntries(CHILD_ENV.filter((key) => source[key] !== undefined).map((key) => [
+        key,
+        source[key],
+    ]));
+}
+export async function verifyClaudeCode() {
+    const execute = promisify(execFile);
+    const options = {
+        env: childEnvironment(),
+        timeout: 5000,
+        maxBuffer: 256_000,
+    };
+    let version = "unknown";
+    try {
+        const detected = await execute("claude", ["--version"], options);
+        version = CLAUDE_VERSION.exec(detected.stdout.trim())?.[0] ?? "unknown";
+        const help = await execute("claude", ["--help"], options);
+        if (version !== "unknown" && DONT_ASK.test(help.stdout)) {
+            return;
+        }
+    }
+    catch {
+        // Never include provider stderr, which may contain login details.
+    }
+    throw new Error(`Update Claude Code (${version}) to a version that supports --permission-mode dontAsk.`);
+}
+export function readProviderEvent(provider, value) {
+    if (!value || typeof value !== "object") {
+        return {};
+    }
+    const event = value;
+    if (provider === "claude_code") {
+        if (event.type === "result") {
+            if (event.is_error) {
+                return { failed: true };
+            }
+            return {
+                ...(typeof event.session_id === "string"
+                    ? { sessionId: event.session_id }
+                    : {}),
+                ...(typeof event.result === "string" ? { text: event.result } : {}),
+            };
+        }
+        const message = event.message;
+        if (event.type === "assistant" &&
+            Array.isArray(message?.content) &&
+            message.content.some((part) => part.type === "tool_use")) {
+            return { status: "Using room tools…" };
+        }
+    }
+    else {
+        if (event.type === "thread.started" &&
+            typeof event.thread_id === "string") {
+            return { sessionId: event.thread_id };
+        }
+        if (event.type === "turn.failed" || event.type === "error") {
+            return { failed: true };
+        }
+        const item = event.item;
+        if (event.type === "item.completed" &&
+            item?.type === "agent_message" &&
+            typeof item.text === "string") {
+            return { text: item.text };
+        }
+        if (event.type === "item.started" && item?.type === "mcp_tool_call") {
+            return { status: "Using room tools…" };
+        }
+    }
+    return {};
+}
+export async function runProvider(input) {
+    const { config, job, workDir, sessionId, signal } = input;
+    const prompt = JSON.stringify(job.packet), mcpPath = join(dirname(workDir), ".talentos-mcp.json");
+    let command, args;
+    if (config.provider === "claude_code") {
+        await writePrivateFile(mcpPath, JSON.stringify({
+            mcpServers: {
+                talentos: {
+                    type: "http",
+                    url: new URL("/mcp", config.apiUrl).href,
+                    headers: { Authorization: `Bearer ${config.apiKey}` },
+                },
+            },
+        }));
+        command = "claude";
+        args = [
+            "-p",
+            prompt,
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--mcp-config",
+            mcpPath,
+            "--strict-mcp-config",
+            "--append-system-prompt",
+            job.packet.instructions,
+            "--tools",
+            "",
+            "--allowedTools",
+            CLAUDE_TOOLS,
+            "--disallowedTools",
+            "Bash,Agent,Task",
+            "--permission-mode",
+            "dontAsk",
+        ];
+        if (sessionId) {
+            args.push("--resume", sessionId);
+        }
+    }
+    else {
+        command = "codex";
+        const entry = fileURLToPath(new URL("./mcp-entry.js", import.meta.url));
+        // Resume has a different flag surface. Root overrides are inherited by
+        // both exec paths; shell_tool=false enforces ADR 0093's default no-Bash.
+        args = [
+            "-c",
+            'sandbox_mode="workspace-write"',
+            "-c",
+            'approval_policy="never"',
+            "-c",
+            "features.shell_tool=false",
+            "-c",
+            "features.unified_exec=false",
+            "-c",
+            `mcp_servers.talentos.command=${JSON.stringify(process.execPath)}`,
+            "-c",
+            `mcp_servers.talentos.args=${JSON.stringify([entry, config.agentId])}`,
+            "exec",
+        ];
+        if (sessionId) {
+            args.push("resume", sessionId);
+        }
+        args.push("--json", "--skip-git-repo-check", "--ignore-user-config", "--ignore-rules", prompt);
+    }
+    const child = spawn(command, args, {
+        cwd: workDir,
+        env: childEnvironment(),
+        stdio: ["ignore", "pipe", "ignore"],
+        detached: process.platform !== "win32",
+    });
+    let killTimer;
+    const stop = () => {
+        const pid = child.pid;
+        if (!pid || child.exitCode !== null || child.signalCode !== null) {
+            return;
+        }
+        const kill = (signal) => {
+            try {
+                if (process.platform === "win32") {
+                    child.kill(signal);
+                }
+                else {
+                    process.kill(-pid, signal);
+                }
+            }
+            catch {
+                /* The process group may have already exited. */
+            }
+        };
+        kill("SIGTERM");
+        killTimer ??= setTimeout(() => kill("SIGKILL"), 5000);
+    };
+    const ended = new Promise((resolve) => {
+        child.once("error", () => resolve(null));
+        child.once("close", resolve);
+    });
+    signal.addEventListener("abort", stop, { once: true });
+    if (signal.aborted) {
+        stop();
+    }
+    try {
+        let text = "", failed = false, sawResult = false;
+        if (!child.stdout) {
+            throw new Error("Provider output is unavailable.");
+        }
+        const lines = createInterface({ input: child.stdout });
+        for await (const line of lines) {
+            if (line.length > 1_000_000) {
+                throw new Error("Provider output exceeded its limit.");
+            }
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const event = readProviderEvent(config.provider, value);
+            if (event.failed) {
+                failed = true;
+            }
+            if (event.sessionId) {
+                await input.remember(event.sessionId);
+            }
+            if (event.status) {
+                input.status(event.status);
+            }
+            if (event.text !== undefined) {
+                text = event.text.slice(0, 12_000);
+            }
+            const type = value?.type;
+            if (type === "result" || type === "turn.completed") {
+                sawResult = true;
+            }
+        }
+        const code = await ended;
+        if (code !== 0 || failed || !sawResult || signal.aborted) {
+            throw new Error("Provider could not finish this turn. Check its login and quota.");
+        }
+        return { text: redactAgentOutput(text, [config.apiKey]) };
+    }
+    finally {
+        signal.removeEventListener("abort", stop);
+        stop();
+        await ended;
+        if (killTimer) {
+            clearTimeout(killTimer);
+        }
+        await rm(mcpPath, { force: true });
+    }
+}

package/dist/agent/gateway.js

@@ -0,0 +1,70 @@
+import { ConvexClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { isSecureUrl } from "../agent-link.js";
+export class GatewayError extends Error {
+    status;
+    constructor(status) {
+        super(status === 401 || status === 409
+            ? "Agent is no longer available. Re-link it from TalentOS."
+            : "Agent gateway request failed; retrying.");
+        this.status = status;
+    }
+}
+export class AgentGateway {
+    config;
+    constructor(config) {
+        if (!isSecureUrl(new URL(config.apiUrl))) {
+            throw new Error("Agent gateway needs HTTPS or localhost.");
+        }
+        this.config = config;
+    }
+    async request(path, body = {}, signal) {
+        const response = await fetch(new URL(path, this.config.apiUrl), {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.config.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+            signal: signal
+                ? AbortSignal.any([signal, AbortSignal.timeout(15_000)])
+                : AbortSignal.timeout(15_000),
+            redirect: "error",
+        });
+        if (!response.ok) {
+            throw new GatewayError(response.status);
+        }
+        return response.status === 204 ? null : (await response.json());
+    }
+    async subscribe(wake, fallback) {
+        const initial = await this.request("/agent-gateway/token");
+        if (!(initial && isSecureUrl(new URL(initial.convexUrl)))) {
+            throw new Error("Agent push is unavailable.");
+        }
+        const client = new ConvexClient(initial.convexUrl, { logger: false });
+        let cached = initial;
+        client.setAuth(async ({ forceRefreshToken }) => {
+            if (forceRefreshToken || cached.expiresAt - Date.now() < 60_000) {
+                const renewed = await this.request("/agent-gateway/token");
+                if (!renewed) {
+                    return null;
+                }
+                cached = renewed;
+            }
+            return cached.token;
+        }, (authenticated) => {
+            if (!authenticated) {
+                fallback();
+            }
+        });
+        const unsubscribe = client.onUpdate(makeFunctionReference("externalAgents/jobs:pendingForAgent"), {}, (count) => {
+            if (count > 0) {
+                wake();
+            }
+        }, () => fallback());
+        return async () => {
+            unsubscribe();
+            await client.close();
+        };
+    }
+}

package/dist/agent/mcp-entry.js

@@ -0,0 +1,10 @@
+import { localAgents } from "../agent-config.js";
+import { AgentClient } from "../client.js";
+import { startMcpProxy } from "../mcp-proxy.js";
+// A local stdio entry avoids putting the bearer key in Codex's argv or child
+// environment. Only the MCP proxy reads the linked-agent credential file.
+const config = (await localAgents()).find((agent) => agent.agentId === process.argv[2]);
+if (!config) {
+    throw new Error("Linked agent configuration is unavailable.");
+}
+await startMcpProxy(new AgentClient({ apiUrl: config.apiUrl, apiKey: config.apiKey }));

package/dist/agent/serve.js

@@ -0,0 +1,269 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { childEnvironment, runProvider } from "./adapters.js";
+import { AgentGateway, GatewayError } from "./gateway.js";
+import { SessionMap } from "./sessions.js";
+const HEARTBEAT_MS = 20_000;
+const LEASE_SAFETY_MS = 55_000;
+const IDLE_MS = 30 * 60_000;
+const VERSION = /^(\d+)\.(\d+)\.(\d+)$/;
+export function needsUpdate(current, minimum) {
+    const a = VERSION.exec(current), b = VERSION.exec(minimum);
+    if (!b) {
+        return false;
+    }
+    if (!a) {
+        return true;
+    }
+    for (let i = 1; i <= 3; i++) {
+        if (Number(a[i]) !== Number(b[i])) {
+            return Number(a[i]) < Number(b[i]);
+        }
+    }
+    return false;
+}
+export function claimPollInterval(lastJobAt, now = Date.now()) {
+    return now - lastJobAt >= IDLE_MS ? 10_000 : 2000;
+}
+async function acquireLock(directory) {
+    const path = join(directory, "serve.lock");
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    try {
+        const handle = await open(path, "wx", 0o600);
+        await handle.writeFile(String(process.pid));
+        await handle.close();
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+        const pid = Number(await readFile(path, "utf8"));
+        try {
+            process.kill(pid, 0);
+        }
+        catch (failure) {
+            if (failure.code === "ESRCH") {
+                await rm(path, { force: true });
+                return await acquireLock(directory);
+            }
+            throw failure;
+        }
+        throw new Error("This agent is already serving on this machine.");
+    }
+    return async () => {
+        await rm(path, { force: true });
+    };
+}
+export async function installGatewayUpdate(directory, minimum, signal) {
+    if (!VERSION.test(minimum)) {
+        throw new Error("Unsupported gateway minimum version.");
+    }
+    const destination = join(directory, "gateway-cli");
+    await new Promise((resolve, reject) => {
+        const child = spawn("npm", [
+            "install",
+            "--prefix",
+            destination,
+            "--omit=dev",
+            "--ignore-scripts",
+            "--no-audit",
+            "--no-fund",
+            `talentos@${minimum}`,
+        ], { env: childEnvironment(), stdio: "ignore", signal });
+        child.once("error", () => reject(new Error("Gateway update could not start.")));
+        child.once("close", (code) => code === 0
+            ? resolve()
+            : reject(new Error("Gateway update failed. Retry when the network is available.")));
+    });
+    return join(destination, "node_modules", "talentos", "dist", "index.js");
+}
+export async function serveAgent(config, directory, version, stop) {
+    const release = await acquireLock(directory);
+    try {
+        const workDir = join(directory, "work"), sessions = new SessionMap(directory), gateway = new AgentGateway(config);
+        await mkdir(workDir, { recursive: true, mode: 0o700 });
+        const deviceId = randomUUID();
+        const service = new AbortController();
+        const signal = AbortSignal.any([stop, service.signal]);
+        let wakeResolve, wakePending = true;
+        const wake = () => {
+            wakePending = true;
+            wakeResolve?.();
+        };
+        let active;
+        let minimum = version, lastJobAt = Date.now(), push = false, dispose;
+        let terminalError;
+        const failService = (error) => {
+            if (error instanceof GatewayError && error.status === 401) {
+                terminalError = error;
+                service.abort();
+                active?.cancel.abort();
+                wake();
+            }
+        };
+        const heartbeat = async () => {
+            const response = await gateway.request("/agent-gateway/heartbeat", { cliVersion: version }, signal);
+            if (response) {
+                minimum = response.cliMinVersion;
+                if (response.pendingJobs > 0 || minimum !== version) {
+                    wake();
+                }
+            }
+        };
+        const heartbeatLoop = async () => {
+            while (!signal.aborted) {
+                const started = Date.now();
+                const leased = active;
+                await Promise.all([
+                    heartbeat().catch(failService),
+                    leased
+                        ? gateway
+                            .request(`/agent-gateway/jobs/${leased.job.jobId}/renew`, { leaseToken: leased.job.leaseToken }, signal)
+                            .then(() => {
+                            if (active === leased) {
+                                leased.deadline = started + LEASE_SAFETY_MS;
+                            }
+                        })
+                            .catch((error) => {
+                            if (active !== leased) {
+                                return;
+                            }
+                            if (error instanceof GatewayError && error.status === 409) {
+                                leased.cancel.abort();
+                            }
+                            failService(error);
+                        })
+                        : Promise.resolve(),
+                ]);
+                await delay(Math.max(1, HEARTBEAT_MS - (Date.now() - started)), undefined, { signal }).catch(() => {
+                    /* Shutdown interrupts the timer. */
+                });
+            }
+        };
+        let heartbeats;
+        const watchdog = setInterval(() => {
+            if (active && Date.now() >= active.deadline) {
+                active.cancel.abort();
+            }
+        }, 1000);
+        try {
+            await heartbeat();
+            try {
+                push = true;
+                dispose = await gateway.subscribe(wake, () => {
+                    push = false;
+                    wake();
+                });
+            }
+            catch (error) {
+                push = false;
+                failService(error);
+            }
+            heartbeats = heartbeatLoop();
+            while (!signal.aborted) {
+                if (needsUpdate(version, minimum)) {
+                    return await installGatewayUpdate(directory, minimum, signal);
+                }
+                wakePending = false;
+                let job;
+                const claimStartedAt = Date.now();
+                try {
+                    job = await gateway.request("/agent-gateway/claim", { deviceId }, signal);
+                }
+                catch (error) {
+                    failService(error);
+                    job = null;
+                }
+                if (job) {
+                    lastJobAt = Date.now();
+                    const cancel = new AbortController();
+                    active = { job, cancel, deadline: claimStartedAt + LEASE_SAFETY_MS };
+                    let lastStatusAt = 0;
+                    try {
+                        const result = await runProvider({
+                            config,
+                            job,
+                            workDir,
+                            sessionId: await sessions.get(job.packet.thread.id),
+                            signal: AbortSignal.any([signal, cancel.signal]),
+                            remember: async (sessionId) => {
+                                await sessions.remember(job.packet.thread.id, sessionId);
+                            },
+                            status: (line) => {
+                                if (Date.now() - lastStatusAt < 1000) {
+                                    return;
+                                }
+                                lastStatusAt = Date.now();
+                                gateway
+                                    .request(`/agent-gateway/jobs/${job.jobId}/status`, { leaseToken: job.leaseToken, statusLine: line }, signal)
+                                    .catch(failService);
+                            },
+                        });
+                        // A transient delivery error retries this same completion. It must
+                        // never become a new provider run or a duplicate final reply.
+                        while (!(signal.aborted || cancel.signal.aborted)) {
+                            try {
+                                await gateway.request(`/agent-gateway/jobs/${job.jobId}/complete`, { leaseToken: job.leaseToken, text: result.text }, signal);
+                                break;
+                            }
+                            catch (error) {
+                                if (error instanceof GatewayError && error.status === 409) {
+                                    cancel.abort();
+                                }
+                                failService(error);
+                                await delay(2000, undefined, { signal }).catch(() => {
+                                    /* Shutdown interrupts the timer. */
+                                });
+                            }
+                        }
+                    }
+                    catch {
+                        if (!(signal.aborted || cancel.signal.aborted)) {
+                            await gateway
+                                .request(`/agent-gateway/jobs/${job.jobId}/fail`, { leaseToken: job.leaseToken }, signal)
+                                .catch(failService);
+                        }
+                    }
+                    finally {
+                        active = undefined;
+                    }
+                    continue;
+                }
+                if (wakePending) {
+                    continue;
+                }
+                await new Promise((resolve) => {
+                    const timer = setTimeout(finish, push ? HEARTBEAT_MS : claimPollInterval(lastJobAt));
+                    function finish() {
+                        clearTimeout(timer);
+                        signal.removeEventListener("abort", finish);
+                        wakeResolve = undefined;
+                        resolve();
+                    }
+                    wakeResolve = finish;
+                    signal.addEventListener("abort", finish, { once: true });
+                    if (signal.aborted || wakePending) {
+                        finish();
+                    }
+                });
+            }
+            if (terminalError) {
+                throw terminalError;
+            }
+            return null;
+        }
+        finally {
+            service.abort();
+            active?.cancel.abort();
+            clearInterval(watchdog);
+            await heartbeats;
+            await dispose?.();
+        }
+    }
+    finally {
+        await release();
+    }
+}

package/dist/agent/sessions.js

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isMissing, writePrivateFile } from "../agent-config.js";
+// One file per agent already supplies the agentId half of the session key.
+export class SessionMap {
+    path;
+    constructor(directory) {
+        this.path = join(directory, "sessions.json");
+    }
+    async get(threadId) {
+        return (await this.read())[threadId];
+    }
+    async remember(threadId, sessionId) {
+        const sessions = await this.read();
+        sessions[threadId] = sessionId;
+        await writePrivateFile(this.path, `${JSON.stringify(sessions)}\n`);
+    }
+    async read() {
+        try {
+            const value = JSON.parse(await readFile(this.path, "utf8"));
+            if (!value ||
+                typeof value !== "object" ||
+                Array.isArray(value) ||
+                Object.values(value).some((session) => typeof session !== "string")) {
+                throw new Error("Agent sessions are invalid. Restore sessions.json before serving.");
+            }
+            return value;
+        }
+        catch (error) {
+            if (isMissing(error)) {
+                return {};
+            }
+            throw error;
+        }
+    }
+}