maka-agent 0.2.0-dev.42.20260918 → 0.2.0-dev.43.20260919

package/dist/acp/maka-acp-agent.js

@@ -18,19 +18,30 @@
  */
 import { agent, methods } from '@agentclientprotocol/sdk';
 export function createMakaAcpAgent(options) {
+    let clientCapabilities = {};
     return agent({ name: 'maka' })
-        .onRequest(methods.agent.initialize, () => ({
-        protocolVersion: 1,
-        agentCapabilities: { sessionCapabilities: { list: {}, close: {} } },
-        authMethods: [],
-        agentInfo: { name: 'maka', title: 'Maka', version: options.version },
-    }))
+        .onRequest(methods.agent.initialize, ({ params }) => {
+        clientCapabilities = structuredClone(params.clientCapabilities ?? {});
+        return {
+            protocolVersion: 1,
+            agentCapabilities: { sessionCapabilities: { list: {}, close: {} } },
+            authMethods: [],
+            agentInfo: { name: 'maka', title: 'Maka', version: options.version },
+        };
+    })
         .onRequest(methods.agent.session.new, ({ params }) => options.sessionRegistry.create(params))
         .onRequest(methods.agent.session.list, ({ params }) => options.sessionRegistry.list(params))
         .onRequest(methods.agent.session.setConfigOption, ({ params }) => options.sessionRegistry.setConfigOption(params))
         .onRequest(methods.agent.session.prompt, ({ params, signal, client }) => options.sessionRegistry.prompt(params, {
         signal,
         notify: (notification) => client.notify(methods.client.session.update, notification),
+        interactions: {
+            capabilities: clientCapabilities,
+            requestPermission: (params, cancellationSignal) => client.request(methods.client.session.requestPermission, params, {
+                cancellationSignal,
+            }),
+            createElicitation: (params, cancellationSignal) => client.request(methods.client.elicitation.create, params, { cancellationSignal }),
+        },
     }))
         .onNotification(methods.agent.session.cancel, ({ params }) => options.sessionRegistry.cancel(params))
         .onRequest(methods.agent.session.close, ({ params }) => options.sessionRegistry.close(params));

package/dist/acp/session-event-mapper.js

@@ -84,6 +84,12 @@ export class AcpSessionEventMapper {
     finishTools(turnId, terminalStatus = 'completed') {
         return this.#enqueue(() => this.#tools.finishTools(turnId, terminalStatus));
     }
+    pendingInteraction(pending) {
+        return this.#enqueue(() => this.#tools.pendingInteraction(pending));
+    }
+    resolvedInteraction(resolved, pending) {
+        return this.#enqueue(() => this.#tools.resolvedInteraction(resolved, pending));
+    }
     /** Waits until every notification already accepted by this mapper has settled. */
     flush() {
         return this.#tail.then(() => {

package/dist/acp/session-interactions.js

@@ -0,0 +1,520 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { RequestError, } from '@agentclientprotocol/sdk';
+import { decodeInteractionAnswer, isInteractionAnswerValidForRequest, INTERACTION_ANSWER_MAX_BYTES, INTERACTION_ANSWER_SERIALIZED_MAX_BYTES, } from '@maka/core/interaction';
+import { RuntimeHostOperationError } from '@maka/runtime-host/client';
+import { INTERACTION_MAX_PENDING_PER_SESSION, } from '@maka/runtime-host/protocol';
+import { whileActive } from './active-promise.js';
+// JSON Schema maxLength counts Unicode characters, while Core limits UTF-8
+// bytes per answer and for the whole answer object. A character can occupy
+// four UTF-8 bytes or six bytes when JSON-escaped (e.g. a control character).
+function questionAnswerMaxChars(count) {
+    const envelopeBytes = Buffer.byteLength(JSON.stringify({ kind: 'question', answers: Array(count).fill('') }));
+    return Math.min(Math.floor(INTERACTION_ANSWER_MAX_BYTES / 4), Math.floor((INTERACTION_ANSWER_SERIALIZED_MAX_BYTES - envelopeBytes) / (count * 6)));
+}
+/** Connection-local presentation of Host interactions; the Host owns every answer and grant. */
+export class AcpSessionInteractions {
+    #options;
+    #lifetime = new AbortController();
+    #pending = new Map();
+    #resolving = new Map();
+    #published = new Set();
+    #cancelledTurns = new Set();
+    #cancelledInteractions = new Set();
+    constructor(options) {
+        this.#options = options;
+    }
+    pending(snapshot) {
+        if (this.#lifetime.signal.aborted) {
+            return Promise.resolve();
+        }
+        if (this.#cancelledTurns.has(snapshot.turnId) ||
+            this.#cancelledInteractions.has(snapshot.interactionId)) {
+            this.#cancelledInteractions.add(snapshot.interactionId);
+            return Promise.resolve();
+        }
+        const existing = this.#pending.get(snapshot.interactionId);
+        if (existing)
+            return existing.task;
+        if (snapshot.sessionId !== this.#options.sessionId) {
+            this.#fail(snapshot, interactionError(snapshot, 'invalid_interaction', 'Wrong Session'));
+            return Promise.resolve();
+        }
+        if (this.#pending.size >= INTERACTION_MAX_PENDING_PER_SESSION) {
+            this.#fail(snapshot, interactionError(snapshot, 'interaction_capacity_exceeded'));
+            return Promise.resolve();
+        }
+        const entry = {
+            snapshot,
+            cancellation: new AbortController(),
+            task: Promise.resolve(),
+        };
+        this.#pending.set(snapshot.interactionId, entry);
+        entry.task = this.#present(entry)
+            .catch((error) => {
+            if (!entry.cancellation.signal.aborted)
+                this.#fail(snapshot, error);
+        })
+            .finally(() => {
+            if (this.#pending.get(snapshot.interactionId) === entry) {
+                this.#pending.delete(snapshot.interactionId);
+            }
+        });
+        return entry.task;
+    }
+    resolved(pending) {
+        if (pending.sessionId !== this.#options.sessionId) {
+            this.#fail(pending, interactionError(pending, 'invalid_interaction', 'Wrong Session'));
+            return Promise.resolve();
+        }
+        this.#retire(pending.interactionId);
+        if (this.#lifetime.signal.aborted || this.#published.has(pending.interactionId)) {
+            this.#retireCancelledInteraction(pending);
+            return Promise.resolve();
+        }
+        const existing = this.#resolving.get(pending.interactionId);
+        if (existing)
+            return existing;
+        if (this.#resolving.size >= INTERACTION_MAX_PENDING_PER_SESSION) {
+            this.#fail(pending, interactionError(pending, 'interaction_capacity_exceeded'));
+            this.#retireCancelledInteraction(pending);
+            return Promise.resolve();
+        }
+        const task = this.#readResolved(pending)
+            .catch((error) => this.#fail(pending, error))
+            .finally(() => {
+            if (this.#resolving.get(pending.interactionId) === task) {
+                this.#resolving.delete(pending.interactionId);
+            }
+            this.#retireCancelledInteraction(pending);
+        });
+        this.#resolving.set(pending.interactionId, task);
+        return task;
+    }
+    cancelTurn(turnId) {
+        this.#cancelledTurns.add(turnId);
+        for (const entry of this.#pending.values()) {
+            if (entry.snapshot.turnId !== turnId)
+                continue;
+            this.#cancelledInteractions.add(entry.snapshot.interactionId);
+            this.#retire(entry.snapshot.interactionId);
+        }
+    }
+    fencesTurn(turnId) {
+        return this.#cancelledTurns.has(turnId);
+    }
+    /** Local prompt settlement cannot prove the Host Turn is terminal after a failed Stop. */
+    settleTurn(turnId) {
+        for (const entry of this.#pending.values()) {
+            if (entry.snapshot.turnId === turnId)
+                this.#retire(entry.snapshot.interactionId);
+        }
+        // Keep cancelled Turns fenced until an authoritative terminal observation
+        // or attachment closure. A new interaction ID may arrive after Stop fails.
+    }
+    terminalTurn(turnId) {
+        this.#cancelledTurns.delete(turnId);
+    }
+    close() {
+        if (this.#lifetime.signal.aborted)
+            return;
+        this.#lifetime.abort();
+        for (const id of this.#pending.keys())
+            this.#retire(id);
+        this.#resolving.clear();
+        this.#published.clear();
+        this.#cancelledTurns.clear();
+        this.#cancelledInteractions.clear();
+    }
+    async #present(entry) {
+        const pending = entry.snapshot;
+        const signal = entry.cancellation.signal;
+        // A replayed pending snapshot can outlive an answer. Re-query the existing
+        // authority before opening another dialog rather than retaining an unbounded history.
+        const queried = await whileActive(this.#query(pending), signal);
+        if (!queried.active)
+            return;
+        assertSameInteraction(pending, queried.value);
+        if (queried.value.status !== 'pending') {
+            await this.#publishResolved(queried.value, pending, signal);
+            return;
+        }
+        const request = pending.request;
+        if ((request.kind === 'question' || request.kind === 'form') &&
+            this.#options.client.capabilities.elicitation?.form == null) {
+            throw interactionError(pending, 'unsupported_interaction', 'Client requires form elicitation');
+        }
+        const presented = await whileActive(Promise.resolve().then(() => {
+            if (!signal.aborted)
+                return this.#options.onPending(pending);
+        }), signal);
+        if (!presented.active)
+            return;
+        let answer;
+        if (request.kind === 'question' || request.kind === 'form') {
+            const response = await whileActive(this.#options.client.createElicitation(elicitationRequest(pending), signal), signal);
+            if (!response.active)
+                return;
+            if (request.kind === 'question' && response.value.action === 'cancel') {
+                this.#cancelPendingTurn(pending);
+                return;
+            }
+            try {
+                answer = elicitationAnswer(pending, response.value);
+            }
+            catch (error) {
+                if (error instanceof RequestError)
+                    throw error;
+                throw interactionError(pending, 'invalid_interaction_answer');
+            }
+        }
+        else {
+            const presentation = permissionPresentation(pending);
+            const response = await whileActive(this.#options.client.requestPermission(presentation.request, signal), signal);
+            if (!response.active)
+                return;
+            if (response.value.outcome.outcome === 'cancelled') {
+                this.#cancelPendingTurn(pending);
+                return;
+            }
+            const optionId = response.value.outcome.optionId;
+            const selected = presentation.answers.get(optionId);
+            if (!selected) {
+                throw interactionError(pending, 'invalid_interaction_answer', 'Unknown permission option');
+            }
+            answer = selected;
+        }
+        try {
+            answer = decodeInteractionAnswer(answer);
+            if (!isInteractionAnswerValidForRequest(pending.request, answer))
+                throw new Error();
+        }
+        catch {
+            throw interactionError(pending, 'invalid_interaction_answer');
+        }
+        if (signal.aborted)
+            return;
+        try {
+            const answered = await whileActive(this.#options.connection.request('interaction.answer', {
+                sessionId: pending.sessionId,
+                interactionId: pending.interactionId,
+                answer,
+            }), signal);
+            if (answered.active)
+                await this.#publishResolved(answered.value, pending, signal);
+        }
+        catch (error) {
+            if (!(error instanceof RuntimeHostOperationError) || error.code !== 'already_resolved') {
+                throw error;
+            }
+            await this.#readResolved(pending, signal);
+        }
+    }
+    #query(pending) {
+        return this.#options.connection.request('interaction.query', {
+            sessionId: pending.sessionId,
+            interactionId: pending.interactionId,
+        });
+    }
+    async #readResolved(pending, signal = this.#lifetime.signal) {
+        const active = AbortSignal.any([signal, this.#lifetime.signal]);
+        const queried = await whileActive(this.#query(pending), active);
+        if (!queried.active)
+            return;
+        assertSameInteraction(pending, queried.value);
+        if (queried.value.status !== 'pending') {
+            await this.#publishResolved(queried.value, pending, active);
+        }
+    }
+    async #publishResolved(resolved, pending, signal = this.#lifetime.signal) {
+        const active = AbortSignal.any([signal, this.#lifetime.signal]);
+        if (active.aborted || this.#published.has(pending.interactionId))
+            return;
+        assertSameInteraction(pending, resolved);
+        this.#published.add(pending.interactionId);
+        // Keep replay deduplication bounded for a long-lived attachment. IDs older
+        // than this window may be projected again only if the Host replays a
+        // pathologically old resolved event.
+        if (this.#published.size > INTERACTION_MAX_PENDING_PER_SESSION) {
+            const oldest = this.#published.values().next();
+            if (!oldest.done)
+                this.#published.delete(oldest.value);
+        }
+        if (resolved.status === 'answered')
+            this.#options.onAnswered(resolved, pending);
+        await whileActive(Promise.resolve().then(() => {
+            if (!active.aborted)
+                return this.#options.onResolved(resolved, pending);
+        }), active);
+    }
+    #retire(interactionId) {
+        const entry = this.#pending.get(interactionId);
+        this.#pending.delete(interactionId);
+        entry?.cancellation.abort();
+    }
+    #retireCancelledInteraction(pending) {
+        this.#cancelledInteractions.delete(pending.interactionId);
+    }
+    #cancelPendingTurn(pending) {
+        this.cancelTurn(pending.turnId);
+        this.#options.onCancelled(pending);
+    }
+    #fail(pending, error) {
+        if (this.#lifetime.signal.aborted)
+            return;
+        let failure;
+        if (error instanceof RuntimeHostOperationError) {
+            failure = RequestError.internalError({ source: 'runtime_host', operation: error.operation, code: error.code }, 'Runtime Host interaction failed');
+        }
+        else if (error instanceof RequestError && error.code !== -32601) {
+            failure = error;
+        }
+        else {
+            failure = interactionError(pending, error instanceof RequestError ? 'unsupported_interaction' : 'interaction_failed');
+        }
+        this.#options.onFailure(pending, failure);
+    }
+}
+function elicitationRequest(pending) {
+    const request = pending.request;
+    if (request.kind !== 'question' && request.kind !== 'form')
+        throw new Error('Not a form');
+    const properties = Object.create(null);
+    const required = [];
+    if (request.kind === 'question') {
+        const maxChars = questionAnswerMaxChars(request.questions.length);
+        request.questions.forEach((question, index) => {
+            properties[`q${index}`] = {
+                type: 'string',
+                title: question.question,
+                description: [
+                    ...question.options.map((option) => option.description ? `${option.label}: ${option.description}` : option.label),
+                    'Enter an option or your own answer. Leave empty to skip this question.',
+                    `Limit: ${maxChars} characters (${INTERACTION_ANSWER_MAX_BYTES} UTF-8 bytes per answer).`,
+                ].join('\n'),
+                maxLength: maxChars,
+            };
+        });
+    }
+    else {
+        for (const field of request.fields) {
+            properties[field.name] = formProperty(field);
+            if (field.required)
+                required.push(field.name);
+        }
+    }
+    return {
+        sessionId: pending.sessionId,
+        toolCallId: request.toolUseId,
+        mode: 'form',
+        message: request.kind === 'question'
+            ? 'Please answer the following questions.'
+            : `${request.requester.name}${request.requester.source ? ` (${request.requester.source})` : ''}: ${request.message}`,
+        requestedSchema: { type: 'object', properties, required },
+    };
+}
+function formProperty(field) {
+    const base = {
+        title: field.label,
+        ...(field.description === undefined ? {} : { description: field.description }),
+        ...(field.default === undefined ? {} : { default: structuredClone(field.default) }),
+    };
+    switch (field.kind) {
+        case 'string':
+            return {
+                ...base,
+                type: 'string',
+                ...(field.minLength === undefined ? {} : { minLength: field.minLength }),
+                ...(field.maxLength === undefined ? {} : { maxLength: field.maxLength }),
+                ...(field.format === undefined ? {} : { format: field.format }),
+            };
+        case 'number':
+            return {
+                ...base,
+                type: 'number',
+                ...(field.minimum === undefined ? {} : { minimum: field.minimum }),
+                ...(field.maximum === undefined ? {} : { maximum: field.maximum }),
+            };
+        case 'integer':
+            return {
+                ...base,
+                type: 'integer',
+                minimum: Math.max(Number.MIN_SAFE_INTEGER, Math.ceil(field.minimum ?? Number.MIN_SAFE_INTEGER)),
+                maximum: Math.min(Number.MAX_SAFE_INTEGER, Math.floor(field.maximum ?? Number.MAX_SAFE_INTEGER)),
+            };
+        case 'boolean':
+            return { ...base, type: 'boolean' };
+        case 'single_select':
+            return {
+                ...base,
+                type: 'string',
+                oneOf: field.options.map((option) => ({ const: option.value, title: option.label })),
+            };
+        case 'multi_select':
+            return {
+                ...base,
+                type: 'array',
+                items: {
+                    anyOf: field.options.map((option) => ({ const: option.value, title: option.label })),
+                },
+                ...(field.minItems === undefined ? {} : { minItems: field.minItems }),
+                ...(field.maxItems === undefined ? {} : { maxItems: field.maxItems }),
+            };
+    }
+}
+function elicitationAnswer(pending, response) {
+    const request = pending.request;
+    const action = response.action;
+    if (action !== 'accept' && action !== 'decline' && action !== 'cancel') {
+        throw interactionError(pending, 'invalid_interaction_answer', 'Unknown elicitation action');
+    }
+    if (request.kind === 'form') {
+        return decodeInteractionAnswer(action === 'accept'
+            ? { kind: 'form', action, values: response.content ?? {} }
+            : { kind: 'form', action });
+    }
+    if (request.kind !== 'question')
+        throw new Error('Not a question');
+    if (response.action === 'cancel') {
+        throw interactionError(pending, 'invalid_interaction_answer', 'Question cancellation escaped');
+    }
+    if (response.action === 'decline') {
+        return { kind: 'question', answers: request.questions.map(() => null) };
+    }
+    if (response.action !== 'accept') {
+        throw interactionError(pending, 'invalid_interaction_answer', 'Unknown elicitation action');
+    }
+    const content = response.content ?? {};
+    if (typeof content !== 'object' ||
+        Array.isArray(content) ||
+        Object.keys(content).some((key) => !request.questions.some((_, index) => key === `q${index}`))) {
+        throw interactionError(pending, 'invalid_interaction_answer', 'Invalid question fields');
+    }
+    return {
+        kind: 'question',
+        answers: request.questions.map((_, index) => {
+            const value = content[`q${index}`];
+            if (value === undefined)
+                return null;
+            if (typeof value !== 'string') {
+                throw interactionError(pending, 'invalid_interaction_answer', 'Question answer is not text');
+            }
+            return value.trim() || null;
+        }),
+    };
+}
+function permissionPresentation(pending) {
+    const request = pending.request;
+    if (request.kind !== 'permission' &&
+        request.kind !== 'sandbox_boundary' &&
+        request.kind !== 'client_capability') {
+        throw new Error('Not a permission request');
+    }
+    const allow = randomUUID();
+    const deny = randomUUID();
+    if (request.kind === 'permission') {
+        const canRemember = request.prompt.kind === 'tool_permission' && request.prompt.rememberForTurnAllowed;
+        const options = [
+            { optionId: allow, name: 'Allow once', kind: 'allow_once' },
+        ];
+        const answers = new Map([
+            [allow, { kind: 'permission', decision: 'allow', rememberForTurn: false }],
+        ]);
+        if (canRemember) {
+            const remember = randomUUID();
+            options.push({ optionId: remember, name: 'Allow for this Turn', kind: 'allow_always' });
+            answers.set(remember, { kind: 'permission', decision: 'allow', rememberForTurn: true });
+        }
+        options.push({ optionId: deny, name: 'Reject', kind: 'reject_once' });
+        answers.set(deny, { kind: 'permission', decision: 'deny', rememberForTurn: false });
+        return {
+            request: {
+                sessionId: pending.sessionId,
+                toolCall: {
+                    toolCallId: request.toolUseId,
+                    title: `Authorize ${request.prompt.toolName}`,
+                    status: 'pending',
+                    content: [
+                        {
+                            type: 'content',
+                            content: {
+                                type: 'text',
+                                text: `Review this exact permission request:\n${JSON.stringify(request.prompt, null, 2)}`,
+                            },
+                        },
+                    ],
+                },
+                options,
+            },
+            answers,
+        };
+    }
+    const boundary = request.kind === 'sandbox_boundary';
+    return {
+        request: {
+            sessionId: pending.sessionId,
+            toolCall: {
+                toolCallId: boundary ? pending.interactionId : request.toolUseId,
+                title: boundary
+                    ? 'Expand this Session’s sandbox boundary'
+                    : 'Authorize a Session capability',
+                status: 'pending',
+                content: [
+                    {
+                        type: 'content',
+                        content: {
+                            type: 'text',
+                            text: boundary
+                                ? `${request.justification}\n\nApply only this requested expansion to this Session’s boundary:\n${JSON.stringify(request.expansion, null, 2)}`
+                                : `Grant only the following exact capability target for this Session:\n${JSON.stringify(request.target, null, 2)}`,
+                        },
+                    },
+                ],
+            },
+            options: [
+                {
+                    optionId: allow,
+                    name: boundary
+                        ? 'Apply this expansion to this Session'
+                        : 'Allow this scope for this Session',
+                    kind: 'allow_always',
+                },
+                { optionId: deny, name: 'Reject', kind: 'reject_once' },
+            ],
+        },
+        answers: new Map([
+            [allow, { kind: request.kind, decision: 'allow' }],
+            [deny, { kind: request.kind, decision: 'deny' }],
+        ]),
+    };
+}
+function assertSameInteraction(pending, actual) {
+    if (pending.interactionId !== actual.interactionId ||
+        pending.sessionId !== actual.sessionId ||
+        pending.turnId !== actual.turnId ||
+        pending.runId !== actual.runId ||
+        !isDeepStrictEqual(pending.request, actual.request)) {
+        throw interactionError(pending, 'invalid_interaction', 'Host interaction identity changed');
+    }
+}
+function interactionError(pending, code, detail) {
+    return RequestError.internalError({ source: 'adapter', code, kind: pending.request.kind, interactionId: pending.interactionId }, detail ? `ACP interaction failed: ${detail}` : 'ACP interaction failed');
+}