talentos 0.3.0 → 1.1.0

package/README.md

@@ -1,126 +1,168 @@
 # talentos
 
-A thin [stdio MCP](https://modelcontextprotocol.io) server that wraps the TalentOS
-external HTTP API (`/api/v0/*`). Point any MCP-capable agent (Claude Code, Claude
-Desktop, Cursor, etc.) at it and the agent can read your org's workflows and
-nodes, then create or replace its own private Skills through the same API key.
-
-Published to npm as [`talentos`](https://www.npmjs.com/package/talentos) — run it
-with `npx -y talentos`, no checkout or build required.
-
-It exposes six tools:
-
-- **`get_context`** (no arguments) — one compact org summary: company profile
-  basics plus the names of the org's published workflows and nodes.
-  Good first call to prime an agent.
-- **`list_workflows`** (no arguments) — published workflows plus drafts created
-  by the API key's owner as a compact text list (status, title, id, step count,
-  department, description, ISO `updatedAt`).
-- **`get_workflow`** (`{ workflowId: string }`) — one workflow as an
-  agent-ready Markdown runbook, including its `**Version:**` stamp.
-- **`list_nodes`** (no arguments) — company-wide reusable nodes as name, id,
-  step type, summary, and tools.
-- **`create_skill`** (`{ name, summary, instructions, successCriteria?,
-  requestedTools? }`) — create a new Skill from plain-text instructions.
-  Returns the new `skillId` and its version. The Skill is private to the API
-  key's owner, who curates it in their TalentOS Skills library.
-- **`update_skill`** (`{ skillId, name, summary, instructions,
-  successCriteria?, requestedTools? }`) — replace one of the API key owner's
-  private Skills with a complete new body. Only that owner's private Skills are
-  writable; published and shared Skills stay human-owned.
-
-The server holds no state and stores nothing. Every call is a single
-authenticated request to the HTTP API; all authorization and visibility rules
-live server-side.
-
-## Configuration
-
-Only `TALENTOS_API_KEY` is required — the server exits immediately with a message
-on stderr if it's missing. `TALENTOS_API_URL` is optional: it defaults to the
-production TalentOS deployment, so most users never set it.
-
-| Variable            | Required | Description                                                                                                   |
-| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
-| `TALENTOS_API_KEY`  | yes      | An API key you create in the TalentOS admin UI. Sent as `Authorization: Bearer <key>`. Never logged.          |
-| `TALENTOS_API_URL`  | no       | Override the API base URL to target a non-production deployment. Defaults to the production `https://<name>.convex.site` origin. Must be the `.convex.site` domain, **not** `.convex.cloud`. |
-
-## Install
-
-Nothing to install ahead of time — `npx` fetches the published package on first
-run and caches it:
+The TalentOS CLI. It connects the coding agent on your machine to your team's
+governed brain, for four jobs:
+
+1. **Push** a skill your agent wrote into TalentOS, then share it with the company.
+2. **Pull** the company's skills into your agent's skill folder.
+3. **Memory** — read and write what you and the team know.
+4. **Delegate** work to your Talent so it runs inside TalentOS governance
+   (connectors, approvals, audit) and reports back.
+
+It is an MCP client for the remote TalentOS server. `talentos mcp` also runs that
+same server over stdio for clients that cannot speak streamable HTTP.
+
+## Quick start
+
+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 -y talentos
+npx talentos@1 init
 ```
 
-The `-y` skips the install prompt so noninteractive MCP clients don't hang. The
-first launch does a one-time network fetch to populate the npx cache (then exits
-asking for `TALENTOS_API_KEY`); run it once by hand — or pin a version like
-`talentos@0.3.0` — before wiring it into an offline or CI environment.
+`init` is the whole setup in one command. It:
+
+1. **Signs you in** — skipped when the key already on this machine still works.
+2. **Detects your coding agents** — Claude Code (the `claude` command on your
+   PATH, or `~/.claude`), Cursor (`~/.cursor` or `./.cursor`), Codex (`~/.codex`).
+   `--for claude|cursor|codex|all` overrides detection.
+3. **Writes the MCP config** for each of them, at user level (see the table below).
+4. **Pulls the company's skills** into `./.agents/skills` — the folder Cursor and
+   Codex auto-load — plus `./.claude/skills` when Claude Code is here. `--no-pull`
+   skips this.
+
+Then ask your agent to call the `talentos` `whoami` tool. Re-running `init` is
+safe: the config entry is replaced (so a new key takes effect) and skills are
+overwritten by slug.
 
-## Add it to Claude Code
+| agent | what `init` writes |
+| --- | --- |
+| Claude Code | `claude mcp add --scope user --transport http talentos <url> --header ...` (prints the command if `claude` is not on your PATH) |
+| Cursor | `~/.cursor/mcp.json` → `mcpServers.talentos` (other servers kept, mode 0600) |
+| Codex | `~/.codex/config.toml` → `[mcp_servers.talentos]`, the stdio proxy carrying `TALENTOS_API_KEY` and `TALENTOS_API_URL` (mode 0600) |
+
+**Nothing is written inside the repo except pulled skills.** Your API key lives in
+`~/.config/talentos/config.json` and in those user-level agent configs, never in
+a file your team could check in.
+
+## Login on its own
 
 ```bash
-claude mcp add talentos \
-  -e TALENTOS_API_KEY=tos_your_key_here \
-  -- npx -y talentos
+npx talentos@1 login
 ```
 
-Then ask Claude Code to *"list our TalentOS workflows and show me one as
-markdown"* — it calls `list_workflows`, picks an id, and calls `get_workflow`.
-
-## Add it to any other MCP client
-
-Add this to your MCP client config (`.mcp.json`, Claude Desktop config, etc.):
-
-```json
-{
-  "mcpServers": {
-    "talentos": {
-      "command": "npx",
-      "args": ["-y", "talentos"],
-      "env": {
-        "TALENTOS_API_KEY": "tos_your_key_here"
-      }
-    }
-  }
-}
+`login` mints an API key **on your machine**, registers only its SHA-256 hash,
+and asks you to approve the device in TalentOS. The raw key is written to
+`~/.config/talentos/config.json` (mode 0600) and never leaves the machine.
+
+It prints an eight-character code and, when the server returns an approval link,
+opens it. Otherwise open TalentOS yourself, go to **Settings → Agents & CLI**, and
+enter the code there.
+
+Already have a key? `npx talentos@1 login --key tos_...` — it is checked for shape
+before it is sent, and stored only once TalentOS accepts it.
+
+## Connect one agent by hand
+
+`talentos mcp install <client>` prints the snippet for your client; add
+`--apply` to write it for you (the same user-level write `init` does):
+
+| client | what you get |
+| --- | --- |
+| `claude` | a `claude mcp add --scope user --transport http` command |
+| `cursor` | the `~/.cursor/mcp.json` entry |
+| `codex` | the `~/.codex/config.toml` entry (stdio, via `npx -y talentos@1 mcp`, with the API url in its env) |
+| `json` | a generic `mcpServers` entry (print only) |
+
+## 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>]
+
+talentos login [--key <key>] [--api-url <url>] [--name <device>]
+talentos logout
+talentos whoami
 
-## Five-minute smoke test
+talentos mcp                                    # stdio proxy to the remote server
+talentos mcp install <claude|cursor|codex|json> [--apply]
 
-1. **Create a key.** In the TalentOS admin UI, create an API key. Copy the
-   `tos_...` value (you only see it once).
+talentos skills list [--mine|--company] [-q <query>]
+talentos skills get <id|slug> [--out <dir>]     # prints SKILL.md, or writes the package
+talentos skills push <SKILL.md|dir> [--id <skillId>]
+talentos skills pull [--for claude|cursor|codex|all] [--global] [--to <dir>] [--mine|--company]
+talentos skills share <id>                       # refuses: Share this Skill from TalentOS.
+
+talentos memory search "<query>" [--personal|--company]
+talentos memory add "<fact>" [--company]
+
+talentos ask "<message>" [--thread <id>] [--no-wait]
+talentos routines list
+talentos routines run <id>
+```
 
-2. **Curl the list endpoint** to confirm the key and URL work before involving an
-   agent:
+`skills pull` writes to `./.agents/skills` by default. `--for claude` writes to
+`./.claude/skills`, `--for all` writes both, and `--global` puts the same folders
+under your home directory; an explicit `--to` wins over all of them.
 
-   ```bash
-   curl -H "Authorization: Bearer tos_your_key_here" \
-     https://your-deployment.convex.site/api/v0/workflows
-   ```
+One pull fetches at most 100 skills; if it hits that ceiling it says so on stderr
+— narrow it with `--mine`, `--company` or `-q <query>`. Two skills that share a
+slug both land: the second goes to `<slug>-<last 6 of its id>`.
 
-   You should get `{ "workflows": [ ... ] }`. A `401` means the key is wrong;
-   make sure you used the `.convex.site` domain, not `.convex.cloud`.
+After `skills push`, `skills get`, `ask` and `routines run`, the last line is
+`Open: <url>` — the deep link to that skill or thread in TalentOS.
 
-3. **Add the server** to your MCP client using a snippet above, with your real
-   key (the API URL defaults to production).
+Every command takes `--json` to print the raw structured result instead of text.
+`talentos --help` and `talentos <group> --help` print usage.
 
-4. **Ask the agent** to list your workflows, then create a Skill:
+A skill package is a `SKILL.md` (YAML frontmatter with `name` and `description`,
+body = the instructions) plus any supporting files next to it. `push` accepts the
+file or the folder that contains it; a folder is walked recursively, skipping
+`node_modules` and `.git`, capped at 100 text files and 512 KiB.
 
-   > List my TalentOS workflows, show me the first one as markdown, then create
-   > a Skill for candidate outreach.
+## Config and environment
 
-   The agent calls `list_workflows`, `get_workflow`, and `create_skill`. The new
-   Skill lands as a private Skill in TalentOS for its owner to review.
+| | |
+| --- | --- |
+| `~/.config/talentos/config.json` | `{ apiUrl, apiKey }`, mode 0600 (honours `XDG_CONFIG_HOME`) |
+| `TALENTOS_API_KEY` | overrides the stored key |
+| `TALENTOS_API_URL` | overrides the stored API url (default `https://woozy-oyster-769.convex.site`) |
+| `--api-url` | overrides both, for one command |
 
-## Errors you might see
+## Exit codes
 
-- **Unauthorized (401)** — `TALENTOS_API_KEY` is missing, wrong, or revoked.
-- **Not found (404)** — the workflow or skill `id` doesn't exist, or it is not
-  visible to this API key. `update_skill` only reaches the key owner's own
-  private Skills.
-- **Rate limited (429)** — the key is over its requests-per-minute budget;
-  wait a moment and retry.
-- **Could not reach the API** — `TALENTOS_API_URL` is wrong or unreachable;
-  confirm it is the `.convex.site` URL.
+| code | meaning |
+| --- | --- |
+| 0 | success |
+| 1 | any failure — one line on stderr, nothing on stdout |

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