@covia/covia-sdk 1.17.0 → 1.19.0

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";
@@ -1743,16 +1759,46 @@ async function sliceAll(workspace, path, pageSize = SLICE_PAGE_SIZE) {
   }
   return items;
 }
+function descWindow(total, offset, limit) {
+  const end = Math.max(0, total - offset);
+  return [Math.max(0, end - limit), end];
+}
 
 // src/AgentManager.ts
+var SESSION_ROLES = ["system", "user", "assistant", "tool"];
+var MAX_COMPACTION_DEPTH = 32;
+function collectTurns(entries, out, depth = 0) {
+  if (depth > MAX_COMPACTION_DEPTH) return;
+  for (const entry of entries) {
+    const e = record(entry);
+    if (!e) continue;
+    if (Array.isArray(e.items) && typeof e.summary === "string") {
+      collectTurns(e.items, out, depth + 1);
+      continue;
+    }
+    if (typeof e.role === "string" && SESSION_ROLES.includes(e.role)) {
+      out.push({ ...e, role: e.role });
+    }
+  }
+}
+function sessionConversation(frames) {
+  const turns = [];
+  for (const frame of frames) {
+    const entries = record(frame)?.conversation;
+    if (Array.isArray(entries)) collectTurns(entries, turns);
+  }
+  return turns;
+}
 function sessionRecord(sessionId, value) {
   const session = record(value) ?? {};
   const meta = record(session.meta);
+  const frames = Array.isArray(session.frames) ? session.frames : [];
   return {
     id: sessionId,
     metadata: meta ?? {},
     pending: Array.isArray(session.pending) ? session.pending : [],
-    frames: Array.isArray(session.frames) ? session.frames : [],
+    frames,
+    conversation: sessionConversation(frames),
     wakeTime: typeof session.wakeTime === "number" ? session.wakeTime : void 0
   };
 }
@@ -1905,11 +1951,31 @@ var AgentManager = class {
    * 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 path = `g/${agentId}/sessions`;
+    if ((options.order ?? "asc") === "asc") {
+      return this._sessionPage(path, await this.venue.workspace.slice(
+        path,
+        options.offset,
+        options.limit
+      ), options.offset ?? 0, options.limit);
+    }
+    const offset = Math.max(0, options.offset ?? 0);
+    const limit = options.limit;
+    const guess = (await this.venue.workspace.count(path)).count ?? 0;
+    if (limit === 0) return { items: [], total: guess, offset, limit: 0 };
+    const read = async (total2) => {
+      const [start, end] = descWindow(total2, offset, limit ?? total2);
+      return end > start ? this.venue.workspace.slice(path, start, end - start) : { exists: true, values: [], count: total2, offset: start };
+    };
+    let result = await read(guess);
+    const total = result.count ?? guess;
+    if (total !== guess) result = await read(total);
+    const page = this._sessionPage(path, result, offset, limit);
+    page.items.reverse();
+    return page;
+  }
+  /** Shape a `{key, value}` session slice into a page. */
+  _sessionPage(_path, result, offset, limit) {
     const sessions = (result.values ?? []).flatMap((entry) => {
       const pair = record(entry);
       if (!pair || typeof pair.key !== "string") return [];
@@ -1918,8 +1984,8 @@ var AgentManager = class {
     return {
       items: sessions,
       total: result.count ?? sessions.length,
-      offset: result.offset ?? options.offset ?? 0,
-      limit: options.limit ?? sessions.length
+      offset,
+      limit: limit ?? sessions.length
     };
   }
   /** Read one agent session directly from the workspace Values surface. */
@@ -2111,6 +2177,24 @@ var Job = class {
 };
 
 // src/JobManager.ts
+var JOB_INDEX = "j";
+var DEFAULT_HISTORY_LIMIT = 50;
+var MAX_SLICE_LIMIT = 100;
+function isSliceCapError(error) {
+  return error instanceof Error && error.message.includes("exceeds maxSize");
+}
+function jobRecords(values) {
+  const records = [];
+  for (const entry of values) {
+    const pair = record(entry);
+    const value = record(pair?.value);
+    if (!value) continue;
+    const meta = value;
+    const key = typeof pair?.key === "string" ? pair.key : "";
+    records.push({ ...meta, id: meta.id ?? `0x${key}` });
+  }
+  return records;
+}
 function jobPage(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new CoviaError("Venue returned an invalid jobs listing");
@@ -2152,6 +2236,70 @@ var JobManager = class {
     }
     return items;
   }
+  /**
+   * A page of job history: `JobMetadata` rows, newest-first by default, with an
+   * authoritative total.
+   *
+   * `list()` answers "which jobs exist" as ids; a history view needs a bounded
+   * window of *records* and a count to page against. This reads the job index
+   * directly, so each row arrives with its metadata already attached — the
+   * alternative, listing ids and then fetching each one, is an N+1 fan-out per
+   * page. Reads stay job-free (covia#177): paging job history must not itself
+   * write a job record per page.
+   *
+   * The total is read before a `desc` window can be placed, so the index may
+   * grow in between; the page self-corrects once against the count the slice
+   * itself reports, which is authoritative for the rows returned with it.
+   */
+  async history(options = {}) {
+    const offset = Math.max(0, Math.trunc(options.offset ?? 0));
+    const limit = Math.max(0, Math.trunc(options.limit ?? DEFAULT_HISTORY_LIMIT));
+    const descending = (options.order ?? "desc") === "desc";
+    if (limit === 0) {
+      const { count } = await this.venue.workspace.count(JOB_INDEX);
+      return { items: [], total: count ?? 0, offset, limit };
+    }
+    if (!descending) {
+      const asc = await this._readJobRange(offset, offset + limit);
+      return { items: jobRecords(asc.values), total: asc.count ?? offset + asc.values.length, offset, limit };
+    }
+    const guess = (await this.venue.workspace.count(JOB_INDEX)).count ?? 0;
+    let read = await this._readJobRange(...descWindow(guess, offset, limit));
+    const total = read.count ?? guess;
+    if (total !== guess) {
+      read = await this._readJobRange(...descWindow(total, offset, limit));
+    }
+    return { items: jobRecords(read.values).reverse(), total: read.count ?? total, offset, limit };
+  }
+  /**
+   * Read index ranks `[start, end)` in cap-aware chunks, halving on an oversize
+   * response and skipping a record that is individually oversize.
+   */
+  async _readJobRange(start, end) {
+    const values = [];
+    let count;
+    let pos = start;
+    let chunk = MAX_SLICE_LIMIT;
+    while (pos < end) {
+      const want = Math.min(chunk, end - pos);
+      try {
+        const page = await this.venue.workspace.slice(JOB_INDEX, pos, want);
+        count = page.count ?? count;
+        const got = page.values ?? [];
+        values.push(...got);
+        if (got.length < want) break;
+        pos += got.length;
+      } catch (error) {
+        if (!isSliceCapError(error)) throw error;
+        if (want > 1) {
+          chunk = Math.max(1, Math.floor(want / 2));
+          continue;
+        }
+        pos += 1;
+      }
+    }
+    return { count, values };
+  }
   async get(jobId) {
     try {
       const data = await venueJson(this.venue, `/api/v1/jobs/${jobId}`);
@@ -2326,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
    */
@@ -2334,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);
@@ -2349,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) {
@@ -2583,12 +2740,58 @@ 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;
+}
+function scopeParamsFor(ns, scope) {
+  const { agent, task, session } = scope;
+  switch (ns) {
+    case "n":
+      return { agent };
+    case "c":
+      if (!session) throw new CoviaError("A 'c/' scratch read needs a session in its scope");
+      return { agent, session };
+    case "t":
+      if (!task) throw new CoviaError("A 't/' scratch read needs a task in its scope");
+      return { agent, task };
+  }
+}
+function expandScopedPath(path, ns, scope) {
+  if (scope.agent.startsWith("did:")) {
+    throw new CoviaError(
+      "This venue cannot expand scoped scratch paths and the SDK cannot do it for a DID-qualified agent \u2014 pass a bare agent id, or upgrade the venue (covia#230)"
+    );
+  }
+  const suffix = path.slice(ns.length);
+  switch (ns) {
+    case "n":
+      return `g/${scope.agent}/n${suffix}`;
+    case "c":
+      return `g/${scope.agent}/sessions/${scope.session}/c${suffix}`;
+    case "t":
+      return `j/${scope.task}/temp${suffix}`;
+  }
+}
 var WorkspaceManager = class {
   constructor(venue) {
     this.venue = venue;
     // Whether this venue serves GET /api/v1/values/* — flipped on the first 404
     // so pre-0.3 venues pay the probe once, not one failed GET per read.
     this.valuesSupported = true;
+    // Whether this venue expands t/, n/ and c/ from explicit agent/task/session
+    // selectors (covia#230) — flipped off the first time a venue answers a
+    // 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) {
@@ -2622,6 +2825,52 @@ var WorkspaceManager = class {
     }
     return this.unsupported(`workspace ${op} reads`);
   }
+  /**
+   * A job-free Values read of an execution-scoped path, preferring the venue's
+   * own selector expansion and falling back to the client-side one.
+   *
+   * The venue is preferred because it expands *before* the capability check, so
+   * authorisation applies to the same canonical resource that is ultimately
+   * read — a caller cannot substitute a sibling or foreign agent's scratch.
+   * The fallback reaches the same resource but re-derives the layout here.
+   */
+  async scopedRead(op, params, scope) {
+    const path = String(params.path ?? "");
+    const ns = scopedNamespaceOf(path);
+    if (!ns) return this.valuesRead(op, params);
+    if (this.scopeExpansionSupported) {
+      try {
+        return await this.valuesRead(op, { ...params, ...scopeParamsFor(ns, scope) });
+      } catch (e) {
+        if (!(e instanceof Error) || !SCOPE_UNEXPANDED.test(e.message)) throw e;
+        this.scopeExpansionSupported = false;
+      }
+    }
+    scopeParamsFor(ns, scope);
+    return this.valuesRead(op, { ...params, path: expandScopedPath(path, ns, scope) });
+  }
+  /**
+   * Bind an execution scope, giving job-free reads of the `t/`, `n/` and `c/`
+   * scratch shorthands that a bare GET cannot otherwise resolve (covia#177
+   * forbids minting a Job for a read; the shorthands need context a GET lacks).
+   *
+   * ```ts
+   * const scratch = venue.workspace.scoped({ agent: 'alice', task: taskId });
+   * await scratch.read('t/snapshot');
+   * await scratch.list('t/');
+   * ```
+   *
+   * Ordinary paths still work through the handle, so a caller rendering a task
+   * inspector can use one reader for both scratch and workspace. Capability
+   * behaviour is unchanged: the caller needs read caps on the agent's subtree.
+   */
+  scoped(scope) {
+    return new ScopedWorkspace(this, scope);
+  }
+  /** @internal — the scoped read used by {@link ScopedWorkspace}. */
+  _scopedRead(op, params, scope) {
+    return this.scopedRead(op, params, scope);
+  }
   // ── job-free reads (#177) ───────────────────────────────────────────────────
   async read(path, maxSize, ucans) {
     if (ucans?.length) return this.unsupported("UCAN-authorised workspace reads");
@@ -2632,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 });
@@ -2682,6 +3001,30 @@ var WorkspaceManager = class {
     return this.venue.operations.run("v/ops/covia/copy", { from, to }, { ucans });
   }
 };
+var ScopedWorkspace = class {
+  constructor(workspace, scope) {
+    this.workspace = workspace;
+    this.scope = scope;
+  }
+  read(path, maxSize) {
+    return this.workspace._scopedRead("read", { path, maxSize }, this.scope);
+  }
+  list(path, limit, offset) {
+    return this.workspace._scopedRead("list", { path, limit, offset }, this.scope);
+  }
+  slice(path, offset, limit) {
+    return this.workspace._scopedRead("slice", { path, offset, limit }, this.scope);
+  }
+  inspect(path, budget, compact) {
+    return this.workspace._scopedRead("inspect", { path, budget, compact }, this.scope);
+  }
+  count(path, opts = {}) {
+    return this.workspace._scopedRead("count", { path, depth: opts.depth }, this.scope);
+  }
+  aggregate(path, opts = {}) {
+    return this.workspace._scopedRead("aggregate", { path, depth: opts.depth, groupBy: opts.groupBy }, this.scope);
+  }
+};
 
 // src/UCANManager.ts
 var UCANManager = class {
@@ -3004,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) {
@@ -3053,6 +3575,15 @@ var Agent = class _Agent {
   async getSession(sessionId) {
     return this._agents.getSession(this.id, sessionId);
   }
+  /**
+   * One session's transcript — its turns in order, with compacted segments
+   * expanded back into the turns they archived.
+   *
+   * Shorthand for `getSession(sessionId)` when only the conversation is wanted.
+   */
+  async transcript(sessionId) {
+    return (await this._agents.getSession(this.id, sessionId)).conversation;
+  }
   /** Stream this agent's run-loop events. See `AgentManager.events`. */
   async *events(options) {
     yield* this._agents.events(this.id, options);
@@ -3212,6 +3743,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));
   }
@@ -3579,6 +4113,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;
@@ -3587,6 +4123,7 @@ exports.Operation = Operation;
 exports.OperationManager = OperationManager;
 exports.RateLimitError = RateLimitError;
 exports.RunStatus = RunStatus;
+exports.ScopedWorkspace = ScopedWorkspace;
 exports.SecretManager = SecretManager;
 exports.SkillManager = SkillManager;
 exports.UCANManager = UCANManager;