@a3s-lab/code 0.3.1 → 0.4.0

package/dist/session.js

@@ -0,0 +1,1092 @@
+/**
+ * Session — The core abstraction for A3S Code SDK.
+ *
+ * A Session binds a workspace and model at creation time (immutable).
+ * All agentic, generation, streaming, and context management calls are methods on the session.
+ *
+ * Every `session.send()` can trigger the AgenticLoop — when the model calls tools,
+ * the session automatically enters the loop (generate → tool call → execute → reflect → repeat).
+ *
+ * Supports `using` syntax for automatic cleanup via Symbol.asyncDispose.
+ *
+ * @example
+ * ```typescript
+ * import { A3sClient, createProvider } from '@a3s-lab/code';
+ *
+ * const client = new A3sClient();
+ * const openai = createProvider({ name: 'openai', apiKey: 'sk-xxx' });
+ *
+ * await using session = await client.createSession({
+ *   model: openai('gpt-4o'),
+ *   workspace: '/project',
+ *   system: 'You are a senior software engineer.',
+ * });
+ *
+ * // Simple question — model answers directly
+ * const { text } = await session.send('What is TypeScript?');
+ *
+ * // Complex task — auto-enters AgenticLoop
+ * const { text, steps, toolCalls } = await session.send(
+ *   'Refactor the auth module to use JWT',
+ * );
+ *
+ * // Streaming with real-time events
+ * const { eventStream } = session.sendStream('Fix all TODOs in src/');
+ * for await (const event of eventStream) {
+ *   if (event.type === 'text') process.stdout.write(event.content);
+ * }
+ * ```
+ */
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+function resolveMessages(prompt, messages) {
+    if (messages && messages.length > 0)
+        return messages;
+    if (prompt)
+        return [{ role: 'user', content: prompt }];
+    throw new Error('Either "prompt" or "messages" must be provided');
+}
+async function executeClientTool(toolDef, toolCall, onToolCall) {
+    const args = toolCall.arguments ? JSON.parse(toolCall.arguments) : {};
+    const event = {
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        args,
+    };
+    if (onToolCall) {
+        const callbackResult = await onToolCall(event);
+        if (callbackResult !== undefined && !toolDef.execute) {
+            return {
+                success: true,
+                output: typeof callbackResult === 'string'
+                    ? callbackResult
+                    : JSON.stringify(callbackResult),
+                error: '',
+                metadata: {},
+            };
+        }
+    }
+    if (toolDef.execute) {
+        try {
+            const result = await toolDef.execute(args, { toolCallId: toolCall.id });
+            return {
+                success: true,
+                output: typeof result === 'string' ? result : JSON.stringify(result),
+                error: '',
+                metadata: {},
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                output: '',
+                error: err instanceof Error ? err.message : String(err),
+                metadata: {},
+            };
+        }
+    }
+    return {
+        success: false,
+        output: '',
+        error: `Tool "${toolCall.name}" has no execute function and onToolCall did not return a result`,
+        metadata: {},
+    };
+}
+/** Map friendly lane name to proto enum */
+function laneNameToProto(lane) {
+    const map = {
+        control: 'SESSION_LANE_CONTROL',
+        query: 'SESSION_LANE_QUERY',
+        execute: 'SESSION_LANE_EXECUTE',
+        generate: 'SESSION_LANE_GENERATE',
+    };
+    return map[lane];
+}
+/** Map friendly handler mode to proto enum */
+function handlerModeToProto(mode) {
+    const map = {
+        internal: 'TASK_HANDLER_MODE_INTERNAL',
+        external: 'TASK_HANDLER_MODE_EXTERNAL',
+        hybrid: 'TASK_HANDLER_MODE_HYBRID',
+    };
+    return map[mode];
+}
+/** Map friendly timeout action to proto enum */
+function timeoutActionToProto(action) {
+    if (action === 'auto-approve')
+        return 'TIMEOUT_ACTION_AUTO_APPROVE';
+    return 'TIMEOUT_ACTION_REJECT';
+}
+/** Map friendly permission action to proto enum */
+function permissionActionToProto(action) {
+    const map = {
+        allow: 'PERMISSION_DECISION_ALLOW',
+        deny: 'PERMISSION_DECISION_DENY',
+        ask: 'PERMISSION_DECISION_ASK',
+    };
+    return map[action] || 'PERMISSION_DECISION_ALLOW';
+}
+/** Map a proto AgenticGenerateEvent to an SDK AgentLoopEvent */
+function mapProtoAgenticEvent(event) {
+    switch (event.type) {
+        case 'text':
+            return event.content ? { type: 'text', content: event.content } : null;
+        case 'tool_call':
+            if (!event.toolCall)
+                return null;
+            return {
+                type: 'tool_call',
+                toolName: event.toolCall.name,
+                args: event.toolCall.arguments ? JSON.parse(event.toolCall.arguments) : {},
+                toolCallId: event.toolCall.id,
+            };
+        case 'tool_result':
+            return event.toolResult
+                ? {
+                    type: 'tool_result',
+                    toolCallId: event.toolCallId || '',
+                    output: event.toolResult.output,
+                    success: event.toolResult.success,
+                }
+                : null;
+        case 'step_finish':
+            return {
+                type: 'step_finish',
+                stepIndex: event.stepIndex ?? 0,
+                text: event.stepText || '',
+                toolCalls: [],
+            };
+        case 'error':
+            return {
+                type: 'error',
+                message: event.errorMessage || 'Unknown error',
+                recoverable: event.recoverable ?? false,
+            };
+        case 'done':
+            return { type: 'done', finishReason: event.finishReason || 'stop' };
+        case 'confirmation_required':
+            return {
+                type: 'confirmation_required',
+                confirmationId: event.confirmationId || '',
+                toolName: event.toolName || '',
+                args: event.toolArgs ? JSON.parse(event.toolArgs) : {},
+                timeout: event.timeoutMs ?? 30000,
+            };
+        case 'confirmation_received':
+            return { type: 'confirmation_received', approved: event.approved ?? false };
+        case 'subagent_start':
+            return {
+                type: 'subagent_start',
+                agentName: event.agentName || '',
+                task: event.agentTask || '',
+                sessionId: event.agentSessionId || '',
+            };
+        case 'subagent_end':
+            return {
+                type: 'subagent_end',
+                agentName: event.agentName || '',
+                result: event.agentResult || '',
+            };
+        case 'context_compact':
+            return {
+                type: 'context_compact',
+                beforeTokens: event.beforeTokens ?? 0,
+                afterTokens: event.afterTokens ?? 0,
+            };
+        default:
+            return null;
+    }
+}
+// ============================================================================
+// Session Class
+// ============================================================================
+/**
+ * Session — The core object for interacting with A3S Code.
+ *
+ * Created via `client.createSession()`. Workspace and model are immutable
+ * after creation. Supports `await using` for automatic cleanup.
+ */
+export class Session {
+    /** The underlying A3S client */
+    _client;
+    /** Session ID on the server */
+    id;
+    /** Whether this session has been closed */
+    _closed = false;
+    /** Custom registered agents */
+    _customAgents = [];
+    /** @internal — Use client.createSession() instead */
+    constructor(client, sessionId) {
+        this._client = client;
+        this.id = sessionId;
+    }
+    // --------------------------------------------------------------------------
+    // Text Generation
+    // --------------------------------------------------------------------------
+    /**
+     * Generate text from the language model.
+     *
+     * Supports multi-step tool calling via `tools` and `maxSteps`.
+     *
+     * @example
+     * ```typescript
+     * const { text } = await session.generateText({ prompt: 'Hello' });
+     *
+     * // With tools
+     * const { text, steps } = await session.generateText({
+     *   prompt: 'What is the weather?',
+     *   tools: { weather: weatherTool },
+     *   maxSteps: 5,
+     * });
+     * ```
+     */
+    async generateText(options) {
+        this._ensureOpen();
+        const messages = resolveMessages(options.prompt, options.messages);
+        const maxSteps = options.maxSteps ?? 1;
+        const allSteps = [];
+        let fullText = '';
+        let lastFinishReason = 'stop';
+        const allToolCalls = [];
+        for (let step = 0; step < maxSteps; step++) {
+            const stepMessages = step === 0 ? messages : [];
+            const response = await this._client.generate(this.id, stepMessages);
+            const stepText = response.message?.content || '';
+            fullText += stepText;
+            lastFinishReason = response.finishReason;
+            const stepToolCalls = response.toolCalls || [];
+            const stepToolResults = [];
+            allToolCalls.push(...stepToolCalls);
+            // Execute client-side tools
+            const clientToolCalls = stepToolCalls.filter((tc) => options.tools && tc.name in options.tools);
+            for (const tc of clientToolCalls) {
+                const toolDef = options.tools[tc.name];
+                const result = await executeClientTool(toolDef, tc, options.onToolCall);
+                stepToolResults.push(result);
+                tc.result = result;
+            }
+            const stepResult = {
+                stepIndex: step,
+                text: stepText,
+                toolCalls: stepToolCalls,
+                toolResults: stepToolResults,
+                usage: response.usage,
+                finishReason: response.finishReason,
+            };
+            allSteps.push(stepResult);
+            if (options.onStepFinish) {
+                await options.onStepFinish(stepResult);
+            }
+            if (stepToolCalls.length === 0 || response.finishReason !== 'tool_calls') {
+                break;
+            }
+        }
+        return {
+            text: fullText,
+            usage: allSteps.length > 0 ? allSteps[allSteps.length - 1].usage : undefined,
+            finishReason: lastFinishReason,
+            toolCalls: allToolCalls,
+            steps: allSteps,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Text Streaming
+    // --------------------------------------------------------------------------
+    /**
+     * Stream text from the language model.
+     *
+     * Returns immediately with stream handles. Supports multi-step tool calling.
+     *
+     * @example
+     * ```typescript
+     * const { textStream } = session.streamText({ prompt: 'Explain this' });
+     * for await (const chunk of textStream) {
+     *   process.stdout.write(chunk);
+     * }
+     * ```
+     */
+    streamText(options) {
+        this._ensureOpen();
+        const messages = resolveMessages(options.prompt, options.messages);
+        const maxSteps = options.maxSteps ?? 1;
+        let fullText = '';
+        let finalUsage;
+        let finalFinishReason;
+        const allSteps = [];
+        let resolveText;
+        let resolveUsage;
+        let resolveFinishReason;
+        let resolveSteps;
+        let rejectText;
+        const textPromise = new Promise((res, rej) => {
+            resolveText = res;
+            rejectText = rej;
+        });
+        const usagePromise = new Promise((res) => {
+            resolveUsage = res;
+        });
+        const finishReasonPromise = new Promise((res) => {
+            resolveFinishReason = res;
+        });
+        const stepsPromise = new Promise((res) => {
+            resolveSteps = res;
+        });
+        const chunks = [];
+        let streamDone = false;
+        const waiters = [];
+        function notifyWaiters() {
+            for (const w of waiters.splice(0))
+                w();
+        }
+        const sessionId = this.id;
+        const client = this._client;
+        const produce = (async () => {
+            try {
+                for (let step = 0; step < maxSteps; step++) {
+                    const stepMessages = step === 0 ? messages : [];
+                    const stream = client.streamGenerate(sessionId, stepMessages);
+                    let stepText = '';
+                    const stepToolCalls = [];
+                    const stepToolResults = [];
+                    let stepFinishReason;
+                    for await (const chunk of stream) {
+                        if (chunk.content) {
+                            fullText += chunk.content;
+                            stepText += chunk.content;
+                        }
+                        if (chunk.toolCall)
+                            stepToolCalls.push(chunk.toolCall);
+                        if (chunk.finishReason) {
+                            stepFinishReason = chunk.finishReason;
+                            finalFinishReason = chunk.finishReason;
+                        }
+                        chunks.push(chunk);
+                        notifyWaiters();
+                    }
+                    // Execute client-side tools
+                    if (options.tools) {
+                        for (const tc of stepToolCalls) {
+                            if (tc.name in options.tools) {
+                                const toolDef = options.tools[tc.name];
+                                const result = await executeClientTool(toolDef, tc, options.onToolCall);
+                                stepToolResults.push(result);
+                                tc.result = result;
+                                chunks.push({
+                                    type: 'tool_result',
+                                    sessionId,
+                                    content: '',
+                                    toolCall: tc,
+                                    toolResult: result,
+                                    metadata: {},
+                                });
+                                notifyWaiters();
+                            }
+                        }
+                    }
+                    const stepResult = {
+                        stepIndex: step,
+                        text: stepText,
+                        toolCalls: stepToolCalls,
+                        toolResults: stepToolResults,
+                        usage: undefined,
+                        finishReason: stepFinishReason,
+                    };
+                    allSteps.push(stepResult);
+                    if (options.onStepFinish) {
+                        await options.onStepFinish(stepResult);
+                    }
+                    if (stepToolCalls.length === 0 || stepFinishReason !== 'tool_calls') {
+                        break;
+                    }
+                }
+                resolveText(fullText);
+                resolveUsage(finalUsage);
+                resolveFinishReason(finalFinishReason);
+                resolveSteps(allSteps);
+            }
+            catch (err) {
+                rejectText(err);
+                throw err;
+            }
+            finally {
+                streamDone = true;
+                notifyWaiters();
+            }
+        })();
+        produce.catch(() => { });
+        function createIterator(transform) {
+            return {
+                [Symbol.asyncIterator]() {
+                    let index = 0;
+                    return {
+                        async next() {
+                            while (true) {
+                                if (index < chunks.length) {
+                                    const val = transform(chunks[index++]);
+                                    if (val !== null)
+                                        return { value: val, done: false };
+                                    continue;
+                                }
+                                if (streamDone) {
+                                    return { value: undefined, done: true };
+                                }
+                                await new Promise((r) => waiters.push(r));
+                            }
+                        },
+                    };
+                },
+            };
+        }
+        return {
+            textStream: createIterator((c) => (c.content ? c.content : null)),
+            fullStream: createIterator((c) => c),
+            toolStream: createIterator((c) => (c.toolCall ? c.toolCall : null)),
+            text: textPromise,
+            usage: usagePromise,
+            finishReason: finishReasonPromise,
+            steps: stepsPromise,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Structured Output
+    // --------------------------------------------------------------------------
+    /**
+     * Generate a structured object from the language model.
+     *
+     * @example
+     * ```typescript
+     * const { object } = await session.generateObject({
+     *   schema: JSON.stringify({ type: 'object', properties: { name: { type: 'string' } } }),
+     *   prompt: 'Extract the name',
+     * });
+     * ```
+     */
+    async generateObject(options) {
+        this._ensureOpen();
+        const messages = resolveMessages(options.prompt, options.messages);
+        const response = await this._client.generateStructured(this.id, messages, options.schema);
+        let parsed;
+        try {
+            parsed = JSON.parse(response.data);
+        }
+        catch {
+            parsed = response.data;
+        }
+        return { object: parsed, data: response.data, usage: response.usage };
+    }
+    /**
+     * Stream a structured object from the language model.
+     *
+     * @example
+     * ```typescript
+     * const { partialStream, object } = session.streamObject({
+     *   schema: '{"type":"object","properties":{"items":{"type":"array"}}}',
+     *   prompt: 'List project files',
+     * });
+     * for await (const partial of partialStream) {
+     *   console.log('partial:', partial);
+     * }
+     * const result = await object;
+     * ```
+     */
+    streamObject(options) {
+        this._ensureOpen();
+        const messages = resolveMessages(options.prompt, options.messages);
+        let fullData = '';
+        let resolveObject;
+        let resolveData;
+        let rejectAll;
+        const objectPromise = new Promise((res, rej) => {
+            resolveObject = res;
+            rejectAll = rej;
+        });
+        const dataPromise = new Promise((res) => {
+            resolveData = res;
+        });
+        const sessionId = this.id;
+        const client = this._client;
+        const partialStream = {
+            [Symbol.asyncIterator]() {
+                let started = false;
+                let iter;
+                return {
+                    async next() {
+                        if (!started) {
+                            started = true;
+                            const stream = client.streamGenerateStructured(sessionId, messages, options.schema);
+                            iter = stream[Symbol.asyncIterator]();
+                        }
+                        try {
+                            const result = await iter.next();
+                            if (result.done) {
+                                resolveData(fullData);
+                                try {
+                                    resolveObject(JSON.parse(fullData));
+                                }
+                                catch {
+                                    resolveObject(fullData);
+                                }
+                                return { value: undefined, done: true };
+                            }
+                            fullData += result.value.data;
+                            return { value: result.value.data, done: false };
+                        }
+                        catch (err) {
+                            rejectAll(err);
+                            throw err;
+                        }
+                    },
+                };
+            },
+        };
+        return { partialStream, object: objectPromise, data: dataPromise };
+    }
+    // --------------------------------------------------------------------------
+    // Context Management
+    // --------------------------------------------------------------------------
+    /** Get context usage (token counts, message count) */
+    async getContextUsage() {
+        this._ensureOpen();
+        const resp = await this._client.getContextUsage(this.id);
+        return resp.usage;
+    }
+    /** Compact the conversation context to save tokens */
+    async compactContext() {
+        this._ensureOpen();
+        await this._client.compactContext(this.id);
+    }
+    /** Clear conversation history */
+    async clearContext() {
+        this._ensureOpen();
+        await this._client.clearContext(this.id);
+    }
+    /** Get conversation messages */
+    async getMessages(limit, offset) {
+        this._ensureOpen();
+        return this._client.getMessages(this.id, limit, offset);
+    }
+    // --------------------------------------------------------------------------
+    // AgenticLoop: send() / sendStream()
+    // --------------------------------------------------------------------------
+    /**
+     * Send a message to the agent. Automatically enters the server-side
+     * AgenticLoop when the model calls tools (plan → execute → reflect → repeat).
+     *
+     * The entire loop runs on the server — built-in tools, planning, reflection,
+     * and HITL are all handled server-side. Client-side tools (if provided) are
+     * used as a fallback for tools not available on the server.
+     *
+     * @example
+     * ```typescript
+     * // Simple question — no tools needed
+     * const { text } = await session.send('What is TypeScript?');
+     *
+     * // Complex task — server runs full AgenticLoop
+     * const { text, steps, toolCalls } = await session.send(
+     *   'Refactor the auth module to use JWT',
+     *   { maxSteps: 50 },
+     * );
+     * ```
+     */
+    async send(prompt, options = {}) {
+        this._ensureOpen();
+        const strategyMap = {
+            auto: 'AGENTIC_STRATEGY_AUTO',
+            direct: 'AGENTIC_STRATEGY_DIRECT',
+            planned: 'AGENTIC_STRATEGY_PLANNED',
+            iterative: 'AGENTIC_STRATEGY_ITERATIVE',
+            parallel: 'AGENTIC_STRATEGY_PARALLEL',
+        };
+        const resp = await this._client.agenticGenerate(this.id, prompt, {
+            strategy: strategyMap[options.strategy || 'auto'],
+            maxSteps: options.maxSteps ?? 50,
+            reflection: options.reflection ?? true,
+            planning: options.planning === true || options.planning === 'auto',
+        });
+        // Map server response to SDK types
+        const steps = (resp.steps || []).map((s) => ({
+            stepIndex: s.stepIndex,
+            text: s.text,
+            toolCalls: s.toolCalls || [],
+            toolResults: s.toolResults || [],
+            usage: s.usage,
+            finishReason: s.finishReason,
+        }));
+        // Emit events for callbacks
+        if (options.onEvent) {
+            await options.onEvent({ type: 'done', finishReason: resp.finishReason });
+        }
+        return {
+            text: resp.text,
+            steps,
+            toolCalls: resp.toolCalls || [],
+            usage: resp.usage || { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            finishReason: resp.finishReason || 'stop',
+        };
+    }
+    /**
+     * Stream a message to the agent. Returns an event stream for real-time UI
+     * and a promise for the final result.
+     *
+     * @example
+     * ```typescript
+     * const { eventStream, result } = session.sendStream('Fix all TODOs in src/');
+     * for await (const event of eventStream) {
+     *   if (event.type === 'text') process.stdout.write(event.content);
+     *   if (event.type === 'tool_call') console.log(`🔧 ${event.toolName}`);
+     * }
+     * const final = await result;
+     * ```
+     */
+    sendStream(prompt, options = {}) {
+        this._ensureOpen();
+        const maxSteps = options.maxSteps ?? 50;
+        const events = [];
+        let streamDone = false;
+        const waiters = [];
+        function pushEvent(event) {
+            events.push(event);
+            for (const w of waiters.splice(0))
+                w();
+        }
+        const resultPromise = (async () => {
+            const allSteps = [];
+            const allToolCalls = [];
+            let fullText = '';
+            let totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            try {
+                for (let step = 0; step < maxSteps; step++) {
+                    if (options.signal?.aborted) {
+                        pushEvent({ type: 'done', finishReason: 'cancelled' });
+                        return { text: fullText, steps: allSteps, toolCalls: allToolCalls, usage: totalUsage, finishReason: 'cancelled' };
+                    }
+                    const messages = step === 0 ? [{ role: 'user', content: prompt }] : [];
+                    const stream = this._client.streamGenerate(this.id, messages);
+                    let stepText = '';
+                    const stepToolCalls = [];
+                    let stepFinishReason;
+                    for await (const chunk of stream) {
+                        if (chunk.content) {
+                            fullText += chunk.content;
+                            stepText += chunk.content;
+                            pushEvent({ type: 'text', content: chunk.content });
+                        }
+                        if (chunk.toolCall) {
+                            stepToolCalls.push(chunk.toolCall);
+                            const args = chunk.toolCall.arguments ? JSON.parse(chunk.toolCall.arguments) : {};
+                            pushEvent({ type: 'tool_call', toolName: chunk.toolCall.name, args, toolCallId: chunk.toolCall.id });
+                        }
+                        if (chunk.finishReason) {
+                            stepFinishReason = chunk.finishReason;
+                        }
+                    }
+                    allToolCalls.push(...stepToolCalls);
+                    // Execute client-side tools
+                    const stepToolResults = [];
+                    if (options.tools) {
+                        for (const tc of stepToolCalls) {
+                            if (tc.name in options.tools) {
+                                const toolDef = options.tools[tc.name];
+                                const result = await executeClientTool(toolDef, tc, options.onToolCall);
+                                stepToolResults.push(result);
+                                tc.result = result;
+                                pushEvent({ type: 'tool_result', toolCallId: tc.id, output: result.output, success: result.success });
+                            }
+                        }
+                    }
+                    const stepResult = {
+                        stepIndex: step,
+                        text: stepText,
+                        toolCalls: stepToolCalls,
+                        toolResults: stepToolResults,
+                        usage: undefined,
+                        finishReason: stepFinishReason,
+                    };
+                    allSteps.push(stepResult);
+                    pushEvent({ type: 'step_finish', stepIndex: step, text: stepText, toolCalls: stepToolCalls });
+                    if (options.onStepFinish) {
+                        await options.onStepFinish(stepResult);
+                    }
+                    if (stepToolCalls.length === 0 || stepFinishReason !== 'tool_calls') {
+                        break;
+                    }
+                }
+                const finishReason = allSteps.length >= maxSteps ? 'max_steps' : 'stop';
+                pushEvent({ type: 'done', finishReason });
+                return { text: fullText, steps: allSteps, toolCalls: allToolCalls, usage: totalUsage, finishReason };
+            }
+            finally {
+                streamDone = true;
+                for (const w of waiters.splice(0))
+                    w();
+            }
+        })();
+        // Suppress unhandled rejection on the background promise
+        resultPromise.catch(() => { });
+        const eventStream = {
+            [Symbol.asyncIterator]() {
+                let index = 0;
+                return {
+                    async next() {
+                        while (true) {
+                            if (index < events.length) {
+                                return { value: events[index++], done: false };
+                            }
+                            if (streamDone) {
+                                return { value: undefined, done: true };
+                            }
+                            await new Promise((r) => waiters.push(r));
+                        }
+                    },
+                };
+            },
+        };
+        return { eventStream, result: resultPromise };
+    }
+    // --------------------------------------------------------------------------
+    // Delegation (Subagents)
+    // --------------------------------------------------------------------------
+    /**
+     * Delegate a task to a built-in or custom agent.
+     *
+     * Uses server-side delegation — the server creates a child session with
+     * the agent's restricted permissions and executes the task.
+     *
+     * @example
+     * ```typescript
+     * const result = await session.delegate('explore', 'Find all API endpoints');
+     * console.log(result.text);
+     * ```
+     */
+    async delegate(agent, task, options) {
+        this._ensureOpen();
+        const resp = await this._client.delegateToAgent(this.id, agent, task, {
+            maxSteps: options?.maxSteps ?? 50,
+            allowedTools: options?.allowedTools,
+        });
+        const steps = (resp.steps || []).map((s) => ({
+            stepIndex: s.stepIndex,
+            text: s.text,
+            toolCalls: s.toolCalls || [],
+            toolResults: s.toolResults || [],
+            usage: s.usage,
+            finishReason: s.finishReason,
+        }));
+        return {
+            text: resp.text,
+            steps,
+            toolCalls: resp.toolCalls || [],
+            usage: resp.usage || { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            finishReason: resp.finishReason || 'stop',
+        };
+    }
+    /**
+     * Delegate a task to a subagent with streaming.
+     *
+     * Uses server-side streaming delegation for real-time event updates.
+     */
+    delegateStream(agent, task, options) {
+        this._ensureOpen();
+        const events = [];
+        let streamDone = false;
+        const waiters = [];
+        function pushEvent(event) {
+            events.push(event);
+            for (const w of waiters.splice(0))
+                w();
+        }
+        const resultPromise = (async () => {
+            const allSteps = [];
+            const allToolCalls = [];
+            let fullText = '';
+            let totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            try {
+                const stream = this._client.streamDelegateToAgent(this.id, agent, task, {
+                    maxSteps: options?.maxSteps ?? 50,
+                    allowedTools: options?.allowedTools,
+                });
+                for await (const event of stream) {
+                    const mapped = mapProtoAgenticEvent(event);
+                    if (mapped)
+                        pushEvent(mapped);
+                    if (event.content)
+                        fullText += event.content;
+                    if (event.toolCall)
+                        allToolCalls.push(event.toolCall);
+                    if (event.usage)
+                        totalUsage = event.usage;
+                }
+                const finishReason = 'stop';
+                pushEvent({ type: 'done', finishReason });
+                return { text: fullText, steps: allSteps, toolCalls: allToolCalls, usage: totalUsage, finishReason };
+            }
+            finally {
+                streamDone = true;
+                for (const w of waiters.splice(0))
+                    w();
+            }
+        })();
+        resultPromise.catch(() => { });
+        const eventStream = {
+            [Symbol.asyncIterator]() {
+                let index = 0;
+                return {
+                    async next() {
+                        while (true) {
+                            if (index < events.length) {
+                                return { value: events[index++], done: false };
+                            }
+                            if (streamDone) {
+                                return { value: undefined, done: true };
+                            }
+                            await new Promise((r) => waiters.push(r));
+                        }
+                    },
+                };
+            },
+        };
+        return { eventStream, result: resultPromise };
+    }
+    // --------------------------------------------------------------------------
+    // Lane Queue Management
+    // --------------------------------------------------------------------------
+    /** Set lane execution mode (internal/external/hybrid) */
+    async setLaneHandler(lane, config) {
+        this._ensureOpen();
+        const protoLane = laneNameToProto(lane);
+        const protoConfig = {
+            mode: handlerModeToProto(config.mode),
+            timeoutMs: config.timeout ?? 60_000,
+        };
+        await this._client.setLaneHandler(this.id, protoLane, protoConfig);
+    }
+    /** Get lane handler configuration */
+    async getLaneHandler(lane) {
+        this._ensureOpen();
+        const resp = await this._client.getLaneHandler(this.id, laneNameToProto(lane));
+        if (!resp.config)
+            return undefined;
+        const modeMap = {
+            TASK_HANDLER_MODE_INTERNAL: 'internal',
+            TASK_HANDLER_MODE_EXTERNAL: 'external',
+            TASK_HANDLER_MODE_HYBRID: 'hybrid',
+        };
+        return {
+            mode: modeMap[resp.config.mode] || 'internal',
+            timeout: resp.config.timeoutMs,
+        };
+    }
+    /** List tasks waiting for external processing */
+    async listPendingTasks() {
+        this._ensureOpen();
+        const resp = await this._client.listPendingExternalTasks(this.id);
+        return resp.tasks;
+    }
+    /** Complete an external task */
+    async completeTask(taskId, result) {
+        this._ensureOpen();
+        await this._client.completeExternalTask(this.id, taskId, result.success, result.output, result.error);
+    }
+    // --------------------------------------------------------------------------
+    // Skills Management
+    // --------------------------------------------------------------------------
+    /** Load skills from a directory (uses server-side batch loading) */
+    async loadSkills(dir, recursive = true) {
+        this._ensureOpen();
+        const resp = await this._client.loadSkillsFromDir(this.id, dir, recursive);
+        return resp.loadedSkills || [];
+    }
+    /** Load a single skill by name */
+    async loadSkill(name, content) {
+        this._ensureOpen();
+        await this._client.loadSkill(this.id, name, content);
+    }
+    /** Add an inline skill definition */
+    async addSkill(skill) {
+        this._ensureOpen();
+        await this._client.loadSkill(this.id, skill.name, skill.content);
+    }
+    /** Unload a skill */
+    async unloadSkill(name) {
+        this._ensureOpen();
+        await this._client.unloadSkill(this.id, name);
+    }
+    /** List available skills */
+    async listSkills() {
+        this._ensureOpen();
+        const resp = await this._client.listSkills(this.id);
+        return resp.skills.map((s) => ({
+            name: s.name,
+            description: s.description,
+            loaded: true,
+            source: 'builtin',
+        }));
+    }
+    // --------------------------------------------------------------------------
+    // Built-in Agents
+    // --------------------------------------------------------------------------
+    /** List available agents (built-in + custom) */
+    async listAgents() {
+        this._ensureOpen();
+        return [
+            { name: 'explore', description: 'Read-only codebase exploration', mode: 'subagent' },
+            { name: 'plan', description: 'Read-only planning and analysis', mode: 'subagent' },
+            { name: 'general', description: 'Multi-step task execution', mode: 'subagent' },
+            ...this._customAgents.map((a) => ({
+                name: a.name,
+                description: a.description,
+                mode: 'subagent',
+            })),
+        ];
+    }
+    /** Register a custom agent */
+    registerAgent(def) {
+        this._ensureOpen();
+        this._customAgents.push(def);
+    }
+    // --------------------------------------------------------------------------
+    // HITL & Permissions
+    // --------------------------------------------------------------------------
+    /** Set HITL confirmation policy */
+    async setConfirmation(config) {
+        this._ensureOpen();
+        const policy = {
+            enabled: true,
+            requireConfirmTools: config.requireConfirmation || [],
+            autoApproveTools: config.autoApprove || [],
+            defaultTimeoutMs: config.timeout ?? 30_000,
+            timeoutAction: timeoutActionToProto(config.timeoutAction),
+            yoloLanes: [],
+        };
+        await this._client.setConfirmationPolicy(this.id, policy);
+    }
+    /** Set tool permission policy */
+    async setPermissions(config) {
+        this._ensureOpen();
+        const allow = [];
+        const deny = [];
+        const ask = [];
+        for (const rule of config.rules || []) {
+            const ruleStr = rule.pattern ? `${rule.tool}:${rule.pattern}` : rule.tool;
+            if (rule.action === 'allow')
+                allow.push({ rule: ruleStr });
+            else if (rule.action === 'deny')
+                deny.push({ rule: ruleStr });
+            else
+                ask.push({ rule: ruleStr });
+        }
+        const policy = {
+            enabled: true,
+            allow,
+            deny,
+            ask,
+            defaultDecision: permissionActionToProto(config.defaultAction || 'allow'),
+        };
+        await this._client.setPermissionPolicy(this.id, policy);
+    }
+    /** Respond to a confirmation request */
+    async confirm(confirmationId, approved, reason) {
+        this._ensureOpen();
+        await this._client.confirmToolExecution(this.id, confirmationId, approved, reason);
+    }
+    // --------------------------------------------------------------------------
+    // Observability & Stats
+    // --------------------------------------------------------------------------
+    /** Get session statistics (tokens, cost, message count, tool calls) */
+    async getStats() {
+        this._ensureOpen();
+        const [ctx, cost] = await Promise.all([
+            this._client.getContextUsage(this.id),
+            this._client.getCostSummary({ sessionId: this.id }),
+        ]);
+        return {
+            totalTokens: cost.totalTokens,
+            promptTokens: cost.totalPromptTokens,
+            completionTokens: cost.totalCompletionTokens,
+            totalCost: cost.totalCostUsd,
+            messageCount: ctx.usage?.messageCount ?? 0,
+            toolCallCount: cost.callCount,
+        };
+    }
+    /** Get per-tool execution metrics */
+    async getToolMetrics() {
+        this._ensureOpen();
+        const resp = await this._client.getToolMetrics(this.id);
+        const result = {};
+        for (const t of resp.tools) {
+            result[t.toolName] = t;
+        }
+        return result;
+    }
+    /** Get cost breakdown by model and day */
+    async getCostSummary() {
+        this._ensureOpen();
+        return this._client.getCostSummary({ sessionId: this.id });
+    }
+    /** Get per-lane queue statistics */
+    async getQueueStats() {
+        this._ensureOpen();
+        const resp = await this._client.getQueueStats(this.id);
+        const mapLane = (lane) => ({
+            pending: lane?.pending ?? 0,
+            active: lane?.active ?? 0,
+            external: lane?.external ?? 0,
+            completed: lane?.completed ?? 0,
+            failed: lane?.failed ?? 0,
+        });
+        return {
+            control: mapLane(resp.control),
+            query: mapLane(resp.query),
+            execute: mapLane(resp.execute),
+            generate: mapLane(resp.generate),
+            deadLetters: resp.deadLetters ?? 0,
+        };
+    }
+    /** Update session configuration (cannot change model or workspace) */
+    async configure(options) {
+        this._ensureOpen();
+        const resp = await this._client.getSession(this.id);
+        const existing = resp.session?.config;
+        if (existing) {
+            await this._client.configureSession(this.id, {
+                ...existing,
+                autoCompact: options.autoCompact ?? existing.autoCompact,
+            });
+        }
+    }
+    /** Subscribe to real-time agent events for this session */
+    subscribeEvents(eventTypes) {
+        this._ensureOpen();
+        return this._client.subscribeEvents(this.id, eventTypes);
+    }
+    // --------------------------------------------------------------------------
+    // Lifecycle
+    // --------------------------------------------------------------------------
+    /** Close the session and release server resources */
+    async close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        try {
+            await this._client.destroySession(this.id);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+    }
+    /** Support `await using session = ...` for automatic cleanup */
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    /** Whether this session has been closed */
+    get closed() {
+        return this._closed;
+    }
+    _ensureOpen() {
+        if (this._closed) {
+            throw new Error(`Session ${this.id} has been closed`);
+        }
+    }
+}
+//# sourceMappingURL=session.js.map