talentos 0.2.0 → 1.0.0

package/README.md

@@ -1,127 +1,137 @@
 # 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 workflow drafts 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_workflow`** (`{ title, steps, connections }`) — create a new draft
-  workflow from a full plan. Steps may include `outputs`, `successCriteria`, and
-  `runtime` contract fields. Writes always create drafts; a human publishes in
-  the app.
-- **`update_workflow`** (`{ workflowId, title, steps, connections }`) —
-  replace an existing draft workflow from a full plan. Steps may include
-  `outputs`, `successCriteria`, and `runtime`; published workflows return a
-  clear conflict instead of being edited.
-
-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.
 
 ```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.2.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.
 
-## Add it to Claude Code
+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.
+
+| 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
+
 ```
+talentos init [--for claude|cursor|codex|all] [--no-pull] [--name <device>]
 
-## Five-minute smoke test
+talentos login [--key <key>] [--api-url <url>] [--name <device>]
+talentos logout
+talentos whoami
 
-1. **Create a key.** In the TalentOS admin UI, create an API key. Copy the
-   `tos_...` value (you only see it once).
+talentos mcp                                    # stdio proxy to the remote server
+talentos mcp install <claude|cursor|codex|json> [--apply]
+
+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 draft:
+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 new draft workflow for candidate outreach.
+## Config and environment
 
-   The agent calls `list_workflows`, `get_workflow`, and `create_workflow`. The
-   new workflow lands as a draft in TalentOS for a human to review and publish.
+| | |
+| --- | --- |
+| `~/.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.
-- **Workflow not found (404)** — the `id` doesn't exist or it is not visible to
-  this API key.
-- **Published workflow conflict (409)** — `update_workflow` only edits drafts;
-  published workflows must be duplicated or edited in TalentOS.
-- **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/args.js

@@ -0,0 +1,49 @@
+import { parseArgs } from "node:util";
+const CLI_OPTIONS = {
+    json: { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+    key: { type: "string" },
+    "api-url": { type: "string" },
+    name: { type: "string" },
+    out: { type: "string" },
+    to: { type: "string" },
+    id: { type: "string" },
+    mine: { type: "boolean" },
+    company: { type: "boolean" },
+    personal: { type: "boolean" },
+    query: { type: "string", short: "q" },
+    thread: { type: "string" },
+    "no-wait": { type: "boolean" },
+    for: { type: "string" },
+    global: { type: "boolean" },
+    apply: { type: "boolean" },
+    "no-pull": { type: "boolean" },
+};
+/** Groups whose first positional is a sub-command rather than an argument. */
+const ACTION_GROUPS = new Set(["mcp", "skills", "memory", "routines"]);
+export function parseArgv(argv) {
+    const { values, positionals } = parse(argv);
+    const group = positionals[0];
+    const hasAction = group !== undefined && ACTION_GROUPS.has(group);
+    const action = hasAction ? positionals[1] : undefined;
+    return {
+        group,
+        action,
+        args: positionals.slice(action === undefined ? 1 : 2),
+        options: values,
+    };
+}
+function parse(argv) {
+    try {
+        return parseArgs({
+            args: argv,
+            options: CLI_OPTIONS,
+            allowPositionals: true,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message.split("\n")[0] : String(error);
+        throw new Error(`${message} Run \`talentos --help\`.`);
+    }
+}

package/dist/client.js

@@ -0,0 +1,87 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { requireCredentials, resolveApiUrl, } from "./config.js";
+const CLIENT_INFO = { name: "talentos-cli", version: "1.0.0" };
+const UNAUTHORIZED_HINT = /\b401\b|unauthoriz/i;
+const UNREACHABLE_HINT = /fetch failed|ECONNREFUSED|ENOTFOUND/i;
+export const UNAUTHORIZED = "Not logged in or key revoked. Run `talentos login`.";
+/** MCP client for the remote TalentOS server, one process-lived connection. */
+export class AgentClient {
+    credentials;
+    client;
+    constructor(credentials) {
+        this.credentials = credentials;
+    }
+    async call(name, args) {
+        const client = await this.connect();
+        const result = (await withFriendlyErrors(() => client.callTool({ name, arguments: args })));
+        const text = firstText(result);
+        if (result.isError) {
+            throw new Error(text || `Tool ${name} failed.`);
+        }
+        return { text, data: result.structuredContent };
+    }
+    async listTools() {
+        const client = await this.connect();
+        return await withFriendlyErrors(() => client.listTools());
+    }
+    async callTool(params) {
+        const client = await this.connect();
+        return (await withFriendlyErrors(() => client.callTool(params)));
+    }
+    async close() {
+        const client = this.client;
+        this.client = undefined;
+        await client?.close();
+    }
+    async connect() {
+        if (this.client) {
+            return this.client;
+        }
+        const client = new Client(CLIENT_INFO, { capabilities: {} });
+        const transport = new StreamableHTTPClientTransport(new URL(`${this.credentials.apiUrl}/mcp`), {
+            requestInit: {
+                headers: { Authorization: `Bearer ${this.credentials.apiKey}` },
+            },
+        });
+        await withFriendlyErrors(() => client.connect(transport));
+        this.client = client;
+        return client;
+    }
+}
+export async function withClient(apiUrlOverride, run) {
+    const credentials = await requireCredentials();
+    const client = new AgentClient({
+        ...credentials,
+        apiUrl: resolveApiUrl(apiUrlOverride, credentials.apiUrl),
+    });
+    try {
+        return await run(client);
+    }
+    finally {
+        await client.close();
+    }
+}
+function firstText(result) {
+    const block = result.content?.[0];
+    return block && block.type === "text" ? block.text : "";
+}
+async function withFriendlyErrors(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        throw new Error(describe(error));
+    }
+}
+function describe(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error?.code;
+    if (code === 401 || UNAUTHORIZED_HINT.test(message)) {
+        return UNAUTHORIZED;
+    }
+    if (UNREACHABLE_HINT.test(message)) {
+        return "Cannot reach TalentOS. Check your connection or --api-url.";
+    }
+    return message;
+}

package/dist/commands/ask.js

@@ -0,0 +1,74 @@
+import { withClient } from "../client.js";
+import { dim, emit, emitJson, emitLink } from "../format.js";
+const POLL_INTERVAL_MS = 2000;
+const MAX_WAIT_MS = 10 * 60 * 1000;
+// The two non-terminal webChannelMessages statuses; anything else means the
+// Talent is done with that message.
+const IN_FLIGHT_STATUSES = new Set(["queued", "claimed"]);
+export function isTerminalStatus(status) {
+    return !IN_FLIGHT_STATUSES.has(status);
+}
+export function replyAfter(messages, messageId) {
+    const index = messages.findIndex((message) => message.id === messageId);
+    const candidates = messages
+        .slice(index + 1)
+        .filter((message) => message.role === "talent");
+    return candidates.at(-1);
+}
+export async function runAsk(parsed) {
+    const message = parsed.args.join(" ").trim();
+    if (message === "") {
+        throw new Error('Usage: talentos ask "<message>" [--thread <id>] [--no-wait]');
+    }
+    await withClient(parsed.options["api-url"], async (client) => {
+        const { data } = await client.call("ask_talent", {
+            message,
+            ...(parsed.options.thread ? { threadId: parsed.options.thread } : {}),
+        });
+        const json = parsed.options.json === true;
+        if (parsed.options["no-wait"]) {
+            reportHandoff(data.threadId, json, data.url);
+            return;
+        }
+        emit(dim(`Asked your Talent. Thread ${data.threadId}`));
+        const reply = await waitForReply(client, data.threadId, data.messageId);
+        if (!reply) {
+            reportHandoff(data.threadId, json, data.url);
+            return;
+        }
+        if (json) {
+            emitJson({ threadId: data.threadId, message: reply });
+            return;
+        }
+        emit(reply.body);
+        emitLink(data.url);
+    });
+}
+async function waitForReply(client, threadId, messageId) {
+    const deadline = Date.now() + MAX_WAIT_MS;
+    while (Date.now() < deadline) {
+        await sleep(POLL_INTERVAL_MS);
+        const { data } = await client.call("get_thread", { threadId });
+        const reply = replyAfter(data.messages, messageId);
+        if (reply && isTerminalStatus(reply.status)) {
+            return reply;
+        }
+        if (!data.active && reply) {
+            return reply;
+        }
+    }
+    return;
+}
+function reportHandoff(threadId, json, url) {
+    if (json) {
+        emitJson({ threadId });
+        return;
+    }
+    emit(`Your Talent is still working. Open thread ${threadId} in TalentOS for the reply, or keep the conversation going with \`talentos ask "<message>" --thread ${threadId}\`.`);
+    emitLink(url);
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/commands/init.js

@@ -0,0 +1,98 @@
+import { withClient } from "../client.js";
+import { bold, dim, emit } from "../format.js";
+import { agentLabel, agentTargetsFor, applyInstall, buildInstallSnippet, defaultProbe, detectAgents, homeDir, pullDirs, } from "../install.js";
+import { authorize, currentSession } from "./login.js";
+import { pullInto } from "./skills.js";
+import { memberLabel } from "./whoami.js";
+const DONE = "✓";
+const SKIPPED = "·";
+const TRAILING_PUNCTUATION = /[.:\s]+$/;
+/**
+ * The one command a new member runs: sign in, configure every coding agent on
+ * this machine at user level, and drop the company's skills where those agents
+ * already look for them.
+ */
+export async function runInit(parsed) {
+    const session = await signIn(parsed);
+    const targets = chosenTargets(parsed.options.for);
+    if (targets.length === 0) {
+        step(false, "No coding agent found. Re-run with --for claude|cursor|codex.");
+    }
+    const configured = [];
+    for (const target of targets) {
+        if (await configure(target, session.credentials)) {
+            configured.push(target);
+        }
+    }
+    const pulled = parsed.options["no-pull"]
+        ? undefined
+        : await pullShared(parsed, targets);
+    emit(summary(configured, pulled));
+}
+async function signIn(parsed) {
+    const stored = await currentSession(parsed);
+    const session = stored ?? (await authorize(parsed));
+    const member = memberLabel(session.who.member);
+    const organization = session.who.organization.name;
+    step(true, `${stored ? "Already signed in" : "Signed in"} as ${member} · ${organization}`);
+    return { credentials: session.credentials, member, organization };
+}
+function chosenTargets(forOption) {
+    return forOption === undefined
+        ? detectAgents(defaultProbe())
+        : agentTargetsFor(forOption);
+}
+async function configure(target, credentials) {
+    const label = agentLabel(target);
+    const snippet = () => buildInstallSnippet(target, credentials);
+    try {
+        const outcome = await applyInstall(target, credentials);
+        if (outcome.applied) {
+            step(true, `${label} → ${outcome.detail}`);
+            return true;
+        }
+        emit(manualInstallNotice(label, outcome.detail, snippet()));
+    }
+    catch (error) {
+        emit(manualInstallNotice(label, messageOf(error), snippet()));
+    }
+    return false;
+}
+/** Every failure ends the same way: why, then the command to run by hand. */
+export function manualInstallNotice(label, reason, snippet) {
+    const why = reason.replace(TRAILING_PUNCTUATION, "");
+    return `${SKIPPED} ${label}: ${why}. Run it yourself:\n  ${snippet}`;
+}
+/**
+ * Cursor and Codex both auto-load `./.agents/skills`; Claude Code needs its own
+ * folder as well. Both live in the working tree, the only place `init` writes
+ * inside a repo.
+ */
+async function pullShared(parsed, targets) {
+    const dirs = pullDirs({
+        home: homeDir(),
+        target: targets.includes("claude") ? "all" : undefined,
+    });
+    const pulled = await withClient(parsed.options["api-url"], (client) => pullInto(client, dirs, "company"));
+    step(pulled.length > 0, pulled.length === 0
+        ? "No company skills to pull yet."
+        : `${pulled.length} skill(s) → ${dirs.join(", ")}`);
+    return pulled.length;
+}
+function summary(configured, pulled) {
+    const agents = configured.length === 0 ? "none" : configured.map(agentLabel).join(", ");
+    return [
+        "",
+        bold("TalentOS is connected."),
+        `Agents configured: ${agents}`,
+        `Skills written: ${pulled ?? "skipped (--no-pull)"}`,
+        dim("Next: ask your agent to call the talentos whoami tool."),
+    ].join("\n");
+}
+function step(done, text) {
+    emit(`${done ? DONE : SKIPPED} ${text}`);
+}
+function messageOf(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.split("\n")[0] ?? message;
+}