@byok-sdk/client 0.4.2 → 0.6.0

package/README.md

@@ -63,6 +63,24 @@ validated registry. Only those logical IDs are advertised in `conn.hello`
 and hosted presence; command, args, environment, headers, and credentials
 remain local.
 
+Hosted deployments that enforce an activity-ingress byte ceiling should inject
+the same ceiling into the daemon. The byte count is the UTF-8 length of
+`JSON.stringify(events)`; it does not include envelope or transport overhead.
+One event that cannot fit fails the task locally without truncation or network
+delivery.
+
+```ts
+createDaemon({
+  // ...normal device and transport configuration
+  progressBatch: {
+    maxBatchBytes: 64 * 1024,
+  },
+});
+```
+
+The value is intentionally host-owned and has no SDK default because it is a
+deployment/read-model policy, not a frozen protocol limit.
+
 For a concrete private host composition, see the
 [`examples/salesko-connector-broker`](../../examples/salesko-connector-broker)
 reference. It keeps `@byok-sdk/client` credential-blind while combining

package/dist/bin/byok-agent.js

@@ -5,7 +5,7 @@ import { readFileSync, promises, linkSync, fstatSync, lstatSync, unlinkSync, con
 import path20, { isAbsolute, join } from 'path';
 import os from 'os';
 import { DEVICE_ASSERTION_AUDIENCE_MAX_BYTES, DEVICE_ASSERTION_DEFAULT_TTL_MS, DEVICE_ASSERTION_MAX_TTL_MS, nonceSigningBytes, CapabilityDeclarationSchema, hasCapability, DeviceAssertionClaimsSchema, deviceAssertionSigningInput, DEVICE_ASSERTION_SCHEMA_ID } from '@byok-sdk/core';
-import { TASK_STATES, CONFIGURED_TOOLSETS_MAX_ITEMS, ToolsetIdSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, partitionAgentEvents, TASK_TRANSITIONS, encodeEnvelope, createEnvelope, byokBlobUrlPath, BYOK_BLOBS_PATH, byokBlobFinalizePath, checkResultDocument, MAX_MESSAGES_PER_BATCH, BYOK_CAPABILITIES_PATH, BYOK_PRESENCE_PATH, RuntimeIdSchema, RESULT_DOCUMENT_MAX_BYTES, PROTOCOL_VERSION, decodeEnvelope, BYOK_MESSAGES_PATH, MessagesSendResponseSchema, BYOK_EVENTS_PATH, parseMessage, UnknownMessageTypeError, BYOK_WS_PATH } from '@byok-sdk/protocol';
+import { TASK_STATES, CONFIGURED_TOOLSETS_MAX_ITEMS, ToolsetIdSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, partitionAgentEvents, TASK_TRANSITIONS, encodeEnvelope, PROTOCOL_VERSION, createEnvelope, byokBlobUrlPath, BYOK_BLOBS_PATH, byokBlobFinalizePath, checkResultDocument, MAX_MESSAGES_PER_BATCH, BYOK_CAPABILITIES_PATH, BYOK_PRESENCE_PATH, RuntimeIdSchema, TERMINAL_INFERENCE_USAGE_MAX_DURATION_MS, TERMINAL_INFERENCE_USAGE_MAX_TOKENS, RESULT_DOCUMENT_MAX_BYTES, decodeEnvelope, BYOK_MESSAGES_PATH, MessagesSendResponseSchema, BYOK_EVENTS_PATH, parseMessage, UnknownMessageTypeError, BYOK_WS_PATH } from '@byok-sdk/protocol';
 import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import 'readline';
@@ -77,6 +77,28 @@ var SteerUnsupportedError = class extends Error {
   }
 };
 
+// src/release-identity.ts
+var LOCAL_AGENT_RELEASE_VERSION_MAX_LENGTH = 128;
+var LOCAL_AGENT_RELEASE_BUILD_ID_MAX_LENGTH = 128;
+var STRICT_SEMVER_PATTERN = new RegExp(
+  "^(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 BUILD_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+function resolveLocalAgentReleaseIdentity(input) {
+  if (input === void 0 || typeof input.version !== "string" || input.version.length > LOCAL_AGENT_RELEASE_VERSION_MAX_LENGTH || !STRICT_SEMVER_PATTERN.test(input.version)) {
+    throw new Error("DaemonConfig.localAgentRelease.version must be canonical strict SemVer");
+  }
+  if (input.buildId !== void 0 && (typeof input.buildId !== "string" || input.buildId.length > LOCAL_AGENT_RELEASE_BUILD_ID_MAX_LENGTH || !BUILD_ID_PATTERN.test(input.buildId))) {
+    throw new Error(
+      `DaemonConfig.localAgentRelease.buildId must be 1-${LOCAL_AGENT_RELEASE_BUILD_ID_MAX_LENGTH} safe opaque characters`
+    );
+  }
+  return Object.freeze({
+    version: input.version,
+    ...input.buildId === void 0 ? {} : { buildId: input.buildId }
+  });
+}
+
 // src/runtime-failure.ts
 var RUNTIME_EXECUTION_FAILURE_BRAND = /* @__PURE__ */ Symbol.for("@byok-sdk/client/RuntimeExecutionFailure/v1");
 var RUNTIME_DISPOSAL_FAILURE_BRAND = /* @__PURE__ */ Symbol.for("@byok-sdk/client/RuntimeDisposalFailure/v1");
@@ -4419,7 +4441,20 @@ var PresencePublisher = class {
           headers: { "content-type": "application/json" },
           body: JSON.stringify({
             level: "online",
-            ...this.opts.configuredToolsets === void 0 ? {} : { configuredToolsets: this.opts.configuredToolsets }
+            ...this.opts.configuredToolsets === void 0 ? {} : { configuredToolsets: this.opts.configuredToolsets },
+            ...this.opts.clientVersion === void 0 ? {} : { clientVersion: this.opts.clientVersion },
+            ...this.opts.protocolVersions === void 0 ? {} : { protocolVersions: [...this.opts.protocolVersions] },
+            // Presence is a lightweight readiness fact, not a second
+            // capability-negotiation channel. Keep its projection identical
+            // to the persisted presence contract: the conn.hello snapshot's
+            // runtime identity/version/auth facts, with no capabilities blob.
+            ...this.opts.runtimes === void 0 ? {} : {
+              runtimes: this.opts.runtimes.map(({ id, version, authPresent }) => ({
+                id,
+                ...version === void 0 ? {} : { version },
+                ...authPresent === void 0 ? {} : { authPresent }
+              }))
+            }
           })
         },
         this.opts.auth
@@ -5145,6 +5180,7 @@ var WsTransport = class {
         capabilities: this.opts.capabilities,
         deviceId: this.opts.deviceId,
         productId: this.opts.productId,
+        clientVersion: this.opts.clientVersion,
         runtimes: this.opts.runtimes,
         configuredToolsets: this.opts.configuredToolsets === void 0 ? void 0 : [...this.opts.configuredToolsets],
         cursor: this.opts.getCursor?.()
@@ -5235,6 +5271,7 @@ var ConnectionManager = class {
       deviceId: opts.deviceId,
       productId: opts.productId,
       capabilities: opts.capabilities,
+      clientVersion: opts.clientVersion,
       runtimes: opts.runtimes,
       configuredToolsets: opts.configuredToolsets,
       getCursor: () => this.cursor,
@@ -8275,6 +8312,11 @@ function createStatfsFreeBytesProvider(dir) {
 var BASE_PLATFORM_ALLOWLIST = [
   "PATH",
   "HOME",
+  // macOS credential-store discovery used by subscription-authenticated
+  // agent CLIs depends on the login account name as well as HOME. Omitting
+  // USER makes `claude auth status` report logged out under the filtered
+  // child environment even when the host CLI is logged in.
+  "USER",
   "USERPROFILE",
   "TMPDIR",
   "TEMP",
@@ -8382,11 +8424,37 @@ function computeEffectivePolicy(offered, ceiling) {
 }
 
 // src/daemon/progress-batcher.ts
+var ProgressEventTooLargeError = class extends Error {
+  constructor(actualBytes, maxBatchBytes) {
+    super(`Progress event requires ${actualBytes} UTF-8 bytes, exceeding maxBatchBytes ${maxBatchBytes}.`);
+    this.actualBytes = actualBytes;
+    this.maxBatchBytes = maxBatchBytes;
+    this.name = "ProgressEventTooLargeError";
+  }
+  actualBytes;
+  maxBatchBytes;
+};
+var encoder = new TextEncoder();
+function assertPositiveSafeInteger(value, name) {
+  if (value !== void 0 && (!Number.isSafeInteger(value) || value <= 0)) {
+    throw new TypeError(`${name} must be a positive safe integer when configured.`);
+  }
+}
+function validateProgressBatcherOptions(options = {}) {
+  assertPositiveSafeInteger(options.maxBatchSize, "maxBatchSize");
+  assertPositiveSafeInteger(options.flushIntervalMs, "flushIntervalMs");
+  assertPositiveSafeInteger(options.maxBatchBytes, "maxBatchBytes");
+}
+function encodedEventsBytes(events) {
+  return encoder.encode(JSON.stringify(events)).length;
+}
 var ProgressBatcher = class {
   constructor(emit, options = {}) {
     this.emit = emit;
+    validateProgressBatcherOptions(options);
     this.maxBatchSize = options.maxBatchSize ?? 10;
     this.flushIntervalMs = options.flushIntervalMs ?? 250;
+    this.maxBatchBytes = options.maxBatchBytes;
   }
   emit;
   buffer = [];
@@ -8394,7 +8462,17 @@ var ProgressBatcher = class {
   timer;
   maxBatchSize;
   flushIntervalMs;
+  maxBatchBytes;
   push(event) {
+    if (this.maxBatchBytes !== void 0) {
+      const eventBytes = encodedEventsBytes([event]);
+      if (eventBytes > this.maxBatchBytes) {
+        throw new ProgressEventTooLargeError(eventBytes, this.maxBatchBytes);
+      }
+      if (this.buffer.length > 0 && encodedEventsBytes([...this.buffer, event]) > this.maxBatchBytes) {
+        this.flush();
+      }
+    }
     this.buffer.push(event);
     if (this.buffer.length >= this.maxBatchSize) {
       this.flush();
@@ -8447,6 +8525,7 @@ var MAX_INLINE_ARTIFACT_BYTES = 64 * 1024;
 var MAX_TRACKED_TASK_IDS = 2e3;
 var MAX_DURATION_EXCEEDED_REASON_PREFIX = "resource limit exceeded: maxDurationMs";
 var MAX_OUTPUT_BYTES_EXCEEDED_REASON_PREFIX = "resource limit exceeded: maxTaskOutputBytes";
+var MAX_PROGRESS_BATCH_BYTES_EXCEEDED_REASON_PREFIX = "resource limit exceeded: progressBatch.maxBatchBytes";
 var RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX = "result document undeliverable";
 function resultDocumentRejectionDetail(check) {
   switch (check.reason) {
@@ -8466,6 +8545,9 @@ var DEFAULT_MAX_TASK_OUTPUT_BYTES = 64 * 1024 * 1024;
 function isKnownRuntimeId(id) {
   return RuntimeIdSchema.safeParse(id).success;
 }
+function terminalUsageNumber(value, maximum) {
+  return value !== void 0 && Number.isSafeInteger(value) && value >= 0 && value <= maximum ? value : void 0;
+}
 var DEFAULT_RUNTIME_PREFERENCE = ["claude", "codex", "pi"];
 function orderByPreference(candidates, preference) {
   const rank = new Map(preference.map((id, index) => [id, index]));
@@ -8765,7 +8847,13 @@ var TaskRunner = class {
     const timeoutMs = this.deps.shutdownInterruptTimeoutMs ?? DEFAULT_SHUTDOWN_INTERRUPT_TIMEOUT_MS;
     await raceSettleFirst(() => active.session.interrupt(), timeoutMs);
     if (this.tasks.get(active.taskId) !== active) return true;
-    this.deps.send(createEnvelope("task.fail", { reason, retryable }, { taskId: active.taskId }));
+    this.deps.send(
+      createEnvelope(
+        "task.fail",
+        { reason, retryable, ...this.terminalInferenceUsagePayload(active) },
+        { taskId: active.taskId }
+      )
+    );
     return this.finish(active.taskId);
   }
   /** Graceful-shutdown caller of {@link teardownActiveTask} — see `shutdownActiveTasks`'s own doc comment. `retryable: true`: nothing about the task/policy itself was ever at fault, only this device's own availability right now. */
@@ -9143,7 +9231,8 @@ var TaskRunner = class {
           this.deps.batcherOptions
         ),
         approvalQueue: [],
-        outputBytesSoFar: 0
+        outputBytesSoFar: 0,
+        startedAtMs: Date.now()
       };
       if (this.pendingCancelled.has(taskId)) {
         const reason = this.pendingCancelled.get(taskId);
@@ -9155,7 +9244,13 @@ var TaskRunner = class {
         } catch {
         }
         await this.updateGitPhaseBestEffort(gitWorkspaceId, "cancelled");
-        this.deps.send(createEnvelope("task.cancelled", { reason }, { taskId }));
+        this.deps.send(
+          createEnvelope(
+            "task.cancelled",
+            { reason, ...this.terminalInferenceUsagePayload(active) },
+            { taskId }
+          )
+        );
         await this.finish(taskId);
         return;
       }
@@ -9228,6 +9323,9 @@ var TaskRunner = class {
           );
           return;
         }
+        if (event.type === "usage") {
+          active.lastUsage = event;
+        }
         if (event.type === "needs_approval") {
           active.batcher.flush();
           const { taskId } = active;
@@ -9280,7 +9378,8 @@ var TaskRunner = class {
                 // (where the codec actually serializes it), so a contextual
                 // `toJSON(key)` or an unstable getter cannot make the wire
                 // bytes differ from what the cap gate approved.
-                ...outcome.document !== void 0 ? { document: outcome.document } : {}
+                ...outcome.document !== void 0 ? { document: outcome.document } : {},
+                ...this.terminalInferenceUsagePayload(active)
               },
               { taskId: active.taskId, sessionRef: active.session.sessionRef }
             )
@@ -9303,6 +9402,13 @@ var TaskRunner = class {
     } catch (err) {
       if (this.tasks.get(active.taskId) !== active || active.beingTornDown) return;
       active.batcher.flush();
+      if (err instanceof ProgressEventTooLargeError) {
+        await this.failActiveTaskForResourceLimit(
+          active.taskId,
+          `${MAX_PROGRESS_BATCH_BYTES_EXCEEDED_REASON_PREFIX}: event requires ${err.actualBytes} UTF-8 bytes, exceeding the configured limit of ${err.maxBatchBytes} bytes`
+        );
+        return;
+      }
       const failure = projectRuntimeBoundaryFailure(err, "run");
       if (failure.contractViolation) {
         console.error("[byok/client] runtime adapter events iterable returned an untyped failure", err);
@@ -9390,7 +9496,13 @@ var TaskRunner = class {
     } catch {
     }
     await this.observeGit(active, "salvage");
-    this.deps.send(createEnvelope("task.cancelled", { reason }, { taskId }));
+    this.deps.send(
+      createEnvelope(
+        "task.cancelled",
+        { reason, ...this.terminalInferenceUsagePayload(active) },
+        { taskId }
+      )
+    );
     await this.finish(taskId);
   }
   /** M3-B: bounded insert for `pendingCancelled` — see its class-level doc comment and `MAX_TRACKED_TASK_IDS`. Evicts the oldest SAFE-TO-EVICT entry once over cap — see `evictPendingCancelled` (finding #5: not simply "the oldest entry", which could be an in-flight offer's own cancel marker). */
@@ -9828,7 +9940,13 @@ var TaskRunner = class {
     } catch {
     }
     await this.observeGit(active, "salvage");
-    this.deps.send(createEnvelope("task.fail", { reason: reason ?? "rejected", retryable: false }, { taskId }));
+    this.deps.send(
+      createEnvelope(
+        "task.fail",
+        { reason: reason ?? "rejected", retryable: false, ...this.terminalInferenceUsagePayload(active) },
+        { taskId }
+      )
+    );
     await this.finish(taskId);
   }
   /** Pre-claim, fail-closed rejection (protocol §3.2) — never claims first. */
@@ -9846,9 +9964,44 @@ var TaskRunner = class {
       return;
     }
     if (active) await this.observeGit(active, "salvage");
-    this.deps.send(createEnvelope("task.fail", { reason, retryable }, { taskId }));
+    this.deps.send(
+      createEnvelope(
+        "task.fail",
+        active === void 0 ? { reason, retryable } : { reason, retryable, ...this.terminalInferenceUsagePayload(active) },
+        { taskId }
+      )
+    );
     await this.finish(taskId);
   }
+  /**
+   * Build the optional terminal observation from facts this running daemon
+   * actually has. No offered `dispatchSelection` is echoed here: it is a
+   * requested execution target, not an adapter-reported provider/model fact.
+   * The bundled adapter event contracts currently expose token observations
+   * (Codex and Claude) but no provider/model observation, so those keys stay
+   * absent. Pi exposes no native usage observation, so its terminal payload
+   * omits this optional block rather than fabricating a usage observation from
+   * independently known runtime, elapsed duration, or Local Agent version.
+   */
+  terminalInferenceUsagePayload(active) {
+    const release = this.deps.localAgentRelease;
+    const runtimeId = active.adapter.descriptor.id;
+    if (release === void 0 || active.lastUsage === void 0 || !isKnownRuntimeId(runtimeId)) return {};
+    const nowMs = Date.now();
+    const durationMs = terminalUsageNumber(nowMs - active.startedAtMs, TERMINAL_INFERENCE_USAGE_MAX_DURATION_MS);
+    const promptTokens = terminalUsageNumber(active.lastUsage?.inputTokens, TERMINAL_INFERENCE_USAGE_MAX_TOKENS);
+    const completionTokens = terminalUsageNumber(active.lastUsage?.outputTokens, TERMINAL_INFERENCE_USAGE_MAX_TOKENS);
+    return {
+      usage: {
+        runtime: runtimeId,
+        clientVersion: release.version,
+        reportedAt: new Date(nowMs).toISOString(),
+        ...promptTokens === void 0 ? {} : { promptTokens },
+        ...completionTokens === void 0 ? {} : { completionTokens },
+        ...durationMs === void 0 ? {} : { durationMs }
+      }
+    };
+  }
   /**
    * additive-minor (`task.complete.document`): the whole daemon-side gate
    * between a configured {@link ResultDocumentExtractor} and the wire —
@@ -10377,6 +10530,7 @@ function createDaemonWithAdapters(config, adapters, overrides = {}) {
   return buildDaemonWithAdapters(config, adapters, overrides);
 }
 function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProbe) {
+  const localAgentRelease = resolveLocalAgentReleaseIdentity(config.localAgentRelease);
   const mcpToolsets = resolveMcpToolsets(config.mcpToolsets);
   const configuredToolsets = Object.freeze(
     [...mcpToolsets?.keys() ?? []].sort()
@@ -10389,6 +10543,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
       `DaemonConfig.maxTaskOutputBytes must be a positive number (or omitted to use the ${DEFAULT_MAX_TASK_OUTPUT_BYTES}-byte default) \u2014 got ${config.maxTaskOutputBytes}. Pass Number.POSITIVE_INFINITY to explicitly disable the cap; 0 or a negative number is rejected rather than silently treated as "disabled".`
     );
   }
+  validateProgressBatcherOptions(config.progressBatch);
   const presenceCadence = {
     intervalMs: config.presence?.intervalMs ?? DEFAULT_PRESENCE_HEARTBEAT_INTERVAL_MS,
     ttlMs: config.presence?.ttlMs ?? DEFAULT_PRESENCE_TTL_MS,
@@ -10489,6 +10644,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
   let controlServerHandle;
   let daemonOwnerLease;
   let presencePublisher;
+  let detectedRuntimeFacts = [];
   let presenceDiscovery;
   let presenceDiscoveryInFlight = false;
   let shutdownPromise;
@@ -10622,6 +10778,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
         Promise.resolve(new BlobClient(config.serverUrl, auth))
       ]);
       observer.noteRuntimesDetected(runtimes);
+      detectedRuntimeFacts = runtimes;
       const capabilities = computeCapabilities(adapters);
       const journalIdentity = config.hostedJournal ? { tenantId: config.hostedJournal.tenantId, productId: config.productId, deviceId: record.deviceId } : void 0;
       const sendEnvelope = activeJournal && journalIdentity ? (envelope) => {
@@ -10674,7 +10831,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
         // untouched. See `observer.ts`'s module doc comment.
         send: sendEnvelope,
         blobClient,
-        batcherOptions: overrides.batch,
+        batcherOptions: config.progressBatch,
         sessionWorkspaces,
         gitWorkspaceManager,
         gitWorkspaceStore,
@@ -10699,6 +10856,10 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
         approvalRegistry,
         storeDir,
         productId: config.productId,
+        // U2 terminal inference usage consumes the one U4a-resolved,
+        // process-immutable identity captured above. This is composition-only:
+        // TaskRunner receives no config, manifest, or second identity resolver.
+        localAgentRelease,
         approvalTimeoutMs: overrides.approvalTimeoutMs,
         // Finding F5(a): see TaskRunnerDeps.shutdownInterruptTimeoutMs's own doc comment.
         shutdownInterruptTimeoutMs: overrides.shutdown?.taskInterruptTimeoutMs,
@@ -10744,6 +10905,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
         deviceId: record.deviceId,
         productId: config.productId,
         capabilities,
+        clientVersion: localAgentRelease.version,
         runtimes,
         configuredToolsets,
         auth,
@@ -10833,6 +10995,9 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
             serverUrl: config.serverUrl,
             auth,
             configuredToolsets,
+            clientVersion: localAgentRelease.version,
+            protocolVersions: [PROTOCOL_VERSION],
+            runtimes: detectedRuntimeFacts,
             ...presenceCadence,
             onDegraded: (reason) => console.warn(`[byok/client] ${reason}`)
           });
@@ -11014,6 +11179,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
     const activeTasks = observer.tasks().filter((task) => TASK_TRANSITIONS[task.state].length > 0).map((task) => ({ taskId: task.taskId, state: task.state }));
     const pendingApprovals = approvalRegistry.list();
     return {
+      localAgentRelease,
       pid: process.pid,
       uptimeMs: startedAt !== void 0 ? Date.now() - startedAt : 0,
       paired: auth.deviceId !== void 0,
@@ -11212,6 +11378,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
   }
   function status() {
     return {
+      localAgentRelease,
       paired: auth.deviceId !== void 0,
       connected: connectionState === "open",
       degraded: connection?.isTransportDegraded() ?? false,
@@ -11841,6 +12008,13 @@ function createServiceLifecycle(def, opts = {}) {
       throw new UnsupportedServicePlatformError(platform);
   }
 }
+
+// src/bin/official-release.ts
+var OFFICIAL_LOCAL_AGENT_RELEASE = resolveLocalAgentReleaseIdentity({
+  version: "0.6.0"
+});
+
+// src/bin/config.ts
 var REQUIRED_FIELDS = ["productName", "productId", "serverUrl", "workspaceRoot"];
 var ConfigError = class extends Error {
   constructor(message) {
@@ -11863,6 +12037,9 @@ function loadConfig(configPath, overrides = {}) {
       throw new ConfigError(`config at "${configPath}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
+  if (Object.prototype.hasOwnProperty.call(base, "localAgentRelease") || Object.prototype.hasOwnProperty.call(overrides, "localAgentRelease")) {
+    throw new ConfigError('config field "localAgentRelease" is distribution-owned and must not be supplied');
+  }
   const merged = { ...base, ...overrides };
   if (merged.gitWorkspace !== void 0) {
     try {
@@ -11876,7 +12053,7 @@ function loadConfig(configPath, overrides = {}) {
       throw new ConfigError(`config is missing required field "${field}"`);
     }
   }
-  return merged;
+  return { ...merged, localAgentRelease: OFFICIAL_LOCAL_AGENT_RELEASE };
 }
 function resolveStoreDir(config) {
   return DeviceStore.resolveDir(config.productId, config.storeDir);
@@ -12050,6 +12227,9 @@ function formatStatusLines(view) {
   const lines = [];
   const label = view.branding?.displayName ?? view.productName;
   lines.push(`product: ${label} (${view.productId})`);
+  lines.push(
+    `local-agent-release: ${view.localAgentRelease.version}${view.localAgentRelease.buildId ? ` buildId=${view.localAgentRelease.buildId}` : ""}`
+  );
   if (view.branding?.supportUrl) lines.push(`support: ${view.branding.supportUrl}`);
   lines.push(`paired: ${view.paired ? "yes" : "no"}${view.deviceId ? ` deviceId=${view.deviceId}` : ""}`);
   lines.push(
@@ -12065,8 +12245,10 @@ function formatStatusLines(view) {
   return lines;
 }
 function formatLiveStatusLines(live) {
+  const liveRelease = live.localAgentRelease;
   const lines = [
     `live: pid=${live.pid} uptimeMs=${live.uptimeMs} transport=${live.transport}`,
+    liveRelease ? `live-local-agent-release: ${liveRelease.version}${liveRelease.buildId ? ` buildId=${liveRelease.buildId}` : ""}` : "live-local-agent-release: unknown",
     `live-paired: ${live.paired ? "yes" : "no"}${live.deviceId ? ` deviceId=${live.deviceId}` : ""}`,
     `live-runtimes: ${live.runtimeIds.length ? live.runtimeIds.join(",") : "(none)"}`
   ];
@@ -13755,6 +13937,7 @@ async function runStatusCommand(config, deps = {}) {
   ]);
   const tasks = deriveTasksFromEvents(events);
   const view = {
+    localAgentRelease: config.localAgentRelease,
     productName: config.productName,
     productId: config.productId,
     branding: config.branding,
@@ -14183,11 +14366,17 @@ async function runWorkspacesCommand(config, deps = {}) {
   for (const record of records) log(formatWorkspaceLine(record, deps.showPaths === true));
 }
 
+// src/bin/version.ts
+function runVersionCommand(log = console.log) {
+  log(OFFICIAL_LOCAL_AGENT_RELEASE.version);
+}
+
 // src/bin/byok-agent.ts
 function usage() {
   console.error(
     [
       "Usage:",
+      "  byok-agent --version",
       "  byok-agent pair <code> --server <url> [--config <path>]",
       "  byok-agent start [--config <path>]                        (or BYOK_CONFIG env var)",
       "  byok-agent status [--config <path>]",
@@ -14223,6 +14412,10 @@ function abortOnSignal() {
 }
 async function main() {
   const [, , command, ...rest] = process.argv;
+  if (command === "--version") {
+    runVersionCommand();
+    return;
+  }
   if (command === "pair") {
     const [code] = positionalArgs(rest, ["--server", "--config"]);
     const server = argValue(rest, "--server");