@covia/covia-sdk 1.17.0 → 1.18.0

package/dist/index.d.mts

@@ -24,6 +24,13 @@ declare class Agent {
     listSessions(options?: AgentSessionListOptions): Promise<AgentSessionPage>;
     /** Read one session through the job-free workspace Values API. */
     getSession(sessionId: string): Promise<AgentSession>;
+    /**
+     * One session's transcript — its turns in order, with compacted segments
+     * expanded back into the turns they archived.
+     *
+     * Shorthand for `getSession(sessionId)` when only the conversation is wanted.
+     */
+    transcript(sessionId: string): Promise<AgentSessionMessage[]>;
     /** Stream this agent's run-loop events. See `AgentManager.events`. */
     events(options?: {
         sessionId?: string;
@@ -369,6 +376,9 @@ interface AgentManagerVenue extends VenueRequestContext {
     workspace: {
         read(path: string, maxSize?: number): Promise<WorkspaceReadResult>;
         slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+        count(path: string, opts?: {
+            depth?: number;
+        }): Promise<WorkspaceCountResult>;
     };
 }
 declare class AgentManager {
@@ -446,6 +456,8 @@ declare class AgentManager {
      * available on each record's `value` while common runtime fields are typed.
      */
     listSessions(agentId: string, options?: AgentSessionListOptions): Promise<AgentSessionPage>;
+    /** Shape a `{key, value}` session slice into a page. */
+    private _sessionPage;
     /** Read one agent session directly from the workspace Values surface. */
     getSession(agentId: string, sessionId: string): Promise<AgentSession>;
     private _readLargeSession;
@@ -455,11 +467,39 @@ declare class AgentManager {
     failTask(error: string): Promise<AgentFailTaskResult>;
 }
 
-type JobManagerVenue = VenueRequestContext;
+interface JobManagerVenue extends VenueRequestContext {
+    workspace: {
+        count(path: string, opts?: {
+            depth?: number;
+        }): Promise<WorkspaceCountResult>;
+        slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+    };
+}
 declare class JobManager {
     private venue;
     constructor(venue: JobManagerVenue);
     list(): Promise<string[]>;
+    /**
+     * A page of job history: `JobMetadata` rows, newest-first by default, with an
+     * authoritative total.
+     *
+     * `list()` answers "which jobs exist" as ids; a history view needs a bounded
+     * window of *records* and a count to page against. This reads the job index
+     * directly, so each row arrives with its metadata already attached — the
+     * alternative, listing ids and then fetching each one, is an N+1 fan-out per
+     * page. Reads stay job-free (covia#177): paging job history must not itself
+     * write a job record per page.
+     *
+     * The total is read before a `desc` window can be placed, so the index may
+     * grow in between; the page self-corrects once against the count the slice
+     * itself reports, which is authoritative for the rows returned with it.
+     */
+    history(options?: JobHistoryOptions): Promise<JobHistoryPage>;
+    /**
+     * Read index ranks `[start, end)` in cap-aware chunks, halving on an oversize
+     * response and skipping a record that is individually oversize.
+     */
+    private _readJobRange;
     get(jobId: string): Promise<Job>;
     cancel(jobId: string): Promise<JobMetadata>;
     delete(jobId: string): Promise<void>;
@@ -610,6 +650,7 @@ interface WorkspaceManagerVenue extends VenueRequestContext {
 declare class WorkspaceManager {
     private venue;
     private valuesSupported;
+    private scopeExpansionSupported;
     constructor(venue: WorkspaceManagerVenue);
     /** GET a job-free `/api/v1/values/{op}` read; omit undefined params. */
     private _values;
@@ -624,6 +665,34 @@ declare class WorkspaceManager {
     private unsupported;
     /** A job-free Values read that rejects when the endpoint is unavailable. */
     private valuesRead;
+    /**
+     * A job-free Values read of an execution-scoped path, preferring the venue's
+     * own selector expansion and falling back to the client-side one.
+     *
+     * The venue is preferred because it expands *before* the capability check, so
+     * authorisation applies to the same canonical resource that is ultimately
+     * read — a caller cannot substitute a sibling or foreign agent's scratch.
+     * The fallback reaches the same resource but re-derives the layout here.
+     */
+    private scopedRead;
+    /**
+     * Bind an execution scope, giving job-free reads of the `t/`, `n/` and `c/`
+     * scratch shorthands that a bare GET cannot otherwise resolve (covia#177
+     * forbids minting a Job for a read; the shorthands need context a GET lacks).
+     *
+     * ```ts
+     * const scratch = venue.workspace.scoped({ agent: 'alice', task: taskId });
+     * await scratch.read('t/snapshot');
+     * await scratch.list('t/');
+     * ```
+     *
+     * Ordinary paths still work through the handle, so a caller rendering a task
+     * inspector can use one reader for both scratch and workspace. Capability
+     * behaviour is unchanged: the caller needs read caps on the agent's subtree.
+     */
+    scoped(scope: ExecutionScope): ScopedWorkspace;
+    /** @internal — the scoped read used by {@link ScopedWorkspace}. */
+    _scopedRead<T>(op: string, params: Record<string, string | number | boolean | undefined>, scope: ExecutionScope): Promise<T>;
     read(path: string, maxSize?: number, ucans?: string[]): Promise<WorkspaceReadResult>;
     list(path?: string, limit?: number, offset?: number, ucans?: string[]): Promise<WorkspaceListResult>;
     slice(path: string, offset?: number, limit?: number, ucans?: string[]): Promise<WorkspaceSliceResult>;
@@ -658,6 +727,35 @@ declare class WorkspaceManager {
     append(path: string, value: unknown, ucans?: string[]): Promise<WorkspaceAppendResult>;
     copy(from: string, to: string, ucans?: string[]): Promise<WorkspaceCopyResult>;
 }
+/**
+ * A {@link WorkspaceManager} bound to one execution scope, so `t/`, `n/` and
+ * `c/` scratch resolve without the caller hand-building the physical paths
+ * (`g/<agent>/sessions/<sid>/c/...` and friends). Reads only — scoped scratch
+ * is written from inside the execution that owns it, where the shorthands
+ * already resolve from the request's own context.
+ *
+ * Obtained from {@link WorkspaceManager.scoped}; every method mirrors the
+ * job-free read of the same name.
+ */
+declare class ScopedWorkspace {
+    private workspace;
+    /** The scope every read on this handle resolves against. */
+    readonly scope: ExecutionScope;
+    constructor(workspace: WorkspaceManager, 
+    /** The scope every read on this handle resolves against. */
+    scope: ExecutionScope);
+    read(path: string, maxSize?: number): Promise<WorkspaceReadResult>;
+    list(path: string, limit?: number, offset?: number): Promise<WorkspaceListResult>;
+    slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+    inspect(path: string, budget?: number, compact?: boolean): Promise<WorkspaceInspectResult>;
+    count(path: string, opts?: {
+        depth?: number;
+    }): Promise<WorkspaceCountResult>;
+    aggregate(path: string, opts?: {
+        depth?: number;
+        groupBy?: string;
+    }): Promise<WorkspaceAggregateResult>;
+}
 
 interface UCANManagerVenue {
     operations: OperationRunner;
@@ -1149,6 +1247,23 @@ interface OperationPayload {
 interface ContentHashResult {
     hash: string;
 }
+/** Paging/ordering for {@link JobManager.history}. */
+interface JobHistoryOptions {
+    /** Rows to skip from the ordered start (default 0). */
+    offset?: number;
+    /** Maximum rows to return (default 50). */
+    limit?: number;
+    /** `desc` (default) is newest-first, the order a history view wants. */
+    order?: 'asc' | 'desc';
+}
+/** One page of job history: the rows plus the window they were drawn from. */
+interface JobHistoryPage {
+    items: JobMetadata[];
+    /** Authoritative total at the moment the page was read. */
+    total: number;
+    offset: number;
+    limit: number;
+}
 interface JobMetadata {
     id?: string;
     name?: string;
@@ -1438,17 +1553,78 @@ interface AgentSessionMetadata {
     turnCount?: number;
     [key: string]: unknown;
 }
+/** The four roles a stored conversation turn may carry. */
+type AgentSessionRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * One persisted conversation turn (AGENT_CONTEXT.md §1.1 `Turn`).
+ *
+ * Most turns carry text in `content`; a tool result may instead carry its typed
+ * map or vector in `structuredContent`. Provider-specific continuation state
+ * (`providerState`) is deliberately absent — it is opaque, is omitted from
+ * retrospective session projections, and is not part of a readable transcript.
+ */
+interface AgentSessionMessage {
+    role: AgentSessionRole;
+    content?: unknown;
+    /** A typed tool result, in place of textual `content`. */
+    structuredContent?: unknown;
+    /** Present on an assistant turn that called tools. */
+    toolCalls?: unknown[];
+    /** A `tool` turn's matching call id. */
+    id?: string;
+    name?: string;
+    isError?: boolean;
+    ts?: number;
+    source?: string;
+    caller?: string;
+    /** The job that delivered this turn — links it back to the calling job. */
+    jobId?: string;
+    tokens?: number;
+}
+/**
+ * An archived run of turns that compaction replaced with a summary
+ * (AGENT_CONTEXT.md §1.1 `CompactedSegment`). `items` is the exact recursively
+ * archived vector, so no history is lost — {@link AgentSession.conversation}
+ * expands it back into the transcript.
+ */
+interface AgentCompactedSegment {
+    summary: string;
+    /** How many turns the summary stands in for. */
+    turns?: number;
+    items: unknown[];
+}
 /** A session record read directly from `g/<agentId>/sessions`. */
 interface AgentSession {
     id: string;
     metadata: AgentSessionMetadata;
     pending: unknown[];
+    /**
+     * Raw goal-tree frames, newest last. `frames[0]` is the root frame and a flat
+     * `llmagent` session has only that one. Kept verbatim for callers that need
+     * frame-level state; for the readable transcript use {@link conversation}.
+     */
     frames: unknown[];
+    /**
+     * The session transcript: every frame's turns, in order, with compacted
+     * segments expanded back into the turns they archived.
+     *
+     * This is the field a chat UI renders. Assembling it from `frames` means
+     * knowing that turns live at `frames[].conversation`, that an entry there may
+     * be an archived segment rather than a turn, and that segments nest — layout
+     * knowledge that belongs here rather than in every consumer.
+     */
+    conversation: AgentSessionMessage[];
     wakeTime?: number;
 }
 interface AgentSessionListOptions {
     offset?: number;
     limit?: number;
+    /**
+     * `desc` is newest-first. Session ids are timestamp-prefixed, so the index is
+     * already chronological and the window is taken from its end — the order
+     * holds across pages, unlike sorting one page after the fact.
+     */
+    order?: 'asc' | 'desc';
 }
 interface AgentSessionPage {
     items: AgentSession[];
@@ -1640,6 +1816,33 @@ interface WorkspaceAppendResult {
     /** 0.3.0: true iff a new parent path was built. */
     pathCreated?: boolean;
 }
+/**
+ * The execution context a `t/`, `n/` or `c/` scratch read resolves against.
+ *
+ * A GET carries no execution context of its own, so the venue cannot know which
+ * job, agent or session a bare shorthand means. These selectors supply it
+ * explicitly (covia#230) and are the only way to read scoped scratch job-free.
+ *
+ * Each namespace consumes a different part of the scope, and the venue rejects
+ * a selector its namespace does not use:
+ *
+ * | Path | Needs            | Resolves to                                  |
+ * |------|------------------|----------------------------------------------|
+ * | `n/` | `agent`          | `g/<agent>/n/...`                            |
+ * | `c/` | `agent`+`session`| `g/<agent>/sessions/<session>/c/...`         |
+ * | `t/` | `agent`+`task`   | `j/<task>/temp/...`                          |
+ *
+ * A bound scope may therefore carry all three; each read sends only what its
+ * own namespace needs.
+ */
+interface ExecutionScope {
+    /** Agent id (`alice`) or a full agent DID. Required for every scoped read. */
+    agent: string;
+    /** Task id — the `agent:request` Job whose record holds `t/` scratch. */
+    task?: string;
+    /** Session id, for `c/` session scratch. */
+    session?: string;
+}
 interface WorkspaceListInput {
     path?: string;
     limit?: number;
@@ -2282,4 +2485,4 @@ declare function grant(ownerPrivateKey: Uint8Array, audienceDID: string, withRes
  */
 declare function relayDelegation(privateKey: Uint8Array, venueDID: string, lifetimeSeconds: number, caps?: UCANCapability[]): string;
 
-export { type A2AAuthRef, type A2AImportAgentInput, type A2AImportAgentResult, A2AManager, type A2AMessage, type A2APart, type A2ATask, type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentCycleEndEvent, type AgentCycleStartEvent, type AgentDeleteInput, type AgentDeleteResult, type AgentEvent, type AgentEventEnvelope, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInferenceEndEvent, type AgentInferenceStartEvent, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentRunEndEvent, type AgentRunStartEvent, type AgentSession, type AgentSessionListOptions, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, AgentStatus, type AgentStatusEvent, type AgentSuspendResult, type AgentToolResultEvent, type AgentToolStartEvent, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, type AuthenticationKeyEntry, type AuthenticationKeysMap, type AuthenticationKeysResult, type AuthenticatorRevokeResult, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, type UserInfo, type UserListResult, UserManager, type UserSummary, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { type A2AAuthRef, type A2AImportAgentInput, type A2AImportAgentResult, A2AManager, type A2AMessage, type A2APart, type A2ATask, type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompactedSegment, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentCycleEndEvent, type AgentCycleStartEvent, type AgentDeleteInput, type AgentDeleteResult, type AgentEvent, type AgentEventEnvelope, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInferenceEndEvent, type AgentInferenceStartEvent, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentRunEndEvent, type AgentRunStartEvent, type AgentSession, type AgentSessionListOptions, type AgentSessionMessage, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, type AgentSessionRole, AgentStatus, type AgentStatusEvent, type AgentSuspendResult, type AgentToolResultEvent, type AgentToolStartEvent, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, type AuthenticationKeyEntry, type AuthenticationKeysMap, type AuthenticationKeysResult, type AuthenticatorRevokeResult, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExecutionScope, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, type JobHistoryOptions, type JobHistoryPage, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, ScopedWorkspace, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, type UserInfo, type UserListResult, UserManager, type UserSummary, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };

package/dist/index.d.ts

@@ -24,6 +24,13 @@ declare class Agent {
     listSessions(options?: AgentSessionListOptions): Promise<AgentSessionPage>;
     /** Read one session through the job-free workspace Values API. */
     getSession(sessionId: string): Promise<AgentSession>;
+    /**
+     * One session's transcript — its turns in order, with compacted segments
+     * expanded back into the turns they archived.
+     *
+     * Shorthand for `getSession(sessionId)` when only the conversation is wanted.
+     */
+    transcript(sessionId: string): Promise<AgentSessionMessage[]>;
     /** Stream this agent's run-loop events. See `AgentManager.events`. */
     events(options?: {
         sessionId?: string;
@@ -369,6 +376,9 @@ interface AgentManagerVenue extends VenueRequestContext {
     workspace: {
         read(path: string, maxSize?: number): Promise<WorkspaceReadResult>;
         slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+        count(path: string, opts?: {
+            depth?: number;
+        }): Promise<WorkspaceCountResult>;
     };
 }
 declare class AgentManager {
@@ -446,6 +456,8 @@ declare class AgentManager {
      * available on each record's `value` while common runtime fields are typed.
      */
     listSessions(agentId: string, options?: AgentSessionListOptions): Promise<AgentSessionPage>;
+    /** Shape a `{key, value}` session slice into a page. */
+    private _sessionPage;
     /** Read one agent session directly from the workspace Values surface. */
     getSession(agentId: string, sessionId: string): Promise<AgentSession>;
     private _readLargeSession;
@@ -455,11 +467,39 @@ declare class AgentManager {
     failTask(error: string): Promise<AgentFailTaskResult>;
 }
 
-type JobManagerVenue = VenueRequestContext;
+interface JobManagerVenue extends VenueRequestContext {
+    workspace: {
+        count(path: string, opts?: {
+            depth?: number;
+        }): Promise<WorkspaceCountResult>;
+        slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+    };
+}
 declare class JobManager {
     private venue;
     constructor(venue: JobManagerVenue);
     list(): Promise<string[]>;
+    /**
+     * A page of job history: `JobMetadata` rows, newest-first by default, with an
+     * authoritative total.
+     *
+     * `list()` answers "which jobs exist" as ids; a history view needs a bounded
+     * window of *records* and a count to page against. This reads the job index
+     * directly, so each row arrives with its metadata already attached — the
+     * alternative, listing ids and then fetching each one, is an N+1 fan-out per
+     * page. Reads stay job-free (covia#177): paging job history must not itself
+     * write a job record per page.
+     *
+     * The total is read before a `desc` window can be placed, so the index may
+     * grow in between; the page self-corrects once against the count the slice
+     * itself reports, which is authoritative for the rows returned with it.
+     */
+    history(options?: JobHistoryOptions): Promise<JobHistoryPage>;
+    /**
+     * Read index ranks `[start, end)` in cap-aware chunks, halving on an oversize
+     * response and skipping a record that is individually oversize.
+     */
+    private _readJobRange;
     get(jobId: string): Promise<Job>;
     cancel(jobId: string): Promise<JobMetadata>;
     delete(jobId: string): Promise<void>;
@@ -610,6 +650,7 @@ interface WorkspaceManagerVenue extends VenueRequestContext {
 declare class WorkspaceManager {
     private venue;
     private valuesSupported;
+    private scopeExpansionSupported;
     constructor(venue: WorkspaceManagerVenue);
     /** GET a job-free `/api/v1/values/{op}` read; omit undefined params. */
     private _values;
@@ -624,6 +665,34 @@ declare class WorkspaceManager {
     private unsupported;
     /** A job-free Values read that rejects when the endpoint is unavailable. */
     private valuesRead;
+    /**
+     * A job-free Values read of an execution-scoped path, preferring the venue's
+     * own selector expansion and falling back to the client-side one.
+     *
+     * The venue is preferred because it expands *before* the capability check, so
+     * authorisation applies to the same canonical resource that is ultimately
+     * read — a caller cannot substitute a sibling or foreign agent's scratch.
+     * The fallback reaches the same resource but re-derives the layout here.
+     */
+    private scopedRead;
+    /**
+     * Bind an execution scope, giving job-free reads of the `t/`, `n/` and `c/`
+     * scratch shorthands that a bare GET cannot otherwise resolve (covia#177
+     * forbids minting a Job for a read; the shorthands need context a GET lacks).
+     *
+     * ```ts
+     * const scratch = venue.workspace.scoped({ agent: 'alice', task: taskId });
+     * await scratch.read('t/snapshot');
+     * await scratch.list('t/');
+     * ```
+     *
+     * Ordinary paths still work through the handle, so a caller rendering a task
+     * inspector can use one reader for both scratch and workspace. Capability
+     * behaviour is unchanged: the caller needs read caps on the agent's subtree.
+     */
+    scoped(scope: ExecutionScope): ScopedWorkspace;
+    /** @internal — the scoped read used by {@link ScopedWorkspace}. */
+    _scopedRead<T>(op: string, params: Record<string, string | number | boolean | undefined>, scope: ExecutionScope): Promise<T>;
     read(path: string, maxSize?: number, ucans?: string[]): Promise<WorkspaceReadResult>;
     list(path?: string, limit?: number, offset?: number, ucans?: string[]): Promise<WorkspaceListResult>;
     slice(path: string, offset?: number, limit?: number, ucans?: string[]): Promise<WorkspaceSliceResult>;
@@ -658,6 +727,35 @@ declare class WorkspaceManager {
     append(path: string, value: unknown, ucans?: string[]): Promise<WorkspaceAppendResult>;
     copy(from: string, to: string, ucans?: string[]): Promise<WorkspaceCopyResult>;
 }
+/**
+ * A {@link WorkspaceManager} bound to one execution scope, so `t/`, `n/` and
+ * `c/` scratch resolve without the caller hand-building the physical paths
+ * (`g/<agent>/sessions/<sid>/c/...` and friends). Reads only — scoped scratch
+ * is written from inside the execution that owns it, where the shorthands
+ * already resolve from the request's own context.
+ *
+ * Obtained from {@link WorkspaceManager.scoped}; every method mirrors the
+ * job-free read of the same name.
+ */
+declare class ScopedWorkspace {
+    private workspace;
+    /** The scope every read on this handle resolves against. */
+    readonly scope: ExecutionScope;
+    constructor(workspace: WorkspaceManager, 
+    /** The scope every read on this handle resolves against. */
+    scope: ExecutionScope);
+    read(path: string, maxSize?: number): Promise<WorkspaceReadResult>;
+    list(path: string, limit?: number, offset?: number): Promise<WorkspaceListResult>;
+    slice(path: string, offset?: number, limit?: number): Promise<WorkspaceSliceResult>;
+    inspect(path: string, budget?: number, compact?: boolean): Promise<WorkspaceInspectResult>;
+    count(path: string, opts?: {
+        depth?: number;
+    }): Promise<WorkspaceCountResult>;
+    aggregate(path: string, opts?: {
+        depth?: number;
+        groupBy?: string;
+    }): Promise<WorkspaceAggregateResult>;
+}
 
 interface UCANManagerVenue {
     operations: OperationRunner;
@@ -1149,6 +1247,23 @@ interface OperationPayload {
 interface ContentHashResult {
     hash: string;
 }
+/** Paging/ordering for {@link JobManager.history}. */
+interface JobHistoryOptions {
+    /** Rows to skip from the ordered start (default 0). */
+    offset?: number;
+    /** Maximum rows to return (default 50). */
+    limit?: number;
+    /** `desc` (default) is newest-first, the order a history view wants. */
+    order?: 'asc' | 'desc';
+}
+/** One page of job history: the rows plus the window they were drawn from. */
+interface JobHistoryPage {
+    items: JobMetadata[];
+    /** Authoritative total at the moment the page was read. */
+    total: number;
+    offset: number;
+    limit: number;
+}
 interface JobMetadata {
     id?: string;
     name?: string;
@@ -1438,17 +1553,78 @@ interface AgentSessionMetadata {
     turnCount?: number;
     [key: string]: unknown;
 }
+/** The four roles a stored conversation turn may carry. */
+type AgentSessionRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * One persisted conversation turn (AGENT_CONTEXT.md §1.1 `Turn`).
+ *
+ * Most turns carry text in `content`; a tool result may instead carry its typed
+ * map or vector in `structuredContent`. Provider-specific continuation state
+ * (`providerState`) is deliberately absent — it is opaque, is omitted from
+ * retrospective session projections, and is not part of a readable transcript.
+ */
+interface AgentSessionMessage {
+    role: AgentSessionRole;
+    content?: unknown;
+    /** A typed tool result, in place of textual `content`. */
+    structuredContent?: unknown;
+    /** Present on an assistant turn that called tools. */
+    toolCalls?: unknown[];
+    /** A `tool` turn's matching call id. */
+    id?: string;
+    name?: string;
+    isError?: boolean;
+    ts?: number;
+    source?: string;
+    caller?: string;
+    /** The job that delivered this turn — links it back to the calling job. */
+    jobId?: string;
+    tokens?: number;
+}
+/**
+ * An archived run of turns that compaction replaced with a summary
+ * (AGENT_CONTEXT.md §1.1 `CompactedSegment`). `items` is the exact recursively
+ * archived vector, so no history is lost — {@link AgentSession.conversation}
+ * expands it back into the transcript.
+ */
+interface AgentCompactedSegment {
+    summary: string;
+    /** How many turns the summary stands in for. */
+    turns?: number;
+    items: unknown[];
+}
 /** A session record read directly from `g/<agentId>/sessions`. */
 interface AgentSession {
     id: string;
     metadata: AgentSessionMetadata;
     pending: unknown[];
+    /**
+     * Raw goal-tree frames, newest last. `frames[0]` is the root frame and a flat
+     * `llmagent` session has only that one. Kept verbatim for callers that need
+     * frame-level state; for the readable transcript use {@link conversation}.
+     */
     frames: unknown[];
+    /**
+     * The session transcript: every frame's turns, in order, with compacted
+     * segments expanded back into the turns they archived.
+     *
+     * This is the field a chat UI renders. Assembling it from `frames` means
+     * knowing that turns live at `frames[].conversation`, that an entry there may
+     * be an archived segment rather than a turn, and that segments nest — layout
+     * knowledge that belongs here rather than in every consumer.
+     */
+    conversation: AgentSessionMessage[];
     wakeTime?: number;
 }
 interface AgentSessionListOptions {
     offset?: number;
     limit?: number;
+    /**
+     * `desc` is newest-first. Session ids are timestamp-prefixed, so the index is
+     * already chronological and the window is taken from its end — the order
+     * holds across pages, unlike sorting one page after the fact.
+     */
+    order?: 'asc' | 'desc';
 }
 interface AgentSessionPage {
     items: AgentSession[];
@@ -1640,6 +1816,33 @@ interface WorkspaceAppendResult {
     /** 0.3.0: true iff a new parent path was built. */
     pathCreated?: boolean;
 }
+/**
+ * The execution context a `t/`, `n/` or `c/` scratch read resolves against.
+ *
+ * A GET carries no execution context of its own, so the venue cannot know which
+ * job, agent or session a bare shorthand means. These selectors supply it
+ * explicitly (covia#230) and are the only way to read scoped scratch job-free.
+ *
+ * Each namespace consumes a different part of the scope, and the venue rejects
+ * a selector its namespace does not use:
+ *
+ * | Path | Needs            | Resolves to                                  |
+ * |------|------------------|----------------------------------------------|
+ * | `n/` | `agent`          | `g/<agent>/n/...`                            |
+ * | `c/` | `agent`+`session`| `g/<agent>/sessions/<session>/c/...`         |
+ * | `t/` | `agent`+`task`   | `j/<task>/temp/...`                          |
+ *
+ * A bound scope may therefore carry all three; each read sends only what its
+ * own namespace needs.
+ */
+interface ExecutionScope {
+    /** Agent id (`alice`) or a full agent DID. Required for every scoped read. */
+    agent: string;
+    /** Task id — the `agent:request` Job whose record holds `t/` scratch. */
+    task?: string;
+    /** Session id, for `c/` session scratch. */
+    session?: string;
+}
 interface WorkspaceListInput {
     path?: string;
     limit?: number;
@@ -2282,4 +2485,4 @@ declare function grant(ownerPrivateKey: Uint8Array, audienceDID: string, withRes
  */
 declare function relayDelegation(privateKey: Uint8Array, venueDID: string, lifetimeSeconds: number, caps?: UCANCapability[]): string;
 
-export { type A2AAuthRef, type A2AImportAgentInput, type A2AImportAgentResult, A2AManager, type A2AMessage, type A2APart, type A2ATask, type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentCycleEndEvent, type AgentCycleStartEvent, type AgentDeleteInput, type AgentDeleteResult, type AgentEvent, type AgentEventEnvelope, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInferenceEndEvent, type AgentInferenceStartEvent, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentRunEndEvent, type AgentRunStartEvent, type AgentSession, type AgentSessionListOptions, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, AgentStatus, type AgentStatusEvent, type AgentSuspendResult, type AgentToolResultEvent, type AgentToolStartEvent, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, type AuthenticationKeyEntry, type AuthenticationKeysMap, type AuthenticationKeysResult, type AuthenticatorRevokeResult, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, type UserInfo, type UserListResult, UserManager, type UserSummary, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };
+export { type A2AAuthRef, type A2AImportAgentInput, type A2AImportAgentResult, A2AManager, type A2AMessage, type A2APart, type A2ATask, type AdapterInfo, AdapterManager, type AdaptersResult, Agent, type AgentCancelTaskInput, type AgentCard, type AgentChatInput, type AgentChatResult, type AgentCompactedSegment, type AgentCompleteTaskResult, type AgentContextInput, type AgentCreateInput, type AgentCreateResult, type AgentCycleEndEvent, type AgentCycleStartEvent, type AgentDeleteInput, type AgentDeleteResult, type AgentEvent, type AgentEventEnvelope, type AgentFailTaskResult, type AgentForkInput, type AgentForkResult, type AgentInferenceEndEvent, type AgentInferenceStartEvent, type AgentInfoResult, type AgentListInput, type AgentListResult, AgentManager, type AgentMessageInput, type AgentMessageResult, type AgentRenameSessionResult, type AgentRequestInput, type AgentRequestResult, type AgentResumeInput, type AgentRunEndEvent, type AgentRunStartEvent, type AgentSession, type AgentSessionListOptions, type AgentSessionMessage, type AgentSessionMetadata, AgentSessionNotFoundError, type AgentSessionPage, type AgentSessionRole, AgentStatus, type AgentStatusEvent, type AgentSuspendResult, type AgentToolResultEvent, type AgentToolStartEvent, type AgentTriggerInput, type AgentTriggerResult, type AgentUpdateInput, Asset, type AssetID, type AssetList, type AssetListItem, type AssetListOptions, AssetManager, type AssetMetadata, type AssetMetadataStore, AssetNotFoundError, type AssetPinResult, type AssetSummary, Auth, type AuthenticationKeyEntry, type AuthenticationKeysMap, type AuthenticationKeysResult, type AuthenticatorRevokeResult, BasicAuth, BearerAuth, ChatSession, type ConnectionAttempt, type ContentDetails, type ContentHashResult, CoviaConnectionError, type CoviaConnectionErrorOptions, CoviaError, CoviaTimeoutError, type Credentials, CredentialsHTTP, type DIDDocument, type DIDURL, type DLFSDrivesResult, type DLFSEntry, type DLFSListResult, DLFSManager, DataAsset, Ed25519Auth, type ExecutionScope, type ExpandedAssetList, type FunctionInfo, type FunctionsResult, Grid, GridError, type GroupCount, type InvokeOptions, type InvokePayload, Job, JobFailedError, type JobHistoryOptions, type JobHistoryPage, JobManager, type JobMetadata, JobNotFoundError, JobStatus, KeyPairAuth, type MCPDiscovery, type MemoryChange, type MemoryEntry, MemoryManager, type MyAssetList, Namespace, NoAuth, NotFoundError, Operation, type OperationDetails, type OperationInfo, OperationManager, type OperationPayload, type OperationRunner, RateLimitError, RunStatus, type SSEEvent, ScopedWorkspace, type SecretExtractInput, type SecretExtractResult, SecretManager, type SecretSetInput, type SecretSetResult, type Skill, type SkillFacet, SkillManager, type SkillMetadata, type StatsData, type StatusData, type UCANAttenuation, type UCANCapability, type UCANIssueInput, type UCANIssueResult, UCANManager, type UCANVerifyResult, UnsupportedVenueFeatureError, type UserInfo, type UserListResult, UserManager, type UserSummary, VENUE_RELAY, Venue, type VenueConstructor, type VenueData, VenueIdentityChangedError, type VenueInterface, type VenueOptions, type WorkspaceAggregateResult, type WorkspaceAppendInput, type WorkspaceAppendResult, type WorkspaceCopyResult, type WorkspaceCountResult, type WorkspaceDeleteInput, type WorkspaceDeleteResult, type WorkspaceInspectInput, type WorkspaceInspectResult, type WorkspaceListInput, type WorkspaceListResult, WorkspaceManager, type WorkspaceReadInput, type WorkspaceReadResult, type WorkspaceSliceInput, type WorkspaceSliceResult, type WorkspaceWriteInput, type WorkspaceWriteResult, assetHash, createSSEEvent, createUCANJWT, decodePublicKey, didFor, didFromPublicKey, didMethod, didUrl, encodePublicKey, fetchStreamWithError, fetchWithError, generateKeyPair, getAssetIdFromPath, getAssetIdFromVenueId, getAssetMetadataStore, getParsedAssetId, grant, hexToPrivateKey, identityToken, isDid, isJobComplete, isJobFinished, isJobPaused, logger, parseDidUrl, parseRetryAfterMs, parseSSEStream, privateKeyToHex, relayDelegation, retryDelayMs, setAssetMetadataStore, venueBaseUrlCandidates };

package/dist/index.js

@@ -1743,16 +1743,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
   };
 }
@@ -1905,11 +1935,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 [];
@@ -1918,8 +1968,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. */
@@ -2111,6 +2161,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");
@@ -2152,6 +2220,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}`);
@@ -2583,12 +2715,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) {
@@ -2622,6 +2794,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");
@@ -2682,6 +2900,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 {
@@ -3053,6 +3295,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);
@@ -3587,6 +3838,7 @@ exports.Operation = Operation;
 exports.OperationManager = OperationManager;
 exports.RateLimitError = RateLimitError;
 exports.RunStatus = RunStatus;
+exports.ScopedWorkspace = ScopedWorkspace;
 exports.SecretManager = SecretManager;
 exports.SkillManager = SkillManager;
 exports.UCANManager = UCANManager;

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.17.0",
+  "version": "1.18.0",
   "description": "Typescript library for covia-ai",
   "packageManager": "pnpm@11.9.0",
   "main": "./dist/index.js",