@hypercli.com/sdk 0.9.1

package/dist/runners.js

@@ -0,0 +1,127 @@
+/**
+ * Runners API - self-hosted compute registry (agents backend /runners).
+ */
+import { requestWithRetry, responseAPIError } from './http.js';
+import { getAgentsApiBaseUrl } from './config.js';
+export function deriveRunnersApiBase(agentsApiBase) {
+    const raw = (agentsApiBase || getAgentsApiBaseUrl()).replace(/\/$/, '');
+    const url = new URL(raw.includes('://') ? raw : `https://${raw}`);
+    const path = url.pathname.replace(/\/$/, '');
+    if (path.endsWith('/runners')) {
+        return `${url.protocol}//${url.host}${path}`;
+    }
+    return `${url.protocol}//${url.host}${path}/runners`;
+}
+function runnerUiMetaFromDict(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    const ui = {};
+    if ('display_name' in data) {
+        const value = data.display_name;
+        if (typeof value !== 'string' && value !== null)
+            return null;
+        ui.displayName = value;
+    }
+    return ui;
+}
+function runnerMetaFromDict(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    const meta = {};
+    if ('ui' in data)
+        meta.ui = runnerUiMetaFromDict(data.ui);
+    return meta;
+}
+function runnerFromDict(data) {
+    const platform = data?.platform && typeof data.platform === 'object' ? data.platform : {};
+    return {
+        runnerId: String(data?.runner_id || ''),
+        ownerUserId: String(data?.owner_user_id || ''),
+        name: String(data?.name || ''),
+        tags: Array.isArray(data?.tags) ? data.tags.map(String) : [],
+        platform: { os: String(platform.os || ''), arch: String(platform.arch || '') },
+        version: String(data?.version || ''),
+        createdAt: data?.created_at ?? null,
+        lastSeenAt: data?.last_seen_at ?? null,
+        disconnectedAt: data?.disconnected_at ?? null,
+        meta: runnerMetaFromDict(data?.meta),
+        ...(data?.connected !== undefined ? { connected: Boolean(data.connected) } : {}),
+        ...(data?.ready !== undefined ? { ready: Boolean(data.ready) } : {}),
+        ...(data?.connection_scope !== undefined ? { connectionScope: String(data.connection_scope) } : {}),
+    };
+}
+async function handleResponse(response, method) {
+    if (response.status >= 400) {
+        throw await responseAPIError(response, method);
+    }
+    if (response.status === 204 || response.status === 205)
+        return undefined;
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    return JSON.parse(text);
+}
+function encodeRef(value) {
+    return encodeURIComponent(value);
+}
+export class RunnersAPI {
+    apiBase;
+    apiKey;
+    timeout;
+    constructor(apiKey, options = {}) {
+        if (!apiKey) {
+            throw new Error('API key required for runners');
+        }
+        this.apiKey = apiKey;
+        this.apiBase = (options.apiBase || deriveRunnersApiBase(options.agentsApiBase)).replace(/\/$/, '');
+        this.timeout = options.timeout ?? 30000;
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+        };
+    }
+    async request(method, path, body) {
+        const response = await requestWithRetry({
+            method,
+            url: `${this.apiBase}${path}`,
+            headers: this.headers(),
+            body,
+            retries: method === 'GET' ? 3 : 1,
+            timeout: this.timeout,
+        });
+        return handleResponse(response, method);
+    }
+    async list() {
+        const data = await this.request('GET', '');
+        const items = Array.isArray(data) ? data : Array.isArray(data?.runners) ? data.runners : null;
+        if (!items) {
+            throw new Error('Runners response must be an array.');
+        }
+        return items.map(runnerFromDict);
+    }
+    /** Omit runnerId to allocate an identity. Sent once; a lost reply is uncertain. */
+    async register(body) {
+        return runnerFromDict(await this.request('POST', '', {
+            ...(body.runnerId !== undefined ? { runner_id: body.runnerId } : {}),
+            name: body.name, tags: body.tags ?? [], version: body.version, platform: body.platform,
+        }));
+    }
+    async get(runnerId) {
+        const data = await this.request('GET', `/${encodeRef(runnerId)}`);
+        return runnerFromDict(data);
+    }
+    async update(runnerId, body) {
+        const payload = {};
+        if (body.ui !== undefined) {
+            const ui = {};
+            if (body.ui.displayName !== undefined)
+                ui.display_name = body.ui.displayName;
+            payload.ui = ui;
+        }
+        const data = await this.request('PATCH', `/${encodeRef(runnerId)}`, payload);
+        return runnerFromDict(data);
+    }
+}
+//# sourceMappingURL=runners.js.map

package/dist/runners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runners.js","sourceRoot":"","sources":["../src/runners.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,MAAM,UAAU,oBAAoB,CAAC,aAAsB;IACzD,MAAM,GAAG,GAAG,CAAC,aAAa,IAAI,mBAAmB,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACxE,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,CAAC,CAAC;IAClE,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7C,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9B,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,EAAE,CAAC;IAC/C,CAAC;IACD,OAAO,GAAG,GAAG,CAAC,QAAQ,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,UAAU,CAAC;AACvD,CAAC;AAyCD,SAAS,oBAAoB,CAAC,IAAS;IACrC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,MAAM,EAAE,GAAiB,EAAE,CAAC;IAC5B,IAAI,cAAc,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC;QAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC7D,EAAE,CAAC,WAAW,GAAG,KAAK,CAAC;IACzB,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAS;IACnC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1E,MAAM,IAAI,GAAe,EAAE,CAAC;IAC5B,IAAI,IAAI,IAAI,IAAI;QAAE,IAAI,CAAC,EAAE,GAAG,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,cAAc,CAAC,IAAS;IAC/B,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1F,OAAO;QACL,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,IAAI,EAAE,CAAC;QACvC,WAAW,EAAE,MAAM,CAAC,IAAI,EAAE,aAAa,IAAI,EAAE,CAAC;QAC9C,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;QAC9B,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;QAC5D,QAAQ,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE;QAC9E,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,IAAI,EAAE,CAAC;QACpC,SAAS,EAAE,IAAI,EAAE,UAAU,IAAI,IAAI;QACnC,UAAU,EAAE,IAAI,EAAE,YAAY,IAAI,IAAI;QACtC,cAAc,EAAE,IAAI,EAAE,eAAe,IAAI,IAAI;QAC7C,IAAI,EAAE,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC;QACpC,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,GAAG,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,GAAG,CAAC,IAAI,EAAE,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpG,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,cAAc,CAAU,QAAkB,EAAE,MAAe;IACxE,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QAC3B,MAAM,MAAM,gBAAgB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,SAAc,CAAC;IAC9E,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAc,CAAC;IACjC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;AAC/B,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,OAAO,UAAU;IACb,OAAO,CAAS;IAChB,MAAM,CAAS;IACf,OAAO,CAAS;IAExB,YAAY,MAAc,EAAE,UAA0E,EAAE;QACtG,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,oBAAoB,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACnG,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,KAAK,CAAC;IAC1C,CAAC;IAEO,OAAO;QACb,OAAO;YACL,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;YACtC,cAAc,EAAE,kBAAkB;SACnC,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,OAAO,CAAU,MAAc,EAAE,IAAY,EAAE,IAAU;QACrE,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC;YACtC,MAAM;YACN,GAAG,EAAE,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE;YAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE;YACvB,IAAI;YACJ,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;QACH,OAAO,cAAc,CAAI,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAM,KAAK,EAAE,EAAE,CAAC,CAAC;QAChD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QAC9F,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACnC,CAAC;IAED,mFAAmF;IACnF,KAAK,CAAC,QAAQ,CAAC,IAA2B;QACxC,OAAO,cAAc,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,EAAE;YACnD,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACvF,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,QAAgB;QACxB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAClE,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,IAAyB;QACtD,MAAM,OAAO,GAA4B,EAAE,CAAC;QAC5C,IAAI,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,EAAE,GAA4B,EAAE,CAAC;YACvC,IAAI,IAAI,CAAC,EAAE,CAAC,WAAW,KAAK,SAAS;gBAAE,EAAE,CAAC,YAAY,GAAG,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC;YAC7E,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;QAClB,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC7E,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CACF"}

package/dist/sessions.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Sessions REST client — the §15 memory-shaped session model
+ * (sessions/README §15) as a read surface for console/desktop/CLI.
+ *
+ * The backend proxy (`/ws/acp`, see acp.ts) is the write/turn path; this
+ * namespace is the typed read path over the durable `agent_sessions` /
+ * `session_messages` tables: session catalog with summaries and participants,
+ * backwards-paginated history per session. The wire contract is owned by the
+ * backend routes (`agents/backend/agents/session_routes.py` —
+ * `SessionListPage` / `SessionMessagePage`), and both pages are the same
+ * envelope: `{ items, next_cursor, has_more }`.
+ *
+ * Pagination contract (§15 "Type & pagination"): every list is keyset over a
+ * server-issued opaque cursor — never OFFSET. Messages page BACKWARDS from
+ * last-seen (`seq < cursor`, newest first), extending whole chunk runs and tool
+ * dependencies; has_more says older eligible rows exist. Sessions page over
+ * `(updated_at, id)`.
+ */
+import type { HTTPClient } from './http.js';
+/** Native catalog discovery, independent of active conversation/turn state. */
+export interface SessionDiscoveryStatus {
+    status: 'pending' | 'running' | 'complete' | 'error' | 'unsupported';
+    /** Catalog enumeration may succeed even when the runtime cannot replay history. */
+    history_status?: 'unknown' | 'supported' | 'unsupported';
+    error_code: 'runtime_unavailable' | 'discovery_failed' | 'catalog_unsupported' | null;
+    discovered_count: number | null;
+    queued_count: number;
+    importing_count: number;
+    last_attempt_at: string | null;
+    last_completed_at: string | null;
+}
+/** Durable, content-free REST evidence for the current import generation.
+ * Counts describe the attempt, not the requested history page. `empty` means
+ * supported replay completed with zero updates; `filtered` means valid updates
+ * were excluded by retention policy. Unknown/never-attempted evidence is null.
+ */
+export interface SessionImportOutcome {
+    status: 'retained' | 'empty' | 'filtered' | 'unsupported' | 'malformed' | 'failed';
+    protocol_version: 1 | null;
+    generation: number;
+    recorded_at: string;
+    observed_updates: number;
+    valid_updates: number;
+    filtered_updates: number;
+    invalid_updates: number;
+    foreign_updates: number;
+    retained_rows: number;
+}
+/** One `session_participants` row as embedded in the session catalog (backend `SessionParticipant`). */
+export interface AcpSessionParticipant {
+    kind: 'user' | 'agent';
+    participantId: string;
+    /** The agent leg's harness-side session id; null for user participants and legs without one. */
+    internalSessionId: string | null;
+    /** Participant's durable delivery cursor (seq) in this session. */
+    cursorPos: number;
+}
+/** One `agent_sessions` row as the catalog sees it (backend `SessionListItem`). summaryText doubles as the display title. */
+export interface AcpSessionRecord {
+    id: string;
+    /** Persisted product permission mode; distinct from native ACP session modes. */
+    mode?: 'ask' | 'auto' | 'none' | null;
+    /** Descriptive creation provenance; unknown values are preserved. */
+    source: string | null;
+    createdAt: string | null;
+    /** Last-activity timestamp; bumps on every message append, not on row touch. */
+    updatedAt: string | null;
+    summaryText: string | null;
+    summaryKeywords: string[];
+    participants: AcpSessionParticipant[];
+    importOutcome?: SessionImportOutcome | null;
+}
+/**
+ * Per-logical-message delivery evidence from the session detail read (backend
+ * `SessionStateDetail.receipts`): the settled markers a chat pane merges onto
+ * already-rendered messages without paging message rows. Merged per
+ * participant, role and message id: earliest created_at, first non-null delivery
+ * and user completion (latest assistant completion). Missing scope stays unknown.
+ */
+export interface AcpSessionReceipt {
+    messageId: string;
+    role: 'user' | 'assistant' | 'tool';
+    /** Author scope, matching messages-page participantId; absent on older servers. */
+    participantId?: string | null;
+    createdAt: string | null;
+    deliveredAt: string | null;
+    completedAt: string | null;
+}
+/**
+ * The session detail read (`GET /sessions/{id}`, backend `SessionStateDetail`):
+ * the catalog record plus the state a chat pane needs to open on the session —
+ * logical-message identity anchors and delivery receipts — without the
+ * messages page. Fields absent on an older backend default empty.
+ */
+export interface AcpSessionState extends AcpSessionRecord {
+    /** Effective identity of the newest replay-eligible logical message; null on an empty session. */
+    lastMessageId: string | null;
+    /** Distinct logical message identities over replay-eligible rows. */
+    messageCount: number;
+    /** Highest stored seq; the read receipt advances to here. */
+    headSeq: number;
+    receipts: AcpSessionReceipt[];
+    /** Agent connection state computed per request by the backend, never stored; null on a pre-state backend. */
+    agentState: 'live' | 'archived' | 'deleted' | null;
+}
+/** Current product metadata on an existing session message, never ACP metadata. */
+export interface SessionMessageMeta {
+    /** Keys are exact `unicode:${value}` or `custom:${scopedReference}`. */
+    reactions: Record<string, SessionReactionGroup>;
+    reactionSupport: 'supported' | 'unsupported' | 'unknown';
+    reactionsComplete: boolean;
+    /** Canonical UTC, six fractional digits. Compare strings, not JS milliseconds. */
+    reactionUpdatedAt: string | null;
+}
+export interface SessionReactionGroup {
+    /** Null means unknown, not zero or the number of known actors. */
+    count: number | null;
+    actors: Record<string, {
+        isBot: boolean;
+        receipt: string | null;
+    }>;
+    actorsComplete: boolean;
+}
+/** Rollout read compatibility only; new operations already carry dictionary metadata. */
+export declare function sessionMessageMetaFromWire(value: unknown, legacyRead?: boolean): SessionMessageMeta | undefined;
+/** Retain the freshest current projection; equal timestamps preserve object identity. */
+export declare function newerSessionMessageMeta(current: SessionMessageMeta | undefined, incoming: SessionMessageMeta | undefined): SessionMessageMeta | undefined;
+/** Read-only subscriber operation, separate from ACP and from native write requests. */
+export interface SessionReactionOperation {
+    type: 'addReaction' | 'removeReaction';
+    agent_id: string;
+    session_id: string;
+    seq: number;
+    message_id: string;
+    target: {
+        source: string;
+        account: string;
+        workspace: string | null;
+        channel: string | null;
+        thread: string | null;
+        message: string;
+    };
+    actor: {
+        id: string;
+        isBot: boolean;
+    };
+    reaction: {
+        kind: 'unicode' | 'custom';
+        value: string;
+    };
+    receipt: string | null;
+    meta: SessionMessageMeta;
+}
+/** Apply the resulting snapshot, never increment counts or replay actor deltas. */
+export declare function applySessionReactionOperation<T extends AcpSessionMessage>(rows: T[], event: SessionReactionOperation): T[];
+export declare function sessionReactionDisplay(key: string): string;
+/** One `session_messages` row (backend `SessionMessage`): the durable full-fidelity truth for a session. */
+export interface AcpSessionMessage {
+    /** Stable platform history identity; never an ACP wire field. */
+    messageId?: string | null;
+    sessionId: string;
+    /** Per-session ordering; the store's "where are we" value (the ACP wire has no ordinals). */
+    seq: number;
+    role: 'user' | 'assistant' | 'tool';
+    /** ACP-style settled payload at FULL fidelity — tool calls retained. */
+    acp: Record<string, unknown>;
+    /** Absent on older servers. Retain the authoritative snapshot without folding deltas. */
+    meta?: SessionMessageMeta;
+    /** Assistant-side end-of-turn marker; turns derive prompt→stop. */
+    stopReason: string | null;
+    createdAt: string | null;
+    /** Null until delivery is durable: user rows stamp at turn commit, agent rows at persist (§15). */
+    deliveredAt: string | null;
+    /** Null until the covering turn commits; on user rows this is the "agent acted on this" receipt (§15). */
+    completedAt: string | null;
+    /** Author tuple; resolve via the session's participants. */
+    participantKind: 'user' | 'agent' | null;
+    participantId: string | null;
+}
+/** One page of a cursor-paginated endpoint. */
+export interface AcpSessionPage<T> {
+    items: T[];
+    /** Opaque server cursor for the next page; null when exhausted. */
+    nextCursor: string | null;
+    /** The server has more eligible rows beyond this page. */
+    hasMore: boolean;
+}
+export interface AcpSessionMessagePage extends AcpSessionPage<AcpSessionMessage> {
+    importOutcome: SessionImportOutcome | null;
+    /** Session event head read with the page's receipts; missing on older servers. */
+    headSeq?: number | null;
+}
+export interface AcpSessionListOptions {
+    agentId?: string;
+    cursor?: string | null;
+    limit?: number;
+}
+export interface AcpSessionMessagesOptions {
+    /** Opaque cursor from a previous page's nextCursor; omitted starts at the newest message. */
+    cursor?: string | null;
+    limit?: number;
+}
+/**
+ * One full-text transcript hit (backend `GET /sessions/search`): the durable
+ * message the query matched inside, with a server-built excerpt of the
+ * surrounding transcript words. `score` is currently always null — full-text
+ * match carries no rank.
+ */
+export interface AcpTranscriptSearchHit {
+    sessionId: string;
+    /** Authorized platform navigation metadata; null on older servers. */
+    agentId: string | null;
+    title: string | null;
+    seq: number;
+    role: string;
+    /** ACP message identity when the matched frame carries one; resolve via the session's rendered messages. */
+    messageId: string | null;
+    excerpt: string;
+    score: number | null;
+}
+export interface AcpTranscriptSearchOptions {
+    /** Restrict the search to one session (in-transcript find); omitted searches every session the caller can read. */
+    sessionId?: string;
+    /** Opaque cursor from a previous page's nextCursor; omitted starts at the newest session activity. */
+    cursor?: string | null;
+    limit?: number;
+}
+/** Ascending durable-message window centered on `focusSeq` (backend `GET /sessions/{id}/messages/around`). */
+export interface AcpSessionMessagesWindow {
+    sessionId: string;
+    focusSeq: number;
+    items: AcpSessionMessage[];
+}
+/**
+ * Session read surface scoped to the caller's identity (user key: sessions
+ * of owned agents; runtime key: sessions §15 exposes to the pod). Bound to
+ * the agents API base, so `/sessions` resolves to `/agents/sessions`.
+ */
+export declare class SessionsAPI {
+    private readonly http;
+    constructor(http: Pick<HTTPClient, 'get'> & Partial<Pick<HTTPClient, 'post'>>);
+    /** Read discovery evidence; an empty stored catalog alone is not discovery success. */
+    getDiscoveryStatus(agentId: string): Promise<SessionDiscoveryStatus>;
+    /** Explicitly request discovery. Unsupported runtimes remain unsupported. */
+    requestDiscovery(agentId: string): Promise<SessionDiscoveryStatus>;
+    /**
+     * Stored metadata and chat-open state for one platform session ID (not an
+     * agent/runtime session ID). Uses the caller's existing participation scope;
+     * no runtime connection. Advances the caller's read receipt to the head.
+     */
+    getSession(platformSessionId: string): Promise<AcpSessionState>;
+    /** Persist product permission mode. A 503 can follow persistence; GET reads it back. */
+    setMode(platformSessionId: string, mode: 'ask' | 'auto' | 'none'): Promise<AcpSessionRecord>;
+    /** Session catalog page, newest activity first (`(updated_at, id)` keyset). */
+    listSessions(options?: AcpSessionListOptions): Promise<AcpSessionPage<AcpSessionRecord>>;
+    /**
+     * Canonical complete history page, delivered as one coherent result.
+     * Rows stay descending by seq; feed the opaque nextCursor back to read older
+     * rows. Limit (default 20) is a target: the server extends chunk runs and tool
+     * creation dependencies. Native ACP payloads/IDs and full tool content are
+     * untouched; only platform DTO fields are normalized. This read does not
+     * establish a transaction or gap-free boundary with a live subscription.
+     */
+    getMessages(sessionId: string, options?: AcpSessionMessagesOptions): Promise<AcpSessionMessagePage>;
+    /**
+     * Full-text search over durable transcript payloads (`GET /sessions/search`),
+     * keyset-paged over (session activity desc, seq desc). Feed `nextCursor`
+     * back in to walk further. Read-only; no read-receipt effect.
+     */
+    searchTranscript(query: string, options?: AcpTranscriptSearchOptions): Promise<AcpSessionPage<AcpTranscriptSearchHit>>;
+    /**
+     * One ascending window of durable messages around `seq` (`GET
+     * /sessions/{id}/messages/around`) — for landing a search jump on history
+     * the caller has not loaded. Never advances the read receipt.
+     */
+    getMessagesAround(sessionId: string, seq: number, options?: {
+        radius?: number;
+    }): Promise<AcpSessionMessagesWindow>;
+}
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"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"}