@covia/covia-sdk 1.16.0 → 1.18.0

package/dist/index.mjs

@@ -1741,16 +1741,46 @@ async function sliceAll(workspace, path, pageSize = SLICE_PAGE_SIZE) {
   }
   return items;
 }
+function descWindow(total, offset, limit) {
+  const end = Math.max(0, total - offset);
+  return [Math.max(0, end - limit), end];
+}
 
 // src/AgentManager.ts
+var SESSION_ROLES = ["system", "user", "assistant", "tool"];
+var MAX_COMPACTION_DEPTH = 32;
+function collectTurns(entries, out, depth = 0) {
+  if (depth > MAX_COMPACTION_DEPTH) return;
+  for (const entry of entries) {
+    const e = record(entry);
+    if (!e) continue;
+    if (Array.isArray(e.items) && typeof e.summary === "string") {
+      collectTurns(e.items, out, depth + 1);
+      continue;
+    }
+    if (typeof e.role === "string" && SESSION_ROLES.includes(e.role)) {
+      out.push({ ...e, role: e.role });
+    }
+  }
+}
+function sessionConversation(frames) {
+  const turns = [];
+  for (const frame of frames) {
+    const entries = record(frame)?.conversation;
+    if (Array.isArray(entries)) collectTurns(entries, turns);
+  }
+  return turns;
+}
 function sessionRecord(sessionId, value) {
   const session = record(value) ?? {};
   const meta = record(session.meta);
+  const frames = Array.isArray(session.frames) ? session.frames : [];
   return {
     id: sessionId,
     metadata: meta ?? {},
     pending: Array.isArray(session.pending) ? session.pending : [],
-    frames: Array.isArray(session.frames) ? session.frames : [],
+    frames,
+    conversation: sessionConversation(frames),
     wakeTime: typeof session.wakeTime === "number" ? session.wakeTime : void 0
   };
 }
@@ -1903,11 +1933,31 @@ var AgentManager = class {
    * available on each record's `value` while common runtime fields are typed.
    */
   async listSessions(agentId, options = {}) {
-    const result = await this.venue.workspace.slice(
-      `g/${agentId}/sessions`,
-      options.offset,
-      options.limit
-    );
+    const path = `g/${agentId}/sessions`;
+    if ((options.order ?? "asc") === "asc") {
+      return this._sessionPage(path, await this.venue.workspace.slice(
+        path,
+        options.offset,
+        options.limit
+      ), options.offset ?? 0, options.limit);
+    }
+    const offset = Math.max(0, options.offset ?? 0);
+    const limit = options.limit;
+    const guess = (await this.venue.workspace.count(path)).count ?? 0;
+    if (limit === 0) return { items: [], total: guess, offset, limit: 0 };
+    const read = async (total2) => {
+      const [start, end] = descWindow(total2, offset, limit ?? total2);
+      return end > start ? this.venue.workspace.slice(path, start, end - start) : { exists: true, values: [], count: total2, offset: start };
+    };
+    let result = await read(guess);
+    const total = result.count ?? guess;
+    if (total !== guess) result = await read(total);
+    const page = this._sessionPage(path, result, offset, limit);
+    page.items.reverse();
+    return page;
+  }
+  /** Shape a `{key, value}` session slice into a page. */
+  _sessionPage(_path, result, offset, limit) {
     const sessions = (result.values ?? []).flatMap((entry) => {
       const pair = record(entry);
       if (!pair || typeof pair.key !== "string") return [];
@@ -1916,8 +1966,8 @@ var AgentManager = class {
     return {
       items: sessions,
       total: result.count ?? sessions.length,
-      offset: result.offset ?? options.offset ?? 0,
-      limit: options.limit ?? sessions.length
+      offset,
+      limit: limit ?? sessions.length
     };
   }
   /** Read one agent session directly from the workspace Values surface. */
@@ -2109,6 +2159,24 @@ var Job = class {
 };
 
 // src/JobManager.ts
+var JOB_INDEX = "j";
+var DEFAULT_HISTORY_LIMIT = 50;
+var MAX_SLICE_LIMIT = 100;
+function isSliceCapError(error) {
+  return error instanceof Error && error.message.includes("exceeds maxSize");
+}
+function jobRecords(values) {
+  const records = [];
+  for (const entry of values) {
+    const pair = record(entry);
+    const value = record(pair?.value);
+    if (!value) continue;
+    const meta = value;
+    const key = typeof pair?.key === "string" ? pair.key : "";
+    records.push({ ...meta, id: meta.id ?? `0x${key}` });
+  }
+  return records;
+}
 function jobPage(value) {
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
     throw new CoviaError("Venue returned an invalid jobs listing");
@@ -2150,6 +2218,70 @@ var JobManager = class {
     }
     return items;
   }
+  /**
+   * A page of job history: `JobMetadata` rows, newest-first by default, with an
+   * authoritative total.
+   *
+   * `list()` answers "which jobs exist" as ids; a history view needs a bounded
+   * window of *records* and a count to page against. This reads the job index
+   * directly, so each row arrives with its metadata already attached — the
+   * alternative, listing ids and then fetching each one, is an N+1 fan-out per
+   * page. Reads stay job-free (covia#177): paging job history must not itself
+   * write a job record per page.
+   *
+   * The total is read before a `desc` window can be placed, so the index may
+   * grow in between; the page self-corrects once against the count the slice
+   * itself reports, which is authoritative for the rows returned with it.
+   */
+  async history(options = {}) {
+    const offset = Math.max(0, Math.trunc(options.offset ?? 0));
+    const limit = Math.max(0, Math.trunc(options.limit ?? DEFAULT_HISTORY_LIMIT));
+    const descending = (options.order ?? "desc") === "desc";
+    if (limit === 0) {
+      const { count } = await this.venue.workspace.count(JOB_INDEX);
+      return { items: [], total: count ?? 0, offset, limit };
+    }
+    if (!descending) {
+      const asc = await this._readJobRange(offset, offset + limit);
+      return { items: jobRecords(asc.values), total: asc.count ?? offset + asc.values.length, offset, limit };
+    }
+    const guess = (await this.venue.workspace.count(JOB_INDEX)).count ?? 0;
+    let read = await this._readJobRange(...descWindow(guess, offset, limit));
+    const total = read.count ?? guess;
+    if (total !== guess) {
+      read = await this._readJobRange(...descWindow(total, offset, limit));
+    }
+    return { items: jobRecords(read.values).reverse(), total: read.count ?? total, offset, limit };
+  }
+  /**
+   * Read index ranks `[start, end)` in cap-aware chunks, halving on an oversize
+   * response and skipping a record that is individually oversize.
+   */
+  async _readJobRange(start, end) {
+    const values = [];
+    let count;
+    let pos = start;
+    let chunk = MAX_SLICE_LIMIT;
+    while (pos < end) {
+      const want = Math.min(chunk, end - pos);
+      try {
+        const page = await this.venue.workspace.slice(JOB_INDEX, pos, want);
+        count = page.count ?? count;
+        const got = page.values ?? [];
+        values.push(...got);
+        if (got.length < want) break;
+        pos += got.length;
+      } catch (error) {
+        if (!isSliceCapError(error)) throw error;
+        if (want > 1) {
+          chunk = Math.max(1, Math.floor(want / 2));
+          continue;
+        }
+        pos += 1;
+      }
+    }
+    return { count, values };
+  }
   async get(jobId) {
     try {
       const data = await venueJson(this.venue, `/api/v1/jobs/${jobId}`);
@@ -2581,12 +2713,52 @@ var OperationManager = class {
 };
 
 // src/WorkspaceManager.ts
+var SCOPED_NAMESPACES = ["t", "n", "c"];
+var SCOPE_UNEXPANDED = /Cannot use '[tnc]\/' prefix outside/;
+function scopedNamespaceOf(path) {
+  const head = path.split("/", 1)[0];
+  return SCOPED_NAMESPACES.includes(head) ? head : void 0;
+}
+function scopeParamsFor(ns, scope) {
+  const { agent, task, session } = scope;
+  switch (ns) {
+    case "n":
+      return { agent };
+    case "c":
+      if (!session) throw new CoviaError("A 'c/' scratch read needs a session in its scope");
+      return { agent, session };
+    case "t":
+      if (!task) throw new CoviaError("A 't/' scratch read needs a task in its scope");
+      return { agent, task };
+  }
+}
+function expandScopedPath(path, ns, scope) {
+  if (scope.agent.startsWith("did:")) {
+    throw new CoviaError(
+      "This venue cannot expand scoped scratch paths and the SDK cannot do it for a DID-qualified agent \u2014 pass a bare agent id, or upgrade the venue (covia#230)"
+    );
+  }
+  const suffix = path.slice(ns.length);
+  switch (ns) {
+    case "n":
+      return `g/${scope.agent}/n${suffix}`;
+    case "c":
+      return `g/${scope.agent}/sessions/${scope.session}/c${suffix}`;
+    case "t":
+      return `j/${scope.task}/temp${suffix}`;
+  }
+}
 var WorkspaceManager = class {
   constructor(venue) {
     this.venue = venue;
     // Whether this venue serves GET /api/v1/values/* — flipped on the first 404
     // so pre-0.3 venues pay the probe once, not one failed GET per read.
     this.valuesSupported = true;
+    // Whether this venue expands t/, n/ and c/ from explicit agent/task/session
+    // selectors (covia#230) — flipped off the first time a venue answers a
+    // selector-bearing read by complaining the shorthand has no execution scope,
+    // after which scoped reads expand client-side instead.
+    this.scopeExpansionSupported = true;
   }
   /** GET a job-free `/api/v1/values/{op}` read; omit undefined params. */
   _values(op, params) {
@@ -2620,6 +2792,52 @@ var WorkspaceManager = class {
     }
     return this.unsupported(`workspace ${op} reads`);
   }
+  /**
+   * A job-free Values read of an execution-scoped path, preferring the venue's
+   * own selector expansion and falling back to the client-side one.
+   *
+   * The venue is preferred because it expands *before* the capability check, so
+   * authorisation applies to the same canonical resource that is ultimately
+   * read — a caller cannot substitute a sibling or foreign agent's scratch.
+   * The fallback reaches the same resource but re-derives the layout here.
+   */
+  async scopedRead(op, params, scope) {
+    const path = String(params.path ?? "");
+    const ns = scopedNamespaceOf(path);
+    if (!ns) return this.valuesRead(op, params);
+    if (this.scopeExpansionSupported) {
+      try {
+        return await this.valuesRead(op, { ...params, ...scopeParamsFor(ns, scope) });
+      } catch (e) {
+        if (!(e instanceof Error) || !SCOPE_UNEXPANDED.test(e.message)) throw e;
+        this.scopeExpansionSupported = false;
+      }
+    }
+    scopeParamsFor(ns, scope);
+    return this.valuesRead(op, { ...params, path: expandScopedPath(path, ns, scope) });
+  }
+  /**
+   * Bind an execution scope, giving job-free reads of the `t/`, `n/` and `c/`
+   * scratch shorthands that a bare GET cannot otherwise resolve (covia#177
+   * forbids minting a Job for a read; the shorthands need context a GET lacks).
+   *
+   * ```ts
+   * const scratch = venue.workspace.scoped({ agent: 'alice', task: taskId });
+   * await scratch.read('t/snapshot');
+   * await scratch.list('t/');
+   * ```
+   *
+   * Ordinary paths still work through the handle, so a caller rendering a task
+   * inspector can use one reader for both scratch and workspace. Capability
+   * behaviour is unchanged: the caller needs read caps on the agent's subtree.
+   */
+  scoped(scope) {
+    return new ScopedWorkspace(this, scope);
+  }
+  /** @internal — the scoped read used by {@link ScopedWorkspace}. */
+  _scopedRead(op, params, scope) {
+    return this.scopedRead(op, params, scope);
+  }
   // ── job-free reads (#177) ───────────────────────────────────────────────────
   async read(path, maxSize, ucans) {
     if (ucans?.length) return this.unsupported("UCAN-authorised workspace reads");
@@ -2680,6 +2898,30 @@ var WorkspaceManager = class {
     return this.venue.operations.run("v/ops/covia/copy", { from, to }, { ucans });
   }
 };
+var ScopedWorkspace = class {
+  constructor(workspace, scope) {
+    this.workspace = workspace;
+    this.scope = scope;
+  }
+  read(path, maxSize) {
+    return this.workspace._scopedRead("read", { path, maxSize }, this.scope);
+  }
+  list(path, limit, offset) {
+    return this.workspace._scopedRead("list", { path, limit, offset }, this.scope);
+  }
+  slice(path, offset, limit) {
+    return this.workspace._scopedRead("slice", { path, offset, limit }, this.scope);
+  }
+  inspect(path, budget, compact) {
+    return this.workspace._scopedRead("inspect", { path, budget, compact }, this.scope);
+  }
+  count(path, opts = {}) {
+    return this.workspace._scopedRead("count", { path, depth: opts.depth }, this.scope);
+  }
+  aggregate(path, opts = {}) {
+    return this.workspace._scopedRead("aggregate", { path, depth: opts.depth, groupBy: opts.groupBy }, this.scope);
+  }
+};
 
 // src/UCANManager.ts
 var UCANManager = class {
@@ -3051,6 +3293,15 @@ var Agent = class _Agent {
   async getSession(sessionId) {
     return this._agents.getSession(this.id, sessionId);
   }
+  /**
+   * One session's transcript — its turns in order, with compacted segments
+   * expanded back into the turns they archived.
+   *
+   * Shorthand for `getSession(sessionId)` when only the conversation is wanted.
+   */
+  async transcript(sessionId) {
+    return (await this._agents.getSession(this.id, sessionId)).conversation;
+  }
   /** Stream this agent's run-loop events. See `AgentManager.events`. */
   async *events(options) {
     yield* this._agents.events(this.id, options);
@@ -3549,4 +3800,4 @@ function relayDelegation(privateKey, venueDID, lifetimeSeconds, caps = []) {
   (*! noble-ed25519 - MIT License (c) 2019 Paul Miller (paulmillr.com) *)
 */
 
-export { A2AManager, AdapterManager, Agent, AgentManager, AgentSessionNotFoundError, AgentStatus, Asset, AssetManager, AssetNotFoundError, Auth, BasicAuth, BearerAuth, ChatSession, CoviaConnectionError, CoviaError, CoviaTimeoutError, CredentialsHTTP, DLFSManager, DataAsset, Ed25519Auth, Grid, GridError, Job, JobFailedError, JobManager, JobNotFoundError, JobStatus, KeyPairAuth, MemoryManager, Namespace, NoAuth, NotFoundError, Operation, OperationManager, RateLimitError, RunStatus, SecretManager, SkillManager, UCANManager, UnsupportedVenueFeatureError, UserManager, VENUE_RELAY, Venue, VenueIdentityChangedError, WorkspaceManager, 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 { A2AManager, AdapterManager, Agent, AgentManager, AgentSessionNotFoundError, AgentStatus, Asset, AssetManager, AssetNotFoundError, Auth, BasicAuth, BearerAuth, ChatSession, CoviaConnectionError, CoviaError, CoviaTimeoutError, CredentialsHTTP, DLFSManager, DataAsset, Ed25519Auth, Grid, GridError, Job, JobFailedError, JobManager, JobNotFoundError, JobStatus, KeyPairAuth, MemoryManager, Namespace, NoAuth, NotFoundError, Operation, OperationManager, RateLimitError, RunStatus, ScopedWorkspace, SecretManager, SkillManager, UCANManager, UnsupportedVenueFeatureError, UserManager, VENUE_RELAY, Venue, VenueIdentityChangedError, WorkspaceManager, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@covia/covia-sdk",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Typescript library for covia-ai",
   "packageManager": "pnpm@11.9.0",
   "main": "./dist/index.js",