@covia/covia-sdk 1.8.0 → 1.9.0

package/README.md

@@ -25,14 +25,14 @@ yarn add @covia/covia-sdk
 ## Quick Start
 
 ```typescript
-import { Grid, KeyPairAuth } from "@covia/covia-sdk";
+import { Grid, Ed25519Auth } from "@covia/covia-sdk";
 
 // Connect to a venue (URL, DNS name, or DID)
-const venue = await Grid.connect("https://venue.covia.ai");
+const venue = await Grid.connect("https://your-venue.example.com");
 
 // Or connect with keypair authentication
-const auth = KeyPairAuth.generate();
-const venue = await Grid.connect("did:web:venue.covia.ai", auth);
+const auth = Ed25519Auth.generate();
+const venue = await Grid.connect("did:web:your-venue.example.com", auth);
 
 // Run an operation and get the result
 const result = await venue.operations.run("v/ops/schema/infer", {
@@ -65,34 +65,34 @@ venue.close();
 The SDK supports three connection methods:
 
 ```typescript
-import { Grid, Venue, KeyPairAuth, BearerAuth } from "@covia/covia-sdk";
+import { Grid, Venue, Ed25519Auth, BearerAuth } from "@covia/covia-sdk";
 
 // Via Grid (cached — same ID returns the same Venue instance)
-const venue = await Grid.connect("https://venue.covia.ai");
-const venue = await Grid.connect("did:web:venue.covia.ai");
-const venue = await Grid.connect("venue.covia.ai"); // DNS name → https://
+const venue = await Grid.connect("https://your-venue.example.com");
+const venue = await Grid.connect("did:web:your-venue.example.com");
+const venue = await Grid.connect("your-venue.example.com"); // DNS name → https://
 
 // Via Venue directly (no caching)
-const venue = await Venue.connect("https://venue.covia.ai");
+const venue = await Venue.connect("https://your-venue.example.com");
 ```
 
 ### Authentication
 
 ```typescript
 // No auth (default)
-const venue = await Grid.connect("https://venue.covia.ai");
+const venue = await Grid.connect("https://your-venue.example.com");
 
 // Ed25519 keypair (self-issued JWT per request)
-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);
+const venue = await Grid.connect("https://your-venue.example.com", auth);
 
 // From a saved private key
-const auth = KeyPairAuth.fromHex("abcdef1234...");
+const auth = Ed25519Auth.fromHex("abcdef1234...");
 
 // Bearer token
 const auth = new BearerAuth("my-api-token");
-const venue = await Grid.connect("https://venue.covia.ai", auth);
+const venue = await Grid.connect("https://your-venue.example.com", auth);
 ```
 
 ## API Reference
@@ -118,26 +118,28 @@ 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.setPrivate(enabled)` | Deprecated connection-wide private-jobs mode (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.
+Pass `{ private: true }` to `operations.run()` to execute as a memory-only job:
+it is never persisted to the venue's job index and is 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. Private execution works
+with `run()`; poll-style `operations.invoke()` rejects it.
 
 ```typescript
-venue.setPrivate(true);
 const result = await venue.operations.run("v/ops/schema/infer", {
   value: { name: "Ada", age: 36 },
-});
+}, { private: true });
 ```
 
+`venue.setPrivate(true)` remains available for compatibility, but is
+deprecated because it mutates execution behaviour for every user of the same
+cached connection.
+
 ---
 
 ### Operations — `venue.operations`
@@ -375,7 +377,6 @@ const mina = venue.agent("Mina");
 const response = await mina.request({ text: "hello" });
 await mina.message({ event: "update" });
 await mina.trigger();
-const state = await mina.query();
 const info = await mina.info();
 
 // Session-scoped chat — ChatSession manages the sessionId for you
@@ -408,8 +409,9 @@ const clone = await mina.fork("Mina-v2", { includeTimeline: true });
 | `agent.chat(message, sessionId?)` | `AgentChatResult` | Single chat call (manual sessionId) |
 | `agent.chatSession(sessionId?)` | `ChatSession` | Create a session that manages sessionId |
 | `agent.trigger()` | `AgentTriggerResult` | Trigger agent execution |
-| `agent.query()` | `AgentQueryResult` | Query agent state |
 | `agent.info()` | `AgentInfoResult` | Get agent info |
+| `agent.listSessions(options?)` | `AgentSessionPage` | Page sessions (job-free) |
+| `agent.getSession(sessionId)` | `AgentSession` | Get one session (job-free) |
 | `agent.context(task?)` | `string` | Get agent context |
 | `agent.suspend()` | `AgentSuspendResult` | Suspend the agent |
 | `agent.resume(autoWake?)` | `AgentSuspendResult` | Resume the agent |
@@ -448,8 +450,9 @@ await venue.agents.chat("my-agent", "hi");
 | `agents.message(id, message)` | `AgentMessageResult` | Send a message |
 | `agents.chat(id, message, sessionId?)` | `AgentChatResult` | Session-scoped chat |
 | `agents.trigger(id)` | `AgentTriggerResult` | Trigger agent execution |
-| `agents.query(id)` | `AgentQueryResult` | Query agent state |
 | `agents.info(id)` | `AgentInfoResult` | Get agent info |
+| `agents.listSessions(id, options?)` | `AgentSessionPage` | Page sessions (job-free) |
+| `agents.getSession(id, sessionId)` | `AgentSession` | Get one session (job-free) |
 | `agents.suspend(id)` | `AgentSuspendResult` | Suspend an agent |
 | `agents.resume(id, autoWake?)` | `AgentSuspendResult` | Resume an agent |
 | `agents.update(input)` | `any` | Update agent config/state |
@@ -468,8 +471,10 @@ Read and write shared state in the venue's workspace.
 `GET /api/v1/values/*` (covia #177) — synchronous, capability-checked, and **no job is
 persisted**. This matters under load: routing reads through the invoke/job path writes a
 durable job record per read, growing the venue's etch without bound. **Writes stay on the
-job path** (they should leave an audit record). A read that needs UCAN **proof tokens**
-(cross-DID) transparently falls back to the invoke path.
+job path** (they should leave an audit record). Reads that need UCAN proof tokens,
+multi-path inspection, or a venue without the Values surface reject with
+`UnsupportedVenueFeatureError` rather than silently creating a persisted job. Invoke
+the corresponding operation explicitly when a persisted job is intended.
 
 ```typescript
 // CRUD (reads are job-free; writes are jobs)
@@ -478,8 +483,8 @@ const data = await venue.workspace.read("w/my-app/config");
 await venue.workspace.append("w/my-app/log", "new entry");
 await venue.workspace.delete("w/my-app/config");
 
-// List and slice
-const entries = await venue.workspace.list("w/my-app/log", 100, 0);
+// List (map keys) and slice (sequence elements)
+const entries = await venue.workspace.list("w/my-app/config", 100, 0);
 const slice = await venue.workspace.slice("w/my-app/log", 0, 10);
 
 // Server-side tallies — count / group-by without reading every record
@@ -501,6 +506,40 @@ const byKind = await venue.workspace.aggregate("w/my-app/events", { depth: 2, gr
 | `workspace.aggregate(path, {depth?, groupBy?})` | `WorkspaceAggregateResult` | Count, optionally grouped by a field (job-free) |
 | `workspace.copy(from, to)` | `WorkspaceCopyResult` | Copy a value between paths (job) |
 
+### Skills — `venue.skills`
+
+Skills are ordinary assets with optional agent-behaviour metadata. The SDK only
+provides exact location/path access; applications decide how to combine, search
+or prioritise collections.
+
+```typescript
+const skills = await venue.skills.list("w/skills");
+const reviewer = await venue.skills.get("w/skills/reviewer");
+
+reviewer.metadata.name;
+reviewer.metadata.skill?.tools;
+const content = await reviewer.getContent();
+```
+
+`list(path)` follows internal collection pagination and returns the asset objects
+at that location. `get(path)` is the corresponding typed asset lookup.
+
+---
+
+### Memory — `venue.memory`
+
+Read the conventional `w/memory` vector as structured entries. Reads are
+job-free; edits use the venue memory operation and therefore leave an audit Job.
+
+```typescript
+const entries = await venue.memory.list();
+await venue.memory.remember("Prefers concise answers");
+await venue.memory.update(1, "Prefers concise technical answers");
+await venue.memory.forget(1);
+```
+
+An alternative path can be passed to each method.
+
 ---
 
 ### Secrets — `venue.secrets`
@@ -667,12 +706,38 @@ RunStatus.AUTH_REQUIRED;   // Waiting for authentication
 import {
   Venue, Grid, Job, Agent, ChatSession, Asset, Operation, DataAsset,
   AdapterManager, AssetManager, OperationManager, JobManager,
-  AgentManager, WorkspaceManager, SecretManager, UCANManager,
-  KeyPairAuth, BearerAuth,
+  AgentManager, WorkspaceManager, SecretManager, UCANManager, SkillManager,
+  MemoryManager,
+  Ed25519Auth, BearerAuth,
   RunStatus, CoviaError,
 } from "@covia/covia-sdk";
 ```
 
+## Upgrading from 1.8
+
+1.9.0 keeps every exported signature compatible, but three behaviours changed
+deliberately:
+
+- **Reads never create jobs — and no longer fall back to the job path.**
+  In 1.8.x, workspace reads with UCAN proofs, multi-path `inspect`, and
+  `agents.list()`/`info()` on older venues silently fell back to invoking an
+  operation, persisting a Job per read. These calls now throw
+  `UnsupportedVenueFeatureError` instead. If creating a persisted job is
+  genuinely intended, invoke the corresponding operation explicitly
+  (e.g. `operations.run("v/ops/covia/read", ...)`).
+- **`Ed25519Auth` requires a venue audience.** Tokens are always bound to the
+  venue's DID (`aud` claim) so they cannot be replayed at another venue.
+  Connect via `Grid.connect()` / `Venue.connect()` and this happens
+  automatically; hand-constructed `new Venue({...})` usage must either call
+  `venue.status()`-style validation first or pin `auth.audience` explicitly.
+  Connect-time probing itself is anonymous — credentials are only ever sent to
+  a venue whose identity has been pinned.
+- **`assets.clearCache()` clears only the in-memory cache.** Purging a
+  configured persistent metadata store (e.g. localStorage) is the new
+  `assets.clearPersistentCache()`. Cached entries are content-addressed and
+  immutable, so keeping them across sessions is safe; call
+  `clearPersistentCache()` at sign-out if your app must empty the store.
+
 ## Resources
 
 - [Covia.ai Platform](https://covia.ai)