@byok-sdk/client 0.5.0 → 0.6.0

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,
@@ -8508,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]));
@@ -8807,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. */
@@ -9185,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);
@@ -9197,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;
       }
@@ -9270,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;
@@ -9322,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 }
             )
@@ -9439,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). */
@@ -9877,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. */
@@ -9895,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 —
@@ -10426,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()
@@ -10539,6 +10644,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
   let controlServerHandle;
   let daemonOwnerLease;
   let presencePublisher;
+  let detectedRuntimeFacts = [];
   let presenceDiscovery;
   let presenceDiscoveryInFlight = false;
   let shutdownPromise;
@@ -10672,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) => {
@@ -10749,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,
@@ -10794,6 +10905,7 @@ function buildDaemonWithAdapters(config, adapters, overrides = {}, assertionProb
         deviceId: record.deviceId,
         productId: config.productId,
         capabilities,
+        clientVersion: localAgentRelease.version,
         runtimes,
         configuredToolsets,
         auth,
@@ -10883,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}`)
           });
@@ -11064,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,
@@ -11262,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,
@@ -11891,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) {
@@ -11913,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 {
@@ -11926,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);
@@ -12100,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(
@@ -12115,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)"}`
   ];
@@ -13805,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,
@@ -14233,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>]",
@@ -14273,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");