@covia/covia-sdk 1.16.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;
@@ -1157,7 +1272,31 @@ interface JobMetadata {
     updated?: string;
     input?: unknown;
     output?: unknown;
-    operation?: string;
+    /** The operation reference that was invoked, verbatim: a venue path
+     *  (`v/ops/json/merge`), a caller-namespace path (`o/my-tool`), a DID URL, or
+     *  a bare hash when the caller pinned a definition explicitly. An inline
+     *  definition has no reference, so its own metadata hash stands in. Records
+     *  written by venues before 0.9.9 always carry the resolved hash, so readers
+     *  must accept both forms (covia#499).
+     *
+     *  A path is a mutable binding: re-invoking this reference runs whatever
+     *  definition sits at that path now, which is not necessarily the one that
+     *  ran for this job. Invoke by hash when the record must pin the exact
+     *  definition.
+     *
+     *  Replaces the never-populated `operation` field — the venue has always
+     *  emitted this as `op`. */
+    op?: string;
+    /** Id (hex) of the nearest *recorded* job inside whose execution this job was
+     *  dispatched; absent on top-level jobs (covia#500). Transient wrappers never
+     *  appear in a record, so a recorded grandchild dispatched through a
+     *  transient layer links straight to its recorded ancestor.
+     *
+     *  Only the up-link is stored: there is no `root`, no children list and no
+     *  children query. Reconstruct a tree by tracing `parent` across the jobs you
+     *  hold. Links are venue- and user-local — a job run on another venue through
+     *  the grid adapter carries none. */
+    parent?: string;
     caller?: string;
     error?: string;
     [key: string]: unknown;
@@ -1414,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[];
@@ -1616,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;
@@ -2258,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 };