@covia/covia-sdk 1.5.0 → 1.6.0

package/dist/index.d.mts

@@ -3,23 +3,22 @@ declare class Agent {
     readonly venue: VenueInterface;
     private _agents;
     constructor(id: string, venue: VenueInterface);
-    request(input?: any, wait?: boolean | number): Promise<AgentRequestResult>;
-    message(message: any): Promise<AgentMessageResult>;
-    chat(message: any, sessionId?: string): Promise<AgentChatResult>;
+    request(input?: unknown, wait?: boolean | number): Promise<AgentRequestResult>;
+    message(message: unknown): Promise<AgentMessageResult>;
+    chat(message: unknown, sessionId?: string): Promise<AgentChatResult>;
     /**
      * Create a ChatSession bound to this agent.
      * @param sessionId - Optional session ID to resume an existing session
      */
     chatSession(sessionId?: string): ChatSession;
     trigger(): Promise<AgentTriggerResult>;
-    query(): Promise<AgentQueryResult>;
     suspend(): Promise<AgentSuspendResult>;
     resume(autoWake?: boolean): Promise<AgentSuspendResult>;
     update(options: {
-        config?: Record<string, any>;
-        state?: Record<string, any>;
-    }): Promise<any>;
-    cancelTask(taskId: string): Promise<any>;
+        config?: Record<string, unknown>;
+        state?: Record<string, unknown>;
+    }): Promise<unknown>;
+    cancelTask(taskId: string): Promise<unknown>;
     info(): Promise<AgentInfoResult>;
     /**
      * Fork this agent into a new agent.
@@ -28,11 +27,11 @@ declare class Agent {
      * @returns A new Agent instance for the forked agent
      */
     fork(agentId: string, options?: {
-        config?: Record<string, any>;
+        config?: Record<string, unknown>;
         includeTimeline?: boolean;
         overwrite?: boolean;
     }): Promise<Agent>;
-    context(task?: any): Promise<string>;
+    context(task?: unknown): Promise<string>;
     delete(remove?: boolean): Promise<AgentDeleteResult>;
 }
 declare class ChatSession {
@@ -46,7 +45,7 @@ declare class ChatSession {
      * On the first call (when no sessionId is set), the server mints a new session.
      * The returned sessionId is captured and reused for all subsequent calls.
      */
-    send(message: any): Promise<AgentChatResult>;
+    send(message: unknown): Promise<AgentChatResult>;
 }
 
 declare class Job {
@@ -68,7 +67,7 @@ declare class Job {
      * @throws {Error} If the job has not finished yet.
      * @throws {JobFailedError} If the job finished with a non-COMPLETE status.
      */
-    get output(): any;
+    get output(): unknown;
     /**
      * Poll the venue for the latest job status.
      * @throws {Error} If the job has no ID.
@@ -92,7 +91,7 @@ declare class Job {
      */
     result(options?: {
         timeout?: number;
-    }): Promise<any>;
+    }): Promise<unknown>;
     /**
      * Stream server-sent events for this job.
      * @returns AsyncGenerator yielding SSEEvent objects
@@ -115,7 +114,7 @@ declare class Job {
      * @param message - Message payload
      * @returns {Promise<any>}
      */
-    sendMessage(message: any): Promise<any>;
+    sendMessage(message: unknown): Promise<unknown>;
     /**
      * Pause the job
      * @returns {Promise<JobMetadata>} Updated job metadata
@@ -168,17 +167,19 @@ declare abstract class Asset {
      */
     getContentURL(): string;
     /**
-     * Execute the operation
+     * Execute the operation and await its result.
      * @param input - Operation input parameters
-     * @returns {Promise<any>}
+     * @param options - Invocation options (e.g. UCAN proofs)
+     * @returns {Promise<T>} The operation result, typed as `T` (defaults to `unknown`)
      */
-    run(input: any): Promise<any>;
+    run<T = unknown>(input?: unknown, options?: InvokeOptions): Promise<T>;
     /**
-    * Execute the operation
-    * @param input - Operation input parameters
-    * @returns {Promise<Job>}
-    */
-    invoke(input: any): Promise<Job>;
+     * Execute the operation, returning the Job without awaiting completion.
+     * @param input - Operation input parameters
+     * @param options - Invocation options (e.g. UCAN proofs)
+     * @returns {Promise<Job>}
+     */
+    invoke(input?: unknown, options?: InvokeOptions): Promise<Job>;
 }
 
 /**
@@ -195,12 +196,19 @@ declare abstract class Asset {
  *   }
  */
 declare abstract class Auth {
-    /** Apply authentication credentials to request headers (mutates in place). */
-    abstract apply(headers: Record<string, string>): void;
+    /**
+     * Apply authentication credentials to request headers (mutates in place).
+     *
+     * @param headers - Outgoing request headers to mutate.
+     * @param audience - The venue's DID, supplied by the transport. Providers
+     *   that bind tokens to the venue's identity (e.g. {@link Ed25519Auth}) use it
+     *   as the JWT `aud`; others ignore it.
+     */
+    abstract apply(headers: Record<string, string>, audience?: string): void;
 }
 /** No-op authentication provider. Sends no credentials. */
 declare class NoAuth extends Auth {
-    apply(_headers: Record<string, string>): void;
+    apply(_headers: Record<string, string>, _audience?: string): void;
 }
 /**
  * Bearer token authentication.
@@ -212,7 +220,20 @@ declare class NoAuth extends Auth {
 declare class BearerAuth extends Auth {
     private _token;
     constructor(token: string);
-    apply(headers: Record<string, string>): void;
+    apply(headers: Record<string, string>, _audience?: string): void;
+}
+/**
+ * HTTP Basic authentication.
+ * Adds `Authorization: Basic <base64(username:password)>` to every request.
+ *
+ * Example:
+ *   const venue = await Grid.connect("https://venue.covia.ai", new BasicAuth("admin", "s3cret"));
+ */
+declare class BasicAuth extends Auth {
+    private _username;
+    private _password;
+    constructor(username: string, password: string);
+    apply(headers: Record<string, string>, _audience?: string): void;
 }
 /**
  * Ed25519 keypair authentication (self-issued EdDSA JWT).
@@ -221,37 +242,53 @@ declare class BearerAuth extends Auth {
  * extracts the caller's DID from the `sub` claim.
  *
  * Example:
- *   const auth = KeyPairAuth.generate();
+ *   const auth = Ed25519Auth.generate();
  *   console.log(auth.getDID()); // did:key:z6Mk...
  *   const venue = await Grid.connect("https://venue.covia.ai", auth);
  */
-declare class KeyPairAuth extends Auth {
+declare class Ed25519Auth extends Auth {
     private _privateKey;
     private _publicKey;
     private _did;
     private _lifetime;
+    private _audience?;
     /**
      * @param privateKey - 32-byte Ed25519 private key
      * @param tokenLifetimeSeconds - JWT lifetime in seconds (default 300 = 5 min)
      */
     constructor(privateKey: Uint8Array, tokenLifetimeSeconds?: number);
-    apply(headers: Record<string, string>): void;
+    apply(headers: Record<string, string>, audience?: string): void;
     /** The caller's DID derived from the public key. */
     getDID(): string;
+    /**
+     * Explicitly pin the JWT `aud` claim. Overrides the venue DID the transport
+     * supplies — normally unnecessary, since the venue DID is the correct audience.
+     */
+    set audience(value: string | undefined);
+    get audience(): string | undefined;
     /** The 32-byte Ed25519 public key. */
     getPublicKey(): Uint8Array;
-    /** Generate a new random keypair and return a KeyPairAuth instance. */
-    static generate(tokenLifetimeSeconds?: number): KeyPairAuth;
+    /** Generate a new random keypair and return an Ed25519Auth instance. */
+    static generate(tokenLifetimeSeconds?: number): Ed25519Auth;
     /** Create from a hex-encoded private key string. */
-    static fromHex(privateKeyHex: string, tokenLifetimeSeconds?: number): KeyPairAuth;
+    static fromHex(privateKeyHex: string, tokenLifetimeSeconds?: number): Ed25519Auth;
 }
-/** @deprecated Use Auth subclasses instead (NoAuth, BearerAuth, KeyPairAuth). */
+/**
+ * @deprecated Renamed to {@link Ed25519Auth} for cross-SDK consistency
+ * (the Python SDK uses the same name). This alias keeps existing
+ * `KeyPairAuth` / `KeyPairAuth.generate()` / `KeyPairAuth.fromHex()` usage
+ * working; prefer `Ed25519Auth` in new code.
+ */
+declare const KeyPairAuth: typeof Ed25519Auth;
+/** @deprecated Renamed to {@link Ed25519Auth}. */
+type KeyPairAuth = Ed25519Auth;
+/** @deprecated Use Auth subclasses instead (NoAuth, BearerAuth, BasicAuth, Ed25519Auth). */
 interface Credentials {
     venueId: string;
     apiKey: string;
     userId: string;
 }
-/** @deprecated Use Auth subclasses instead (NoAuth, BearerAuth, KeyPairAuth). */
+/** @deprecated Use Auth subclasses instead (NoAuth, BearerAuth, BasicAuth, Ed25519Auth). */
 declare class CredentialsHTTP implements Credentials {
     venueId: string;
     apiKey: string;
@@ -260,16 +297,14 @@ declare class CredentialsHTTP implements Credentials {
 }
 
 interface AgentManagerVenue {
-    operations: {
-        run(assetId: string, input: any): Promise<any>;
-    };
+    operations: OperationRunner;
 }
 declare class AgentManager {
     private venue;
     constructor(venue: AgentManagerVenue);
     create(input: AgentCreateInput): Promise<AgentCreateResult>;
-    request(agentId: string, input?: any, wait?: boolean | number): Promise<AgentRequestResult>;
-    message(agentId: string, message: any): Promise<AgentMessageResult>;
+    request(agentId: string, input?: unknown, wait?: boolean | number): Promise<AgentRequestResult>;
+    message(agentId: string, message: unknown): Promise<AgentMessageResult>;
     /**
      * Send a message to an agent and synchronously await its next response on the session.
      *
@@ -286,26 +321,26 @@ declare class AgentManager {
      * Blocking: always blocks until the agent produces its next response on the session.
      * No polling required.
      */
-    chat(agentId: string, message: any, sessionId?: string): Promise<AgentChatResult>;
+    chat(agentId: string, message: unknown, sessionId?: string): Promise<AgentChatResult>;
     trigger(agentId: string): Promise<AgentTriggerResult>;
-    query(agentId: string): Promise<AgentQueryResult>;
     list(includeTerminated?: boolean): Promise<AgentListResult>;
     delete(agentId: string, remove?: boolean): Promise<AgentDeleteResult>;
     suspend(agentId: string): Promise<AgentSuspendResult>;
     resume(agentId: string, autoWake?: boolean): Promise<AgentSuspendResult>;
-    update(input: AgentUpdateInput): Promise<any>;
-    cancelTask(agentId: string, taskId: string): Promise<any>;
+    update(input: AgentUpdateInput): Promise<unknown>;
+    cancelTask(agentId: string, taskId: string): Promise<unknown>;
     info(agentId: string): Promise<AgentInfoResult>;
     fork(input: AgentForkInput): Promise<AgentForkResult>;
-    context(agentId: string, task?: any): Promise<string>;
-    completeTask(result?: any): Promise<AgentCompleteTaskResult>;
+    context(agentId: string, task?: unknown): Promise<string>;
+    completeTask(result?: unknown): Promise<AgentCompleteTaskResult>;
     failTask(error: string): Promise<AgentFailTaskResult>;
 }
 
 interface JobManagerVenue {
     baseUrl: string;
+    venueId: string;
     auth: {
-        apply(headers: Record<string, string>): void;
+        apply(headers: Record<string, string>, audience?: string): void;
     };
 }
 declare class JobManager {
@@ -317,26 +352,30 @@ declare class JobManager {
     delete(jobId: string): Promise<void>;
     pause(jobId: string): Promise<JobMetadata>;
     resume(jobId: string): Promise<JobMetadata>;
-    sendMessage(jobId: string, message: any): Promise<any>;
+    sendMessage(jobId: string, message: unknown): Promise<unknown>;
     stream(jobId: string): AsyncGenerator<SSEEvent>;
     private _buildHeaders;
 }
 
 interface AssetManagerVenue {
     baseUrl: string;
+    venueId: string;
     auth: {
-        apply(headers: Record<string, string>): void;
-    };
-    operations: {
-        run(assetId: string, input: any): Promise<any>;
+        apply(headers: Record<string, string>, audience?: string): void;
     };
+    operations: OperationRunner;
 }
 declare class AssetManager {
     private venue;
     constructor(venue: AssetManagerVenue);
     /**
-     * Get asset by ID
-     * @param assetId - Asset identifier
+     * Get an asset by lattice address.
+     *
+     * `assetId` may be a content hash (`<hash>`, `a/<hash>`, `<DID>/a/<hash>`) or
+     * 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.
+     * @param assetId - Asset identifier or lattice address
      * @returns Returns either an Operation or DataAsset based on the asset's metadata
      */
     get(assetId: AssetID): Promise<Asset>;
@@ -349,7 +388,7 @@ declare class AssetManager {
      * Register a new asset
      * @param assetData - Asset configuration
      */
-    register(assetData: any): Promise<Asset>;
+    register(assetData: unknown): Promise<Asset>;
     /**
      * Get asset metadata
      * @param assetId - Asset identifier
@@ -382,8 +421,9 @@ declare class AssetManager {
 
 interface OperationManagerVenue {
     baseUrl: string;
+    venueId: string;
     auth: {
-        apply(headers: Record<string, string>): void;
+        apply(headers: Record<string, string>, audience?: string): void;
     };
 }
 declare class OperationManager {
@@ -404,39 +444,104 @@ declare class OperationManager {
      * @param input - Operation input parameters
      * @param options - Invoke options (e.g., ucans)
      */
-    run(assetId: string, input: any, options?: InvokeOptions): Promise<any>;
+    run<T = unknown>(assetId: string, input?: unknown, options?: InvokeOptions): Promise<T>;
     /**
      * Execute an operation and return a Job for tracking
      * @param assetId - Operation asset ID or named operation
      * @param input - Operation input parameters
      * @param options - Invoke options (e.g., ucans)
      */
-    invoke(assetId: string, input: any, options?: InvokeOptions): Promise<Job>;
+    invoke(assetId: string, input?: unknown, options?: InvokeOptions): Promise<Job>;
     private _buildHeaders;
 }
 
 interface WorkspaceManagerVenue {
-    operations: {
-        run(assetId: string, input: any): Promise<any>;
+    baseUrl: string;
+    venueId: string;
+    auth: {
+        apply(headers: Record<string, string>, audience?: string): void;
     };
+    operations: OperationRunner;
+    lastKnownStatus?: StatusData;
 }
+/**
+ * Workspace (lattice) operations against a venue.
+ *
+ * **Reads are job-free.** `read`/`list`/`slice`/`inspect`/`count`/`aggregate` go
+ * through `GET /api/v1/values/*` (covia #177) — synchronous, capability-checked,
+ * and **no Job is persisted**. This matters at scale: routing reads through the
+ * invoke/job path writes one durable job record per read, which grows the venue's
+ * etch without bound under a read-heavy consumer.
+ *
+ * **Writes stay on the job path** (`write`/`delete`/`append`/`copy` via
+ * `operations.run`) — a mutation *should* leave an audit record.
+ *
+ * Paths resolve against the caller's own DID unless fully qualified
+ * (`<DID>/w/...`). Reading another DID's namespace is capability-gated: the
+ * job-free GET path carries only the caller's identity token, so a read that
+ * needs UCAN **proof tokens** (`ucans`) transparently falls back to the invoke
+ * path (the only transport that carries a proof array). Own-namespace reads —
+ * the common case — never need this and stay fully job-free.
+ *
+ * Venues that predate the `/values` routes (< covia 0.3) are accommodated
+ * here, not in application code: a 404 from the GET surface can only mean the
+ * route is missing (an absent path is `200 {exists:false}`), so reads fall
+ * back to the invoke path and the venue is remembered as pre-0.3 for the rest
+ * of this manager's lifetime.
+ */
 declare class WorkspaceManager {
     private venue;
+    private valuesSupported;
     constructor(venue: WorkspaceManagerVenue);
-    read(path: string, maxSize?: number): Promise<WorkspaceReadResult>;
-    write(path: string, value: any): Promise<WorkspaceWriteResult>;
-    delete(path: string): Promise<WorkspaceDeleteResult>;
-    append(path: string, value: any): Promise<WorkspaceAppendResult>;
-    list(path?: string, limit?: number, offset?: number): Promise<WorkspaceListResult>;
-    slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
-    copy(from: string, to: string): Promise<WorkspaceCopyResult>;
-    inspect(paths: string | string[], budget?: number, compact?: boolean): Promise<WorkspaceInspectResult>;
+    private _headers;
+    /** GET a job-free `/api/v1/values/{op}` read; omit undefined params. */
+    private _values;
+    /**
+     * Whether the venue serves `GET /api/v1/values/*`: no if a probe already
+     * 404'd, or if the venue's last known status identifies it as pre-0.3
+     * (venues that old don't report a `version` at all). Checked per read —
+     * connect/`status()` may populate the status after this manager exists.
+     */
+    private supportsValues;
+    /** A job-free values read, falling back to the invoke path on pre-0.3 venues. */
+    private _valuesOr;
+    read(path: string, maxSize?: number, ucans?: string[]): Promise<WorkspaceReadResult>;
+    list(path?: string, limit?: number, offset?: number, ucans?: string[]): Promise<WorkspaceListResult>;
+    slice(path: string, offset?: number, limit?: number, ucans?: string[]): Promise<WorkspaceSliceResult>;
+    inspect(paths: string | string[], budget?: number, compact?: boolean, ucans?: string[]): Promise<WorkspaceInspectResult>;
+    /**
+     * Count entries at a depth below `path` — a job-free server-side tally, so the
+     * caller never reads every record to learn "how many".
+     *
+     * `depth` = the exact number of `get`-steps below `path` to visit (default 1 =
+     * direct children). Records nested at `w/x/<bucket>/<record>` are counted with
+     * `depth: 2`. Absent path or a scalar → `{exists:false}`.
+     */
+    count(path: string, opts?: {
+        depth?: number;
+        ucans?: string[];
+    }): Promise<WorkspaceCountResult>;
+    /**
+     * Count entries at a depth below `path`, optionally partitioned by a field —
+     * the job-free, authoritative alternative to counting client-side.
+     *
+     * `groupBy` names the field whose value forms each group key (may be a relative
+     * path, `foo/bar`); an entry missing it groups under `"null"`. Σ(group counts)
+     * equals the top-level `count`.
+     */
+    aggregate(path: string, opts?: {
+        depth?: number;
+        groupBy?: string;
+        ucans?: string[];
+    }): Promise<WorkspaceAggregateResult>;
+    write(path: string, value: unknown, ucans?: string[]): Promise<WorkspaceWriteResult>;
+    delete(path: string, ucans?: string[]): Promise<WorkspaceDeleteResult>;
+    append(path: string, value: unknown, ucans?: string[]): Promise<WorkspaceAppendResult>;
+    copy(from: string, to: string, ucans?: string[]): Promise<WorkspaceCopyResult>;
 }
 
 interface UCANManagerVenue {
-    operations: {
-        run(assetId: string, input: any): Promise<any>;
-    };
+    operations: OperationRunner;
 }
 declare class UCANManager {
     private venue;
@@ -445,11 +550,8 @@ declare class UCANManager {
 }
 
 interface SecretManagerVenue {
-    operations: {
-        run(assetId: string, input: any): Promise<any>;
-    };
+    operations: OperationRunner;
     listSecrets(): Promise<string[]>;
-    putSecret(name: string, value: string): Promise<void>;
     deleteSecret(name: string): Promise<void>;
 }
 declare class SecretManager {
@@ -458,20 +560,36 @@ declare class SecretManager {
     set(name: string, value: string): Promise<SecretSetResult>;
     /**
      * Extract a secret value by name.
-     * NOTE: This operation requires a UCAN capability grant. The backend
-     * may reject requests that lack the appropriate capability proof.
+     * Requires a UCAN capability grant — pass the proof token(s) as `ucans`.
+     * Extracting another DID's secret needs a grant on that DID's `/s/<name>`.
      */
-    extract(name: string): Promise<SecretExtractResult>;
+    extract(name: string, ucans?: string[]): Promise<SecretExtractResult>;
     list(): Promise<string[]>;
-    put(name: string, value: string): Promise<void>;
     delete(name: string): Promise<void>;
 }
 
+/**
+ * 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
+ * honoured as given (trailing slash trimmed, single candidate, no fallback);
+ * schemeless inputs (bare host / IP / host:port) pick a scheme by host — local
+ * hosts (loopback, private ranges, mDNS) try http then https, public hosts stay
+ * https-only. `did:*` ids are resolved separately and are not handled here.
+ */
+declare function venueBaseUrlCandidates(venueId: string): string[];
 declare class Venue implements VenueInterface {
     baseUrl: string;
     venueId: string;
     auth: Auth;
     metadata: VenueData;
+    /**
+     * The most recent status this instance has seen — seeded by {@link connect}
+     * (which fetches `/api/v1/status` anyway) and refreshed by every
+     * {@link status} call. Undefined until one of those has happened, e.g. on a
+     * directly constructed venue. Managers use it as a capability hint (venue
+     * `version`); it is a cache, not a liveness check.
+     */
+    lastKnownStatus?: StatusData;
     private _agents?;
     private _jobs?;
     private _assets?;
@@ -488,10 +606,25 @@ declare class Venue implements VenueInterface {
     get secrets(): SecretManager;
     constructor(options?: VenueOptions);
     /**
-     * Static method to connect to a venue
-     * @param venueId - Can be a HTTP base URL, DNS name, or existing Venue instance
-     * @param credentials - Optional credentials for venue authentication
-     * @returns {Promise<Venue>} A new Venue instance configured appropriately
+     * 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
+     * venue is validated against its public did:web document at
+     * `/.well-known/did.json` instead, whose `id` becomes `venueId` — identity is
+     * publicly resolvable by spec even when the API is not.
+     *
+     * The input is permissive: a full `http(s)://` URL, a bare host / IP /
+     * host:port, a `did:web:` id, or an existing Venue instance. Schemeless inputs
+     * pick a scheme by host and may fall back across http/https (see
+     * {@link venueBaseUrlCandidates}); did:web ids resolve to their `Covia.API.v1`
+     * endpoint.
+     *
+     * @param venueId - A venue URL, DNS name / host:port, `did:web:` id, or existing Venue
+     * @param auth - Optional credentials for venue authentication
+     * @returns {Promise<Venue>} A connected venue. The actually resolved/validated
+     *   target is on the returned object: `venue.baseUrl` is the origin that
+     *   responded (the https candidate if an http fallback failed; the resolved
+     *   endpoint for a did:web id), and `venue.venueId` is the DID the venue
+     *   reported. The validated API root is `${venue.baseUrl}/api/v1`.
      */
     static connect(venueId: string | Venue, auth?: Auth): Promise<Venue>;
     /**
@@ -529,12 +662,6 @@ declare class Venue implements VenueInterface {
      * @returns {Promise<string[]>}
      */
     listSecrets(): Promise<string[]>;
-    /**
-     * Store a secret value
-     * @param name - Secret name
-     * @param value - Secret value
-     */
-    putSecret(name: string, value: string): Promise<void>;
     /**
      * Delete a secret
      * @param name - Secret name
@@ -545,6 +672,23 @@ declare class Venue implements VenueInterface {
      * @returns {Promise<StatusData>}
      */
     status(): Promise<StatusData>;
+    /**
+     * Block until the venue is ready to serve operations.
+     *
+     * Polls {@link status} until it responds and reports either no explicit
+     * `status` or `"OK"`. Connection/HTTP errors are treated as "not ready yet"
+     * and retried until `timeoutMs` elapses — useful right after starting a venue,
+     * since a cold venue may answer its root before its invoke layer is up.
+     *
+     * @param options.timeoutMs - Max time to wait (default 60000).
+     * @param options.pollIntervalMs - Delay between polls (default 1000).
+     * @returns The ready {@link StatusData}.
+     * @throws {CoviaTimeoutError} If the venue is not ready within the timeout.
+     */
+    waitUntilReady(options?: {
+        timeoutMs?: number;
+        pollIntervalMs?: number;
+    }): Promise<StatusData>;
     /**
      * Get the full DID document for this venue
      * @returns {Promise<DIDDocument>}
@@ -578,6 +722,8 @@ interface VenueOptions {
     name?: string;
     description?: string;
     auth?: Auth;
+    /** Status observed while connecting — seeds {@link Venue.lastKnownStatus}. */
+    status?: StatusData;
 }
 interface VenueConstructor {
     new (): VenueInterface;
@@ -586,6 +732,14 @@ interface VenueConstructor {
 interface InvokeOptions {
     ucans?: string[];
 }
+/**
+ * The venue's operation-execution surface, as the typed managers consume it.
+ * `run<T>` returns the operation's result typed as `T` (defaults to `unknown`,
+ * so an un-parameterised call stays type-safe rather than leaking `any`).
+ */
+interface OperationRunner {
+    run<T = unknown>(assetId: string, input?: unknown, options?: InvokeOptions): Promise<T>;
+}
 interface VenueInterface {
     baseUrl: string;
     venueId: string;
@@ -600,7 +754,6 @@ interface VenueInterface {
     mcpDiscovery(): Promise<MCPDiscovery>;
     agentCard(): Promise<AgentCard>;
     listSecrets(): Promise<string[]>;
-    putSecret(name: string, value: string): Promise<void>;
     deleteSecret(name: string): Promise<void>;
     agent(agentId: string): Agent;
     close(): void;
@@ -642,16 +795,17 @@ interface ContentHashResult {
     hash: string;
 }
 interface JobMetadata {
+    id?: string;
     name?: string;
     status?: RunStatus;
     created?: string;
     updated?: string;
-    input?: any;
-    output?: any;
+    input?: unknown;
+    output?: unknown;
     operation?: string;
     caller?: string;
     error?: string;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 interface InvokePayload {
     assetId: AssetID;
@@ -678,6 +832,8 @@ interface StatusData {
     status?: string;
     did?: string;
     name?: string;
+    /** Venue platform version (e.g. "0.3.0"). Absent on venues before 0.3. */
+    version?: string;
     stats?: StatsData;
 }
 interface StatsData {
@@ -704,13 +860,23 @@ interface MCPDiscovery {
     endpoint?: Record<string, any> | string;
     [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
+ * official A2A Java SDK). The index signature preserves any spec fields a
+ * given venue build adds (e.g. `securitySchemes`, `protocolVersion`).
+ */
 interface AgentCard {
-    agentProvider?: Record<string, any>;
-    agentCapabilities?: Record<string, any>;
-    agentSkills?: Record<string, any>[];
-    agentInterfaces?: Record<string, any>[];
-    securityScheme?: Record<string, any>;
-    preferredTransport?: Record<string, any>;
+    name: string;
+    description?: string;
+    version?: string;
+    provider?: Record<string, any>;
+    capabilities?: Record<string, any>;
+    defaultInputModes?: string[];
+    defaultOutputModes?: string[];
+    skills?: Record<string, any>[];
+    supportedInterfaces?: Record<string, any>[];
+    preferredTransport?: string;
     [key: string]: any;
 }
 interface DIDDocument {
@@ -733,7 +899,7 @@ interface SSEEvent {
     id: string | null;
     retry: number | null;
     /** Parse the event data as JSON. */
-    json: () => any;
+    json: () => unknown;
 }
 declare enum AgentStatus {
     SLEEPING = "SLEEPING",
@@ -789,17 +955,6 @@ interface AgentTriggerResult {
     result?: any;
     taskResults?: any[];
 }
-interface AgentQueryInput {
-    agentId: string;
-}
-interface AgentQueryResult {
-    agentId: string;
-    status: string;
-    state?: Record<string, any>;
-    config?: Record<string, any>;
-    tasks?: any[];
-    [key: string]: any;
-}
 interface AgentListInput {
     includeTerminated?: boolean;
 }
@@ -877,7 +1032,10 @@ interface AssetPinResult {
     hash: string;
 }
 interface WorkspaceCopyResult {
-    copied: boolean;
+    /** 0.3.0 (#147): `false` = copy created a new value at the destination, `true` = it replaced an existing one. */
+    existed?: boolean;
+    /** 0.3.0: present and true only if a new parent path was built at the destination. */
+    pathCreated?: boolean;
 }
 interface WorkspaceInspectInput {
     paths: string | string[];
@@ -885,7 +1043,8 @@ interface WorkspaceInspectInput {
     compact?: boolean;
 }
 interface WorkspaceInspectResult {
-    result: any;
+    /** Rendered string for a single path, or a `{path: string}` map for multiple. */
+    result: string | Record<string, string>;
 }
 interface WorkspaceReadInput {
     path: string;
@@ -895,39 +1054,58 @@ interface WorkspaceReadResult {
     exists: boolean;
     value?: any;
     truncated?: boolean;
-    size?: number;
+    /** Convex type name; included on a truncated read (0.3.0) so the caller can
+     *  fall back to `list` (map) or `slice` (sequence) instead of guessing. */
+    type?: string;
+    /** 0.3.0: encoded size in bytes (always present). */
+    valueBytes?: number;
 }
 interface WorkspaceWriteInput {
     path: string;
     value: any;
 }
 interface WorkspaceWriteResult {
-    written: boolean;
+    /** 0.3.0 (#147): `false` = a new value was created, `true` = an existing one was replaced (a stored null counts as present). */
+    existed?: boolean;
+    /** 0.3.0: true iff the write built a new parent path; omitted otherwise. */
+    pathCreated?: boolean;
 }
 interface WorkspaceDeleteInput {
     path: string;
 }
 interface WorkspaceDeleteResult {
-    deleted: boolean;
+    /** 0.3.0 (#147): `true` = a value was present and removed, `false` = idempotent no-op. (Pre-0.3.0 this was a constant `true`, then an empty object.) */
+    deleted?: boolean;
 }
 interface WorkspaceAppendInput {
     path: string;
     value: any;
 }
 interface WorkspaceAppendResult {
-    appended: boolean;
+    /** 0.3.0 (#147): `false` = a new collection was created, `true` = an existing one was extended. */
+    existed?: boolean;
+    /** 0.3.0 (#147): the position the appended element landed at (`newSize - 1`). */
+    index?: number;
+    /** 0.3.0: vector element count after the append. */
+    newSize?: number;
+    /** 0.3.0: true iff a new parent path was built. */
+    pathCreated?: boolean;
 }
 interface WorkspaceListInput {
     path?: string;
     limit?: number;
     offset?: number;
 }
+/** Result of `covia:list` — the direct children of a node. A map lists its
+ *  `keys`; sets and vectors report only `type` + `count` (page their elements
+ *  with `slice`). */
 interface WorkspaceListResult {
     exists: boolean;
     type: string;
+    /** total entries in the collection (the single cardinality word). */
     count?: number;
+    /** populated for maps; omitted for sets/vectors/scalars. */
     keys?: string[];
-    values?: any[];
     offset?: number;
 }
 interface WorkspaceSliceInput {
@@ -937,10 +1115,32 @@ interface WorkspaceSliceInput {
 }
 interface WorkspaceSliceResult {
     exists: boolean;
-    type: string;
-    values: any[];
-    count: number;
-    offset: number;
+    type?: string;
+    values?: any[];
+    /** total entries in the collection (the single cardinality word). */
+    count?: number;
+    offset?: number;
+}
+/** Job-free tally (#177). `exists` = a countable collection is present at the
+ *  path (absent path, or a scalar with nothing to descend into → `{exists:false}`,
+ *  no `count`; an empty or too-deep collection → `{exists:true, count:0}`). */
+interface WorkspaceCountResult {
+    exists: boolean;
+    count?: number;
+}
+/** One group's metrics in `WorkspaceAggregateResult.groups`. `count` today;
+ *  numeric reductions (`sum`/`min`/`max`) will add keys additively. */
+interface GroupCount {
+    count?: number;
+    [key: string]: number | undefined;
+}
+interface WorkspaceAggregateResult {
+    exists: boolean;
+    count?: number;
+    /** Present when `groupBy` was supplied: each distinct field value → a
+     *  `GroupCount`. An entry lacking the field groups under the `"null"` key.
+     *  Σ(group counts) == count. */
+    groups?: Record<string, GroupCount>;
 }
 interface UCANAttenuation {
     with: string;
@@ -952,7 +1152,10 @@ interface UCANIssueInput {
     exp: number;
 }
 interface UCANIssueResult {
-    [key: string]: any;
+    /** The issued delegation token — pass as an element of the `ucans` array on
+     *  subsequent invokes. */
+    token: string;
+    [key: string]: unknown;
 }
 interface SecretSetInput {
     name: string;
@@ -992,8 +1195,8 @@ declare class CoviaError extends Error {
 /** Raised when the Covia API returns an error response (4xx/5xx). */
 declare class GridError extends CoviaError {
     statusCode: number;
-    responseBody: any;
-    constructor(statusCode: number, message: string, responseBody?: any);
+    responseBody: unknown;
+    constructor(statusCode: number, message: string, responseBody?: unknown);
 }
 /** Raised when the SDK cannot connect to the venue. */
 declare class CoviaConnectionError extends CoviaError {
@@ -1062,7 +1265,8 @@ declare function isJobFinished(jobStatus: RunStatus): boolean;
  */
 declare function getParsedAssetId(assetId: string): string;
 /**
- * Utility function to return complete assetId from hex and path
+ * Utility function to return complete assetId from hex and an API path of the
+ * form `/api/v1/assets/<encoded-did>/...`.
  * @param assetHex - The asset hex
  * @param assetPath - The asset path
  * @returns {string} - Returns the complete assetId
@@ -1084,6 +1288,65 @@ declare function createSSEEvent(fields: {
  */
 declare function parseSSEStream(response: Response): AsyncGenerator<SSEEvent>;
 
+/**
+ * DID and lattice-path helpers for the Covia grid.
+ *
+ * Covia addresses its lattice as `<DID>/<namespace>/<path...>`. These helpers
+ * build and parse those addresses so callers don't hand-concatenate strings.
+ *
+ * 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 namespace-relative path (no `<DID>`) resolves to the authenticated caller.
+ */
+/** Lattice namespace identifiers. */
+declare const Namespace: {
+    readonly ASSET: "a";
+    readonly OPERATION: "o";
+    readonly JOB: "j";
+    readonly AGENT: "g";
+    readonly WORKSPACE: "w";
+    readonly SECRET: "s";
+    readonly AGENT_SCRATCH: "n";
+    readonly SESSION_SCRATCH: "c";
+    readonly JOB_SCRATCH: "t";
+    readonly VENUE: "v";
+};
+/** A parsed lattice address. */
+interface DIDURL {
+    did: string | null;
+    namespace: string | null;
+    path: string;
+}
+/** True if `value` is a bare DID (`did:<method>:<id>`), not a DID URL with a path. */
+declare function isDid(value: string): boolean;
+/** The DID method (e.g. `'key'`, `'web'`), or null if `value` is not a DID. */
+declare function didMethod(value: string): string | null;
+/**
+ * Split a lattice address into its DID, namespace, and path. Handles bare DIDs,
+ * namespace-relative paths (`w/foo` or `/w/foo`), and fully-qualified DID URLs
+ * (`did:key:z.../w/foo`); did:web `:` path separators inside the DID are kept.
+ */
+declare function parseDidUrl(value: string): DIDURL;
+/**
+ * Build a lattice address `<did>/<namespace>/<segments...>`. Pass `did = null`
+ * for a namespace-relative path. Stray surrounding slashes on segments are
+ * stripped and empty segments dropped.
+ *
+ * Remember the ownership rules above: for `w`/`o`/`g`/`j`/`s` the `did` is the
+ * resource owner's DID, not the venue's.
+ */
+declare function didUrl(did: string | null, namespace: string, ...segments: string[]): string;
+/**
+ * The content hash `ref` pins to, or null if it isn't content-addressed.
+ * Recognises a bare hex hash, `a/<hash>`, and `<DID>/a/<hash>` — the forms that
+ * name a specific immutable asset. Mutable lattice paths (`w/…`, `o/…`) return
+ * null: they resolve server-side, so there's no client-side hash and they must
+ * not be treated as immutable (e.g. cached).
+ */
+declare function assetHash(ref: string): string | null;
+
 /**
  * Simple logger for the Covia SDK.
  *
@@ -1106,7 +1369,7 @@ declare class Grid {
     /**
     * Static method to connect to a venue
     * @param venueId - Can be a HTTP base URL, DNS name, or existing Venue instance
-    * @param auth - Optional authentication provider (BearerAuth, KeyPairAuth, etc.)
+    * @param auth - Optional authentication provider (BearerAuth, BasicAuth, Ed25519Auth, etc.)
     * @returns {Promise<Venue>} A new Venue instance configured appropriately
     */
     static connect(venueId: string, auth?: Auth): Promise<Venue>;
@@ -1163,4 +1426,4 @@ declare function decodePublicKey(multikey: string): Uint8Array;
  */
 declare function didFromPublicKey(publicKey: Uint8Array): string;
 
-export { type AdapterInfo, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentDeleteInput, type AgentDeleteResult, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentQueryInput, type AgentQueryResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, AgentStatus, type AgentSuspendResult, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListOptions, AssetManager, type AssetMetadata, AssetNotFoundError, type AssetPinResult, Auth, BearerAuth, ChatSession, type ContentDetails, type ContentHashResult, CoviaConnectionError, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, DataAsset, type FunctionInfo, type FunctionsResult, Grid, GridError, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type StatsData, type StatusData, type UCANAttenuation, type UCANIssueInput, type UCANIssueResult, UCANManager, Venue, type VenueConstructor, type VenueData, type VenueInterface, type VenueOptions, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, 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, createSSEEvent, decodePublicKey, didFromPublicKey, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getParsedAssetId, hexToPrivateKey, isJobComplete, isJobFinished, isJobPaused, logger, parseSSEStream, privateKeyToHex };
+export { type AdapterInfo, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentDeleteInput, type AgentDeleteResult, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, AgentStatus, type AgentSuspendResult, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListOptions, AssetManager, type AssetMetadata, AssetNotFoundError, type AssetPinResult, Auth, BasicAuth, BearerAuth, ChatSession, type ContentDetails, type ContentHashResult, CoviaConnectionError, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, DataAsset, Ed25519Auth, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type StatsData, type StatusData, type UCANAttenuation, type UCANIssueInput, type UCANIssueResult, UCANManager, Venue, type VenueConstructor, type VenueData, 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, decodePublicKey, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getParsedAssetId, hexToPrivateKey, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseSSEStream, privateKeyToHex, venueBaseUrlCandidates };