talentos 1.4.22 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/README.md +120 -17
  2. package/dist/agent/adapters.js +12 -2
  3. package/dist/agent/codex-policy.js +71 -0
  4. package/dist/agent/native/touch.js +18 -8
  5. package/dist/agent/provider-failure.js +9 -2
  6. package/dist/agent/serve.js +28 -5
  7. package/dist/agent/talentos-content.js +33 -0
  8. package/dist/agent-link.js +31 -3
  9. package/dist/args.js +14 -1
  10. package/dist/claude-plugin.js +82 -0
  11. package/dist/client.js +8 -4
  12. package/dist/commands/agent.js +1 -1
  13. package/dist/commands/approvals.js +145 -0
  14. package/dist/commands/doctor.js +427 -0
  15. package/dist/commands/init.js +78 -9
  16. package/dist/commands/login.js +10 -1
  17. package/dist/commands/mcp.js +17 -2
  18. package/dist/commands/publish.js +74 -0
  19. package/dist/commands/skills-sync.js +174 -0
  20. package/dist/commands/skills.js +24 -4
  21. package/dist/commands/task.js +77 -0
  22. package/dist/commands/tools.js +56 -0
  23. package/dist/config.js +34 -0
  24. package/dist/format.js +12 -0
  25. package/dist/hosting-skill.js +67 -0
  26. package/dist/index.js +129 -23
  27. package/dist/install.js +126 -38
  28. package/dist/memory-wire.js +22 -0
  29. package/dist/output.js +107 -0
  30. package/dist/publish-site.js +291 -0
  31. package/dist/published-pages.js +30 -0
  32. package/dist/setup.generated.js +180 -0
  33. package/dist/skill-files.js +1 -1
  34. package/dist/skill-sync-state.js +38 -0
  35. package/dist/upload-file.js +1 -1
  36. package/dist/watch.js +39 -0
  37. package/package.json +3 -2
  38. package/plugin/.claude-plugin/marketplace.json +12 -0
  39. package/plugin/plugins/talentos/.claude-plugin/plugin.json +9 -0
  40. package/plugin/plugins/talentos/.mcp.json +8 -0
  41. package/plugin/plugins/talentos/commands/ask-talent.md +21 -0
  42. package/plugin/plugins/talentos/commands/catch-up.md +16 -0
  43. package/plugin/plugins/talentos/commands/remember.md +15 -0
  44. package/plugin/plugins/talentos/hooks/hooks.json +17 -0
  45. package/plugin/plugins/talentos/scripts/session-start.mjs +177 -0
package/dist/index.js CHANGED
@@ -2,7 +2,8 @@
2
2
  import { readFileSync } from "node:fs";
3
3
  import { redactAgentOutput } from "./agent-link.js";
4
4
  import { parseArgv } from "./args.js";
5
- import { emit } from "./format.js";
5
+ import { emit, emitJson } from "./format.js";
6
+ import { CliError, cliContractEnabled, machineOutput, runJsonCommand, } from "./output.js";
6
7
  import { ProviderBinaryError } from "./provider-binary.js";
7
8
  const USAGE = `talentos — your team's skills, memory and Talent, from any agent.
8
9
 
@@ -10,26 +11,51 @@ Usage: talentos <command> [options]
10
11
 
11
12
  Commands:
12
13
  init Connect this machine's agents to TalentOS
14
+ doctor Check what is connected and how to fix what is not
13
15
  agent <link|repair|status|list|unlink|logs|connect-session> Bring your own agent into Rooms
14
16
  login Authorize this machine
15
17
  logout Forget the key stored on this machine
16
18
  whoami Show the member and org this key acts as
17
19
  mcp Run the stdio MCP proxy (for stdio-only clients)
18
20
  mcp install <target> [--apply] Configure one client, or print its snippet
19
- skills <list|get|push|pull|share> Move skills; sharing stays in TalentOS
21
+ skills <list|get|push|pull|sync|share> Move skills; sharing stays in TalentOS
20
22
  memory <search|add> Read and write personal and company memory
21
23
  ask "<message>" Delegate work to your Talent
24
+ publish [folder|page.html] Publish a web page to your TalentOS Library
22
25
  routines <list|run> See and run your routines
26
+ tools List the tools this member can use with input schemas
27
+ call <tool> [--json '<args>'] Call any visible MCP tool
28
+ task <status|watch> <id> Follow a delegated task without starting work
29
+ approvals [list|status|watch] [id] See what waits for the member's approval (read-only)
23
30
 
24
31
  Options:
25
- --json Print the raw JSON result
32
+ --json Print one JSON result (HEADLESS_CLI_V1=true); progress goes to stderr
26
33
  --api-url <url> Override the TalentOS API url
27
34
  -h, --help Show help
28
35
  -v, --version Show the version
29
36
 
30
37
  Run \`talentos <command> --help\` for command options.`;
31
38
  const GROUP_USAGE = {
32
- agent: `talentos agent link --url <setup-url-with-#token> [--yes] [--name <device>]
39
+ tools: "talentos tools [--json]\n\nLists the remote MCP tools and their input schemas, under this connection's permissions.",
40
+ call: `talentos call <tool> [--json '<args>']
41
+
42
+ Forwards one tool call with a JSON object (default {}). The MCP server owns
43
+ validation, visibility, permissions and approvals. Returns the full MCP result;
44
+ a tool error exits nonzero. Calls are never retried.`,
45
+ approvals: `talentos approvals [list] [--json]
46
+ talentos approvals status <approvalId> [--json]
47
+ talentos approvals watch [approvalId] [--json]
48
+
49
+ Reads the approvals your AI is waiting on (approval_status) and the TalentOS
50
+ link where the member decides. It cannot approve or decline anything: that is
51
+ the member's own tap. Watch follows changes until none waits, or ten minutes.`,
52
+ task: `talentos task status <id> [--json]
53
+ talentos task watch <id> [--json]
54
+
55
+ Read a delegate_task result through get_task. Watch waits for changes on the
56
+ server, stopping on completion, stale work, or a question for the member.
57
+ After ten minutes it returns the latest state with a continuation command.`,
58
+ agent: `talentos agent link --url <setup-url-with-#token> [--provider claude_code|codex|gemini_cli] [--yes] [--name <device>]
33
59
  talentos agent status | list [--json] [--agent <id>]
34
60
  talentos agent unlink [name] [--agent <id>]
35
61
  talentos agent logs [--agent <id>]
@@ -49,7 +75,13 @@ as that agent. It gets a key of its own, kept in a private file under
49
75
  talentos-room server. disconnect-session stops the key and removes the entry
50
76
  from every client (or only --for one);
51
77
  unlinking the agent stops it too.`,
52
- init: `talentos init [--for claude|cursor|codex|all] [--no-pull] [--name <device>]
78
+ doctor: `talentos doctor [--json] [--api-url <url>]
79
+
80
+ Says in plain words whether TalentOS answers with the key on this machine and
81
+ whether Claude Code, Cursor and Codex are set up, with the one fix for each
82
+ problem. Changes nothing and never prints a key. Exits 1 when something needs a
83
+ fix.`,
84
+ init: `talentos init [--for claude|cursor|codex|gemini|antigravity|all] [--no-pull] [--oauth] [--name <device>]
53
85
 
54
86
  One command: signs you in (skipped when your stored key still works), writes the
55
87
  TalentOS MCP config for every agent on this machine at USER level, and
@@ -58,6 +90,11 @@ Claude Code is here). Nothing else is written inside the repo. Safe to re-run.
58
90
 
59
91
  --for <agent> Configure these agents instead of the detected ones
60
92
  --no-pull Configure the agents but do not write any skills
93
+ --oauth Sign in through the browser instead of a key in each agent's
94
+ config: installs the Claude Code plugin (primer, /talentos
95
+ commands) and writes a keyless Codex entry; Cursor keeps its key. Also
96
+ on with HEADLESS_SETUP_V1=true. Needs a server that accepts
97
+ these clients.
61
98
  --name <device> Device name shown on the approval screen`,
62
99
  login: `talentos login [--key <key>] [--api-url <url>] [--name <device>]
63
100
 
@@ -69,22 +106,37 @@ key never leaves the machine; only its hash is registered.
69
106
  logout: "talentos logout\n\nRemoves the stored key from this machine.",
70
107
  whoami: "talentos whoami [--json]",
71
108
  mcp: `talentos mcp
72
- talentos mcp install <claude|cursor|codex|json> [--apply]
109
+ talentos mcp install <claude|cursor|codex|gemini|antigravity|json> [--apply]
73
110
 
74
111
  \`mcp\` runs a stdio MCP server that forwards to your TalentOS account.
75
112
  \`mcp install\` prints the config snippet for a client; \`--apply\` writes it to
76
- that client's user-level config (claude, cursor or codex).`,
113
+ that client's user-level config (claude, cursor, codex, gemini or antigravity).`,
77
114
  skills: `talentos skills list [--mine|--company] [-q <query>]
78
115
  talentos skills get <id|slug> [--out <dir>]
79
116
  talentos skills push <SKILL.md|dir> [--id <skillId>]
80
- talentos skills pull [--for claude|cursor|codex|all] [--global] [--to <dir>] [--mine|--company]
117
+ talentos skills pull [--for claude|cursor|codex|gemini|antigravity|all] [--global] [--to <dir>] [--mine|--company]
118
+ talentos skills sync [--for claude|cursor|codex|gemini|antigravity|all] [--global] [--to <dir>] [--mine|--company] [--quiet]
81
119
  talentos skills share <id> Refuses: Share this Skill from TalentOS.
82
120
 
83
121
  \`pull\` writes to ./.agents/skills by default; \`--for claude\` writes to
84
122
  ./.claude/skills, \`--for all\` writes both, and \`--global\` puts them under your
85
- home directory. An explicit \`--to\` wins.`,
123
+ home directory. An explicit \`--to\` wins.
124
+
125
+ \`sync\` rewrites only skills TalentOS changed, and never overwrites work you did
126
+ here: a skill you edited stays as it is (and is reported) until you run \`pull\`,
127
+ a folder it did not write is left alone, and it never deletes files you added.`,
86
128
  memory: `talentos memory search "<query>" [--personal|--company]
87
129
  talentos memory add "<fact>" [--company]`,
130
+ publish: `talentos publish [folder|page.html] [--title <title>] [--replace] [--json]
131
+
132
+ Publishes a web page (a folder's index.html, or one .html file) to your
133
+ TalentOS Library and prints its link. Only you can open it until you share it.
134
+ The page's own styles, scripts, images and fonts from the folder go inside the
135
+ page; it loads nothing from other websites. One page per site.
136
+
137
+ Publishing the same page again updates the same app, and TalentOS keeps every
138
+ version. If someone changed the app in TalentOS since, nothing is replaced
139
+ unless you add --replace.`,
88
140
  ask: `talentos ask "<message>" [--thread <id>] [--no-wait]
89
141
 
90
142
  Waits for your Talent's reply (up to 10 minutes) unless --no-wait.`,
@@ -93,16 +145,45 @@ talentos routines run <id>`,
93
145
  };
94
146
  async function main(argv) {
95
147
  const parsed = parseArgv(argv);
148
+ const output = machineOutput();
149
+ if (output) {
150
+ output.apiUrl = parsed.options["api-url"];
151
+ }
96
152
  if (parsed.options.version) {
97
- emit(version());
153
+ if (machineOutput()) {
154
+ emitJson({ version: version() });
155
+ }
156
+ else {
157
+ emit(version());
158
+ }
98
159
  return;
99
160
  }
100
161
  if (parsed.group === undefined || parsed.options.help) {
101
- emit(helpFor(parsed.group));
162
+ showHelp(parsed.group);
102
163
  return;
103
164
  }
165
+ if (machineOutput() &&
166
+ ((parsed.group === "mcp" && !parsed.action) ||
167
+ (parsed.group === "agent" &&
168
+ ["serve", "mcp"].includes(parsed.action ?? "")))) {
169
+ throw new CliError("INVALID_ARGUMENT", "--json is for command results. Start the MCP protocol or agent service without --json.");
170
+ }
171
+ if (machineOutput() &&
172
+ parsed.group === "agent" &&
173
+ parsed.action === "link" &&
174
+ !parsed.options.yes) {
175
+ throw new CliError("INVALID_ARGUMENT", "Use --yes only after the member approves installing the user service.");
176
+ }
104
177
  await dispatch(parsed);
105
178
  }
179
+ function showHelp(group) {
180
+ if (machineOutput()) {
181
+ emitJson({ help: helpFor(group) });
182
+ }
183
+ else {
184
+ emit(helpFor(group));
185
+ }
186
+ }
106
187
  function helpFor(group) {
107
188
  if (group === undefined) {
108
189
  return USAGE;
@@ -115,6 +196,8 @@ async function dispatch(parsed) {
115
196
  return await (await import("./commands/agent.js")).runAgent(parsed);
116
197
  case "init":
117
198
  return await (await import("./commands/init.js")).runInit(parsed);
199
+ case "doctor":
200
+ return await (await import("./commands/doctor.js")).runDoctor(parsed);
118
201
  case "login":
119
202
  return await (await import("./commands/login.js")).runLogin(parsed);
120
203
  case "logout":
@@ -131,8 +214,17 @@ async function dispatch(parsed) {
131
214
  return await (await import("./commands/ask.js")).runAsk(parsed);
132
215
  case "routines":
133
216
  return await (await import("./commands/routines.js")).runRoutines(parsed);
217
+ case "publish":
218
+ return await (await import("./commands/publish.js")).runPublish(parsed);
219
+ case "tools":
220
+ case "call":
221
+ return await (await import("./commands/tools.js")).runTools(parsed);
222
+ case "task":
223
+ return await (await import("./commands/task.js")).runTask(parsed);
224
+ case "approvals":
225
+ return await (await import("./commands/approvals.js")).runApprovals(parsed);
134
226
  case "help": {
135
- emit(helpFor(parsed.args[0]));
227
+ showHelp(parsed.args[0]);
136
228
  return;
137
229
  }
138
230
  default:
@@ -143,16 +235,30 @@ function version() {
143
235
  const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
144
236
  return manifest.version;
145
237
  }
146
- main(process.argv.slice(2)).catch((error) => {
238
+ const argv = process.argv.slice(2);
239
+ const fragments = argv.flatMap((arg) => {
240
+ try {
241
+ return new URLSearchParams(new URL(arg).hash.slice(1)).getAll("token");
242
+ }
243
+ catch {
244
+ return [];
245
+ }
246
+ });
247
+ const keyOption = argv.indexOf("--key");
248
+ const secrets = [
249
+ ...fragments,
250
+ process.env.TALENTOS_API_KEY ?? "",
251
+ ...(keyOption < 0 ? [] : [argv[keyOption + 1] ?? ""]),
252
+ ].filter(Boolean);
253
+ const optionArgs = argv.includes("--")
254
+ ? argv.slice(0, argv.indexOf("--"))
255
+ : argv;
256
+ const execution = cliContractEnabled() &&
257
+ optionArgs.some((arg) => arg === "--json" || arg.startsWith("--json="))
258
+ ? runJsonCommand(() => main(argv), secrets)
259
+ : main(argv);
260
+ execution.catch((error) => {
147
261
  const message = error instanceof Error ? error.message : String(error);
148
- const fragments = process.argv.flatMap((arg) => {
149
- try {
150
- return new URLSearchParams(new URL(arg).hash.slice(1)).getAll("token");
151
- }
152
- catch {
153
- return [];
154
- }
155
- });
156
- process.stderr.write(`${redactAgentOutput(message, fragments).split("\n")[0]}\n`);
157
- process.exit(error instanceof ProviderBinaryError ? error.exitCode : 1);
262
+ process.stderr.write(`${redactAgentOutput(message, secrets).split("\n")[0]}\n`);
263
+ process.exitCode = error instanceof ProviderBinaryError ? error.exitCode : 1;
158
264
  });
package/dist/install.js CHANGED
@@ -3,12 +3,20 @@ import { existsSync } from "node:fs";
3
3
  import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
4
4
  import { homedir } from "node:os";
5
5
  import { dirname, join } from "node:path";
6
- export const AGENT_TARGETS = ["claude", "cursor", "codex"];
6
+ import { mcpUrlFor } from "./config.js";
7
+ import { OAUTH_NEXT, setupEntry, setupSnippet } from "./setup.generated.js";
8
+ export const AGENT_TARGETS = [
9
+ "claude",
10
+ "cursor",
11
+ "codex",
12
+ "gemini",
13
+ "antigravity",
14
+ ];
7
15
  export const MCP_INSTALL_TARGETS = [...AGENT_TARGETS, "json"];
8
- /** Cursor and Codex both auto-load `.agents/skills`; Claude Code reads its own. */
16
+ /** Cursor, Codex, Gemini CLI and Antigravity CLI read `.agents/skills`;
17
+ * Claude Code reads its own. */
9
18
  const AGENTS_SKILLS_DIR = ".agents/skills";
10
19
  const CLAUDE_SKILLS_DIR = ".claude/skills";
11
- const CODEX_HEADER = "[mcp_servers.talentos]";
12
20
  const TOML_HEADER_START = "[";
13
21
  const TRAILING_NEWLINES = /\n*$/;
14
22
  export const CONFIG_MODE = 0o600;
@@ -21,7 +29,7 @@ const AGENT_SPECS = {
21
29
  label: "Claude Code",
22
30
  hint: "Run this once:",
23
31
  detect: (probe) => probe.which("claude") || probe.exists(join(probe.home, ".claude")),
24
- render: (credentials) => `claude mcp add --scope user --transport http talentos ${mcpUrl(credentials)} --header "Authorization: ${bearer(credentials)}"`,
32
+ render: (credentials, mode) => clientSnippet("claude", credentials, mode),
25
33
  skillDirs: [CLAUDE_SKILLS_DIR],
26
34
  },
27
35
  cursor: {
@@ -30,7 +38,9 @@ const AGENT_SPECS = {
30
38
  detect: (probe) => probe.exists(join(probe.home, ".cursor")) ||
31
39
  probe.exists(join(probe.cwd, ".cursor")),
32
40
  configPath: (home) => join(home, ".cursor", "mcp.json"),
33
- render: (credentials) => JSON.stringify(cursorEntry(credentials), null, 2),
41
+ // Cursor stays on the key in every mode: the server has no OAuth join rule
42
+ // for it yet (#15810).
43
+ render: (credentials) => clientSnippet("cursor", credentials, "key"),
34
44
  merge: (existing, credentials) => mergeCursorConfig(existing, credentials),
35
45
  skillDirs: [AGENTS_SKILLS_DIR],
36
46
  },
@@ -39,15 +49,39 @@ const AGENT_SPECS = {
39
49
  hint: "Add to ~/.codex/config.toml:",
40
50
  detect: (probe) => probe.exists(join(probe.home, ".codex")),
41
51
  configPath: (home) => join(home, ".codex", "config.toml"),
42
- // Codex speaks stdio only, so it launches this CLI as a proxy. The url
43
- // travels with the key: a staging key must not reach production.
44
- render: (credentials) => [
45
- CODEX_HEADER,
46
- 'command = "npx"',
47
- 'args = ["-y", "talentos@1", "mcp"]',
48
- `env = { TALENTOS_API_KEY = "${credentials.apiKey}", TALENTOS_API_URL = "${credentials.apiUrl}" }`,
49
- ].join("\n"),
50
- merge: (existing, credentials) => upsertCodexBlock(existing, credentials),
52
+ // `key`: Codex launches this CLI as a stdio proxy; the url travels with the
53
+ // key, because a staging key must not reach production. `oauth`: Codex
54
+ // speaks to the remote server itself and `codex mcp login talentos` signs
55
+ // the member in.
56
+ render: (credentials, mode) => clientSnippet("codex", credentials, mode),
57
+ merge: (existing, credentials, mode) => upsertCodexBlock(existing, credentials, mode),
58
+ skillDirs: [AGENTS_SKILLS_DIR],
59
+ },
60
+ // Gemini CLI (paid Gemini API key or enterprise accounts since Google moved
61
+ // personal accounts to Antigravity CLI on 2026-06-18). `oauth`: the member
62
+ // signs in with `/mcp auth talentos`, as any other app.
63
+ gemini: {
64
+ label: "Gemini CLI",
65
+ hint: "Add to ~/.gemini/settings.json:",
66
+ detect: (probe) => probe.which("gemini"),
67
+ configPath: (home) => join(home, ".gemini", "settings.json"),
68
+ render: (credentials, mode) => clientSnippet("gemini", credentials, mode),
69
+ merge: (existing, credentials, mode) => mergeJsonServer(existing, clientSnippet("gemini", credentials, mode), {
70
+ file: "~/.gemini/settings.json",
71
+ target: "gemini",
72
+ }),
73
+ skillDirs: [AGENTS_SKILLS_DIR],
74
+ },
75
+ // Antigravity CLI (agy) keeps MCP servers in their own file beside Gemini
76
+ // CLI's settings (antigravity.google/docs/cli/gcli-migration).
77
+ antigravity: {
78
+ label: "Antigravity CLI",
79
+ hint: "Add to ~/.gemini/config/mcp_config.json:",
80
+ detect: (probe) => probe.which("agy") ||
81
+ probe.exists(join(probe.home, ".gemini", "antigravity-cli")),
82
+ configPath: (home) => join(home, ".gemini", "config", "mcp_config.json"),
83
+ render: (credentials, mode) => clientSnippet("antigravity", credentials, mode),
84
+ merge: (existing, credentials, mode) => mergeJsonServer(existing, clientSnippet("antigravity", credentials, mode), { file: "~/.gemini/config/mcp_config.json", target: "antigravity" }),
51
85
  skillDirs: [AGENTS_SKILLS_DIR],
52
86
  },
53
87
  };
@@ -73,11 +107,20 @@ export function agentTargetsFor(value) {
73
107
  export function installHint(target) {
74
108
  return isAgentTarget(target) ? AGENT_SPECS[target].hint : GENERIC_HINT;
75
109
  }
76
- export function buildInstallSnippet(target, credentials) {
110
+ export function buildInstallSnippet(target, credentials, mode = "key") {
77
111
  return isAgentTarget(target)
78
- ? AGENT_SPECS[target].render(credentials)
112
+ ? AGENT_SPECS[target].render(credentials, mode)
79
113
  : JSON.stringify(cursorEntry(credentials), null, 2);
80
114
  }
115
+ /**
116
+ * The OAuth-first setup is dark: `--oauth` or `HEADLESS_SETUP_V1=true` turns it
117
+ * on. Until the server accepts these clients' loopback sign-in (see the
118
+ * agent-access doc), the default stays the key every client uses today.
119
+ */
120
+ export function setupModeFrom(options, env = process.env) {
121
+ const flag = env.HEADLESS_SETUP_V1?.trim().toLowerCase();
122
+ return options.oauth || flag === "true" || flag === "1" ? "oauth" : "key";
123
+ }
81
124
  /** Where Codex keeps its user-level MCP servers. */
82
125
  export function codexConfigPath(home) {
83
126
  return (AGENT_SPECS.codex.configPath?.(home) ?? join(home, ".codex", "config.toml"));
@@ -120,8 +163,43 @@ export function mergeCursorConfig(existing, credentials) {
120
163
  };
121
164
  return `${JSON.stringify(next, null, 2)}\n`;
122
165
  }
123
- export function upsertCodexBlock(existing, credentials) {
124
- return upsertCodexSection(existing, "talentos", AGENT_SPECS.codex.render(credentials));
166
+ /**
167
+ * Sets `mcpServers.talentos` in a JSON client config to the entry in
168
+ * `snippet`, keeping every other server and setting. A file that is not a
169
+ * plain JSON object, or whose `mcpServers` is not one, is refused rather than
170
+ * overwritten. Gemini CLI also reads comments in its settings, which a rewrite
171
+ * would drop, so such a file is refused too and the member adds the entry by
172
+ * hand. No message here holds the key.
173
+ */
174
+ export function mergeJsonServer(existing, snippet, where) {
175
+ const rerun = `then run \`npx talentos@1 init --for ${where.target}\` again`;
176
+ let config = {};
177
+ if (existing !== undefined && existing.trim() !== "") {
178
+ let parsed;
179
+ try {
180
+ parsed = JSON.parse(existing);
181
+ }
182
+ catch {
183
+ throw new Error(`${where.file} is not plain JSON (comments aren't supported). Add the talentos entry by hand, or fix the file, ${rerun}.`);
184
+ }
185
+ if (!isPlainObject(parsed)) {
186
+ throw new Error(`${where.file} is not a JSON object. Fix it, ${rerun}.`);
187
+ }
188
+ config = parsed;
189
+ }
190
+ if (config.mcpServers !== undefined && !isPlainObject(config.mcpServers)) {
191
+ throw new Error(`${where.file} has an mcpServers that is not an object. Fix it, ${rerun}.`);
192
+ }
193
+ const servers = config.mcpServers ?? {};
194
+ const entry = JSON.parse(snippet)
195
+ .mcpServers.talentos;
196
+ return `${JSON.stringify({ ...config, mcpServers: { ...servers, talentos: entry } }, null, 2)}\n`;
197
+ }
198
+ function isPlainObject(value) {
199
+ return typeof value === "object" && value !== null && !Array.isArray(value);
200
+ }
201
+ export function upsertCodexBlock(existing, credentials, mode = "key") {
202
+ return upsertCodexSection(existing, "talentos", AGENT_SPECS.codex.render(credentials, mode));
125
203
  }
126
204
  /** Replaces or appends the `[mcp_servers.<server>]` block, leaving the rest. */
127
205
  export function upsertCodexSection(existing, server, block) {
@@ -146,6 +224,14 @@ export function removeCodexSection(existing, server) {
146
224
  const rest = [...lines.slice(0, bounds.start), ...lines.slice(bounds.end)];
147
225
  return `${rest.join("\n").replace(TRAILING_NEWLINES, "")}\n`;
148
226
  }
227
+ /** The lines of the `[mcp_servers.<server>]` block (header excluded), if any. */
228
+ export function readCodexSection(existing, server) {
229
+ const lines = existing.split("\n");
230
+ const bounds = codexSectionBounds(lines, server);
231
+ return bounds === undefined
232
+ ? undefined
233
+ : lines.slice(bounds.start + 1, bounds.end).join("\n");
234
+ }
149
235
  function codexSectionBounds(lines, server) {
150
236
  const header = `[mcp_servers.${server}]`;
151
237
  const start = lines.findIndex((line) => line.trim() === header);
@@ -161,17 +247,17 @@ function codexSectionBounds(lines, server) {
161
247
  * Writes the MCP config for one agent at USER level. Nothing lands inside the
162
248
  * repo: a checked-in config would leak the member's key to the whole team.
163
249
  */
164
- export async function applyInstall(target, credentials, home = defaultProbe().home) {
250
+ export async function applyInstall(target, credentials, home = defaultProbe().home, mode = "key") {
165
251
  const spec = AGENT_SPECS[target];
166
252
  const path = spec.configPath?.(home);
167
253
  if (path === undefined || spec.merge === undefined) {
168
- return applyClaudeInstall(credentials);
254
+ return applyClaudeInstall(credentials, mode);
169
255
  }
170
- const next = spec.merge(await readIfPresent(path), credentials);
256
+ const next = spec.merge(await readIfPresent(path), credentials, mode);
171
257
  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
172
258
  await writeFile(path, next, { mode: CONFIG_MODE });
173
- // writeFile's mode only applies when it creates the file, and this one holds
174
- // the member's API key.
259
+ // writeFile's mode only applies when it creates the file, and in `key` mode
260
+ // this one holds the member's API key.
175
261
  await chmod(path, CONFIG_MODE);
176
262
  return { applied: true, detail: path };
177
263
  }
@@ -182,7 +268,7 @@ export async function applyInstall(target, credentials, home = defaultProbe().ho
182
268
  export function shellArgs(args, platform = process.platform) {
183
269
  return platform === "win32" ? args.map((arg) => `"${arg}"`) : args;
184
270
  }
185
- function applyClaudeInstall(credentials) {
271
+ function applyClaudeInstall(credentials, mode) {
186
272
  if (!onPath("claude")) {
187
273
  return { applied: false, detail: "the `claude` command is not on PATH" };
188
274
  }
@@ -203,8 +289,9 @@ function applyClaudeInstall(credentials) {
203
289
  "http",
204
290
  "talentos",
205
291
  mcpUrl(credentials),
206
- "--header",
207
- `Authorization: ${bearer(credentials)}`,
292
+ ...(mode === "oauth"
293
+ ? []
294
+ : ["--header", `Authorization: Bearer ${credentials.apiKey}`]),
208
295
  ]);
209
296
  if (added.status !== 0) {
210
297
  throw new Error(firstLine(added.stderr) || "`claude mcp add` failed");
@@ -242,14 +329,7 @@ function parseCursorConfig(existing) {
242
329
  }
243
330
  }
244
331
  function cursorEntry(credentials) {
245
- return {
246
- mcpServers: {
247
- talentos: {
248
- url: mcpUrl(credentials),
249
- headers: { Authorization: bearer(credentials) },
250
- },
251
- },
252
- };
332
+ return setupEntry(mcpUrl(credentials), credentials.apiKey);
253
333
  }
254
334
  export async function readIfPresent(path) {
255
335
  try {
@@ -267,12 +347,20 @@ export function onPath(command) {
267
347
  });
268
348
  return probe.error === undefined && probe.status === 0;
269
349
  }
270
- function mcpUrl(credentials) {
271
- return `${credentials.apiUrl}/mcp`;
350
+ /** The MCP address written into client configs for this API url. */
351
+ export function mcpUrl(credentials) {
352
+ return mcpUrlFor(credentials.apiUrl);
272
353
  }
273
- function bearer(credentials) {
274
- return `Bearer ${credentials.apiKey}`;
354
+ function clientSnippet(target, credentials, mode) {
355
+ return setupSnippet(target, mode, {
356
+ apiUrl: credentials.apiUrl,
357
+ key: credentials.apiKey,
358
+ url: mcpUrl(credentials),
359
+ });
275
360
  }
276
361
  function firstLine(text) {
277
362
  return text?.trim().split("\n")[0] ?? "";
278
363
  }
364
+ export function oauthNext(target) {
365
+ return OAUTH_NEXT[target];
366
+ }
@@ -0,0 +1,22 @@
1
+ // Standalone npm package: keep this decoder aligned with the v1 wire spec in
2
+ // docs/features/agent-access/memory-wire-format.md, without Convex imports.
3
+ export function unescapeMemoryText(text) {
4
+ return text.replace(/\\(\\|u[\da-f]{4})/giu, (_, encoded) => encoded === "\\"
5
+ ? "\\"
6
+ : String.fromCharCode(Number.parseInt(encoded.slice(1), 16)));
7
+ }
8
+ export function decodeMemoryRead(text, data) {
9
+ const open = "<teammate_message>\n";
10
+ const close = "\n</teammate_message>";
11
+ if (data.bodyEncoding !== "talentos-memory-v1" ||
12
+ !text.startsWith(open) ||
13
+ !text.endsWith(close) ||
14
+ !Number.isSafeInteger(data.bodyStart) ||
15
+ !Number.isSafeInteger(data.bodyLength) ||
16
+ data.bodyStart < open.length ||
17
+ data.bodyLength < 0 ||
18
+ data.bodyStart + data.bodyLength !== text.length - close.length) {
19
+ throw new Error("Unsupported or incomplete Memory read. Refresh memory_read.");
20
+ }
21
+ return unescapeMemoryText(text.slice(data.bodyStart, data.bodyStart + data.bodyLength));
22
+ }
package/dist/output.js ADDED
@@ -0,0 +1,107 @@
1
+ import { AsyncLocalStorage } from "node:async_hooks";
2
+ import { redactAgentOutput } from "./agent-link.js";
3
+ export class CliError extends Error {
4
+ code;
5
+ next;
6
+ details;
7
+ constructor(code, message, next, details) {
8
+ super(message);
9
+ this.code = code;
10
+ this.next = next;
11
+ this.details = details;
12
+ }
13
+ }
14
+ const output = new AsyncLocalStorage();
15
+ const AUTH_ERROR = /not logged in|key revoked|rejected that key|unauthorized|\b401\b/iu;
16
+ const ARGUMENT_ERROR = /usage:|unknown (command|option)|argument|--help/iu;
17
+ const TALENTOS_COMMAND = /^(?:talentos|npx(?: -y)? talentos(?:@\S+)?)(?:\s|$)/u;
18
+ const NETWORK_ERROR = /cannot reach|fetch failed|ECONNREFUSED|ENOTFOUND/iu;
19
+ export function cliContractEnabled() {
20
+ return process.env.HEADLESS_CLI_V1 === "true";
21
+ }
22
+ export function machineOutput() {
23
+ return output.getStore();
24
+ }
25
+ export function nextActions(next) {
26
+ const current = machineOutput();
27
+ if (current) {
28
+ current.next = next;
29
+ }
30
+ }
31
+ export function withApiUrl(command, apiUrl) {
32
+ if (!(apiUrl && TALENTOS_COMMAND.test(command)) ||
33
+ command.includes(" --api-url ")) {
34
+ return command;
35
+ }
36
+ return `${command} --api-url '${apiUrl.replaceAll("'", "'\\''")}'`;
37
+ }
38
+ function contextualNext(next, apiUrl) {
39
+ return next?.map((action) => ({
40
+ ...action,
41
+ command: withApiUrl(action.command, apiUrl),
42
+ }));
43
+ }
44
+ /** One envelope after the command settles; nested progress goes to stderr. */
45
+ export async function runJsonCommand(run, secrets) {
46
+ const result = {};
47
+ await output.run(result, async () => {
48
+ try {
49
+ await run();
50
+ if (process.exitCode) {
51
+ throw new CliError("COMMAND_FAILED", result.message ?? "The command needs attention.", result.next);
52
+ }
53
+ writeEnvelope({
54
+ ok: true,
55
+ data: result.data ?? (result.message ? { message: result.message } : null),
56
+ ...(result.next?.length
57
+ ? { next: contextualNext(result.next, result.apiUrl) }
58
+ : {}),
59
+ });
60
+ }
61
+ catch (error) {
62
+ const message = redactAgentOutput(error instanceof Error ? error.message : String(error), secrets);
63
+ const failure = error instanceof CliError ? error : classifyError(message);
64
+ writeEnvelope({
65
+ ok: false,
66
+ error: {
67
+ code: failure.code,
68
+ message,
69
+ ...(failure.details === undefined
70
+ ? {}
71
+ : { details: failure.details }),
72
+ },
73
+ ...(failure.next?.length
74
+ ? { next: contextualNext(failure.next, result.apiUrl) }
75
+ : {}),
76
+ });
77
+ process.exitCode ||= 1;
78
+ }
79
+ });
80
+ }
81
+ function classifyError(message) {
82
+ if (AUTH_ERROR.test(message)) {
83
+ return new CliError("UNAUTHENTICATED", message, [
84
+ {
85
+ command: "talentos login",
86
+ why: "Sign in with the member's current key.",
87
+ },
88
+ ]);
89
+ }
90
+ if (ARGUMENT_ERROR.test(message)) {
91
+ return new CliError("INVALID_ARGUMENT", message, [
92
+ { command: "talentos --help", why: "Check the command and its options." },
93
+ ]);
94
+ }
95
+ if (NETWORK_ERROR.test(message)) {
96
+ return new CliError("UNAVAILABLE", message, [
97
+ {
98
+ command: "talentos doctor",
99
+ why: "Check the connection before trying again.",
100
+ },
101
+ ]);
102
+ }
103
+ return new CliError("COMMAND_FAILED", message);
104
+ }
105
+ function writeEnvelope(value) {
106
+ process.stdout.write(`${JSON.stringify(value)}\n`);
107
+ }