@covia/covia-sdk 1.7.4 → 1.9.0

package/dist/index.js

@@ -45,6 +45,15 @@ var GridError = class extends CoviaError {
     this.responseBody = responseBody;
   }
 };
+var UnsupportedVenueFeatureError = class extends CoviaError {
+  constructor(feature) {
+    super(
+      `The connected venue cannot serve ${feature} without creating a job. Invoke the corresponding operation explicitly if creating a persisted job is intended.`
+    );
+    this.feature = feature;
+    this.name = "UnsupportedVenueFeatureError";
+  }
+};
 var CoviaConnectionError = class extends CoviaError {
   constructor(message, options = {}) {
     super(message);
@@ -114,6 +123,14 @@ var JobNotFoundError = class extends NotFoundError {
     this.jobId = jobId;
   }
 };
+var AgentSessionNotFoundError = class extends CoviaError {
+  constructor(agentId, sessionId) {
+    super(`Agent session not found: ${agentId}/${sessionId}`, 404);
+    this.agentId = agentId;
+    this.sessionId = sessionId;
+    this.name = "AgentSessionNotFoundError";
+  }
+};
 
 // node_modules/.pnpm/@noble+ed25519@3.1.0/node_modules/@noble/ed25519/index.js
 var ed25519_CURVE = Object.freeze({
@@ -1033,9 +1050,13 @@ function privateKeyToHex(key) {
   return Array.from(key).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function hexToPrivateKey(hex) {
-  const bytes = new Uint8Array(hex.length / 2);
+  const cleaned = hex.startsWith("0x") || hex.startsWith("0X") ? hex.slice(2) : hex;
+  if (!/^[0-9a-fA-F]{64}$/.test(cleaned)) {
+    throw new Error("Invalid Ed25519 private key: expected 64 hex characters (32 bytes)");
+  }
+  const bytes = new Uint8Array(32);
   for (let i = 0; i < bytes.length; i++) {
-    bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+    bytes[i] = parseInt(cleaned.substring(i * 2, i * 2 + 2), 16);
   }
   return bytes;
 }
@@ -1149,6 +1170,14 @@ function createEdDSAJWT(privateKey, lifetimeSeconds = 300, audience) {
 }
 
 // src/Credentials.ts
+function base64Encode(text) {
+  const bytes = new TextEncoder().encode(text);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
 var Auth = class {
 };
 var NoAuth = class extends Auth {
@@ -1171,7 +1200,7 @@ var BasicAuth = class extends Auth {
     this._password = password;
   }
   apply(headers, _audience) {
-    const credentials = Buffer.from(`${this._username}:${this._password}`, "utf-8").toString("base64");
+    const credentials = base64Encode(`${this._username}:${this._password}`);
     headers["Authorization"] = `Basic ${credentials}`;
   }
 };
@@ -1188,7 +1217,13 @@ var Ed25519Auth = class _Ed25519Auth extends Auth {
     this._lifetime = tokenLifetimeSeconds;
   }
   apply(headers, audience) {
-    const jwt = createEdDSAJWT(this._privateKey, this._lifetime, this._audience ?? audience);
+    const aud = this._audience ?? (audience || void 0);
+    if (!aud) {
+      throw new CoviaError(
+        "Ed25519Auth requires a venue audience to bind the token to: connect via Grid.connect()/Venue.connect() so the venue DID is known, or pin auth.audience explicitly."
+      );
+    }
+    const jwt = createEdDSAJWT(this._privateKey, this._lifetime, aud);
     headers["Authorization"] = `Bearer ${jwt}`;
   }
   /** The caller's DID derived from the public key. */
@@ -1302,17 +1337,24 @@ async function parseErrorBody(response) {
   let body = null;
   let message = `Request failed with status ${response.status}`;
   try {
-    body = await response.json();
+    if (typeof response.text === "function") {
+      const text = await response.text();
+      if (text) {
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = text;
+          message = text;
+        }
+      }
+    } else {
+      body = await response.json();
+    }
     if (body && typeof body === "object" && "error" in body) {
       const err2 = body.error;
       if (typeof err2 === "string") message = err2;
     }
   } catch {
-    try {
-      const text = await response.text();
-      if (text) message = text;
-    } catch {
-    }
   }
   return { message, body };
 }
@@ -1606,13 +1648,82 @@ var AdapterManager = class {
   }
 };
 
-// src/AgentManager.ts
+// src/VenueTransport.ts
+function requestOptions(venue, options) {
+  const {
+    contentType,
+    headers: suppliedHeaders = {},
+    ...request
+  } = options;
+  const headers = { ...suppliedHeaders };
+  const effectiveContentType = contentType !== void 0 ? contentType : request.body != null ? "application/json" : null;
+  if (effectiveContentType && headers["Content-Type"] === void 0) {
+    headers["Content-Type"] = effectiveContentType;
+  }
+  venue.auth.apply(headers, venue.venueId);
+  return { ...request, headers };
+}
+function venueJson(venue, path, options = {}) {
+  return fetchWithError(
+    `${venue.baseUrl}${path}`,
+    requestOptions(venue, options)
+  );
+}
+function venueStream(venue, path, options = {}) {
+  return fetchStreamWithError(
+    `${venue.baseUrl}${path}`,
+    requestOptions(venue, options)
+  );
+}
+
+// src/venue-features.ts
 function versionAtLeast(version, major, minor) {
   const m = version?.match(/^(\d+)\.(\d+)/);
   if (!m) return true;
   const [maj, min] = [Number(m[1]), Number(m[2])];
   return maj > major || maj === major && min >= minor;
 }
+var ROUTE_MISSING_404 = /\bEndpoint (GET|POST|PUT|DELETE|PATCH|HEAD) /;
+
+// src/values-util.ts
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+var SLICE_PAGE_SIZE = 200;
+async function sliceAll(workspace, path, pageSize = SLICE_PAGE_SIZE) {
+  const items = [];
+  let offset = 0;
+  for (; ; ) {
+    const page = await workspace.slice(path, offset, pageSize);
+    if (!page.exists) {
+      if (items.length === 0) return items;
+      throw new CoviaError(`Sliceable value at ${path} disappeared mid-read`);
+    }
+    const values = page.values ?? [];
+    items.push(...values);
+    const nextOffset = (page.offset ?? offset) + values.length;
+    const done = page.count !== void 0 ? nextOffset >= page.count : values.length < pageSize;
+    if (values.length === 0 || done) break;
+    if (nextOffset <= offset) {
+      throw new CoviaError(`Venue returned a slice of ${path} that did not advance`);
+    }
+    offset = nextOffset;
+  }
+  return items;
+}
+
+// src/AgentManager.ts
+function sessionRecord(sessionId, value) {
+  const session = record(value) ?? {};
+  const meta = record(session.meta);
+  return {
+    id: sessionId,
+    metadata: meta ?? {},
+    pending: Array.isArray(session.pending) ? session.pending : [],
+    frames: Array.isArray(session.frames) ? session.frames : [],
+    wakeTime: typeof session.wakeTime === "number" ? session.wakeTime : void 0
+  };
+}
 var AgentManager = class {
   constructor(venue) {
     this.venue = venue;
@@ -1620,11 +1731,6 @@ var AgentManager = class {
     // pre-0.4 venues pay the probe once, not one failed GET per read (covia#180).
     this.agentsGetSupported = true;
   }
-  _headers() {
-    const headers = { "Content-Type": "application/json" };
-    this.venue.auth.apply(headers, this.venue.venueId);
-    return headers;
-  }
   /** Whether the venue serves `GET /api/v1/agents`: no if a probe already
    *  404'd, or if the venue's last known status identifies it as pre-0.4. */
   supportsAgentsGet() {
@@ -1635,25 +1741,25 @@ var AgentManager = class {
     }
     return this.agentsGetSupported;
   }
-  /** A job-free agents GET, falling back to the invoke path on pre-0.4 venues. */
-  async _agentsOr(path, params, fallback) {
+  /** A job-free agents GET that rejects when the endpoint is unavailable. */
+  async agentsGet(path, params) {
     if (this.supportsAgentsGet()) {
       try {
         const qs = new URLSearchParams();
         for (const [k, v] of Object.entries(params)) if (v !== void 0) qs.set(k, String(v));
         const q = qs.toString();
-        return await fetchWithError(
-          `${this.venue.baseUrl}/api/v1/agents${path}${q ? `?${q}` : ""}`,
-          { headers: this._headers() }
+        return await venueJson(
+          this.venue,
+          `/api/v1/agents${path}${q ? `?${q}` : ""}`
         );
       } catch (e) {
         if (!(e instanceof NotFoundError)) throw e;
-        const routeMissing = path === "" || /\bEndpoint (GET|POST|PUT|DELETE|PATCH|HEAD) /.test(e.message);
+        const routeMissing = path === "" || ROUTE_MISSING_404.test(e.message);
         if (!routeMissing) throw e;
         this.agentsGetSupported = false;
       }
     }
-    return fallback();
+    throw new UnsupportedVenueFeatureError("agent reads");
   }
   async create(input) {
     return this.venue.operations.run("v/ops/agent/create", input);
@@ -1698,10 +1804,10 @@ var AgentManager = class {
   /**
    * List the caller's agents. **Job-free** on covia ≥ 0.4: goes through
    * `GET /api/v1/agents` (covia#180) — synchronous, no Job persisted. Older
-   * venues transparently fall back to the invoke path (one probe, remembered).
+   * venues reject rather than silently creating a persisted Job.
    */
   async list(includeTerminated) {
-    const result = await this._agentsOr("", { includeTerminated }, () => this.venue.operations.run("v/ops/agent/list", { includeTerminated }));
+    const result = await this.agentsGet("", { includeTerminated });
     const raw = result?.agents ?? [];
     const agents = raw.map((a) => typeof a === "string" ? { agentId: a } : a);
     return { agents };
@@ -1722,9 +1828,61 @@ var AgentManager = class {
     return this.venue.operations.run("v/ops/agent/cancel-task", { agentId, taskId });
   }
   /** Agent info. **Job-free** on covia ≥ 0.4 (`GET /api/v1/agents/{id}`,
-   *  covia#180); older venues fall back to the invoke path. */
+   *  covia#180); older venues require an explicit compatibility opt-in. */
   async info(agentId) {
-    return this._agentsOr(`/${encodeURIComponent(agentId)}`, {}, () => this.venue.operations.run("v/ops/agent/info", { agentId }));
+    return this.agentsGet(`/${encodeURIComponent(agentId)}`, {});
+  }
+  /**
+   * Page an agent's sessions directly from `g/<agentId>/sessions`.
+   * This is a job-free Values read; session adapter-specific fields remain
+   * available on each record's `value` while common runtime fields are typed.
+   */
+  async listSessions(agentId, options = {}) {
+    const result = await this.venue.workspace.slice(
+      `g/${agentId}/sessions`,
+      options.offset,
+      options.limit
+    );
+    const sessions = (result.values ?? []).flatMap((entry) => {
+      const pair = record(entry);
+      if (!pair || typeof pair.key !== "string") return [];
+      return [sessionRecord(pair.key, pair.value)];
+    });
+    return {
+      items: sessions,
+      total: result.count ?? sessions.length,
+      offset: result.offset ?? options.offset ?? 0,
+      limit: options.limit ?? sessions.length
+    };
+  }
+  /** Read one agent session directly from the workspace Values surface. */
+  async getSession(agentId, sessionId) {
+    const path = `g/${agentId}/sessions/${sessionId}`;
+    const result = await this.venue.workspace.read(path);
+    if (!result.exists) {
+      throw new AgentSessionNotFoundError(agentId, sessionId);
+    }
+    if (result.truncated) {
+      return this._readLargeSession(path, sessionId);
+    }
+    if (result.value === void 0 || result.value === null) {
+      throw new AgentSessionNotFoundError(agentId, sessionId);
+    }
+    return sessionRecord(sessionId, result.value);
+  }
+  async _readLargeSession(path, sessionId) {
+    const [meta, wakeTime, pending, frames] = await Promise.all([
+      this.venue.workspace.read(`${path}/meta`),
+      this.venue.workspace.read(`${path}/wakeTime`),
+      sliceAll(this.venue.workspace, `${path}/pending`),
+      sliceAll(this.venue.workspace, `${path}/frames`)
+    ]);
+    return sessionRecord(sessionId, {
+      meta: meta.exists ? meta.value : void 0,
+      wakeTime: wakeTime.exists ? wakeTime.value : void 0,
+      pending,
+      frames
+    });
   }
   async fork(input) {
     return this.venue.operations.run("v/ops/agent/fork", input);
@@ -1886,23 +2044,50 @@ var Job = class {
 };
 
 // src/JobManager.ts
+function jobPage(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new CoviaError("Venue returned an invalid jobs listing");
+  }
+  const page = value;
+  if (!Array.isArray(page.items) || !page.items.every((item) => typeof item === "string") || !Number.isInteger(page.total) || (page.total ?? -1) < 0 || !Number.isInteger(page.offset) || (page.offset ?? -1) < 0 || !Number.isInteger(page.limit) || (page.limit ?? -1) < 0) {
+    throw new CoviaError("Venue returned an invalid jobs page");
+  }
+  return page;
+}
 var JobManager = class {
   constructor(venue) {
     this.venue = venue;
   }
   async list() {
-    const body = await fetchWithError(`${this.venue.baseUrl}/api/v1/jobs`, {
-      headers: this._buildHeaders()
-    });
-    if (Array.isArray(body)) return body;
-    const items = body?.items;
-    return Array.isArray(items) ? items : [];
+    const items = [];
+    let offset = 0;
+    let targetTotal;
+    while (targetTotal === void 0 || items.length < targetTotal) {
+      const body = await venueJson(
+        this.venue,
+        `/api/v1/jobs?offset=${offset}&limit=1000`
+      );
+      if (Array.isArray(body)) {
+        if (!body.every((item) => typeof item === "string")) {
+          throw new CoviaError("Venue returned an invalid jobs listing");
+        }
+        return body;
+      }
+      const page = jobPage(body);
+      targetTotal ?? (targetTotal = page.total);
+      items.push(...page.items);
+      if (page.items.length === 0) break;
+      const nextOffset = page.offset + page.items.length;
+      if (nextOffset <= offset) {
+        throw new CoviaError("Venue returned a jobs page that did not advance");
+      }
+      offset = nextOffset;
+    }
+    return items;
   }
   async get(jobId) {
     try {
-      const data = await fetchWithError(`${this.venue.baseUrl}/api/v1/jobs/${jobId}`, {
-        headers: this._buildHeaders()
-      });
+      const data = await venueJson(this.venue, `/api/v1/jobs/${jobId}`);
       return new Job(jobId, this.venue, data);
     } catch (error) {
       if (error instanceof NotFoundError) {
@@ -1913,9 +2098,8 @@ var JobManager = class {
   }
   async cancel(jobId) {
     try {
-      return await fetchWithError(`${this.venue.baseUrl}/api/v1/jobs/${jobId}/cancel`, {
-        method: "PUT",
-        headers: this._buildHeaders()
+      return await venueJson(this.venue, `/api/v1/jobs/${jobId}/cancel`, {
+        method: "PUT"
       });
     } catch (error) {
       if (error instanceof NotFoundError) {
@@ -1926,9 +2110,8 @@ var JobManager = class {
   }
   async delete(jobId) {
     try {
-      await fetchStreamWithError(`${this.venue.baseUrl}/api/v1/jobs/${jobId}/delete`, {
-        method: "PUT",
-        headers: this._buildHeaders()
+      await venueStream(this.venue, `/api/v1/jobs/${jobId}/delete`, {
+        method: "PUT"
       });
     } catch (error) {
       if (error instanceof NotFoundError) {
@@ -1939,9 +2122,8 @@ var JobManager = class {
   }
   async pause(jobId) {
     try {
-      return await fetchWithError(`${this.venue.baseUrl}/api/v1/jobs/${jobId}/pause`, {
-        method: "PUT",
-        headers: this._buildHeaders()
+      return await venueJson(this.venue, `/api/v1/jobs/${jobId}/pause`, {
+        method: "PUT"
       });
     } catch (error) {
       if (error instanceof NotFoundError) {
@@ -1952,9 +2134,8 @@ var JobManager = class {
   }
   async resume(jobId) {
     try {
-      return await fetchWithError(`${this.venue.baseUrl}/api/v1/jobs/${jobId}/resume`, {
-        method: "PUT",
-        headers: this._buildHeaders()
+      return await venueJson(this.venue, `/api/v1/jobs/${jobId}/resume`, {
+        method: "PUT"
       });
     } catch (error) {
       if (error instanceof NotFoundError) {
@@ -1965,9 +2146,8 @@ var JobManager = class {
   }
   async sendMessage(jobId, message) {
     try {
-      return await fetchWithError(`${this.venue.baseUrl}/api/v1/jobs/${jobId}`, {
+      return await venueJson(this.venue, `/api/v1/jobs/${jobId}`, {
         method: "POST",
-        headers: this._buildHeaders(),
         body: JSON.stringify(message)
       });
     } catch (error) {
@@ -1978,16 +2158,11 @@ var JobManager = class {
     }
   }
   async *stream(jobId) {
-    const response = await fetchStreamWithError(`${this.venue.baseUrl}/api/v1/jobs/${jobId}/sse`, {
-      headers: { ...this._buildHeaders(), "Accept": "text/event-stream" }
+    const response = await venueStream(this.venue, `/api/v1/jobs/${jobId}/sse`, {
+      headers: { "Accept": "text/event-stream" }
     });
     yield* parseSSEStream(response);
   }
-  _buildHeaders() {
-    const headers = { "Content-Type": "application/json" };
-    this.venue.auth.apply(headers, this.venue.venueId);
-    return headers;
-  }
 };
 
 // src/Asset.ts
@@ -2067,10 +2242,12 @@ var DataAsset = class extends Asset {
 };
 
 // src/AssetManager.ts
-var cache = /* @__PURE__ */ new Map();
 var AssetManager = class {
   constructor(venue) {
     this.venue = venue;
+    // Memory cache is manager/venue-local. Content-addressed metadata may still
+    // be shared deliberately through the configured persistent metadata store.
+    this.cache = /* @__PURE__ */ new Map();
   }
   /**
    * Get an asset by lattice address.
@@ -2083,23 +2260,25 @@ var AssetManager = class {
    * @returns Returns either an Operation or DataAsset based on the asset's metadata
    */
   async get(assetId) {
-    if (cache.has(assetId)) {
-      return this._wrap(assetId, cache.get(assetId));
+    if (this.cache.has(assetId)) {
+      return this._wrap(assetId, this.cache.get(assetId));
     }
     const hash = assetHash(assetId);
     if (hash) {
       const persisted = getAssetMetadataStore()?.get(normaliseHash(hash));
       if (persisted) {
-        cache.set(assetId, persisted);
+        this.cache.set(assetId, persisted);
         return this._wrap(assetId, persisted);
       }
     }
     try {
-      const data = await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`, {
-        headers: this._buildHeaders(null)
-      });
+      const data = await venueJson(
+        this.venue,
+        `/api/v1/assets/${assetId}`,
+        { contentType: null }
+      );
       if (hash) {
-        cache.set(assetId, data);
+        this.cache.set(assetId, data);
         getAssetMetadataStore()?.put(normaliseHash(hash), data);
       }
       return this._wrap(assetId, data);
@@ -2126,18 +2305,19 @@ var AssetManager = class {
     if (options.limit !== void 0) {
       params.set("limit", String(options.limit));
     }
-    return fetchWithError(`${this.venue.baseUrl}/api/v1/assets?${params.toString()}`, {
-      headers: this._buildHeaders(null)
-    });
+    return venueJson(
+      this.venue,
+      `/api/v1/assets?${params.toString()}`,
+      { contentType: null }
+    );
   }
   /**
    * Register a new asset
    * @param assetData - Asset configuration
    */
   async register(assetData) {
-    return fetchWithError(`${this.venue.baseUrl}/api/v1/assets`, {
+    return venueJson(this.venue, "/api/v1/assets", {
       method: "POST",
-      headers: this._buildHeaders(),
       body: JSON.stringify(assetData)
     }).then((response) => this.get(response));
   }
@@ -2147,9 +2327,11 @@ var AssetManager = class {
    */
   async getMetadata(assetId) {
     try {
-      return await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}`, {
-        headers: this._buildHeaders(null)
-      });
+      return await venueJson(
+        this.venue,
+        `/api/v1/assets/${assetId}`,
+        { contentType: null }
+      );
     } catch (error) {
       if (error instanceof NotFoundError) {
         throw new AssetNotFoundError(assetId);
@@ -2165,9 +2347,9 @@ var AssetManager = class {
    */
   async putContent(assetId, content) {
     try {
-      return await fetchWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}/content`, {
+      return await venueJson(this.venue, `/api/v1/assets/${assetId}/content`, {
         method: "PUT",
-        headers: this._buildHeaders(null),
+        contentType: null,
         body: content
       });
     } catch (error) {
@@ -2183,9 +2365,11 @@ var AssetManager = class {
    */
   async getContent(assetId) {
     try {
-      const response = await fetchStreamWithError(`${this.venue.baseUrl}/api/v1/assets/${assetId}/content`, {
-        headers: this._buildHeaders(null)
-      });
+      const response = await venueStream(
+        this.venue,
+        `/api/v1/assets/${assetId}/content`,
+        { contentType: null }
+      );
       return response.body;
     } catch (error) {
       if (error instanceof NotFoundError) {
@@ -2206,17 +2390,11 @@ var AssetManager = class {
    * Clear the asset cache.
    */
   clearCache() {
-    cache.clear();
-    getAssetMetadataStore()?.clear();
+    this.cache.clear();
   }
-  // `contentType` defaults to JSON for the metadata/register endpoints. Pass
-  // `undefined` for binary content upload so fetch infers the type from the
-  // body — forcing application/json would mislabel a Blob/ArrayBuffer/stream.
-  _buildHeaders(contentType = "application/json") {
-    const headers = {};
-    if (contentType) headers["Content-Type"] = contentType;
-    this.venue.auth.apply(headers, this.venue.venueId);
-    return headers;
+  /** Clear the explicitly configured cross-session metadata store. */
+  clearPersistentCache() {
+    getAssetMetadataStore()?.clear();
   }
 };
 
@@ -2229,23 +2407,23 @@ var OperationManager = class {
    * List all named operations available on this venue
    */
   async list() {
-    return fetchWithError(`${this.venue.baseUrl}/api/v1/operations`);
+    return venueJson(this.venue, "/api/v1/operations");
   }
   /**
    * Get details of a named operation
    * @param name - Operation name (e.g., "v/ops/schema/infer")
    */
   async get(name) {
-    return fetchWithError(`${this.venue.baseUrl}/api/v1/operations/${name}`);
+    return venueJson(this.venue, `/api/v1/operations/${name}`);
   }
   /**
    * Execute an operation and wait for the result
    * @param assetId - Operation asset ID or named operation
    * @param input - Operation input parameters
-   * @param options - Invoke options (e.g., ucans)
+   * @param options - Execution options (e.g., ucans or private execution)
    */
   async run(assetId, input, options) {
-    if (this.venue.privateJobs) {
+    if (options?.private ?? this.venue.privateJobs) {
       return this._runPrivate(assetId, input, options);
     }
     const job = await this.invoke(assetId, input, options);
@@ -2267,9 +2445,8 @@ var OperationManager = class {
       wait: true
     };
     if (options?.ucans) payload.ucans = options.ucans;
-    const rec = await fetchWithError(`${this.venue.baseUrl}/api/v1/invoke`, {
+    const rec = await venueJson(this.venue, "/api/v1/invoke", {
       method: "POST",
-      headers: this._buildHeaders(),
       body: JSON.stringify(payload)
     });
     const status = rec.status;
@@ -2281,6 +2458,7 @@ var OperationManager = class {
       const job = new Job(rec.id ?? "", this.venue, rec);
       return await job.result();
     } catch (e) {
+      if (!(e instanceof NotFoundError)) throw e;
       throw new CoviaError(
         `Private job completed while unobserved \u2014 its record is already forgotten, so the result could not be collected. Private jobs that outlive the venue wait window cannot be reliably collected; consider a non-private run for long operations. (${e.message})`
       );
@@ -2293,7 +2471,7 @@ var OperationManager = class {
    * @param options - Invoke options (e.g., ucans)
    */
   async invoke(assetId, input, options) {
-    if (this.venue.privateJobs) {
+    if (options?.private ?? this.venue.privateJobs) {
       throw new CoviaError(
         "Private-jobs mode requires run(): a completed private job is immediately forgotten by the venue, so a poll-style Job cannot collect its result."
       );
@@ -2305,27 +2483,15 @@ var OperationManager = class {
     if (options?.ucans) {
       payload.ucans = options.ucans;
     }
-    const response = await fetchWithError(`${this.venue.baseUrl}/api/v1/invoke`, {
+    const response = await venueJson(this.venue, "/api/v1/invoke", {
       method: "POST",
-      headers: this._buildHeaders(),
       body: JSON.stringify(payload)
     });
     return new Job(response.id ?? "", this.venue, response);
   }
-  _buildHeaders() {
-    const headers = { "Content-Type": "application/json" };
-    this.venue.auth.apply(headers, this.venue.venueId);
-    return headers;
-  }
 };
 
 // src/WorkspaceManager.ts
-function versionAtLeast2(version, major, minor) {
-  const m = version?.match(/^(\d+)\.(\d+)/);
-  if (!m) return true;
-  const [maj, min] = [Number(m[1]), Number(m[2])];
-  return maj > major || maj === major && min >= minor;
-}
 var WorkspaceManager = class {
   constructor(venue) {
     this.venue = venue;
@@ -2333,16 +2499,11 @@ var WorkspaceManager = class {
     // so pre-0.3 venues pay the probe once, not one failed GET per read.
     this.valuesSupported = true;
   }
-  _headers() {
-    const headers = { "Content-Type": "application/json" };
-    this.venue.auth.apply(headers, this.venue.venueId);
-    return headers;
-  }
   /** GET a job-free `/api/v1/values/{op}` read; omit undefined params. */
   _values(op, params) {
     const qs = new URLSearchParams();
     for (const [k, v] of Object.entries(params)) if (v !== void 0) qs.set(k, String(v));
-    return fetchWithError(`${this.venue.baseUrl}/api/v1/values/${op}?${qs.toString()}`, { headers: this._headers() });
+    return venueJson(this.venue, `/api/v1/values/${op}?${qs.toString()}`);
   }
   /**
    * Whether the venue serves `GET /api/v1/values/*`: no if a probe already
@@ -2353,40 +2514,46 @@ var WorkspaceManager = class {
   supportsValues() {
     if (!this.valuesSupported) return false;
     const status = this.venue.lastKnownStatus;
-    if (status && (!status.version || !versionAtLeast2(status.version, 0, 3))) {
+    if (status && (!status.version || !versionAtLeast(status.version, 0, 3))) {
       this.valuesSupported = false;
     }
     return this.valuesSupported;
   }
-  /** A job-free values read, falling back to the invoke path on pre-0.3 venues. */
-  async _valuesOr(op, params, fallback) {
+  unsupported(feature) {
+    throw new UnsupportedVenueFeatureError(feature);
+  }
+  /** A job-free Values read that rejects when the endpoint is unavailable. */
+  async valuesRead(op, params) {
     if (this.supportsValues()) {
       try {
         return await this._values(op, params);
       } catch (e) {
         if (!(e instanceof NotFoundError)) throw e;
+        if (!ROUTE_MISSING_404.test(e.message)) throw e;
         this.valuesSupported = false;
       }
     }
-    return fallback();
+    return this.unsupported(`workspace ${op} reads`);
   }
   // ── job-free reads (#177) ───────────────────────────────────────────────────
   async read(path, maxSize, ucans) {
-    if (ucans?.length) return this.venue.operations.run("v/ops/covia/read", { path, maxSize }, { ucans });
-    return this._valuesOr("read", { path, maxSize }, () => this.venue.operations.run("v/ops/covia/read", { path, maxSize }));
+    if (ucans?.length) return this.unsupported("UCAN-authorised workspace reads");
+    return this.valuesRead("read", { path, maxSize });
   }
   async list(path, limit, offset, ucans) {
     path = path || "/";
-    if (ucans?.length) return this.venue.operations.run("v/ops/covia/list", { path, limit, offset }, { ucans });
-    return this._valuesOr("list", { path, limit, offset }, () => this.venue.operations.run("v/ops/covia/list", { path, limit, offset }));
+    if (ucans?.length) return this.unsupported("UCAN-authorised workspace listings");
+    return this.valuesRead("list", { path, limit, offset });
   }
   async slice(path, offset, limit, ucans) {
-    if (ucans?.length) return this.venue.operations.run("v/ops/covia/slice", { path, offset, limit }, { ucans });
-    return this._valuesOr("slice", { path, offset, limit }, () => this.venue.operations.run("v/ops/covia/slice", { path, offset, limit }));
+    if (ucans?.length) return this.unsupported("UCAN-authorised workspace slices");
+    return this.valuesRead("slice", { path, offset, limit });
   }
   async inspect(paths, budget, compact, ucans) {
-    if (ucans?.length || Array.isArray(paths)) return this.venue.operations.run("v/ops/covia/inspect", { paths, budget, compact }, { ucans });
-    return this._valuesOr("inspect", { path: paths, budget, compact }, () => this.venue.operations.run("v/ops/covia/inspect", { paths, budget, compact }));
+    if (ucans?.length || Array.isArray(paths)) return this.unsupported(
+      Array.isArray(paths) ? "multi-path workspace inspection" : "UCAN-authorised workspace inspection"
+    );
+    return this.valuesRead("inspect", { path: paths, budget, compact });
   }
   /**
    * Count entries at a depth below `path` — a job-free server-side tally, so the
@@ -2398,8 +2565,8 @@ var WorkspaceManager = class {
    */
   async count(path, opts = {}) {
     const { depth, ucans } = opts;
-    if (ucans?.length) return this.venue.operations.run("v/ops/covia/aggregate", { path, depth }, { ucans });
-    return this._valuesOr("count", { path, depth }, () => this.venue.operations.run("v/ops/covia/aggregate", { path, depth }));
+    if (ucans?.length) return this.unsupported("UCAN-authorised workspace counts");
+    return this.valuesRead("count", { path, depth });
   }
   /**
    * Count entries at a depth below `path`, optionally partitioned by a field —
@@ -2411,8 +2578,8 @@ var WorkspaceManager = class {
    */
   async aggregate(path, opts = {}) {
     const { depth, groupBy, ucans } = opts;
-    if (ucans?.length) return this.venue.operations.run("v/ops/covia/aggregate", { path, depth, groupBy }, { ucans });
-    return this._valuesOr("aggregate", { path, depth, groupBy }, () => this.venue.operations.run("v/ops/covia/aggregate", { path, depth, groupBy }));
+    if (ucans?.length) return this.unsupported("UCAN-authorised workspace aggregation");
+    return this.valuesRead("aggregate", { path, depth, groupBy });
   }
   // ── writes stay on the job path (they should leave an audit record) ─────────
   async write(path, value, ucans) {
@@ -2473,6 +2640,121 @@ var SecretManager = class {
   }
 };
 
+// src/SkillManager.ts
+var PAGE_SIZE = 100;
+var SkillManager = class {
+  constructor(venue) {
+    this.venue = venue;
+  }
+  /** Return every skill asset directly contained at `path`. */
+  async list(path) {
+    const location = path.replace(/\/+$/, "");
+    const skills = [];
+    let offset = 0;
+    for (; ; ) {
+      const page = await this.venue.workspace.list(location, PAGE_SIZE, offset);
+      if (!page.exists) {
+        if (skills.length === 0) return [];
+        throw new CoviaError(`Skill listing at ${location} disappeared mid-listing`);
+      }
+      const keys = page.keys ?? [];
+      const assets = await Promise.all(
+        keys.map((key) => this.get(`${location}/${key}`))
+      );
+      skills.push(...assets);
+      const nextOffset = (page.offset ?? offset) + keys.length;
+      if (keys.length === 0 || nextOffset >= (page.count ?? nextOffset)) break;
+      if (nextOffset <= offset) {
+        throw new CoviaError("Venue returned a skills page that did not advance");
+      }
+      offset = nextOffset;
+    }
+    return skills;
+  }
+  /** Return the ordinary asset at exactly `path`, with typed skill metadata. */
+  async get(path) {
+    return this.venue.assets.get(path);
+  }
+};
+
+// src/MemoryManager.ts
+var DEFAULT_MEMORY_PATH = "w/memory";
+function memoryChange(value) {
+  const result = record(value);
+  if (typeof result?.n !== "number" || typeof result.count !== "number") {
+    throw new CoviaError("Venue returned an invalid memory mutation result");
+  }
+  return { number: result.n, count: result.count };
+}
+var MemoryManager = class {
+  constructor(venue) {
+    this.venue = venue;
+  }
+  /**
+   * Read memory directly from the workspace Values surface. This is job-free;
+   * unlike `v/ops/memory {command:'recall'}`, it returns structured entries
+   * rather than an LLM-oriented numbered text block.
+   */
+  async list(path = DEFAULT_MEMORY_PATH) {
+    const result = await this.venue.workspace.read(path);
+    if (!result.exists) {
+      return [];
+    }
+    let raw;
+    if (result.truncated) {
+      raw = await sliceAll(this.venue.workspace, path);
+    } else if (result.value === void 0 || result.value === null) {
+      return [];
+    } else if (Array.isArray(result.value)) {
+      raw = result.value;
+    } else {
+      throw new CoviaError(`Memory at ${path} is not a flat list`);
+    }
+    const entries = raw.map((value, index) => {
+      const item = record(value);
+      const text = typeof value === "string" ? value : typeof item?.text === "string" ? item.text : void 0;
+      if (text === void 0) {
+        throw new CoviaError(`Memory entry ${index + 1} at ${path} has no text`);
+      }
+      return {
+        number: index + 1,
+        text,
+        createdAt: typeof item?.ts === "number" ? item.ts : void 0,
+        updatedAt: typeof item?.updated === "number" ? item.updated : void 0
+      };
+    });
+    return entries;
+  }
+  /** Append a memory entry. Mutations intentionally remain audited Jobs. */
+  async remember(text, path = DEFAULT_MEMORY_PATH) {
+    const result = await this.venue.operations.run("v/ops/memory", {
+      command: "remember",
+      text,
+      path
+    });
+    return memoryChange(result);
+  }
+  /** Replace a 1-based memory entry. Mutations intentionally remain audited Jobs. */
+  async update(number, text, path = DEFAULT_MEMORY_PATH) {
+    const result = await this.venue.operations.run("v/ops/memory", {
+      command: "update",
+      n: number,
+      text,
+      path
+    });
+    return memoryChange(result);
+  }
+  /** Remove a 1-based memory entry. Mutations intentionally remain audited Jobs. */
+  async forget(number, path = DEFAULT_MEMORY_PATH) {
+    const result = await this.venue.operations.run("v/ops/memory", {
+      command: "forget",
+      n: number,
+      path
+    });
+    return memoryChange(result);
+  }
+};
+
 // src/Agent.ts
 var Agent = class _Agent {
   constructor(id, venue) {
@@ -2514,6 +2796,14 @@ var Agent = class _Agent {
   async info() {
     return this._agents.info(this.id);
   }
+  /** Page this agent's sessions through the job-free workspace Values API. */
+  async listSessions(options) {
+    return this._agents.listSessions(this.id, options);
+  }
+  /** Read one session through the job-free workspace Values API. */
+  async getSession(sessionId) {
+    return this._agents.getSession(this.id, sessionId);
+  }
   /**
    * Fork this agent into a new agent.
    * @param agentId - ID for the new forked agent
@@ -2598,7 +2888,11 @@ function connectionFailureMessage(venueId, attempts) {
 }
 var Venue = class _Venue {
   constructor(options = {}) {
-    /** Connection-level private-jobs mode — see {@link setPrivate}. */
+    this._closed = false;
+    /**
+     * Connection-level private-jobs mode — see {@link setPrivate}.
+     * @deprecated Pass `{ private: true }` to `operations.run()` instead.
+     */
     this.privateJobs = false;
     this.baseUrl = options.baseUrl || "";
     this.venueId = options.venueId || "";
@@ -2609,6 +2903,10 @@ var Venue = class _Venue {
       description: options.description || ""
     };
   }
+  /** Whether this handle has been closed and should not be reused by Grid. */
+  get closed() {
+    return this._closed;
+  }
   /**
    * Puts this connection in **private-jobs mode**: every subsequent
    * `operations.run(...)` executes as a memory-only job (covia #192) — never
@@ -2617,7 +2915,10 @@ var Venue = class _Venue {
    *
    * Because a completed private job is immediately forgotten, results are
    * collected through the invoke `wait` window rather than polling — so
-   * private mode works with `run()`; a poll-style `invoke()` throws.
+  * private mode works with `run()`; a poll-style `invoke()` throws.
+   *
+   * @deprecated Pass `{ private: true }` to `operations.run()` instead. The
+   * per-call option avoids mutable connection-wide execution state.
    */
   setPrivate(enabled) {
     this.privateJobs = enabled;
@@ -2646,6 +2947,12 @@ var Venue = class _Venue {
   get secrets() {
     return this._secrets ?? (this._secrets = new SecretManager(this));
   }
+  get skills() {
+    return this._skills ?? (this._skills = new SkillManager(this));
+  }
+  get memory() {
+    return this._memory ?? (this._memory = new MemoryManager(this));
+  }
   /**
    * Connect to a venue, validating it with `GET {base}/api/v1/status`. If the
    * venue is auth-gated (status answers 401/403 — public access disabled), the
@@ -2675,7 +2982,7 @@ var Venue = class _Venue {
         baseUrl: venueId.baseUrl,
         venueId: venueId.venueId,
         name: venueId.metadata.name,
-        auth,
+        auth: auth ?? venueId.auth,
         status: venueId.lastKnownStatus
       });
       await connected.status();
@@ -2694,7 +3001,7 @@ var Venue = class _Venue {
         if (typeof endpoint !== "string") {
           throw new CoviaError("No (string) endpoint found for DID");
         }
-        candidates = [endpoint.replace(/\/api\/v1/, "")];
+        candidates = [stripTrailingSlash(endpoint).replace(/\/api\/v1$/, "")];
       } else {
         candidates = venueBaseUrlCandidates(venueId);
       }
@@ -2702,7 +3009,11 @@ var Venue = class _Venue {
       for (const baseUrl of candidates) {
         const statusUrl = baseUrl + "/api/v1/status";
         try {
-          const data = await fetchWithError(statusUrl);
+          const data = await venueJson({
+            baseUrl,
+            venueId: expectedDid ?? "",
+            auth: new NoAuth()
+          }, "/api/v1/status");
           if (!data.did) {
             throw new CoviaError(`Venue status at ${statusUrl} did not include a DID`);
           }
@@ -2787,9 +3098,10 @@ var Venue = class _Venue {
    * @returns {Promise<string[]>}
    */
   async listSecrets() {
-    const result = await fetchWithError(`${this.baseUrl}/api/v1/secrets`, {
-      headers: this._buildHeaders()
-    });
+    const result = await venueJson(
+      this,
+      "/api/v1/secrets"
+    );
     return Array.isArray(result.items) ? result.items : [];
   }
   /**
@@ -2797,9 +3109,8 @@ var Venue = class _Venue {
    * @param name - Secret name
    */
   async deleteSecret(name) {
-    await fetchStreamWithError(`${this.baseUrl}/api/v1/secrets/${encodeURIComponent(name)}`, {
-      method: "DELETE",
-      headers: this._buildHeaders()
+    await venueStream(this, `/api/v1/secrets/${encodeURIComponent(name)}`, {
+      method: "DELETE"
     });
   }
   /**
@@ -2808,7 +3119,7 @@ var Venue = class _Venue {
    * @throws {VenueIdentityChangedError} If this address reports a different known DID.
    */
   async status() {
-    const data = await fetchWithError(`${this.baseUrl}/api/v1/status`);
+    const data = await venueJson(this, "/api/v1/status");
     if (data.did) {
       if (this.venueId) {
         assertVenueIdentity(this.venueId, data.did, this.baseUrl);
@@ -2876,7 +3187,8 @@ var Venue = class _Venue {
    * Clears cached asset data for this venue.
    */
   close() {
-    this.assets.clearCache();
+    this._closed = true;
+    this._assets?.clearCache();
   }
   /**
    * Disposable support — allows `using venue = await Grid.connect(...)` in TS 5.2+.
@@ -2884,15 +3196,28 @@ var Venue = class _Venue {
   [Symbol.dispose]() {
     this.close();
   }
-  _buildHeaders() {
-    const headers = { "Content-Type": "application/json" };
-    this.auth.apply(headers, this.venueId);
-    return headers;
-  }
 };
 
 // src/Grid.ts
-var cache2 = /* @__PURE__ */ new Map();
+var anonymousConnections = /* @__PURE__ */ new Map();
+var authenticatedConnections = /* @__PURE__ */ new WeakMap();
+function connectionsFor(auth) {
+  if (!auth) return anonymousConnections;
+  let connections = authenticatedConnections.get(auth);
+  if (!connections) {
+    connections = /* @__PURE__ */ new Map();
+    authenticatedConnections.set(auth, connections);
+  }
+  return connections;
+}
+function normaliseKey(venueId) {
+  return venueId.replace(/\/+$/, "");
+}
+function removeEntry(cache, entry) {
+  for (const [key, candidate] of cache) {
+    if (candidate === entry) cache.delete(key);
+  }
+}
 var Grid = class {
   /**
   * Static method to connect to a venue
@@ -2901,18 +3226,34 @@ var Grid = class {
   * @returns {Promise<Venue>} A new Venue instance configured appropriately
   */
   static async connect(venueId, auth) {
-    const cached = cache2.get(venueId);
-    if (cached && cached.auth === auth)
-      return cached.venue;
-    const connectedVenue = await Venue.connect(venueId, auth);
-    cache2.set(venueId, { auth, venue: connectedVenue });
-    return connectedVenue;
+    const cache = connectionsFor(auth);
+    const key = normaliseKey(venueId);
+    const cached = cache.get(key);
+    if (cached) {
+      if (!cached.venue?.closed) return cached.promise;
+      removeEntry(cache, cached);
+    }
+    const entry = {};
+    entry.promise = Venue.connect(venueId, auth).then((venue) => {
+      entry.venue = venue;
+      cache.set(normaliseKey(venue.baseUrl), entry);
+      if (key.startsWith("did:")) {
+        cache.set(normaliseKey(venue.venueId), entry);
+      }
+      return venue;
+    }).catch((error) => {
+      removeEntry(cache, entry);
+      throw error;
+    });
+    cache.set(key, entry);
+    return entry.promise;
   }
 };
 
 // src/crypto/ucan.ts
 var encoder2 = new TextEncoder();
 var VENUE_RELAY = "venue/relay";
+var UCV_VERSION = "0.10.0";
 function didFor(privateKey) {
   return `did:key:${encodePublicKey(getPublicKey2(privateKey))}`;
 }
@@ -2923,10 +3264,11 @@ function createUCANJWT(privateKey, audienceDID, att, lifetimeSeconds, proofs = [
   const claims = {
     iss: `did:key:${multikey}`,
     aud: audienceDID,
+    ucv: UCV_VERSION,
     att,
-    exp: nowSecs + lifetimeSeconds
+    prf: proofs,
+    exp: lifetimeSeconds === null ? null : nowSecs + lifetimeSeconds
   };
-  if (proofs.length) claims.prf = proofs;
   const signingInput = `${base64UrlEncode(encoder2.encode(header))}.${base64UrlEncode(encoder2.encode(JSON.stringify(claims)))}`;
   const signature = sign(encoder2.encode(signingInput), privateKey);
   return `${signingInput}.${base64UrlEncode(signature)}`;
@@ -2950,6 +3292,7 @@ function relayDelegation(privateKey, venueDID, lifetimeSeconds, caps = []) {
 exports.AdapterManager = AdapterManager;
 exports.Agent = Agent;
 exports.AgentManager = AgentManager;
+exports.AgentSessionNotFoundError = AgentSessionNotFoundError;
 exports.AgentStatus = AgentStatus;
 exports.Asset = Asset;
 exports.AssetManager = AssetManager;
@@ -2972,6 +3315,7 @@ exports.JobManager = JobManager;
 exports.JobNotFoundError = JobNotFoundError;
 exports.JobStatus = JobStatus;
 exports.KeyPairAuth = KeyPairAuth;
+exports.MemoryManager = MemoryManager;
 exports.Namespace = Namespace;
 exports.NoAuth = NoAuth;
 exports.NotFoundError = NotFoundError;
@@ -2980,7 +3324,9 @@ exports.OperationManager = OperationManager;
 exports.RateLimitError = RateLimitError;
 exports.RunStatus = RunStatus;
 exports.SecretManager = SecretManager;
+exports.SkillManager = SkillManager;
 exports.UCANManager = UCANManager;
+exports.UnsupportedVenueFeatureError = UnsupportedVenueFeatureError;
 exports.VENUE_RELAY = VENUE_RELAY;
 exports.Venue = Venue;
 exports.VenueIdentityChangedError = VenueIdentityChangedError;