@ai-projector/ide 0.0.0-stage → 0.11.1

package/packages/server/modules/agents/acp/acp-dialect.js

@@ -0,0 +1,82 @@
+/** The message asks the agent to compact its context: the compaction summary is the answer. */
+export function isCompactCommand(message, parts) {
+    return (message.trim().split(/\s+/, 1)[0] === "/compact" ||
+        !!parts?.some((part) => part.type === "command" && part.name?.toLowerCase() === "compact"));
+}
+/** Text of an ACP content block (a string, one block or a list of blocks). */
+function contentText(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value
+            .map((item) => contentText(item?.text ?? ""))
+            .filter(Boolean)
+            .join("");
+    const text = value?.text;
+    return typeof text === "string" ? text : "";
+}
+/** The standard `compaction_update` of ACP v2, which also carries the summary at the end. */
+export function readCompaction(update) {
+    if (update.sessionUpdate !== "compaction_update")
+        return undefined;
+    const id = typeof update.compactionId === "string" ? update.compactionId : undefined;
+    if (update.status === "in_progress")
+        return { ...(id ? { id } : {}), status: "started" };
+    if (update.status === "completed") {
+        const summary = contentText(update.summary).trim();
+        return { ...(id ? { id } : {}), status: "completed", ...(summary ? { summary } : {}) };
+    }
+    if (update.status === "cancelled")
+        return { ...(id ? { id } : {}), status: "cancelled" };
+    if (update.status === "failed") {
+        const error = update.error;
+        const message = typeof error === "string"
+            ? error
+            : typeof error?.message === "string"
+                ? error.message
+                : "";
+        return { ...(id ? { id } : {}), status: "failed", ...(message ? { error: message } : {}) };
+    }
+    return undefined;
+}
+const UUID_V7 = /^([0-9a-f]{8})-?([0-9a-f]{4})-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** The time a UUIDv7 carries in its first 48 bits. */
+export function uuidV7Time(id) {
+    const match = typeof id === "string" ? UUID_V7.exec(id) : null;
+    if (!match)
+        return undefined;
+    const time = parseInt(match[1] + match[2], 16);
+    return time > 0 ? time : undefined;
+}
+/** An agent without extensions: every call is a plain tool call. */
+export function createPlainDialect() {
+    return {
+        tool: (update) => ({ name: String(update.title || update.kind || "tool") }),
+        inner: () => false,
+        chunk: () => undefined,
+        call: () => [],
+        output: () => "",
+        outputChunk: () => "",
+        result: (_update, _id, output) => output,
+        end: () => [],
+        speak: () => [],
+        finish: () => [],
+        time: (update) => uuidV7Time(update.messageId),
+        retry: () => undefined,
+        compaction: readCompaction,
+    };
+}
+/** A dialect that changes only part of the plain one. */
+export function extendPlainDialect(parts) {
+    return { ...createPlainDialect(), ...parts };
+}
+export function inputOf(update) {
+    const input = update.rawInput;
+    return input && typeof input === "object" ? input : {};
+}
+export const isOver = (update) => update.status === "completed" || update.status === "failed";
+/** The last line of what an agent said, cut to fit a row. */
+export function shorten(text, limit = 200) {
+    const line = text.trim().split("\n").at(-1) ?? "";
+    return line.length > limit ? `${line.slice(0, limit)}…` : line;
+}

package/packages/server/modules/agents/acp/acp-elicitation.js

@@ -0,0 +1,135 @@
+const record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+const text = (value, limit) => typeof value === "string" ? value.slice(0, limit) : "";
+/** Choices of a property: `oneOf`/`anyOf` entries with `const`/`title`, or a plain `enum`. */
+function choices(schema) {
+    const entries = [schema.oneOf, schema.anyOf].find(Array.isArray);
+    if (entries)
+        return entries.slice(0, 50).flatMap((entry) => {
+            const item = record(entry);
+            const id = text(item.const, 500);
+            if (!id)
+                return [];
+            const description = text(item.description, 1000);
+            return [{ id, label: text(item.title, 500) || id, ...(description ? { description } : {}) }];
+        });
+    if (Array.isArray(schema.enum))
+        return schema.enum.slice(0, 50).flatMap((value) => {
+            const id = text(value, 500);
+            return id ? [{ id, label: id }] : [];
+        });
+    return [];
+}
+const strippedKey = (key) => key.replace(/_(custom|note)\d*$/, "");
+/** A companion holds the user's own words for the question its key is based on. */
+const isCompanion = (field, properties, forms) => forms
+    ? forms.companion(field, properties)
+    : strippedKey(field.key) !== field.key && strippedKey(field.key) in properties;
+/** The questions of an ACP form (`elicitation/create`, mode `form`). */
+function fieldsOf(requestedSchema, forms) {
+    const properties = record(record(requestedSchema).properties);
+    const required = new Set(Array.isArray(record(requestedSchema).required)
+        ? record(requestedSchema).required
+        : []);
+    const companions = new Map();
+    for (const [key, value] of Object.entries(properties)) {
+        const field = { key, schema: record(value) };
+        if (!isCompanion(field, properties, forms))
+            continue;
+        const base = forms?.baseOf(field) ?? strippedKey(key);
+        if (base in properties)
+            companions.set(base, key);
+    }
+    const companionKeys = new Set(companions.values());
+    return Object.entries(properties)
+        .slice(0, 20)
+        .flatMap(([key, raw]) => {
+        if (companionKeys.has(key))
+            return [];
+        const schema = record(raw);
+        const array = schema.type === "array";
+        let options = choices(array ? record(schema.items) : schema);
+        const type = ["string", "number", "integer", "boolean", "array"].find((item) => item === schema.type);
+        if (!type)
+            return [];
+        if (type === "boolean")
+            options = [
+                { id: "true", label: "Да" },
+                { id: "false", label: "Нет" },
+            ];
+        const title = text(schema.title, 2000) || text(schema.description, 2000) || key;
+        const description = text(schema.description, 300);
+        const companion = companions.get(key);
+        // Only the agent's own dialect knows which option means "none of these".
+        const fallback = companion && forms ? forms.fallbackOption(options) : undefined;
+        return [
+            {
+                type,
+                ...(companion ? { companion } : {}),
+                ...(fallback ? { fallback: fallback.id } : {}),
+                question: {
+                    id: key,
+                    question: title,
+                    ...(description && description !== title ? { header: description } : {}),
+                    options: options.filter((option) => option.id !== fallback?.id),
+                    multiple: array,
+                    // Free text where there are no options, or where the agent made room for it.
+                    custom: !options.length || !!companion,
+                    optional: !required.has(key),
+                },
+            },
+        ];
+    });
+}
+/**
+ * Answers a form the agent opened (`elicitation/create`): the agents' own question tools and MCP
+ * servers' forms. Without the capability or a user, the agent is told nothing was answered.
+ */
+export async function elicitForm(options, params, forms) {
+    if (params.mode !== "form")
+        return { action: "cancel" };
+    const fields = fieldsOf(params.requestedSchema, forms);
+    if (!options.ask || !fields.length)
+        return { action: "cancel" };
+    const message = text(params.message, 300);
+    const answer = await options
+        .ask({
+        ...(message ? { title: message } : {}),
+        questions: fields.map((field) => field.question),
+        custom: false,
+    })
+        .catch(() => undefined);
+    if (answer === undefined)
+        return { action: "cancel" };
+    if (answer === null)
+        return { action: "decline" };
+    const content = {};
+    for (const field of fields) {
+        const given = answer[field.question.id] ?? [];
+        const known = new Set(field.question.options.map((option) => option.id));
+        const picked = given.filter((value) => known.has(value));
+        const own = given
+            .filter((value) => !known.has(value) && value.trim())
+            .join("\n")
+            .trim();
+        if (field.type === "array") {
+            if (picked.length)
+                content[field.question.id] = picked;
+            if (own && field.companion)
+                content[field.companion] = own;
+        }
+        else if (field.question.options.length) {
+            if (picked[0] !== undefined)
+                content[field.question.id] = field.type === "boolean" ? picked[0] === "true" : picked[0];
+            else if (own && field.companion) {
+                content[field.companion] = own;
+                if (field.fallback)
+                    content[field.question.id] = field.fallback;
+            }
+        }
+        else if (own) {
+            const value = field.type === "string" ? own : Number(own);
+            content[field.question.id] = Number.isNaN(value) ? own : value;
+        }
+    }
+    return { action: "accept", content };
+}

package/packages/server/modules/agents/acp/acp-events.js

@@ -0,0 +1,340 @@
+import { createReplay } from "../../agent/index.js";
+import { createPlainDialect, isOver, } from "./acp-dialect.js";
+/**
+ * The slash commands of an `available_commands_update` (or of `session/new` in ACP v2) as the
+ * chat knows them. The list is a full snapshot, so the caller replaces whatever it had.
+ */
+export function availableCommands(list) {
+    const commands = Array.isArray(list) ? list : [];
+    return commands.flatMap((item) => {
+        const { name, description, input } = item;
+        if (typeof name !== "string" || !name)
+            return [];
+        return [
+            {
+                name,
+                ...(typeof description === "string" && description ? { description } : {}),
+                ...(typeof input?.hint === "string" ? { hint: input.hint } : {}),
+            },
+        ];
+    });
+}
+/** ACP stop reasons are a short code; the chat shows a readable sentence. */
+export function stopReasonError(stopReason) {
+    if (stopReason === "max_tokens")
+        return "Достигнут лимит ответа агента";
+    if (stopReason === "max_turn_requests")
+        return "Достигнут лимит шагов агента";
+    if (stopReason === "refusal")
+        return "Агент отказался выполнять запрос";
+    return "Агент завершился с ошибкой";
+}
+export function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content))
+        return content
+            .map((part) => part?.text ?? "")
+            .filter(Boolean)
+            .join("");
+    const block = content;
+    return typeof block?.text === "string" ? block.text : "";
+}
+function toolOutput(update) {
+    // `content` is what the protocol asks clients to display; `rawOutput` is often only metadata
+    // (a status, an exit code), so it is used when the update carries no readable content.
+    const content = Array.isArray(update.content) ? update.content : [];
+    const text = content
+        .map((item) => {
+        const block = item;
+        if (block.type === "content")
+            return contentText(block.content);
+        if (block.type === "diff")
+            return [
+                String(block.path ?? ""),
+                ...(typeof block.oldText === "string"
+                    ? block.oldText.split("\n").map((line) => `- ${line}`)
+                    : []),
+                ...(typeof block.newText === "string"
+                    ? block.newText.split("\n").map((line) => `+ ${line}`)
+                    : []),
+            ].join("\n");
+        return "";
+    })
+        .filter(Boolean)
+        .join("\n");
+    if (text)
+        return text;
+    if (typeof update.rawOutput === "string")
+        return update.rawOutput;
+    if (update.rawOutput != null)
+        return JSON.stringify(update.rawOutput, null, 2);
+    return "";
+}
+/**
+ * Translates ACP `session/update` notifications into the chat's SSE events. Text chunks stream
+ * into the answer; tool calls become chips that resolve on their `tool_call_update`.
+ */
+export function createAcpEventMapper(emit, label, dialect = createPlainDialect(), options = {}) {
+    let text = "";
+    let model = "";
+    const toolNames = new Map();
+    const emitTasks = (patches) => {
+        for (const patch of patches)
+            emit("task", patch);
+    };
+    /** A compaction took the context away: show its progress and keep its result in the chat. */
+    function applyCompaction(compaction) {
+        const inputId = compaction.id ? `compaction:${compaction.id}` : undefined;
+        const note = (message) => emit("input", { text: message, ...(inputId ? { inputId } : {}) });
+        // The compaction is over; the answer (or the next step of it) goes on from here.
+        const done = () => emit("status", { phase: "thinking", provider: label, model });
+        if (compaction.status === "started") {
+            emit("status", { phase: "compacting" });
+            return;
+        }
+        if (compaction.status === "completed") {
+            const summary = compaction.summary?.trim();
+            if (options.compactCommand) {
+                const answer = summary || "Контекст сжат.";
+                text += answer;
+                emit("text", { text: answer });
+            }
+            else
+                note("Контекст сжат");
+            done();
+            return;
+        }
+        if (compaction.status === "cancelled") {
+            note("Сжатие контекста отменено");
+            done();
+            return;
+        }
+        note(compaction.error
+            ? `Не удалось сжать контекст: ${compaction.error}`
+            : "Не удалось сжать контекст");
+        done();
+    }
+    function finishTool(update, id, name) {
+        const output = dialect.output(id) || toolOutput(update);
+        emitTasks(dialect.end(update, id, output));
+        const shown = dialect.result(update, id, output);
+        if (update.status === "failed")
+            emit("tool-result", { id, name, error: shown || "Ошибка инструмента" });
+        else
+            emit("tool-result", { id, name, output: shown });
+    }
+    /** Output that arrives while the call still runs: the chat shows it as it comes. */
+    function streamOutput(update, id) {
+        if (isOver(update))
+            return;
+        const chunk = dialect.outputChunk(update);
+        if (chunk)
+            emit("tool-output", { id, chunk });
+    }
+    function handleUpdate(_sessionId, update) {
+        const kind = update.sessionUpdate;
+        const compaction = dialect.compaction(update);
+        if (compaction) {
+            applyCompaction(compaction);
+            return;
+        }
+        if (kind === "agent_message_chunk") {
+            const chunk = contentText(update.content);
+            if (!chunk)
+                return;
+            // What a subagent says is its progress, not part of the answer.
+            const progress = dialect.chunk(update, chunk);
+            if (progress) {
+                emitTasks(progress);
+                return;
+            }
+            emitTasks(dialect.speak());
+            text += chunk;
+            emit("text", { text: chunk });
+            return;
+        }
+        if (kind === "available_commands_update") {
+            emit("commands", { commands: availableCommands(update.availableCommands) });
+            return;
+        }
+        if (kind === "usage_update") {
+            const { used, size, cost } = update;
+            if (typeof used === "number" && typeof size === "number" && size > 0) {
+                const { amount, currency } = (cost ?? {});
+                emit("context", {
+                    used,
+                    size,
+                    ...(typeof amount === "number" && typeof currency === "string"
+                        ? { cost: { amount, currency } }
+                        : {}),
+                });
+            }
+            return;
+        }
+        if (kind === "session_info_update") {
+            const retry = dialect.retry(update);
+            if (retry === null)
+                emit("status", { phase: "thinking", provider: label, model });
+            else if (retry)
+                emit("status", {
+                    phase: "retrying",
+                    attempt: retry.attempt,
+                    ...(retry.delay !== undefined ? { delay: retry.delay } : {}),
+                    ...(retry.message ? { message: retry.message } : {}),
+                    provider: label,
+                    model,
+                });
+            return;
+        }
+        if (kind === "current_mode_update") {
+            // Native title/mode live on the agent's session list; the chat keeps its own first-message title.
+            return;
+        }
+        if (kind === "agent_thought_chunk") {
+            emit("status", { phase: "thinking", provider: label, model });
+            // A subagent's reasoning is not the answer's.
+            const thought = contentText(update.content);
+            if (thought && !dialect.inner(update))
+                emit("thought", { text: thought });
+            return;
+        }
+        if (kind === "tool_call") {
+            const id = String(update.toolCallId ?? "");
+            if (!id)
+                return;
+            const { name, parent } = dialect.tool(update);
+            toolNames.set(id, name);
+            emit("tool", {
+                id,
+                name,
+                input: update.rawInput && Object.keys(update.rawInput).length
+                    ? update.rawInput
+                    : { title: update.title, kind: update.kind },
+                ...(typeof update.kind === "string" ? { kind: update.kind } : {}),
+                ...(parent ? { parent } : {}),
+            });
+            emitTasks(dialect.call(update, id));
+            streamOutput(update, id);
+            if (update.status === "completed" || update.status === "failed")
+                finishTool(update, id, name);
+            return;
+        }
+        if (kind === "tool_call_update") {
+            const id = String(update.toolCallId ?? "");
+            const name = toolNames.get(id) ?? String(update.title || "tool");
+            // The input often completes after the call began: show it once it is there.
+            const input = update.rawInput;
+            if (input && typeof input === "object" && Object.keys(input).length) {
+                const { parent } = dialect.tool(update);
+                emit("tool", {
+                    id,
+                    name,
+                    input,
+                    ...(typeof update.kind === "string" ? { kind: update.kind } : {}),
+                    ...(parent ? { parent } : {}),
+                });
+            }
+            emitTasks(dialect.call(update, id));
+            streamOutput(update, id);
+            if (update.status === "completed" || update.status === "failed")
+                finishTool(update, id, name);
+        }
+    }
+    return {
+        handleUpdate,
+        /** The answer ended: commands still running will outlive it. */
+        finish: () => emitTasks(dialect.finish()),
+        setModel(name) {
+            model = name;
+        },
+        get text() {
+            return text;
+        },
+    };
+}
+/**
+ * Rebuilds the chat from the updates an agent replays on `session/load`: user and agent message
+ * chunks become turns, tool calls become the chips of the answer they belong to.
+ */
+export function createAcpReplayCollector(backend, sessionId, dialect = createPlainDialect()) {
+    const replay = createReplay(backend, sessionId);
+    function handleUpdate(update) {
+        const kind = update.sessionUpdate;
+        const call = String(update.toolCallId ?? "");
+        const compaction = dialect.compaction(update);
+        if (compaction) {
+            if (compaction.status === "completed")
+                replay.note("Контекст сжат");
+            else if (compaction.status === "failed")
+                replay.note(compaction.error
+                    ? `Не удалось сжать контекст: ${compaction.error}`
+                    : "Не удалось сжать контекст");
+            return;
+        }
+        if (kind === "user_message_chunk" || kind === "agent_message_chunk")
+            replay.mark(dialect.time(update));
+        if (kind === "user_message_chunk")
+            replay.user(contentText(update.content));
+        else if (kind === "agent_message_chunk") {
+            const chunk = contentText(update.content);
+            // The dialect keeps what a subagent said out of the answer.
+            if (!dialect.chunk(update, chunk))
+                replay.text(chunk);
+        }
+        else if (kind === "agent_thought_chunk") {
+            const chunk = contentText(update.content);
+            if (chunk)
+                replay.thought(chunk);
+        }
+        else if (kind === "tool_call") {
+            if (!call)
+                return;
+            const { name, parent } = dialect.tool(update);
+            replay.tool({
+                id: call,
+                name,
+                status: "running",
+                detail: toolDetail(update.rawInput),
+                ...(parent ? { parent } : {}),
+            });
+            dialect.call(update, call);
+            finish(update, call);
+        }
+        else if (kind === "tool_call_update") {
+            if (!call)
+                return;
+            dialect.call(update, call);
+            finish(update, call);
+        }
+    }
+    function finish(update, id) {
+        if (update.status !== "completed" && update.status !== "failed")
+            return;
+        const chip = replay.findTool(id);
+        if (!chip)
+            return;
+        chip.status = update.status === "failed" ? "error" : "done";
+        const output = dialect.result(update, id, dialect.output(id) || toolOutput(update));
+        if (output)
+            chip.detail = output.slice(0, 8000);
+    }
+    return {
+        handleUpdate,
+        get turns() {
+            return replay.turns;
+        },
+    };
+}
+function toolDetail(input) {
+    if (input == null)
+        return "";
+    if (typeof input === "string")
+        return input.slice(0, 8000);
+    try {
+        return JSON.stringify(input, null, 2).slice(0, 8000);
+    }
+    catch {
+        return "";
+    }
+}

package/packages/server/modules/agents/acp/acp-process.js

@@ -0,0 +1,78 @@
+import { agentEnv, assertHostProject, attachHosted, startHosted } from "../../agent/index.js";
+import { os } from "../../../../core/modules/os/index.js";
+import { createAcpConnection, } from "./acp-client.js";
+import { acpProgram } from "./acp-programs.js";
+/** Agent Client Protocol revision this client speaks. */
+const PROTOCOL_VERSION = 1;
+/**
+ * Prefer a globally installed binary. `npx` reads the working directory's `package.json`, so a
+ * project that pins another package manager (`devEngines`/`packageManager`) makes npm refuse to
+ * start; the `npx` fallback therefore runs outside the project. The session still gets the project
+ * through `session/new`, so the agent's own config and files are unaffected.
+ */
+async function resolveLaunch(program, cwd) {
+    // Resolve programs the way a terminal session does, not through the server's own PATH.
+    const env = await os.tools.agentEnv(agentEnv());
+    if (program.binary && os.tools.commandExists(program.binary, env))
+        return { command: program.binary, args: [], cwd, env };
+    if (program.command === "npx")
+        return { command: program.command, args: program.args, cwd: os.dataHome(), env };
+    return { command: program.command, args: program.args, cwd, env };
+}
+/**
+ * Spawns the agent's ACP server for `cwd` and wraps it in a connection; nothing is sent yet.
+ * With a `run` the process is held by a host that outlives this server (see `hosted-process.ts`)
+ * and may be an earlier server's run that is rejoined; without one it is a plain child process.
+ */
+export async function startAcp(id, cwd, handlers, run) {
+    const program = acpProgram(id);
+    if (!cwd)
+        throw new Error(`${program.label} работает внутри проекта: откройте чат в проекте`);
+    await assertHostProject(cwd, program.label);
+    const child = run?.attach
+        ? await attachHosted(run.id)
+        : run
+            ? await startHosted(run.id, await resolveLaunch(program, cwd))
+            : os.tools.spawnAgentProcess(await resolveLaunch(program, cwd));
+    return createAcpConnection(child, { ...handlers, label: program.label });
+}
+/** What the last handshake said about `session/delete`, so the UI does not offer a dead action. */
+const advertisedDelete = new Map();
+export function acpAdvertisedDelete(id) {
+    return advertisedDelete.get(id) === true;
+}
+/** Nested objects of `clientCapabilities` are merged one level; scalars replace. */
+export function mergeClientCapabilities(base, extra) {
+    if (!extra)
+        return base;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(extra)) {
+        const prev = out[key];
+        if (value &&
+            typeof value === "object" &&
+            !Array.isArray(value) &&
+            prev &&
+            typeof prev === "object" &&
+            !Array.isArray(prev))
+            out[key] = { ...prev, ...value };
+        else
+            out[key] = value;
+    }
+    return out;
+}
+export async function initializeAcp(connection, id) {
+    const extra = id ? acpProgram(id).clientCapabilities : undefined;
+    const init = (await connection.request("initialize", {
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: mergeClientCapabilities({
+            fs: { readTextFile: false, writeTextFile: false },
+            terminal: false,
+            // Agents ask their questions through forms; without this they answer for the user.
+            elicitation: { form: {} },
+        }, extra),
+        clientInfo: { name: "projector", title: "Projector", version: "1.0" },
+    }));
+    if (id)
+        advertisedDelete.set(id, !!init.agentCapabilities?.sessionCapabilities?.delete);
+    return init;
+}

package/packages/server/modules/agents/acp/acp-programs.js

@@ -0,0 +1,11 @@
+const programs = new Map();
+/** Adds a program to the ACP runtime; the agent module that declares it does this once. */
+export function registerAcpProgram(program) {
+    programs.set(program.id, program);
+}
+export function acpProgram(id) {
+    const program = programs.get(id);
+    if (!program)
+        throw new Error(`Неизвестный ACP-агент: ${id}`);
+    return program;
+}