@cargo-ai/cli 1.0.17 → 1.0.18

package/build/commands/ai/mcpServer.js

@@ -30,13 +30,13 @@ Examples:
   $ cargo-ai ai mcp-server create --name "My Server"
   $ cargo-ai ai mcp-server create --name "My Server" \\
       --actions '[{"slug":"my-action","kind":"tool","name":null,"description":null,"isBulkAllowed":false,"config":{}}]' \\
-      --resources '[{"kind":"model","slug":"my-resource","name":"My Resource","description":null,"integrationSlug":"hubspot","modelUuid":null,"filter":null,"selectedColumnSlugs":null,"limit":null,"prompt":null}]'
+      --resources '[{"kind":"model","slug":"my-resource","name":"My Resource","description":null,"integrationSlug":"hubspot","modelUuid":null,"filter":null,"selectedColumnSlugs":null,"limit":null,"prompt":null,"isReadOnly":true}]'
 
 Action object shape:
   { "slug": string, "kind": "tool", "name": string | null, "description": string | null, "isBulkAllowed": boolean, "config": object }
 
 Resource object shapes:
-  Model:  { "kind": "model", "slug": string, "name": string, "description": string | null, "integrationSlug": string, "modelUuid": string | null, "filter": object | null, "selectedColumnSlugs": string[] | null, "limit": number | null, "prompt": string | null }
+  Model:  { "kind": "model", "slug": string, "name": string, "description": string | null, "integrationSlug": string, "modelUuid": string | null, "filter": object | null, "selectedColumnSlugs": string[] | null, "limit": number | null, "prompt": string | null, "isReadOnly": boolean }
   File:   { "kind": "file", "slug": string, "name": string, "description": string | null, "items": [{"kind":"file","fileUuid": string}], "prompt": string | null }`)
         .action(async (opts) => {
         const api = getApi();

package/build/commands/ai/memory.js

@@ -4,13 +4,13 @@ export function registerMemoryCommands(parent, getApi) {
     memory
         .command("list")
         .description("List memories")
-        .requiredOption("--scope <scope>", "Scope (workspace, user, agent)")
+        .requiredOption("--scope <scope>", "Scope (user, agent)")
         .option("--agent-uuid <uuid>", "Agent UUID (required when scope is agent)")
         .action(async (opts) => {
         const api = getApi();
         const payload = opts.scope === "agent"
             ? { scope: "agent", agentUuid: opts.agentUuid }
-            : { scope: opts.scope };
+            : { scope: "user" };
         const result = await handleApiCall(() => api.ai.memory.list(payload));
         outputJson(result);
     });
@@ -18,13 +18,13 @@ export function registerMemoryCommands(parent, getApi) {
         .command("remove")
         .description("Remove a memory")
         .requiredOption("--mem0-id <id>", "Memory ID")
-        .requiredOption("--scope <scope>", "Scope (workspace, user, agent)")
+        .requiredOption("--scope <scope>", "Scope (user, agent)")
         .option("--agent-uuid <uuid>", "Agent UUID (required when scope is agent)")
         .action(async (opts) => {
         const api = getApi();
         const scopePayload = opts.scope === "agent"
             ? { scope: "agent", agentUuid: opts.agentUuid }
-            : { scope: opts.scope };
+            : { scope: "user" };
         await handleApiCall(() => api.ai.memory.remove({ mem0Id: opts.mem0Id, ...scopePayload }));
         outputJson({ ok: true });
     });
@@ -33,13 +33,13 @@ export function registerMemoryCommands(parent, getApi) {
         .description("Update a memory")
         .requiredOption("--mem0-id <id>", "Memory ID")
         .requiredOption("--content <text>", "Memory content")
-        .requiredOption("--scope <scope>", "Scope (workspace, user, agent)")
+        .requiredOption("--scope <scope>", "Scope (user, agent)")
         .option("--agent-uuid <uuid>", "Agent UUID (required when scope is agent)")
         .action(async (opts) => {
         const api = getApi();
         const scopePayload = opts.scope === "agent"
             ? { scope: "agent", agentUuid: opts.agentUuid }
-            : { scope: opts.scope };
+            : { scope: "user" };
         const result = await handleApiCall(() => api.ai.memory.update({
             mem0Id: opts.mem0Id,
             content: opts.content,

package/build/commands/ai/message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAQxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAuLN"}
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAQxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAgMN"}

package/build/commands/ai/message.js

@@ -19,6 +19,7 @@ export function registerMessageCommands(parent, getApi) {
         .option("--integration-slug <slug>", "Integration slug (string)")
         .option("--connector-uuid <uuid>", "Connector UUID (string)")
         .option("--language-model-slug <slug>", "Language model slug (string)")
+        .option("--output <json>", 'Output format for the assistant message (JSON object, e.g. \'{"type":"text"}\' or \'{"type":"jsonSchema","jsonSchema":{...}}\'). Defaults to text when omitted.')
         .option("--wait-until-finished", "Poll the assistant message until finished before returning (boolean flag)")
         .option("--polling-interval <ms>", "Polling interval in milliseconds, used with --wait-until-finished (integer, default: 5000)", "5000")
         .addHelpText("after", `
@@ -59,6 +60,9 @@ MCP client shape:      { "name": string, "url": string }`)
             integrationSlug: opts.integrationSlug,
             connectorUuid: opts.connectorUuid,
             languageModelSlug: opts.languageModelSlug,
+            output: opts.output !== undefined
+                ? parseJson(opts.output, "--output")
+                : undefined,
         }));
         if (opts.waitUntilFinished === true) {
             const intervalMs = parseInt(opts.pollingInterval, 10);

package/build/commands/ai/release.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/release.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAwRN"}
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../../src/commands/ai/release.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAqSN"}

package/build/commands/ai/release.js

@@ -68,6 +68,16 @@ export function registerReleaseCommands(parent, getApi) {
         .option("--capabilities <json>", "Capabilities to enable (JSON array of capability objects)")
         .option("--suggested-actions <json>", "Suggested actions for the chat UI (JSON array of action objects)")
         .option("--options <json>", "Additional options (JSON object)")
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai ai release update-draft --agent-uuid <uuid> \\
+      --resources '[{"kind":"model","slug":"my-resource","name":"My Resource","description":null,"integrationSlug":"hubspot","modelUuid":null,"filter":null,"selectedColumnSlugs":null,"limit":null,"prompt":null,"isReadOnly":true}]'
+
+Resource object shapes:
+  Model:  { "kind": "model", "slug": string, "name": string, "description": string | null, "integrationSlug": string, "modelUuid": string | null, "filter": object | null, "selectedColumnSlugs": string[] | null, "limit": number | null, "prompt": string | null, "isReadOnly": boolean }
+  File:   { "kind": "file", "slug": string, "name": string, "description": string | null, "items": [{"kind":"file","fileUuid": string}], "prompt": string | null }
+
+Set "isReadOnly": false on a model resource to grant the agent write tools (insert/update/upsert/delete/custom columns).`)
         .action(async (opts) => {
         const api = getApi();
         const result = await handleApiCall(() => api.ai.release.updateDraft({

package/build/commands/orchestration/action.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AASxC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAmIN"}
+{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../../../src/commands/orchestration/action.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AASxC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CA8JN"}

package/build/commands/orchestration/action.js

@@ -61,4 +61,20 @@ Examples:
         }
         outputJson(result);
     });
+    action
+        .command("get-output-schema")
+        .description("Resolve the JSON schema of an action's data output without executing it")
+        .requiredOption("--action <json>", 'Action definition (JSON object, required). Example: \'{"kind":"tool","toolUuid":"550e8400-...","config":{}}\'')
+        .addHelpText("after", `
+Examples:
+  $ cargo-ai orchestration action get-output-schema --action '{"kind":"tool","toolUuid":"550e8400-...","config":{}}'
+  $ cargo-ai orchestration action get-output-schema --action '{"kind":"connector","integrationSlug":"clearbit","actionSlug":"company_enrich","config":{}}'`)
+        .action(async (opts) => {
+        const actionPayload = parseJson(opts.action, "--action");
+        const api = getApi();
+        const result = await handleApiCall(() => api.orchestration.action.getOutputSchema({
+            action: actionPayload,
+        }));
+        outputJson(result);
+    });
 }

package/build/commands/version.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerVersionCommand(parent: Command, currentVersion: string): void;
+//# sourceMappingURL=version.d.ts.map

package/build/commands/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/commands/version.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAOzC,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,MAAM,GACrB,IAAI,CAoCN"}

package/build/commands/version.js

@@ -0,0 +1,29 @@
+import { fetchLatestVersion, isOutdated, UPDATE_COMMAND } from "../version.js";
+import { failWith, outputJson } from "./runHandler.js";
+const CHECK_FETCH_TIMEOUT_MS = 5000;
+export function registerVersionCommand(parent, currentVersion) {
+    parent
+        .command("version")
+        .description("Print the installed CLI version, or check npm for a newer release with --check")
+        .option("--check", "Query the npm registry and report whether a newer version is available")
+        .action(async (opts) => {
+        if (opts.check !== true) {
+            outputJson({ version: currentVersion });
+            return;
+        }
+        let latest;
+        try {
+            latest = await fetchLatestVersion(CHECK_FETCH_TIMEOUT_MS);
+        }
+        catch (error) {
+            failWith(`Could not reach the npm registry to check for updates: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const upToDate = isOutdated(currentVersion, latest) === false;
+        outputJson({
+            current: currentVersion,
+            latest,
+            upToDate,
+            updateCommand: upToDate ? undefined : UPDATE_COMMAND,
+        });
+    });
+}

package/build/commands/workspaceManagement/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/workspaceManagement/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AASxC,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAYN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/workspaceManagement/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAUxC,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAeN"}

package/build/commands/workspaceManagement/index.js

@@ -2,13 +2,14 @@ import { registerFileCommands } from "./file.js";
 import { registerFolderCommands } from "./folder.js";
 import { registerReportCommands } from "./report.js";
 import { registerRoleCommands } from "./role.js";
+import { registerSessionCommands } from "./session.js";
 import { registerTokenCommands } from "./token.js";
 import { registerUserCommands } from "./user.js";
 import { registerWorkspacesCommands } from "./workspaces.js";
 export function registerWorkspaceManagementCommands(parent, getApi) {
     const workspaceManagement = parent
         .command("workspaceManagement")
-        .description("Workspaces, users, tokens, roles, folders, reports");
+        .description("Workspaces, users, tokens, roles, folders, reports, sessions");
     registerWorkspacesCommands(workspaceManagement, getApi);
     registerUserCommands(workspaceManagement, getApi);
     registerTokenCommands(workspaceManagement, getApi);
@@ -16,4 +17,5 @@ export function registerWorkspaceManagementCommands(parent, getApi) {
     registerFolderCommands(workspaceManagement, getApi);
     registerFileCommands(workspaceManagement, getApi);
     registerReportCommands(workspaceManagement, getApi);
+    registerSessionCommands(workspaceManagement, getApi);
 }

package/build/commands/workspaceManagement/session.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { Api } from "../../api.js";
+export declare function registerSessionCommands(parent: Command, getApi: () => Api): void;
+//# sourceMappingURL=session.d.ts.map

package/build/commands/workspaceManagement/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/commands/workspaceManagement/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAGxC,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GAAG,GAChB,IAAI,CAiDN"}

package/build/commands/workspaceManagement/session.js

@@ -0,0 +1,31 @@
+import { handleApiCall, outputJson } from "../runHandler.js";
+export function registerSessionCommands(parent, getApi) {
+    const session = parent
+        .command("session")
+        .description("Claude Code session tracking");
+    session
+        .command("upsert")
+        .description("Create or update a Claude Code session")
+        .requiredOption("--session-id <sessionId>", "Claude Code session id")
+        .requiredOption("--title <title>", "Short title for the session")
+        .requiredOption("--summary <summary>", "Summary of what happened in the session")
+        .option("--finished", "Mark the session as finished now (sets finishedAt = now)")
+        .option("--finished-at <timestamp>", "Explicit ISO timestamp for when the session finished")
+        .action(async (opts) => {
+        let finishedAt;
+        if (opts.finishedAt !== undefined) {
+            finishedAt = opts.finishedAt;
+        }
+        else if (opts.finished === true) {
+            finishedAt = new Date().toISOString();
+        }
+        const api = getApi();
+        const result = await handleApiCall(() => api.workspaceManagement.session.upsert({
+            sessionId: opts.sessionId,
+            title: opts.title,
+            summary: opts.summary,
+            finishedAt,
+        }));
+        outputJson(result);
+    });
+}

package/build/credentials.d.ts

@@ -7,4 +7,5 @@ export declare function loadCredentials(): Credentials | undefined;
 export declare function saveCredentials(creds: Credentials): void;
 export declare function clearCredentials(): boolean;
 export declare function getCredentialsPath(): string;
+export declare function getConfigDir(): string;
 //# sourceMappingURL=credentials.d.ts.map

package/build/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAKF,wBAAgB,eAAe,IAAI,WAAW,GAAG,SAAS,CAQzD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAKxD;AAED,wBAAgB,gBAAgB,IAAI,OAAO,CAI1C;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAKF,wBAAgB,eAAe,IAAI,WAAW,GAAG,SAAS,CAQzD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAKxD;AAED,wBAAgB,gBAAgB,IAAI,OAAO,CAI1C;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAErC"}

package/build/credentials.js

@@ -29,3 +29,6 @@ export function clearCredentials() {
 export function getCredentialsPath() {
     return CREDENTIALS_FILE;
 }
+export function getConfigDir() {
+    return CONFIG_DIR;
+}

package/build/index.js

@@ -17,8 +17,10 @@ import { registerSegmentationCommands } from "./commands/segmentation/index.js";
 import { registerStorageCommands } from "./commands/storage/index.js";
 import { registerSystemOfRecordIntegrationCommands } from "./commands/systemOfRecordIntegration/index.js";
 import { registerUserManagementCommands } from "./commands/userManagement/index.js";
+import { registerVersionCommand } from "./commands/version.js";
 import { registerWorkspaceManagementCommands } from "./commands/workspaceManagement/index.js";
 import { getConfig } from "./config.js";
+import { maybeNotifyUpdate } from "./updateNotifier.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../package.json");
 const program = new Command();
@@ -53,6 +55,7 @@ const getApi = () => {
     return createApi({ baseUrl, accessToken, workspaceUuid });
 };
 registerAuthCommands(program, getApi);
+registerVersionCommand(program, version);
 registerInitCommand(program, getApi);
 registerOrchestrationCommands(program, getApi);
 registerWorkspaceManagementCommands(program, getApi);
@@ -67,6 +70,9 @@ registerSystemOfRecordIntegrationCommands(program, getApi);
 registerUserManagementCommands(program, getApi);
 registerAiCommands(program, getApi);
 registerHostingCommands(program, getApi);
-program.parseAsync().catch((err) => {
+program
+    .parseAsync()
+    .then(() => maybeNotifyUpdate(version))
+    .catch((err) => {
     failWith(err instanceof Error ? err.message : String(err));
 });

package/build/updateNotifier.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Best-effort "update available" nudge, printed to stderr after a command's
+ * own output. The registry is checked at most once per 24h (result cached in
+ * the config dir). Stays silent on non-TTY stderr (scripts/CI), when disabled
+ * via CARGO_NO_UPDATE_NOTIFIER, and on any network/parse failure — it must
+ * never block, delay, or break the command that triggered it.
+ */
+export declare function maybeNotifyUpdate(currentVersion: string): Promise<void>;
+//# sourceMappingURL=updateNotifier.d.ts.map

package/build/updateNotifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateNotifier.d.ts","sourceRoot":"","sources":["../src/updateNotifier.ts"],"names":[],"mappings":"AAmBA;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B7E"}

package/build/updateNotifier.js

@@ -0,0 +1,38 @@
+import { colors, info } from "./commands/runHandler.js";
+import { fetchLatestVersion, isOutdated, readUpdateCache, UPDATE_COMMAND, writeUpdateCache, } from "./version.js";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000; // once per day
+const NOTIFY_FETCH_TIMEOUT_MS = 1500;
+const isDisabled = () => {
+    const flag = process.env["CARGO_NO_UPDATE_NOTIFIER"];
+    return (flag === "1" || flag === "true" || process.env["NO_UPDATE_NOTIFIER"] === "1");
+};
+/**
+ * Best-effort "update available" nudge, printed to stderr after a command's
+ * own output. The registry is checked at most once per 24h (result cached in
+ * the config dir). Stays silent on non-TTY stderr (scripts/CI), when disabled
+ * via CARGO_NO_UPDATE_NOTIFIER, and on any network/parse failure — it must
+ * never block, delay, or break the command that triggered it.
+ */
+export async function maybeNotifyUpdate(currentVersion) {
+    // Only nudge interactive users; never pollute scripted/CI stderr.
+    if (process.stderr.isTTY !== true)
+        return;
+    if (isDisabled())
+        return;
+    try {
+        let cache = readUpdateCache();
+        const now = Date.now();
+        if (cache === undefined || now - cache.lastCheck > CHECK_INTERVAL_MS) {
+            const latestVersion = await fetchLatestVersion(NOTIFY_FETCH_TIMEOUT_MS);
+            cache = { lastCheck: now, latestVersion };
+            writeUpdateCache(cache);
+        }
+        if (isOutdated(currentVersion, cache.latestVersion)) {
+            info(`${colors.yellow("⚠")} A new version of cargo-ai is available: ${colors.dim(currentVersion)} → ${colors.green(cache.latestVersion)}`);
+            info(`  Update with: ${colors.cyan(UPDATE_COMMAND)}`);
+        }
+    }
+    catch {
+        // Fail open: an update check must never get in the way of the command.
+    }
+}

package/build/version.d.ts

@@ -0,0 +1,25 @@
+export declare const UPDATE_COMMAND = "npm install -g @cargo-ai/cli@latest";
+export type UpdateCache = {
+    /** Epoch milliseconds of the last successful registry check. */
+    lastCheck: number;
+    /** Latest version reported by the npm registry at that time. */
+    latestVersion: string;
+};
+/**
+ * Fetch the latest published version of the CLI from the npm registry.
+ * Throws on network error, timeout, or unexpected response shape — callers
+ * decide whether to surface or swallow the failure.
+ */
+export declare function fetchLatestVersion(timeoutMs?: number): Promise<string>;
+/**
+ * Compare two semver-ish strings. Returns 1 if `a > b`, -1 if `a < b`, 0 if
+ * equal. Only the major.minor.patch core is compared numerically; a version
+ * carrying a prerelease tag (e.g. `1.2.0-beta.1`) ranks below the same core
+ * without one, matching semver precedence rules.
+ */
+export declare function compareSemver(a: string, b: string): number;
+/** True when `current` is strictly older than `latest`. */
+export declare function isOutdated(current: string, latest: string): boolean;
+export declare function readUpdateCache(): UpdateCache | undefined;
+export declare function writeUpdateCache(cache: UpdateCache): void;
+//# sourceMappingURL=version.d.ts.map

package/build/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,cAAc,wCAAwC,CAAC;AAEpE,MAAM,MAAM,WAAW,GAAG;IACxB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,GAAE,MAAiC,GAC3C,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA2B1D;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wBAAgB,eAAe,IAAI,WAAW,GAAG,SAAS,CAsBzD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAOzD"}

package/build/version.js

@@ -0,0 +1,91 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "./credentials.js";
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/@cargo-ai/cli/latest";
+const DEFAULT_FETCH_TIMEOUT_MS = 1500;
+const UPDATE_CACHE_FILE = join(getConfigDir(), "update-check.json");
+export const UPDATE_COMMAND = "npm install -g @cargo-ai/cli@latest";
+/**
+ * Fetch the latest published version of the CLI from the npm registry.
+ * Throws on network error, timeout, or unexpected response shape — callers
+ * decide whether to surface or swallow the failure.
+ */
+export async function fetchLatestVersion(timeoutMs = DEFAULT_FETCH_TIMEOUT_MS) {
+    const response = await fetch(NPM_REGISTRY_URL, {
+        signal: AbortSignal.timeout(timeoutMs),
+        headers: { accept: "application/json" },
+    });
+    if (response.ok === false) {
+        throw new Error(`npm registry returned HTTP ${response.status}`);
+    }
+    const body = (await response.json());
+    if (typeof body.version !== "string") {
+        throw new Error("npm registry response did not include a version");
+    }
+    return body.version;
+}
+/**
+ * Compare two semver-ish strings. Returns 1 if `a > b`, -1 if `a < b`, 0 if
+ * equal. Only the major.minor.patch core is compared numerically; a version
+ * carrying a prerelease tag (e.g. `1.2.0-beta.1`) ranks below the same core
+ * without one, matching semver precedence rules.
+ */
+export function compareSemver(a, b) {
+    const parse = (v) => {
+        const clean = v.trim().replace(/^v/, "");
+        const [core = "", pre = ""] = clean.split("-", 2);
+        const nums = core.split(".").map((n) => {
+            const parsed = Number.parseInt(n, 10);
+            return Number.isNaN(parsed) ? 0 : parsed;
+        });
+        return { nums: [nums[0] ?? 0, nums[1] ?? 0, nums[2] ?? 0], pre };
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i += 1) {
+        const na = pa.nums[i] ?? 0;
+        const nb = pb.nums[i] ?? 0;
+        if (na !== nb) {
+            return na > nb ? 1 : -1;
+        }
+    }
+    if (pa.pre === pb.pre)
+        return 0;
+    // A version without a prerelease tag outranks one that has it.
+    if (pa.pre === "")
+        return 1;
+    if (pb.pre === "")
+        return -1;
+    return pa.pre > pb.pre ? 1 : -1;
+}
+/** True when `current` is strictly older than `latest`. */
+export function isOutdated(current, latest) {
+    return compareSemver(current, latest) < 0;
+}
+export function readUpdateCache() {
+    if (existsSync(UPDATE_CACHE_FILE) === false)
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(UPDATE_CACHE_FILE, "utf-8"));
+        if (typeof parsed.lastCheck === "number" &&
+            typeof parsed.latestVersion === "string") {
+            return {
+                lastCheck: parsed.lastCheck,
+                latestVersion: parsed.latestVersion,
+            };
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeUpdateCache(cache) {
+    try {
+        mkdirSync(getConfigDir(), { recursive: true });
+        writeFileSync(UPDATE_CACHE_FILE, JSON.stringify(cache, null, 2) + "\n");
+    }
+    catch {
+        // Best-effort cache: a write failure should never break a command.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cargo-ai/cli",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "private": false,
   "description": "Command-line interface for the Cargo API",
   "engines": {
@@ -28,9 +28,9 @@
     "format:check": "prettier --check ."
   },
   "dependencies": {
-    "@cargo-ai/api": "^1.0.25",
+    "@cargo-ai/api": "^1.0.26",
     "@cargo-ai/app-sdk": "^1.0.0",
-    "@cargo-ai/worker-sdk": "^1.0.0",
+    "@cargo-ai/worker-sdk": "^1.0.1",
     "commander": "^12.1.0"
   },
   "devDependencies": {