@covia/covia-sdk 1.17.0 → 1.19.0

package/dist/index.d.mts

@@ -24,6 +24,13 @@ declare class Agent {
     listSessions(options?: AgentSessionListOptions): Promise<AgentSessionPage>;
     /** Read one session through the job-free workspace Values API. */
     getSession(sessionId: string): Promise<AgentSession>;
+    /**
+     * 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.
+     */
+    transcript(sessionId: string): Promise<AgentSessionMessage[]>;
     /** Stream this agent's run-loop events. See `AgentManager.events`. */
     events(options?: {
         sessionId?: string;
@@ -369,6 +376,9 @@ interface AgentManagerVenue extends VenueRequestContext {
     workspace: {
         read(path: string, maxSize?: number): Promise<WorkspaceReadResult>;
         slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+        count(path: string, opts?: {
+            depth?: number;
+        }): Promise<WorkspaceCountResult>;
     };
 }
 declare class AgentManager {
@@ -446,6 +456,8 @@ declare class AgentManager {
      * available on each record's `value` while common runtime fields are typed.
      */
     listSessions(agentId: string, options?: AgentSessionListOptions): Promise<AgentSessionPage>;
+    /** Shape a `{key, value}` session slice into a page. */
+    private _sessionPage;
     /** Read one agent session directly from the workspace Values surface. */
     getSession(agentId: string, sessionId: string): Promise<AgentSession>;
     private _readLargeSession;
@@ -455,11 +467,39 @@ declare class AgentManager {
     failTask(error: string): Promise<AgentFailTaskResult>;
 }
 
-type JobManagerVenue = VenueRequestContext;
+interface JobManagerVenue extends VenueRequestContext {
+    workspace: {
+        count(path: string, opts?: {
+            depth?: number;
+        }): Promise<WorkspaceCountResult>;
+        slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+    };
+}
 declare class JobManager {
     private venue;
     constructor(venue: JobManagerVenue);
     list(): Promise<string[]>;
+    /**
+     * 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.
+     */
+    history(options?: JobHistoryOptions): Promise<JobHistoryPage>;
+    /**
+     * Read index ranks `[start, end)` in cap-aware chunks, halving on an oversize
+     * response and skipping a record that is individually oversize.
+     */
+    private _readJobRange;
     get(jobId: string): Promise<Job>;
     cancel(jobId: string): Promise<JobMetadata>;
     delete(jobId: string): Promise<void>;
@@ -485,6 +525,14 @@ declare class AssetManager {
      * 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
      */
@@ -610,6 +658,8 @@ interface WorkspaceManagerVenue extends VenueRequestContext {
 declare class WorkspaceManager {
     private venue;
     private valuesSupported;
+    private scopeExpansionSupported;
+    private fieldsSupported;
     constructor(venue: WorkspaceManagerVenue);
     /** GET a job-free `/api/v1/values/{op}` read; omit undefined params. */
     private _values;
@@ -624,8 +674,78 @@ declare class WorkspaceManager {
     private unsupported;
     /** A job-free Values read that rejects when the endpoint is unavailable. */
     private valuesRead;
+    /**
+     * 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.
+     */
+    private scopedRead;
+    /**
+     * 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: ExecutionScope): ScopedWorkspace;
+    /** @internal — the scoped read used by {@link ScopedWorkspace}. */
+    _scopedRead<T>(op: string, params: Record<string, string | number | boolean | undefined>, scope: ExecutionScope): Promise<T>;
     read(path: string, maxSize?: number, ucans?: string[]): Promise<WorkspaceReadResult>;
     list(path?: string, limit?: number, offset?: number, ucans?: string[]): Promise<WorkspaceListResult>;
+    /**
+     * 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.
+     */
+    listFields(path: string, fields: string[], opts?: {
+        limit?: number;
+        offset?: number;
+        maxSize?: number;
+    }): Promise<WorkspaceProjectedList>;
+    /**
+     * 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.
+     */
+    private projectClientSide;
     slice(path: string, offset?: number, limit?: number, ucans?: string[]): Promise<WorkspaceSliceResult>;
     inspect(paths: string | string[], budget?: number, compact?: boolean, ucans?: string[]): Promise<WorkspaceInspectResult>;
     /**
@@ -658,6 +778,35 @@ declare class WorkspaceManager {
     append(path: string, value: unknown, ucans?: string[]): Promise<WorkspaceAppendResult>;
     copy(from: string, to: string, ucans?: string[]): Promise<WorkspaceCopyResult>;
 }
+/**
+ * A {@link WorkspaceManager} bound to one execution scope, so `t/`, `n/` and
+ * `c/` scratch resolve without the caller hand-building the physical paths
+ * (`g/<agent>/sessions/<sid>/c/...` and friends). Reads only — scoped scratch
+ * is written from inside the execution that owns it, where the shorthands
+ * already resolve from the request's own context.
+ *
+ * Obtained from {@link WorkspaceManager.scoped}; every method mirrors the
+ * job-free read of the same name.
+ */
+declare class ScopedWorkspace {
+    private workspace;
+    /** The scope every read on this handle resolves against. */
+    readonly scope: ExecutionScope;
+    constructor(workspace: WorkspaceManager, 
+    /** The scope every read on this handle resolves against. */
+    scope: ExecutionScope);
+    read(path: string, maxSize?: number): Promise<WorkspaceReadResult>;
+    list(path: string, limit?: number, offset?: number): Promise<WorkspaceListResult>;
+    slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+    inspect(path: string, budget?: number, compact?: boolean): Promise<WorkspaceInspectResult>;
+    count(path: string, opts?: {
+        depth?: number;
+    }): Promise<WorkspaceCountResult>;
+    aggregate(path: string, opts?: {
+        depth?: number;
+        groupBy?: string;
+    }): Promise<WorkspaceAggregateResult>;
+}
 
 interface UCANManagerVenue {
     operations: OperationRunner;
@@ -876,6 +1025,123 @@ declare class A2AManager {
     }): Promise<Job>;
 }
 
+interface MCPOps {
+    invoke(assetId: string, input?: unknown, options?: InvokeOptions): Promise<Job>;
+}
+interface MCPManagerVenue extends VenueRequestContext {
+    operations: MCPOps;
+    mcpDiscovery(): Promise<MCPDiscovery>;
+}
+/**
+ * MCP client for a venue's native `/mcp` endpoint.
+ *
+ * The venue speaks Streamable HTTP MCP: JSON-RPC over POST, answering either
+ * `application/json` or `text/event-stream` at its discretion. Everything that
+ * implies — request-id correlation, reading a response that may arrive as SSE
+ * frames, applying the venue's auth with the venue DID as audience, turning
+ * JSON-RPC error objects into typed errors — is protocol plumbing every
+ * TypeScript consumer would otherwise rebuild (covia-sdk#23).
+ *
+ * ```ts
+ * const page = await venue.mcp.listTools();
+ * const out  = await venue.mcp.callTool(page.tools[0].name, { text: 'hi' });
+ * ```
+ *
+ * **`listTools()` is job-free.** It reads the native endpoint, never the
+ * `v/ops/mcp/tools-list` operation — discovery and display must not persist a
+ * job per page (covia#177).
+ */
+declare class MCPManager {
+    private venue;
+    private nextId;
+    private sessionId?;
+    private endpointPromise?;
+    constructor(venue: MCPManagerVenue);
+    /** The venue's MCP discovery document (`GET /.well-known/mcp`). */
+    discovery(): Promise<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.
+     */
+    listTools(options?: {
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<MCPToolPage>;
+    /**
+     * 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.
+     */
+    listAllTools(options?: {
+        signal?: AbortSignal;
+    }): Promise<MCPToolPage['tools']>;
+    /**
+     * 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.
+     */
+    callTool(name: string, args?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<MCPToolResult>;
+    /**
+     * 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.
+     */
+    callToolTracked(name: string, args?: Record<string, unknown>, options?: {
+        server?: string;
+        token?: string;
+    } & InvokeOptions): Promise<Job>;
+    /**
+     * 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.
+     */
+    request<T = unknown>(method: string, params?: Record<string, unknown>, options?: {
+        signal?: AbortSignal;
+    }): Promise<T>;
+    /** The resolved MCP endpoint path, from discovery, probed once. */
+    private endpoint;
+    /**
+     * 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.
+     */
+    private resolveEndpoint;
+    /**
+     * 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.
+     */
+    private readSSEFrame;
+    /** JSON-RPC envelope → result, or a typed error. */
+    private unwrap;
+}
+
 /**
  * Resolve a non-DID venue id into the ordered list of base URLs that
  * {@link Venue.connect} will try in turn. Explicit `http(s)://` inputs are
@@ -933,6 +1199,7 @@ declare class Venue implements VenueInterface {
     private _dlfs?;
     private _users?;
     private _a2a?;
+    private _mcp?;
     get adapters(): AdapterManager;
     get agents(): AgentManager;
     get jobs(): JobManager;
@@ -945,6 +1212,7 @@ declare class Venue implements VenueInterface {
     get memory(): MemoryManager;
     get dlfs(): DLFSManager;
     get users(): UserManager;
+    get mcp(): MCPManager;
     get a2a(): A2AManager;
     constructor(options?: VenueOptions);
     /**
@@ -1149,6 +1417,23 @@ interface OperationPayload {
 interface ContentHashResult {
     hash: string;
 }
+/** Paging/ordering for {@link JobManager.history}. */
+interface JobHistoryOptions {
+    /** Rows to skip from the ordered start (default 0). */
+    offset?: number;
+    /** Maximum rows to return (default 50). */
+    limit?: number;
+    /** `desc` (default) is newest-first, the order a history view wants. */
+    order?: 'asc' | 'desc';
+}
+/** One page of job history: the rows plus the window they were drawn from. */
+interface JobHistoryPage {
+    items: JobMetadata[];
+    /** Authoritative total at the moment the page was read. */
+    total: number;
+    offset: number;
+    limit: number;
+}
 interface JobMetadata {
     id?: string;
     name?: string;
@@ -1268,6 +1553,36 @@ interface MCPDiscovery {
     endpoint?: Record<string, any> | string;
     [key: string]: any;
 }
+/** One tool as MCP describes it (`tools/list`). */
+interface MCPTool {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    [key: string]: any;
+}
+/** One page of `tools/list`. `nextCursor` absent = the last page. */
+interface MCPToolPage {
+    tools: MCPTool[];
+    nextCursor?: string;
+}
+/** One content block of a tool result. */
+interface MCPContent {
+    type: string;
+    text?: string;
+    [key: string]: any;
+}
+/**
+ * The result of `tools/call`. `isError` marks a tool that ran and failed —
+ * a successful protocol call reporting a failed tool — as distinct from a
+ * protocol error, which throws `MCPError` instead.
+ */
+interface MCPToolResult {
+    content?: MCPContent[];
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    [key: string]: any;
+}
 /**
  * A2A agent card from `GET /.well-known/agent-card.json`.
  * Field names mirror the A2A v1.0 wire format the venue serves (via the
@@ -1438,17 +1753,78 @@ interface AgentSessionMetadata {
     turnCount?: number;
     [key: string]: unknown;
 }
+/** The four roles a stored conversation turn may carry. */
+type AgentSessionRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * One persisted conversation turn (AGENT_CONTEXT.md §1.1 `Turn`).
+ *
+ * Most turns carry text in `content`; a tool result may instead carry its typed
+ * map or vector in `structuredContent`. Provider-specific continuation state
+ * (`providerState`) is deliberately absent — it is opaque, is omitted from
+ * retrospective session projections, and is not part of a readable transcript.
+ */
+interface AgentSessionMessage {
+    role: AgentSessionRole;
+    content?: unknown;
+    /** A typed tool result, in place of textual `content`. */
+    structuredContent?: unknown;
+    /** Present on an assistant turn that called tools. */
+    toolCalls?: unknown[];
+    /** A `tool` turn's matching call id. */
+    id?: string;
+    name?: string;
+    isError?: boolean;
+    ts?: number;
+    source?: string;
+    caller?: string;
+    /** The job that delivered this turn — links it back to the calling job. */
+    jobId?: string;
+    tokens?: number;
+}
+/**
+ * An archived run of turns that compaction replaced with a summary
+ * (AGENT_CONTEXT.md §1.1 `CompactedSegment`). `items` is the exact recursively
+ * archived vector, so no history is lost — {@link AgentSession.conversation}
+ * expands it back into the transcript.
+ */
+interface AgentCompactedSegment {
+    summary: string;
+    /** How many turns the summary stands in for. */
+    turns?: number;
+    items: unknown[];
+}
 /** A session record read directly from `g/<agentId>/sessions`. */
 interface AgentSession {
     id: string;
     metadata: AgentSessionMetadata;
     pending: unknown[];
+    /**
+     * Raw goal-tree frames, newest last. `frames[0]` is the root frame and a flat
+     * `llmagent` session has only that one. Kept verbatim for callers that need
+     * frame-level state; for the readable transcript use {@link conversation}.
+     */
     frames: unknown[];
+    /**
+     * The session transcript: every frame's turns, in order, with compacted
+     * segments expanded back into the turns they archived.
+     *
+     * This is the field a chat UI renders. Assembling it from `frames` means
+     * knowing that turns live at `frames[].conversation`, that an entry there may
+     * be an archived segment rather than a turn, and that segments nest — layout
+     * knowledge that belongs here rather than in every consumer.
+     */
+    conversation: AgentSessionMessage[];
     wakeTime?: number;
 }
 interface AgentSessionListOptions {
     offset?: number;
     limit?: number;
+    /**
+     * `desc` is newest-first. Session ids are timestamp-prefixed, so the index is
+     * already chronological and the window is taken from its end — the order
+     * holds across pages, unlike sorting one page after the fact.
+     */
+    order?: 'asc' | 'desc';
 }
 interface AgentSessionPage {
     items: AgentSession[];
@@ -1640,6 +2016,33 @@ interface WorkspaceAppendResult {
     /** 0.3.0: true iff a new parent path was built. */
     pathCreated?: boolean;
 }
+/**
+ * The execution context a `t/`, `n/` or `c/` scratch read resolves against.
+ *
+ * A GET carries no execution context of its own, so the venue cannot know which
+ * job, agent or session a bare shorthand means. These selectors supply it
+ * explicitly (covia#230) and are the only way to read scoped scratch job-free.
+ *
+ * Each namespace consumes a different part of the scope, and the venue rejects
+ * a selector its namespace does not use:
+ *
+ * | Path | Needs            | Resolves to                                  |
+ * |------|------------------|----------------------------------------------|
+ * | `n/` | `agent`          | `g/<agent>/n/...`                            |
+ * | `c/` | `agent`+`session`| `g/<agent>/sessions/<session>/c/...`         |
+ * | `t/` | `agent`+`task`   | `j/<task>/temp/...`                          |
+ *
+ * A bound scope may therefore carry all three; each read sends only what its
+ * own namespace needs.
+ */
+interface ExecutionScope {
+    /** Agent id (`alice`) or a full agent DID. Required for every scoped read. */
+    agent: string;
+    /** Task id — the `agent:request` Job whose record holds `t/` scratch. */
+    task?: string;
+    /** Session id, for `c/` session scratch. */
+    session?: string;
+}
 interface WorkspaceListInput {
     path?: string;
     limit?: number;
@@ -1657,6 +2060,26 @@ interface WorkspaceListResult {
     keys?: string[];
     offset?: number;
 }
+/**
+ * One projected field of one listed record (covia#191).
+ *
+ * Exactly what a `values/read` of `<parent>/<key>/<field>` returns, down to
+ * `valueBytes` — projection is pure composition of reads, not new semantics.
+ * So: a stored null is present (`{exists: true, value: null}`), an absent
+ * field is `{exists: false}`, and a value past the per-field byte guard
+ * withholds `value` and sets `truncated` alongside its `type`.
+ */
+type WorkspaceFieldValue = WorkspaceReadResult;
+/**
+ * A `list` carrying a field projection: the ordinary list result plus, per
+ * listed key, the read result of each requested subpath of that key's child.
+ *
+ * `values` is keyed by the same keys `keys` reports, in the same page —
+ * projection applies after `limit`/`offset`.
+ */
+interface WorkspaceProjectedList extends WorkspaceListResult {
+    values: Record<string, Record<string, WorkspaceFieldValue>>;
+}
 interface WorkspaceSliceInput {
     path: string;
     offset?: number;
@@ -1834,6 +2257,15 @@ declare class CoviaError extends Error {
     code: number | null;
     constructor(message: string, code?: number | null);
 }
+/**
+ * A JSON-RPC error from an MCP endpoint. `code` is the JSON-RPC code (e.g.
+ * -32602 invalid params), not an HTTP status — a JSON-RPC error arrives in a
+ * 200 response, so it would otherwise read as success.
+ */
+declare class MCPError extends CoviaError {
+    data?: unknown;
+    constructor(message: string, code: number, data?: unknown);
+}
 /** Raised when the Covia API returns an error response (4xx/5xx). */
 declare class GridError extends CoviaError {
     statusCode: number;
@@ -2063,7 +2495,11 @@ declare function parseSSEStream(response: Response, options?: {
  * Which DID belongs in a lattice address:
  * - `w`/`o`/`g`/`j`/`s` are per-user: the `<DID>` is the resource *owner's* DID
  *   (yours is your auth DID, e.g. `Ed25519Auth.getDID()`) — NOT the venue's.
- * - `a` (assets) is venue-global and content-addressed.
+ * - `a` (assets) is content-addressed, and **caller-relative**: a bare hash or
+ *   `a/<hash>` names the asset in the requesting caller's own `a/` namespace,
+ *   not a global one (covia#502). Name another owner's copy explicitly as
+ *   `<ownerDID>/a/<hash>` — the only portable form — and the venue's own
+ *   catalog as `<venueDID>/a/<hash>`.
  * - A namespace-relative path (no `<DID>`) resolves to the authenticated caller.
  */
 /** Lattice namespace identifiers. */
@@ -2116,23 +2552,30 @@ declare function assetHash(ref: string): string | null;
 /**
  * Pluggable persistent store for content-addressed asset metadata.
  *
- * An asset id is the Convex value hash of its metadata (`AMap.getHash()`
- * venue-side), so hash → metadata is immutable: entries never go stale and are
- * safe to cache indefinitely, across sessions and across venues. Keys are the
- * normalised bare hash (lowercase, no `0x`), so `<hash>`, `0x<hash>` and
- * `<DID>/a/<hash>` refs all share one entry.
+ * Keys are the **fully qualified** `<ownerDID>/a/<hash>` form, and only that
+ * form is admitted. A bare hash or `a/<hash>` is *caller-relative*: it names
+ * the asset in the requesting caller's own `a/` namespace, so the same bytes
+ * registered by two principals are two records, each readable only under its
+ * owner's authority (covia#502, `venue/docs/OPERATIONS.md` §"Content-addressed
+ * forms are caller-relative, not global"). Covia has no global lookup by hash.
+ * Keying this store on a bare hash would therefore let an entry populated
+ * under one identity be served back to another that may have no right to read
+ * it — and this store is cross-session by design, outliving the auth that
+ * filled it. `persistentCacheKey` returns null for those refs, and
+ * `AssetManager` keeps them in its own venue-local memory cache instead.
  *
  * Trust model: entries are cached as returned by the venue that served them.
  * Provable verification — recomputing the Convex value hash of the metadata
  * and rejecting mismatches — requires a canonical CVM cell encoder in
- * TypeScript, which does not exist yet; when it lands, verification will gate
- * admission to this cache so entries are correct by construction rather than
- * by trust. Until then this is a availability/performance cache with the same
- * trust as an uncached fetch from the same venue.
+ * TypeScript, which does not exist yet (covia-sdk#18); when it lands,
+ * verification will gate admission to this cache so entries are correct by
+ * construction rather than by trust. Until then this is an
+ * availability/performance cache with the same trust as an uncached fetch
+ * from the same venue.
  */
 interface AssetMetadataStore {
-    get(hash: string): AssetMetadata | undefined;
-    put(hash: string, metadata: AssetMetadata): void;
+    get(key: string): AssetMetadata | undefined;
+    put(key: string, metadata: AssetMetadata): void;
     clear(): void;
 }
 /** Replace the persistent metadata store (e.g. a file-backed store in Node),
@@ -2282,4 +2725,4 @@ declare function grant(ownerPrivateKey: Uint8Array, audienceDID: string, withRes
  */
 declare function relayDelegation(privateKey: Uint8Array, venueDID: string, lifetimeSeconds: number, caps?: UCANCapability[]): string;
 
-export { type A2AAuthRef, type A2AImportAgentInput, type A2AImportAgentResult, A2AManager, type A2AMessage, type A2APart, type A2ATask, type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentCycleEndEvent, type AgentCycleStartEvent, type AgentDeleteInput, type AgentDeleteResult, type AgentEvent, type AgentEventEnvelope, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInferenceEndEvent, type AgentInferenceStartEvent, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentRunEndEvent, type AgentRunStartEvent, type AgentSession, type AgentSessionListOptions, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, AgentStatus, type AgentStatusEvent, type AgentSuspendResult, type AgentToolResultEvent, type AgentToolStartEvent, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, type AuthenticationKeyEntry, type AuthenticationKeysMap, type AuthenticationKeysResult, type AuthenticatorRevokeResult, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, type UserInfo, type UserListResult, UserManager, type UserSummary, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { type A2AAuthRef, type A2AImportAgentInput, type A2AImportAgentResult, A2AManager, type A2AMessage, type A2APart, type A2ATask, type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompactedSegment, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentCycleEndEvent, type AgentCycleStartEvent, type AgentDeleteInput, type AgentDeleteResult, type AgentEvent, type AgentEventEnvelope, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInferenceEndEvent, type AgentInferenceStartEvent, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentRunEndEvent, type AgentRunStartEvent, type AgentSession, type AgentSessionListOptions, type AgentSessionMessage, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, type AgentSessionRole, AgentStatus, type AgentStatusEvent, type AgentSuspendResult, type AgentToolResultEvent, type AgentToolStartEvent, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, type AuthenticationKeyEntry, type AuthenticationKeysMap, type AuthenticationKeysResult, type AuthenticatorRevokeResult, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExecutionScope, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, type JobHistoryOptions, type JobHistoryPage, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPContent, type MCPDiscovery, MCPError, MCPManager, type MCPTool, type MCPToolPage, type MCPToolResult, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, ScopedWorkspace, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, type UserInfo, type UserListResult, UserManager, type UserSummary, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceFieldValue, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceProjectedList, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };