@klex/agent-admin-api 0.8.1 → 0.9.0

package/README.md

@@ -66,4 +66,40 @@ The Admin API contract includes the dedicated God Messages session:
 - `GET /v1/god-messages/messages` returns cursor-paginated session history.
 - `POST /v1/god-messages/reset` replaces a resettable session.
 
+## Session history
+
+The agent persists the transcript of every chat session instance (default,
+god, and child) to local storage. These routes expose it read-only:
+
+- `GET /v1/sessions` lists instances, newest first. Filter with `kind`
+  (`default`, `god`, `child`), `live`, and `parentInstanceId`; page with
+  `limit` and the opaque `cursor` returned as `nextCursor`. To find the
+  current main session, call `GET /v1/sessions?kind=default&live=true&limit=1`.
+  A session is persisted only after its first message, so this list can be
+  empty right after a restart.
+- `GET /v1/sessions/{instanceId}` returns one instance's metadata, including
+  `live`, `endReason`, `messageCount`, and `trimmedMessageCount`.
+- `GET /v1/sessions/{instanceId}/messages` returns messages in chronological
+  order. Without a cursor it returns the newest `limit` messages. Pass the
+  numeric `nextCursor` as `cursor` to load the previous, older page.
+
+Messages use the stored AI SDK `UIMessage` shape: `tool-${name}` parts carry
+full `input`, `output`, and `errorText`, and `data-${name}` parts carry their
+`data`. Unlike God Messages history, nothing is truncated. Provider metadata
+(`providerMetadata`, `callProviderMetadata`, `resultProviderMetadata`, such
+as encrypted reasoning) is omitted unless `includeProviderMetadata=true`.
+
+Each `ChatSession` gets its own `instanceId`. The default session reuses
+`sessionId = "default"` across replacements, so query by `instanceId`. The
+local store has a size cap. When the cap is reached, the oldest ended sessions
+are deleted first. After that, the oldest messages of live sessions are
+trimmed, and `trimmedMessageCount` reports how many were removed. Inline
+data is redacted everywhere, including inside tool outputs: the payload of
+every `data:` URL in any encoding, also inside longer strings, the `data`
+field of image, audio, and media blocks, and embedded resource `blob`s.
+Objects nested deeper than 64 levels are replaced by a placeholder.
+
+Unknown instances return `404` with code `session_not_found`. Malformed list
+cursors return `400` with code `invalid_cursor`.
+
 Install `hono` and `@hono/zod-openapi` as peer dependencies.

package/dist/index.d.ts

@@ -512,15 +512,6 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
 } & {
     "/v1/introspect": {
         $get: {
-            output: {
-                error: string;
-                code: string;
-                remediation?: string | undefined;
-            };
-            outputFormat: "json";
-            status: 500;
-            input: {};
-        } | {
             output: {
                 path: string[];
                 state: {
@@ -535,6 +526,15 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             outputFormat: "json";
             status: 200;
             input: {};
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {};
         };
     };
 } & {
@@ -1167,10 +1167,12 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
     "/v1/god-messages": {
         $post: {
             output: {
-                sessionId: string;
+                error: string;
+                code: string;
+                remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 202;
+            status: 400;
             input: {
                 json: {
                     content: ({
@@ -1210,7 +1212,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                 remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 400;
+            status: 409;
             input: {
                 json: {
                     content: ({
@@ -1250,7 +1252,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                 remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 409;
+            status: 500;
             input: {
                 json: {
                     content: ({
@@ -1290,7 +1292,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                 remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 500;
+            status: 503;
             input: {
                 json: {
                     content: ({
@@ -1325,12 +1327,10 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             };
         } | {
             output: {
-                error: string;
-                code: string;
-                remediation?: string | undefined;
+                sessionId: string;
             };
             outputFormat: "json";
-            status: 503;
+            status: 202;
             input: {
                 json: {
                     content: ({
@@ -1523,6 +1523,221 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             input: {};
         };
     };
+} & {
+    "/v1/sessions": {
+        $get: {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 400;
+            input: {
+                query: {
+                    kind?: "child" | "default" | "god" | undefined;
+                    parentInstanceId?: string | undefined;
+                    live?: "false" | "true" | undefined;
+                    limit?: unknown;
+                    cursor?: string | undefined;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {
+                query: {
+                    kind?: "child" | "default" | "god" | undefined;
+                    parentInstanceId?: string | undefined;
+                    live?: "false" | "true" | undefined;
+                    limit?: unknown;
+                    cursor?: string | undefined;
+                };
+            };
+        } | {
+            output: {
+                sessions: {
+                    instanceId: string;
+                    sessionId: string;
+                    kind: "child" | "default" | "god";
+                    name: string;
+                    parentInstanceId: string | null;
+                    extensionIdentifier: string | null;
+                    createdAt: string;
+                    updatedAt: string;
+                    endedAt: string | null;
+                    endReason: string | null;
+                    live: boolean;
+                    messageCount: number;
+                    trimmedMessageCount: number;
+                    byteSize: number;
+                }[];
+                nextCursor: string | null;
+                hasMore: boolean;
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                query: {
+                    kind?: "child" | "default" | "god" | undefined;
+                    parentInstanceId?: string | undefined;
+                    live?: "false" | "true" | undefined;
+                    limit?: unknown;
+                    cursor?: string | undefined;
+                };
+            };
+        };
+    };
+} & {
+    "/v1/sessions/:instanceId": {
+        $get: {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 404;
+            input: {
+                param: {
+                    instanceId: string;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {
+                param: {
+                    instanceId: string;
+                };
+            };
+        } | {
+            output: {
+                instanceId: string;
+                sessionId: string;
+                kind: "child" | "default" | "god";
+                name: string;
+                parentInstanceId: string | null;
+                extensionIdentifier: string | null;
+                createdAt: string;
+                updatedAt: string;
+                endedAt: string | null;
+                endReason: string | null;
+                live: boolean;
+                messageCount: number;
+                trimmedMessageCount: number;
+                byteSize: number;
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                param: {
+                    instanceId: string;
+                };
+            };
+        };
+    };
+} & {
+    "/v1/sessions/:instanceId/messages": {
+        $get: {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 400;
+            input: {
+                param: {
+                    instanceId: string;
+                };
+            } & {
+                query: {
+                    limit?: unknown;
+                    cursor?: unknown;
+                    includeProviderMetadata?: "false" | "true" | undefined;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 404;
+            input: {
+                param: {
+                    instanceId: string;
+                };
+            } & {
+                query: {
+                    limit?: unknown;
+                    cursor?: unknown;
+                    includeProviderMetadata?: "false" | "true" | undefined;
+                };
+            };
+        } | {
+            output: {
+                error: string;
+                code: string;
+                remediation?: string | undefined;
+            };
+            outputFormat: "json";
+            status: 500;
+            input: {
+                param: {
+                    instanceId: string;
+                };
+            } & {
+                query: {
+                    limit?: unknown;
+                    cursor?: unknown;
+                    includeProviderMetadata?: "false" | "true" | undefined;
+                };
+            };
+        } | {
+            output: {
+                messages: {
+                    id: string;
+                    role: "assistant" | "system" | "user";
+                    metadata?: import("hono/utils/types").JSONValue | undefined;
+                    parts: {
+                        [x: string]: import("hono/utils/types").JSONValue;
+                        type: string;
+                    }[];
+                    seq: number;
+                    persistedAt: string;
+                }[];
+                nextCursor: number | null;
+                hasMore: boolean;
+                trimmedMessageCount: number;
+            };
+            outputFormat: "json";
+            status: 200;
+            input: {
+                param: {
+                    instanceId: string;
+                };
+            } & {
+                query: {
+                    limit?: unknown;
+                    cursor?: unknown;
+                    includeProviderMetadata?: "false" | "true" | undefined;
+                };
+            };
+        };
+    };
 } & {
     "/v1/usage": {
         $get: {
@@ -2786,12 +3001,18 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
     "/v1/introspect/:path": {
         $get: {
             output: {
-                error: string;
-                code: string;
-                remediation?: string | undefined;
+                path: string[];
+                state: {
+                    [x: string]: import("hono/utils/types").JSONValue;
+                } | null;
+                children: {
+                    id: string;
+                    hasState: boolean;
+                    hasChildren: boolean;
+                }[];
             };
             outputFormat: "json";
-            status: 400;
+            status: 200;
             input: {
                 param: {
                     path: string;
@@ -2804,7 +3025,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                 remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 404;
+            status: 400;
             input: {
                 param: {
                     path: string;
@@ -2817,7 +3038,7 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
                 remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 500;
+            status: 404;
             input: {
                 param: {
                     path: string;
@@ -2825,18 +3046,12 @@ export type AdminApi = import("hono/hono-base").HonoBase<any, {
             };
         } | {
             output: {
-                path: string[];
-                state: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | null;
-                children: {
-                    id: string;
-                    hasState: boolean;
-                    hasChildren: boolean;
-                }[];
+                error: string;
+                code: string;
+                remediation?: string | undefined;
             };
             outputFormat: "json";
-            status: 200;
+            status: 500;
             input: {
                 param: {
                     path: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klex/agent-admin-api",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
   "sideEffects": false,
   "description": "Shared types for the Klex Bot Admin API",