@windowkit/agent-chat 0.0.0-stage → 0.1.0

package/dist/core/session.js

@@ -0,0 +1,648 @@
+// A session: the transcript, the harness behind it, and every question the
+// harness asks the client — answered by the app's policy, or by the user.
+//
+// It is a store in the `useSyncExternalStore` sense: `snapshot` is one
+// immutable object, replaced on every change, and `subscribe` hears each
+// replacement. Nothing in it is React's, so a terminal or DOM front end can
+// drive the same object.
+import { AgentUnavailableError, } from './driver.js';
+import { transcriptMarkdown } from './markdown.js';
+import { policyDecision } from './policy.js';
+import { reduce, restore, findLivePart, } from './reducer.js';
+import { errorResult, normalizeResult, validateInput, } from './tools.js';
+import { NO_CAPABILITIES, } from './types.js';
+const APPROVAL_OPTIONS = Object.freeze([
+    { id: 'allow-once', label: 'Allow', kind: 'allow' },
+    { id: 'allow-session', label: 'Allow for this session', kind: 'allow' },
+    { id: 'deny', label: 'Deny', kind: 'deny' },
+]);
+const BUSY = new Set([
+    'starting',
+    'running',
+    'waiting',
+    'paused',
+]);
+export function createAgentSession(options = {}) {
+    return new Session(options);
+}
+/** Lines that tell the agent what the UI can draw — see `describe` on a
+ *  fence or a component. */
+export function describeRenderers(renderers = {}) {
+    const lines = [];
+    for (const [lang, entry] of Object.entries(renderers.fences ?? {})) {
+        const describe = describeOf(entry);
+        if (describe) {
+            lines.push(`The UI draws a fenced code block tagged \`${lang}\` as: ${describe}`);
+        }
+    }
+    for (const [name, entry] of Object.entries(renderers.components ?? {})) {
+        const describe = describeOf(entry);
+        if (describe) {
+            lines.push(`The UI draws a <${name}/> tag, alone on its line, as: ${describe}. ` +
+                'Its attributes are strings or JSON.');
+        }
+    }
+    return lines.length
+        ? ['You are shown in a chat UI that renders markdown.', ...lines]
+        : [];
+}
+function describeOf(entry) {
+    return entry && typeof entry === 'object' && 'describe' in entry
+        ? String(entry.describe)
+        : undefined;
+}
+class Session {
+    #options;
+    #config;
+    #snapshot;
+    #listeners = new Set();
+    #driver = null;
+    #starting = null;
+    #turn = null;
+    #queue = [];
+    #ids = 0;
+    #decisions = new Map();
+    #sessionAllowed = new Set();
+    #approvals = new Map();
+    #questions = new Map();
+    #paused = false;
+    #resumers = new Set();
+    constructor(options) {
+        this.#options = options;
+        this.#config = resolveConfig(options);
+        const messages = restore(options.messages ?? []);
+        // the user's next message continues the saved ones' numbering, so its
+        // id is not one already in the transcript
+        for (const m of messages) {
+            const n = /^u(\d+)$/.exec(m.id);
+            if (n)
+                this.#ids = Math.max(this.#ids, Number(n[1]));
+        }
+        const driverName = typeof options.agent === 'object' ? options.agent.name : 'claude';
+        this.#snapshot = Object.freeze({
+            status: 'idle',
+            messages,
+            info: {
+                agent: driverName,
+                cwd: this.#config.cwd,
+                models: [],
+                modes: [],
+                commands: [],
+            },
+            capabilities: NO_CAPABILITIES,
+            paused: false,
+        });
+    }
+    get snapshot() {
+        return this.#snapshot;
+    }
+    subscribe = (listener) => {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    };
+    get tools() {
+        return this.#config.tools;
+    }
+    #set(patch) {
+        this.#snapshot = Object.freeze({ ...this.#snapshot, ...patch });
+        for (const l of [...this.#listeners])
+            l();
+    }
+    #dispatch(action) {
+        const messages = reduce(this.#snapshot.messages, action);
+        if (messages !== this.#snapshot.messages)
+            this.#set({ messages });
+    }
+    // --- the harness -----------------------------------------------------------
+    start() {
+        return this.#start().then(() => undefined);
+    }
+    #start() {
+        if (this.#driver)
+            return Promise.resolve(this.#driver);
+        if (this.#starting)
+            return this.#starting;
+        this.#set({ status: 'starting', error: undefined });
+        this.#starting = (async () => {
+            try {
+                const driver = await loadDriver(this.#options.agent);
+                const session = await driver.start(this.#host());
+                this.#driver = session;
+                this.#set({
+                    capabilities: session.capabilities,
+                    status: this.#turn ? 'running' : 'idle',
+                });
+                return session;
+            }
+            catch (err) {
+                const unavailable = err instanceof AgentUnavailableError;
+                this.#set({
+                    status: unavailable ? 'unavailable' : 'error',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                this.#turn = null;
+                return null;
+            }
+            finally {
+                this.#starting = null;
+            }
+        })();
+        return this.#starting;
+    }
+    #host() {
+        return {
+            config: this.#config,
+            emit: (event) => this.#onEvent(event),
+            gate: (call) => this.#gate(call, true),
+            approve: (call, signal) => this.#approve(call, signal),
+            ask: (id, questions, signal) => this.#ask(id, questions, signal),
+            runTool: (name, input, ctx) => this.#runTool(name, input, ctx),
+        };
+    }
+    #onEvent(event) {
+        switch (event.type) {
+            case 'info':
+                this.#set({ info: { ...this.#snapshot.info, ...event.info } });
+                return;
+            case 'usage':
+                this.#set({
+                    info: {
+                        ...this.#snapshot.info,
+                        usage: { ...this.#snapshot.info.usage, ...event.usage },
+                    },
+                });
+                return;
+            case 'message':
+                // the harness took it and is acting on it: a turn, if none runs
+                this.#dispatch(event);
+                if (!this.#turn) {
+                    this.#turn = new AbortController();
+                    this.#set({ status: this.#paused ? 'paused' : 'running' });
+                }
+                return;
+            case 'turn-end':
+                this.#dispatch(event);
+                if (event.reason === 'error' && event.error) {
+                    this.#dispatch({ type: 'notice', level: 'error', text: event.error });
+                }
+                this.#endTurn();
+                return;
+            default:
+                this.#dispatch(event);
+        }
+    }
+    #endTurn() {
+        this.#turn = null;
+        this.#decisions.clear();
+        const next = this.#queue.shift();
+        if (next) {
+            this.#dispatch({ type: 'unqueue', id: next.id });
+            void this.#deliver(next);
+            return;
+        }
+        if (BUSY.has(this.#snapshot.status))
+            this.#set({ status: 'idle' });
+    }
+    // --- the user's side -------------------------------------------------------
+    send(input) {
+        const composed = typeof input === 'string' ? { text: input } : input;
+        const text = composed.text;
+        const attachments = composed.attachments ?? [];
+        const from = composed.from;
+        if (!text.trim() && !attachments.length)
+            return;
+        if (this.#snapshot.status === 'closed')
+            return;
+        const id = `u${++this.#ids}`;
+        const parts = [];
+        if (text)
+            parts.push({ type: 'text', id: `${id}:t`, text, streaming: false });
+        attachments.forEach((a, i) => parts.push({
+            type: 'file',
+            id: `${id}:f${i}`,
+            label: a.label,
+            mime: a.mime ?? (a.kind === 'image' ? 'image/png' : 'text/plain'),
+            ...(a.path ? { path: a.path } : {}),
+            ...(a.data !== undefined ? { data: a.data } : {}),
+        }));
+        const busy = !!this.#turn;
+        const steer = busy && this.#snapshot.capabilities.steer;
+        const queued = busy && !steer;
+        this.#dispatch({
+            type: 'user',
+            message: {
+                id,
+                role: 'user',
+                parts,
+                createdAt: Date.now(),
+                ...(from ? { from } : {}),
+                ...(queued ? { queued: true } : {}),
+            },
+        });
+        const out = {
+            id,
+            text,
+            attachments,
+            steer,
+            ...(from ? { from } : {}),
+        };
+        if (queued)
+            this.#queue.push(out);
+        else
+            void this.#deliver(out);
+    }
+    async #deliver(message) {
+        if (!message.steer)
+            this.#turn = new AbortController();
+        if (!this.#paused)
+            this.#set({ status: 'running', restored: undefined });
+        const driver = await this.#start();
+        if (!driver)
+            return;
+        if (!this.#turn && !message.steer)
+            return; // stopped while starting
+        if (!BUSY.has(this.#snapshot.status))
+            this.#set({ status: 'running' });
+        try {
+            driver.send(message);
+        }
+        catch (err) {
+            this.#onEvent({
+                type: 'turn-end',
+                reason: 'error',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    async stop() {
+        if (!this.#turn && !this.#queue.length)
+            return;
+        // what the user typed goes back to the composer; what another session
+        // sent is not theirs to edit, and goes with the turn
+        const restored = this.#queue
+            .filter((m) => !m.from)
+            .map((m) => m.text)
+            .join('\n\n');
+        const dropped = new Set(this.#queue.map((m) => m.id));
+        this.#queue.length = 0;
+        this.#turn?.abort();
+        for (const [id, resolve] of this.#approvals) {
+            this.#approvals.delete(id);
+            resolve({
+                behavior: 'deny',
+                message: 'Stopped by the user.',
+                interrupt: true,
+            });
+        }
+        for (const [id, resolve] of this.#questions) {
+            this.#questions.delete(id);
+            resolve(null);
+        }
+        this.#wake();
+        if (dropped.size) {
+            this.#set({
+                messages: this.#snapshot.messages.filter((m) => !dropped.has(m.id)),
+                restored: restored || undefined,
+            });
+        }
+        const driver = this.#driver;
+        this.#dispatch({ type: 'stopped' });
+        this.#turn = null;
+        this.#decisions.clear();
+        this.#set({ status: 'idle' });
+        try {
+            await driver?.interrupt();
+        }
+        catch {
+            // the harness is already gone; the transcript says stopped either way
+        }
+    }
+    takeRestored() {
+        const restored = this.#snapshot.restored;
+        if (restored !== undefined)
+            this.#set({ restored: undefined });
+        return restored;
+    }
+    pause() {
+        if (this.#paused)
+            return;
+        this.#paused = true;
+        this.#set({
+            paused: true,
+            ...(this.#turn ? { status: 'paused' } : {}),
+        });
+    }
+    resume() {
+        if (!this.#paused)
+            return;
+        this.#paused = false;
+        this.#set({
+            paused: false,
+            ...(this.#snapshot.status === 'paused'
+                ? {
+                    status: this.#approvals.size || this.#questions.size
+                        ? 'waiting'
+                        : 'running',
+                }
+                : {}),
+        });
+        this.#wake();
+    }
+    #wake() {
+        const resumers = [...this.#resumers];
+        this.#resumers.clear();
+        for (const r of resumers)
+            r();
+    }
+    #unpaused(signal) {
+        if (!this.#paused || signal?.aborted || !this.#turn)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const done = () => {
+                this.#resumers.delete(done);
+                signal?.removeEventListener('abort', done);
+                resolve();
+            };
+            this.#resumers.add(done);
+            signal?.addEventListener('abort', done, { once: true });
+        });
+    }
+    respond(toolId, choice, note) {
+        const resolve = this.#approvals.get(toolId);
+        if (!resolve)
+            return;
+        this.#approvals.delete(toolId);
+        if (choice === 'deny') {
+            resolve({
+                behavior: 'deny',
+                message: note?.trim()
+                    ? `Denied by the user: ${note.trim()}`
+                    : 'Denied by the user.',
+            });
+            return;
+        }
+        if (choice === 'allow-session') {
+            const part = findLivePart(this.#snapshot.messages, toolId);
+            if (part?.type === 'tool')
+                this.#sessionAllowed.add(part.label);
+        }
+        resolve({ behavior: 'allow' });
+    }
+    answer(questionId, answers) {
+        const resolve = this.#questions.get(questionId);
+        if (!resolve)
+            return;
+        this.#questions.delete(questionId);
+        resolve(answers);
+    }
+    async setModel(id) {
+        const driver = this.#driver ?? (await this.#start());
+        if (!driver?.setModel)
+            return;
+        await driver.setModel(id);
+        this.#set({ info: { ...this.#snapshot.info, model: id } });
+    }
+    async setMode(id) {
+        const driver = this.#driver ?? (await this.#start());
+        if (!driver?.setMode)
+            return;
+        await driver.setMode(id);
+        this.#set({ info: { ...this.#snapshot.info, mode: id } });
+    }
+    notify(level, text) {
+        // a notice goes in the turn under way, or in a message of its own
+        if (!this.#turn) {
+            this.#dispatch({
+                type: 'user',
+                message: {
+                    id: `n${++this.#ids}`,
+                    role: 'assistant',
+                    parts: [{ type: 'notice', id: `n${this.#ids}:0`, level, text }],
+                    createdAt: Date.now(),
+                    done: true,
+                },
+            });
+            return;
+        }
+        this.#dispatch({ type: 'notice', level, text });
+    }
+    toMarkdown() {
+        return transcriptMarkdown(this.#snapshot.messages);
+    }
+    async close() {
+        if (this.#snapshot.status === 'closed')
+            return;
+        await this.stop();
+        const driver = this.#driver;
+        this.#driver = null;
+        this.#set({ status: 'closed' });
+        await driver?.close();
+    }
+    // --- the harness's questions -------------------------------------------------
+    async #gate(call, remember) {
+        if (this.#paused && this.#turn)
+            return { behavior: 'ask' };
+        const known = this.#decisions.get(call.id);
+        if (known)
+            return known;
+        if (this.#sessionAllowed.has(call.label))
+            return { behavior: 'allow' };
+        let decision;
+        let fromApp;
+        try {
+            fromApp = await this.#options.onToolCall?.(call);
+        }
+        catch (err) {
+            fromApp = {
+                deny: `The app's check failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (fromApp === undefined)
+            decision = policyDecision(call, this.#config);
+        else if (fromApp === 'allow')
+            decision = { behavior: 'allow' };
+        else if (fromApp === 'allow-session') {
+            this.#sessionAllowed.add(call.label);
+            decision = { behavior: 'allow' };
+        }
+        else if (fromApp === 'deny') {
+            decision = { behavior: 'deny', message: 'Denied by the app.' };
+        }
+        else if (fromApp === 'ask')
+            decision = { behavior: 'ask' };
+        else if ('deny' in fromApp)
+            decision = { behavior: 'deny', message: fromApp.deny };
+        else
+            decision = { behavior: 'allow', input: fromApp.input };
+        if (remember)
+            this.#decisions.set(call.id, decision);
+        if (decision.behavior === 'deny') {
+            this.#dispatch({ type: 'approved', id: call.id, allowed: false });
+        }
+        return decision;
+    }
+    async #approve(call, signal) {
+        await this.#unpaused(signal);
+        if (signal?.aborted || !this.#turn) {
+            return {
+                behavior: 'deny',
+                message: 'Stopped by the user.',
+                interrupt: true,
+            };
+        }
+        const decision = await this.#gate(call, true);
+        if (decision.behavior === 'allow') {
+            return { behavior: 'allow', input: decision.input };
+        }
+        if (decision.behavior === 'deny') {
+            return { behavior: 'deny', message: decision.message };
+        }
+        if (!findLivePart(this.#snapshot.messages, call.id)) {
+            this.#dispatch({
+                type: 'tool-start',
+                id: call.id,
+                name: call.name,
+                label: call.label,
+                kind: call.kind,
+                title: call.title,
+                input: call.input,
+                app: call.app,
+            });
+        }
+        this.#dispatch({
+            type: 'approval',
+            id: call.id,
+            options: APPROVAL_OPTIONS,
+        });
+        this.#set({ status: 'waiting' });
+        const result = await new Promise((resolve) => {
+            this.#approvals.set(call.id, resolve);
+            signal?.addEventListener('abort', () => {
+                if (!this.#approvals.delete(call.id))
+                    return;
+                resolve({ behavior: 'deny', message: 'Stopped.', interrupt: true });
+            }, { once: true });
+        });
+        this.#decisions.set(call.id, result.behavior === 'allow'
+            ? { behavior: 'allow', input: result.input }
+            : { behavior: 'deny', message: result.message });
+        this.#dispatch({
+            type: 'approved',
+            id: call.id,
+            allowed: result.behavior === 'allow',
+        });
+        this.#settleWaiting();
+        return result;
+    }
+    async #ask(id, questions, signal) {
+        this.#dispatch({ type: 'question', id, questions });
+        this.#set({ status: 'waiting' });
+        const answers = await new Promise((resolve) => {
+            this.#questions.set(id, resolve);
+            signal?.addEventListener('abort', () => {
+                if (this.#questions.delete(id))
+                    resolve(null);
+            }, { once: true });
+        });
+        this.#dispatch({ type: 'answered', id, answers });
+        this.#settleWaiting();
+        return answers;
+    }
+    #settleWaiting() {
+        if (this.#approvals.size || this.#questions.size)
+            return;
+        if (this.#snapshot.status === 'waiting') {
+            this.#set({
+                status: this.#turn ? (this.#paused ? 'paused' : 'running') : 'idle',
+            });
+        }
+    }
+    async #runTool(name, input, ctx) {
+        const tool = this.#config.tools.get(name);
+        if (!tool)
+            return errorResult(new Error(`No tool named ${name}.`));
+        const checked = await validateInput(tool.parameters, input);
+        if (!checked.ok)
+            return errorResult(new Error(checked.message));
+        const callId = ctx.callId ?? `${name}:${++this.#ids}`;
+        const signal = ctx.signal ?? this.#turn?.signal ?? new AbortController().signal;
+        if (ctx.callId) {
+            this.#dispatch({ type: 'tool-update', id: callId, state: 'running' });
+        }
+        try {
+            const returned = await tool.run(checked.value, {
+                signal,
+                callId,
+                progress: (text) => {
+                    if (ctx.callId) {
+                        this.#dispatch({ type: 'tool-update', id: callId, progress: text });
+                    }
+                },
+            });
+            const { result, output } = normalizeResult(returned);
+            if (ctx.callId) {
+                this.#dispatch({ type: 'tool-update', id: callId, output });
+            }
+            return result;
+        }
+        catch (err) {
+            if (ctx.callId) {
+                this.#dispatch({
+                    type: 'tool-update',
+                    id: callId,
+                    output: [],
+                });
+            }
+            return errorResult(err);
+        }
+    }
+}
+function resolveConfig(options) {
+    const tools = new Map(Object.entries(options.tools ?? {}));
+    const removed = [];
+    const asking = [];
+    const replaced = {};
+    for (const [key, setting] of Object.entries(options.coreTools ?? {})) {
+        if (setting === undefined || setting === true)
+            continue;
+        if (setting === false)
+            removed.push(key);
+        else if (setting === 'ask')
+            asking.push(key);
+        else {
+            tools.set(key, setting);
+            replaced[key] = key;
+        }
+    }
+    const instructions = Array.isArray(options.instructions)
+        ? options.instructions.filter(Boolean).join('\n\n')
+        : (options.instructions ?? '');
+    return {
+        cwd: options.cwd ?? process.cwd(),
+        folders: options.folders ?? [],
+        instructions,
+        ...(options.systemPrompt !== undefined
+            ? { systemPrompt: options.systemPrompt }
+            : {}),
+        removed,
+        asking,
+        replaced,
+        tools,
+        permissions: options.permissions ?? 'ask',
+        ...(options.model ? { model: options.model } : {}),
+        ...(options.mode ? { mode: options.mode } : {}),
+        ...(options.resume ? { resume: options.resume } : {}),
+        settings: options.settings ?? 'cli',
+        driverOptions: options.driverOptions ?? {},
+    };
+}
+async function loadDriver(agent) {
+    if (agent && typeof agent === 'object')
+        return agent;
+    // A dynamic import, so a bundle that never names Claude carries none of it.
+    const { claudeDriver } = await import('../drivers/claude/index.js');
+    return claudeDriver();
+}
+//# sourceMappingURL=session.js.map