talentos 0.3.0 → 1.1.0

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;
+        }
+    }
+}

package/dist/agent-config.js

@@ -0,0 +1,105 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { redactAgentOutput } from "./agent-link.js";
+import { warn } from "./format.js";
+import { homeDir } from "./install.js";
+const AGENT_ID = /^[a-z\d_-]+$/iu;
+export function agentsDir(home = homeDir()) {
+    return join(home, ".talentos", "agents");
+}
+export function agentConfigPath(agentId, home = homeDir()) {
+    if (!AGENT_ID.test(agentId)) {
+        throw new Error("Invalid agent ID.");
+    }
+    return join(agentsDir(home), `${agentId}.json`);
+}
+export function agentWorkDir(agentId, home = homeDir()) {
+    agentConfigPath(agentId, home);
+    return join(agentsDir(home), agentId, "work");
+}
+export function agentLogPath(agentId, home = homeDir()) {
+    agentConfigPath(agentId, home);
+    return join(agentsDir(home), agentId, "gateway.log");
+}
+export async function writePrivateFile(path, content) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    try {
+        if ((await readFile(path, "utf8")) === content) {
+            await chmod(path, 0o600);
+            return false;
+        }
+    }
+    catch (error) {
+        if (!isMissing(error)) {
+            throw error;
+        }
+    }
+    const temporary = `${path}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        await writeFile(temporary, content, { mode: 0o600, flag: "wx" });
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return true;
+}
+export async function storeAgent(config, home = homeDir()) {
+    await mkdir(agentsDir(home), { recursive: true, mode: 0o700 });
+    await chmod(agentsDir(home), 0o700);
+    await writePrivateFile(agentConfigPath(config.agentId, home), `${JSON.stringify(config, null, 2)}\n`);
+    await mkdir(agentWorkDir(config.agentId, home), {
+        recursive: true,
+        mode: 0o700,
+    });
+}
+export async function localAgents(home = homeDir()) {
+    let entries;
+    try {
+        entries = await readdir(agentsDir(home));
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return [];
+        }
+        throw error;
+    }
+    const agents = [];
+    for (const entry of entries.sort()) {
+        if (!entry.startsWith(".") && entry.endsWith(".json")) {
+            try {
+                const parsed = JSON.parse(await readFile(join(agentsDir(home), entry), "utf8"));
+                if (!isLinkedAgent(parsed) || entry !== `${parsed.agentId}.json`) {
+                    throw new Error("Invalid agent configuration.");
+                }
+                agents.push(parsed);
+            }
+            catch {
+                warn(`Skipping unreadable or invalid agent configuration ${redactAgentOutput(JSON.stringify(entry))}. Restore it to manage that agent.`);
+            }
+        }
+    }
+    return agents;
+}
+function isLinkedAgent(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const config = value;
+    return (typeof config.agentId === "string" &&
+        AGENT_ID.test(config.agentId) &&
+        typeof config.apiKey === "string" &&
+        config.apiKey.startsWith("tos_") &&
+        typeof config.apiUrl === "string" &&
+        typeof config.name === "string" &&
+        typeof config.linkHash === "string" &&
+        typeof config.linkedAt === "number" &&
+        (config.provider === "claude_code" || config.provider === "codex"));
+}
+export function isMissing(error) {
+    return (error !== null &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/agent-http.js

@@ -0,0 +1,176 @@
+import { spawnSync } from "node:child_process";
+import { isSecureUrl, } from "./agent-link.js";
+const REQUEST_TIMEOUT_MS = 10_000;
+const HEARTBEAT_WINDOW_MS = 60_000;
+export class AgentHttpError extends Error {
+    status;
+    retryAfterMs;
+    constructor(operation, response) {
+        super(`${operation} (HTTP ${response.status}). Ask for a fresh setup prompt if this link expired.`);
+        this.status = response.status;
+        const seconds = Number(response.headers.get("Retry-After"));
+        this.retryAfterMs = Number.isFinite(seconds)
+            ? Math.max(0, Math.min(60_000, seconds * 1000))
+            : 0;
+    }
+}
+export function apiOrigin(value) {
+    try {
+        const url = new URL(value);
+        if (!(isSecureUrl(url) && url.pathname === "/" && !url.search && !url.hash)) {
+            throw new Error("Invalid origin");
+        }
+        return url.origin;
+    }
+    catch {
+        throw new Error("Use a secure TalentOS API origin with --api-url.");
+    }
+}
+export async function setupApiOrigin(link, override) {
+    if (override) {
+        return apiOrigin(override);
+    }
+    const response = await safeFetch(link.setupUrl);
+    const apiUrl = response.headers.get("X-TalentOS-Api-Url");
+    if (!(response.ok && apiUrl)) {
+        throw new Error("The setup page is unavailable. Ask for a fresh prompt or supply its API origin with --api-url.");
+    }
+    return apiOrigin(apiUrl);
+}
+export function inspectProvider(provider) {
+    const binary = provider === "claude_code" ? "claude" : "codex";
+    const version = spawnSync(binary, ["--version"], {
+        encoding: "utf8",
+        timeout: REQUEST_TIMEOUT_MS,
+    });
+    if (version.status !== 0 || !version.stdout?.trim()) {
+        throw new Error(`Install the official ${binary} CLI and sign in before linking.`);
+    }
+    const args = provider === "claude_code"
+        ? ["auth", "status", "--json"]
+        : ["login", "status"];
+    const login = spawnSync(binary, args, {
+        encoding: "utf8",
+        timeout: REQUEST_TIMEOUT_MS,
+    });
+    if (login.status !== 0) {
+        throw new Error(`Sign in through the official ${binary} CLI before linking.`);
+    }
+    if (provider === "claude_code") {
+        let loggedIn = false;
+        try {
+            const status = JSON.parse(login.stdout);
+            loggedIn =
+                !!status &&
+                    typeof status === "object" &&
+                    "loggedIn" in status &&
+                    status.loggedIn === true;
+        }
+        catch {
+            loggedIn = false;
+        }
+        if (!loggedIn) {
+            throw new Error("Sign in through the official claude CLI before linking.");
+        }
+    }
+    return version.stdout.trim().split("\n")[0]?.slice(0, 200) ?? "unknown";
+}
+export async function redeemAgent(apiUrl, body) {
+    const response = await safeFetch(`${apiOrigin(apiUrl)}/agent-link/redeem`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        throw new AgentHttpError("Could not redeem this link", response);
+    }
+    const value = await readJson(response);
+    if (!value ||
+        typeof value !== "object" ||
+        !("agentId" in value && "name" in value) ||
+        typeof value.agentId !== "string" ||
+        typeof value.name !== "string") {
+        throw new Error("TalentOS returned an invalid agent link. Ask for a fresh prompt.");
+    }
+    return { agentId: value.agentId, name: value.name };
+}
+export async function fetchAgentStatus(agent) {
+    const response = await safeFetch(`${apiOrigin(agent.apiUrl)}/agent-link/status`, { headers: { Authorization: `Bearer ${agent.apiKey}` } });
+    if (!response.ok) {
+        throw new AgentHttpError("Could not check the agent", response);
+    }
+    const value = await readJson(response);
+    if (!value || typeof value !== "object") {
+        throw new Error("TalentOS returned an invalid agent status.");
+    }
+    const status = value;
+    if (typeof status.agentId !== "string" ||
+        (agent.agentId !== undefined && status.agentId !== agent.agentId) ||
+        status.provider !== agent.provider ||
+        typeof status.name !== "string" ||
+        !Number.isFinite(status.serverNow) ||
+        !(status.lastSeenAt === null || typeof status.lastSeenAt === "number") ||
+        !["online", "busy", "offline"].includes(String(status.presence))) {
+        throw new Error("TalentOS returned an invalid agent status.");
+    }
+    return status;
+}
+export async function unlinkRemoteAgent(agent) {
+    const response = await safeFetch(`${apiOrigin(agent.apiUrl)}/agent-link/unlink`, { method: "POST", headers: { Authorization: `Bearer ${agent.apiKey}` } });
+    if (response.status === 401) {
+        return false;
+    }
+    if (!response.ok) {
+        throw new AgentHttpError("Could not disconnect the agent", response);
+    }
+    return true;
+}
+export async function waitForHeartbeat(agent, options = {}) {
+    const deadline = Date.now() + (options.timeoutMs ?? 10 * 60_000);
+    let serverStartedAt;
+    const wait = options.wait ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    while (Date.now() < deadline) {
+        let delay = 10_000;
+        try {
+            const status = await fetchAgentStatus(agent);
+            serverStartedAt ??= status.serverNow;
+            if (status.lastSeenAt !== null &&
+                status.lastSeenAt > serverStartedAt &&
+                status.lastSeenAt <= status.serverNow &&
+                status.serverNow - status.lastSeenAt < HEARTBEAT_WINDOW_MS &&
+                status.presence !== "offline") {
+                return status;
+            }
+        }
+        catch (error) {
+            if (error instanceof AgentHttpError && error.status === 401) {
+                throw error;
+            }
+            if (error instanceof AgentHttpError) {
+                delay = Math.max(delay, error.retryAfterMs);
+            }
+        }
+        await wait(Math.max(0, Math.min(delay, deadline - Date.now())));
+    }
+    return null;
+}
+async function safeFetch(url, init = {}) {
+    try {
+        return await fetch(url, {
+            ...init,
+            redirect: "error",
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new Error("Could not reach TalentOS. Check the network and try again.");
+    }
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new Error("TalentOS returned an invalid response.");
+    }
+}

package/dist/agent-link.js

@@ -0,0 +1,49 @@
+const INVALID_LINK = "Get a new setup prompt from TalentOS and pass its complete URL with --url.";
+const SETUP_PATH = /^\/agent-setup\/(claude_code|codex)\/?$/;
+const FRAGMENT_TOKEN = /((?:#|%23)token(?:=|%3d))[^\s"'<>]+/giu;
+const RAW_KEY = /\btos_[a-z\d_-]+/giu;
+const BEARER = /\bBearer\s+\S+/giu;
+const TOKEN_WHITESPACE = /\s/u;
+export function parseAgentLink(value) {
+    try {
+        const url = new URL(value);
+        const provider = SETUP_PATH.exec(url.pathname)?.[1];
+        const fragment = new URLSearchParams(url.hash.slice(1));
+        const tokens = fragment.getAll("token");
+        const token = tokens[0];
+        if (!(isSecureUrl(url) &&
+            (provider === "claude_code" || provider === "codex") &&
+            !url.search &&
+            fragment.size === 1 &&
+            tokens.length === 1 &&
+            token &&
+            token.length <= 200 &&
+            !TOKEN_WHITESPACE.test(token))) {
+            throw new Error(INVALID_LINK);
+        }
+        url.hash = "";
+        return { provider, setupUrl: url.href, token };
+    }
+    catch {
+        throw new Error(INVALID_LINK);
+    }
+}
+export function isSecureUrl(url) {
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    return (!(url.username || url.password) &&
+        (url.protocol === "https:" || (url.protocol === "http:" && loopback)));
+}
+export function redactAgentOutput(value, secrets = []) {
+    let safe = value;
+    for (const secret of secrets) {
+        if (secret) {
+            safe = safe
+                .replaceAll(secret, "[redacted]")
+                .replaceAll(encodeURIComponent(secret), "[redacted]");
+        }
+    }
+    return safe
+        .replace(FRAGMENT_TOKEN, "$1[redacted]")
+        .replace(RAW_KEY, "[redacted key]")
+        .replace(BEARER, "Bearer [redacted]");
+}