anyclaude-sdk 0.1.0 → 0.3.0

package/dist/agent.d.ts

@@ -1,11 +1,11 @@
-import type { AgentDefinition, CanUseTool, CommandExecutor, FileSystem, HookCallback, HookEvent, PermissionMode, SDKMessage, SDKUserMessage } from './types/index.js';
+import type { AgentDefinition, CanUseTool, CommandExecutor, ContentBlockParam, FileSystem, HookCallback, HookEvent, PermissionMode, SDKMessage, SDKUserMessage } from './types/index.js';
 import type { FileReadLimits, Tool } from './tools/types.js';
 import { type McpServers, type McpProxy } from './mcp/index.js';
 import type { SlashCommand } from './commands/index.js';
 import { BackgroundTaskManager } from './background/index.js';
 import { Mailbox, TaskBoard } from './team/index.js';
 import type { MemoryStore } from './memory/index.js';
-import type { SessionStore } from './session/index.js';
+import type { SessionStoreLike } from './session/index.js';
 import { type Settings } from './settings/index.js';
 import { type Skill } from './skills/index.js';
 export type Workspace = FileSystem & CommandExecutor;
@@ -27,6 +27,23 @@ export interface AgentOptions {
     /** Denylist of tool names, applied after allowedTools. */
     disallowedTools?: string[];
     maxTurns?: number;
+    /** Wall-clock budget (ms). At a turn boundary past this, the loop pauses: it
+     *  persists to sessionStore and emits a `paused` system message instead of
+     *  continuing — for spanning serverless function time limits ("survivor"). */
+    maxDurationMs?: number;
+    /** Resume + CONTINUE the tool loop on the stored transcript without a new user
+     *  message (pairs with `resume`). Used to continue after a `paused` boundary. */
+    continueRun?: boolean;
+    /** Tool names executed by the HOST/client, not the server. When the agent calls
+     *  one, the loop emits a `client_tool_request` + pauses; the client runs it and
+     *  resumes (continueRun) with `clientToolResults`. (e.g. bash on a browser WebContainer.) */
+    clientTools?: string[];
+    /** Results for client-tool calls, injected into the transcript before continuing. */
+    clientToolResults?: Array<{
+        tool_use_id: string;
+        content: string | ContentBlockParam[];
+        is_error?: boolean;
+    }>;
     cwd?: string;
     sessionId?: string;
     abortController?: AbortController;
@@ -76,7 +93,7 @@ export interface AgentOptions {
     /** This agent's name/label for messaging (default 'coordinator'). */
     agentName?: string;
     /** Persist the transcript to this store (keyed by sessionId) for resume. */
-    sessionStore?: SessionStore;
+    sessionStore?: SessionStoreLike;
     /** Load the stored transcript for sessionId before the first turn. */
     resume?: boolean;
     /** Auto-compact the transcript when it approaches the context limit. */
@@ -95,6 +112,16 @@ export interface AgentOptions {
     };
     /** Prompt callback for 'ask' decisions; if absent, default mode allows / dontAsk denies. */
     onPermissionAsk?: (toolName: string, input: Record<string, unknown>) => Promise<boolean>;
+    /** Surfaces `ask_user_question` to the host UI. When set, the tool is registered. */
+    onAskUser?: (q: {
+        question: string;
+        header?: string;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+        multiSelect?: boolean;
+    }) => Promise<string | string[]>;
     /** Load + apply `.claude/settings.json` (project/local cascade) under explicit options. true, or a Settings object. */
     settings?: boolean | Settings;
     /** Load `.claude/skills/*.md` as slash commands + skill registry. true, or a Skill[] array. */

package/dist/agent.js

@@ -10,6 +10,7 @@
 //   7. Repeat until no tool calls or max turns reached
 import { ALL_CLAUDE_CODE_TOOLS, toolByName, toolDefs } from './tools/index.js';
 import { task as taskTool } from './tools/task.js';
+import { askUserQuestion } from './tools/ask_user.js';
 import { loadMcpServers } from './mcp/index.js';
 import { runSlashCommand } from './commands/index.js';
 import { BackgroundTaskManager, BACKGROUND_TOOLS } from './background/index.js';
@@ -201,6 +202,7 @@ export async function* runAgent(options) {
         ? options.backgroundManager ?? new BackgroundTaskManager()
         : undefined;
     const messageQueue = options.messageQueue;
+    const clientTools = new Set(options.clientTools ?? []);
     // Teammates: a shared Mailbox + TaskBoard (reused from the parent when this
     // is a sub-agent) + team tools + coordinator prompt.
     const teamEnabled = options.team === true;
@@ -214,6 +216,9 @@ export async function* runAgent(options) {
         const present = new Set(localTools.map((t) => t.def.function.name));
         localTools = [...localTools, ...BACKGROUND_TOOLS.filter((t) => !present.has(t.def.function.name))];
     }
+    if (options.onAskUser && !localTools.some((t) => t.def.function.name === 'ask_user_question')) {
+        localTools = [...localTools, askUserQuestion];
+    }
     if (teamEnabled) {
         const present = new Set(localTools.map((t) => t.def.function.name));
         const teamSet = subagentsEnabled ? [...TEAM_TOOLS, ...TEAM_DISPATCH_TOOLS] : TEAM_TOOLS;
@@ -267,6 +272,7 @@ export async function* runAgent(options) {
         signal,
         store,
         limits,
+        askUser: options.onAskUser,
         background,
         mailbox,
         board,
@@ -308,6 +314,7 @@ export async function* runAgent(options) {
                 tools: subTools,
                 model: def?.model ?? model,
                 systemPrompt: subSystem,
+                onAskUser: options.onAskUser,
                 maxTurns,
                 cwd,
                 abortController: childController,
@@ -403,6 +410,10 @@ export async function* runAgent(options) {
     });
     const startedAt = Date.now();
     const sessionUsage = emptyUsage();
+    const maxDurationMs = options.maxDurationMs;
+    let paused = false;
+    // Pending client-executed tool calls for the current turn (emitted on pause).
+    let clientRequests = [];
     // Resume: seed the transcript from a prior session before the first turn.
     if (options.resume && options.sessionStore) {
         const prior = await options.sessionStore.load(sessionId);
@@ -412,12 +423,16 @@ export async function* runAgent(options) {
             history.splice(0, history.length, ...prior);
         }
     }
-    for await (const userMsg of prompt) {
+    // continueRun: prepend a sentinel turn so the loop continues the stored
+    // transcript with no new user message (used after a `paused` boundary).
+    const promptSrc = options.continueRun ? withContinueSentinel(prompt) : prompt;
+    for await (const userMsg of promptSrc) {
         if (signal?.aborted)
             break;
+        const isContinue = userMsg.__continue === true;
         const content = userMsg.message.content;
         // Slash-command interception: a string user turn beginning with '/'.
-        if (typeof content === 'string' && content.trim().startsWith('/')) {
+        if (!isContinue && typeof content === 'string' && content.trim().startsWith('/')) {
             const outcome = await runSlashCommand(content, {
                 history,
                 tools: defs.map((d) => ({
@@ -479,7 +494,7 @@ export async function* runAgent(options) {
                 history.push({ role: 'user', content }); // unknown command → normal prompt
             }
         }
-        else {
+        else if (!isContinue) {
             history.push({ role: 'user', content });
             const pre = await runHooks('UserPromptSubmit', {
                 hook_event_name: 'UserPromptSubmit',
@@ -489,6 +504,28 @@ export async function* runAgent(options) {
             if (extra)
                 history.push({ role: 'user', content: extra });
         }
+        // Continue after a client-tool pause: inject the host-executed results into
+        // the transcript so the (paused) assistant tool_use calls are now resolved.
+        if (isContinue && options.clientToolResults?.length) {
+            const blocks = [];
+            for (const r of options.clientToolResults) {
+                history.push({
+                    role: 'tool',
+                    tool_call_id: r.tool_use_id,
+                    content: typeof r.content === 'string' ? r.content : JSON.stringify(r.content),
+                });
+                blocks.push({ type: 'tool_result', tool_use_id: r.tool_use_id, content: r.content, is_error: r.is_error || undefined });
+            }
+            yield {
+                type: 'user',
+                message: { role: 'user', content: blocks },
+                parent_tool_use_id: null,
+                isSynthetic: true,
+                timestamp: new Date().toISOString(),
+                uuid: uuid(),
+                session_id: sessionId,
+            };
+        }
         let turns = 0;
         let lastText = '';
         let resultModel = model ?? 'unknown';
@@ -505,6 +542,11 @@ export async function* runAgent(options) {
                 hitMaxTurns = true;
                 break;
             }
+            // Survivor: pause at this turn boundary if we're past the time budget.
+            if (maxDurationMs != null && Date.now() - startedAt >= maxDurationMs) {
+                paused = true;
+                break;
+            }
             turns++;
             // Message queue: deliver one interjected user message per turn boundary.
             // (Messages enqueued via options.messageQueue while this loop runs.)
@@ -648,12 +690,19 @@ export async function* runAgent(options) {
             }
             // Execute tool calls (permission gate + hooks around each).
             const toolResultBlocks = [];
+            clientRequests = [];
             const turnMedia = [];
             for (const call of calls) {
                 if (signal?.aborted)
                     break;
                 const name = call.function.name;
                 let input = safeParse(call.function.arguments);
+                // Client-executed tool: don't run it here — record it; we pause after this
+                // turn's server tools and let the host execute + resume with the result.
+                if (clientTools.has(name)) {
+                    clientRequests.push({ tool_use_id: call.id, name, input });
+                    continue;
+                }
                 const tool = byName.get(name);
                 let content = '';
                 let isError = false;
@@ -818,15 +867,23 @@ export async function* runAgent(options) {
                     ],
                 });
             }
-            yield {
-                type: 'user',
-                message: { role: 'user', content: toolResultBlocks },
-                parent_tool_use_id: null,
-                isSynthetic: true,
-                timestamp: new Date().toISOString(),
-                uuid: uuid(),
-                session_id: sessionId,
-            };
+            if (toolResultBlocks.length) {
+                yield {
+                    type: 'user',
+                    message: { role: 'user', content: toolResultBlocks },
+                    parent_tool_use_id: null,
+                    isSynthetic: true,
+                    timestamp: new Date().toISOString(),
+                    uuid: uuid(),
+                    session_id: sessionId,
+                };
+            }
+            // Client-executed tools were requested this turn → pause; the host runs
+            // them and resumes (continueRun + clientToolResults).
+            if (clientRequests.length) {
+                paused = true;
+                break;
+            }
         }
         await runHooks('Stop', {
             hook_event_name: 'Stop',
@@ -891,7 +948,39 @@ export async function* runAgent(options) {
                 /* persistence is best-effort */
             }
         }
+        // Survivor / client-tools: paused at a boundary. Transcript persisted above.
+        // Emit any client-tool requests for the host to execute, then signal the
+        // client to continue in a fresh invocation (resume + continueRun [+ results]).
+        if (paused) {
+            for (const req of clientRequests) {
+                yield {
+                    type: 'system',
+                    subtype: 'client_tool_request',
+                    request: req,
+                    session_id: sessionId,
+                    uuid: uuid(),
+                };
+            }
+            yield {
+                type: 'system',
+                subtype: 'paused',
+                reason: clientRequests.length ? 'client_tool' : 'time_budget',
+                session_id: sessionId,
+                uuid: uuid(),
+            };
+            break;
+        }
     }
     // The prompt stream is exhausted — the session is ending.
     await runHooks('SessionEnd', { hook_event_name: 'SessionEnd', reason: 'prompt_input_exit' });
 }
+/** Prepend a continue-sentinel turn so the loop continues a resumed transcript. */
+async function* withContinueSentinel(prompt) {
+    yield {
+        type: 'user',
+        message: { role: 'user', content: '' },
+        parent_tool_use_id: null,
+        __continue: true,
+    };
+    yield* prompt;
+}

package/dist/commands/builtins.js

@@ -123,7 +123,7 @@ const sessions = {
     name: 'sessions',
     description: 'List saved sessions',
     async run(_args, ctx) {
-        if (!ctx.sessionStore)
+        if (!ctx.sessionStore?.list)
             return { systemText: 'No session store configured.' };
         const list = await ctx.sessionStore.list();
         if (!list.length)
@@ -153,7 +153,7 @@ const rename = {
     description: 'Rename the current session',
     argumentHint: '<title>',
     async run(args, ctx) {
-        if (!ctx.sessionStore || !ctx.sessionId)
+        if (!ctx.sessionStore?.rename || !ctx.sessionId)
             return { systemText: 'No active session to rename.' };
         const title = args.trim();
         if (!title)

package/dist/commands/types.d.ts

@@ -36,17 +36,7 @@ export interface SlashCommandContext {
     /** Current session id. */
     sessionId?: string;
     /** Session store, for /sessions, /resume, /rename. */
-    sessionStore?: {
-        list(): Promise<Array<{
-            sessionId: string;
-            title?: string;
-            updatedAt: number;
-            messageCount: number;
-        }>>;
-        load(id: string): Promise<ChatMsg[] | null>;
-        rename(id: string, title: string): Promise<void>;
-        remove(id: string): Promise<void>;
-    };
+    sessionStore?: import('../session/types.js').SessionStoreLike;
     /** Paths the model has read this session, for /files. */
     readFiles?: Set<string>;
     /** Configured sub-agents, for /agents. */

package/dist/query.d.ts

@@ -2,7 +2,7 @@ import type { AgentDefinition, CanUseTool, HookCallback, HookEvent, LLMClient, P
 import type { FileReadLimits, Tool } from './tools/types.js';
 import type { McpServers, McpProxy } from './mcp/index.js';
 import type { SlashCommand } from './commands/index.js';
-import type { SessionStore } from './session/index.js';
+import type { SessionStoreLike } from './session/index.js';
 import type { MemoryStore } from './memory/index.js';
 import { type Workspace } from './agent.js';
 export interface QueryOptions {
@@ -22,6 +22,19 @@ export interface QueryOptions {
     allowedTools?: string[];
     disallowedTools?: string[];
     maxTurns?: number;
+    /** Wall-clock budget (ms): pause at a turn boundary past this + emit `paused` (survivor). */
+    maxDurationMs?: number;
+    /** Resume + continue the tool loop with no new user message (after a `paused` boundary). */
+    continueRun?: boolean;
+    /** Tool names the HOST/client executes (e.g. bash on a browser WebContainer). The agent
+     *  emits a `client_tool_request` + pauses; the client runs it and resumes with results. */
+    clientTools?: string[];
+    /** Results for client-tool calls, injected before continuing (with continueRun). */
+    clientToolResults?: Array<{
+        tool_use_id: string;
+        content: string | import('./types/index.js').ContentBlockParam[];
+        is_error?: boolean;
+    }>;
     cwd?: string;
     sessionId?: string;
     abortController?: AbortController;
@@ -59,7 +72,7 @@ export interface QueryOptions {
     /** This agent's name/label for messaging (default 'coordinator'). */
     agentName?: string;
     /** Persist the transcript to this store (keyed by sessionId) for resume. */
-    sessionStore?: SessionStore;
+    sessionStore?: SessionStoreLike;
     /** Load the stored transcript for sessionId before the first turn. */
     resume?: boolean;
     /** Auto-compact the transcript when it nears the context limit. */
@@ -78,6 +91,16 @@ export interface QueryOptions {
     };
     /** Prompt callback for 'ask' permission decisions. */
     onPermissionAsk?: (toolName: string, input: Record<string, unknown>) => Promise<boolean>;
+    /** Handler for the `ask_user_question` tool. When set, the tool is registered. */
+    onAskUser?: (q: {
+        question: string;
+        header?: string;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+        multiSelect?: boolean;
+    }) => Promise<string | string[]>;
     /** Load `.claude/settings.json` (project/local cascade), or pass a Settings object. */
     settings?: boolean | import('./settings/index.js').Settings;
     /** Load `.claude/skills/*.md` as slash commands + a skill registry, or pass a Skill[]. */

package/dist/query.js

@@ -20,6 +20,10 @@ export function query(options) {
         allowedTools: options.allowedTools,
         disallowedTools: options.disallowedTools,
         maxTurns: options.maxTurns,
+        maxDurationMs: options.maxDurationMs,
+        continueRun: options.continueRun,
+        clientTools: options.clientTools,
+        clientToolResults: options.clientToolResults,
         cwd: options.cwd,
         sessionId: options.sessionId,
         abortController,
@@ -48,6 +52,7 @@ export function query(options) {
         memory: options.memory,
         permissionRules: options.permissionRules,
         onPermissionAsk: options.onPermissionAsk,
+        onAskUser: options.onAskUser,
         settings: options.settings,
         skills: options.skills,
     });

package/dist/session/adapters/kv.d.ts

@@ -0,0 +1,25 @@
+import type { ChatMsg } from '../../types/index.js';
+import type { SessionMeta, SessionStoreLike, StoredSession } from '../types.js';
+/** Structural view of a KV client (Vercel KV / Upstash Redis / Cloudflare KV). */
+export interface KVClientLike {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: string): Promise<unknown>;
+    del?(key: string): Promise<unknown>;
+    /** Glob-style key listing (e.g. Upstash/ioredis `keys('bcs:session:*')`). */
+    keys?(pattern: string): Promise<string[]>;
+}
+export declare class KVSessionStore implements SessionStoreLike {
+    private readonly kv;
+    private readonly prefix;
+    constructor(kv: KVClientLike, prefix?: string);
+    private key;
+    get(sessionId: string): Promise<StoredSession | null>;
+    load(sessionId: string): Promise<ChatMsg[] | null>;
+    save(sessionId: string, transcript: ChatMsg[], meta?: {
+        title?: string;
+        model?: string;
+    }): Promise<void>;
+    list(): Promise<SessionMeta[]>;
+    rename(sessionId: string, title: string): Promise<void>;
+    remove(sessionId: string): Promise<void>;
+}

package/dist/session/adapters/kv.js

@@ -0,0 +1,55 @@
+function parse(raw) {
+    if (raw == null)
+        return null;
+    const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    return obj && Array.isArray(obj.transcript) ? obj : null;
+}
+export class KVSessionStore {
+    constructor(kv, prefix = 'bcs:session:') {
+        this.kv = kv;
+        this.prefix = prefix;
+    }
+    key(id) {
+        return this.prefix + id;
+    }
+    async get(sessionId) {
+        return parse(await this.kv.get(this.key(sessionId)));
+    }
+    async load(sessionId) {
+        const s = await this.get(sessionId);
+        return s ? s.transcript : null;
+    }
+    async save(sessionId, transcript, meta = {}) {
+        const now = Date.now();
+        const existing = await this.get(sessionId);
+        const row = {
+            sessionId,
+            title: meta.title ?? existing?.title,
+            model: meta.model ?? existing?.model,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            messageCount: transcript.length,
+            transcript,
+        };
+        await this.kv.set(this.key(sessionId), JSON.stringify(row));
+    }
+    async list() {
+        if (!this.kv.keys)
+            return [];
+        const keys = await this.kv.keys(this.prefix + '*');
+        const rows = await Promise.all(keys.map((k) => this.kv.get(k).then(parse)));
+        return rows
+            .filter((s) => !!s)
+            .map(({ transcript: _t, ...meta }) => meta)
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    async rename(sessionId, title) {
+        const s = await this.get(sessionId);
+        if (!s)
+            return;
+        await this.kv.set(this.key(sessionId), JSON.stringify({ ...s, title, updatedAt: Date.now() }));
+    }
+    async remove(sessionId) {
+        await this.kv.del?.(this.key(sessionId));
+    }
+}

package/dist/session/adapters/memory.d.ts

@@ -0,0 +1,14 @@
+import type { ChatMsg } from '../../types/index.js';
+import type { SessionMeta, SessionStoreLike, StoredSession } from '../types.js';
+export declare class MemorySessionStore implements SessionStoreLike {
+    private readonly data;
+    load(sessionId: string): Promise<ChatMsg[] | null>;
+    save(sessionId: string, transcript: ChatMsg[], meta?: {
+        title?: string;
+        model?: string;
+    }): Promise<void>;
+    get(sessionId: string): Promise<StoredSession | null>;
+    list(): Promise<SessionMeta[]>;
+    rename(sessionId: string, title: string): Promise<void>;
+    remove(sessionId: string): Promise<void>;
+}

package/dist/session/adapters/memory.js

@@ -0,0 +1,37 @@
+export class MemorySessionStore {
+    constructor() {
+        this.data = new Map();
+    }
+    async load(sessionId) {
+        return this.data.get(sessionId)?.transcript ?? null;
+    }
+    async save(sessionId, transcript, meta) {
+        const now = Date.now();
+        const prev = this.data.get(sessionId);
+        this.data.set(sessionId, {
+            sessionId,
+            title: meta?.title ?? prev?.title,
+            model: meta?.model ?? prev?.model,
+            createdAt: prev?.createdAt ?? now,
+            updatedAt: now,
+            messageCount: transcript.length,
+            transcript: transcript.slice(),
+        });
+    }
+    async get(sessionId) {
+        return this.data.get(sessionId) ?? null;
+    }
+    async list() {
+        return [...this.data.values()]
+            .map(({ transcript: _t, ...meta }) => meta)
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    async rename(sessionId, title) {
+        const s = this.data.get(sessionId);
+        if (s)
+            s.title = title;
+    }
+    async remove(sessionId) {
+        this.data.delete(sessionId);
+    }
+}

package/dist/session/adapters/postgres.d.ts

@@ -0,0 +1,25 @@
+import type { ChatMsg } from '../../types/index.js';
+import type { SessionMeta, SessionStoreLike, StoredSession } from '../types.js';
+/** Structural Postgres query runner (node-postgres Pool/Client compatible). */
+export interface PgRunnerLike {
+    query(text: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+export declare const POSTGRES_SCHEMA: string;
+export declare class PostgresSessionStore implements SessionStoreLike {
+    private readonly pg;
+    private readonly table;
+    constructor(pg: PgRunnerLike, table?: string);
+    /** Create the table if it doesn't exist (optional convenience). */
+    migrate(): Promise<void>;
+    load(sessionId: string): Promise<ChatMsg[] | null>;
+    get(sessionId: string): Promise<StoredSession | null>;
+    save(sessionId: string, transcript: ChatMsg[], meta?: {
+        title?: string;
+        model?: string;
+    }): Promise<void>;
+    list(): Promise<SessionMeta[]>;
+    rename(sessionId: string, title: string): Promise<void>;
+    remove(sessionId: string): Promise<void>;
+}

package/dist/session/adapters/postgres.js

@@ -0,0 +1,72 @@
+export const POSTGRES_SCHEMA = `
+CREATE TABLE IF NOT EXISTS sessions (
+  id            text PRIMARY KEY,
+  title         text,
+  model         text,
+  created_at    bigint NOT NULL,
+  updated_at    bigint NOT NULL,
+  message_count int NOT NULL DEFAULT 0,
+  transcript    jsonb NOT NULL DEFAULT '[]'::jsonb
+);
+CREATE INDEX IF NOT EXISTS sessions_updated_at_idx ON sessions (updated_at DESC);
+`.trim();
+function toMeta(r) {
+    return {
+        sessionId: String(r.id),
+        title: r.title ?? undefined,
+        model: r.model ?? undefined,
+        createdAt: Number(r.created_at),
+        updatedAt: Number(r.updated_at),
+        messageCount: Number(r.message_count),
+    };
+}
+export class PostgresSessionStore {
+    constructor(pg, table = 'sessions') {
+        this.pg = pg;
+        this.table = table;
+    }
+    /** Create the table if it doesn't exist (optional convenience). */
+    async migrate() {
+        await this.pg.query(POSTGRES_SCHEMA);
+    }
+    async load(sessionId) {
+        const { rows } = await this.pg.query(`SELECT transcript FROM ${this.table} WHERE id = $1`, [sessionId]);
+        if (!rows.length)
+            return null;
+        const t = rows[0].transcript;
+        return (typeof t === 'string' ? JSON.parse(t) : t);
+    }
+    async get(sessionId) {
+        const { rows } = await this.pg.query(`SELECT * FROM ${this.table} WHERE id = $1`, [sessionId]);
+        if (!rows.length)
+            return null;
+        const r = rows[0];
+        const t = r.transcript;
+        return { ...toMeta(r), transcript: (typeof t === 'string' ? JSON.parse(t) : t) };
+    }
+    async save(sessionId, transcript, meta = {}) {
+        const now = Date.now();
+        await this.pg.query(`INSERT INTO ${this.table} (id, title, model, created_at, updated_at, message_count, transcript)
+       VALUES ($1, $2, $3, $4, $4, $5, $6::jsonb)
+       ON CONFLICT (id) DO UPDATE SET
+         title = COALESCE(EXCLUDED.title, ${this.table}.title),
+         model = COALESCE(EXCLUDED.model, ${this.table}.model),
+         updated_at = EXCLUDED.updated_at,
+         message_count = EXCLUDED.message_count,
+         transcript = EXCLUDED.transcript`, [sessionId, meta.title ?? null, meta.model ?? null, now, transcript.length, JSON.stringify(transcript)]);
+    }
+    async list() {
+        const { rows } = await this.pg.query(`SELECT id, title, model, created_at, updated_at, message_count FROM ${this.table} ORDER BY updated_at DESC`);
+        return rows.map(toMeta);
+    }
+    async rename(sessionId, title) {
+        await this.pg.query(`UPDATE ${this.table} SET title = $2, updated_at = $3 WHERE id = $1`, [
+            sessionId,
+            title,
+            Date.now(),
+        ]);
+    }
+    async remove(sessionId) {
+        await this.pg.query(`DELETE FROM ${this.table} WHERE id = $1`, [sessionId]);
+    }
+}

package/dist/session/adapters/redis.d.ts

@@ -0,0 +1,24 @@
+import type { ChatMsg } from '../../types/index.js';
+import type { SessionMeta, SessionStoreLike, StoredSession } from '../types.js';
+/** Structural view of a Redis client (ioredis / node-redis). */
+export interface RedisClientLike {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    del(key: string): Promise<unknown>;
+    keys(pattern: string): Promise<string[]>;
+}
+export declare class RedisSessionStore implements SessionStoreLike {
+    private readonly redis;
+    private readonly prefix;
+    constructor(redis: RedisClientLike, prefix?: string);
+    private key;
+    get(sessionId: string): Promise<StoredSession | null>;
+    load(sessionId: string): Promise<ChatMsg[] | null>;
+    save(sessionId: string, transcript: ChatMsg[], meta?: {
+        title?: string;
+        model?: string;
+    }): Promise<void>;
+    list(): Promise<SessionMeta[]>;
+    rename(sessionId: string, title: string): Promise<void>;
+    remove(sessionId: string): Promise<void>;
+}

package/dist/session/adapters/redis.js

@@ -0,0 +1,52 @@
+export class RedisSessionStore {
+    constructor(redis, prefix = 'bcs:session:') {
+        this.redis = redis;
+        this.prefix = prefix;
+    }
+    key(id) {
+        return this.prefix + id;
+    }
+    async get(sessionId) {
+        const raw = await this.redis.get(this.key(sessionId));
+        if (!raw)
+            return null;
+        const obj = JSON.parse(raw);
+        return Array.isArray(obj.transcript) ? obj : null;
+    }
+    async load(sessionId) {
+        const s = await this.get(sessionId);
+        return s ? s.transcript : null;
+    }
+    async save(sessionId, transcript, meta = {}) {
+        const now = Date.now();
+        const existing = await this.get(sessionId);
+        const row = {
+            sessionId,
+            title: meta.title ?? existing?.title,
+            model: meta.model ?? existing?.model,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+            messageCount: transcript.length,
+            transcript,
+        };
+        await this.redis.set(this.key(sessionId), JSON.stringify(row));
+    }
+    async list() {
+        const keys = await this.redis.keys(this.prefix + '*');
+        const raws = await Promise.all(keys.map((k) => this.redis.get(k)));
+        return raws
+            .filter((r) => !!r)
+            .map((r) => JSON.parse(r))
+            .map(({ transcript: _t, ...meta }) => meta)
+            .sort((a, b) => b.updatedAt - a.updatedAt);
+    }
+    async rename(sessionId, title) {
+        const s = await this.get(sessionId);
+        if (!s)
+            return;
+        await this.redis.set(this.key(sessionId), JSON.stringify({ ...s, title, updatedAt: Date.now() }));
+    }
+    async remove(sessionId) {
+        await this.redis.del(this.key(sessionId));
+    }
+}

package/dist/session/adapters/supabase.d.ts

@@ -0,0 +1,51 @@
+import type { ChatMsg } from '../../types/index.js';
+import type { SessionMeta, SessionStoreLike, StoredSession } from '../types.js';
+export declare const SUPABASE_SCHEMA: string;
+interface SessionRow {
+    id: string;
+    title: string | null;
+    model: string | null;
+    created_at: number;
+    updated_at: number;
+    message_count: number;
+    transcript: ChatMsg[];
+}
+interface SupaResp<T> {
+    data: T | null;
+    error: {
+        message: string;
+    } | null;
+}
+interface SupaQuery<T> extends PromiseLike<SupaResp<T[]>> {
+    select(columns?: string): SupaQuery<T>;
+    eq(column: string, value: unknown): SupaQuery<T>;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): SupaQuery<T>;
+    single(): PromiseLike<SupaResp<T>>;
+}
+interface SupaTable<T> {
+    select(columns?: string): SupaQuery<T>;
+    upsert(values: Partial<T> | Partial<T>[]): PromiseLike<SupaResp<T[]>>;
+    update(values: Partial<T>): SupaQuery<T>;
+    delete(): SupaQuery<T>;
+}
+/** Structural view of a @supabase/supabase-js client. */
+export interface SupabaseClientLike {
+    from(relation: string): SupaTable<SessionRow>;
+}
+export declare class SupabaseSessionStore implements SessionStoreLike {
+    private readonly supabase;
+    private readonly table;
+    constructor(supabase: SupabaseClientLike, table?: string);
+    get(sessionId: string): Promise<StoredSession | null>;
+    load(sessionId: string): Promise<ChatMsg[] | null>;
+    save(sessionId: string, transcript: ChatMsg[], meta?: {
+        title?: string;
+        model?: string;
+    }): Promise<void>;
+    list(): Promise<SessionMeta[]>;
+    rename(sessionId: string, title: string): Promise<void>;
+    remove(sessionId: string): Promise<void>;
+}
+export {};

package/dist/session/adapters/supabase.js

@@ -0,0 +1,65 @@
+export const SUPABASE_SCHEMA = `
+create table if not exists sessions (
+  id            text primary key,
+  title         text,
+  model         text,
+  created_at    bigint not null,
+  updated_at    bigint not null,
+  message_count int not null default 0,
+  transcript    jsonb not null default '[]'::jsonb
+);
+create index if not exists sessions_updated_at_idx on sessions (updated_at desc);
+`.trim();
+const toMeta = (r) => ({
+    sessionId: r.id,
+    title: r.title ?? undefined,
+    model: r.model ?? undefined,
+    createdAt: Number(r.created_at),
+    updatedAt: Number(r.updated_at),
+    messageCount: Number(r.message_count),
+});
+export class SupabaseSessionStore {
+    constructor(supabase, table = 'sessions') {
+        this.supabase = supabase;
+        this.table = table;
+    }
+    async get(sessionId) {
+        const { data } = await this.supabase.from(this.table).select('*').eq('id', sessionId).single();
+        if (!data)
+            return null;
+        return { ...toMeta(data), transcript: Array.isArray(data.transcript) ? data.transcript : [] };
+    }
+    async load(sessionId) {
+        const s = await this.get(sessionId);
+        return s ? s.transcript : null;
+    }
+    async save(sessionId, transcript, meta = {}) {
+        const now = Date.now();
+        const existing = await this.get(sessionId);
+        const row = {
+            id: sessionId,
+            title: meta.title ?? existing?.title ?? null,
+            model: meta.model ?? existing?.model ?? null,
+            created_at: existing?.createdAt ?? now,
+            updated_at: now,
+            message_count: transcript.length,
+            transcript,
+        };
+        const { error } = await this.supabase.from(this.table).upsert(row);
+        if (error)
+            throw new Error('SupabaseSessionStore.save: ' + error.message);
+    }
+    async list() {
+        const { data } = await this.supabase
+            .from(this.table)
+            .select('id,title,model,created_at,updated_at,message_count')
+            .order('updated_at', { ascending: false });
+        return (data ?? []).map(toMeta);
+    }
+    async rename(sessionId, title) {
+        await this.supabase.from(this.table).update({ title, updated_at: Date.now() }).eq('id', sessionId);
+    }
+    async remove(sessionId) {
+        await this.supabase.from(this.table).delete().eq('id', sessionId);
+    }
+}

package/dist/session/index.d.ts

@@ -1,2 +1,7 @@
 export { SessionStore } from './store.js';
-export type { SessionMeta, StoredSession, SessionStoreOptions } from './types.js';
+export type { SessionMeta, StoredSession, SessionStoreOptions, SessionStoreLike } from './types.js';
+export { MemorySessionStore } from './adapters/memory.js';
+export { KVSessionStore, type KVClientLike } from './adapters/kv.js';
+export { RedisSessionStore, type RedisClientLike } from './adapters/redis.js';
+export { PostgresSessionStore, POSTGRES_SCHEMA, type PgRunnerLike } from './adapters/postgres.js';
+export { SupabaseSessionStore, SUPABASE_SCHEMA, type SupabaseClientLike } from './adapters/supabase.js';

package/dist/session/index.js

@@ -4,3 +4,10 @@
 // IndexedDB (via Dexie), enabling listSessions / resume / fork / rename across
 // reloads.
 export { SessionStore } from './store.js';
+// Pluggable backends for the survivor / serverless persistence (structural
+// clients — the DB packages stay optional).
+export { MemorySessionStore } from './adapters/memory.js';
+export { KVSessionStore } from './adapters/kv.js';
+export { RedisSessionStore } from './adapters/redis.js';
+export { PostgresSessionStore, POSTGRES_SCHEMA } from './adapters/postgres.js';
+export { SupabaseSessionStore, SUPABASE_SCHEMA } from './adapters/supabase.js';

package/dist/session/store.d.ts

@@ -1,6 +1,6 @@
 import type { ChatMsg } from '../types/index.js';
-import type { SessionMeta, SessionStoreOptions, StoredSession } from './types.js';
-export declare class SessionStore {
+import type { SessionMeta, SessionStoreOptions, StoredSession, SessionStoreLike } from './types.js';
+export declare class SessionStore implements SessionStoreLike {
     private readonly dbName;
     private db;
     private opening;

package/dist/session/store.js

@@ -4,6 +4,8 @@
 //
 // `dexie` is an OPTIONAL peer dependency — imported dynamically so this module
 // loads even when Dexie isn't installed (the error surfaces only on first use).
+// The built-in IndexedDB (Dexie) session store. `implements SessionStoreLike`
+// guarantees it stays compatible with the pluggable interface the agent expects.
 export class SessionStore {
     constructor(options = {}) {
         this.db = null;

package/dist/session/types.d.ts

@@ -20,3 +20,25 @@ export interface SessionStoreOptions {
     /** IndexedDB database name. Default: 'bcs-sessions'. */
     dbName?: string;
 }
+/**
+ * Minimal pluggable session store — implement this to back persistence with any
+ * database (Supabase, Neon/Postgres, Vercel KV, Upstash Redis, files, …). The
+ * agent loop only needs `load` + `save`; the rest are for UIs/management.
+ */
+export interface SessionStoreLike {
+    /** Return the stored transcript for a session, or null if none. */
+    load(sessionId: string): Promise<ChatMsg[] | null>;
+    /** Persist the transcript (called after each turn + on a paused boundary). */
+    save(sessionId: string, transcript: ChatMsg[], meta?: {
+        title?: string;
+        model?: string;
+    }): Promise<void>;
+    /** Optional: list sessions (metadata only). */
+    list?(): Promise<SessionMeta[]>;
+    /** Optional: full stored session. */
+    get?(sessionId: string): Promise<StoredSession | null>;
+    /** Optional: rename a session. */
+    rename?(sessionId: string, title: string): Promise<void>;
+    /** Optional: delete a session. */
+    remove?(sessionId: string): Promise<void>;
+}

package/dist/tools/ask_user.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from './types.js';
+export declare const askUserQuestion: Tool;

package/dist/tools/ask_user.js

@@ -0,0 +1,54 @@
+const DESCRIPTION = `Ask the user a multiple-choice question and wait for their answer. Use ONLY when you hit a decision that's genuinely the user's to make (choosing between distinct approaches, confirming ambiguous scope) and you can't resolve it from the request or sensible defaults. Provide 2-4 concrete, mutually-exclusive options. Prefer acting on a reasonable default over asking.`;
+export const askUserQuestion = {
+    def: {
+        type: 'function',
+        function: {
+            name: 'ask_user_question',
+            description: DESCRIPTION,
+            parameters: {
+                type: 'object',
+                properties: {
+                    question: { type: 'string', description: 'The question to ask the user.' },
+                    header: { type: 'string', description: 'Very short label/chip for the question (max ~12 chars).' },
+                    options: {
+                        type: 'array',
+                        description: '2-4 options the user can choose from.',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                label: { type: 'string', description: 'Concise choice text (1-5 words).' },
+                                description: { type: 'string', description: 'What this option means / its trade-off.' },
+                            },
+                            required: ['label'],
+                        },
+                    },
+                    multiSelect: { type: 'boolean', description: 'Allow selecting multiple options.' },
+                },
+                required: ['question', 'options'],
+            },
+        },
+    },
+    async run(input, ctx) {
+        if (!ctx.askUser) {
+            return {
+                content: 'Interactive questions are unavailable in this environment. Choose the most reasonable option yourself, state the assumption, and continue.',
+                isError: true,
+            };
+        }
+        const question = String(input.question ?? '').trim();
+        const raw = Array.isArray(input.options) ? input.options : [];
+        const options = raw.map((o) => typeof o === 'string'
+            ? { label: o }
+            : { label: String(o.label ?? ''), description: o.description ? String(o.description) : undefined });
+        if (!question || !options.length)
+            return { content: 'Error: `question` and `options` are required.', isError: true };
+        const answer = await ctx.askUser({
+            question,
+            header: input.header ? String(input.header) : undefined,
+            options,
+            multiSelect: !!input.multiSelect,
+        });
+        const chosen = Array.isArray(answer) ? answer.join(', ') : String(answer);
+        return { content: `User answered "${question}" → ${chosen || '(no selection)'}` };
+    },
+};

package/dist/tools/index.d.ts

@@ -20,6 +20,7 @@ export { bash, readFile, writeFile, editFile, deleteFile, listFiles, glob, grep
 export { multiEdit, notebookEdit, todoWrite, webFetch, webSearch, toolSearch, config };
 export { walk, globToRegExp, joinPath, DEFAULT_IGNORE } from './walk.js';
 export { defineTool, type DefineToolSpec } from './define.js';
+export { askUserQuestion } from './ask_user.js';
 /** Every built-in Claude Code tool, ready to pass to `query()`. */
 export declare const ALL_CLAUDE_CODE_TOOLS: Tool[];
 /** Extract the OpenAI-shape definitions to send to the LLM. */

package/dist/tools/index.js

@@ -17,6 +17,7 @@ export { bash, readFile, writeFile, editFile, deleteFile, listFiles, glob, grep
 export { multiEdit, notebookEdit, todoWrite, webFetch, webSearch, toolSearch, config };
 export { walk, globToRegExp, joinPath, DEFAULT_IGNORE } from './walk.js';
 export { defineTool } from './define.js';
+export { askUserQuestion } from './ask_user.js';
 /** Every built-in Claude Code tool, ready to pass to `query()`. */
 export const ALL_CLAUDE_CODE_TOOLS = [
     bash,

package/dist/tools/types.d.ts

@@ -41,6 +41,16 @@ export interface ToolContext {
         text: string;
         isError?: boolean;
     }>;
+    /** Ask the user a multiple-choice question (wired from query({ onAskUser })). */
+    askUser?: (q: {
+        question: string;
+        header?: string;
+        options: Array<{
+            label: string;
+            description?: string;
+        }>;
+        multiSelect?: boolean;
+    }) => Promise<string | string[]>;
     /** Background task manager, present when background tasks are enabled. */
     background?: import('../background/manager.js').BackgroundTaskManager;
     /** Inter-agent mailbox, present when teammates are enabled. Shared with sub-agents. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anyclaude-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Standalone, browser-compatible SDK providing Claude Code agent capabilities (tools, tool loop, multi-turn, MCP, sub-agents, sessions) against any OpenAI/Anthropic-compatible LLM endpoint. Runs in the browser (WebContainer), Node, and Bun — no backend required.",
   "type": "module",
   "main": "./dist/index.js",