@covia/covia-sdk 1.6.0 → 1.7.0

package/README.md

@@ -118,8 +118,26 @@ venue.metadata;   // { name, description }
 | `venue.didDocument()` | Get the venue's DID document |
 | `venue.mcpDiscovery()` | Get MCP (Model Context Protocol) discovery info |
 | `venue.agentCard()` | Get A2A (Agent-to-Agent) agent card |
+| `venue.setPrivate(enabled)` | Toggle private-jobs mode for this connection (see below) |
 | `venue.close()` | Release resources and clear caches |
 
+#### Private jobs
+
+`venue.setPrivate(true)` puts the connection in **private-jobs mode**: every
+subsequent `operations.run()` executes as a memory-only job — never persisted
+to the venue's job index, gone on venue restart. The venue must have
+`enablePrivateJobs` set. Because a completed private job is immediately
+forgotten by the venue, results are collected through the server-side invoke
+`wait` window rather than polling — so private mode works with `run()`, and
+poll-style `operations.invoke()` throws.
+
+```typescript
+venue.setPrivate(true);
+const result = await venue.operations.run("v/ops/schema/infer", {
+  value: { name: "Ada", age: 36 },
+});
+```
+
 ---
 
 ### Operations — `venue.operations`
@@ -160,6 +178,22 @@ const job = await venue.operations.invoke("sensitive:op", input, {
 
 ---
 
+### Adapters — `venue.adapters`
+
+List the adapters registered on a venue — the true registry, including adapters
+with zero catalogued operations. Backed by the venue's canonical
+`v/info/adapters/<name>` lattice data, read job-free via the values API.
+
+```typescript
+// All registered adapters
+const adapters = await venue.adapters.list();
+adapters.forEach((a) => console.log(`${a.name}: ${a.operations.length} ops`));
+
+// One adapter's summary (null if not registered)
+const covia = await venue.adapters.get("covia");
+console.log(covia?.description, covia?.operations);
+```
+
 ### Assets — `venue.assets`
 
 Manage data assets and operations registered on the venue.
@@ -509,7 +543,31 @@ const token = await venue.ucan.issue("did:key:z6MkBob", att, exp);
 
 | Method | Returns | Description |
 |---|---|---|
-| `ucan.issue(aud, att, exp)` | `UCANIssueResult` | Issue a UCAN token |
+| `ucan.issue(aud, att, exp)` | `UCANIssueResult` | Issue a venue-signed UCAN token |
+| `ucan.verify(token, check?)` | `UCANVerifyResult` | Diagnose a token against the venue's trust policy |
+
+`ucan.verify` explains a token's verdict — `valid`/`reason`, `chainDepth`,
+`rootIssuer`, and a per-capability `rootAuthority` (`owner` / `venue` /
+`refused`). Pass `check: { with, can, aud }` to also ask whether the token
+would authorise a specific request (`authorises`).
+
+#### Client-side minting
+
+Tokens can also be minted locally with your own Ed25519 key — no venue
+round-trip:
+
+```typescript
+import { grant, identityToken, relayDelegation, didFor } from "@covia/covia-sdk";
+
+// Self-sovereign grant over your own namespace — verifies on ANY venue
+const token = grant(privateKey, "did:key:z6MkBob", `${didFor(privateKey)}/w/shared/`, "crud/read", 3600);
+
+// Identity token — proves control of your DID to a venue (empty attenuation)
+const idToken = identityToken(privateKey, venue.venueId);
+
+// Relay delegation — authorises the venue to forward your authority cross-venue
+const relay = relayDelegation(privateKey, venue.venueId, 300, [{ with: `${didFor(privateKey)}/w/`, can: "crud/read" }]);
+```
 
 ---
 
@@ -527,6 +585,7 @@ import {
   CoviaConnectionError,// Connection failures
   CoviaTimeoutError,   // Timeout exceeded
   JobFailedError,      // Job finished with non-COMPLETE status
+  RateLimitError,      // 429 after bounded retries (carries retryAfterSeconds)
 } from "@covia/covia-sdk";
 
 try {
@@ -579,7 +638,7 @@ RunStatus.AUTH_REQUIRED;   // Waiting for authentication
 ```typescript
 import {
   Venue, Grid, Job, Agent, ChatSession, Asset, Operation, DataAsset,
-  AssetManager, OperationManager, JobManager,
+  AdapterManager, AssetManager, OperationManager, JobManager,
   AgentManager, WorkspaceManager, SecretManager, UCANManager,
   KeyPairAuth, BearerAuth,
   RunStatus, CoviaError,

package/dist/index.d.mts

@@ -296,12 +296,57 @@ declare class CredentialsHTTP implements Credentials {
     constructor(venueId: string, apiKey: string, userId: string);
 }
 
+interface AdapterManagerVenue {
+    workspace: {
+        slice(path: string, offset?: number, limit?: number, ucans?: string[]): Promise<WorkspaceSliceResult>;
+        read(path: string, maxSize?: number, ucans?: string[]): Promise<WorkspaceReadResult>;
+    };
+}
+/**
+ * Adapter introspection for a venue.
+ *
+ * Reads go through the workspace manager, so they are job-free (`GET
+ * /api/v1/values/*`, covia #177) on 0.3+ venues and transparently fall back
+ * to the invoke path on older ones — the same job-free/fallback behaviour
+ * every other workspace-backed read gets, rather than a hand-rolled fetch.
+ */
+declare class AdapterManager {
+    private venue;
+    constructor(venue: AdapterManagerVenue);
+    /**
+     * List the adapters registered on the venue, with their descriptions and
+     * invocable operation catalog paths. Registered-but-inactive or zero-op
+     * adapters are included — this is the true registry, not an inference
+     * from the operations catalog.
+     */
+    list(): Promise<AdapterInfo[]>;
+    /**
+     * Get a single adapter's summary by name.
+     * @param name - Adapter name, e.g. "mcp"
+     * @returns {Promise<AdapterInfo | null>} `null` if no adapter with that name is registered
+     */
+    get(name: string): Promise<AdapterInfo | null>;
+}
+
 interface AgentManagerVenue {
+    baseUrl: string;
+    venueId: string;
+    auth: {
+        apply(headers: Record<string, string>, audience?: string): void;
+    };
     operations: OperationRunner;
+    lastKnownStatus?: StatusData;
 }
 declare class AgentManager {
     private venue;
+    private agentsGetSupported;
     constructor(venue: AgentManagerVenue);
+    private _headers;
+    /** Whether the venue serves `GET /api/v1/agents`: no if a probe already
+     *  404'd, or if the venue's last known status identifies it as pre-0.4. */
+    private supportsAgentsGet;
+    /** A job-free agents GET, falling back to the invoke path on pre-0.4 venues. */
+    private _agentsOr;
     create(input: AgentCreateInput): Promise<AgentCreateResult>;
     request(agentId: string, input?: unknown, wait?: boolean | number): Promise<AgentRequestResult>;
     message(agentId: string, message: unknown): Promise<AgentMessageResult>;
@@ -323,12 +368,19 @@ declare class AgentManager {
      */
     chat(agentId: string, message: unknown, sessionId?: string): Promise<AgentChatResult>;
     trigger(agentId: string): Promise<AgentTriggerResult>;
+    /**
+     * List the caller's agents. **Job-free** on covia ≥ 0.4: goes through
+     * `GET /api/v1/agents` (covia#180) — synchronous, no Job persisted. Older
+     * venues transparently fall back to the invoke path (one probe, remembered).
+     */
     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<unknown>;
     cancelTask(agentId: string, taskId: string): Promise<unknown>;
+    /** Agent info. **Job-free** on covia ≥ 0.4 (`GET /api/v1/agents/{id}`,
+     *  covia#180); older venues fall back to the invoke path. */
     info(agentId: string): Promise<AgentInfoResult>;
     fork(input: AgentForkInput): Promise<AgentForkResult>;
     context(agentId: string, task?: unknown): Promise<string>;
@@ -425,6 +477,7 @@ interface OperationManagerVenue {
     auth: {
         apply(headers: Record<string, string>, audience?: string): void;
     };
+    privateJobs?: boolean;
 }
 declare class OperationManager {
     private venue;
@@ -445,6 +498,15 @@ declare class OperationManager {
      * @param options - Invoke options (e.g., ucans)
      */
     run<T = unknown>(assetId: string, input?: unknown, options?: InvokeOptions): Promise<T>;
+    /**
+     * Private-mode execution (covia #192): a memory-only job whose result is
+     * collected through the invoke `wait` window — a completed private job is
+     * immediately forgotten by the venue, so polling cannot be used. If the
+     * operation outlives the venue's wait cap, polling continues while the job
+     * runs; a job that completes between polls is unobservable and surfaces as
+     * a clear error rather than a confusing 404.
+     */
+    private _runPrivate;
     /**
      * Execute an operation and return a Job for tracking
      * @param assetId - Operation asset ID or named operation
@@ -547,6 +609,18 @@ declare class UCANManager {
     private venue;
     constructor(venue: UCANManagerVenue);
     issue(aud: string, att: UCANAttenuation[], exp: number): Promise<UCANIssueResult>;
+    /**
+     * Verify a UCAN against the venue's trust policy and get the verdict
+     * explained — validity with a diagnosable reason, chain depth and root
+     * issuer, per-capability root-authority (owner / venue / refused), and,
+     * when `check` is supplied, whether the token would authorise that request
+     * here. The diagnostic counterpart to an enforcement "Access denied".
+     */
+    verify(token: string | object, check?: {
+        with?: string;
+        can?: string;
+        aud?: string;
+    }): Promise<UCANVerifyResult>;
 }
 
 interface SecretManagerVenue {
@@ -578,6 +652,19 @@ declare class SecretManager {
  */
 declare function venueBaseUrlCandidates(venueId: string): string[];
 declare class Venue implements VenueInterface {
+    /** Connection-level private-jobs mode — see {@link setPrivate}. */
+    privateJobs: boolean;
+    /**
+     * Puts this connection in **private-jobs mode**: every subsequent
+     * `operations.run(...)` executes as a memory-only job (covia #192) — never
+     * persisted to the venue's job index, no durable record, gone on venue
+     * restart. Requires `enablePrivateJobs` on the venue.
+     *
+     * Because a completed private job is immediately forgotten, results are
+     * collected through the invoke `wait` window rather than polling — so
+     * private mode works with `run()`; a poll-style `invoke()` throws.
+     */
+    setPrivate(enabled: boolean): void;
     baseUrl: string;
     venueId: string;
     auth: Auth;
@@ -590,6 +677,7 @@ declare class Venue implements VenueInterface {
      * `version`); it is a cache, not a liveness check.
      */
     lastKnownStatus?: StatusData;
+    private _adapters?;
     private _agents?;
     private _jobs?;
     private _assets?;
@@ -597,6 +685,7 @@ declare class Venue implements VenueInterface {
     private _workspace?;
     private _ucan?;
     private _secrets?;
+    get adapters(): AdapterManager;
     get agents(): AgentManager;
     get jobs(): JobManager;
     get assets(): AssetManager;
@@ -1151,6 +1240,26 @@ interface UCANIssueInput {
     att: UCANAttenuation[];
     exp: number;
 }
+/** Result of `ucan:verify` — the diagnostic verdict on a token. */
+interface UCANVerifyResult {
+    valid: boolean;
+    /** When invalid: a diagnosable reason (expired, bad signature, unparseable, ...). */
+    reason?: string;
+    iss?: string;
+    aud?: string;
+    exp?: number;
+    /** Delegation hops above this token (0 = a root grant). */
+    chainDepth?: number;
+    /** The DID that signed the root of the delegation chain. */
+    rootIssuer?: string;
+    /** Capabilities, each annotated with rootAuthority: owner | venue | refused. */
+    att?: Array<UCANAttenuation & {
+        rootAuthority?: string;
+    }>;
+    /** Present when with/can supplied: whether the token authorises that request. */
+    authorises?: boolean;
+    [key: string]: unknown;
+}
 interface UCANIssueResult {
     /** The issued delegation token — pass as an element of the `ucans` array on
      *  subsequent invokes. */
@@ -1180,9 +1289,13 @@ interface FunctionInfo {
 interface FunctionsResult {
     functions: FunctionInfo[];
 }
+/** Per-adapter summary the venue materialises at `v/info/adapters/<name>`
+ *  (OPERATIONS.md §3). */
 interface AdapterInfo {
     name: string;
     description?: string;
+    /** Full catalog paths of the adapter's invocable operations
+     *  (`v/ops/...`, `v/test/ops/...`), each runnable via `operations.run`. */
     operations: string[];
 }
 interface AdaptersResult {
@@ -1212,6 +1325,13 @@ declare class JobFailedError extends CoviaError {
     constructor(jobData: JobMetadata);
 }
 /** Raised when a requested resource is not found (404). */
+/** HTTP 429 from the venue — a rate limit or concurrent-job cap. Carries the
+ *  server's Retry-After hint (seconds). Thrown only after the SDK's bounded
+ *  automatic retries are exhausted. */
+declare class RateLimitError extends GridError {
+    retryAfterSeconds: number;
+    constructor(message: string, retryAfterSeconds: number, body?: unknown);
+}
 declare class NotFoundError extends GridError {
     constructor(message: string);
 }
@@ -1226,12 +1346,11 @@ declare class JobNotFoundError extends NotFoundError {
     constructor(jobId: string);
 }
 
-/**
- * Utility function to handle API calls with consistent error handling
- * @param url - The URL to fetch
- * @param options - Fetch options
- * @returns {Promise<T>} The response data
- */
+/** Parse a Retry-After header (delta-seconds or HTTP-date) to ms from now. */
+declare function parseRetryAfterMs(header: string | null, nowMs: number): number;
+/** Delay before the next attempt after a 429, or -1 to give up. Pure — random
+ *  in [0,1) supplied by the caller so tests are deterministic. */
+declare function retryDelayMs(attempt: number, retryAfterMs: number, remainingBudgetMs: number, random: number): number;
 declare function fetchWithError<T>(url: string, options?: RequestInit): Promise<T>;
 /**
  * Utility function to handle fetch requests that return streams
@@ -1426,4 +1545,58 @@ 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 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 };
+/**
+ * Client-side UCAN minting for self-sovereign callers — the tokens a principal
+ * signs with their OWN key (a venue cannot sign as the caller, so these have
+ * no venue-op counterpart; venues only verify). Java parity:
+ * covia-core `covia.grid.auth.UcanTokens`.
+ *
+ * All helpers return the JWT encoding — the transport form carried in the
+ * `ucans` request array and relayed across cross-venue hops. Delegation chains
+ * embed parent tokens as JWT strings in `prf`.
+ */
+/** The ability that instructs a venue to relay a cross-venue hop as itself. */
+declare const VENUE_RELAY = "venue/relay";
+interface UCANCapability {
+    with: string;
+    can: string;
+}
+/** The did:key DID for a private key. */
+declare function didFor(privateKey: Uint8Array): string;
+/**
+ * Mint a UCAN as an EdDSA JWT: `{iss, aud, att, exp[, prf]}` signed by
+ * `privateKey` (iss = its did:key).
+ *
+ * @param privateKey 32-byte Ed25519 private key (the issuer)
+ * @param audienceDID who receives the token (`aud`)
+ * @param att capabilities delegated (empty array = pure identity token)
+ * @param lifetimeSeconds validity window
+ * @param proofs parent UCAN JWT strings (`prf`) for delegation chains
+ */
+declare function createUCANJWT(privateKey: Uint8Array, audienceDID: string, att: UCANCapability[], lifetimeSeconds: number, proofs?: string[]): string;
+/**
+ * Mint an **identity token**: a UCAN with an EMPTY attenuation list, audienced
+ * to `venueDID`. Pure proof of identity — it grants nothing, and being
+ * audience-bound it is unusable at any other venue. Present it in the `ucans`
+ * array; the venue accepts it as the caller identity on an
+ * otherwise-unauthenticated transport (how identity crosses cross-venue
+ * relays — COG-3 §6, COG-15).
+ */
+declare function identityToken(privateKey: Uint8Array, venueDID: string, lifetimeSeconds?: number): string;
+/**
+ * Mint an owner-signed (**self-sovereign**) grant: delegates `(with, can)` to
+ * `audienceDID`, rooted by the signer. Because the root issuer is the resource
+ * owner, the grant verifies on ANY venue hosting the data — no venue involved
+ * in issuance.
+ */
+declare function grant(ownerPrivateKey: Uint8Array, audienceDID: string, withResource: string, can: string, lifetimeSeconds: number): string;
+/**
+ * Mint a **relay delegation**: instructs and authorises `venueDID` to make a
+ * cross-venue hop authenticated as itself, exercising the caller's authority.
+ * Carries the `venue/relay` instruction plus the substantive capabilities the
+ * venue may exercise. The venue honours it only when its issuer is the
+ * authenticated caller (COG-15).
+ */
+declare function relayDelegation(privateKey: Uint8Array, venueDID: string, lifetimeSeconds: number, caps?: UCANCapability[]): string;
+
+export { type AdapterInfo, AdapterManager, 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, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, VENUE_RELAY, 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, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, venueBaseUrlCandidates };