@fieldwork-ai/cli 0.16.0

package/dist/commands/tool.js

@@ -0,0 +1,106 @@
+import { apiJson, getContext } from "../http.js";
+import { EXIT, fail, printData } from "../output.js";
+/**
+ * `fieldwork tool run <name>` argument assembly (the httpie convention):
+ * --args takes a JSON object ('-' reads stdin); repeated --arg entries merge
+ * over it — `k=v` as a string, `k:=v` JSON-parsed.
+ */
+export function buildToolArgs(argsOption, argEntries, stdin) {
+    let base = {};
+    const rawJson = argsOption === "-" ? stdin : argsOption;
+    if (argsOption === "-" && stdin === null) {
+        fail("--args - requires JSON on stdin", EXIT.usage);
+    }
+    if (rawJson !== undefined && rawJson !== null) {
+        try {
+            const parsed = JSON.parse(rawJson);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                throw new Error("not an object");
+            }
+            base = parsed;
+        }
+        catch {
+            fail("--args must be a JSON object", EXIT.usage);
+        }
+    }
+    return applyArgEntries(base, argEntries, "--arg");
+}
+/** Merge `k=v` (string) / `k:=json` entries into base — shared by tool run's
+ * --arg and the query verbs' --param. */
+export function applyArgEntries(base, entries, flag) {
+    for (const entry of entries) {
+        const jsonMatch = /^([^=:]+):=([\s\S]*)$/.exec(entry);
+        if (jsonMatch) {
+            try {
+                base[jsonMatch[1]] = JSON.parse(jsonMatch[2]);
+            }
+            catch {
+                fail(`${flag} ${jsonMatch[1]}:= expects valid JSON`, EXIT.usage);
+            }
+            continue;
+        }
+        const stringMatch = /^([^=]+)=([\s\S]*)$/.exec(entry);
+        if (!stringMatch) {
+            fail(`${flag} must be key=value or key:=json (got "${entry}")`, EXIT.usage);
+        }
+        base[stringMatch[1]] = stringMatch[2];
+    }
+    return base;
+}
+export async function readStdin() {
+    if (process.stdin.isTTY)
+        return null;
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+export function registerToolCommands(program) {
+    const tool = program.command("tool").description("List and run gateway tools");
+    tool
+        .command("list")
+        .description("List the tools you can run (personalized to your connections)")
+        .action(async () => {
+        const { json } = getContext();
+        const body = await apiJson("/api/tools");
+        if (json) {
+            printData(body, true);
+            return;
+        }
+        for (const t of body.tools) {
+            // Skip leading bracketed router markers (Composio prefixes every
+            // "direct" tool with one) so the summary line is the real description.
+            const firstLine = t.description.split("\n").find((l) => l.trim() && !/^\[.*\]$/.test(l.trim())) ??
+                t.description.split("\n")[0] ??
+                "";
+            printData(`${t.name}\t${firstLine.slice(0, 100)}`, false);
+        }
+    });
+    tool
+        .command("describe <name>")
+        .description("One tool's description and input schema (JSON Schema)")
+        .action(async (name) => {
+        const { json } = getContext();
+        const body = await apiJson("/api/tools");
+        const found = body.tools.find((t) => t.name === name);
+        if (!found)
+            fail(`no such tool: ${name} — check fieldwork tool list`, EXIT.notFound);
+        printData(found, json);
+    });
+    tool
+        .command("run <name>")
+        .description("Run a tool by name")
+        .option("--args <json>", "arguments as a JSON object, or - for stdin")
+        .option("--arg <entry...>", "merge one argument: key=value (string) or key:=json", [])
+        .action(async (name, opts) => {
+        const { json } = getContext();
+        const stdin = opts.args === "-" ? await readStdin() : null;
+        const args = buildToolArgs(opts.args, opts.arg, stdin);
+        const body = await apiJson("/api/tools/run", {
+            method: "POST",
+            body: JSON.stringify({ name, args }),
+        });
+        // Tool-error strings are data (chat semantics): printed, exit 0.
+        printData(body.result, json);
+    });
+}

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Credential resolution (ADR 20260804), in order:
+ *   1. FIELDWORK_TOKEN / FIELDWORK_API_URL environment variables — how the
+ *      Firecracker backend delivers per-conversation credentials (env on each
+ *      bash call); env must beat the file, or a stale machine-scoped file
+ *      would shadow the conversation-scoped identity in a shared VM;
+ *   2. ~/.fieldwork/credentials — the dotenv file the platform injects into
+ *      Fargate compute containers at claim time;
+ *   3. ~/.config/fieldwork/config.json — written by `fieldwork login`.
+ * --token / --api-url flags override everything.
+ *
+ * The token is org-pinned at mint (container conversation tokens and OAuth
+ * JWTs both carry the org), so there is no per-request org selection: the org
+ * id is decoded from the token to build org-scoped route paths, and the
+ * server re-verifies everything — the local decode is a convenience, never
+ * an authority.
+ */
+export interface LoginConfig {
+    api_url: string;
+    access_token: string;
+    refresh_token?: string;
+    expires_at?: number;
+    organization_id?: string;
+}
+export interface ResolvedConfig {
+    apiUrl: string;
+    token: string | null;
+    source: "flags" | "container" | "env" | "login" | "none";
+    /** Set when source is "login": enables the refresh-once path in http.ts. */
+    login?: LoginConfig;
+}
+export declare const CONTAINER_CREDENTIALS_PATH: string;
+export declare function loginConfigPath(): string;
+export declare function readLoginConfig(): LoginConfig | null;
+export declare function resolveConfig(flags: {
+    apiUrl?: string;
+    token?: string;
+}): ResolvedConfig;
+interface DecodedToken {
+    sub?: string;
+    org?: string;
+    cnv?: string;
+    organization_id?: string;
+    exp?: number;
+    typ?: string;
+}
+/**
+ * Best-effort local decode of either token kind (2-segment envelope, 3-segment
+ * JWT) — for building org-scoped paths and `whoami` output. Never an
+ * authority: the server verifies the signature and re-resolves membership.
+ */
+export declare function decodeToken(token: string): DecodedToken | null;
+export declare function orgIdFromToken(token: string): string | null;
+export {};

package/dist/config.js

@@ -0,0 +1,93 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+export const CONTAINER_CREDENTIALS_PATH = path.join(homedir(), ".fieldwork", "credentials");
+export function loginConfigPath() {
+    const base = process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config");
+    return path.join(base, "fieldwork", "config.json");
+}
+function parseDotenv(content) {
+    const values = {};
+    for (const line of content.split("\n")) {
+        const match = /^([A-Z0-9_]+)=(.*)$/.exec(line.trim());
+        if (match)
+            values[match[1]] = match[2];
+    }
+    return values;
+}
+export function readLoginConfig() {
+    try {
+        const parsed = JSON.parse(readFileSync(loginConfigPath(), "utf8"));
+        if (typeof parsed?.api_url === "string" && typeof parsed?.access_token === "string") {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveConfig(flags) {
+    const flagUrl = flags.apiUrl;
+    const flagToken = flags.token;
+    if (flagToken && flagUrl) {
+        return { apiUrl: flagUrl, token: flagToken, source: "flags" };
+    }
+    if (process.env.FIELDWORK_TOKEN && process.env.FIELDWORK_API_URL) {
+        return {
+            apiUrl: flagUrl ?? process.env.FIELDWORK_API_URL,
+            token: flagToken ?? process.env.FIELDWORK_TOKEN,
+            source: "env",
+        };
+    }
+    let container = {};
+    try {
+        container = parseDotenv(readFileSync(CONTAINER_CREDENTIALS_PATH, "utf8"));
+    }
+    catch {
+        // Not in a container (or credentials not injected) — fall through.
+    }
+    if (container.FIELDWORK_TOKEN && container.FIELDWORK_API_URL) {
+        return {
+            apiUrl: flagUrl ?? container.FIELDWORK_API_URL,
+            token: flagToken ?? container.FIELDWORK_TOKEN,
+            source: "container",
+        };
+    }
+    const login = readLoginConfig();
+    if (login) {
+        return {
+            apiUrl: flagUrl ?? login.api_url,
+            token: flagToken ?? login.access_token,
+            source: "login",
+            login,
+        };
+    }
+    return {
+        apiUrl: flagUrl ?? process.env.FIELDWORK_API_URL ?? "https://app.getfieldwork.ai",
+        token: flagToken ?? null,
+        source: flagToken ? "flags" : "none",
+    };
+}
+/**
+ * Best-effort local decode of either token kind (2-segment envelope, 3-segment
+ * JWT) — for building org-scoped paths and `whoami` output. Never an
+ * authority: the server verifies the signature and re-resolves membership.
+ */
+export function decodeToken(token) {
+    const segments = token.split(".");
+    const payloadSegment = segments.length === 2 ? segments[0] : segments.length === 3 ? segments[1] : null;
+    if (!payloadSegment)
+        return null;
+    try {
+        return JSON.parse(Buffer.from(payloadSegment, "base64url").toString("utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function orgIdFromToken(token) {
+    const decoded = decodeToken(token);
+    const org = decoded?.org ?? decoded?.organization_id;
+    return typeof org === "string" && org ? org : null;
+}

package/dist/content-kind.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What a Knowledge Base row holds, answered from its content type.
+ *
+ * Mirrors src/lib/kb/content-kind.ts. The CLI ships as its own package and
+ * cannot import from the app, so the discriminator is duplicated rather than
+ * re-derived: there is no `kind` field on the wire, and guessing from the
+ * extension sends a `.md` document down the page write path.
+ */
+/** What the store writes for markdown it authors. */
+export declare const MARKDOWN_CONTENT_TYPE = "text/markdown";
+/** `text/markdown; charset=utf-8` → `text/markdown`. */
+export declare function normalizeContentType(contentType: string): string;
+/** Markdown: read as a page, edited in place, pulled and pushed as text. */
+export declare function isMarkdown(contentType: string | null | undefined): boolean;

package/dist/content-kind.js

@@ -0,0 +1,18 @@
+/**
+ * What a Knowledge Base row holds, answered from its content type.
+ *
+ * Mirrors src/lib/kb/content-kind.ts. The CLI ships as its own package and
+ * cannot import from the app, so the discriminator is duplicated rather than
+ * re-derived: there is no `kind` field on the wire, and guessing from the
+ * extension sends a `.md` document down the page write path.
+ */
+/** What the store writes for markdown it authors. */
+export const MARKDOWN_CONTENT_TYPE = "text/markdown";
+/** `text/markdown; charset=utf-8` → `text/markdown`. */
+export function normalizeContentType(contentType) {
+    return contentType.split(";")[0].trim().toLowerCase();
+}
+/** Markdown: read as a page, edited in place, pulled and pushed as text. */
+export function isMarkdown(contentType) {
+    return contentType != null && normalizeContentType(contentType) === MARKDOWN_CONTENT_TYPE;
+}

package/dist/http.d.ts

@@ -0,0 +1,27 @@
+import { type ResolvedConfig } from "./config.js";
+/**
+ * The one HTTP door: resolves credentials, attaches the bearer, maps failures
+ * to exit codes, and — for login-managed tokens — refreshes once on 401.
+ */
+export interface CliContext {
+    config: ResolvedConfig;
+    json: boolean;
+    yes: boolean;
+}
+export declare function initContext(flags: {
+    apiUrl?: string;
+    token?: string;
+    json?: boolean;
+    yes?: boolean;
+}): CliContext;
+export declare function getContext(): CliContext;
+export declare function requireToken(): string;
+/** The org the token is pinned to — used to build org-scoped route paths. */
+export declare function requireOrgId(): string;
+export declare function api(pathname: string, init?: RequestInit & {
+    body?: string;
+}): Promise<Response>;
+/** api() + JSON body + fail-on-error, the shape most commands want. */
+export declare function apiJson<T = unknown>(pathname: string, init?: RequestInit & {
+    body?: string;
+}): Promise<T>;

package/dist/http.js

@@ -0,0 +1,120 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { loginConfigPath, orgIdFromToken, resolveConfig, } from "./config.js";
+import { EXIT, exitCodeFor, fail } from "./output.js";
+let ctx = null;
+export function initContext(flags) {
+    ctx = {
+        config: resolveConfig(flags),
+        json: flags.json ?? false,
+        yes: flags.yes ?? false,
+    };
+    return ctx;
+}
+export function getContext() {
+    if (!ctx)
+        throw new Error("CLI context not initialized");
+    return ctx;
+}
+export function requireToken() {
+    const { config } = getContext();
+    if (!config.token) {
+        fail("no credentials — run `fieldwork login`, or set FIELDWORK_TOKEN and FIELDWORK_API_URL", EXIT.auth);
+    }
+    return config.token;
+}
+/** The org the token is pinned to — used to build org-scoped route paths. */
+export function requireOrgId() {
+    const org = orgIdFromToken(requireToken());
+    if (!org) {
+        fail("the current token carries no organization — run `fieldwork login` again", EXIT.auth);
+    }
+    return org;
+}
+async function refreshLoginToken() {
+    const { config } = getContext();
+    if (config.source !== "login" || !config.login?.refresh_token)
+        return null;
+    try {
+        const discovery = await fetch(`${config.apiUrl}/.well-known/oauth-authorization-server/api/auth`);
+        if (!discovery.ok)
+            return null;
+        const { token_endpoint } = (await discovery.json());
+        if (!token_endpoint)
+            return null;
+        const res = await fetch(token_endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: config.login.refresh_token,
+                client_id: "fieldwork-cli",
+                resource: config.apiUrl,
+            }).toString(),
+        });
+        if (!res.ok)
+            return null;
+        const tokens = (await res.json());
+        if (!tokens.access_token)
+            return null;
+        const updated = {
+            ...config.login,
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token ?? config.login.refresh_token,
+            expires_at: tokens.expires_in
+                ? Math.floor(Date.now() / 1000) + tokens.expires_in
+                : undefined,
+            organization_id: orgIdFromToken(tokens.access_token) ?? config.login.organization_id,
+        };
+        const file = loginConfigPath();
+        mkdirSync(path.dirname(file), { recursive: true });
+        writeFileSync(file, `${JSON.stringify(updated, null, 2)}\n`, { mode: 0o600 });
+        config.token = tokens.access_token;
+        config.login = updated;
+        return tokens.access_token;
+    }
+    catch {
+        return null;
+    }
+}
+export async function api(pathname, init = {}) {
+    const { config } = getContext();
+    const token = requireToken();
+    const headers = new Headers(init.headers);
+    headers.set("authorization", `Bearer ${token}`);
+    const orgId = orgIdFromToken(token);
+    if (orgId)
+        headers.set("X-Organization-Id", orgId);
+    if (init.body && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    let res;
+    try {
+        res = await fetch(`${config.apiUrl}${pathname}`, { ...init, headers });
+    }
+    catch (err) {
+        if (init.signal?.aborted)
+            throw err;
+        fail(`could not reach ${config.apiUrl}: ${err instanceof Error ? err.message : "network error"}`, EXIT.server);
+    }
+    if (res.status === 401) {
+        const refreshed = await refreshLoginToken();
+        if (refreshed) {
+            headers.set("authorization", `Bearer ${refreshed}`);
+            const orgId = orgIdFromToken(refreshed);
+            if (orgId)
+                headers.set("X-Organization-Id", orgId);
+            res = await fetch(`${config.apiUrl}${pathname}`, { ...init, headers });
+        }
+    }
+    return res;
+}
+/** api() + JSON body + fail-on-error, the shape most commands want. */
+export async function apiJson(pathname, init = {}) {
+    const res = await api(pathname, init);
+    const body = (await res.json().catch(() => null));
+    if (!res.ok) {
+        fail(body?.error ?? `request failed (${res.status})`, exitCodeFor(res.status));
+    }
+    return body;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { createRequire } from "node:module";
+import { initContext } from "./http.js";
+import { registerToolCommands } from "./commands/tool.js";
+import { registerAssetCommands } from "./commands/assets.js";
+import { registerKbCommands } from "./commands/kb.js";
+import { registerAppCommands } from "./commands/apps.js";
+import { registerAutomationCommands } from "./commands/automations.js";
+import { registerTaskCommands } from "./commands/tasks.js";
+import { registerConnectorCommands } from "./commands/connectors.js";
+import { registerAuthCommands } from "./commands/auth.js";
+/**
+ * The Fieldwork CLI (ADR 20260804): a plain REST client of the org-scoped
+ * API. One artifact, two environments — inside the compute container
+ * (credentials injected at ~/.fieldwork/credentials, conversation-scoped
+ * token) and on a laptop (`fieldwork login`, org-bound OAuth token). stdout
+ * is data, stderr is messages; --json for machines; mutations prompt unless
+ * --yes.
+ */
+// One version source: package.json sits beside src/ and dist/ alike, so the
+// relative require resolves in both the tsx dev path and the built package.
+const { version } = createRequire(import.meta.url)("../package.json");
+const program = new Command("fieldwork")
+    .description("Drive Fieldwork: org assets, tools, and credentials")
+    .version(version)
+    .option("--json", "print raw API responses (compact JSON)")
+    .option("--yes", "skip confirmation prompts (mutations)")
+    .option("--api-url <url>", "override the API base URL")
+    .option("--token <token>", "override the bearer token")
+    .hook("preAction", (thisCommand) => {
+    const opts = thisCommand.optsWithGlobals();
+    initContext(opts);
+});
+registerAuthCommands(program);
+registerToolCommands(program);
+registerAssetCommands(program);
+registerKbCommands(program);
+registerAppCommands(program);
+registerAutomationCommands(program);
+registerTaskCommands(program);
+registerConnectorCommands(program);
+program.parseAsync(process.argv).catch((err) => {
+    process.stderr.write(`fieldwork: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/oauth.d.ts

@@ -0,0 +1,2 @@
+import { type LoginConfig } from "./config.js";
+export declare function login(apiUrl: string): Promise<LoginConfig>;

package/dist/oauth.js

@@ -0,0 +1,123 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { loginConfigPath, orgIdFromToken } from "./config.js";
+import { EXIT, fail, note } from "./output.js";
+/**
+ * `fieldwork login`: OAuth 2.1 authorization-code + PKCE against the
+ * Fieldwork provider, as the seeded public `fieldwork-cli` client. Loopback
+ * redirect on an ephemeral 127.0.0.1 port — the registered port is ignored
+ * for loopback IPs (RFC 8252 §7.3). Zero dependencies: node:http catches the
+ * callback, node:crypto does PKCE S256.
+ */
+const CLIENT_ID = "fieldwork-cli";
+const SCOPE = "openid profile email offline_access fieldwork:api";
+async function discover(apiUrl) {
+    const res = await fetch(`${apiUrl}/.well-known/oauth-authorization-server/api/auth`).catch(() => null);
+    if (!res?.ok) {
+        fail(`could not discover the OAuth server at ${apiUrl}`, EXIT.server);
+    }
+    const meta = (await res.json());
+    if (!meta.authorization_endpoint || !meta.token_endpoint) {
+        fail("the OAuth server metadata is missing its endpoints", EXIT.server);
+    }
+    return meta;
+}
+function openBrowser(url) {
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        const child = spawn(command, [url], { stdio: "ignore", detached: true });
+        child.on("error", () => note(`Open this URL to continue:\n\n  ${url}\n`));
+        child.unref();
+    }
+    catch {
+        note(`Open this URL to continue:\n\n  ${url}\n`);
+    }
+}
+export async function login(apiUrl) {
+    const discovery = await discover(apiUrl);
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const state = randomBytes(16).toString("base64url");
+    // Bind first so the redirect_uri carries the real port.
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : 0;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const authorizeUrl = new URL(discovery.authorization_endpoint);
+    authorizeUrl.search = new URLSearchParams({
+        response_type: "code",
+        client_id: CLIENT_ID,
+        redirect_uri: redirectUri,
+        scope: SCOPE,
+        state,
+        code_challenge: challenge,
+        code_challenge_method: "S256",
+    }).toString();
+    const callback = new Promise((resolve, reject) => {
+        server.on("request", (req, res) => {
+            const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const error = url.searchParams.get("error");
+            const code = url.searchParams.get("code");
+            const gotState = url.searchParams.get("state");
+            res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            res.end(error
+                ? "<p>Authorization failed — you can close this tab.</p>"
+                : "<p>Signed in — you can close this tab and return to the terminal.</p>");
+            server.close();
+            if (error)
+                reject(new Error(`authorization failed: ${error}`));
+            else if (!code || gotState !== state)
+                reject(new Error("invalid callback"));
+            else
+                resolve(code);
+        });
+        setTimeout(() => {
+            server.close();
+            reject(new Error("timed out waiting for the browser (5 minutes)"));
+        }, 5 * 60 * 1000).unref();
+    });
+    note("Opening your browser to sign in to Fieldwork…");
+    openBrowser(authorizeUrl.toString());
+    const code = await callback.catch((err) => fail(err.message, EXIT.auth));
+    const tokenRes = await fetch(discovery.token_endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            client_id: CLIENT_ID,
+            code_verifier: verifier,
+            redirect_uri: redirectUri,
+            // RFC 8707: makes the access token a JWT bound to the API audience.
+            resource: apiUrl,
+        }).toString(),
+    });
+    const tokens = (await tokenRes.json().catch(() => null));
+    if (!tokenRes.ok || !tokens?.access_token) {
+        fail(tokens?.error_description ?? "token exchange failed", EXIT.auth);
+    }
+    const config = {
+        api_url: apiUrl,
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token,
+        expires_at: tokens.expires_in
+            ? Math.floor(Date.now() / 1000) + tokens.expires_in
+            : undefined,
+        organization_id: orgIdFromToken(tokens.access_token) ?? undefined,
+    };
+    const file = loginConfigPath();
+    mkdirSync(path.dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    return config;
+}

package/dist/output.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Output conventions (ADR 20260804): stdout carries data only, every message
+ * and prompt goes to stderr, --json prints the raw API payload compact —
+ * every verb honors it with a stable shape (mutations included: writes print
+ * what happened, pulls print what landed where).
+ * Exit codes: 0 ok · 1 server/network · 2 usage or 400 · 3 auth (401) ·
+ * 4 forbidden (403) · 5 not found (404) · 6 conflict (409) · 7 rate limited.
+ * Failures exit non-zero via fail()/exitCodeFor. The one deliberate
+ * exception: `tool run` prints tool-error strings as data and exits 0 (chat
+ * semantics — a tool error is a result, not a CLI failure); purpose verbs
+ * never do that, which is one reason they are REST-backed.
+ */
+export declare const EXIT: {
+    readonly ok: 0;
+    readonly server: 1;
+    readonly usage: 2;
+    readonly auth: 3;
+    readonly forbidden: 4;
+    readonly notFound: 5;
+    readonly conflict: 6;
+    readonly rateLimited: 7;
+};
+export declare function exitCodeFor(status: number): number;
+export declare function printData(value: unknown, json: boolean): void;
+export declare function note(message: string): void;
+export interface TabularResult {
+    columns: string[];
+    rows: Record<string, unknown>[];
+    truncated?: boolean;
+    truncatedBy?: "rows" | "bytes" | null;
+    rowsReturned?: number;
+}
+/** Query results: --json prints the raw payload; human mode prints TSV (a
+ * header row, then rows) with any truncation noted on stderr. Truncation is
+ * a successful result — no exit-code change. */
+export declare function printTabular(result: TabularResult, json: boolean): void;
+export declare function fail(message: string, code: number): never;
+/** Confirm a mutation: prompt on a TTY, --yes skips, non-TTY without --yes
+ * is a usage error (unattended callers must opt in explicitly). */
+export declare function confirm(message: string, yes: boolean): Promise<void>;