@aisa-one/cli 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.2] — 2026-09-23
+
+### Added
+
+- Carry Router session IDs through CLI tool commands.
+
+### Fixed
+
+- Send `User-Agent: aisa-cli` on outbound HTTP requests.
+
+## [0.6.1] — 2026-09-11
+
+### Changed
+
+- Show the GTM balance separately in `aisa balance`. The account and
+  key-available totals now reflect the API's combined PAYG and GTM balances.
+
 ## [0.6.0] — 2026-09-10
 
 ### Changed
@@ -444,7 +461,9 @@ supports today; nothing here depends on a backend change.
 - Config commands (`aisa config get|set|list|reset`) and auth
   (`aisa login|logout|whoami`).
 
-[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/AIsa-team/cli/compare/v0.6.2...HEAD
+[0.6.2]: https://github.com/AIsa-team/cli/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/AIsa-team/cli/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/AIsa-team/cli/compare/v0.5.2...v0.6.0
 [0.5.2]: https://github.com/AIsa-team/cli/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/AIsa-team/cli/compare/v0.5.0...v0.5.1

package/README.md

@@ -63,7 +63,13 @@ and `aisa manifest search` / `schema` / `quote` / `call` expose `mcp`, `auth`,
 
 Recommended sequence: discover a tool → `aisa schema` when
 `has_full_schema=false` → `aisa quote` → `aisa call`. Quote and call share
-one request shape. **Enforced:** invalid local input exits 2 and is not sent;
+one request shape. The first search may omit `session_id`; the Router returns
+one. Reuse that ID for every later search, schema, quote, and call in the same
+task, using `--session-id <id>` or a top-level `session_id` in `--input`/`-f`
+JSON. The CLI does not save it between commands. For related quote/call
+requests, also carry the Search `search_id`; it identifies the search, while
+`session_id` groups the task. Standalone commands may omit either ID.
+**Enforced:** invalid local input exits 2 and is not sent;
 quote and call refuse to run without an OAuth session or static AIsa API key. **Not
 enforced:** the CLI does not record quotes, approvals, or budget caps and
 does not reject an unquoted call. **Instruction:** do not execute unquoted
@@ -98,6 +104,21 @@ aisa call --input '{"calls":[{"call_id":"c1","tool":"get_financial_company_facts
 aisa call -f - --json < request.json
 ```
 
+For a multi-step task, copy the actual `session_id` from the first search
+response (shown in normal output or `--json`) and pass it on later commands:
+
+```sh
+aisa search "company facts"
+aisa search "company revenue" --session-id "$SESSION_ID"
+aisa schema get_financial_company_facts --session-id "$SESSION_ID"
+aisa quote --input '{"search_id":"SEARCH_ID","calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --session-id "$SESSION_ID" --json
+aisa call --input '{"search_id":"SEARCH_ID","calls":[{"call_id":"c1","tool":"get_financial_company_facts","arguments":{"ticker":"AAPL"}}]}' --session-id "$SESSION_ID" --json
+```
+
+Set `SESSION_ID` and replace `SEARCH_ID` with values returned by your search;
+quote the same calls before an authorized call. If JSON already contains
+`session_id`, omit `--session-id` to avoid conflicting sources.
+
 `--json` keeps large integer tokens. Diagnostics go to stderr. Exit `2` means
 local input was invalid and nothing was sent; `1` is transport, auth, or an
 HTTP error; `3` means the Router returned a batch with at least one failed

package/dist/commands/account.js

@@ -29,6 +29,7 @@ export async function balanceAction(options = {}) {
     const balance = res.data;
     console.log(`  Balance:             ${formatMicrosUSD(balance.account_balance_micros_usd)} ${balance.currency}`);
     console.log(`  Available with key:  ${formatMicrosUSD(balance.available_balance_micros_usd)} ${balance.currency}`);
+    console.log(`  GTM balance:         ${formatMicrosUSD(balance.go_to_market_balance_micros_usd)} ${balance.currency}`);
     if (balance.api_key.unlimited) {
         console.log("  API key limit:       Unlimited");
     }

package/dist/commands/connect.js

@@ -1935,7 +1935,7 @@ async function probeRun(url) {
         const token = u.searchParams.get("token") ?? "";
         if (!token)
             return { ours: false };
-        const res = await fetch(`${u.origin}/status?token=${token}`, { signal: AbortSignal.timeout(2_000) });
+        const res = await httpFetch(`${u.origin}/status?token=${token}`, { timeoutMs: 2_000 });
         if (!res.ok)
             return { ours: false };
         const data = (await res.json());

package/dist/commands/install.js

@@ -1,5 +1,6 @@
 import { accessSync, constants, existsSync } from "node:fs";
 import { runShell, runSync, QUICK_TIMEOUT_MS } from "../utils/exec.js";
+import { httpFetch } from "../utils/http.js";
 export const INSTALLERS = {
     "claude-code": {
         id: "claude-code",
@@ -10,7 +11,7 @@ export const INSTALLERS = {
         // what makes the mirror path below work where claude.ai is unreachable.
         // Curl gets its own timeouts: a blackholed connection must fail in
         // seconds, not sit until the overall install deadline.
-        command: "curl -fsSL --connect-timeout 10 --max-time 180 https://claude.ai/install.sh | bash",
+        command: "curl -fsSL -A aisa-cli --connect-timeout 10 --max-time 180 https://claude.ai/install.sh | bash",
         installDir: "~/.local/bin",
         npmPackage: "@anthropic-ai/claude-code",
         probeUrl: "https://claude.ai/install.sh",
@@ -71,7 +72,7 @@ export async function pickNpmChannel(pkg, probe = headOk, userRegistry = npmConf
 }
 async function headOk(url) {
     try {
-        const res = await fetch(url, { method: "HEAD", signal: AbortSignal.timeout(3_000) });
+        const res = await httpFetch(url, { method: "HEAD", timeoutMs: 3_000 });
         return res.ok;
     }
     catch {

package/dist/commands/mcp.js

@@ -254,7 +254,7 @@ export async function mcpStatusAction() {
  */
 export async function pingEndpoint(endpoint) {
     try {
-        const res = await fetch(endpoint, {
+        const res = await httpFetch(endpoint, {
             method: "POST",
             headers: { "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
             body: JSON.stringify({
@@ -267,7 +267,7 @@ export async function pingEndpoint(endpoint) {
                     clientInfo: { name: "aisa-cli", version: "status" },
                 },
             }),
-            signal: AbortSignal.timeout(8_000),
+            timeoutMs: 8_000,
         });
         if (res.status === 200)
             return `${chalk.green("✓")} reachable (open)`;

package/dist/commands/serve-results.js

@@ -3,6 +3,7 @@ import { spawn } from "node:child_process";
 import { readFileSync, writeFileSync, unlinkSync, mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { httpFetch } from "../utils/http.js";
 import { renderT2Page } from "./connect-t2.js";
 import { isInstalled } from "./install.js";
 import { renderDone } from "./connect.js";
@@ -56,8 +57,8 @@ export async function closeStaleResults() {
     // crash may belong to something else entirely by now. Answering on that
     // port with that token is the only proof that counts.
     try {
-        const res = await fetch(`http://127.0.0.1:${rec.port}/status?token=${rec.token}`, {
-            signal: AbortSignal.timeout(1_500),
+        const res = await httpFetch(`http://127.0.0.1:${rec.port}/status?token=${rec.token}`, {
+            timeoutMs: 1_500,
         });
         if (!res.ok)
             return forget();

package/dist/commands/tool-help.js

@@ -29,7 +29,7 @@ export const ROUTER_EXITS = {
     "1": "transport, auth, or HTTP error",
     "3": "HTTP 200 with any failed batch item",
 };
-const FLOW = "Recommended sequence: aisa search → aisa schema when has_full_schema=false → aisa quote → aisa call.";
+const FLOW = "Recommended sequence: aisa search → aisa schema when has_full_schema=false → aisa quote → aisa call. First search may omit session_id; reuse the returned session_id for every later search, schema, quote, and call in the same task. Pass it as --session-id or as a top-level JSON field. The CLI does not save sessions between commands. Keep search_id from search on related quote and call requests.";
 const INLINE = "--input is inline JSON text (no file required). Shell examples are POSIX sh with single-quoted --input; apostrophes are written as '\\'' so $(), backticks, and other expansions stay literal. -f FILE and -f - remain available.";
 const JSON_CONTRACT = "--json writes the unmodified application body, including MCP identifiers and numeric tokens. Human output maps only AISA_SEARCH_TOOL, AISA_BATCH_GET_SCHEMA, AISA_BATCH_QUOTE, and AISA_BATCH_USE to aisa search / schema / quote / call.";
 const KEY_RESOLUTION = "Prefer aisa login (stores a CLI key). Resolution: AISA_API_KEY, then ~/.aisa/key, then legacy login. CI: AISA_API_KEY or aisa login --key.";
@@ -60,7 +60,7 @@ export function routerContract(kind) {
         case "schema":
             return {
                 auth: "optional",
-                flow: `Use after search when has_full_schema=false. Pass exact tool names from search. ${EXAMPLE_PUBLISHED_TOOL} is a published tool whose schema includes ticker.`,
+                flow: `Use after search when has_full_schema=false. Pass exact tool names and reuse the returned session_id via --session-id or a top-level JSON field. The CLI does not save sessions between commands. ${EXAMPLE_PUBLISHED_TOOL} is a published tool whose schema includes ticker.`,
                 enforced: [ENFORCED_OPTIONAL],
                 safety: [
                     "Instruction: Do not invent tool names. Do not guess arguments; read the returned schema.",

package/dist/commands/tool-input.d.ts

@@ -2,6 +2,7 @@ export type RouterKind = "search" | "schema" | "quote" | "call";
 export interface RouterIoOptions {
     input?: string;
     file?: string;
+    sessionId?: string;
     json?: boolean;
     limit?: string;
     provider?: string[];

package/dist/commands/tool-input.js

@@ -8,6 +8,8 @@ export async function prepareRouterRequest(kind, operands, options) {
     const hasInput = options.input !== undefined;
     const hasFile = options.file !== undefined;
     const hasOperands = operands.length > 0;
+    if (options.sessionId === "")
+        throw usageError("--session-id must not be empty");
     if (hasInput && hasFile) {
         throw usageError("Use either --input or -f/--file, not both");
     }
@@ -18,10 +20,10 @@ export async function prepareRouterRequest(kind, operands, options) {
         throw usageError("Do not combine --input/-f with field flags; put every field in the JSON request");
     }
     if (hasInput) {
-        return fromEnvelope(kind, options.input, " --input");
+        return withSessionId(kind, fromEnvelope(kind, options.input, " --input"), options.sessionId);
     }
     if (hasFile) {
-        return fromEnvelope(kind, await readRequestFile(options.file), ` -f ${options.file}`);
+        return withSessionId(kind, fromEnvelope(kind, await readRequestFile(options.file), ` -f ${options.file}`), options.sessionId);
     }
     if (kind === "search") {
         return buildSearch(operands, options);
@@ -68,6 +70,20 @@ function fromEnvelope(kind, raw, source) {
     // Send the original text so numeric tokens in arguments are not rewritten.
     return { body: text, value };
 }
+/** Add the flag without parsing and rewriting numeric tokens in the raw JSON body. */
+function withSessionId(kind, prepared, sessionId) {
+    if (sessionId === undefined)
+        return prepared;
+    validateSessionId(sessionId);
+    if (prepared.value.session_id !== undefined) {
+        throw usageError("session_id is already present in the JSON request; use either it or --session-id");
+    }
+    const value = { ...prepared.value, session_id: sessionId };
+    validateEnvelope(kind, value);
+    const separator = Object.keys(prepared.value).length > 0 ? "," : "";
+    const body = `${prepared.body.slice(0, -1)}${separator}"session_id":${JSON.stringify(sessionId)}}`;
+    return { body, value };
+}
 function buildSearch(operands, options) {
     if (operands.length !== 1 || !operands[0].trim()) {
         throw usageError("search requires a query, --input '<json>', or -f FILE");
@@ -79,6 +95,8 @@ function buildSearch(operands, options) {
     if (options.provider && options.provider.length > 0) {
         request.provider_filters = options.provider;
     }
+    if (options.sessionId !== undefined)
+        request.session_id = options.sessionId;
     validateEnvelope("search", request);
     return { body: JSON.stringify(request), value: request };
 }
@@ -98,6 +116,8 @@ function buildSchema(operands, options) {
     if (options.includeArgumentsSchema === false && options.includeResponseSchema !== true) {
         throw usageError("At least one of arguments or response schema must be requested");
     }
+    if (options.sessionId !== undefined)
+        request.session_id = options.sessionId;
     validateEnvelope("schema", request);
     return { body: JSON.stringify(request), value: request };
 }
@@ -111,11 +131,13 @@ function parseLimit(raw) {
     }
     return n;
 }
-const SEARCH_KEYS = ["query", "known_fields", "provider_filters", "limit"];
-const SCHEMA_KEYS = ["tools", "include_arguments_schema", "include_response_schema"];
-const BATCH_KEYS = ["search_id", "calls"];
+const SEARCH_KEYS = ["query", "known_fields", "provider_filters", "limit", "session_id"];
+const SCHEMA_KEYS = ["tools", "include_arguments_schema", "include_response_schema", "session_id"];
+const BATCH_KEYS = ["search_id", "calls", "session_id"];
 const CALL_KEYS = ["call_id", "tool", "arguments"];
 export function validateEnvelope(kind, value) {
+    if (value.session_id !== undefined)
+        validateSessionId(value.session_id);
     if (kind === "search") {
         rejectUnknownKeys(value, SEARCH_KEYS, "search request");
         if (typeof value.query !== "string" || value.query.trim().length === 0) {
@@ -197,6 +219,11 @@ export function validateEnvelope(kind, value) {
         throw usageError("call_id values must be unique within the batch");
     }
 }
+function validateSessionId(value) {
+    if (typeof value !== "string" || (value !== "" && !/^[A-Za-z0-9_-]{1,128}$/.test(value))) {
+        throw usageError("session_id must be a string of at most 128 letters, digits, underscores, or hyphens");
+    }
+}
 function rejectUnknownKeys(value, allowed, label) {
     const extra = Object.keys(value).filter((key) => !allowed.includes(key));
     if (extra.length > 0) {

package/dist/commands/tools.js

@@ -127,6 +127,9 @@ function renderHuman(kind, raw) {
         console.log(raw);
         return;
     }
+    if (typeof value.session_id === "string") {
+        console.log(`\n  ${chalk.gray("session_id")} ${value.session_id}`);
+    }
     if (kind === "search") {
         renderSearch(value);
         return;

package/dist/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.6.2";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */
 export declare const BASE_URL = "https://api.aisa.one";
 export declare const ENV_VAR_NAME = "AISA_API_KEY";

package/dist/constants.js

@@ -1,4 +1,4 @@
-export const VERSION = "0.6.0";
+export const VERSION = "0.6.2";
 /** Root of the platform. Per-surface bases are derived in api.ts#resolveBases. */
 export const BASE_URL = "https://api.aisa.one";
 export const ENV_VAR_NAME = "AISA_API_KEY";

package/dist/index.js

@@ -58,6 +58,7 @@ function routerIo(opts) {
     return {
         input: opts.input,
         file: opts.file,
+        sessionId: opts.sessionId,
         json: Boolean(opts.json),
         limit: opts.limit,
         provider: opts.provider,
@@ -111,6 +112,7 @@ program
     .option("-f, --file <path>", "Read JSON request from file, or - for stdin")
     .option("--limit <n>", "Max additional discovery results (1-20)")
     .option("--provider <id>", "Exact catalog provider key (repeatable)", collectProvider, [])
+    .option("--session-id <id>", "Reuse a session_id returned by an earlier search in this task")
     .option("--json", "Write the unmodified application response to stdout (MCP identifiers unchanged)")
     .addHelpText("after", searchHelpAfter())
     .action((query, opts) => wrap(searchAction)(query, routerIo(opts)));
@@ -121,6 +123,7 @@ program
     .option("-f, --file <path>", "Read JSON request from file, or - for stdin")
     .option("--no-arguments-schema", "Omit arguments_schema (at least one schema type is required)")
     .option("--include-response-schema", "Include response_schema")
+    .option("--session-id <id>", "Reuse the session_id returned by search for this task")
     .option("--json", "Write the unmodified application response to stdout (MCP identifiers unchanged)")
     .addHelpText("after", schemaHelpAfter())
     .action((tools, opts) => wrap(schemaAction)(tools, routerIo(opts)));
@@ -129,6 +132,7 @@ program
     .description("Quote published tools via the Tool Router without executing them (MCP AISA_BATCH_QUOTE)")
     .option("--input <json>", "Inline JSON request body, same shape as call (no file required)")
     .option("-f, --file <path>", "Read JSON request from file, or - for stdin")
+    .option("--session-id <id>", "Reuse the session_id returned by search for this task")
     .option("--json", "Write the unmodified application response to stdout (MCP identifiers unchanged)")
     .addHelpText("after", quoteHelpAfter())
     .action((opts) => wrap(quoteAction)(routerIo(opts)));
@@ -137,6 +141,7 @@ program
     .description("Execute published tools via the Tool Router (MCP AISA_BATCH_USE)")
     .option("--input <json>", "Inline JSON request body, same shape as quote (no file required)")
     .option("-f, --file <path>", "Read JSON request from file, or - for stdin")
+    .option("--session-id <id>", "Reuse the session_id returned by search for this task")
     .option("--json", "Write the unmodified application response to stdout (MCP identifiers unchanged)")
     .addHelpText("after", callHelpAfter())
     .action((opts) => wrap(callAction)(routerIo(opts)));

package/dist/skills-registry.js

@@ -21,7 +21,6 @@ const FETCH_CONCURRENCY = 8;
 function ghHeaders(etag) {
     const headers = {
         Accept: "application/vnd.github+json",
-        "User-Agent": "aisa-cli",
     };
     // Raises the rate limit from 60/hr to 5000/hr when the user has one set.
     const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;

package/dist/types.d.ts

@@ -29,6 +29,7 @@ export interface BalanceResponse {
     currency: string;
     account_balance_micros_usd: number;
     available_balance_micros_usd: number;
+    go_to_market_balance_micros_usd: number;
     api_key: {
         unlimited: boolean;
         remaining_micros_usd: number;

package/dist/utils/http.d.ts

@@ -35,6 +35,7 @@ export declare const MAX_ATTEMPTS = 3;
 export declare const INFO_TIMEOUT_MS = 10000;
 /** A normal authenticated API call. */
 export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const USER_AGENT = "aisa-cli";
 export interface HttpOptions extends RequestInit {
     timeoutMs?: number;
     /** Opt in to retries. See the note above: this must mean "safe to send

package/dist/utils/http.js

@@ -35,6 +35,7 @@ export const MAX_ATTEMPTS = 3;
 export const INFO_TIMEOUT_MS = 10_000;
 /** A normal authenticated API call. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
+export const USER_AGENT = "aisa-cli";
 const BASE_BACKOFF_MS = 300;
 /** Agents fan out many calls at once; identical backoff would resynchronise
  *  them into a second wave against a gateway that is already struggling. */
@@ -75,10 +76,18 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export async function httpFetch(url, options = {}) {
     const { timeoutMs = DEFAULT_TIMEOUT_MS, idempotent = false, maxAttempts, ...init } = options;
     const attempts = idempotent ? (maxAttempts ?? MAX_ATTEMPTS) : 1;
+    const headers = init.headers instanceof Headers || Array.isArray(init.headers)
+        ? Object.fromEntries(new Headers(init.headers))
+        : { ...(init.headers ?? {}) };
+    for (const name of Object.keys(headers)) {
+        if (name.toLowerCase() === "user-agent")
+            delete headers[name];
+    }
+    headers["User-Agent"] = USER_AGENT;
     let lastError;
     for (let attempt = 1; attempt <= attempts; attempt++) {
         try {
-            const res = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
+            const res = await fetch(url, { ...init, headers, signal: AbortSignal.timeout(timeoutMs) });
             if (attempt === attempts || !RETRYABLE_STATUS.has(res.status))
                 return res;
             const after = retryAfterMs(res);

package/dist/utils/update-check.js

@@ -1,6 +1,7 @@
 import { readCache, writeCache } from "../cache.js";
 import { VERSION } from "../constants.js";
 import { detectInstall } from "./install-method.js";
+import { httpFetch } from "./http.js";
 /**
  * Throttled, best-effort check for a newer published version.
  *
@@ -32,9 +33,7 @@ export function isNewer(candidate, current) {
     return false;
 }
 async function defaultFetchLatest() {
-    const res = await fetch(`https://registry.npmjs.org/${PACKAGE}/latest`, {
-        signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-    });
+    const res = await httpFetch(`https://registry.npmjs.org/${PACKAGE}/latest`, { timeoutMs: FETCH_TIMEOUT_MS });
     if (!res.ok)
         return undefined;
     const json = (await res.json());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aisa-one/cli",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "CLI for the AIsa unified AI infrastructure platform - one API key for 80+ LLMs and 900+ endpoints across finance, search, social, and video APIs",
   "type": "module",
   "main": "dist/index.js",