@agentshouse/kit 0.1.0-alpha.9 → 0.2.1-alpha.1

package/dist/conversations.js

@@ -0,0 +1,538 @@
+import { client, } from '@agentclientprotocol/sdk';
+import { randomUUID } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { killMarked, startAdapter, TURN_ENDED, TURN_STARTED } from './acp.js';
+import { blocksOf, firstChange } from './blocks.js';
+import { openBridge } from './bridge.js';
+import { CLIS } from './clis.js';
+import { placeFiles } from './files.js';
+import { instructions } from './instructions.js';
+import { holdSecretInput } from './secret-input.js';
+const LAUNCH_BASE = '/agents/house';
+const KILLED = 'the conversation was killed';
+function causeOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function logged(error) {
+    process.stderr.write(`kit: ${causeOf(error)}\n`);
+}
+function unlessKilled(work, signal) {
+    return new Promise((resolve, reject) => {
+        const killed = () => reject(signal.reason);
+        signal.addEventListener('abort', killed, { once: true });
+        if (signal.aborted)
+            killed();
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', killed));
+    });
+}
+function stop(bridge) {
+    killMarked(`HOUSE_BRIDGE=${bridge.env.HOUSE_BRIDGE}`);
+}
+class Turn {
+    id = randomUUID();
+    text = '';
+    sent = [];
+    unsentFrom = null;
+    draftSequence = 0;
+    planSequence = 0;
+    questions = 0;
+    secrets = 0;
+    prompt = null;
+    ended = false;
+    ready = Promise.resolve();
+}
+class Conversation {
+    id;
+    running = null;
+    turn = null;
+    commands = null;
+    jobs = new Set();
+    queued = [];
+    late = [];
+    opening = null;
+    kills = 0;
+    killed = new AbortController();
+    open = 0;
+    queue = Promise.resolve();
+    reports = Promise.resolve();
+    constructor(id) {
+        this.id = id;
+    }
+}
+function formProperties(request) {
+    if (request.mode !== 'form')
+        return {};
+    return request.requestedSchema?.properties ?? {};
+}
+function asksSecret(request) {
+    return Object.values(formProperties(request)).some((property) => Object.values(property._meta ?? {}).some((meta) => typeof meta === 'object' && meta !== null && meta.isSecret === true));
+}
+export class Conversations {
+    kit;
+    conversations = new Map();
+    acks = new Map();
+    questions = new Map();
+    carrying = 0;
+    reporting = 0;
+    constructor(kit) {
+        this.kit = kit;
+    }
+    input(input) {
+        this.carrying++;
+        const carried = this.acks.get(input.input_id) ??
+            (() => {
+                const conversation = this.conversation(input.conversation_id);
+                if (input.kind === 'kill') {
+                    conversation.kills++;
+                    conversation.killed.abort(new Error(KILLED));
+                    this.halt(conversation);
+                }
+                const work = conversation.queue.then(() => this.carry(conversation, input));
+                conversation.queue = work.catch(() => undefined);
+                this.acks.set(input.input_id, work);
+                return work;
+            })();
+        carried
+            .then((body) => this.kit.house.deliver(`/kit/inputs/${input.input_id}/ack`, body))
+            .catch(logged)
+            .finally(() => {
+            this.carrying--;
+            this.kit.changed();
+        });
+    }
+    idle() {
+        if (this.carrying > 0 || this.reporting > 0)
+            return false;
+        for (const conversation of this.conversations.values()) {
+            const turn = conversation.turn;
+            const asking = turn !== null && turn.questions > 0 && turn.secrets === 0;
+            if (conversation.jobs.size > 0 || conversation.open > (asking ? 1 : 0))
+                return false;
+        }
+        return true;
+    }
+    opened() {
+        for (const conversation of this.conversations.values()) {
+            if (conversation.turn !== null)
+                conversation.turn.unsentFrom = 0;
+        }
+    }
+    conversation(id) {
+        let conversation = this.conversations.get(id);
+        if (conversation === undefined) {
+            conversation = new Conversation(id);
+            this.conversations.set(id, conversation);
+        }
+        return conversation;
+    }
+    async carry(conversation, input) {
+        if (input.kind === 'open')
+            return this.open(conversation, input);
+        if (input.kind === 'message')
+            return this.message(conversation, input);
+        if (input.kind === 'interrupt')
+            await this.interrupt(conversation, String(input.turn_id));
+        if (input.kind === 'kill') {
+            await this.kill(conversation);
+            if (--conversation.kills === 0)
+                conversation.killed = new AbortController();
+        }
+        if (input.kind === 'option')
+            await this.option(conversation, String(input.option), input.value);
+        if (input.kind === 'answer')
+            this.questions.get(String(input.interaction_id))?.answer(input.response);
+        return {};
+    }
+    async open(conversation, input) {
+        if (conversation.running !== null)
+            return {};
+        try {
+            return { provider_session_id: await this.start(conversation, await this.route(conversation, input.agent_id), null) };
+        }
+        catch (error) {
+            return { refused: causeOf(error) };
+        }
+    }
+    async message(conversation, input) {
+        let ack = {};
+        const prompt = [];
+        try {
+            const route = await this.route(conversation, input.agent_id);
+            const paths = await placeFiles(this.kit.house, route.working_directory, input.files, conversation.killed.signal);
+            if (conversation.running === null) {
+                const opened = await this.start(conversation, route, input.provider_session_id);
+                if (input.provider_session_id === null)
+                    ack = { provider_session_id: opened };
+            }
+            if (input.first === true) {
+                prompt.push({ type: 'text', text: await instructions(conversation.running.bridge, route.base_instructions) });
+            }
+            prompt.push({ type: 'text', text: String(input.text) });
+            if (paths.length > 0)
+                prompt.push({ type: 'text', text: paths.join('\n') });
+            if (conversation.kills > 0)
+                throw new Error(KILLED);
+        }
+        catch (error) {
+            if ('provider_session_id' in ack)
+                await this.kill(conversation);
+            return { refused: conversation.kills > 0 ? KILLED : causeOf(error) };
+        }
+        this.prompt(conversation, prompt);
+        return ack;
+    }
+    async interrupt(conversation, turnId) {
+        if (conversation.running === null || conversation.turn?.id !== turnId)
+            return;
+        await conversation.running.adapter.connection.agent.notify('session/cancel', {
+            sessionId: conversation.running.sessionId,
+        });
+    }
+    halt(conversation) {
+        if (conversation.opening !== null)
+            stop(conversation.opening);
+        if (conversation.running === null)
+            return;
+        conversation.running.killed = true;
+        stop(conversation.running.bridge);
+    }
+    async kill(conversation) {
+        const running = conversation.running;
+        this.halt(conversation);
+        await running?.adapter.exited;
+    }
+    async option(conversation, option, value) {
+        const running = conversation.running;
+        if (running === null)
+            return;
+        try {
+            const answered = await running.adapter.connection.agent.request('session/set_config_option', {
+                sessionId: running.sessionId,
+                configId: option,
+                ...(typeof value === 'boolean' ? { type: 'boolean', value } : { value: String(value) }),
+            });
+            this.options(conversation, answered.configOptions);
+        }
+        catch (error) {
+            logged(error);
+        }
+    }
+    async route(conversation, agentId) {
+        const signal = conversation.killed.signal;
+        await unlessKilled(this.kit.agents.read(), signal);
+        if (this.kit.agents.route(agentId) === undefined)
+            await unlessKilled(this.kit.agents.refresh(), signal);
+        const route = this.kit.agents.route(agentId);
+        if (route === undefined)
+            throw new Error(`this Environment hosts no Agent ${agentId}`);
+        if (route.working_directory === join(LAUNCH_BASE, route.agent_id)) {
+            await mkdir(route.working_directory, { recursive: true });
+        }
+        return route;
+    }
+    async start(conversation, route, sessionId) {
+        const app = client({ name: '@agentshouse/kit' })
+            .onNotification('session/update', ({ params }) => this.update(conversation, params))
+            .onNotification(TURN_STARTED, (params) => params, () => void this.started(conversation))
+            .onNotification(TURN_ENDED, (params) => params, () => this.ended(conversation))
+            .onRequest('session/request_permission', ({ params, signal }) => this.ask(conversation, 'session/request_permission', params, false, signal))
+            .onRequest('elicitation/create', ({ params, signal }) => this.ask(conversation, 'elicitation/create', params, asksSecret(params), signal));
+        await unlessKilled(this.kit.agents.installed(), conversation.killed.signal);
+        const bridge = await openBridge(this.kit.house, conversation.id, conversation.killed.signal);
+        if (conversation.kills > 0) {
+            bridge.close();
+            throw new Error(KILLED);
+        }
+        conversation.opening = bridge;
+        try {
+            const adapter = await startAdapter(route.kind, route.working_directory, app, (job) => this.job(conversation, job), { ...process.env, ...bridge.env });
+            void adapter.exited.then(() => bridge.close());
+            const agent = adapter.connection.agent;
+            const cwd = route.working_directory;
+            const opened = sessionId === null
+                ? await agent.request('session/new', { cwd, mcpServers: [] })
+                : { ...(await agent.request('session/resume', { sessionId, cwd, mcpServers: [] })), sessionId };
+            const running = {
+                adapter,
+                bridge,
+                sessionId: opened.sessionId,
+                killed: false,
+                queues: CLIS[route.kind].queues,
+            };
+            const options = await this.launchSettings(running, route, opened.configOptions ?? []);
+            conversation.running = running;
+            this.kit.send({ type: 'process', conversation_id: conversation.id, running: true });
+            if (conversation.commands !== null)
+                this.commands(conversation, conversation.commands);
+            this.options(conversation, options);
+            void adapter.exited.then((cause) => this.exited(conversation, adapter, cause));
+            return running.sessionId;
+        }
+        catch (error) {
+            stop(bridge);
+            bridge.close();
+            throw conversation.kills > 0 ? new Error(KILLED) : error;
+        }
+        finally {
+            conversation.opening = null;
+        }
+    }
+    async launchSettings(running, route, offered) {
+        let options = offered;
+        const settings = [
+            ['model', route.model],
+            ['thought_level', route.effort],
+        ];
+        for (const [category, value] of settings) {
+            if (value === null)
+                continue;
+            const option = options.find((candidate) => candidate.category === category);
+            const answered = await running.adapter.connection.agent.request('session/set_config_option', {
+                sessionId: running.sessionId,
+                configId: option?.id ?? category,
+                value,
+            });
+            options = answered.configOptions;
+        }
+        return options;
+    }
+    exited(conversation, adapter, cause) {
+        const running = conversation.running;
+        if (running?.adapter !== adapter)
+            return;
+        conversation.running = null;
+        conversation.commands = null;
+        conversation.jobs.clear();
+        conversation.queued.length = 0;
+        for (const [id, question] of this.questions) {
+            if (question.conversation === conversation)
+                this.questions.delete(id);
+        }
+        this.kit.send({ type: 'process', conversation_id: conversation.id, running: false });
+        if (conversation.turn !== null) {
+            this.end(conversation, conversation.turn, { failed: running.killed ? KILLED : cause });
+        }
+        this.kit.changed();
+    }
+    commands(conversation, commands) {
+        conversation.commands = commands;
+        if (conversation.running === null)
+            return;
+        this.kit.send({ type: 'commands', conversation_id: conversation.id, commands });
+    }
+    options(conversation, options) {
+        if (conversation.running === null)
+            return;
+        this.kit.send({ type: 'options', conversation_id: conversation.id, options });
+    }
+    deliver(conversation, turn, event, body) {
+        this.reporting++;
+        const delivered = conversation.reports.then(() => this.kit.house.deliver(`/kit/conversations/${conversation.id}/turns/${turn.id}/${event}`, body));
+        conversation.reports = delivered
+            .catch(() => undefined)
+            .finally(() => {
+            this.reporting--;
+            this.kit.changed();
+        });
+        return delivered;
+    }
+    report(conversation) {
+        const turn = new Turn();
+        conversation.open++;
+        turn.ready = this.deliver(conversation, turn, 'started', {}).then(() => undefined, logged);
+        return turn;
+    }
+    begin(conversation) {
+        const turn = this.report(conversation);
+        conversation.turn = turn;
+        this.kit.changed();
+        return turn;
+    }
+    end(conversation, turn, outcome) {
+        if (turn.ended)
+            return;
+        turn.ended = true;
+        conversation.open--;
+        if (conversation.turn === turn)
+            conversation.turn = null;
+        void this.deliver(conversation, turn, 'ended', outcome).catch(logged);
+        const late = conversation.open === 0 ? conversation.late.shift() : undefined;
+        if (late !== undefined)
+            this.failed(conversation, late);
+        this.kit.changed();
+    }
+    failed(conversation, cause) {
+        if (conversation.open > 0)
+            conversation.late.push(cause);
+        else
+            this.end(conversation, this.report(conversation), { failed: cause });
+    }
+    prompt(conversation, prompt) {
+        const running = conversation.running;
+        const sent = { turn: null };
+        if (running.queues && (conversation.turn !== null || conversation.queued.length > 0)) {
+            conversation.queued.push(sent);
+        }
+        else {
+            this.attach(conversation.turn ?? this.begin(conversation), sent);
+        }
+        running.adapter.connection.agent.request('session/prompt', { sessionId: running.sessionId, prompt }).then(() => this.answered(conversation, sent, null), async (error) => {
+            if (!running.adapter.connection.signal.aborted)
+                this.answered(conversation, sent, causeOf(error));
+            else if (sent.turn !== null) {
+                this.end(conversation, sent.turn, { failed: running.killed ? KILLED : await running.adapter.exited });
+            }
+        });
+    }
+    attach(turn, sent) {
+        turn.prompt = sent;
+        sent.turn = turn;
+    }
+    answered(conversation, sent, failed) {
+        const turn = sent.turn;
+        if (turn === null) {
+            const queued = conversation.queued.indexOf(sent);
+            if (queued < 0)
+                return;
+            conversation.queued.splice(queued, 1);
+            if (failed !== null)
+                this.failed(conversation, failed);
+        }
+        else if (failed !== null) {
+            if (turn.ended)
+                this.failed(conversation, failed);
+            else
+                this.end(conversation, turn, { failed });
+        }
+        else if (turn.prompt === sent) {
+            this.end(conversation, turn, { text: turn.text });
+        }
+    }
+    started(conversation) {
+        if (conversation.turn !== null)
+            return conversation.turn;
+        const turn = this.begin(conversation);
+        const queued = conversation.queued.shift();
+        if (queued !== undefined)
+            this.attach(turn, queued);
+        return turn;
+    }
+    ended(conversation) {
+        const turn = conversation.turn;
+        if (turn === null)
+            return;
+        if (turn.prompt === null) {
+            this.end(conversation, turn, { text: turn.text });
+        }
+        else {
+            conversation.turn = null;
+            this.kit.changed();
+        }
+    }
+    async ask(conversation, method, params, secret, signal) {
+        const turn = this.started(conversation);
+        const interactionId = randomUUID();
+        const answered = new Promise((answer, fail) => {
+            this.questions.set(interactionId, { conversation, answer: (response) => answer(response) });
+            signal.addEventListener('abort', () => answer(null), { once: true });
+            this.deliver(conversation, turn, 'interactions', {
+                interaction_id: interactionId,
+                request: { method, params },
+                secret,
+            }).then(() => {
+                if (secret)
+                    void this.holdSecret(interactionId, params);
+            }, fail);
+        });
+        turn.questions++;
+        if (secret)
+            turn.secrets++;
+        this.kit.changed();
+        try {
+            const response = await answered;
+            if (response === null)
+                throw signal.reason;
+            return response;
+        }
+        finally {
+            this.questions.delete(interactionId);
+            turn.questions--;
+            if (secret)
+                turn.secrets--;
+            this.kit.changed();
+        }
+    }
+    async holdSecret(interactionId, request) {
+        const steps = Object.entries(formProperties(request)).map(([name, property]) => ({
+            kind: 'collect',
+            label: property.title ?? name,
+            name,
+            ...(property.description ? { description: property.description } : {}),
+        }));
+        const content = await holdSecretInput(this.kit.house, interactionId, steps, () => this.questions.has(interactionId));
+        if (content !== null)
+            this.questions.get(interactionId)?.answer({ action: 'accept', content });
+    }
+    update(conversation, notification) {
+        const update = notification.update;
+        if (update.sessionUpdate === 'agent_message_chunk' && update.content.type === 'text') {
+            const turn = this.started(conversation);
+            turn.text += update.content.text;
+            const text = turn.text;
+            void turn.ready.then(() => this.draft(conversation, turn, text));
+        }
+        else if (update.sessionUpdate === 'plan') {
+            const turn = this.started(conversation);
+            void turn.ready.then(() => this.plan(conversation, turn, update.entries));
+        }
+        else if (update.sessionUpdate === 'agent_thought_chunk' || update.sessionUpdate === 'tool_call') {
+            this.started(conversation);
+        }
+        else if (update.sessionUpdate === 'available_commands_update') {
+            this.commands(conversation, update.availableCommands);
+        }
+        else if (update.sessionUpdate === 'config_option_update') {
+            this.options(conversation, update.configOptions);
+        }
+    }
+    job(conversation, job) {
+        if (job.running)
+            conversation.jobs.add(job.id);
+        else
+            conversation.jobs.delete(job.id);
+        this.kit.changed();
+    }
+    draft(conversation, turn, text) {
+        const blocks = blocksOf(text);
+        const from = Math.min(firstChange(turn.sent, blocks), turn.unsentFrom ?? Infinity);
+        const sent = this.kit.send({
+            type: 'draft',
+            conversation_id: conversation.id,
+            turn_id: turn.id,
+            sequence: turn.draftSequence + 1,
+            from,
+            blocks: blocks.slice(from),
+        });
+        if (sent) {
+            turn.draftSequence++;
+            turn.sent = blocks;
+            turn.unsentFrom = null;
+        }
+        else {
+            turn.unsentFrom = from;
+        }
+    }
+    plan(conversation, turn, entries) {
+        const sent = this.kit.send({
+            type: 'plan',
+            conversation_id: conversation.id,
+            turn_id: turn.id,
+            sequence: turn.planSequence + 1,
+            from: 0,
+            steps: entries.map((entry) => ({ label: entry.content, priority: entry.priority, status: entry.status })),
+        });
+        if (sent)
+            turn.planSequence++;
+    }
+}

package/dist/files.js

@@ -0,0 +1,21 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function placeFiles(house, directory, files, signal) {
+    const paths = [];
+    for (const file of files) {
+        const original = await house.post('/kit/conversation/originals/get', { version: file.version, download: true }, signal);
+        const answer = await fetch(original.download.url, { signal });
+        if (!answer.ok)
+            throw new Error(`${file.name} did not download: ${answer.status}`);
+        const folder = join(directory, '.house', 'files', original.message, file.version);
+        await mkdir(join(directory, '.house')).catch((error) => {
+            if (error.code !== 'EEXIST')
+                throw error;
+        });
+        await mkdir(folder, { recursive: true });
+        const path = join(folder, file.name);
+        await writeFile(path, Buffer.from(await answer.arrayBuffer()));
+        paths.push(path);
+    }
+    return paths;
+}

package/dist/home.js

@@ -0,0 +1,24 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const ENROLMENT = 'credential.json';
+export function kitHome() {
+    return process.env.HOUSE_KIT_HOME ?? join(homedir(), '.house-kit');
+}
+export async function readEnrolment() {
+    try {
+        return JSON.parse(await readFile(join(kitHome(), ENROLMENT), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+export async function writeEnrolment(enrolment) {
+    const home = kitHome();
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    const temporary = join(home, `${ENROLMENT}.${process.pid}`);
+    await writeFile(temporary, `${JSON.stringify(enrolment)}\n`, { mode: 0o600 });
+    await rename(temporary, join(home, ENROLMENT));
+}

package/dist/house-main.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { request } from 'node:http';
+import { basename } from 'node:path';
+const USAGE = "usage: house <tool> ['<arguments as JSON>']";
+const socketPath = process.env.HOUSE_BRIDGE;
+function bridged(path, body) {
+    return new Promise((resolve, reject) => {
+        const sent = request({ socketPath, path, method: 'POST', headers: { 'content-type': 'application/json' } }, (answer) => {
+            let text = '';
+            answer.setEncoding('utf8');
+            answer.on('data', (chunk) => {
+                text += chunk;
+            });
+            answer.on('end', () => {
+                if (answer.statusCode === 200)
+                    resolve(text);
+                else
+                    reject(new Error(`${path} answered ${answer.statusCode}: ${text}`));
+            });
+        });
+        sent.on('error', reject);
+        sent.end(JSON.stringify(body));
+    });
+}
+async function mcp(method, params) {
+    const answer = JSON.parse(await bridged('/', { jsonrpc: '2.0', id: 1, method, params }));
+    if (answer.error !== undefined)
+        throw new Error(answer.error.message);
+    return answer.result;
+}
+async function tools() {
+    return (await mcp('tools/list', {})).tools;
+}
+async function upload(path, roomRef) {
+    const bytes = await readFile(path);
+    const declared = JSON.parse(await bridged('/kit/attachments/upload', {
+        ...(roomRef === undefined ? {} : { room_ref: roomRef }),
+        version: randomUUID(),
+        name: basename(path),
+        bytes: bytes.length,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+    }));
+    const answer = await fetch(declared.upload.url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/octet-stream', 'x-house-byte-operation': declared.upload.operation },
+        body: bytes,
+    });
+    const text = await answer.text();
+    if (!answer.ok)
+        throw new Error(`House refused the bytes of ${path} with ${answer.status}: ${text}`);
+    return text;
+}
+async function house([verb, argument]) {
+    if (verb === undefined || verb === '--help') {
+        return [USAGE, ...(await tools()).map((tool) => `${tool.name}: ${tool.description}`)].join('\n');
+    }
+    if (argument === '--help') {
+        const tool = (await tools()).find((listed) => listed.name === verb);
+        if (tool === undefined)
+            throw new Error(`House has no tool ${verb}`);
+        return `${tool.description}\n${JSON.stringify(tool.inputSchema, null, 2)}`;
+    }
+    const args = (argument === undefined ? {} : JSON.parse(argument));
+    if (verb === 'upload_attachment')
+        return upload(String(args.path), args.room_ref);
+    if (verb === 'append_record' && Array.isArray(args.attachments)) {
+        const attachments = [];
+        for (const path of args.attachments) {
+            attachments.push(JSON.parse(await upload(String(path), args.room_ref)).attachment);
+        }
+        args.attachments = attachments;
+    }
+    const result = await mcp('tools/call', { name: verb, arguments: args });
+    const text = result.content.map((content) => content.text).join('\n');
+    if (result.isError === true)
+        throw new Error(text);
+    return text;
+}
+if (socketPath === undefined) {
+    process.stderr.write('house: house runs inside an Agent conversation\n');
+    process.exitCode = 1;
+}
+else {
+    house(process.argv.slice(2)).then((text) => {
+        process.stdout.write(`${text}\n`);
+    }, (error) => {
+        process.stderr.write(`house: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}