@native-marketing/sdk 0.3.6 → 0.3.7

package/dist/index.js

@@ -7598,6 +7598,176 @@ function capabilityStatusRead(name, input) {
   };
 }
 
+// packages/contracts/src/client-lifecycle.ts
+import { z as z104 } from "zod";
+
+// packages/contracts/src/generated/client-release.ts
+var nativeClientRelease = {
+  schemaVersion: 1,
+  product: "native-marketing",
+  version: "0.3.7",
+  packages: {
+    sdk: "@native-marketing/sdk",
+    cli: "@native-marketing/cli"
+  },
+  contractVersion: 1,
+  minimumClientVersion: "0.3.6",
+  apiMajor: 1,
+  nodeMajor: 24,
+  changes: [
+    "Unified SDK, CLI and MCP release discovery and compatibility checks.",
+    "Configurable CLI update notifications, pins and compatible automatic updates.",
+    "Upgrade verification and explicit continuation without replaying business commands."
+  ]
+};
+
+// packages/contracts/src/client-lifecycle.ts
+var nativeReleaseCapability = "com.native-marketing/client-release";
+var releaseVersionSchema = z104.string().max(128).regex(
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
+);
+var clientIdentitySchema = z104.object({
+  version: releaseVersionSchema,
+  contractVersion: z104.number().int().positive(),
+  apiMajor: z104.number().int().positive()
+});
+var clientReleaseSchema = z104.object({
+  schemaVersion: z104.literal(1),
+  product: z104.literal("native-marketing"),
+  version: releaseVersionSchema,
+  packages: z104.object({
+    sdk: z104.literal("@native-marketing/sdk"),
+    cli: z104.literal("@native-marketing/cli")
+  }),
+  contractVersion: z104.number().int().positive(),
+  minimumClientVersion: releaseVersionSchema,
+  apiMajor: z104.number().int().positive(),
+  nodeMajor: z104.number().int().positive(),
+  changes: z104.array(z104.string().min(1).max(240)).max(8).default([])
+});
+var updatePolicySchema = z104.object({
+  mode: z104.enum(["off", "notify", "auto"]).default("notify"),
+  channel: z104.enum(["latest", "next", "beta"]).default("latest"),
+  pin: releaseVersionSchema.nullable().default(null),
+  intervalHours: z104.number().int().min(1).max(168).default(24)
+}).strict();
+var defaultUpdatePolicy = updatePolicySchema.parse({});
+function compareReleaseVersions(left, right) {
+  const parse = (raw) => releaseVersionSchema.parse(raw).split("+")[0].split(/-(.*)/s);
+  const a = parse(left), b = parse(right);
+  const numbers = (x, y) => BigInt(x) < BigInt(y) ? -1 : BigInt(x) > BigInt(y) ? 1 : 0;
+  const ac = a[0].split("."), bc = b[0].split(".");
+  for (let i = 0; i < 3; i++) {
+    const order = numbers(ac[i], bc[i]);
+    if (order) return order;
+  }
+  if (a[1] === b[1]) return 0;
+  if (!a[1] || !b[1]) return a[1] ? -1 : 1;
+  const ap = a[1].split("."), bp = b[1].split(".");
+  for (let i = 0; i < Math.max(ap.length, bp.length); i++) {
+    const x = ap[i], y = bp[i];
+    if (x === void 0 || y === void 0) return x === void 0 ? -1 : 1;
+    if (x === y) continue;
+    const xn = /^\d+$/.test(x), yn = /^\d+$/.test(y);
+    return xn && yn ? numbers(x, y) : xn !== yn ? xn ? -1 : 1 : x < y ? -1 : 1;
+  }
+  return 0;
+}
+function assessNativeCompatibility(client, server) {
+  client = clientIdentitySchema.parse(client);
+  const result2 = (status, reason) => ({ status, reason, client, server: server ?? null });
+  if (!server) return result2("UNKNOWN", "SERVER_METADATA_UNAVAILABLE");
+  server = clientReleaseSchema.parse(server);
+  if (client.contractVersion !== server.contractVersion)
+    return result2("INCOMPATIBLE", "CONTRACT_MISMATCH");
+  if (client.apiMajor !== server.apiMajor) return result2("INCOMPATIBLE", "API_MISMATCH");
+  if (compareReleaseVersions(client.version, server.minimumClientVersion) < 0)
+    return result2("INCOMPATIBLE", "CLIENT_TOO_OLD");
+  return compareReleaseVersions(client.version, server.version) < 0 ? result2("UPGRADE_RECOMMENDED", "NEWER_CLIENT_AVAILABLE") : result2("COMPATIBLE", "CURRENT");
+}
+
+// packages/contracts/src/client-update-policy.ts
+import { z as z105 } from "zod";
+var registryReleaseSchema = z105.object({
+  name: z105.enum(["@native-marketing/sdk", "@native-marketing/cli"]),
+  version: releaseVersionSchema,
+  deprecated: z105.string().optional(),
+  nativeMarketing: z105.object({
+    contractVersion: z105.number().int().positive(),
+    apiMajor: z105.number().int().positive(),
+    nodeMajor: z105.number().int().positive(),
+    changes: z105.array(z105.string().min(1).max(240)).max(8).optional()
+  }).optional(),
+  dist: z105.object({
+    integrity: z105.string().max(512).regex(/^sha512-[A-Za-z0-9+/]{86}==$/)
+  })
+});
+var clientUpdateStateSchema = z105.object({
+  schemaVersion: z105.literal(1),
+  policy: updatePolicySchema,
+  lastCheck: z105.object({
+    at: z105.number().int().nonnegative(),
+    selector: z105.string().max(160),
+    target: registryReleaseSchema
+  }).strict().optional(),
+  lastAttempt: z105.object({ at: z105.number().int().nonnegative(), selector: z105.string().max(160) }).strict().optional()
+}).strict();
+function planNativeUpdate(input) {
+  const target = registryReleaseSchema.parse(input.target);
+  const current = releaseVersionSchema.parse(input.currentVersion ?? nativeClientRelease.version);
+  const policy = updatePolicySchema.parse(input.policy ?? {});
+  const spec = `${target.name}@${target.version}`;
+  const cli = target.name === nativeClientRelease.packages.cli;
+  const result2 = (status, reason, eligible = false) => ({
+    package: target.name,
+    currentVersion: current,
+    targetVersion: target.version,
+    status,
+    reason,
+    eligibleForAutoUpdate: eligible,
+    policy,
+    commands: {
+      npm: [
+        "npm",
+        "install",
+        ...cli ? ["--global"] : ["--save-exact"],
+        spec,
+        "--ignore-scripts",
+        "--registry=https://registry.npmjs.org/",
+        "--@native-marketing:registry=https://registry.npmjs.org/"
+      ],
+      pnpm: ["pnpm", "add", ...cli ? ["--global"] : ["--save-exact"], spec, "--ignore-scripts"],
+      yarn: cli ? null : ["yarn", "add", "--exact", spec]
+    }
+  });
+  if (policy.pin && policy.pin !== target.version) return result2("BLOCKED", "PIN_MISMATCH");
+  if (!policy.pin && policy.channel === "latest" && target.version.split("+")[0].includes("-"))
+    return result2("BLOCKED", "CHANNEL_MISMATCH");
+  const order = compareReleaseVersions(target.version, current);
+  if (order < 0) return result2("BLOCKED", "DOWNGRADE_FORBIDDEN");
+  if (target.deprecated !== void 0) return result2("BLOCKED", "DEPRECATED");
+  if (!target.nativeMarketing) return result2("BLOCKED", "METADATA_UNAVAILABLE");
+  const metadata = target.nativeMarketing;
+  if (metadata.nodeMajor !== (input.nodeMajor ?? nativeClientRelease.nodeMajor))
+    return result2("BLOCKED", "NODE_MISMATCH");
+  if (metadata.contractVersion !== nativeClientRelease.contractVersion || metadata.apiMajor !== nativeClientRelease.apiMajor)
+    return result2("BLOCKED", "CONTRACT_MISMATCH");
+  if (input.server && assessNativeCompatibility(
+    {
+      version: target.version,
+      contractVersion: metadata.contractVersion,
+      apiMajor: metadata.apiMajor
+    },
+    input.server
+  ).status === "INCOMPATIBLE")
+    return result2("BLOCKED", "SERVER_INCOMPATIBLE");
+  if (order === 0) return result2("CURRENT", "CURRENT");
+  const from = current.split(/[.+-]/), to = target.version.split(/[.+-]/);
+  const compatibleLine = from[0] === to[0] && (from[0] !== "0" || from[1] === to[1]);
+  const stable = !current.split("+")[0].includes("-") && !target.version.split("+")[0].includes("-");
+  return compatibleLine && stable ? result2("UPDATE_AVAILABLE", "COMPATIBLE_UPDATE", true) : result2("UPDATE_AVAILABLE", "REVIEW_REQUIRED");
+}
+
 // packages/cli-client/src/errors.ts
 var CliError = class extends Error {
   constructor(code2, message, outcome = "NOT_SENT", details) {
@@ -7650,6 +7820,9 @@ function verifyCapabilityDefinition(raw, name, expectedHash) {
 }
 var CapabilityDefinitionCache = class {
   values = /* @__PURE__ */ new Map();
+  clear() {
+    this.values.clear();
+  }
   remember(value) {
     const verified = verifyCapabilityDefinition(value, value.definition.name);
     const key2 = `${verified.definition.name}:AGENT_V3:${verified.schemaSha256}`;
@@ -7988,13 +8161,105 @@ function object2(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 
+// packages/cli-client/src/updates/version.ts
+import { readFile, realpath } from "node:fs/promises";
+import { dirname, join as join2 } from "node:path";
+function getNativeClientVersion() {
+  return clientReleaseSchema.parse(nativeClientRelease);
+}
+async function getNativeCliVersion(executablePath) {
+  const identity = { ...getNativeClientVersion(), sdkVersion: nativeClientRelease.version };
+  if (!executablePath) return identity;
+  try {
+    const root = dirname(dirname(await realpath(executablePath)));
+    const manifest = JSON.parse(await readFile(join2(root, "package.json"), "utf8"));
+    if (manifest.name === nativeClientRelease.packages.cli)
+      return { ...identity, version: releaseVersionSchema.parse(manifest.version) };
+  } catch {
+  }
+  return identity;
+}
+function readNativeServerVersion(client) {
+  const raw = client.getServerCapabilities()?.experimental?.[nativeReleaseCapability];
+  let server;
+  if (raw !== void 0) {
+    const parsed = clientReleaseSchema.safeParse(raw);
+    if (!parsed.success)
+      throw new CliError(
+        "INVALID_SERVER_RELEASE",
+        "The advertised Native Marketing release contract is invalid."
+      );
+    server = parsed.data;
+  }
+  return {
+    client: getNativeClientVersion(),
+    serverInfo: client.getServerVersion() ?? null,
+    mcpProtocolVersion: client.getNegotiatedProtocolVersion() ?? null,
+    compatibility: assessNativeCompatibility(nativeClientRelease, server)
+  };
+}
+function assertNativeCompatibility(result2, required = false) {
+  if (result2.compatibility.status === "INCOMPATIBLE" || required && result2.compatibility.status === "UNKNOWN")
+    throw new CliError(
+      "CLIENT_INCOMPATIBLE",
+      "Check version --server and update the client or connect to a compatible service. No business operation was sent.",
+      "NOT_SENT",
+      { compatibility: result2.compatibility }
+    );
+}
+async function refreshNativeServerVersion(client, timeout) {
+  const reply = await client.callTool(
+    { name: "cf_get_client_release", arguments: {} },
+    {
+      timeout,
+      allowInputRequired: true,
+      toolDefinition: {
+        name: "cf_get_client_release",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        annotations: { readOnlyHint: true }
+      }
+    }
+  ).catch(() => {
+    throw new CliError(
+      "VERSION_CHECK_UNAVAILABLE",
+      "Cannot refresh the service release. Reconnect or refresh again before continuing."
+    );
+  });
+  const text3 = reply.content?.find((item) => item.type === "text");
+  let server;
+  try {
+    if (reply.isError) throw new Error();
+    server = clientReleaseSchema.parse(
+      reply.structuredContent ?? (text3?.type === "text" ? JSON.parse(text3.text) : null)
+    );
+  } catch {
+    throw new CliError("INVALID_SERVER_RELEASE", "Cannot verify the current server release.");
+  }
+  const result2 = {
+    ...readNativeServerVersion(client),
+    compatibility: assessNativeCompatibility(nativeClientRelease, server)
+  };
+  return result2;
+}
+
 // packages/cli-client/src/transport.ts
-async function withClient(profile, timeout, operation) {
+async function withClient(profile, timeout, operation, options = {}) {
   const resource = resourceUrl(profile.resource);
   const accessToken = tokenText(profile.accessToken);
   const client = new Client(
-    { name: "content-factory-agent-cli", version: "0.1.0" },
-    { inputRequired: { autoFulfill: false } }
+    { name: "@native-marketing/sdk", version: nativeClientRelease.version },
+    {
+      inputRequired: { autoFulfill: false },
+      capabilities: {
+        experimental: {
+          [nativeReleaseCapability]: {
+            version: nativeClientRelease.version,
+            contractVersion: nativeClientRelease.contractVersion,
+            apiMajor: nativeClientRelease.apiMajor
+          }
+        }
+      }
+    }
   );
   const transport = new StreamableHTTPClientTransport(resource, {
     authProvider: { token: async () => accessToken },
@@ -8015,6 +8280,10 @@ async function withClient(profile, timeout, operation) {
         "Cannot authenticate/connect to the configured CF resource. No business operation was sent."
       );
     }
+    const version = readNativeServerVersion(client);
+    if (!options.allowIncompatible)
+      assertNativeCompatibility(version, options.requireCompatibility);
+    options.onVersion?.(version);
     return await operation(client);
   } finally {
     await client.close().catch(() => void 0);
@@ -8882,43 +9151,97 @@ async function withNativeAgentClient(connection, action, options = {}) {
   return withClient(
     connection,
     timeout,
-    (client) => action({
-      readPackageFile: (input) => readNativePackageFile(connection, input, timeout),
-      readProjectMediaFile: (input) => readNativeProjectMediaFile(connection, input, timeout),
-      uploadProjectMedia: (file) => uploadNativeProjectMedia(connection, file, timeout),
-      uploadMaterial: (file) => uploadNativeMaterial(connection, file, timeout),
-      inspectTool: (name) => inspectNativeTool(client, name, timeout, definitions),
-      callTool: (name, input = {}, options2) => callNativeTool(client, name, input, connection.resource, options2, timeout, definitions),
-      listToolsPage: (input = {}) => listNativeToolsPage(client, input, timeout),
-      readCapabilitySchemaPage: (input) => readNativeCapabilitySchemaPage(client, input, timeout),
-      readDocumentPage: (input) => readNativeDocumentPage(client, input, timeout),
-      getBusinessSummary: (input) => getNativeBusinessSummary(client, input, timeout),
-      callCapability: (input) => callNativeCapability(client, input, timeout),
-      readCapability: (input) => readNativeCapability(client, input, timeout),
-      writeCapability: (input) => writeNativeCapability(client, input, timeout),
-      describeCapabilitySummary: (name) => readNativeCapabilityDescriptor(client, name, timeout),
-      searchBusiness: (input) => searchNativeBusiness(client, input, timeout),
-      readBusinessPage: (input) => readNativeBusinessPage(client, input, timeout),
-      findCapabilities: (input) => findNativeCapabilities(client, input, timeout),
-      discoverCapabilities: async (input) => {
-        const page2 = await findAgentCapabilities(client, input, timeout);
-        for (const item of page2.items) if (item.definition) definitions.remember(item.definition);
-        return page2;
-      },
-      describeCapability: async (name, expectedHash) => {
-        const cached = expectedHash ? definitions.get(name, expectedHash) : void 0;
-        if (cached) return cached;
-        const definition = await describeNativeCapability(client, name, timeout);
-        if (expectedHash && definition.schemaSha256 !== expectedHash)
-          throw new CliError(
-            "CAPABILITY_SCHEMA_CHANGED",
-            "Discover the current definition again.",
-            "REJECTED"
-          );
-        definitions.remember(definition);
-        return definition;
-      }
-    })
+    (client) => {
+      let version = readNativeServerVersion(client);
+      let versionUnverified = false;
+      client.setNotificationHandler("notifications/tools/list_changed", () => {
+        definitions.clear();
+      });
+      return action(
+        new Proxy(
+          {
+            getVersion: () => structuredClone(version),
+            refreshVersion: async () => {
+              definitions.clear();
+              try {
+                version = await refreshNativeServerVersion(client, timeout);
+                versionUnverified = false;
+              } catch (error) {
+                version = { ...version, compatibility: assessNativeCompatibility(version.client) };
+                versionUnverified = true;
+                throw error;
+              }
+              assertNativeCompatibility(version, options.requireCompatibility);
+              options.onVersion?.(version);
+              return structuredClone(version);
+            },
+            readPackageFile: (input) => readNativePackageFile(connection, input, timeout),
+            readProjectMediaFile: (input) => readNativeProjectMediaFile(connection, input, timeout),
+            uploadProjectMedia: (file) => uploadNativeProjectMedia(connection, file, timeout),
+            uploadMaterial: (file) => uploadNativeMaterial(connection, file, timeout),
+            inspectTool: (name) => inspectNativeTool(client, name, timeout, definitions),
+            callTool: (name, input = {}, options2) => callNativeTool(
+              client,
+              name,
+              input,
+              connection.resource,
+              options2,
+              timeout,
+              definitions
+            ),
+            listToolsPage: (input = {}) => listNativeToolsPage(client, input, timeout),
+            readCapabilitySchemaPage: (input) => readNativeCapabilitySchemaPage(client, input, timeout),
+            readDocumentPage: (input) => readNativeDocumentPage(client, input, timeout),
+            getBusinessSummary: (input) => getNativeBusinessSummary(client, input, timeout),
+            callCapability: (input) => callNativeCapability(client, input, timeout),
+            readCapability: (input) => readNativeCapability(client, input, timeout),
+            writeCapability: (input) => writeNativeCapability(client, input, timeout),
+            describeCapabilitySummary: (name) => readNativeCapabilityDescriptor(client, name, timeout),
+            searchBusiness: (input) => searchNativeBusiness(client, input, timeout),
+            readBusinessPage: (input) => readNativeBusinessPage(client, input, timeout),
+            findCapabilities: (input) => findNativeCapabilities(client, input, timeout),
+            discoverCapabilities: async (input) => {
+              const page2 = await findAgentCapabilities(client, input, timeout);
+              for (const item of page2.items)
+                if (item.definition) definitions.remember(item.definition);
+              return page2;
+            },
+            describeCapability: async (name, expectedHash) => {
+              const cached = expectedHash ? definitions.get(name, expectedHash) : void 0;
+              if (cached) return cached;
+              const definition = await describeNativeCapability(client, name, timeout);
+              if (expectedHash && definition.schemaSha256 !== expectedHash)
+                throw new CliError(
+                  "CAPABILITY_SCHEMA_CHANGED",
+                  "Discover the current definition again.",
+                  "REJECTED"
+                );
+              definitions.remember(definition);
+              return definition;
+            }
+          },
+          {
+            get(target, name, receiver) {
+              const method = Reflect.get(target, name, receiver);
+              if (typeof method !== "function" || name === "getVersion" || name === "refreshVersion")
+                return method;
+              return async (...args) => {
+                if (versionUnverified)
+                  throw new CliError(
+                    "CLIENT_VERSION_UNVERIFIED",
+                    "Verify the service release again or reconnect before continuing. No business operation was sent.",
+                    "NOT_SENT",
+                    { compatibility: version.compatibility }
+                  );
+                assertNativeCompatibility(version, options.requireCompatibility);
+                return Reflect.apply(method, target, args);
+              };
+            }
+          }
+        )
+      );
+    },
+    options
   );
 }
 function checkTimeout4(timeout) {
@@ -9073,9 +9396,22 @@ var values = /* @__PURE__ */ new Set([
   "scope",
   "job",
   "view",
-  "schema-hash"
+  "schema-hash",
+  "mode",
+  "channel",
+  "pin",
+  "interval-hours"
+]);
+var flags = /* @__PURE__ */ new Set([
+  "json",
+  "stdin",
+  "help",
+  "version",
+  "server",
+  "strict",
+  "allow-breaking",
+  "dry-run"
 ]);
-var flags = /* @__PURE__ */ new Set(["json", "stdin", "help"]);
 function parseArgs(args) {
   const options = {};
   const words = [];
@@ -9154,8 +9490,8 @@ async function login(store, rawResource, scope2, timeout, notify) {
     const state = randomBytes(32).toString("base64url");
     let resolveCode;
     let rejectCode;
-    const codePromise = new Promise((resolve, reject) => {
-      resolveCode = resolve;
+    const codePromise = new Promise((resolve2, reject) => {
+      resolveCode = resolve2;
       rejectCode = reject;
     });
     void codePromise.catch(() => void 0);
@@ -9186,9 +9522,9 @@ async function login(store, rawResource, scope2, timeout, notify) {
     });
     let timer;
     try {
-      await new Promise((resolve, reject) => {
+      await new Promise((resolve2, reject) => {
         server.once("error", reject);
-        server.listen(0, "127.0.0.1", resolve);
+        server.listen(0, "127.0.0.1", resolve2);
       });
       const address = server.address();
       if (!address || typeof address === "string")
@@ -9258,7 +9594,7 @@ Waiting up to 5 minutes. For remote/headless Agents, use auth import with a prov
     } finally {
       if (timer) clearTimeout(timer);
       server.closeAllConnections();
-      await new Promise((resolve) => server.close(() => resolve()));
+      await new Promise((resolve2) => server.close(() => resolve2()));
     }
   });
 }
@@ -9333,6 +9669,10 @@ var fullHelp = {
   executable: "cf-agent",
   transport: "OAuth-authenticated HTTPS MCP; no local database",
   commands: [
+    "version [--server [--strict] [--profile <name>]]",
+    "update check [--channel latest|next|beta] [--pin <exact-version>|none]",
+    "update apply [--dry-run] [--allow-breaking] [--channel latest|next|beta] [--pin <exact-version>|none]",
+    "update policy [--mode off|notify|auto] [--channel latest|next|beta] [--pin <exact-version>|none] [--interval-hours <1..168>]",
     "auth login --resource <url> [--scope <scopes>] [--profile <name>]",
     "auth import --resource <url> --token-file <private-file> [--profile <name>]",
     "auth status|refresh|logout [--profile <name>]",
@@ -9376,6 +9716,8 @@ var help = {
   executable: "cf-agent",
   transport: "OAuth-authenticated MCP; no local database",
   commands: [
+    "version [--server [--strict]]",
+    "update check|apply|policy (help update for channels, pins and automatic updates)",
     "auth login --resource <url> [--scope <scopes>]",
     "search [<text>] [--input-file <query.json>|--stdin]",
     "business read (--input-file <ref-and-page.json>|--stdin)",
@@ -9520,6 +9862,21 @@ function resolveBaseCommand(parsed) {
   throw new CliError("INVALID_COMMAND", "Run help for supported commands.");
 }
 function resolveCommand(parsed) {
+  if ([
+    "mode",
+    "channel",
+    "pin",
+    "interval-hours",
+    "version",
+    "server",
+    "strict",
+    "allow-breaking",
+    "dry-run"
+  ].some((key2) => parsed.options[key2]))
+    throw new CliError(
+      "INVALID_OPTION",
+      "Version/update options apply only to version/update commands."
+    );
   const removed = {
     doctor: "context",
     "knowledge sync-all": "knowledge discover",
@@ -9654,14 +10011,430 @@ function validateCommandInput(parsed, input) {
     throw new CliError("INVALID_PAGINATION", "Supply only an optional nonempty cursor.");
 }
 
+// packages/cli-client/src/updates/registry.ts
+async function checkNativeUpdates(options = {}) {
+  const policy = updatePolicySchema.parse(options.policy ?? {});
+  const current = releaseVersionSchema.safeParse(
+    options.currentVersion ?? nativeClientRelease.version
+  );
+  if (!current.success)
+    throw new CliError(
+      "INVALID_UPDATE_VERSION",
+      "The installed version must be an exact semantic version."
+    );
+  const timeout = options.timeoutMs ?? 5e3;
+  if (!Number.isInteger(timeout) || timeout < 100 || timeout > 12e4)
+    throw new CliError("INVALID_TIMEOUT", "Timeout must be 100\u2013120000 milliseconds.");
+  const name = nativeClientRelease.packages[options.package ?? "sdk"];
+  if (!name) throw new CliError("INVALID_UPDATE_PACKAGE", "Choose sdk or cli.");
+  const selector = policy.pin ?? policy.channel;
+  const url = `https://registry.npmjs.org/${encodeURIComponent(name)}/${encodeURIComponent(selector)}`;
+  let target;
+  try {
+    const response = await (options.fetch ?? fetch)(url, {
+      redirect: "error",
+      credentials: "omit",
+      signal: AbortSignal.timeout(timeout),
+      headers: { accept: "application/json" }
+    });
+    if (!response.ok || !response.body) throw new Error();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.byteLength;
+        if (size > 128 * 1024) throw new Error();
+        chunks.push(value);
+      }
+    } finally {
+      await reader.cancel().catch(() => void 0);
+      reader.releaseLock();
+    }
+    target = registryReleaseSchema.parse(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+    if (target.name !== name || policy.pin && target.version !== policy.pin) throw new Error();
+  } catch {
+    throw new CliError(
+      "UPDATE_CHECK_UNAVAILABLE",
+      "Cannot verify release metadata from the public npm registry. Existing software and credentials are unchanged."
+    );
+  }
+  return {
+    checkedAt: Date.now(),
+    target,
+    plan: planNativeUpdate({
+      target,
+      policy,
+      nodeMajor: Number(process.versions.node.split(".")[0]),
+      currentVersion: current.data,
+      ...options.server ? { server: options.server } : {}
+    })
+  };
+}
+
+// packages/cli-client/src/updates/store.ts
+import { lstat as lstat2, open as open6, rename as rename2, unlink as unlink2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+import { randomUUID as randomUUID3 } from "node:crypto";
+var UpdateStore = class {
+  files;
+  constructor(env) {
+    const base2 = new ProfileStore(env).directory;
+    this.files = new ProfileStore({ CF_AGENT_CONFIG_DIR: join3(base2, "client-lifecycle") }, "state");
+  }
+  async read() {
+    try {
+      await lstat2(this.files.path);
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return { schemaVersion: 1, policy: updatePolicySchema.parse({}) };
+      throw error;
+    }
+    let raw;
+    try {
+      raw = JSON.parse(await readFileBounded(this.files.path, true));
+    } catch {
+      throw new CliError(
+        "INVALID_UPDATE_CONFIGURATION",
+        "Update state is unreadable. Inspect the client-lifecycle configuration."
+      );
+    }
+    const parsed = clientUpdateStateSchema.safeParse(raw);
+    if (!parsed.success)
+      throw new CliError(
+        "INVALID_UPDATE_CONFIGURATION",
+        "Update state is invalid. Inspect the client-lifecycle configuration."
+      );
+    return parsed.data;
+  }
+  locked(action) {
+    return this.files.locked(action);
+  }
+  async change(action) {
+    return this.locked(async () => {
+      const state = clientUpdateStateSchema.parse(action(await this.read()));
+      const temporary = `${this.files.path}.${randomUUID3()}.tmp`;
+      const file = await open6(temporary, "wx", 384);
+      try {
+        try {
+          await file.writeFile(JSON.stringify(state) + "\n");
+          await file.sync();
+        } finally {
+          await file.close();
+        }
+        await rename2(temporary, this.files.path);
+      } finally {
+        await unlink2(temporary).catch(() => void 0);
+      }
+      return state;
+    });
+  }
+};
+function effectiveUpdatePolicy(policy, env) {
+  const parsed = updatePolicySchema.safeParse({
+    ...policy,
+    ...env.CF_AGENT_UPDATE_MODE ? { mode: env.CF_AGENT_UPDATE_MODE } : {},
+    ...env.CF_AGENT_UPDATE_CHANNEL ? { channel: env.CF_AGENT_UPDATE_CHANNEL } : {},
+    ...env.CF_AGENT_UPDATE_PIN ? { pin: env.CF_AGENT_UPDATE_PIN === "none" ? null : env.CF_AGENT_UPDATE_PIN } : {}
+  });
+  if (!parsed.success)
+    throw new CliError("INVALID_UPDATE_CONFIGURATION", "Invalid update environment policy.");
+  return parsed.data;
+}
+
+// packages/cli-client/src/updates/install.ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile as readFile2, realpath as realpath2 } from "node:fs/promises";
+import { dirname as dirname2, join as join4, resolve } from "node:path";
+var execute = promisify(execFile);
+async function installCliUpdate(input) {
+  const plan = planNativeUpdate({
+    target: input.target,
+    ...input.currentVersion ? { currentVersion: input.currentVersion } : {},
+    policy: input.policy,
+    nodeMajor: Number(process.versions.node.split(".")[0])
+  });
+  if (plan.package !== nativeClientRelease.packages.cli || plan.status !== "UPDATE_AVAILABLE" || !plan.eligibleForAutoUpdate && !input.allowBreaking)
+    throw new CliError(
+      "UPDATE_POLICY_BLOCKED",
+      "This release cannot be installed under the selected policy.",
+      "NOT_SENT",
+      { plan }
+    );
+  if (!input.executablePath || process.platform === "win32")
+    throw new CliError(
+      "MANAGED_UPDATE_UNAVAILABLE",
+      "Use the package manager that owns this installation.",
+      "NOT_SENT",
+      { plan }
+    );
+  const environment = Object.fromEntries(
+    Object.entries(input.env).filter(
+      ([key2, value]) => value !== void 0 && !/^(?:CF_AGENT_|CONTENT_FACTORY_)/i.test(key2)
+    )
+  );
+  environment.CF_AGENT_UPDATE_MODE = "off";
+  environment.NODE_OPTIONS = "--max-old-space-size=384";
+  const options = { env: environment, timeout: input.timeoutMs, maxBuffer: 128 * 1024 };
+  let packageRoot, prefix;
+  try {
+    packageRoot = dirname2(dirname2(await realpath2(input.executablePath)));
+    const manifest = JSON.parse(await readFile2(join4(packageRoot, "package.json"), "utf8"));
+    const root = await realpath2(
+      (await execute("npm", ["root", "--global"], options)).stdout.trim()
+    );
+    prefix = await realpath2((await execute("npm", ["prefix", "--global"], options)).stdout.trim());
+    if (manifest.name !== nativeClientRelease.packages.cli || manifest.version !== plan.currentVersion || packageRoot !== await realpath2(join4(root, "@native-marketing/cli")) || packageRoot !== resolve(prefix, "lib/node_modules/@native-marketing/cli"))
+      throw new Error();
+  } catch {
+    throw new CliError(
+      "MANAGED_UPDATE_UNAVAILABLE",
+      "Automatic installation supports the active npm global installation. Use the owning project/package manager for other installs.",
+      "NOT_SENT",
+      { plan }
+    );
+  }
+  const args = [
+    "install",
+    "--global",
+    "--prefix",
+    prefix,
+    `${plan.package}@${plan.targetVersion}`,
+    "--registry=https://registry.npmjs.org/",
+    "--@native-marketing:registry=https://registry.npmjs.org/",
+    "--ignore-scripts",
+    "--no-audit",
+    "--no-fund"
+  ];
+  const recovery = [
+    "npm",
+    "install",
+    "--global",
+    "--prefix",
+    prefix,
+    `${plan.package}@${plan.currentVersion}`,
+    "--ignore-scripts",
+    "--registry=https://registry.npmjs.org/",
+    "--@native-marketing:registry=https://registry.npmjs.org/"
+  ];
+  const store = new UpdateStore(input.env);
+  return store.locked(async () => {
+    if (input.automatic) {
+      const latest = effectiveUpdatePolicy((await store.read()).policy, input.env);
+      if (latest.mode !== "auto" || (latest.pin ?? latest.channel) !== (input.policy.pin ?? input.policy.channel) || !planNativeUpdate({
+        target: input.target,
+        currentVersion: plan.currentVersion,
+        policy: latest,
+        nodeMajor: Number(process.versions.node.split(".")[0])
+      }).eligibleForAutoUpdate)
+        throw new CliError(
+          "UPDATE_POLICY_CHANGED",
+          "Automatic update policy changed. No installation or business operation was sent."
+        );
+    }
+    const before = JSON.parse(await readFile2(join4(packageRoot, "package.json"), "utf8"));
+    if (before.name !== plan.package || before.version !== plan.currentVersion)
+      throw new CliError(
+        "UPDATE_INSTALLATION_CHANGED",
+        "The installed version changed. Check version before updating again."
+      );
+    try {
+      await execute("npm", args, { ...options, cwd: prefix });
+      const installed = JSON.parse(await readFile2(join4(packageRoot, "package.json"), "utf8"));
+      if (installed.name !== plan.package || releaseVersionSchema.parse(installed.version) !== plan.targetVersion)
+        throw new Error();
+      const verified = await execute(
+        process.execPath,
+        [join4(packageRoot, "dist/cf.js"), "version", "--json"],
+        options
+      );
+      const result2 = JSON.parse(verified.stdout);
+      if (!result2.ok || result2.data?.version !== plan.targetVersion || result2.data?.sdkVersion !== plan.targetVersion)
+        throw new Error();
+      return {
+        state: "UPDATED",
+        package: plan.package,
+        previousVersion: plan.currentVersion,
+        installedVersion: plan.targetVersion,
+        restartRequired: true,
+        originalCommandExecuted: false,
+        recovery
+      };
+    } catch {
+      throw new CliError(
+        "UPDATE_OUTCOME_UNKNOWN",
+        "The installation may have changed. Inspect version before another update; use the recovery command if needed. The original business command was not sent.",
+        "UNKNOWN",
+        { expectedVersion: plan.targetVersion, recovery, originalCommandExecuted: false }
+      );
+    }
+  });
+}
+
+// packages/cli-client/src/updates/commands.ts
+function validateOptions(parsed, names) {
+  if (Object.keys(parsed.options).some((name) => !["json", "timeout-ms", ...names].includes(name)))
+    throw new CliError("INVALID_OPTION", "Unsupported version/update option. Use help update.");
+}
+function selectedPolicy(saved, parsed) {
+  const options = parsed.options;
+  const result2 = updatePolicySchema.safeParse({
+    ...saved,
+    ...options.mode ? { mode: options.mode } : {},
+    ...options.channel ? { channel: options.channel } : {},
+    ...options.pin ? { pin: options.pin === "none" ? null : options.pin } : {},
+    ...options["interval-hours"] ? { intervalHours: Number(options["interval-hours"]) } : {}
+  });
+  if (!result2.success)
+    throw new CliError(
+      "INVALID_UPDATE_POLICY",
+      "Use mode off/notify/auto, channel latest/next/beta, an exact pin or none, and interval-hours 1\u2013168."
+    );
+  return result2.data;
+}
+async function runLifecycleCommand(parsed, env, executablePath) {
+  const { words, options, timeout } = parsed;
+  if (options.version || words[0] === "version") {
+    if (options.version && words.length !== 0 || !options.version && words.length !== 1)
+      throw new CliError("INVALID_COMMAND", "Use version or --version.");
+    validateOptions(parsed, ["version", "server", "strict", "profile"]);
+    if (options.strict && !options.server)
+      throw new CliError("INVALID_OPTION", "--strict requires version --server.");
+    if (options.profile && !options.server)
+      throw new CliError("INVALID_OPTION", "--profile requires version --server.");
+    return options.server ? null : { command: "version", data: await getNativeCliVersion(executablePath) };
+  }
+  if (words[0] !== "update") return null;
+  if (words.length !== 2 || !["check", "apply", "policy"].includes(words[1]))
+    throw new CliError("INVALID_COMMAND", "Use update check/apply/policy.");
+  const policyCommand = words[1] === "policy";
+  validateOptions(
+    parsed,
+    policyCommand ? ["mode", "channel", "pin", "interval-hours"] : ["channel", "pin", ...words[1] === "apply" ? ["allow-breaking", "dry-run"] : []]
+  );
+  const store = new UpdateStore(env);
+  const state = await store.read();
+  if (policyCommand) {
+    const changes = Object.keys(options).some(
+      (name) => ["mode", "channel", "pin", "interval-hours"].includes(name)
+    );
+    const saved = changes ? await store.change((current) => ({
+      ...current,
+      policy: selectedPolicy(current.policy, parsed)
+    })) : state;
+    return {
+      command: "update policy",
+      data: {
+        saved: saved.policy,
+        effective: effectiveUpdatePolicy(saved.policy, env),
+        lastCheckedAt: saved.lastCheck?.at ?? null
+      }
+    };
+  }
+  const policy = selectedPolicy(effectiveUpdatePolicy(state.policy, env), parsed);
+  const currentVersion = (await getNativeCliVersion(executablePath)).version;
+  const checked = await checkNativeUpdates({
+    package: "cli",
+    currentVersion,
+    policy,
+    timeoutMs: timeout
+  });
+  await store.change((current) => ({
+    ...current,
+    lastAttempt: { at: checked.checkedAt, selector: policy.pin ?? policy.channel },
+    lastCheck: {
+      at: checked.checkedAt,
+      selector: policy.pin ?? policy.channel,
+      target: checked.target
+    }
+  }));
+  if (words[1] === "check" || options["dry-run"] || checked.plan.status === "CURRENT")
+    return { command: words.join(" "), data: checked };
+  const data = await installCliUpdate({
+    target: checked.target,
+    currentVersion,
+    policy,
+    timeoutMs: timeout,
+    env,
+    allowBreaking: Boolean(options["allow-breaking"]),
+    ...executablePath ? { executablePath } : {}
+  });
+  return { command: "update apply", data };
+}
+async function maybeAutoUpdate(env, io, timeout) {
+  if (!io.executablePath || env.CF_AGENT_UPDATE_MODE === "off" || env.CI && !env.CF_AGENT_UPDATE_MODE)
+    return null;
+  const notify = io.notify ?? ((message) => process.stderr.write(message + "\n"));
+  try {
+    const store = new UpdateStore(env);
+    const state = await store.read();
+    const policy = effectiveUpdatePolicy(state.policy, env);
+    if (policy.mode === "off") return null;
+    const now = Date.now(), selector = policy.pin ?? policy.channel;
+    const age = state.lastAttempt ? now - state.lastAttempt.at : Infinity;
+    if (state.lastAttempt?.selector === selector && age >= 0 && age < policy.intervalHours * 36e5)
+      return null;
+    let claimed = false;
+    await store.change((current) => {
+      const age2 = current.lastAttempt ? now - current.lastAttempt.at : Infinity;
+      if (current.lastAttempt?.selector === selector && age2 >= 0 && age2 < policy.intervalHours * 36e5)
+        return current;
+      claimed = true;
+      return { ...current, lastAttempt: { at: now, selector } };
+    });
+    if (!claimed) return null;
+    const currentVersion = (await getNativeCliVersion(io.executablePath)).version;
+    const checked = await checkNativeUpdates({
+      package: "cli",
+      currentVersion,
+      policy,
+      timeoutMs: Math.min(timeout, 2e3)
+    });
+    await store.change((current) => ({
+      ...current,
+      lastCheck: { at: checked.checkedAt, selector, target: checked.target }
+    }));
+    if (checked.plan.status === "CURRENT" || checked.plan.reason === "DOWNGRADE_FORBIDDEN" && !policy.pin)
+      return null;
+    if (policy.mode === "auto" && checked.plan.eligibleForAutoUpdate) {
+      const data = await installCliUpdate({
+        target: checked.target,
+        currentVersion,
+        automatic: true,
+        policy,
+        executablePath: io.executablePath,
+        env,
+        timeoutMs: timeout
+      });
+      notify(
+        `Native Marketing updated to ${checked.plan.targetVersion}. Run the original command again.`
+      );
+      return { command: "update auto", data };
+    }
+    notify(
+      `Native Marketing ${nativeClientRelease.version}: update ${checked.plan.targetVersion} (${checked.plan.reason}). Use update check or update apply.`
+    );
+  } catch (error) {
+    if (error instanceof CliError && error.code === "UPDATE_OUTCOME_UNKNOWN") throw error;
+    notify("Native Marketing update check/install is unavailable; use update check for details.");
+  }
+  return null;
+}
+
 // packages/cli-client/src/cli/run.ts
 async function runNetworkCli(args, env = process.env, io = {}, executable = "cf") {
   let command5 = executable;
   try {
     const parsed = parseArgs(args);
     const { words, options, timeout } = parsed;
-    if (!words.length || words[0] === "help" || options.help)
+    if ((!words.length || words[0] === "help" || options.help) && !options.version)
       return success("help", { ...commandHelp(words), executable });
+    const local = await runLifecycleCommand(parsed, env, io.executablePath);
+    if (local) return success(local.command, local.data);
+    const remoteVersion = (words.join(" ") === "version" || options.version && !words.length) && options.server;
     const store = new ProfileStore(env, String(options.profile ?? "default"));
     if (words[0] === "auth") {
       if (words.length !== 2)
@@ -9733,10 +10506,14 @@ async function runNetworkCli(args, env = process.env, io = {}, executable = "cf"
         "AUTH_OPTION_MISUSE",
         "Resource/token/scope options belong to auth commands. Business commands use the bound profile or CF_AGENT_RESOURCE and CF_AGENT_ACCESS_TOKEN together."
       );
-    resolveCommand(parsed);
-    command5 = words[0] === "search" ? "search" : words[0] === "capabilities" ? words.slice(0, 2).join(" ") : words.join(" ");
+    if (!remoteVersion) resolveCommand(parsed);
+    command5 = remoteVersion ? "version" : words[0] === "search" ? "search" : words[0] === "capabilities" ? words.slice(0, 2).join(" ") : words.join(" ");
+    if (!remoteVersion) {
+      const automatic = await maybeAutoUpdate(env, io, timeout);
+      if (automatic) return success(automatic.command, automatic.data);
+    }
     const input = options.stdin ? objectJson(await readStream(io.stdin ?? process.stdin)) : typeof options["input-file"] === "string" ? objectJson(await readFileBounded(options["input-file"])) : {};
-    validateCommandInput(parsed, input);
+    if (!remoteVersion) validateCommandInput(parsed, input);
     let profile;
     if (env.CF_AGENT_ACCESS_TOKEN || env.CF_AGENT_RESOURCE) {
       if (options.profile || !env.CF_AGENT_ACCESS_TOKEN || !env.CF_AGENT_RESOURCE)
@@ -9749,7 +10526,18 @@ async function runNetworkCli(args, env = process.env, io = {}, executable = "cf"
         accessToken: tokenText(env.CF_AGENT_ACCESS_TOKEN)
       };
     } else profile = await refreshProfile(store, timeout);
-    const data = resolveCommand(parsed).mode === "package-file" ? await downloadPackageFile(profile, input, String(options["output-file"]), timeout) : resolveCommand(parsed).mode === "media-file" ? await downloadProjectMedia(profile, input, String(options["output-file"]), timeout) : resolveCommand(parsed).mode === "upload" ? await uploadLocalMaterial(
+    const data = remoteVersion ? await withClient(
+      profile,
+      timeout,
+      async (client) => ({
+        ...readNativeServerVersion(client),
+        cli: await getNativeCliVersion(io.executablePath)
+      }),
+      {
+        allowIncompatible: !options.strict,
+        requireCompatibility: Boolean(options.strict)
+      }
+    ) : resolveCommand(parsed).mode === "package-file" ? await downloadPackageFile(profile, input, String(options["output-file"]), timeout) : resolveCommand(parsed).mode === "media-file" ? await downloadProjectMedia(profile, input, String(options["output-file"]), timeout) : resolveCommand(parsed).mode === "upload" ? await uploadLocalMaterial(
       profile,
       String(options.file),
       String(options["request-id"]),
@@ -9758,7 +10546,15 @@ async function runNetworkCli(args, env = process.env, io = {}, executable = "cf"
     ) : await withClient(
       profile,
       timeout,
-      (client) => businessCommand(client, parsed, input, profile.resource)
+      (client) => businessCommand(client, parsed, input, profile.resource),
+      {
+        onVersion: (version) => {
+          if (version.compatibility.status === "UPGRADE_RECOMMENDED")
+            (io.notify ?? ((message) => process.stderr.write(message + "\n")))(
+              `The service recommends Native Marketing ${version.compatibility.server.version}. Use update check.`
+            );
+        }
+      }
     );
     return success(command5, data);
   } catch (error) {
@@ -9770,14 +10566,19 @@ function success(command5, data) {
 }
 export {
   CliError as NativeAgentClientError,
+  assessNativeCompatibility,
   callNativeCapability,
   callNativeTool,
+  checkNativeUpdates,
+  defaultUpdatePolicy,
   describeNativeCapability,
   findAgentCapabilities,
   findNativeCapabilities,
   getNativeBusinessSummary,
+  getNativeClientVersion,
   inspectNativeTool,
   listNativeToolsPage,
+  planNativeUpdate,
   projectMediaFileQuerySchema,
   readNativeBusinessPage,
   readNativeCapability,