@aexhq/sdk 0.46.4-canary → 0.50.0

package/dist/_contracts/operations.d.ts

@@ -1,218 +0,0 @@
-import type { HttpClient } from "./http.js";
-import type { AexEvent } from "./event-envelope.js";
-import type { OtlpExportLogsServiceRequest, OtlpExportRequest, OtlpExportTraceServiceRequest, OtlpSignal } from "./otlp-projection.js";
-import { type IdempotencyOptions } from "./operation-core.js";
-import type { ChildSessionRef, SessionFile, SessionFileLink, SessionFileLinkOptions, SessionFileDownload, SessionFileSelector, SessionFilesQuery, SessionFilesSnapshot, SessionFileText, ReadSessionFileTextOptions, Session, SessionCreateRequest, SessionListPage, SessionListQuery, SessionMessageAccepted, SessionMessageRequest, SessionMessagesPage, SessionMessagesQuery, SessionDeleteAccepted, SessionStateChangeAccepted, SessionWebhookDelivery, WhoAmI, AccountWhoAmI } from "./runtime-types.js";
-import type { ToolInputSchema } from "./session-config.js";
-import type { WorkspaceFileRecord, WorkspaceInstructionRecord, WorkspaceResourceListQuery, WorkspaceResourcePage, WorkspaceSkillRecord, WorkspaceToolRecord } from "./workspace-resources.js";
-export { classifySessionFile, filterSessionFiles, resolveSessionFileSelector, toFilenameMatcher } from "./session-file-query.js";
-export { IDEMPOTENCY_KEY_MAX_LENGTH, deriveMessageIdempotencyKey, resolveIdempotencyKey } from "./operation-core.js";
-export type { IdempotencyOptions } from "./operation-core.js";
-export * from "./account-operations.js";
-export interface CreateSessionWithMessageOptions extends IdempotencyOptions {
-    readonly messageIdempotencyKey?: string;
-}
-export declare function createSession(http: HttpClient, request: SessionCreateRequest, options?: IdempotencyOptions): Promise<Session>;
-/** Create a session and enqueue its first message without waiting for the RUN terminal. */
-export declare function createSessionWithMessage(http: HttpClient, request: SessionCreateRequest, input: SessionMessageRequest["input"], options?: CreateSessionWithMessageOptions): Promise<SessionMessageAccepted>;
-export declare function getSession(http: HttpClient, sessionId: string): Promise<Session>;
-export declare function listSessions(http: HttpClient, query?: SessionListQuery): Promise<SessionListPage>;
-export declare function sendSessionMessage(http: HttpClient, sessionId: string, request: SessionMessageRequest, options?: IdempotencyOptions): Promise<SessionMessageAccepted>;
-export declare function listSessionMessages(http: HttpClient, sessionId: string, query?: SessionMessagesQuery): Promise<SessionMessagesPage>;
-export declare function suspendSession(http: HttpClient, sessionId: string): Promise<SessionStateChangeAccepted>;
-export declare function cancelSession(http: HttpClient, sessionId: string): Promise<SessionStateChangeAccepted>;
-export declare function resumeSession(http: HttpClient, sessionId: string): Promise<SessionStateChangeAccepted>;
-/**
- * Request the HITL write-gate: park the session `awaiting_approval` before its
- * next gated action (mirrors {@link suspendSession}). Imperative counterpart to
- * the declarative submission-time `approvalGate`.
- */
-export declare function requestApproval(http: HttpClient, sessionId: string): Promise<SessionStateChangeAccepted>;
-/** Approve an `awaiting_approval` session so the held turn resumes (→ running). */
-export declare function approveSession(http: HttpClient, sessionId: string): Promise<SessionStateChangeAccepted>;
-/** Deny an `awaiting_approval` session so the held turn is cancelled (→ cancelled). */
-export declare function denySession(http: HttpClient, sessionId: string): Promise<SessionStateChangeAccepted>;
-/**
- * Delete a session and purge its stored footprint.
- *
- * Answers 200 with a BODY, not 204 — the deleted session plus the counters from
- * a best-effort cleanup. This used to be typed `SessionStateChangeAccepted |
- * void`, which said the body might not arrive and hid the two cleanup fields
- * entirely; it always arrives, and `cleanupComplete: false` is the only signal
- * that some stored objects survived the delete.
- */
-export declare function deleteSession(http: HttpClient, sessionId: string): Promise<SessionDeleteAccepted>;
-export declare function listSessionEvents(http: HttpClient, sessionId: string): Promise<readonly AexEvent[]>;
-export interface IterateSessionEventsOptions {
-    /** Number of events requested per API page. Default and maximum: 1000. */
-    readonly pageSize?: number;
-    readonly signal?: AbortSignal;
-}
-/**
- * Lazily traverse a session's durable event history. At most one bounded API
- * page is retained by this iterator, and breaking the loop prevents later
- * pages from being requested.
- */
-export declare function iterateSessionEvents(http: HttpClient, sessionId: string, options?: IterateSessionEventsOptions): AsyncIterable<AexEvent>;
-export interface SessionOtlpPage<Body extends OtlpExportRequest = OtlpExportRequest> {
-    /** The unwrapped, standards-pure OTLP/HTTP JSON request body. */
-    readonly body: Body;
-    /** Opaque API cursor carried separately from the OTLP body. */
-    readonly nextCursor?: string;
-}
-export interface IterateSessionOtlpOptions {
-    readonly signal?: AbortSignal;
-}
-export declare function getSessionOtlpPage(http: HttpClient, sessionId: string, signal: "traces", cursor?: string, abortSignal?: AbortSignal): Promise<SessionOtlpPage<OtlpExportTraceServiceRequest>>;
-export declare function getSessionOtlpPage(http: HttpClient, sessionId: string, signal: "logs", cursor?: string, abortSignal?: AbortSignal): Promise<SessionOtlpPage<OtlpExportLogsServiceRequest>>;
-/**
- * Lazily traverse standards-pure OTLP pages. Pagination metadata remains in
- * `x-aex-next-cursor`; it is never mixed into an OTLP request body.
- */
-export declare function iterateSessionOtlpPages(http: HttpClient, sessionId: string, signal: OtlpSignal, options?: IterateSessionOtlpOptions): AsyncIterable<OtlpExportRequest>;
-export declare function listSessionFiles(http: HttpClient, sessionId: string, query?: SessionFilesQuery): Promise<SessionFilesSnapshot>;
-export declare function getSessionCoordinatorTicket(http: HttpClient, sessionId: string): Promise<CoordinatorTicket>;
-/**
- * A coordinator WS connection grant minted by the hosted API's ticket broker.
- *
- * `ok` and `region` are on the wire and were undeclared. `region` is the plane
- * the ticket was minted in, which matters because the grant is only valid
- * against that region's coordinator.
- */
-export interface CoordinatorTicket {
-    readonly ok: true;
-    readonly wsUrl: string;
-    readonly ticket: string;
-    readonly expiresAtMs: number;
-    /** The region whose coordinator this ticket authorises. */
-    readonly region: string;
-}
-export declare function findSessionFiles(http: HttpClient, sessionId: string, query: SessionFilesQuery): Promise<readonly SessionFile[]>;
-export declare function findSessionFile(http: HttpClient, sessionId: string, query: SessionFilesQuery): Promise<SessionFile | null>;
-export type SessionFileLinkSelector = SessionFileSelector | SessionFilesQuery;
-export declare function sessionFileLink(http: HttpClient, sessionId: string, selectorOrQuery: SessionFileLinkSelector, options?: SessionFileLinkOptions): Promise<SessionFileLink>;
-export declare function eventArchiveLink(http: HttpClient, sessionId: string, options?: SessionFileLinkOptions): Promise<SessionFileLink>;
-export declare function downloadSessionFile(http: HttpClient, sessionId: string, selector: SessionFileSelector, options?: SessionFileTransferOptions): Promise<SessionFileDownload>;
-/** Byte ceiling for {@link readSessionFileText} — a hard cap even if a caller asks for more. */
-export declare const READ_SESSION_FILE_TEXT_MAX_BYTES = 10000000;
-/** Default `maxBytes` for {@link readSessionFileText} — a chat-sized preview. */
-export declare const READ_SESSION_FILE_TEXT_DEFAULT_BYTES = 50000;
-/** Default per-attempt timeout while fetching or reading one session file body. */
-export declare const SESSION_FILE_TRANSFER_DEFAULT_TIMEOUT_MS = 30000;
-/** Idempotent file GETs retry once on a transfer timeout. */
-export declare const SESSION_FILE_TRANSFER_ATTEMPTS = 2;
-export interface SessionFileTransferOptions {
-    readonly timeoutMs?: number;
-    readonly checkpointId?: string;
-}
-/**
- * Read ONE session file as byte-capped, decoded UTF-8 text. Built for handing a session
- * deliverable to an LLM tool: it streams the file body and STOPS at `maxBytes`, so
- * a 200 MB artifact never fully buffers in memory or context. `truncated` is true
- * when the file is larger than the cap. Optionally `grep` keeps only matching lines.
- *
- * Selector is the same `{ path }` / `{ id }` shape as `downloadSessionFile`.
- * Both forms resolve against the authoritative checkpoint snapshot first.
- */
-export declare function readSessionFileText(http: HttpClient, sessionId: string, selector: SessionFileSelector, options?: ReadSessionFileTextOptions): Promise<SessionFileText>;
-/**
- * List a session's subagent child sessions (`GET /api/sessions/:id/children`). Each
- * {@link ChildSessionRef} is a read-only lineage snapshot whose id addresses
- * events, checkpointed files, and descendants. An empty array means the session
- * spawned no children.
- */
-export declare function listSessionChildren(http: HttpClient, sessionId: string): Promise<readonly ChildSessionRef[]>;
-/**
- * List a session's run-terminal webhook deliveries. Each finalized run has its
- * own row; an empty array means the session has no webhook or no run has
- * finalized yet.
- */
-export declare function getSessionWebhookDeliveries(http: HttpClient, sessionId: string): Promise<readonly SessionWebhookDelivery[]>;
-/**
- * Manually re-trigger one run's webhook delivery: resets the row to `pending`
- * and re-sends the frozen payload with the same run-scoped `webhook-id`.
- */
-export declare function redeliverSessionWebhook(http: HttpClient, sessionId: string, deliveryId: string): Promise<void>;
-/**
- * Delete a workspace asset cache entry. Accepts an `asset_<id>` value,
- * `sha256:<hex>`, or a bare 64-hex digest. Workspace is derived server-side
- * from the token; idempotent.
- * Does NOT affect sessions that already snapshotted the asset.
- */
-export declare function deleteWorkspaceAsset(http: HttpClient, hash: string): Promise<void>;
-export declare function whoami(http: HttpClient): Promise<WhoAmI>;
-/**
- * Validate a CONTROL-plane account token (PAT / device session) against the
- * dashboard BFF `GET /api/whoami`. Same endpoint as {@link whoami}, but the
- * bearer is an account PAT (`aexu_...`) so the server answers with an
- * `account_token` principal (no workspace, no data-plane limits) — a shape the
- * workspace-key {@link whoami} parser rejects. Used by
- * `aex login --api-key <account PAT>` to prove the PAT before persisting it.
- */
-export declare function accountWhoami(http: HttpClient): Promise<AccountWhoAmI>;
-export declare function normalizeSessionFileLinkExpiresIn(input?: SessionFileLinkOptions["expiresIn"]): number;
-/**
- * Download EVERYTHING public about a session as one zip, organised into the three
- * namespace folders:
- *
- *   metadata/session.json     — the session record.
- *   events/events.jsonl   — typed event-channel records.
- *   files/<rel>       — the session's captured files.
- *   manifest.json         — `SessionRecordManifestV1`.
- */
-export declare function download(http: HttpClient, sessionId: string): Promise<Uint8Array>;
-/**
- * Download only the session's captured files (the `files` namespace). Zip
- * layout: `<rel>` per file plus a `manifest.json`
- * (`{ sessionId, namespace: "files", files[], errors[] }`).
- */
-export declare function downloadSessionFiles(http: HttpClient, sessionId: string, options?: SessionFileTransferOptions): Promise<Uint8Array>;
-/**
- * Download only the event archive (the `events` namespace). Always includes
- * typed `events.jsonl` plus `manifest.json`.
- */
-export declare function downloadEvents(http: HttpClient, sessionId: string): Promise<Uint8Array>;
-/**
- * Download only the session record (the `metadata` namespace) as a zip
- * containing `session.json` plus `manifest.json`.
- */
-export declare function downloadMetadata(http: HttpClient, sessionId: string): Promise<Uint8Array>;
-interface WorkspacePublishBase {
-    readonly assetId: string;
-    readonly contentHash: string;
-    readonly sizeBytes: number;
-    readonly contentType: string;
-}
-export type PublishWorkspaceFileInput = WorkspacePublishBase & {
-    readonly name: string;
-    readonly mountPath: string;
-};
-export type PublishWorkspaceSkillInput = WorkspacePublishBase & {
-    readonly name: string;
-    readonly description: string;
-};
-export type PublishWorkspaceToolInput = WorkspacePublishBase & {
-    readonly name: string;
-    readonly description: string;
-    readonly input_schema: ToolInputSchema;
-    readonly entry: string;
-};
-export type PublishWorkspaceInstructionInput = WorkspacePublishBase & {
-    readonly name: string;
-};
-export declare function publishWorkspaceFile(http: HttpClient, input: PublishWorkspaceFileInput): Promise<WorkspaceFileRecord>;
-export declare function publishWorkspaceSkill(http: HttpClient, input: PublishWorkspaceSkillInput): Promise<WorkspaceSkillRecord>;
-export declare function publishWorkspaceTool(http: HttpClient, input: PublishWorkspaceToolInput): Promise<WorkspaceToolRecord>;
-export declare function publishWorkspaceInstruction(http: HttpClient, input: PublishWorkspaceInstructionInput): Promise<WorkspaceInstructionRecord>;
-export declare function listWorkspaceFiles(http: HttpClient, query?: WorkspaceResourceListQuery): Promise<WorkspaceResourcePage<WorkspaceFileRecord>>;
-export declare function listWorkspaceSkills(http: HttpClient, query?: WorkspaceResourceListQuery): Promise<WorkspaceResourcePage<WorkspaceSkillRecord>>;
-export declare function listWorkspaceTools(http: HttpClient, query?: WorkspaceResourceListQuery): Promise<WorkspaceResourcePage<WorkspaceToolRecord>>;
-export declare function listWorkspaceInstructions(http: HttpClient, query?: WorkspaceResourceListQuery): Promise<WorkspaceResourcePage<WorkspaceInstructionRecord>>;
-export declare function getWorkspaceFile(http: HttpClient, resourceId: string, version?: number): Promise<WorkspaceFileRecord>;
-export declare function getWorkspaceSkill(http: HttpClient, resourceId: string, version?: number): Promise<WorkspaceSkillRecord>;
-export declare function getWorkspaceTool(http: HttpClient, resourceId: string, version?: number): Promise<WorkspaceToolRecord>;
-export declare function getWorkspaceInstruction(http: HttpClient, resourceId: string, version?: number): Promise<WorkspaceInstructionRecord>;
-export declare function deleteWorkspaceFile(http: HttpClient, resourceId: string): Promise<void>;
-export declare function deleteWorkspaceSkill(http: HttpClient, resourceId: string): Promise<void>;
-export declare function deleteWorkspaceTool(http: HttpClient, resourceId: string): Promise<void>;
-export declare function deleteWorkspaceInstruction(http: HttpClient, resourceId: string): Promise<void>;