@covia/covia-sdk 1.18.0 → 1.19.1

package/dist/index.js

@@ -37,6 +37,13 @@ var CoviaError = class extends Error {
     this.message = message;
   }
 };
+var MCPError = class extends CoviaError {
+  constructor(message, code, data) {
+    super(message, code);
+    this.name = "MCPError";
+    this.data = data;
+  }
+};
 var GridError = class extends CoviaError {
   constructor(statusCode, message, responseBody = null) {
     super(`HTTP ${statusCode}: ${message}`, statusCode);
@@ -1598,17 +1605,17 @@ async function* parseSSEStream(response, options) {
 // src/asset-cache.ts
 var PREFIX = "covia:asset-meta:";
 var LocalStorageMetadataStore = class {
-  get(hash) {
+  get(key) {
     try {
-      const raw = localStorage.getItem(PREFIX + hash);
+      const raw = localStorage.getItem(PREFIX + key);
       return raw ? JSON.parse(raw) : void 0;
     } catch {
       return void 0;
     }
   }
-  put(hash, metadata) {
+  put(key, metadata) {
     try {
-      localStorage.setItem(PREFIX + hash, JSON.stringify(metadata));
+      localStorage.setItem(PREFIX + key, JSON.stringify(metadata));
     } catch {
     }
   }
@@ -1641,6 +1648,15 @@ function getAssetMetadataStore() {
 function normaliseHash(hash) {
   return (hash.startsWith("0x") ? hash.slice(2) : hash).toLowerCase();
 }
+function persistentCacheKey(ref) {
+  const parsed = parseDidUrl(ref);
+  if (!parsed.did) return null;
+  if (parsed.namespace !== Namespace.ASSET) return null;
+  const hash = assetHash(ref);
+  if (!hash) return null;
+  const bare = normaliseHash(hash);
+  return /^[0-9a-f]+$/.test(bare) ? `${parsed.did}/${Namespace.ASSET}/${bare}` : null;
+}
 
 // src/AdapterManager.ts
 var ADAPTERS_PATH = "v/info/adapters";
@@ -2458,6 +2474,14 @@ var AssetManager = class {
    * a mutable lattice path the venue resolves (`w/my-assets/foo`, `o/my-op`,
    * `<DID>/w/...`). Only content-addressed (immutable) refs are cached;
    * mutable paths are always re-fetched, so a changed value is never served stale.
+   *
+   * **Content-addressed refs are caller-relative, not global** (covia#502). A
+   * bare hash or `a/<hash>` names the asset in *your own* `a/` namespace, so it
+   * 404s for a hash someone else registered, and for an anonymous request.
+   * Address another owner's asset explicitly as `<ownerDID>/a/<hash>`, and the
+   * venue's own catalog as `<venueDID>/a/<hash>`. Only the DID-qualified form
+   * is portable, so only it is eligible for the cross-session metadata store;
+   * caller-relative refs are cached in memory on this manager alone.
    * @param assetId - Asset identifier or lattice address
    * @returns Returns either an Operation or DataAsset based on the asset's metadata
    */
@@ -2466,8 +2490,9 @@ var AssetManager = class {
       return this._wrap(assetId, this.cache.get(assetId));
     }
     const hash = assetHash(assetId);
-    if (hash) {
-      const persisted = getAssetMetadataStore()?.get(normaliseHash(hash));
+    const storeKey = persistentCacheKey(assetId);
+    if (storeKey) {
+      const persisted = getAssetMetadataStore()?.get(storeKey);
       if (persisted) {
         this.cache.set(assetId, persisted);
         return this._wrap(assetId, persisted);
@@ -2481,7 +2506,7 @@ var AssetManager = class {
       );
       if (hash) {
         this.cache.set(assetId, data);
-        getAssetMetadataStore()?.put(normaliseHash(hash), data);
+        if (storeKey) getAssetMetadataStore()?.put(storeKey, data);
       }
       return this._wrap(assetId, data);
     } catch (error) {
@@ -2717,6 +2742,7 @@ var OperationManager = class {
 // src/WorkspaceManager.ts
 var SCOPED_NAMESPACES = ["t", "n", "c"];
 var SCOPE_UNEXPANDED = /Cannot use '[tnc]\/' prefix outside/;
+var MAX_PROJECT_FIELDS = 16;
 function scopedNamespaceOf(path) {
   const head = path.split("/", 1)[0];
   return SCOPED_NAMESPACES.includes(head) ? head : void 0;
@@ -2761,6 +2787,11 @@ var WorkspaceManager = class {
     // selector-bearing read by complaining the shorthand has no execution scope,
     // after which scoped reads expand client-side instead.
     this.scopeExpansionSupported = true;
+    // Whether this venue projects fields on `list` (covia#191). A venue without
+    // it ignores the unknown `fields` param and answers a plain list, so the
+    // probe is "asked for fields, got no values" — never a version check, which
+    // covia-sdk#36 showed an embedded venue can misreport.
+    this.fieldsSupported = true;
   }
   /** GET a job-free `/api/v1/values/{op}` read; omit undefined params. */
   _values(op, params) {
@@ -2850,6 +2881,76 @@ var WorkspaceManager = class {
     if (ucans?.length) return this.unsupported("UCAN-authorised workspace listings");
     return this.valuesRead("list", { path, limit, offset });
   }
+  /**
+   * List a node's children *and* read named subpaths of each one, in a single
+   * round trip (covia#191) — the standard partial-response / sparse-fieldset
+   * pattern, and the cure for the collection-view N+1 that list-then-read-each
+   * forces on every page.
+   *
+   * ```ts
+   * const page = await venue.workspace.listFields('j', ['status', 'meta/updated'], { limit: 50 });
+   * page.values['<jobid>']['status']; // → { exists: true, value: 'COMPLETE' }
+   * ```
+   *
+   * Each field is defined as a `read` of `<path>/<key>/<field>` and carries
+   * single-read semantics verbatim: stored null is present, absent is
+   * `{exists:false}`, and a value past `maxSize` withholds `value` and sets
+   * `truncated`. Projection applies *after* the `limit`/`offset` key page, so
+   * work is bounded by `limit × fields.length`.
+   *
+   * Output shape only — no filtering, no ordering. Filter the projected
+   * records locally; for a recency subset use key design plus `slice`.
+   *
+   * On a venue that predates projection this falls back to `list()` plus a
+   * bounded `read()` per (key, field), returning the identical shape, and
+   * remembers not to ask that venue again.
+   *
+   * @param path Parent node. Must be a keyed node (map/Index) — a sequence or
+   *   scalar is a venue 400.
+   * @param fields Subpaths to project per key; may be nested (`meta/updated`).
+   *   At most 16, the venue's cap.
+   */
+  async listFields(path, fields, opts = {}) {
+    const { limit, offset, maxSize } = opts;
+    if (fields.length === 0) throw new CoviaError("listFields needs at least one field");
+    if (fields.length > MAX_PROJECT_FIELDS) {
+      throw new CoviaError(
+        `A fields projection may name at most ${MAX_PROJECT_FIELDS} subpaths; got ${fields.length}`
+      );
+    }
+    if (this.fieldsSupported) {
+      const result = await this.valuesRead(
+        "list",
+        { path, limit, offset, fields: fields.join(","), maxSize }
+      );
+      if (result.values) return result;
+      if (!result.exists || result.keys === void 0) return { ...result, values: {} };
+      this.fieldsSupported = false;
+    }
+    return this.projectClientSide(path, fields, { limit, offset, maxSize });
+  }
+  /**
+   * The pre-covia#191 fallback: one `list`, then a `read` per (key, field).
+   * Fan-out is bounded by the page the list already returned, so this costs
+   * `keys.length × fields.length` reads for the page — exactly the N+1 the
+   * server-side projection exists to remove, which is why it is the fallback
+   * and not the default.
+   */
+  async projectClientSide(path, fields, opts) {
+    const base = await this.valuesRead(
+      "list",
+      { path, limit: opts.limit, offset: opts.offset }
+    );
+    const keys = base.keys ?? [];
+    const parent = path.replace(/\/+$/, "");
+    const rows = await Promise.all(keys.map(async (key) => {
+      const projected = await Promise.all(fields.map(async (field) => {
+        return [field, await this.read(`${parent}/${key}/${field}`, opts.maxSize)];
+      }));
+      return [key, Object.fromEntries(projected)];
+    }));
+    return { ...base, values: Object.fromEntries(rows) };
+  }
   async slice(path, offset, limit, ucans) {
     if (ucans?.length) return this.unsupported("UCAN-authorised workspace slices");
     return this.valuesRead("slice", { path, offset, limit });
@@ -3246,6 +3347,185 @@ var A2AManager = class {
   }
 };
 
+// src/MCPManager.ts
+var TOOL_CALL_OP = "v/ops/mcp/tools-call";
+var DEFAULT_MCP_PATH = "/mcp";
+var HEADER_SESSION_ID = "Mcp-Session-Id";
+function isResponseFrame(value) {
+  return typeof value === "object" && value !== null && ("result" in value || "error" in value);
+}
+var MCPManager = class {
+  constructor(venue) {
+    this.venue = venue;
+    this.nextId = 1;
+  }
+  /** The venue's MCP discovery document (`GET /.well-known/mcp`). */
+  discovery() {
+    return this.venue.mcpDiscovery();
+  }
+  /**
+   * List the tools this venue bridges, job-free.
+   *
+   * @param options.cursor Continue a previous page. MCP pagination is opaque:
+   *   pass back the `nextCursor` a page returned, and stop when it is absent.
+   */
+  async listTools(options = {}) {
+    const params = options.cursor !== void 0 ? { cursor: options.cursor } : {};
+    const result = await this.request(
+      "tools/list",
+      params,
+      { signal: options.signal }
+    );
+    const page = { tools: result?.tools ?? [] };
+    if (result?.nextCursor !== void 0) page.nextCursor = result.nextCursor;
+    return page;
+  }
+  /**
+   * Every tool the venue bridges, draining the cursor.
+   *
+   * A server that never stops handing back a cursor would loop forever, so a
+   * repeated cursor is treated as the end rather than trusted.
+   */
+  async listAllTools(options = {}) {
+    const tools = [];
+    const seen = /* @__PURE__ */ new Set();
+    let cursor;
+    for (; ; ) {
+      const page = await this.listTools({ cursor, signal: options.signal });
+      tools.push(...page.tools);
+      if (page.nextCursor === void 0 || seen.has(page.nextCursor)) return tools;
+      seen.add(page.nextCursor);
+      cursor = page.nextCursor;
+    }
+  }
+  /**
+   * Call a bridged tool natively and return its MCP result.
+   *
+   * This is the direct protocol call: the answer comes back in the response,
+   * and the caller never holds a Job. The venue still runs the tool through
+   * its job machinery and records it — "direct" describes what *this* call
+   * hands back, not whether the venue keeps a record.
+   *
+   * Use {@link callToolTracked} when you want the `Job` itself: to stream it,
+   * inspect its steps, link to its receipt, or continue it when it pauses.
+   *
+   * An MCP tool that fails *its own* execution answers with `isError: true`
+   * and the failure in `content` — a successful protocol call reporting a
+   * failed tool, which is not thrown. Only a protocol-level error throws.
+   */
+  async callTool(name, args = {}, options = {}) {
+    return this.request(
+      "tools/call",
+      { name, arguments: args },
+      { signal: options.signal }
+    );
+  }
+  /**
+   * Call a tool through the `v/ops/mcp/tools-call` operation, returning the
+   * `Job` so the run is an inspectable, linkable record.
+   *
+   * The operation is the venue's bridge to *any* MCP server, so `server`
+   * defaults to this venue's own base URL — pointing the bridge back at the
+   * venue, which is how a local tool gets called with a Job in hand. Name a
+   * different `server` (with a `token` if it needs one) to reach a third-party
+   * MCP server through the venue instead, which the native endpoint cannot do.
+   *
+   * Unlike {@link callTool} this always persists a job, so it belongs to a
+   * user-driven execution, never a page load.
+   */
+  async callToolTracked(name, args = {}, options = {}) {
+    const { server, token, ...invokeOptions } = options;
+    const input = {
+      server: server ?? this.venue.baseUrl,
+      toolName: name,
+      arguments: args
+    };
+    if (token !== void 0) input.token = token;
+    return this.venue.operations.invoke(TOOL_CALL_OP, input, invokeOptions);
+  }
+  /**
+   * Send an arbitrary JSON-RPC method to the venue's MCP endpoint — the escape
+   * hatch for methods this manager does not wrap (`resources/list`,
+   * `prompts/list`, …).
+   *
+   * Request ids are minted and correlated here, so callers never supply one.
+   */
+  async request(method, params = {}, options = {}) {
+    const id = this.nextId++;
+    const endpoint = await this.endpoint();
+    const headers = {
+      // The venue may answer either way; advertise both and branch on what
+      // comes back rather than assuming JSON (which is the bug in every
+      // hand-rolled copy of this call).
+      Accept: "application/json, text/event-stream"
+    };
+    if (this.sessionId) headers[HEADER_SESSION_ID] = this.sessionId;
+    const response = await venueStream(this.venue, endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ jsonrpc: "2.0", id, method, params }),
+      signal: options.signal
+    });
+    const session = response.headers?.get?.(HEADER_SESSION_ID);
+    if (session) this.sessionId = session;
+    const frame = (response.headers?.get?.("Content-Type") ?? "").includes("text/event-stream") ? await this.readSSEFrame(response, id, options.signal) : await response.json();
+    return this.unwrap(frame, method, id);
+  }
+  /** The resolved MCP endpoint path, from discovery, probed once. */
+  endpoint() {
+    return this.endpointPromise ?? (this.endpointPromise = this.resolveEndpoint());
+  }
+  /**
+   * Discovery names the endpoint; `${baseUrl}/mcp` is the compatibility
+   * default. Discovery failing is not fatal — a venue that serves `/mcp`
+   * without advertising it still works, so a failed probe falls through to the
+   * default rather than failing the call that triggered it.
+   */
+  async resolveEndpoint() {
+    try {
+      const doc = await this.discovery();
+      const advertised = [doc?.server_url, typeof doc?.endpoint === "string" ? doc.endpoint : void 0].find((v) => typeof v === "string" && v.length > 0);
+      if (advertised) {
+        if (/^https?:\/\//i.test(advertised)) {
+          return advertised.startsWith(this.venue.baseUrl) ? advertised.slice(this.venue.baseUrl.length) || DEFAULT_MCP_PATH : advertised;
+        }
+        return advertised.startsWith("/") ? advertised : `/${advertised}`;
+      }
+    } catch {
+    }
+    return DEFAULT_MCP_PATH;
+  }
+  /**
+   * Read the response frame from an SSE-framed answer: the first event whose
+   * JSON-RPC id matches the request. Notifications and unrelated frames are
+   * skipped rather than mistaken for the answer.
+   */
+  async readSSEFrame(response, id, signal) {
+    for await (const event of parseSSEStream(response, signal ? { signal } : void 0)) {
+      let payload;
+      try {
+        payload = event.json();
+      } catch {
+        continue;
+      }
+      if (isResponseFrame(payload) && payload.id === id) return payload;
+    }
+    throw new CoviaError(
+      `MCP stream ended without a response to request ${id}`
+    );
+  }
+  /** JSON-RPC envelope → result, or a typed error. */
+  unwrap(frame, method, id) {
+    if (frame?.error) {
+      throw new MCPError(frame.error.message || `MCP ${method} failed`, frame.error.code, frame.error.data);
+    }
+    if (!frame || !("result" in frame)) {
+      throw new CoviaError(`MCP ${method} returned no result for request ${id}`);
+    }
+    return frame.result;
+  }
+};
+
 // src/Agent.ts
 var Agent = class _Agent {
   constructor(id, venue) {
@@ -3381,6 +3661,21 @@ function asCoviaError(error) {
   const message = error instanceof Error ? error.message : String(error);
   return new CoviaError(message);
 }
+function canonicalDidFromDocument(didDoc) {
+  const akas = didDoc.alsoKnownAs;
+  if (Array.isArray(akas)) {
+    const keyDid = akas.find((a) => typeof a === "string" && a.startsWith("did:key:"));
+    if (keyDid) return keyDid;
+  }
+  const methods = didDoc.verificationMethod;
+  if (Array.isArray(methods)) {
+    for (const method of methods) {
+      const multibase = method?.publicKeyMultibase;
+      if (typeof multibase === "string" && multibase.length > 0) return `did:key:${multibase}`;
+    }
+  }
+  return void 0;
+}
 function assertVenueIdentity(expectedDid, actualDid, baseUrl) {
   if (expectedDid && actualDid && expectedDid !== actualDid) {
     throw new VenueIdentityChangedError(expectedDid, actualDid, baseUrl);
@@ -3463,6 +3758,9 @@ var Venue = class _Venue {
   get users() {
     return this._users ?? (this._users = new UserManager(this));
   }
+  get mcp() {
+    return this._mcp ?? (this._mcp = new MCPManager(this));
+  }
   get a2a() {
     return this._a2a ?? (this._a2a = new A2AManager(this));
   }
@@ -3504,12 +3802,14 @@ var Venue = class _Venue {
     if (typeof venueId === "string") {
       let candidates;
       let expectedDid;
+      let requestedWebDid;
       if (venueId.startsWith("did:web:")) {
-        expectedDid = venueId;
         const didDoc = await resolver.resolve(venueId);
         if (!didDoc.didDocument) {
           throw new CoviaError("Invalid DID document");
         }
+        expectedDid = canonicalDidFromDocument(didDoc.didDocument);
+        requestedWebDid = venueId;
         const endpoint = didDoc.didDocument.service?.find((service) => service.type === "Covia.API.v1")?.serviceEndpoint;
         if (typeof endpoint !== "string") {
           throw new CoviaError("No (string) endpoint found for DID");
@@ -3530,7 +3830,8 @@ var Venue = class _Venue {
           if (!data.did) {
             throw new CoviaError(`Venue status at ${statusUrl} did not include a DID`);
           }
-          assertVenueIdentity(expectedDid, data.did, baseUrl);
+          const required = expectedDid ?? (data.did.startsWith("did:web:") ? requestedWebDid : void 0);
+          assertVenueIdentity(required, data.did, baseUrl);
           return new _Venue({
             baseUrl,
             venueId: data.did,
@@ -3830,6 +4131,8 @@ exports.JobManager = JobManager;
 exports.JobNotFoundError = JobNotFoundError;
 exports.JobStatus = JobStatus;
 exports.KeyPairAuth = KeyPairAuth;
+exports.MCPError = MCPError;
+exports.MCPManager = MCPManager;
 exports.MemoryManager = MemoryManager;
 exports.Namespace = Namespace;
 exports.NoAuth = NoAuth;