@noimosai/platform-mcp 0.1.3 → 0.1.4

package/dist/cli/command-help.js

@@ -0,0 +1,395 @@
+import { TOOL_RESULT_PAGE_MAX_ITEMS } from "../client/index.js";
+const inputHelp = `Supply one JSON object inline, use - for stdin, or use --input-file <path>.
+File/stdin input is limited to 1 MiB. --input-file - also reads stdin.`;
+const commands = {
+    parallel: `parallel ('<request-json>' | - | --input-file <path>)
+Start independent existing catalog tools together; no session or advance quotes are required.
+Input: {"calls":[{"tool":"web_search","arguments":{"query":"public sources"},"idempotencyKey":"research-unique-key"}]}
+Each call takes run's purchase fields: tool, arguments, idempotencyKey, optional provider,
+sessionId, intent, relevanceCheck, maximumChargeMicros and externalBillingAccepted.
+Up to 50 calls, with four concurrent admissions. Returns every receipt in input order
+without waiting for completion; read each accepted executionId with result or wait.
+Exit 0 means all calls were admitted (including pending/needs_review), not that they succeeded.
+Exit 1 means some were rejected or admission is unknown. One failure does not stop the others.
+Save the request and distinct per-call keys first. Repeat identical calls and keys after a
+lost reply; never replace accepted or uncertain work. Dependencies belong in later calls.
+Optional top-level maximumChargeMicros requires explicit per-call ceilings whose sum fits.
+Omit ceilings or use null when none was requested. Connected-account and BYOK usage runs by
+default; set externalBillingAccepted:false on calls whose external charges the user asked to avoid.
+When price approval is requested, use quote and meta execute with the approved quotes instead.
+${inputHelp}`,
+    run: `run <tool> ('<arguments-json>' | - | --input-file <path>) --idempotency-key <key> [--maximum-charge-micros <integer>]
+Execute the requested work; omit the ceiling when the user did not specify a budget.
+Quotes exact inputs internally, uses the quote amount when no ceiling was supplied,
+rejects quotes above an explicit ceiling (1 USD=1000000 micros; 0=free Relvo calls), saves the exact purchase before submission,
+waits (default 25s, --wait 1-60), and returns a bounded result plus its retained execution ID.
+Optional: --provider <id> --session <id> --path '<path-array>' --fields '<field-names>' --find '<terms>'
+          --pick '<label-to-paths-json>' --limit <n> --offset <n> --max-chars <n> --file.
+--find keeps the lines of a text that hold a term: one term, or a JSON list of terms.
+Connected-account and BYOK usage runs by default (--accept-external-billing says so explicitly);
+--decline-external-billing stops before submitting when the user asked to avoid that account's or key's charges or quota use.
+For pagination, keep the exact tool, actual serving provider, account and search filters.
+Copy returned cursors unchanged; use the actual serving provider for later pages when it is pinnable.
+A provider's internal source/lane is separate from --provider. Inspect its own continuation contract.
+Follow this operation's documented cursor, page or offset method; a bounded page does not establish complete history.
+The ceiling covers Relvo charges only, not the connected account's or key's own charges.
+--file writes the selected path to a local file instead of printing it, as result --file does.
+Use the same request/key after uncertainty. Source data remain stored; missing fields are explicit.
+Do not ask for or invent a budget. Honor explicit limits across calls and pages.
+When the user requests price approval, use quote and execute instead.`,
+    resume: `resume <run-id> [--wait <1-60 seconds>] [--find '<terms>'] [--pick '<label-to-paths-json>']
+Recover the saved purchase in this credential scope with its original body and key.
+You may change result selection, never the purchase. A missing journal requires checking
+project execution history rather than creating replacement work.`,
+    meta: `meta <search|schemas|connections|execute|workbench|bash> '<request-json>'
+Use session-scoped Relvo meta tools. Search returns session.id; retain it for other calls.
+Supply the matching schema's JSON object inline, from stdin (-) or --input-file <path>, up to 1 MiB.
+Execute batches require each accepted quote/idempotency key and a total reservation cap.
+Workbench/Bash require a quote for remote_workbench/remote_bash with the same session and arguments.
+Accepted work is asynchronous: wait for its execution ID. Unknown admission retains the same request/key.`,
+    setup: `setup --api-url <url> --console-url <origin> [--client auto|claude|codex|terminal] [--mcp-runtime registry|installed] [--local] [--no-browser] [--new-project]
+Sign in in your browser and compare the printed code before approving a project.
+Stores the login in a private Relvo profile. The default, auto, configures every
+installed agent (Claude Code and Codex) with one approval and signs in the CLI when
+neither is installed. Agent setup registers MCP through the official agent CLI and
+installs current first-party guides. Restart the agent afterwards.
+Use --mcp-runtime installed for a CLI tarball installed at a persistent path. It registers
+the same package's MCP directly with Node, without npx or automatic MCP updates.
+Keep that installation and Node path available. Existing foreign MCP entries and edited guide files are preserved. No paid work is run.
+Use project add, or --new-project, for a fresh browser approval while keeping previously approved projects.`,
+    login: `login --api-url <url> --console-url <origin> [--client auto|claude|codex|terminal] [--local] [--no-browser]
+Alias for setup. An incomplete saved request resumes without creating another key.`,
+    wallet: `wallet sign-in [--api-url <url>] [--local] [--key-file <path>]
+wallet top-up --amount <usd> --max <usd> [--key-file <path>]
+Sign in or add funds with an EVM wallet, with no browser step. The private key
+(0x + 64 hex) comes only from RELVO_WALLET_PRIVATE_KEY or an owner-only --key-file;
+it is never a command argument and never printed or sent.
+sign-in creates the wallet's project on first use and saves a 30-day login like setup.
+top-up pays --amount USD in USDC (Base) by x402 and refuses any requirement above --max.
+After an unclear failure, check relvo usage before paying again.`,
+    doctor: `doctor
+Check the private local profile, approved project, live catalog and owned MCP.
+Does not update guides, submit paid tools or repair another program's configuration.`,
+    logout: `logout
+Remove the private local Relvo login. Revoke its key in the Relvo console to disable
+server access. Installed guides and MCP registration remain without a local login.`,
+    "custom-tools": `custom-tools list | get <name> | versions <name> | delete <name>
+custom-tools create <slug> (- | --input-file <path>)
+custom-tools update <name> --expected-version <n> (- | --input-file <path>)
+custom-tools restore <name> --version <n> --expected-version <n>
+Add a tool for the whole team, listed as custom__<slug>. The definition is JSON, either Python
+{ title, description, inputSchema, code } that Relvo runs in its sandbox with the validated input as the dict \`input\`,
+or an API endpoint { kind: "http", title, description, baseUrl, headers?, query?, bindings?, timeoutMs?, responseMiB? }: Relvo adds the fixed, non-secret headers and query
+and the credential bindings to every request; a public API needs no bindings. timeoutMs (5000 to 300000) and responseMiB (1 to 14) raise a call's limits; a tool past 5000 or 1 is metered from the balance.
+A definition can hold a credential, so it is read from stdin or a file and never from an argument; a saved team secret is bound in the console.
+update replaces the whole definition: read it first and pass its version; an edit made since is refused. restore adds the old version as a new one, so it can be undone.
+Run a custom tool like any other: relvo run custom__<slug> '<arguments-json>' --idempotency-key <key>.
+
+Example: relvo custom-tools create weekly_sum --input-file ./weekly_sum.json`,
+    "team-skills": `team-skills sync [--client all|<agent>[,<agent>…]] [--project <id>] [--allow-scripts]
+team-skills check [--client <agents>]
+team-skills apply|dismiss <snapshot> --yes [--client <agents>] [--allow-scripts | --remove-executable-settings]
+team-skills auto-sync on|off|status
+team-skills push <SKILL.md, folder, AGENTS.md, CLAUDE.md, agent or rule file> [--kind skill|instructions|agent|rule] [--slug <slug>]
+team-skills list | get <slug> | versions <slug> | restore <slug> --version <n> --expected-version <n> | delete <slug>
+list, get, versions, restore and delete use the API key or saved login directly; restore adds the old version as a new one, so it can be undone.
+sync writes for each agent: claude (Claude Code), codex, pi, dsh (deepseek-harness), opencode, gemini (Gemini CLI), kimi (Kimi Code),
+qwen (Qwen Code), cursor, copilot (GitHub Copilot CLI), amp and droid (Factory Droid). --client all, the default, means Claude Code and
+Codex as setup registered them (both if it registered neither), every other agent whose folder exists here, and your own agents;
+a comma list names them. Your own agent is one that reads like a listed one from a folder of its own, set in ~/.config/relvo/harnesses.json
+as {"harnesses": [{"name": "my-agent", "like": "claude", "dir": "~/.my-agent"}]} (the folder inside your home, used by no other agent);
+it takes what the team writes for the agent it reads like, and an agent like Codex gets MCP servers through codex with that folder as CODEX_HOME.
+An item the team wrote for some agents only goes only to them: a skill to each one's own skill folder (reported as ownSkills;
+Codex has none and reads ~/.agents/skills), and a rule for deepseek-harness, Kimi Code or Droid to its own AGENTS.md, not ~/.agents/AGENTS.md.
+It writes every team skill this login may see to ~/.claude/skills for Claude Code and to ~/.agents/skills, which every other agent reads,
+as relvo-team-<slug>/SKILL.md, updates the ones changed in Relvo and removes the ones it may no longer see. A folder it did not write, or one
+edited since, is never overwritten or removed and is reported as kept. A teammate's script is written without its executable
+bit and listed as scriptsNotExecutable, and a skill's hooks, allowed-tools, allowedTools and mcpServers frontmatter and its mcp.json
+(which Claude Code, Qwen Code and Amp run or pre-approve) are left out and listed as settingsWithheld;
+read them first, and pass --allow-scripts only when you trust who can edit the team's skills.
+The rest of the team's harness is written the same way, in each agent's own files and format, and reported under harness;
+a kind an agent has no place for is listed as notSupported with the reason.
+Agents: ~/.claude/agents/relvo-team-<slug>.md (without hooks, mcpServers and permissionMode unless --allow-scripts),
+~/.codex/agents/relvo-team-<slug>.toml, and the agent folders of OpenCode, Gemini CLI, Kimi Code, Qwen Code, Copilot, Cursor and Droid
+with only their name, description and the agent's own settings: a frontmatter map named after the agent, which Claude Code's copy leaves
+out, with the keys that only describe or limit the agent (codex: model, model_reasoning_effort, model_reasoning_summary, model_verbosity,
+personality, service_tier; opencode: model, variant, steps, hidden, color; gemini: model, display_name, temperature, max_turns, timeout_mins;
+kimi: whenToUse; qwen: model, maxTurns, background; copilot: model, disable-model-invocation, user-invocable; cursor: model, readonly,
+is_background; droid: model, reasoningEffort), each a line of text, a number (steps, max_turns, timeout_mins and maxTurns above 0) or
+true/false; other keys and values of another type are left out. An agent whose Claude Code tools list another agent's file cannot hold is
+listed as toolsNotKept. Pi, deepseek-harness and Amp have no agent files.
+Rules: ~/.claude/rules and ~/.qwen/rules as relvo-team-<slug>.md, and one marked block of the single instruction file of each other
+agent (~/.codex/AGENTS.md, ~/.pi/agent/AGENTS.md, ~/.config/opencode/AGENTS.md, ~/.gemini/GEMINI.md, ~/.copilot/copilot-instructions.md,
+~/.config/amp/AGENTS.md, and ~/.agents/AGENTS.md for deepseek-harness, Kimi Code and Droid); the rest of each file is never changed, and a
+file the agent would read instead, or would stop reading, is kept and reported. Cursor keeps user rules only in its settings.
+A rule's @ references to files (@path) are written as ＠ for the agents that would put the named file's contents into the model's
+context (Claude Code outside the code its Markdown parser skips; Gemini CLI, Copilot, Amp and ~/.agents/AGENTS.md everywhere) and listed
+as importsEscaped; an @ inside a word, as in an email address, stays. Pushing Claude Code's copy back sends them as @ again.
+Shared folders go to ~/.config/relvo/team/relvo-team-<slug>/ only (never a path the team chooses), with their description as README.md.
+Permission rules join yours in ~/.claude/settings.json and ~/.qwen/settings.json; their Bash rules also become ~/.codex/rules/relvo-team.rules,
+~/.gemini/policies/relvo-team.toml, shell rules of OpenCode's opencode.json (allow and ask before yours, so your own rules decide over them,
+deny after), prefix rules in ~/.factory/settings.json, and Shell(<command>) rules in ~/.cursor/cli-config.json for one-word commands once
+the Cursor CLI has written that file (other rules are listed as permissionsSkipped); a rule you already had is never taken out.
+The team's hooks, MCP servers and allow rules are installed only with --allow-scripts. Hooks: files under <agent folder>/relvo-team-hooks
+(a command's \${RELVO_HOOK_DIR} becomes that folder and \${RELVO_AGENT} the agent's name above), with their events added beside your own
+to ~/.claude/settings.json, ~/.codex/hooks.json, ~/.qwen/settings.json, ~/.gemini/settings.json and Droid's ~/.factory/settings.json
+(~/.factory/hooks.json once it exists), each under the agent's own event and tool names, and as ~/.copilot/hooks/relvo-team.json.
+Pi, OpenCode and Amp run hooks only as code: a hook's files under native/pi/, native/opencode/ or native/amp/ become a plugin folder
+relvo-team-<slug> in ~/.pi/agent/extensions, ~/.config/opencode/plugins or ~/.config/amp/plugins, and a hook without them is listed
+as hooksWithoutPlugin. Cursor runs Claude Code's hooks itself.
+MCP servers as relvo-team-<slug>: Claude Code's user scope (claude mcp add-json), codex mcp add, entries beside yours in the MCP configuration of Pi,
+OpenCode, Gemini CLI, Kimi Code, Qwen Code, Cursor, Copilot, Amp and Droid (a bearer token stays an environment variable in each agent's
+own syntax), and a marked block of ~/.dsh/cordis.patch.yml. Without --allow-scripts they are listed as notInstalled and any installed
+earlier are taken out. Codex runs a new or changed hook only after you trust it in /hooks.
+A JSON configuration with comments is left unchanged and reported, since sync would lose them.
+--project uses that project's already approved credential for this sync without changing the default; approve a new project with project add first.
+check reads metadata only and prints additions, updates/removals, clients and a snapshot. apply requires explicit --yes approval of that
+snapshot and the same --client selection; project/version/target changes require a new check and approval. Executable settings need
+separate --allow-scripts consent. If the target already has executable settings, apply without that separate consent refuses to change them;
+--remove-executable-settings separately approves removing that opt-in. In MCP use removeExecutableSettings:true; never combine it with
+allowScripts:true. An explicit sync without --allow-scripts still removes that opt-in as described above.
+Managed local MCP starts a metadata check on the first successful tool reply and every 60 seconds while running, without delaying that reply, with a
+one-time prompt in the next successful reply for each changed snapshot. It never imports automatically. Use platform_project_sync to
+check/apply/dismiss or enable/disable checks. auto-sync configures this notification mode; RELVO_PROJECT_AUTO_SYNC=0 disables checks for
+that process. There is no idle popup or background OS service. Receipts are private in ~/.config/relvo/project-sync.json and per client;
+kept edits/withheld settings are reported as such. Reload the agent's skills/settings after import.
+push shares a local SKILL.md and every file beside it with the team, and lists the files it sent; a credential file is refused:
+the frontmatter description says when to use it, the first # heading is its title and the rest its steps. A file in an agents
+or rules folder is pushed as an agent or rule (--kind chooses otherwise); its name, frontmatter description and # heading work the same way.
+Push Claude Code's copy of a synced agent or rule; another agent's copy holds only part of it and is refused.
+A synced copy updates its item (refused if it changed in Relvo since); any other file creates a new one and never
+replaces one. The member's and the key's access decide what each may read, create and change, as in the console;
+only project administrators write hooks, MCP servers, permissions, skills or agents whose frontmatter holds hooks,
+allowed-tools, allowedTools, mcpServers or permissionMode, and skills with an mcp.json, and only in the console: pushing one is refused,
+whoever's key it is.
+Pushing needs a key with tools:execute; text that looks like a credential is refused.
+
+Example: relvo team-skills push ./skills/weekly-report
+Example: relvo team-skills push ~/.claude/agents/pricing-analyst.md`,
+    skills: `skills list | skills update [--client claude|codex|all]
+Read current first-party guide summaries, or explicitly install/update verified Markdown.
+Updates preserve foreign folders and user-edited guides. Endpoint discovery remains live.`,
+    update: `update [status|auto on|auto off|pin <version>|rollback]
+Check and prepare a compatible stable CLI/MCP release for the next process start.
+status reads the current policy and prepared versions. auto on enables daily checks;
+In the packaged CLI, normal commands keep their selected version while a separate updater
+checks automatically. It receives no command arguments and never replays user work.
+auto off stops automatic installs and cancels automatically staged releases; a newer release
+is still announced once a day. pin selects an exact stable version.
+rollback selects the previous verified version and disables automatic updates.
+Updates preserve the saved login, permissions and client configuration. A running MCP
+session moves to the selected version between tool calls. RELVO_AUTO_UPDATE=0 disables updates and their announcements for a process.
+This command is provided by the public @relvo/cli package launcher.`,
+    upload: `upload <file>
+Upload one explicitly chosen local JPG/PNG/WebP/WAV/MP3/MP4/MOV, at most 12 MiB, to this project.
+Requires tools:execute. No generation charge. Returns a file ID valid for up to 30 days.
+Use {"source":{"fileId":"..."}} with an understanding or transcription tool.
+Repeating identical bytes reuses the same project file; it does not extend its expiry.
+File bytes and local paths are not included in command output.`,
+    project: `project
+project status [--member-offset <integer>] [--invitation-offset <integer>] [--limit <1-100>]
+status reads your selected project's roles, permission summary and key scopes.
+Only project admins receive paged project members and pending invitations; a team admin role alone is insufficient.
+project list
+project add [--project <project-id>] [--no-browser]
+project use <project-id>
+Read the team and project bound to the API key. Free.
+list shows only this installation's already approved projects, never credentials or unapproved projects.
+add opens a fresh browser approval with --project selected, or else the project last open in that browser: check it there before approving.
+Rerun add after an interruption.
+use verifies live access and retires the old project's managed files before changing the default. Edited old files are archived under
+~/.config/relvo/project-archives; personal files and the target project's files are preserved. Reconnect MCP and start a fresh agent
+session so old instructions do not remain in context. Approve the target files through platform_project_sync or team-skills sync;
+a running default MCP pauses API requests after a switch. Accepted work stays in its original project.
+Tool commands accept --project <id> for one command without changing the default, for example:
+  relvo tools --query search --project <project-id>
+Run team-skills sync [--project <id>] to update managed project files. Edited files are preserved;
+executable files still require --allow-scripts. use does not install files or broaden any key's scope.
+An MCP launched with mcp --profile <managed-path> --project <id> stays explicitly pinned to that approval.`,
+    team: `team [--member-offset <integer>] [--invitation-offset <integer>] [--limit <1-100>]
+Read the selected team/project, your roles and approved key scopes with the normal project:read grant.
+Team owners/admins also receive paged member and pending team invitation summaries; follow each nextOffset.
+Other members receive only their own context. This command changes no permissions and never needs access:write. Free.`,
+    usage: `usage
+Read this project's monthly requests and spend. amountCents is USD cents. Free.`,
+    connections: `connections [--provider <id>] [--offset <integer>] [--limit <1-20>]
+Read a page of OAuth connections belonging to this developer project. Requires tools:read.
+Default 10 rows; follow nextOffset with --offset. --provider filters before paging.
+Returns IDs, labels, connected/reauth_required states and observed scopes without tokens.
+Use an ID only in a selected tool's documented connectionId field. Scopes do not establish
+every operation's permission; reauth_required lists the reconnectUrl that reconnects it in the Relvo console. Free.`,
+    connect: `connect <app>
+Print the console pages where a person connects the named app or adds an account. Requires tools:read.
+sign_in: open url, check the account and requested permissions, and authorize.
+credentials: open url and enter the key on Relvo's page. This command takes no key, token or password.
+Run it again afterwards; status shows the result. Free.`,
+    tools: `tools [--query <text>] [--app <name-or-id>] [--category <all|research|seo|social|enrichment|generation|finance|news>]
+                      [--provider <id>] [--available-only | --include-unavailable]
+                      [--max-charge-micros <integer>] [--quote-arguments '<json>']
+                      [--funding all|relvo|provider|mixed] [--price-unit <unit>] [--sort-by relevance|price_asc]
+                      [--include '<filter-json>'] [--exclude '<filter-json>']
+                      [--limit <1-12>] [--mode auto|keyword|semantic] [--summary | --with-schemas]
+Search capabilities, tool/model names and descriptions; return up to 12 summaries (default 8).
+--app scopes discovery to an indexed connected app, e.g. --app "Google Drive".
+Unknown or ambiguous apps return explicitly unscoped results; inspect the warning.
+Empty/omitted means unscoped. This filter does not select an execution account.
+--provider filters this list; it does not select a provider for executions.
+--max-charge-micros filters per-call quotes, not unit prices (1 USD=1000000 micros; 0=free).
+Unquotable and externally billed candidates are excluded by a cost cap. Without
+--quote-arguments, quotes use catalog examples. Requote actual arguments before executing.
+--price-unit matches an exact catalog unit. price_asc puts unknown costs last.
+--include/--exclude accept {"tools":[],"providers":[],"categories":[]} with exact IDs.
+OR within a list, AND across include lists; any exclusion wins. Empty/null is neutral.
+Excluding a provider removes any tool listing it; it does not pin a later execution.
+Schemas/examples are omitted by default. For a precise capability, --limit 1 --with-schemas
+can include its definition in the search. Reuse complete schemas; use tool <name> only
+for omitted definitions or missing constraints.
+available=true does not override executionEnabled=false or key/budget limits.
+
+Example: relvo tools --query search --available-only --summary`,
+    tool: `tool <name>
+Inspect one tool's full input schema, example, availability and USD price. Free.
+
+Example: relvo tool web_search`,
+    executions: `executions [--limit <1-100>] [--before <id>] [--status <state>] [--tool <name>]
+Read project history, newest first. Use nextBefore as --before for the next page.
+States: queued, running, waiting, succeeded, failed, cancelled, needs_review. Free.
+
+Example: relvo executions --status failed --limit 20`,
+    monitors: `monitors destination-add <id> --destination '<json>' | destination-remove <id> --destination-id <dst_id>
+          monitors list | popular | tools | delete <id> | resume <id> [--maximum-charge-micros-per-run <n>]
+          monitors quote --tool <name> [--args '<json>'] [--provider <id>] [--interval 15m|1h|1d | --cron "<m h dom mon dow>" [--time-zone <IANA>]]
+          monitors create --tool <name> [--args '<json>'] [--provider <id>] [--interval 15m|1h|1d | --cron "<m h dom mon dow>" [--time-zone <IANA>]] [--name <text>]
+                          [--maximum-charge-micros-per-run <n>]
+          monitors events [--monitor <id>] [--after <cursor>] [--limit <1-100>]
+Watch a tool for changes. Relvo re-runs it on a schedule and diffs against the previous result. The
+schedule is --interval (default 1h) or a 5-field --cron such as "0 9 * * 1-5" (weekdays 9:00) read in
+--time-zone (default UTC, e.g. Asia/Tokyo), at least 15 minutes between runs; not both. Projects with
+the same tool, arguments, provider and schedule share one run. tools lists what can
+be monitored, the provider to pin and chargeCeilingMicros (0 = free). Every project watching a
+target pays the full price of each run, the same as running the tool once; they only share the
+fetch. quote shows that price and how many projects watch it. Creating a monitor needs
+--maximum-charge-micros-per-run of at least the ceiling, and charges every run from the balance
+until deleted. A monitor that cannot pay a run is suspended; resume continues it from now. The first run is a baseline with no events. Lists report
+new items (added); single results report changed fields. events reads oldest first; pass nextAfter
+as --after to read only newer events, omit --monitor for every monitor. popular shows monitors that
+at least 3 teams already watch. destination-add also sends a monitor's changes to
+{kind:"webhook",url} (signing secret shown once), {kind:"slack",url} or {kind:"discord",url}, each with a label;
+email is console only. list shows each destination's dst_ id for destination-remove.
+
+Example: relvo monitors quote --tool web_search --provider brave --args '{"query":"relvo"}'`,
+    triggers: `triggers list | types --app <app> [--connection <id>] [--query <text>] [--offset <n>] [--limit <1-100>] | delete <id> | update <id> [--enabled true|false] [--name <text>]
+          triggers create --connection <id> --tool <name> [--args '<json>'] [--interval 1m|5m|15m|1h] [--items-path </json/pointer>]
+                          [--maximum-charge-micros-per-poll <n>] [--name <text>] [--destinations '<json array>']
+          triggers create --connection <id> --type <app.event> [--config '<json>'] [--name <text>] [--destinations '<json array>']
+          triggers events [--trigger <id>] [--after <cursor>] [--limit <1-100>]
+          triggers destination-add <id> --destination '<json>' | destination-remove <id> --destination-id <dst_id>
+Get events from a connected app. The trigger runs as the API key that creates it. A poll trigger
+(--tool) runs a read operation of the app every --interval (default 5m) and reports what is new;
+the first run is a baseline with no events. Each poll is one execution: it counts toward the plan's
+free runs and is charged beyond them, up to --maximum-charge-micros-per-poll. A webhook trigger
+(--type) registers with the app and receives its events at once; --config must match the type's
+configSchema. types --app lists an app's webhook types and a page of its read operations; with
+--connection, only the ones this key may watch on that connection. Destinations
+are a JSON array of {kind:"webhook",url} (signing secret shown once), {kind:"slack"}, {kind:"discord"}
+or {kind:"workflow",workflow,input,maximumChargeMicros}; email is console only. events reads oldest
+first; pass nextAfter as --after to read only newer events, omit --trigger for every trigger.
+update --enabled false pauses a trigger; true resumes it and checks a failed one again. destination-add and
+destination-remove change where an existing trigger's events go; list shows each destination's dst_ id.
+
+Example: relvo triggers types --app github`,
+    access: `access list | access set <member-id> (--tools '<json array>' | --all)
+Legacy NoimosAI Platform only. Relvo shares resources through project membership; use project settings
+to assign Administrator or User. Relvo does not support individual member-policy keys.
+Read and change what each team member may use of the team's own connections, custom tools, skills and
+secrets. list shows every member and pending invitation; toolAccess null is everything, a list names
+connection:<id>, connection:<id>/<tool>, connection:<id>/reads, custom__<slug>, skill:<project-id>/<slug>
+and secret:<project-id>/<NAME>; what it does not name is hidden from them. set replaces one member's whole list
+(--all gives everything, those added later included); read it with list first. Needs a key of the
+team's owner or an admin made in the console with access:write; such a key runs no tool. An admin
+changes no admin's or owner's list and gives nothing they or the key do not hold; roles are never
+changed here.
+
+Example: relvo access set 6f1c… --tools '["connection:c-1/reads"]'`,
+    quote: `quote <tool> '<arguments-json>' [--provider <id>] [--session <id>] [--relevance-check auto|light]
+                      [--maximum-charge-micros <cap>]
+Get a free quote without starting paid work. Returns priceVersion and maximumChargeMicros.
+Auto routing is the default; --provider auto also selects Auto.
+Other --provider values pin one provider; repeat the selection on execute.
+An Auto research tool accepts only the providers it lists, runs just that one when pinned,
+and is billed at the recorded cost of the call. --relevance-check light keeps the rows
+its first relevance classifier cannot decide instead of running the full check.
+With a cap, an Auto quote above it returns the best plan within it as plan;
+pass plan's provider and relevanceCheck to execute unchanged.
+${inputHelp}
+
+Examples:
+  relvo quote web_search '{"query":"content marketing trends"}'
+  relvo quote web_search --input-file brief.json`,
+    execute: `execute <tool> '<arguments-json>' --maximum-charge-micros <integer>
+                        --price-version <version> --idempotency-key <key> [--provider <id>] [--session <id>]
+                        [--relevance-check auto|light] [--raw]
+Enqueue paid work using an accepted quote. All three confirmation flags are required.
+Auto routing is the default. Retain the same provider and relevance check used for the quote.
+1 USD = 1000000 micros. Retain the same body and key when retrying a submission.
+Keys: 8-128 letters, digits, periods, underscores, colons or hyphens.
+${inputHelp}
+Returns an execution ID. Read it with execution <id> or wait <id>; acceptance is not completion.
+Large replay receipts reference the retained result; --raw explicitly returns the full receipt.
+
+Example (use the values from your quote and a saved key):
+  relvo execute web_search --input-file brief.json \\
+    --maximum-charge-micros "$RELVO_QUOTED_MAXIMUM_MICROS" \\
+    --price-version "$RELVO_QUOTED_PRICE_VERSION" --idempotency-key "$RELVO_REQUEST_UUID"`,
+    execution: `execution <id> [--raw]
+Read status, a bounded output preview and chargedMicros (1 USD = 1000000 micros). Free.
+The full output stays retained. Use result <id> to read selected data, or --raw for full JSON.
+A pending zero charge is not a free completion. For needs_review, contact support;
+do not automatically submit a replacement.`,
+    results: `results <id>... [--path '<JSON-array>'] [--fields '<JSON-array>'] [--offset <integer>] [--limit <1-${TOOL_RESULT_PAGE_MAX_ITEMS}>] [--max-chars <n>]
+                        [--find '<terms>'] [--pick '<label-to-paths-json>'] [--wait <1-60 seconds>]
+Read the same selection of several retained outputs at once, such as every ID parallel returned. Free.
+Each ID answers for itself in results, in the order asked; one that cannot be read carries its error.
+A text page holds 8,000 characters by default and at most 20,000 with --max-chars.
+--find keeps the lines of a text that hold a term: one term, or a JSON list of terms.
+What is still pending shares one wait (default 25 seconds).
+Exit 0 means every one succeeded with data, 3 that some are still pending, and 1 otherwise.`,
+    result: `result <id> [--path '<JSON-array>'] [--fields '<JSON-array>'] [--offset <integer>] [--limit <1-${TOOL_RESULT_PAGE_MAX_ITEMS}>] [--max-chars <1-8000>]
+                       [--find '<terms>'] [--pick '<label-to-paths-json>'] [--wait <1-60 seconds>] [--file]
+Read a page of the retained full output without repeating the paid execution. Free.
+Without --wait, unfinished work answers at once with exit 3.
+--find, --pick and --wait read as run does, with the reply {id, status, result}, and --max-chars goes up to 20,000.
+--find keeps the lines of a text that hold a term: one term, or a JSON list of terms. findNotApplied means the path holds no single text.
+Check status and chargedMicros: partial:true is incomplete saved output from a failed/cancelled task.
+upstreamRefusal means the connected app refused the request: the output holds that refusal, not data.
+Exit 1 preserves failed/cancelled/needs_review and an app's refusal, and exit 3 means still pending. --file also exports partial rows.
+Use a JSON array of path segments, including string array indexes; default path is [].
+Default offset: 0, item limit: 20, string limit: 4000 characters. Follow nextOffset.
+The page includes a bounded preview and a reference when the selected value is large.
+
+Pages shrink to fit the response budget; follow nextOffset. --fields keeps named keys from an object or each array row without changing stored data. Object offsets page the selected keys.
+--file writes the whole path instead (fields applied, "a.b" keeps a nested key) to ./.relvo/results
+as JSON Lines for an array, one row per line, and prints its path; git ignores that directory.
+RELVO_RESULT_DIRECTORY selects another directory. Use jq, grep or a file reader on it.
+Example: relvo result job_123 --path '["items"]' --fields '["id","title"]' --limit 100
+Example: relvo result job_123 --path '["items"]' --fields '["title","metrics.likes"]' --file`,
+    wait: `wait <id> [--timeout <seconds>] [--raw]
+Wait for completion, polling every 5 seconds. Default timeout: 480 seconds; range: 1-900.
+Returns a bounded preview by default; use result for selected data or --raw for full JSON.
+Exits 0 on success, 1 on failed/cancelled/needs_review or request error, 3 on timeout.
+A timeout leaves accepted work running. Continue with the same ID. Free.`,
+    cancel: `cancel <id> [--raw]
+Request cancellation of unstarted work. Already incurred provider costs may be charged.
+Large receipts reference retained output; --raw explicitly returns the full receipt.
+Requires execution ownership or project ADMIN access.`,
+    "artifact-url": `artifact-url <execution-id> <artifact-id>
+Get a private output's temporary download URL, valid for up to 5 minutes.
+Treat it as private access; never send the developer API key to the storage host.`,
+    download: `download <execution-id> <artifact-id> --out <file>
+Save a private artifact after verifying size and SHA-256. Never overwrite an existing file.
+The developer API key is sent only to the Relvo API, not the storage host.`,
+};
+export const commandHelpNames = Object.keys(commands);
+export function commandHelp(name) {
+    return Object.hasOwn(commands, name) ? `Usage: relvo ${commands[name]}\n` : undefined;
+}

package/dist/cli/download.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { link, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { outputArtifacts } from "../client/agent-run.js";
+const STALL_MS = 60_000;
+export async function downloadArtifact(client, id, artifactId, filename, transport = fetch) {
+    const execution = (await client.execution(id)).data;
+    if (["queued", "running", "waiting"].includes(execution.status))
+        throw new Error(`This execution is still ${execution.status}. Wait for it with relvo wait ${id}, then download.`);
+    const artifact = outputArtifacts(execution.output).find((entry) => entry.id === artifactId);
+    if (!artifact)
+        throw new Error("Artifact is not present in this execution. Inspect execution output for available artifact IDs.");
+    const { data } = await client.artifactDownload(id, artifactId);
+    const url = new URL(data.url);
+    if (url.hostname !== "storage.googleapis.com" && !url.hostname.endsWith(".storage.googleapis.com"))
+        throw new Error("Unsupported artifact download host.");
+    const stalled = new AbortController();
+    let watchdog = setTimeout(() => stalled.abort(), STALL_MS);
+    const progressed = () => { clearTimeout(watchdog); watchdog = setTimeout(() => stalled.abort(), STALL_MS); };
+    const response = await transport(url, { method: "GET", redirect: "error", signal: stalled.signal }).catch(() => {
+        clearTimeout(watchdog);
+        throw new Error("Artifact download failed. Retrieve a fresh URL and try again.");
+    });
+    if (!response.ok || !response.body) {
+        clearTimeout(watchdog);
+        throw new Error("Artifact download failed. Retrieve a fresh URL and try again.");
+    }
+    const reader = response.body.getReader(), chunks = [];
+    let bytes = 0, oversized = false;
+    try {
+        for (;;) {
+            progressed();
+            const part = await reader.read();
+            if (part.done)
+                break;
+            bytes += part.value.byteLength;
+            if (bytes > artifact.sizeBytes) {
+                oversized = true;
+                await reader.cancel();
+                break;
+            }
+            chunks.push(part.value);
+        }
+    }
+    catch {
+        throw new Error("Artifact download failed. Retrieve a fresh URL and try again.");
+    }
+    finally {
+        clearTimeout(watchdog);
+        reader.releaseLock();
+    }
+    if (oversized)
+        throw new Error("Artifact exceeded its recorded size; no file was saved.");
+    const buffer = Buffer.concat(chunks);
+    if (bytes !== artifact.sizeBytes || createHash("sha256").update(buffer).digest("hex") !== artifact.sha256)
+        throw new Error("Artifact integrity check failed; no file was saved.");
+    const path = resolve(filename);
+    const temporary = await mkdtemp(join(dirname(path), ".noimos-platform-")).catch((error) => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            throw new Error(`The folder for --out does not exist: ${dirname(path)}. No file was saved.`);
+        throw error;
+    });
+    try {
+        const staged = join(temporary, "artifact");
+        await writeFile(staged, buffer, { flag: "wx", mode: 0o600 });
+        await link(staged, path);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+    return { id, artifactId, path, sizeBytes: bytes, sha256: artifact.sha256 };
+}

package/dist/cli/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+process.exitCode = await runCli(process.argv.slice(2), process.env, console.log, console.error);

package/dist/cli/input-error.js

@@ -0,0 +1,48 @@
+export class CliInputError extends Error {
+}
+export function jsonOption(name, text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new CliInputError(`Invalid JSON in ${name}`);
+    }
+}
+export function isCliInputFailure(error) {
+    return error instanceof CliInputError || error instanceof Error && "code" in error && typeof error.code === "string" && error.code.startsWith("ERR_PARSE_ARGS_");
+}
+export function cliInputReason(error) {
+    if (error instanceof CliInputError)
+        return error.message;
+    if (error instanceof SyntaxError)
+        return "Invalid JSON";
+    if (error instanceof Error && error.name === "ZodError" && "issues" in error && Array.isArray(error.issues)) {
+        const issues = error.issues;
+        const fields = new Map();
+        for (const issue of issues) {
+            if (!issue || typeof issue !== "object" || !("path" in issue) || !Array.isArray(issue.path))
+                continue;
+            const path = issue.path;
+            if (!path.every(part => typeof part === "string" || typeof part === "number"))
+                continue;
+            const name = path.join(".") || "input";
+            const expected = "code" in issue && issue.code === "invalid_type" && "expected" in issue && typeof issue.expected === "string" ? issue.expected : undefined;
+            const constraint = expected ? ` (expected ${expected})` : "maximum" in issue && typeof issue.maximum === "number" ? ` (max ${issue.maximum})`
+                : "minimum" in issue && typeof issue.minimum === "number" ? ` (min ${issue.minimum})` : "";
+            if (!fields.has(name) || expected)
+                fields.set(name, `${name}${constraint}`);
+        }
+        return `Invalid input fields: ${[...fields.values()].slice(0, 4).join(", ") || "input"}`;
+    }
+    if (error instanceof Error && "code" in error && typeof error.code === "string") {
+        if (error.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+            const name = /^Unknown option '(--[a-z-]{1,40})'/.exec(error.message)?.[1];
+            return name ? `Unknown command option ${name}` : "Unknown command option";
+        }
+        if (error.code.startsWith("ERR_PARSE_ARGS_"))
+            return "Invalid command option or value";
+        if (["ENOENT", "EACCES", "EISDIR"].includes(error.code))
+            return "The input file could not be read";
+    }
+    return "Invalid command, JSON arguments or input file";
+}