@acontext/acontext 0.1.5 → 0.1.7

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export { APIError, TransportError, AcontextError } from './errors';
 export * from './types';
 export * from './resources';
 export * from './agent';
+export * from './integrations';

package/dist/index.js

@@ -33,3 +33,4 @@ Object.defineProperty(exports, "AcontextError", { enumerable: true, get: functio
 __exportStar(require("./types"), exports);
 __exportStar(require("./resources"), exports);
 __exportStar(require("./agent"), exports);
+__exportStar(require("./integrations"), exports);

package/dist/integrations/claude-agent.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Claude Agent SDK integration for Acontext.
+ *
+ * Provides {@link ClaudeAgentStorage} that accepts messages produced by the
+ * Claude Agent SDK `query()` async iterable and persists **only** user and
+ * assistant messages to Acontext in Anthropic format via
+ * `client.sessions.storeMessage(...)`.
+ *
+ * Other message types (system, result, stream_event, etc.) are used only for
+ * session-id resolution and are **never** stored.
+ *
+ * Usage:
+ * ```typescript
+ * import { AcontextClient, ClaudeAgentStorage } from '@acontext/acontext';
+ * import { query } from '@anthropic-ai/claude-agent-sdk';
+ *
+ * const client = new AcontextClient({ apiKey: 'sk-ac-your-api-key' });
+ * const storage = new ClaudeAgentStorage({ client });
+ *
+ * for await (const message of query({ prompt: 'Hello' })) {
+ *   await storage.saveMessage(message);
+ * }
+ * ```
+ */
+/**
+ * Minimal duck-typed interface for the Acontext client.
+ * Both `AcontextClient` and `MockAcontextClient` satisfy this interface.
+ */
+export interface AcontextClientLike {
+    sessions: {
+        create(options?: {
+            useUuid?: string | null;
+            user?: string | null;
+        }): Promise<{
+            id: string;
+        }>;
+        storeMessage(sessionId: string, blob: Record<string, unknown>, options?: {
+            format?: string;
+            meta?: Record<string, unknown> | null;
+        }): Promise<unknown>;
+    };
+}
+/**
+ * Options for constructing a {@link ClaudeAgentStorage} instance.
+ */
+export interface ClaudeAgentStorageOptions {
+    /** An Acontext client instance (or any object satisfying `AcontextClientLike`). */
+    client: AcontextClientLike;
+    /** Acontext session UUID. If omitted, discovered from the Claude stream or auto-created. */
+    sessionId?: string;
+    /** Optional user identifier passed to `sessions.create()`. */
+    user?: string;
+    /** Whether to store ThinkingBlock content as text blocks. Default: false. */
+    includeThinking?: boolean;
+    /**
+     * Optional error callback invoked when `storeMessage` raises.
+     * Receives `(error, blob)` where `blob` is the **converted** Anthropic blob.
+     * If not provided, errors are logged via `console.warn`.
+     */
+    onError?: (error: Error, blob: Record<string, unknown>) => void;
+}
+/**
+ * Try to extract a Claude session id from a non-storable message.
+ *
+ * In the TS Claude Agent SDK, `session_id` is a flat field on system,
+ * result, stream_event, and other non-storable message types.
+ *
+ * Returns `null` when the message does not carry a session id.
+ */
+export declare function getSessionIdFromMessage(msg: Record<string, unknown>): string | null;
+/**
+ * Convert a Claude Agent SDK user message to an Anthropic blob.
+ *
+ * TS reads `msg.message?.content ?? ""` (nested under API message object).
+ *
+ * Returns `null` when the resulting content would be empty (no storable blocks).
+ */
+export declare function claudeUserMessageToAnthropicBlob(msg: Record<string, unknown>): Record<string, unknown> | null;
+/**
+ * Convert a Claude Agent SDK assistant message to an Anthropic blob.
+ *
+ * TS reads `msg.message?.content ?? []` (nested under API message object).
+ *
+ * Returns `{ blob: ... | null, hasThinking: boolean }`.
+ */
+export declare function claudeAssistantMessageToAnthropicBlob(msg: Record<string, unknown>, includeThinking?: boolean): {
+    blob: Record<string, unknown> | null;
+    hasThinking: boolean;
+};
+/**
+ * Storage adapter for the Claude Agent SDK (TypeScript).
+ *
+ * Accepts messages from the `query()` async iterable and persists **only**
+ * user and assistant messages to Acontext in Anthropic format.
+ */
+export declare class ClaudeAgentStorage {
+    private _client;
+    private _sessionId;
+    private _user;
+    private _includeThinking;
+    private _onError;
+    private _sessionEnsured;
+    constructor(options: ClaudeAgentStorageOptions);
+    /**
+     * The current Acontext session id (may be `null` until resolved).
+     */
+    get sessionId(): string | null;
+    /**
+     * Persist a single Claude Agent SDK message to Acontext.
+     *
+     * - User and assistant messages are stored.
+     * - All other message types (system, result, stream_event, etc.) are used
+     *   only for session-id resolution and are **not** stored.
+     * - Replay messages (`isReplay: true`) are skipped to prevent duplicates.
+     * - API errors are caught and either forwarded to `onError` or logged,
+     *   so the caller's `for await` loop is never interrupted.
+     */
+    saveMessage(msg: Record<string, unknown>): Promise<void>;
+    private _tryUpdateSessionId;
+    private _storeUser;
+    private _storeAssistant;
+    private _ensureSession;
+    private _callStore;
+}

package/dist/integrations/claude-agent.js

@@ -0,0 +1,371 @@
+"use strict";
+/**
+ * Claude Agent SDK integration for Acontext.
+ *
+ * Provides {@link ClaudeAgentStorage} that accepts messages produced by the
+ * Claude Agent SDK `query()` async iterable and persists **only** user and
+ * assistant messages to Acontext in Anthropic format via
+ * `client.sessions.storeMessage(...)`.
+ *
+ * Other message types (system, result, stream_event, etc.) are used only for
+ * session-id resolution and are **never** stored.
+ *
+ * Usage:
+ * ```typescript
+ * import { AcontextClient, ClaudeAgentStorage } from '@acontext/acontext';
+ * import { query } from '@anthropic-ai/claude-agent-sdk';
+ *
+ * const client = new AcontextClient({ apiKey: 'sk-ac-your-api-key' });
+ * const storage = new ClaudeAgentStorage({ client });
+ *
+ * for await (const message of query({ prompt: 'Hello' })) {
+ *   await storage.saveMessage(message);
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClaudeAgentStorage = void 0;
+exports.getSessionIdFromMessage = getSessionIdFromMessage;
+exports.claudeUserMessageToAnthropicBlob = claudeUserMessageToAnthropicBlob;
+exports.claudeAssistantMessageToAnthropicBlob = claudeAssistantMessageToAnthropicBlob;
+const errors_1 = require("../errors");
+// ---------------------------------------------------------------------------
+// Helpers – message type detection (TS Claude Agent SDK uses `type` field)
+// ---------------------------------------------------------------------------
+/**
+ * Check if a message is a storable user message.
+ * Skips replay messages (`isReplay === true`) which are TS-only.
+ */
+function isUserMessage(msg) {
+    return msg.type === 'user' && !msg.isReplay;
+}
+/**
+ * Check if a message is a storable assistant message.
+ */
+function isAssistantMessage(msg) {
+    return msg.type === 'assistant';
+}
+/**
+ * Check if a message is a replay user message (TS-only).
+ */
+function isReplayMessage(msg) {
+    return msg.type === 'user' && msg.isReplay === true;
+}
+// ---------------------------------------------------------------------------
+// Helpers – session id extraction
+// ---------------------------------------------------------------------------
+/**
+ * Try to extract a Claude session id from a non-storable message.
+ *
+ * In the TS Claude Agent SDK, `session_id` is a flat field on system,
+ * result, stream_event, and other non-storable message types.
+ *
+ * Returns `null` when the message does not carry a session id.
+ */
+function getSessionIdFromMessage(msg) {
+    // Only extract from non-storable messages
+    if (msg.type === 'user' || msg.type === 'assistant') {
+        return null;
+    }
+    const sid = msg.session_id;
+    return typeof sid === 'string' ? sid : null;
+}
+// ---------------------------------------------------------------------------
+// Helpers – block conversion (Claude SDK → Anthropic blob)
+// ---------------------------------------------------------------------------
+/**
+ * Normalize `ToolResultBlock.content` to a shape accepted by the API.
+ *
+ * - `null`/`undefined` → `""`
+ * - `string` → as-is
+ * - `array` → `[{ type: "text", text: item.text ?? "" }]`
+ * - other → `String(content)`
+ */
+function normalizeToolResultContent(content) {
+    if (content === null || content === undefined) {
+        return '';
+    }
+    if (typeof content === 'string') {
+        return content;
+    }
+    if (Array.isArray(content)) {
+        return content.map((item) => ({
+            type: 'text',
+            text: item?.text ?? '',
+        }));
+    }
+    return String(content);
+}
+/**
+ * Convert a single Claude SDK content block to an Anthropic content block.
+ *
+ * Returns `null` when the block should be skipped.
+ */
+function convertBlock(block, role, includeThinking) {
+    const blockType = block.type;
+    switch (blockType) {
+        case 'thinking': {
+            if (!includeThinking) {
+                return null;
+            }
+            const thinkingText = block.thinking;
+            if (!thinkingText) {
+                return null; // empty thinking text
+            }
+            return { type: 'text', text: thinkingText };
+        }
+        case 'tool_use': {
+            if (role !== 'assistant') {
+                return null; // tool_use only valid in assistant messages
+            }
+            let inputVal = block.input;
+            if (typeof inputVal === 'string') {
+                try {
+                    inputVal = JSON.parse(inputVal);
+                }
+                catch {
+                    inputVal = { raw: inputVal };
+                }
+            }
+            return {
+                type: 'tool_use',
+                id: block.id,
+                name: block.name,
+                input: inputVal,
+            };
+        }
+        case 'tool_result': {
+            if (role !== 'user') {
+                return null; // tool_result only valid in user messages
+            }
+            const result = {
+                type: 'tool_result',
+                tool_use_id: block.tool_use_id,
+                content: normalizeToolResultContent(block.content),
+            };
+            if (block.is_error) {
+                result.is_error = true;
+            }
+            return result;
+        }
+        case 'text': {
+            const text = block.text;
+            if (!text) {
+                return null; // empty text
+            }
+            return { type: 'text', text };
+        }
+        default:
+            // Unknown block type – skip silently
+            return null;
+    }
+}
+/**
+ * Convert Claude SDK content to Anthropic content block array.
+ *
+ * Returns `[blocks, hasThinking]` where `hasThinking` is `true` when at
+ * least one thinking block was successfully included in the output.
+ */
+function convertContentBlocks(content, role, includeThinking) {
+    let hasThinking = false;
+    if (typeof content === 'string') {
+        if (!content) {
+            return [[], false];
+        }
+        return [[{ type: 'text', text: content }], false];
+    }
+    if (!Array.isArray(content)) {
+        return [[], false];
+    }
+    const blocks = [];
+    for (const block of content) {
+        if (typeof block !== 'object' || block === null) {
+            continue; // skip non-object items (matching Python's `if not isinstance(block, dict)`)
+        }
+        const converted = convertBlock(block, role, includeThinking);
+        if (converted !== null) {
+            blocks.push(converted);
+            // Track whether a thinking block was successfully included
+            if (block.type === 'thinking' &&
+                includeThinking) {
+                hasThinking = true;
+            }
+        }
+    }
+    return [blocks, hasThinking];
+}
+// ---------------------------------------------------------------------------
+// Public conversion helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a Claude Agent SDK user message to an Anthropic blob.
+ *
+ * TS reads `msg.message?.content ?? ""` (nested under API message object).
+ *
+ * Returns `null` when the resulting content would be empty (no storable blocks).
+ */
+function claudeUserMessageToAnthropicBlob(msg) {
+    const message = msg.message;
+    const content = message?.content ?? '';
+    const [blocks] = convertContentBlocks(content, 'user', false);
+    if (blocks.length === 0) {
+        return null;
+    }
+    return { role: 'user', content: blocks };
+}
+/**
+ * Convert a Claude Agent SDK assistant message to an Anthropic blob.
+ *
+ * TS reads `msg.message?.content ?? []` (nested under API message object).
+ *
+ * Returns `{ blob: ... | null, hasThinking: boolean }`.
+ */
+function claudeAssistantMessageToAnthropicBlob(msg, includeThinking = false) {
+    const message = msg.message;
+    const content = message?.content ?? [];
+    const [blocks, hasThinking] = convertContentBlocks(content, 'assistant', includeThinking);
+    if (blocks.length === 0) {
+        return { blob: null, hasThinking };
+    }
+    return {
+        blob: { role: 'assistant', content: blocks },
+        hasThinking,
+    };
+}
+// ---------------------------------------------------------------------------
+// ClaudeAgentStorage
+// ---------------------------------------------------------------------------
+/**
+ * Storage adapter for the Claude Agent SDK (TypeScript).
+ *
+ * Accepts messages from the `query()` async iterable and persists **only**
+ * user and assistant messages to Acontext in Anthropic format.
+ */
+class ClaudeAgentStorage {
+    constructor(options) {
+        this._sessionEnsured = false;
+        this._client = options.client;
+        this._sessionId = options.sessionId ?? null;
+        this._user = options.user ?? null;
+        this._includeThinking = options.includeThinking ?? false;
+        this._onError = options.onError ?? null;
+    }
+    // -- properties ----------------------------------------------------------
+    /**
+     * The current Acontext session id (may be `null` until resolved).
+     */
+    get sessionId() {
+        return this._sessionId;
+    }
+    // -- public API ----------------------------------------------------------
+    /**
+     * Persist a single Claude Agent SDK message to Acontext.
+     *
+     * - User and assistant messages are stored.
+     * - All other message types (system, result, stream_event, etc.) are used
+     *   only for session-id resolution and are **not** stored.
+     * - Replay messages (`isReplay: true`) are skipped to prevent duplicates.
+     * - API errors are caught and either forwarded to `onError` or logged,
+     *   so the caller's `for await` loop is never interrupted.
+     */
+    async saveMessage(msg) {
+        // -- non-storable message types: update session_id only ----------------
+        if (msg.type !== 'user' && msg.type !== 'assistant') {
+            this._tryUpdateSessionId(msg);
+            return;
+        }
+        // -- replay user message: skip (TS-only) -------------------------------
+        if (isReplayMessage(msg)) {
+            return;
+        }
+        // -- storable: assistant or user ---------------------------------------
+        if (isAssistantMessage(msg)) {
+            return this._storeAssistant(msg);
+        }
+        if (isUserMessage(msg)) {
+            return this._storeUser(msg);
+        }
+        // Unknown — ignore
+    }
+    // -- internal helpers ----------------------------------------------------
+    _tryUpdateSessionId(msg) {
+        if (this._sessionId !== null) {
+            return;
+        }
+        const sid = getSessionIdFromMessage(msg);
+        if (sid) {
+            this._sessionId = sid;
+            console.debug(`Resolved session_id=${sid} from message`);
+        }
+    }
+    // -- private store methods -----------------------------------------------
+    async _storeUser(msg) {
+        const blob = claudeUserMessageToAnthropicBlob(msg);
+        if (blob === null) {
+            console.debug('UserMessage produced empty content after conversion – skipping.');
+            return;
+        }
+        await this._callStore(blob, null);
+    }
+    async _storeAssistant(msg) {
+        const { blob, hasThinking } = claudeAssistantMessageToAnthropicBlob(msg, this._includeThinking);
+        if (blob === null) {
+            console.debug('AssistantMessage produced empty content after conversion – skipping.');
+            return;
+        }
+        const meta = {};
+        const message = msg.message;
+        const model = message?.model;
+        if (model) {
+            meta.model = model;
+        }
+        if (hasThinking) {
+            meta.has_thinking = true;
+        }
+        const error = msg.error;
+        if (error) {
+            meta.error = error;
+        }
+        await this._callStore(blob, Object.keys(meta).length > 0 ? meta : null);
+    }
+    async _ensureSession() {
+        if (this._sessionEnsured) {
+            return;
+        }
+        try {
+            const session = await this._client.sessions.create({
+                useUuid: this._sessionId ? this._sessionId : null,
+                user: this._user,
+            });
+            this._sessionId = session.id;
+            console.debug(`Created Acontext session ${this._sessionId}`);
+        }
+        catch (err) {
+            if (err instanceof errors_1.APIError && err.statusCode === 409) {
+                console.debug(`Session ${this._sessionId} already exists (409) – continuing.`);
+            }
+            else {
+                throw err;
+            }
+        }
+        this._sessionEnsured = true;
+    }
+    async _callStore(blob, meta) {
+        try {
+            await this._ensureSession();
+            await this._client.sessions.storeMessage(this._sessionId, blob, {
+                format: 'anthropic',
+                meta,
+            });
+        }
+        catch (err) {
+            if (this._onError) {
+                this._onError(err, blob);
+            }
+            else {
+                console.warn(`Failed to store message (session=${this._sessionId}):`, err);
+            }
+        }
+    }
+}
+exports.ClaudeAgentStorage = ClaudeAgentStorage;

package/dist/integrations/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Integration modules for the Acontext TypeScript SDK.
+ */
+export * from './claude-agent';

package/dist/integrations/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Integration modules for the Acontext TypeScript SDK.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./claude-agent"), exports);

package/dist/resources/sessions.d.ts

@@ -68,8 +68,23 @@ export declare class SessionsAPI {
     getSessionSummary(sessionId: string, options?: {
         limit?: number | null;
     }): Promise<string>;
+    /**
+     * Store a message to a session.
+     *
+     * @param sessionId - The UUID of the session.
+     * @param blob - The message blob in Acontext, OpenAI, Anthropic, or Gemini format.
+     * @param options - Options for storing the message.
+     * @param options.format - The format of the message blob ('acontext', 'openai', 'anthropic', or 'gemini').
+     * @param options.meta - Optional user-provided metadata for the message. This metadata is stored
+     *   separately from the message content and can be retrieved via getMessages().metas
+     *   or updated via patchMessageMeta(). Works with all formats.
+     * @param options.fileField - The field name for file upload. Only used when format is 'acontext'.
+     * @param options.file - Optional file upload. Only used when format is 'acontext'.
+     * @returns The created Message object. The msg.meta field contains only user-provided metadata.
+     */
     storeMessage(sessionId: string, blob: MessageBlob, options?: {
         format?: 'acontext' | 'openai' | 'anthropic' | 'gemini';
+        meta?: Record<string, unknown> | null;
         fileField?: string | null;
         file?: FileUpload | null;
     }): Promise<Message>;
@@ -86,8 +101,11 @@ export declare class SessionsAPI {
      * @param options.editStrategies - Optional list of edit strategies to apply before format conversion.
      *   Examples:
      *   - Remove tool results: [{ type: 'remove_tool_result', params: { keep_recent_n_tool_results: 3 } }]
+     *   - Remove large tool results: [{ type: 'remove_tool_result', params: { gt_token: 100 } }]
+     *   - Remove large tool call params: [{ type: 'remove_tool_call_params', params: { gt_token: 100 } }]
      *   - Middle out: [{ type: 'middle_out', params: { token_reduce_to: 5000 } }]
      *   - Token limit: [{ type: 'token_limit', params: { limit_tokens: 20000 } }]
+     *   Throws if editStrategies fail schema validation.
      * @param options.pinEditingStrategiesAtMessage - Message ID to pin editing strategies at.
      *   When provided, strategies are only applied to messages up to and including this message ID,
      *   keeping subsequent messages unchanged. This helps maintain prompt cache stability by
@@ -126,4 +144,55 @@ export declare class SessionsAPI {
      *          pending counts and updated_at timestamp.
      */
     messagesObservingStatus(sessionId: string): Promise<MessageObservingStatus>;
+    /**
+     * Update message metadata using patch semantics.
+     *
+     * Only updates keys present in the meta object. Existing keys not in the request
+     * are preserved. To delete a key, pass null as its value.
+     *
+     * @param sessionId - The UUID of the session.
+     * @param messageId - The UUID of the message.
+     * @param meta - Object of metadata keys to add, update, or delete. Pass null as a value to delete that key.
+     * @returns The complete user metadata after the patch operation.
+     *
+     * @example
+     * // Add/update keys
+     * const updated = await client.sessions.patchMessageMeta(
+     *   sessionId, messageId,
+     *   { status: 'processed', score: 0.95 }
+     * );
+     *
+     * @example
+     * // Delete a key
+     * const updated = await client.sessions.patchMessageMeta(
+     *   sessionId, messageId,
+     *   { old_key: null }  // Deletes "old_key"
+     * );
+     */
+    patchMessageMeta(sessionId: string, messageId: string, meta: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Update session configs using patch semantics.
+     *
+     * Only updates keys present in the configs object. Existing keys not in the request
+     * are preserved. To delete a key, pass null as its value.
+     *
+     * @param sessionId - The UUID of the session.
+     * @param configs - Object of config keys to add, update, or delete. Pass null as a value to delete that key.
+     * @returns The complete configs after the patch operation.
+     *
+     * @example
+     * // Add/update keys
+     * const updated = await client.sessions.patchConfigs(
+     *   sessionId,
+     *   { agent: 'bot2', temperature: 0.8 }
+     * );
+     *
+     * @example
+     * // Delete a key
+     * const updated = await client.sessions.patchConfigs(
+     *   sessionId,
+     *   { old_key: null }  // Deletes "old_key"
+     * );
+     */
+    patchConfigs(sessionId: string, configs: Record<string, unknown>): Promise<Record<string, unknown>>;
 }

package/dist/resources/sessions.js

@@ -139,6 +139,20 @@ class SessionsAPI {
         }
         return parts.join('\n');
     }
+    /**
+     * Store a message to a session.
+     *
+     * @param sessionId - The UUID of the session.
+     * @param blob - The message blob in Acontext, OpenAI, Anthropic, or Gemini format.
+     * @param options - Options for storing the message.
+     * @param options.format - The format of the message blob ('acontext', 'openai', 'anthropic', or 'gemini').
+     * @param options.meta - Optional user-provided metadata for the message. This metadata is stored
+     *   separately from the message content and can be retrieved via getMessages().metas
+     *   or updated via patchMessageMeta(). Works with all formats.
+     * @param options.fileField - The field name for file upload. Only used when format is 'acontext'.
+     * @param options.file - Optional file upload. Only used when format is 'acontext'.
+     * @returns The created Message object. The msg.meta field contains only user-provided metadata.
+     */
     async storeMessage(sessionId, blob, options) {
         const format = options?.format ?? 'openai';
         if (!['acontext', 'openai', 'anthropic', 'gemini'].includes(format)) {
@@ -150,6 +164,9 @@ class SessionsAPI {
         const payload = {
             format,
         };
+        if (options?.meta !== undefined && options?.meta !== null) {
+            payload.meta = options.meta;
+        }
         if (format === 'acontext') {
             if (blob instanceof messages_1.AcontextMessage) {
                 payload.blob = blob.toJSON();
@@ -197,8 +214,11 @@ class SessionsAPI {
      * @param options.editStrategies - Optional list of edit strategies to apply before format conversion.
      *   Examples:
      *   - Remove tool results: [{ type: 'remove_tool_result', params: { keep_recent_n_tool_results: 3 } }]
+     *   - Remove large tool results: [{ type: 'remove_tool_result', params: { gt_token: 100 } }]
+     *   - Remove large tool call params: [{ type: 'remove_tool_call_params', params: { gt_token: 100 } }]
      *   - Middle out: [{ type: 'middle_out', params: { token_reduce_to: 5000 } }]
      *   - Token limit: [{ type: 'token_limit', params: { limit_tokens: 20000 } }]
+     *   Throws if editStrategies fail schema validation.
      * @param options.pinEditingStrategiesAtMessage - Message ID to pin editing strategies at.
      *   When provided, strategies are only applied to messages up to and including this message ID,
      *   keeping subsequent messages unchanged. This helps maintain prompt cache stability by
@@ -218,6 +238,7 @@ class SessionsAPI {
             time_desc: options?.timeDesc ?? true, // Default to true
         }));
         if (options?.editStrategies !== undefined && options?.editStrategies !== null) {
+            types_1.EditStrategySchema.array().parse(options.editStrategies);
             params.edit_strategies = JSON.stringify(options.editStrategies);
         }
         if (options?.pinEditingStrategiesAtMessage !== undefined && options?.pinEditingStrategiesAtMessage !== null) {
@@ -256,5 +277,68 @@ class SessionsAPI {
         const data = await this.requester.request('GET', `/session/${sessionId}/observing_status`);
         return types_1.MessageObservingStatusSchema.parse(data);
     }
+    /**
+     * Update message metadata using patch semantics.
+     *
+     * Only updates keys present in the meta object. Existing keys not in the request
+     * are preserved. To delete a key, pass null as its value.
+     *
+     * @param sessionId - The UUID of the session.
+     * @param messageId - The UUID of the message.
+     * @param meta - Object of metadata keys to add, update, or delete. Pass null as a value to delete that key.
+     * @returns The complete user metadata after the patch operation.
+     *
+     * @example
+     * // Add/update keys
+     * const updated = await client.sessions.patchMessageMeta(
+     *   sessionId, messageId,
+     *   { status: 'processed', score: 0.95 }
+     * );
+     *
+     * @example
+     * // Delete a key
+     * const updated = await client.sessions.patchMessageMeta(
+     *   sessionId, messageId,
+     *   { old_key: null }  // Deletes "old_key"
+     * );
+     */
+    async patchMessageMeta(sessionId, messageId, meta) {
+        const payload = { meta };
+        const data = await this.requester.request('PATCH', `/session/${sessionId}/messages/${messageId}/meta`, {
+            jsonData: payload,
+        });
+        return data.meta ?? {};
+    }
+    /**
+     * Update session configs using patch semantics.
+     *
+     * Only updates keys present in the configs object. Existing keys not in the request
+     * are preserved. To delete a key, pass null as its value.
+     *
+     * @param sessionId - The UUID of the session.
+     * @param configs - Object of config keys to add, update, or delete. Pass null as a value to delete that key.
+     * @returns The complete configs after the patch operation.
+     *
+     * @example
+     * // Add/update keys
+     * const updated = await client.sessions.patchConfigs(
+     *   sessionId,
+     *   { agent: 'bot2', temperature: 0.8 }
+     * );
+     *
+     * @example
+     * // Delete a key
+     * const updated = await client.sessions.patchConfigs(
+     *   sessionId,
+     *   { old_key: null }  // Deletes "old_key"
+     * );
+     */
+    async patchConfigs(sessionId, configs) {
+        const payload = { configs };
+        const data = await this.requester.request('PATCH', `/session/${sessionId}/configs`, {
+            jsonData: payload,
+        });
+        return data.configs ?? {};
+    }
 }
 exports.SessionsAPI = SessionsAPI;

package/dist/types/session.d.ts

@@ -111,6 +111,7 @@ export type PublicURL = z.infer<typeof PublicURLSchema>;
 export declare const GetMessagesOutputSchema: z.ZodObject<{
     items: z.ZodArray<z.ZodUnknown>;
     ids: z.ZodArray<z.ZodString>;
+    metas: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     next_cursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     has_more: z.ZodBoolean;
     this_time_tokens: z.ZodNumber;
@@ -159,6 +160,7 @@ export declare const RemoveToolResultParamsSchema: z.ZodObject<{
     keep_recent_n_tool_results: z.ZodOptional<z.ZodNumber>;
     tool_result_placeholder: z.ZodOptional<z.ZodString>;
     keep_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    gt_token: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type RemoveToolResultParams = z.infer<typeof RemoveToolResultParamsSchema>;
 /**
@@ -167,6 +169,7 @@ export type RemoveToolResultParams = z.infer<typeof RemoveToolResultParamsSchema
 export declare const RemoveToolCallParamsParamsSchema: z.ZodObject<{
     keep_recent_n_tool_calls: z.ZodOptional<z.ZodNumber>;
     keep_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    gt_token: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type RemoveToolCallParamsParams = z.infer<typeof RemoveToolCallParamsParamsSchema>;
 /**
@@ -183,6 +186,7 @@ export declare const RemoveToolCallParamsStrategySchema: z.ZodObject<{
     params: z.ZodObject<{
         keep_recent_n_tool_calls: z.ZodOptional<z.ZodNumber>;
         keep_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        gt_token: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type RemoveToolCallParamsStrategy = z.infer<typeof RemoveToolCallParamsStrategySchema>;
@@ -197,6 +201,7 @@ export declare const RemoveToolResultStrategySchema: z.ZodObject<{
         keep_recent_n_tool_results: z.ZodOptional<z.ZodNumber>;
         tool_result_placeholder: z.ZodOptional<z.ZodString>;
         keep_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        gt_token: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export type RemoveToolResultStrategy = z.infer<typeof RemoveToolResultStrategySchema>;
@@ -252,12 +257,14 @@ export declare const EditStrategySchema: z.ZodUnion<readonly [z.ZodObject<{
         keep_recent_n_tool_results: z.ZodOptional<z.ZodNumber>;
         tool_result_placeholder: z.ZodOptional<z.ZodString>;
         keep_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        gt_token: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"remove_tool_call_params">;
     params: z.ZodObject<{
         keep_recent_n_tool_calls: z.ZodOptional<z.ZodNumber>;
         keep_tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        gt_token: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"token_limit">;

package/dist/types/session.js

@@ -74,6 +74,8 @@ exports.PublicURLSchema = zod_1.z.object({
 exports.GetMessagesOutputSchema = zod_1.z.object({
     items: zod_1.z.array(zod_1.z.unknown()),
     ids: zod_1.z.array(zod_1.z.string()),
+    /** User-provided metadata for each message (same order as items/ids) */
+    metas: zod_1.z.array(zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())).default([]),
     next_cursor: zod_1.z.string().nullable().optional(),
     has_more: zod_1.z.boolean(),
     /** Total token count of the returned messages */
@@ -121,6 +123,11 @@ exports.RemoveToolResultParamsSchema = zod_1.z.object({
      * Tool results from these tools are always kept regardless of keep_recent_n_tool_results.
      */
     keep_tools: zod_1.z.array(zod_1.z.string()).optional(),
+    /**
+     * Only remove tool results whose text has more than this many tokens.
+     * If omitted, all tool results are eligible for removal.
+     */
+    gt_token: zod_1.z.number().int().min(1).optional(),
 });
 /**
  * Parameters for the remove_tool_call_params edit strategy.
@@ -136,6 +143,11 @@ exports.RemoveToolCallParamsParamsSchema = zod_1.z.object({
      * Tool calls for these tools always keep their full parameters regardless of keep_recent_n_tool_calls.
      */
     keep_tools: zod_1.z.array(zod_1.z.string()).optional(),
+    /**
+     * Only remove tool call params whose arguments have more than this many tokens.
+     * If omitted, all tool calls are eligible for removal.
+     */
+    gt_token: zod_1.z.number().int().min(1).optional(),
 });
 /**
  * Edit strategy to remove parameters from old tool-call parts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acontext/acontext",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "TypeScript SDK for the Acontext API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",