@zocomputer/agent-sdk 0.5.0

package/dist/platform/runtime-ai/index.js

@@ -0,0 +1,91 @@
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-ai/gateway.ts
+import { createGateway } from "ai";
+
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-ai/session-fetch.ts
+var EVE_SESSION_HEADER = "x-zo-eve-session";
+var EVE_TURN_HEADER = "x-zo-eve-turn";
+var EVE_CONTEXT_STORAGE_KEY = Symbol.for("eve.context-storage");
+var SESSION_ID_KEY_NAME = "eve.sessionId";
+var SESSION_KEY_NAME = "eve.session";
+function hasMethod(value, name) {
+  return typeof value === "object" && value !== null && typeof value[name] === "function";
+}
+function ambientEveSessionId() {
+  const value = ambientContextValue(SESSION_ID_KEY_NAME);
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function ambientEveTurnId() {
+  const session = ambientContextValue(SESSION_KEY_NAME);
+  if (typeof session !== "object" || session === null)
+    return;
+  const turn = session["turn"];
+  if (typeof turn !== "object" || turn === null)
+    return;
+  const id = turn["id"];
+  return typeof id === "string" && id.trim().length > 0 ? id : undefined;
+}
+function ambientContextValue(keyName) {
+  const storage = Reflect.get(globalThis, EVE_CONTEXT_STORAGE_KEY);
+  if (!hasMethod(storage, "getStore"))
+    return;
+  const store = storage.getStore();
+  if (!hasMethod(store, "get"))
+    return;
+  return store.get({ name: keyName });
+}
+function eveSessionFetch(getSessionId = ambientEveSessionId, baseFetch = globalThis.fetch, getTurnId = ambientEveTurnId) {
+  return Object.assign((input, init) => {
+    const sessionId = getSessionId()?.trim();
+    if (!sessionId)
+      return baseFetch(input, init);
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    headers.set(EVE_SESSION_HEADER, sessionId);
+    const turnId = getTurnId()?.trim();
+    if (turnId)
+      headers.set(EVE_TURN_HEADER, turnId);
+    else
+      headers.delete(EVE_TURN_HEADER);
+    return baseFetch(input, { ...init, headers });
+  }, baseFetch);
+}
+
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-ai/gateway.ts
+var ZO_TOOL_HEADER = "x-zo-tool";
+var DEFAULT_ZO_AI_BASE_URL = "http://localhost:4000/runtime/ai/v4/ai";
+var DEFAULT_ZO_AI_KEY = "dev-proxy";
+var AGENT_TOKEN_HEADER = "x-zo-agent-token";
+var AGENT_TOKEN_ENV = "ZO_AGENT_TOKEN";
+function agentAuthHeaders(token = process.env[AGENT_TOKEN_ENV]) {
+  const trimmed = token?.trim();
+  return trimmed ? { [AGENT_TOKEN_HEADER]: trimmed } : {};
+}
+function resolveZoGatewayBaseUrl(baseURL = process.env.ZO_AI_BASE_URL) {
+  const trimmed = baseURL?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_ZO_AI_BASE_URL;
+}
+function resolveZoGatewayApiKey(apiKey = process.env.ZO_AI_KEY) {
+  const trimmed = apiKey?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_ZO_AI_KEY;
+}
+function zoGateway(options = {}) {
+  return createGateway({
+    ...options,
+    headers: { ...agentAuthHeaders(), ...options.headers },
+    apiKey: resolveZoGatewayApiKey(options.apiKey),
+    baseURL: resolveZoGatewayBaseUrl(options.baseURL),
+    fetch: eveSessionFetch(undefined, options.fetch)
+  });
+}
+export {
+  zoGateway,
+  resolveZoGatewayBaseUrl,
+  resolveZoGatewayApiKey,
+  eveSessionFetch,
+  ambientEveTurnId,
+  ambientEveSessionId,
+  ZO_TOOL_HEADER,
+  EVE_TURN_HEADER,
+  EVE_SESSION_HEADER,
+  DEFAULT_ZO_AI_KEY,
+  DEFAULT_ZO_AI_BASE_URL
+};

package/dist/platform/runtime-ai/register.js

@@ -0,0 +1,88 @@
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-ai/gateway.ts
+import { createGateway } from "ai";
+
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-ai/session-fetch.ts
+var EVE_SESSION_HEADER = "x-zo-eve-session";
+var EVE_TURN_HEADER = "x-zo-eve-turn";
+var EVE_CONTEXT_STORAGE_KEY = Symbol.for("eve.context-storage");
+var SESSION_ID_KEY_NAME = "eve.sessionId";
+var SESSION_KEY_NAME = "eve.session";
+function hasMethod(value, name) {
+  return typeof value === "object" && value !== null && typeof value[name] === "function";
+}
+function ambientEveSessionId() {
+  const value = ambientContextValue(SESSION_ID_KEY_NAME);
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function ambientEveTurnId() {
+  const session = ambientContextValue(SESSION_KEY_NAME);
+  if (typeof session !== "object" || session === null)
+    return;
+  const turn = session["turn"];
+  if (typeof turn !== "object" || turn === null)
+    return;
+  const id = turn["id"];
+  return typeof id === "string" && id.trim().length > 0 ? id : undefined;
+}
+function ambientContextValue(keyName) {
+  const storage = Reflect.get(globalThis, EVE_CONTEXT_STORAGE_KEY);
+  if (!hasMethod(storage, "getStore"))
+    return;
+  const store = storage.getStore();
+  if (!hasMethod(store, "get"))
+    return;
+  return store.get({ name: keyName });
+}
+function eveSessionFetch(getSessionId = ambientEveSessionId, baseFetch = globalThis.fetch, getTurnId = ambientEveTurnId) {
+  return Object.assign((input, init) => {
+    const sessionId = getSessionId()?.trim();
+    if (!sessionId)
+      return baseFetch(input, init);
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    headers.set(EVE_SESSION_HEADER, sessionId);
+    const turnId = getTurnId()?.trim();
+    if (turnId)
+      headers.set(EVE_TURN_HEADER, turnId);
+    else
+      headers.delete(EVE_TURN_HEADER);
+    return baseFetch(input, { ...init, headers });
+  }, baseFetch);
+}
+
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-ai/gateway.ts
+var DEFAULT_ZO_AI_BASE_URL = "http://localhost:4000/runtime/ai/v4/ai";
+var DEFAULT_ZO_AI_KEY = "dev-proxy";
+var AGENT_TOKEN_HEADER = "x-zo-agent-token";
+var AGENT_TOKEN_ENV = "ZO_AGENT_TOKEN";
+function agentAuthHeaders(token = process.env[AGENT_TOKEN_ENV]) {
+  const trimmed = token?.trim();
+  return trimmed ? { [AGENT_TOKEN_HEADER]: trimmed } : {};
+}
+function resolveZoGatewayBaseUrl(baseURL = process.env.ZO_AI_BASE_URL) {
+  const trimmed = baseURL?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_ZO_AI_BASE_URL;
+}
+function resolveZoGatewayApiKey(apiKey = process.env.ZO_AI_KEY) {
+  const trimmed = apiKey?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_ZO_AI_KEY;
+}
+function zoGateway(options = {}) {
+  return createGateway({
+    ...options,
+    headers: { ...agentAuthHeaders(), ...options.headers },
+    apiKey: resolveZoGatewayApiKey(options.apiKey),
+    baseURL: resolveZoGatewayBaseUrl(options.baseURL),
+    fetch: eveSessionFetch(undefined, options.fetch)
+  });
+}
+
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-ai/register.ts
+var SLOT = "AI_SDK_DEFAULT_PROVIDER";
+if (!(SLOT in globalThis)) {
+  Object.defineProperty(globalThis, SLOT, {
+    value: zoGateway(),
+    writable: false,
+    configurable: false,
+    enumerable: false
+  });
+}

package/dist/platform/runtime-ai/session-fetch.js

@@ -0,0 +1,54 @@
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-ai/session-fetch.ts
+var EVE_SESSION_HEADER = "x-zo-eve-session";
+var EVE_TURN_HEADER = "x-zo-eve-turn";
+var EVE_CONTEXT_STORAGE_KEY = Symbol.for("eve.context-storage");
+var SESSION_ID_KEY_NAME = "eve.sessionId";
+var SESSION_KEY_NAME = "eve.session";
+function hasMethod(value, name) {
+  return typeof value === "object" && value !== null && typeof value[name] === "function";
+}
+function ambientEveSessionId() {
+  const value = ambientContextValue(SESSION_ID_KEY_NAME);
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function ambientEveTurnId() {
+  const session = ambientContextValue(SESSION_KEY_NAME);
+  if (typeof session !== "object" || session === null)
+    return;
+  const turn = session["turn"];
+  if (typeof turn !== "object" || turn === null)
+    return;
+  const id = turn["id"];
+  return typeof id === "string" && id.trim().length > 0 ? id : undefined;
+}
+function ambientContextValue(keyName) {
+  const storage = Reflect.get(globalThis, EVE_CONTEXT_STORAGE_KEY);
+  if (!hasMethod(storage, "getStore"))
+    return;
+  const store = storage.getStore();
+  if (!hasMethod(store, "get"))
+    return;
+  return store.get({ name: keyName });
+}
+function eveSessionFetch(getSessionId = ambientEveSessionId, baseFetch = globalThis.fetch, getTurnId = ambientEveTurnId) {
+  return Object.assign((input, init) => {
+    const sessionId = getSessionId()?.trim();
+    if (!sessionId)
+      return baseFetch(input, init);
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    headers.set(EVE_SESSION_HEADER, sessionId);
+    const turnId = getTurnId()?.trim();
+    if (turnId)
+      headers.set(EVE_TURN_HEADER, turnId);
+    else
+      headers.delete(EVE_TURN_HEADER);
+    return baseFetch(input, { ...init, headers });
+  }, baseFetch);
+}
+export {
+  eveSessionFetch,
+  ambientEveTurnId,
+  ambientEveSessionId,
+  EVE_TURN_HEADER,
+  EVE_SESSION_HEADER
+};

package/dist/platform/runtime-auth/index.js

@@ -0,0 +1,141 @@
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/platform/runtime-auth/index.ts
+import { SignJWT, jwtVerify } from "jose";
+var AGENT_TOKEN_HEADER = "x-zo-agent-token";
+var EVE_SESSION_HEADER = "x-zo-eve-session";
+var EVE_TURN_HEADER = "x-zo-eve-turn";
+var AGENT_TOKEN_ENV = "ZO_AGENT_TOKEN";
+var ZO_PLATFORM_ORG = {
+  id: "org_zo",
+  name: "Zo",
+  slug: "zo"
+};
+var BUILDER_AGENT_IDENTITY = {
+  agentProjectId: "agt_builder",
+  ownerOrgId: ZO_PLATFORM_ORG.id
+};
+var LOCAL_AGENT_IDENTITY = {
+  agentProjectId: "agt_local",
+  ownerOrgId: ZO_PLATFORM_ORG.id
+};
+var RESERVED_AGENT_PROJECT_IDS = [
+  BUILDER_AGENT_IDENTITY.agentProjectId,
+  LOCAL_AGENT_IDENTITY.agentProjectId
+];
+var ISSUER = "zo-api";
+var AGENT_TOKEN_TYP = "zo-agent";
+var defaultClock = () => Math.floor(Date.now() / 1000);
+function key(secret) {
+  return new TextEncoder().encode(secret);
+}
+function asString(v) {
+  return typeof v === "string" && v.length > 0 ? v : undefined;
+}
+async function mintAgentToken(input) {
+  const now = (input.clock ?? defaultClock)();
+  const payload = {
+    typ: AGENT_TOKEN_TYP,
+    agentProjectId: input.claims.agentProjectId,
+    ownerOrgId: input.claims.ownerOrgId,
+    ...input.claims.deploymentId ? { deploymentId: input.claims.deploymentId } : {}
+  };
+  return new SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuer(ISSUER).setIssuedAt(now).setExpirationTime(now + input.ttlSeconds).sign(key(input.secret));
+}
+async function verifyAgentToken(token, secret, clock = defaultClock) {
+  try {
+    const { payload } = await jwtVerify(token, key(secret), {
+      issuer: ISSUER,
+      currentDate: new Date(clock() * 1000)
+    });
+    if (payload.typ !== AGENT_TOKEN_TYP)
+      return null;
+    const agentProjectId = asString(payload.agentProjectId);
+    const ownerOrgId = asString(payload.ownerOrgId);
+    if (!agentProjectId || !ownerOrgId)
+      return null;
+    const deploymentId = asString(payload.deploymentId);
+    return { agentProjectId, ownerOrgId, ...deploymentId ? { deploymentId } : {} };
+  } catch {
+    return null;
+  }
+}
+async function resolveAgentContext(agentToken, secret, eveSessionId, clock = defaultClock) {
+  const claims = await verifyAgentToken(agentToken, secret, clock);
+  if (!claims)
+    return null;
+  return {
+    actor: {
+      kind: "agent",
+      agentProjectId: claims.agentProjectId,
+      ownerOrgId: claims.ownerOrgId,
+      ...claims.deploymentId ? { deploymentId: claims.deploymentId } : {}
+    },
+    ...eveSessionId ? { eveSessionId } : {}
+  };
+}
+var IDENTITY_BEARER_TYP = "zo-identity";
+async function mintIdentityBearer(input) {
+  const now = (input.clock ?? defaultClock)();
+  const payload = {
+    typ: IDENTITY_BEARER_TYP,
+    userId: input.claims.userId,
+    agentId: input.claims.agentId
+  };
+  return new SignJWT(payload).setProtectedHeader({ alg: "HS256" }).setIssuer(ISSUER).setIssuedAt(now).setExpirationTime(now + input.ttlSeconds).sign(key(input.secret));
+}
+async function verifyIdentityBearer(bearer, secret, clock = defaultClock) {
+  try {
+    const { payload } = await jwtVerify(bearer, key(secret), {
+      issuer: ISSUER,
+      currentDate: new Date(clock() * 1000)
+    });
+    if (payload.typ !== IDENTITY_BEARER_TYP)
+      return null;
+    const userId = asString(payload.userId);
+    const agentId = asString(payload.agentId);
+    if (!userId || !agentId)
+      return null;
+    return { userId, agentId };
+  } catch {
+    return null;
+  }
+}
+var INITIATOR_HEADER = "x-zo-initiator";
+function formatInitiator(identity) {
+  return JSON.stringify({ userId: identity.userId, agentId: identity.agentId });
+}
+function parseInitiator(value) {
+  if (!value)
+    return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null)
+    return null;
+  const { userId, agentId } = parsed;
+  if (typeof userId !== "string" || !userId)
+    return null;
+  if (typeof agentId !== "string" || !agentId)
+    return null;
+  return { userId, agentId };
+}
+export {
+  verifyIdentityBearer,
+  verifyAgentToken,
+  resolveAgentContext,
+  parseInitiator,
+  mintIdentityBearer,
+  mintAgentToken,
+  formatInitiator,
+  ZO_PLATFORM_ORG,
+  RESERVED_AGENT_PROJECT_IDS,
+  LOCAL_AGENT_IDENTITY,
+  INITIATOR_HEADER,
+  EVE_TURN_HEADER,
+  EVE_SESSION_HEADER,
+  BUILDER_AGENT_IDENTITY,
+  AGENT_TOKEN_HEADER,
+  AGENT_TOKEN_ENV
+};

package/dist/state-files.js

@@ -0,0 +1,287 @@
+// ../../var/folders/vh/qdfcqc514qj47bbvzslcwjsc0000gn/T/agent-sdk-publish-eDWqsZ/src/state-files.ts
+var STATE_FILES_HANDLE_PATH = "/state/handles";
+var ZO_AGENT_TOKEN_HEADER = "x-zo-agent-token";
+var ZO_EVE_SESSION_HEADER = "x-zo-eve-session";
+
+class StateFilesHandleError extends Error {
+  status;
+  code;
+  constructor(message, options) {
+    super(message);
+    this.name = "StateFilesHandleError";
+    this.status = options.status;
+    this.code = options.code ?? null;
+  }
+}
+async function requestStateFilesHandle(options) {
+  const response = await options.fetch(buildStateFilesHandleUrl(options.apiBaseUrl), {
+    method: "POST",
+    headers: buildStateFilesHandleHeaders(options),
+    body: JSON.stringify(buildStateFilesHandleRequest(options))
+  });
+  const json = await response.json().catch(() => null);
+  if (!response.ok) {
+    const error = parseStateFilesBrokerError(json);
+    throw new StateFilesHandleError(error.message, {
+      status: response.status,
+      code: error.code
+    });
+  }
+  const handle = parseStateFilesHandle(json);
+  if (handle === null) {
+    throw new StateFilesHandleError("state files broker returned a malformed handle", {
+      status: response.status,
+      code: "malformed_handle"
+    });
+  }
+  return handle;
+}
+function parseStateFilesHandle(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const credentials = parseStateFilesCredentials(value.credentials);
+  if (credentials === null) {
+    return null;
+  }
+  const access = parseStateFilesAccess(value.access);
+  if (access === null) {
+    return null;
+  }
+  if (value.interface !== "files" || value.engine !== "zo-blob-r2") {
+    return null;
+  }
+  const handleId = readString(value, "handleId");
+  const declarationName = readString(value, "declarationName");
+  const storeId = readString(value, "storeId");
+  const stateInstanceId = readString(value, "stateInstanceId");
+  const partition = parseStateFilesPartition(value.partition);
+  const bucketName = readString(value, "bucketName");
+  const endpoint = readString(value, "endpoint");
+  if (handleId === null || declarationName === null || storeId === null || stateInstanceId === null || partition === null || bucketName === null || endpoint === null) {
+    return null;
+  }
+  return Object.freeze({
+    handleId,
+    declarationName,
+    interface: "files",
+    access,
+    engine: "zo-blob-r2",
+    storeId,
+    stateInstanceId,
+    partition,
+    bucketName,
+    endpoint,
+    credentials
+  });
+}
+function createStateFilesClient(options) {
+  return createStateFilesClientFromHandleSource({
+    getHandle: async () => options.handle,
+    s3: options.s3
+  });
+}
+function createRefreshingStateFilesClient(options) {
+  let cached = null;
+  const now = options.now ?? (() => new Date);
+  const refreshWindowMs = options.refreshWindowMs ?? 60000;
+  return createStateFilesClientFromHandleSource({
+    getHandle: async () => {
+      if (cached === null || shouldRefreshStateFilesHandle(cached, now(), refreshWindowMs)) {
+        cached = await options.loadHandle();
+      }
+      return cached;
+    },
+    s3: options.s3
+  });
+}
+function shouldRefreshStateFilesHandle(handle, now, refreshWindowMs = 60000) {
+  const expiresAtMs = Date.parse(handle.credentials.expiresAt);
+  if (!Number.isFinite(expiresAtMs)) {
+    return true;
+  }
+  return expiresAtMs - now.getTime() <= refreshWindowMs;
+}
+function createStateFilesClientFromHandleSource(options) {
+  return {
+    async list(prefix) {
+      const handle = await options.getHandle();
+      const normalizedPrefix = normalizeStateFilePrefix(prefix);
+      return options.s3.listObjects({
+        ...buildS3Context(handle),
+        ...normalizedPrefix === undefined ? {} : { prefix: normalizedPrefix }
+      });
+    },
+    async read(path) {
+      const handle = await options.getHandle();
+      return options.s3.readObject({
+        ...buildS3Context(handle),
+        key: normalizeStateFilePath(path)
+      });
+    },
+    async write(path, body, writeOptions) {
+      const handle = await options.getHandle();
+      assertStateFilesWriteAccess(handle);
+      return options.s3.writeObject({
+        ...buildS3Context(handle),
+        key: normalizeStateFilePath(path),
+        body,
+        ...writeOptions?.contentType === undefined ? {} : { contentType: writeOptions.contentType }
+      });
+    },
+    async delete(path) {
+      const handle = await options.getHandle();
+      assertStateFilesWriteAccess(handle);
+      return options.s3.deleteObject({
+        ...buildS3Context(handle),
+        key: normalizeStateFilePath(path)
+      });
+    }
+  };
+}
+function normalizeStateFilePath(path) {
+  if (path.length === 0) {
+    throw new Error("state file path must not be empty");
+  }
+  if (path.startsWith("/")) {
+    throw new Error(`state file path "${path}" must be relative`);
+  }
+  const segments = path.split("/");
+  if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+    throw new Error(`state file path "${path}" must not contain empty, . or .. segments`);
+  }
+  return path;
+}
+function normalizeStateFilePrefix(prefix) {
+  if (prefix === undefined || prefix.length === 0) {
+    return;
+  }
+  if (prefix.endsWith("/")) {
+    return normalizeStateFilePath(prefix.slice(0, -1)) + "/";
+  }
+  return normalizeStateFilePath(prefix);
+}
+function buildStateFilesHandleRequest(options) {
+  const request = {
+    declarationName: options.declarationName,
+    interface: "files",
+    access: options.access
+  };
+  return request;
+}
+function buildStateFilesHandleUrl(apiBaseUrl) {
+  const url = new URL(String(apiBaseUrl));
+  url.pathname = joinUrlPath(url.pathname, STATE_FILES_HANDLE_PATH);
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+function joinUrlPath(basePath, childPath) {
+  const base = basePath.replace(/\/+$/, "");
+  const child = childPath.replace(/^\/+/, "");
+  return `${base}/${child}`;
+}
+function buildStateFilesHandleHeaders(options) {
+  const headers = createHeaders(options.headers);
+  headers.set("content-type", "application/json");
+  if (options.agentToken !== undefined) {
+    headers.set(ZO_AGENT_TOKEN_HEADER, options.agentToken);
+  }
+  if (options.eveSessionKey !== undefined) {
+    headers.set(ZO_EVE_SESSION_HEADER, options.eveSessionKey);
+  }
+  return headers;
+}
+function createHeaders(init) {
+  const headers = new Headers;
+  if (init === undefined) {
+    return headers;
+  }
+  if (init instanceof Headers) {
+    init.forEach((value, key) => headers.set(key, value));
+    return headers;
+  }
+  if (Array.isArray(init)) {
+    for (const [key, value] of init) {
+      headers.set(key, value);
+    }
+    return headers;
+  }
+  for (const [key, value] of Object.entries(init)) {
+    headers.set(key, value);
+  }
+  return headers;
+}
+function parseStateFilesBrokerError(value) {
+  if (!isRecord(value)) {
+    return { message: "state files broker request failed", code: null };
+  }
+  const routeError = readString(value, "error");
+  if (routeError !== null) {
+    return {
+      message: readString(value, "message") ?? "state files broker request failed",
+      code: routeError
+    };
+  }
+  const error = isRecord(value.error) ? value.error : value;
+  const message = readString(error, "message") ?? "state files broker request failed";
+  const code = readString(error, "code") ?? readString(error, "error");
+  return { message, code };
+}
+function parseStateFilesCredentials(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const accessKeyId = readString(value, "accessKeyId");
+  const secretAccessKey = readString(value, "secretAccessKey");
+  const sessionToken = readString(value, "sessionToken");
+  const expiresAt = readString(value, "expiresAt");
+  if (accessKeyId === null || secretAccessKey === null || sessionToken === null || expiresAt === null || !Number.isFinite(Date.parse(expiresAt))) {
+    return null;
+  }
+  return Object.freeze({ accessKeyId, secretAccessKey, sessionToken, expiresAt });
+}
+function parseStateFilesPartition(value) {
+  if (value === "none" || value === "team" || value === "user" || value === "session") {
+    return value;
+  }
+  return null;
+}
+function parseStateFilesAccess(value) {
+  if (value === "r" || value === "rw") {
+    return value;
+  }
+  return null;
+}
+function buildS3Context(handle) {
+  return {
+    endpoint: handle.endpoint,
+    bucketName: handle.bucketName,
+    credentials: handle.credentials
+  };
+}
+function assertStateFilesWriteAccess(handle) {
+  if (handle.access !== "rw") {
+    throw new Error(`state files handle "${handle.handleId}" is read-only`);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(record, key) {
+  const value = record[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+export {
+  shouldRefreshStateFilesHandle,
+  requestStateFilesHandle,
+  parseStateFilesHandle,
+  normalizeStateFilePrefix,
+  normalizeStateFilePath,
+  createStateFilesClient,
+  createRefreshingStateFilesClient,
+  ZO_EVE_SESSION_HEADER,
+  ZO_AGENT_TOKEN_HEADER,
+  StateFilesHandleError,
+  STATE_FILES_HANDLE_PATH
+};