@sandbaseai/cli 0.1.14 → 0.3.6

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.
@@ -0,0 +1,79 @@
1
+ export declare const DEFAULT_MCP_URL = "https://api.sandbase.ai/v1/mcp";
2
+ export declare const UNREACHABLE_HINT = "Check this machine's network, proxy, or VPN, then run `sandbase doctor` and retry.";
3
+ export type ErrorCode = "AUTH_REQUIRED" | "AUTH_FAILED" | "INSUFFICIENT_BALANCE" | "SPENDING_LIMIT" | "FORBIDDEN" | "NOT_FOUND" | "RATE_LIMITED" | "INVALID_INPUT" | "NETWORK" | "UPSTREAM" | "RUN_FAILED" | "INVALID_RESPONSE" | "TOOL_ERROR" | "USAGE";
4
+ export declare class SandBaseError extends Error {
5
+ readonly code: ErrorCode;
6
+ readonly hint?: string | undefined;
7
+ readonly status?: number | undefined;
8
+ readonly runId?: string | undefined;
9
+ constructor(code: ErrorCode, message: string, hint?: string | undefined, status?: number | undefined, runId?: string | undefined);
10
+ }
11
+ export declare function webUrl(env?: NodeJS.ProcessEnv): string;
12
+ export declare function billingUrl(env?: NodeJS.ProcessEnv): string;
13
+ export declare function keysUrl(env?: NodeJS.ProcessEnv): string;
14
+ export declare const CONNECT_COMMAND = "npx -y @sandbaseai/cli@latest connect";
15
+ export declare function spendingLimitHint(env?: NodeJS.ProcessEnv): string;
16
+ export declare function validMcpUrl(value: unknown): string | undefined;
17
+ export interface Endpoint {
18
+ credential: string;
19
+ url: string;
20
+ source: string;
21
+ }
22
+ export interface StoredKey {
23
+ key: string;
24
+ mcpUrl?: string;
25
+ addedAt: string;
26
+ }
27
+ export declare function keyFilePath(env?: NodeJS.ProcessEnv): string;
28
+ export declare function readStoredKey(env?: NodeJS.ProcessEnv): Promise<StoredKey | undefined>;
29
+ /**
30
+ * Credential precedence: SANDBASE_API_KEY → `sandbase keys add` → the record of
31
+ * --client / SANDBASE_CLIENT → any connected client record. Connected client
32
+ * records are the browser sign-in result, so most users never paste a key.
33
+ */
34
+ export declare function resolveEndpoint(options?: {
35
+ client?: string;
36
+ }, env?: NodeJS.ProcessEnv): Promise<Endpoint>;
37
+ /** True when the request provably never reached the server, so resending it elsewhere cannot duplicate work. */
38
+ export declare function isPreSendFailure(error: unknown): boolean;
39
+ /** Calls that start or cancel billable work must never be replayed on another host after they may have been sent. */
40
+ export declare function isIdempotentRequest(method: string, params: unknown): boolean;
41
+ export declare function describeNetworkFailure(error: unknown): string;
42
+ /** Map a server/tool error message to the most useful next step. */
43
+ export declare function hintForMessage(message: string, env?: NodeJS.ProcessEnv): string | undefined;
44
+ export declare function httpError(status: number, body: string, host: string, env?: NodeJS.ProcessEnv): SandBaseError;
45
+ export interface ToolOutput {
46
+ data: Record<string, unknown>;
47
+ text: string;
48
+ }
49
+ export type FetchLike = (url: string, init: {
50
+ method: string;
51
+ headers: Record<string, string>;
52
+ body: string | FormData;
53
+ signal: AbortSignal;
54
+ }) => Promise<{
55
+ ok: boolean;
56
+ status: number;
57
+ headers: {
58
+ get(name: string): string | null;
59
+ };
60
+ text(): Promise<string>;
61
+ }>;
62
+ export declare class SandBaseMCPClient {
63
+ readonly endpoint: Endpoint;
64
+ private readonly fetchImpl;
65
+ private readonly timeoutMs;
66
+ private readonly env;
67
+ private session;
68
+ private nextId;
69
+ readonly attempts: Array<{
70
+ url: string;
71
+ outcome: string;
72
+ }>;
73
+ constructor(endpoint: Endpoint, fetchImpl?: FetchLike, timeoutMs?: number, env?: NodeJS.ProcessEnv);
74
+ /** The single API endpoint for this session. */
75
+ activeUrl(): string;
76
+ rpc(method: string, params?: unknown): Promise<unknown>;
77
+ tool(name: string, args?: Record<string, unknown>): Promise<ToolOutput>;
78
+ }
79
+ export declare function toolOutput(result: unknown, env?: NodeJS.ProcessEnv): ToolOutput;
@@ -0,0 +1,274 @@
1
+ // Agent-facing SandBase client: one JSON-RPC-over-HTTP path to the public MCP
2
+ // endpoint, shared by the discover/inspect/run/runs/balance commands and by
3
+ // `sandbase doctor`. Every failure becomes a SandBaseError carrying a stable
4
+ // code plus a concrete next step, so an agent reading the output knows what to
5
+ // do instead of giving up.
6
+ import { readFile } from "node:fs/promises";
7
+ import { join } from "node:path";
8
+ import { sandbaseHome } from "../paths.js";
9
+ import { clients } from "../types.js";
10
+ export const DEFAULT_MCP_URL = "https://api.sandbase.ai/v1/mcp";
11
+ export const UNREACHABLE_HINT = "Check this machine's network, proxy, or VPN, then run `sandbase doctor` and retry.";
12
+ export class SandBaseError extends Error {
13
+ code;
14
+ hint;
15
+ status;
16
+ runId;
17
+ constructor(code, message, hint, status, runId) {
18
+ super(message);
19
+ this.code = code;
20
+ this.hint = hint;
21
+ this.status = status;
22
+ this.runId = runId;
23
+ this.name = "SandBaseError";
24
+ }
25
+ }
26
+ export function webUrl(env = process.env) { return (env.SANDBASE_WEB_URL || "https://www.sandbase.ai").replace(/\/+$/, ""); }
27
+ export function billingUrl(env = process.env) { return `${webUrl(env)}/console/billing`; }
28
+ export function keysUrl(env = process.env) { return `${webUrl(env)}/console/keys`; }
29
+ export const CONNECT_COMMAND = "npx -y @sandbaseai/cli@latest connect";
30
+ export function spendingLimitHint(env = process.env) { return `Stop and tell the user: this key's spending limit is reached. Topping up does not lift it; they can raise or remove the limit at ${keysUrl(env)}, then retry.`; }
31
+ export function validMcpUrl(value) {
32
+ if (typeof value !== "string")
33
+ return undefined;
34
+ try {
35
+ const url = new URL(value);
36
+ return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password && !url.hash && url.pathname === "/v1/mcp" ? url.href : undefined;
37
+ }
38
+ catch {
39
+ return undefined;
40
+ }
41
+ }
42
+ export function keyFilePath(env = process.env) { return join(sandbaseHome(env), "cli-key.json"); }
43
+ export async function readStoredKey(env = process.env) {
44
+ try {
45
+ const value = JSON.parse(await readFile(keyFilePath(env), "utf8"));
46
+ return typeof value?.key === "string" && value.key ? value : undefined;
47
+ }
48
+ catch {
49
+ return undefined;
50
+ }
51
+ }
52
+ async function readCredentials(env) {
53
+ try {
54
+ const value = JSON.parse(await readFile(join(sandbaseHome(env), "credentials.json"), "utf8"));
55
+ return value && typeof value === "object" && !Array.isArray(value) ? value : {};
56
+ }
57
+ catch {
58
+ return {};
59
+ }
60
+ }
61
+ function usable(record, client) { return !!record && record.client === client && typeof record.credential === "string" && !!record.credential && !!validMcpUrl(record.mcpUrl); }
62
+ /**
63
+ * Credential precedence: SANDBASE_API_KEY → `sandbase keys add` → the record of
64
+ * --client / SANDBASE_CLIENT → any connected client record. Connected client
65
+ * records are the browser sign-in result, so most users never paste a key.
66
+ */
67
+ export async function resolveEndpoint(options = {}, env = process.env) {
68
+ const override = env.SANDBASE_MCP_URL ? validMcpUrl(env.SANDBASE_MCP_URL) : undefined;
69
+ if (env.SANDBASE_MCP_URL && !override)
70
+ throw new SandBaseError("USAGE", "SANDBASE_MCP_URL must be an http(s) URL ending in /v1/mcp.");
71
+ if (env.SANDBASE_API_KEY)
72
+ return { credential: env.SANDBASE_API_KEY, url: override || DEFAULT_MCP_URL, source: "env:SANDBASE_API_KEY" };
73
+ const wanted = options.client || env.SANDBASE_CLIENT;
74
+ if (!wanted) {
75
+ const stored = await readStoredKey(env);
76
+ if (stored)
77
+ return { credential: stored.key, url: override || validMcpUrl(stored.mcpUrl) || DEFAULT_MCP_URL, source: "keys" };
78
+ }
79
+ const records = await readCredentials(env);
80
+ if (wanted) {
81
+ const record = records[wanted];
82
+ if (!usable(record, wanted))
83
+ throw new SandBaseError("AUTH_REQUIRED", `No SandBase credential is stored for client "${wanted}".`, `Run \`${CONNECT_COMMAND} --client ${wanted}\`, or omit --client to use any connected client.`);
84
+ return { credential: record.credential, url: override || validMcpUrl(record.mcpUrl) || DEFAULT_MCP_URL, source: `client:${wanted}` };
85
+ }
86
+ for (const client of clients) {
87
+ const record = records[client];
88
+ if (usable(record, client))
89
+ return { credential: record.credential, url: override || validMcpUrl(record.mcpUrl) || DEFAULT_MCP_URL, source: `client:${client}` };
90
+ }
91
+ throw new SandBaseError("AUTH_REQUIRED", "No SandBase credential found on this machine.", `Run \`${CONNECT_COMMAND}\` (browser sign-in, nothing to paste), or create an API key at ${keysUrl(env)} and run \`sandbase keys add -k <key>\` (or set SANDBASE_API_KEY).`);
92
+ }
93
+ /** True when the request provably never reached the server, so resending it elsewhere cannot duplicate work. */
94
+ export function isPreSendFailure(error) {
95
+ const err = error;
96
+ const code = err?.cause?.code || err?.code || "";
97
+ return ["UND_ERR_CONNECT_TIMEOUT", "ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH", "EADDRNOTAVAIL"].includes(code) || /CERT|SSL|TLS/i.test(code);
98
+ }
99
+ /** Calls that start or cancel billable work must never be replayed on another host after they may have been sent. */
100
+ export function isIdempotentRequest(method, params) {
101
+ if (method !== "tools/call")
102
+ return true;
103
+ const name = params?.name;
104
+ return name !== "sandbase_run" && name !== "sandbase_run_cancel";
105
+ }
106
+ export function describeNetworkFailure(error) {
107
+ const err = error;
108
+ const code = err?.cause?.code || err?.code || "";
109
+ if (err?.name === "TimeoutError" || err?.name === "AbortError" || code === "UND_ERR_CONNECT_TIMEOUT" || code === "ETIMEDOUT")
110
+ return "connection timed out";
111
+ if (code === "ENOTFOUND" || code === "EAI_AGAIN")
112
+ return "DNS lookup failed";
113
+ if (code === "ECONNREFUSED")
114
+ return "connection refused";
115
+ if (code === "ECONNRESET" || code === "UND_ERR_SOCKET")
116
+ return "connection reset";
117
+ if (/CERT|SSL|TLS/i.test(code))
118
+ return `TLS error (${code})`;
119
+ return code ? `network error (${code})` : "network error";
120
+ }
121
+ /** Map a server/tool error message to the most useful next step. */
122
+ export function hintForMessage(message, env = process.env) {
123
+ const text = message.toLowerCase();
124
+ // "API key spending limit exceeded" mentions the key but is not a sign-in problem, and
125
+ // topping up does not lift it, so it is checked before both auth and balance.
126
+ if (/spending limit/.test(text))
127
+ return spendingLimitHint(env);
128
+ // Auth first: "API key not found" is a sign-in problem, not a misspelled tool.
129
+ if (/unauthori[sz]ed|api key|credential|revoked|expired|authenticat|sign-in|signin/.test(text))
130
+ return `Sign in again with \`${CONNECT_COMMAND}\`, or check SANDBASE_API_KEY.`;
131
+ if (/insufficient (balance|credit|funds)|payment required|top up/.test(text))
132
+ return `Top up at ${billingUrl(env)}, then retry.`;
133
+ if (/rate.?limit|too many requests|429/.test(text))
134
+ return "Rate limited. Wait 10-30 seconds, then retry once.";
135
+ if (/run .*not found|task not found/.test(text))
136
+ return "Use the run_id printed by `sandbase run` (or find it with `sandbase runs list`). Agent Service runs also need --service <svc_id>.";
137
+ if (/invalid service request|unknown tool|tool(?: '[^']*')? (?:was )?not found|model not found|tool name is required/.test(text))
138
+ return "Check the exact name with `sandbase discover -q \"<what you need>\"` (MCP: sandbase_discover). Names look like sandbase_twitter_web_search_timeline.";
139
+ if (/invalid (params|arguments|input)|is required|schema|must be|unexpected field|additional propert/.test(text))
140
+ return "Re-read the input schema with `sandbase inspect <name>` (MCP: sandbase_inspect) and pass exactly those fields.";
141
+ if (/capability call failed|upstream|provider|bad gateway|timeout|unavailable/.test(text))
142
+ return "The upstream provider failed. Retry once; if it fails again, choose another tool from discover.";
143
+ return undefined;
144
+ }
145
+ export function httpError(status, body, host, env = process.env) {
146
+ let message = "";
147
+ try {
148
+ const parsed = JSON.parse(body);
149
+ const e = parsed.error;
150
+ message = typeof e === "string" ? e : e && typeof e === "object" && typeof e.message === "string" ? e.message : typeof parsed.message === "string" ? parsed.message : "";
151
+ }
152
+ catch { /* gateway HTML or empty body: the status carries the meaning */ }
153
+ const detail = message ? `: ${message}` : "";
154
+ if (status === 401)
155
+ return new SandBaseError("AUTH_FAILED", `SandBase rejected the saved sign-in or API key (401)${detail}.`, `Sign in again with \`${CONNECT_COMMAND}\`, or create a new key at ${keysUrl(env)}.`, status);
156
+ if (status === 402 && /spending limit/i.test(message))
157
+ return new SandBaseError("SPENDING_LIMIT", `This credential reached the spending limit set on it in the SandBase Dashboard (402)${detail}.`, spendingLimitHint(env), status);
158
+ if (status === 402)
159
+ return new SandBaseError("INSUFFICIENT_BALANCE", `Insufficient balance (402)${detail}.`, `Top up at ${billingUrl(env)}, then retry.`, status);
160
+ if (status === 403)
161
+ return new SandBaseError("FORBIDDEN", `This credential is not allowed to call ${host} (403)${detail}.`, `Use a credential issued by \`${CONNECT_COMMAND}\` or a full API key from ${keysUrl(env)}.`, status);
162
+ if (status === 404)
163
+ return new SandBaseError("NOT_FOUND", `MCP endpoint not found on ${host} (404)${detail}.`, "Check SANDBASE_MCP_URL; it must end in /v1/mcp.", status);
164
+ if (status === 429)
165
+ return new SandBaseError("RATE_LIMITED", `Rate limited (429)${detail}.`, "Wait 10-30 seconds, then retry once.", status);
166
+ if (status >= 500)
167
+ return new SandBaseError("UPSTREAM", `SandBase returned HTTP ${status} from ${host}${detail}.`, "Temporary server error. Retry in a minute; run `sandbase doctor` if it persists.", status);
168
+ return new SandBaseError("UPSTREAM", `SandBase returned HTTP ${status} from ${host}${detail}.`, hintForMessage(message, env), status);
169
+ }
170
+ function parseRpcBody(text, contentType, id) {
171
+ const candidates = [];
172
+ if (contentType.includes("text/event-stream")) {
173
+ for (const line of text.split(/\r?\n/))
174
+ if (line.startsWith("data:"))
175
+ candidates.push(line.slice(5).trim());
176
+ }
177
+ else
178
+ candidates.push(text, ...text.split(/\r?\n/));
179
+ let fallback;
180
+ for (const candidate of candidates) {
181
+ if (!candidate || candidate === "[DONE]")
182
+ continue;
183
+ try {
184
+ const value = JSON.parse(candidate);
185
+ if (!value || typeof value !== "object")
186
+ continue;
187
+ if (value.id === id)
188
+ return value;
189
+ fallback ??= value;
190
+ }
191
+ catch { /* keep scanning */ }
192
+ }
193
+ return fallback;
194
+ }
195
+ export class SandBaseMCPClient {
196
+ endpoint;
197
+ fetchImpl;
198
+ timeoutMs;
199
+ env;
200
+ session;
201
+ nextId = 1;
202
+ attempts = [];
203
+ constructor(endpoint, fetchImpl = globalThis.fetch, timeoutMs = 120_000, env = process.env) {
204
+ this.endpoint = endpoint;
205
+ this.fetchImpl = fetchImpl;
206
+ this.timeoutMs = timeoutMs;
207
+ this.env = env;
208
+ }
209
+ /** The single API endpoint for this session. */
210
+ activeUrl() { return this.endpoint.url; }
211
+ async rpc(method, params) {
212
+ const id = this.nextId++;
213
+ const body = JSON.stringify({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) });
214
+ const url = this.endpoint.url;
215
+ const host = new URL(url).host;
216
+ let response;
217
+ try {
218
+ const headers = { authorization: `Bearer ${this.endpoint.credential}`, "content-type": "application/json", accept: "application/json, text/event-stream", "x-sandbase-client": "cli" };
219
+ if (this.session)
220
+ headers["mcp-session-id"] = this.session;
221
+ response = await this.fetchImpl(url, { method: "POST", headers, body, signal: AbortSignal.timeout(this.timeoutMs) });
222
+ }
223
+ catch (error) {
224
+ const reason = describeNetworkFailure(error);
225
+ this.attempts.push({ url, outcome: reason });
226
+ if (!isIdempotentRequest(method, params) && !isPreSendFailure(error)) {
227
+ // The request may already be running server-side; blindly retrying would bill twice.
228
+ throw new SandBaseError("NETWORK", `The request to ${host} was interrupted after it was sent (${reason}); it may have started a run.`, "Do not re-run yet. Check `sandbase runs list` for the run and poll it with `sandbase runs get -r <run_id> -w`.");
229
+ }
230
+ throw new SandBaseError("NETWORK", `Cannot reach SandBase at ${host} (${reason}).`, UNREACHABLE_HINT);
231
+ }
232
+ this.attempts.push({ url, outcome: `HTTP ${response.status}` });
233
+ const session = response.headers.get("mcp-session-id");
234
+ if (session)
235
+ this.session = session;
236
+ const text = await response.text();
237
+ if (!response.ok)
238
+ throw httpError(response.status, text, host, this.env);
239
+ const parsed = parseRpcBody(text, response.headers.get("content-type") || "", id);
240
+ if (!parsed)
241
+ throw new SandBaseError("INVALID_RESPONSE", `Expected JSON-RPC from ${host} but got ${text ? `"${text.slice(0, 80).replace(/\s+/g, " ")}"` : "an empty body"}.`, "A proxy or captive portal may be intercepting traffic. Run `sandbase doctor`.");
242
+ if (parsed.error) {
243
+ const message = parsed.error.message || "request failed";
244
+ const code = parsed.error.code === -32602 ? "INVALID_INPUT" : /unknown tool|tool(?: '[^']*')? (?:was )?not found|run not found|invalid service request/i.test(message) ? "NOT_FOUND" : "TOOL_ERROR";
245
+ throw new SandBaseError(code, message, hintForMessage(message, this.env));
246
+ }
247
+ return parsed.result;
248
+ }
249
+ async tool(name, args = {}) {
250
+ return toolOutput(await this.rpc("tools/call", { name, arguments: args }), this.env);
251
+ }
252
+ }
253
+ const serverErrorCodes = { tool_not_found: "NOT_FOUND", run_not_found: "NOT_FOUND", invalid_arguments: "INVALID_INPUT", insufficient_balance: "INSUFFICIENT_BALANCE", spending_limit: "SPENDING_LIMIT", rate_limited: "RATE_LIMITED", unauthorized: "AUTH_FAILED", run_failed: "RUN_FAILED", upstream_error: "UPSTREAM", internal_error: "UPSTREAM" };
254
+ export function toolOutput(result, env = process.env) {
255
+ const value = (result || {});
256
+ const text = (value.content || []).filter(item => item?.type === "text" && typeof item.text === "string").map(item => item.text).join("\n");
257
+ if (value.isError) {
258
+ // Servers with B-283 send {error:{code,message,hint}, run_id?}; older ones only text.
259
+ const structured = (value.structuredContent && typeof value.structuredContent === "object" ? value.structuredContent : {});
260
+ const serverCode = typeof structured.error?.code === "string" ? structured.error.code : "";
261
+ const message = typeof structured.error?.message === "string" && structured.error.message ? structured.error.message : text || "The tool reported an error.";
262
+ const hint = typeof structured.error?.hint === "string" && structured.error.hint ? structured.error.hint : hintForMessage(text, env);
263
+ throw new SandBaseError(serverErrorCodes[serverCode] || "TOOL_ERROR", message, hint, undefined, typeof structured.run_id === "string" ? structured.run_id : undefined);
264
+ }
265
+ if (value.structuredContent && typeof value.structuredContent === "object" && !Array.isArray(value.structuredContent))
266
+ return { data: value.structuredContent, text };
267
+ try {
268
+ const parsed = JSON.parse(text);
269
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
270
+ return { data: parsed, text };
271
+ }
272
+ catch { /* plain text result */ }
273
+ return { data: { text }, text };
274
+ }
@@ -0,0 +1,28 @@
1
+ import { type FetchLike } from "./client.js";
2
+ export declare const agentCommands: readonly ["discover", "inspect", "run", "runs", "upload", "balance", "keys"];
3
+ export type AgentCommand = typeof agentCommands[number];
4
+ export declare function isAgentCommand(value: string | undefined): value is AgentCommand;
5
+ export interface AgentDeps {
6
+ env?: NodeJS.ProcessEnv;
7
+ fetchImpl?: FetchLike;
8
+ out?: (text: string) => void;
9
+ err?: (text: string) => void;
10
+ sleep?: (ms: number) => Promise<void>;
11
+ now?: () => number;
12
+ stdin?: () => Promise<string>;
13
+ }
14
+ export declare const agentUsage = "SandBase agent commands (same capabilities as the sandbase_* MCP tools):\n sandbase discover -q \"<what you need>\" [-t llm|api|multimodal|embedding|service] [--vendor <slug>] [-l 10] [-j]\n sandbase inspect <tool_name> [-j]\n sandbase run <tool_name> [-i '<json>' | -f input.json] [-w] [--timeout 300] [-o result.json] [-j]\n sandbase runs get -r <run_id> [--service <svc_id>] [-w] [--timeout 300] [-o result.json] [-j]\n sandbase runs list [-l 10] [--model <model>] [--service <svc_id>] [-j]\n sandbase upload <file> [-j] (local image/audio/video \u2192 public URL for tools that take a URL)\n sandbase balance [-j]\n sandbase keys add -k - (reads the key from stdin) | keys list | keys remove\nGlobal: --client <client> picks a connected client's credential; SANDBASE_API_KEY overrides all; -j prints JSON.";
15
+ export declare function formatPrice(pricing: unknown): string;
16
+ /**
17
+ * Files the run produced. The server returns media outputs as `[{url, …}]`
18
+ * (content_type is only added when it can be inferred), so an entry counts as a
19
+ * file when it has a `url` and carries no content of its own. A scraped page's
20
+ * `{url, markdown}`, a tweet row, or a nested avatar is content, not a file.
21
+ */
22
+ export declare function generatedFiles(output: unknown): string[];
23
+ /** Resolve a root-level local $ref (#/components/schemas/X, #/$defs/X, #/definitions/X) so agents see real fields. */
24
+ export declare function resolveSchema(schema: unknown): Record<string, unknown>;
25
+ export declare function uploadUrlFor(mcpUrl: string): string;
26
+ /** Shows at most a quarter of the key (capped at 6 chars) so short keys are not mostly revealed. */
27
+ export declare function maskKey(key: string): string;
28
+ export declare function runAgentCommand(command: AgentCommand, argv: string[], deps?: AgentDeps): Promise<number>;