@agent-api/app-engine 0.0.1

package/dist/workbench/command-controller.js

@@ -0,0 +1,426 @@
+import { UnknownPresetError } from "./settings-controller.js";
+export function createWorkbenchCommandController(options) {
+    const dispatch = options.engine.dispatch;
+    return {
+        async run(command) {
+            const commandResult = options.engine.handleCommand(command);
+            if (commandResult.handled) {
+                await runEffects(commandResult.effects);
+                return;
+            }
+            switch (command.kind) {
+                case "abort":
+                    if (!options.engine.snapshot().busy) {
+                        dispatch({ type: "message.add", role: "system", text: "No agent turn is running." });
+                        return;
+                    }
+                    await options.turnController.abort("Abort requested.");
+                    return;
+                case "config":
+                    await runConfigCommand(command);
+                    return;
+                case "preset":
+                    await runPresetCommand(command.value);
+                    return;
+                case "summary":
+                    await showSummary();
+                    return;
+                case "search":
+                    await searchWorkdir(command.query);
+                    return;
+                case "new_conversation":
+                    await startNewConversation(command.name);
+                    return;
+                case "switch_conversation":
+                    switchConversation(command.name);
+                    return;
+                case "list_conversations":
+                    await showConversations();
+                    return;
+                case "preview":
+                    showEditPreview();
+                    return;
+                case "apply":
+                    await applyPendingEdit(false);
+                    return;
+                case "apply_all":
+                    await applyPendingEdit(true);
+                    return;
+                case "reject":
+                    rejectPendingEdit();
+                    return;
+            }
+        },
+        runEffects,
+    };
+    async function runEffects(effects) {
+        for (const effect of effects) {
+            switch (effect.type) {
+                case "exit":
+                    options.onExit();
+                    break;
+                case "login":
+                    options.onLogin();
+                    break;
+                case "logout":
+                    dispatch({ type: "activity.add", text: `Logged out: ${options.profileName}` });
+                    options.onLogout();
+                    break;
+                case "delete_profile":
+                    dispatch({ type: "activity.add", level: "warning", text: `Deleting profile: ${options.profileName}` });
+                    await options.onDeleteProfile();
+                    break;
+                case "switch_profile":
+                    options.onSwitchProfile(effect.name);
+                    break;
+                case "show_auth_status":
+                    await showAuthStatus();
+                    break;
+                case "export_transcript":
+                    await exportTranscript(effect);
+                    break;
+                case "clear_preset_tool_catalog_cache":
+                    options.settingsController.clearPresetToolCatalogCache();
+                    break;
+            }
+        }
+    }
+    async function runConfigCommand(command) {
+        const state = options.engine.snapshot();
+        if (!command.field) {
+            dispatch({
+                type: "message.add",
+                role: "system",
+                text: options.settingsController.configText({
+                    profileName: options.profileName,
+                    runPreset: state.runPreset,
+                    runModel: state.runModel,
+                    accessMode: state.accessMode,
+                    contextEnabled: state.contextEnabled,
+                    defaultPreset: state.defaultPreset,
+                    renderMode: state.renderMode,
+                    shellIsolation: state.shellIsolation,
+                }),
+            });
+            return;
+        }
+        if (command.field === "preset") {
+            if (!command.value) {
+                dispatch({
+                    type: "message.add",
+                    role: "system",
+                    text: options.settingsController.defaultPresetHelp(state.defaultPreset),
+                });
+                return;
+            }
+            try {
+                const settings = await options.settingsController.saveDefaultPreset({
+                    value: command.value,
+                    profileName: options.profileName,
+                    options: options.options,
+                });
+                dispatch({ type: "settings.set", settings: { defaultPreset: settings.defaultPreset, runPreset: settings.runPreset } });
+                dispatch({
+                    type: "message.add",
+                    role: "system",
+                    text: settings.message,
+                });
+                dispatch({ type: "activity.add", level: "success", text: settings.activity });
+            }
+            catch (error) {
+                if (error instanceof UnknownPresetError) {
+                    dispatch({
+                        type: "message.add",
+                        role: "system",
+                        text: await presetListText(`Unknown preset: ${error.preset}`),
+                    });
+                    dispatch({ type: "activity.add", level: "warning", text: `Unknown preset: ${error.preset}` });
+                    return;
+                }
+                dispatch({ type: "message.add", role: "system", text: `Could not save default preset: ${userFacingError(error)}` });
+                dispatch({ type: "activity.add", level: "error", text: "Default preset save failed" });
+            }
+        }
+        if (command.field === "isolation") {
+            if (!command.value) {
+                dispatch({
+                    type: "message.add",
+                    role: "system",
+                    text: options.settingsController.shellIsolationHelp(state.shellIsolation),
+                });
+                return;
+            }
+            try {
+                const settings = await options.settingsController.saveShellIsolationMode(command.value);
+                dispatch({ type: "settings.set", settings: { shellIsolation: settings.shellIsolation } });
+                dispatch({ type: "message.add", role: "system", text: settings.message });
+                dispatch({ type: "activity.add", level: "success", text: settings.activity });
+            }
+            catch (error) {
+                dispatch({ type: "message.add", role: "system", text: `Could not save shell isolation mode: ${userFacingError(error)}` });
+                dispatch({ type: "activity.add", level: "error", text: "Shell isolation save failed" });
+            }
+            return;
+        }
+        if (command.field === "isolator") {
+            if (!command.value) {
+                dispatch({
+                    type: "message.add",
+                    role: "system",
+                    text: options.settingsController.isolatorPathHelp(state.shellIsolation),
+                });
+                return;
+            }
+            try {
+                const [subcommand = "", ...rest] = command.value.split(/\s+/);
+                const value = rest.join(" ").trim();
+                const settings = subcommand === "source"
+                    ? await options.settingsController.saveIsolatorSource(value)
+                    : subcommand === "path"
+                        ? await options.settingsController.saveIsolatorPath(value)
+                        : await options.settingsController.saveIsolatorPath(command.value);
+                dispatch({ type: "settings.set", settings: { shellIsolation: settings.shellIsolation } });
+                dispatch({ type: "message.add", role: "system", text: settings.message });
+                dispatch({ type: "activity.add", level: "success", text: settings.activity });
+            }
+            catch (error) {
+                dispatch({ type: "message.add", role: "system", text: `Could not save isolator path: ${userFacingError(error)}` });
+                dispatch({ type: "activity.add", level: "error", text: "Isolator path save failed" });
+            }
+        }
+    }
+    async function runPresetCommand(value) {
+        const state = options.engine.snapshot();
+        if (!value) {
+            dispatch({
+                type: "message.add",
+                role: "system",
+                text: await presetListText(`Preset: ${state.runPreset || "none"}. Use /preset <name> or /preset none.`),
+            });
+            return;
+        }
+        const normalized = normalizeOptionalSetting(value, ["none", "off", "clear"]);
+        if (normalized && !(await validatePresetName(normalized))) {
+            return;
+        }
+        dispatch({ type: "settings.set", settings: { runPreset: normalized } });
+        dispatch({ type: "activity.add", text: `Preset: ${normalized || "none"}` });
+    }
+    async function validatePresetName(preset) {
+        try {
+            if (await options.settingsController.validatePreset(options.profileName, preset))
+                return true;
+            dispatch({
+                type: "message.add",
+                role: "system",
+                text: await presetListText(`Unknown preset: ${preset}`),
+            });
+            dispatch({ type: "activity.add", level: "warning", text: `Unknown preset: ${preset}` });
+            return false;
+        }
+        catch (error) {
+            dispatch({ type: "message.add", role: "system", text: `Could not validate preset "${preset}": ${userFacingError(error)}` });
+            dispatch({ type: "activity.add", level: "error", text: "Preset catalog unavailable" });
+            return false;
+        }
+    }
+    async function presetListText(prefix) {
+        return options.settingsController.presetListText({
+            profileName: options.profileName,
+            currentPreset: options.engine.snapshot().runPreset,
+            prefix,
+        });
+    }
+    async function showAuthStatus() {
+        dispatch({ type: "activity.add", text: "Checking auth status" });
+        try {
+            dispatch({ type: "message.add", role: "system", text: await options.authController.statusText(options.profileName) });
+            dispatch({ type: "activity.add", level: "success", text: "Auth status ready" });
+        }
+        catch (error) {
+            dispatch({ type: "message.add", role: "system", text: userFacingError(error) });
+            dispatch({ type: "activity.add", level: "error", text: "Auth status failed" });
+        }
+    }
+    async function exportTranscript(effect) {
+        try {
+            const file = await options.conversationController.exportTranscript(effect);
+            dispatch({ type: "message.add", role: "system", text: `Transcript exported:\n${file}` });
+            dispatch({ type: "activity.add", level: "success", text: "Transcript exported" });
+        }
+        catch (error) {
+            dispatch({ type: "message.add", role: "system", text: `Transcript export failed: ${userFacingError(error)}` });
+            dispatch({ type: "activity.add", level: "error", text: "Transcript export failed" });
+        }
+    }
+    async function showSummary() {
+        if (!options.localController.isLoaded()) {
+            dispatch({ type: "message.add", role: "system", text: unavailableWorkdirText() });
+            return;
+        }
+        dispatch({ type: "activity.add", text: "Summarizing workdir" });
+        try {
+            dispatch({
+                type: "message.add",
+                role: "system",
+                text: await options.localController.summaryText(),
+            });
+            dispatch({ type: "activity.add", level: "success", text: "Workdir summary ready" });
+        }
+        catch (error) {
+            dispatch({
+                type: "activity.add",
+                level: "error",
+                text: userFacingError(error),
+            });
+        }
+    }
+    async function startNewConversation(name) {
+        const conversation = await options.conversationController.startNewConversation(name, options.options.profile);
+        dispatch({ type: "messages.clear" });
+        dispatch({ type: "conversation.set", name: conversation.name });
+        dispatch({
+            type: "message.add",
+            role: "system",
+            text: conversation.message,
+        });
+    }
+    function switchConversation(name) {
+        const conversation = options.conversationController.switchConversation(name);
+        dispatch({ type: "messages.clear" });
+        dispatch({ type: "conversation.set", name: conversation.name });
+        dispatch({
+            type: "message.add",
+            role: "system",
+            text: conversation.message,
+        });
+    }
+    async function showConversations() {
+        try {
+            dispatch({
+                type: "message.add",
+                role: "system",
+                text: await options.conversationController.listConversations(options.options.profile),
+            });
+        }
+        catch (error) {
+            dispatch({ type: "message.add", role: "system", text: userFacingError(error) });
+        }
+    }
+    async function searchWorkdir(query) {
+        if (!query) {
+            dispatch({ type: "message.add", role: "system", text: "Usage: /search <query>" });
+            return;
+        }
+        if (!options.localController.isLoaded()) {
+            dispatch({ type: "message.add", role: "system", text: unavailableWorkdirText() });
+            return;
+        }
+        dispatch({ type: "activity.add", text: `Searching workdir: ${query}` });
+        try {
+            const result = await options.localController.searchText(query);
+            dispatch({
+                type: "message.add",
+                role: "system",
+                text: result.text,
+            });
+            dispatch({
+                type: "activity.add",
+                level: "success",
+                text: `Search complete: ${result.count} matches`,
+            });
+        }
+        catch (error) {
+            dispatch({
+                type: "activity.add",
+                level: "error",
+                text: userFacingError(error),
+            });
+        }
+    }
+    function showEditPreview() {
+        const state = options.engine.snapshot();
+        if (state.pendingLocalTool) {
+            dispatch({ type: "message.add", role: "system", text: options.localController.approvalPreview(state.pendingLocalTool) });
+            return;
+        }
+        dispatch({ type: "message.add", role: "system", text: "No pending local action." });
+    }
+    async function applyPendingEdit(allowFutureLocalActions) {
+        const state = options.engine.snapshot();
+        if (!options.localController.isLoaded()) {
+            dispatch({ type: "message.add", role: "system", text: unavailableWorkdirText() });
+            return;
+        }
+        if (state.pendingLocalTool) {
+            dispatch({
+                type: "activity.add",
+                level: "warning",
+                text: `Applying local action: ${state.pendingLocalTool.name}${state.pendingLocalTool.action ? `.${state.pendingLocalTool.action}` : ""}`,
+            });
+            try {
+                const result = await options.localController.applyApproval(state.pendingLocalTool);
+                const nextAccessMode = allowFutureLocalActions ? "full" : state.accessMode;
+                if (allowFutureLocalActions) {
+                    dispatch({ type: "access.set", mode: "full" });
+                }
+                dispatch({
+                    type: "message.add",
+                    role: "system",
+                    text: [
+                        allowFutureLocalActions
+                            ? "Applied local action. Future local actions in this workbench conversation are now allowed."
+                            : "Applied local action once. Future local actions still require approval.",
+                        "Continuing agent turn with the local result.",
+                        "Result:",
+                        JSON.stringify(result, null, 2),
+                    ].join("\n"),
+                });
+                dispatch({ type: "activity.add", level: "success", text: "Local action applied" });
+                const approval = state.pendingLocalTool;
+                dispatch({ type: "local_tool.pending.clear" });
+                await options.turnController.continueAfterLocalApproval({
+                    approval,
+                    result,
+                    accessMode: nextAccessMode,
+                });
+            }
+            catch (error) {
+                dispatch({ type: "message.add", role: "system", text: userFacingError(error) });
+                dispatch({ type: "activity.add", level: "error", text: userFacingError(error) });
+            }
+            return;
+        }
+        dispatch({ type: "message.add", role: "system", text: "No pending local action." });
+    }
+    function rejectPendingEdit() {
+        const state = options.engine.snapshot();
+        if (state.pendingLocalTool) {
+            dispatch({
+                type: "activity.add",
+                text: `Rejected local action: ${state.pendingLocalTool.name}${state.pendingLocalTool.action ? `.${state.pendingLocalTool.action}` : ""}`,
+            });
+            dispatch({ type: "local_tool.pending.clear" });
+            return;
+        }
+        dispatch({ type: "message.add", role: "system", text: "No pending local action." });
+    }
+    function unavailableWorkdirText() {
+        const state = options.engine.snapshot();
+        if (!state.contextEnabled || state.accessMode === "off") {
+            return "Local workdir tools are off. Use /workdir on, /access approval, or /access full to load and expose the current workdir.";
+        }
+        return "Workdir is still loading.";
+    }
+}
+export function normalizeOptionalSetting(value, clearValues) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return clearValues.includes(trimmed.toLowerCase()) ? undefined : trimmed;
+}
+function userFacingError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}

package/dist/workbench/conversation-controller.d.ts

@@ -0,0 +1,32 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { deleteConversation, listConversations } from "../agent.js";
+export interface WorkbenchConversationController {
+    startNewConversation(name: string | undefined, profileName?: string): Promise<{
+        name: string;
+        message: string;
+    }>;
+    switchConversation(name: string): {
+        name: string;
+        message: string;
+    };
+    listConversations(profileName?: string): Promise<string>;
+    exportTranscript(input: {
+        path?: string;
+        transcript: string;
+        conversation: string;
+    }): Promise<string>;
+}
+export interface WorkbenchConversationControllerOptions {
+    deleteConversationImpl?: typeof deleteConversation;
+    listConversationsImpl?: typeof listConversations;
+    mkdirImpl?: typeof mkdir;
+    writeFileImpl?: typeof writeFile;
+    now?: () => Date;
+    dataDir?: string;
+}
+export declare function createWorkbenchConversationController(options?: WorkbenchConversationControllerOptions): WorkbenchConversationController;
+export declare function defaultTranscriptExportPath(conversation: string, options?: {
+    dataDir?: string;
+    now?: () => Date;
+}): string;
+export declare function createConversationName(now?: Date): string;

package/dist/workbench/conversation-controller.js

@@ -0,0 +1,53 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { conversationSummary, deleteConversation, listConversations, } from "../agent.js";
+import { runtime } from "../runtime/index.js";
+export function createWorkbenchConversationController(options = {}) {
+    const deleteConversationImpl = options.deleteConversationImpl ?? deleteConversation;
+    const listConversationsImpl = options.listConversationsImpl ?? listConversations;
+    const mkdirImpl = options.mkdirImpl ?? mkdir;
+    const writeFileImpl = options.writeFileImpl ?? writeFile;
+    const now = options.now ?? (() => new Date());
+    return {
+        async startNewConversation(name, profileName) {
+            const conversation = name || createConversationName(now());
+            await deleteConversationImpl(conversation, profileName);
+            return {
+                name: conversation,
+                message: `Started fresh conversation "${conversation}".`,
+            };
+        },
+        switchConversation(name) {
+            return {
+                name,
+                message: `Switched to conversation "${name}". Future turns will continue this handle when history exists.`,
+            };
+        },
+        async listConversations(profileName) {
+            const conversations = await listConversationsImpl(profileName);
+            return conversations.length === 0
+                ? "No saved conversations yet."
+                : conversations.map(conversationSummary).join("\n");
+        },
+        async exportTranscript(input) {
+            const file = input.path?.trim()
+                ? path.resolve(process.cwd(), input.path.trim())
+                : defaultTranscriptExportPath(input.conversation, {
+                    dataDir: options.dataDir,
+                    now,
+                });
+            await mkdirImpl(path.dirname(file), { recursive: true });
+            await writeFileImpl(file, input.transcript, "utf8");
+            return file;
+        },
+    };
+}
+export function defaultTranscriptExportPath(conversation, options = {}) {
+    const safeConversation = conversation.replace(/[^a-z0-9._-]+/gi, "-").replace(/^-+|-+$/g, "") || "conversation";
+    const stamp = (options.now?.() ?? new Date()).toISOString().replace(/[:.]/g, "-");
+    return path.join(options.dataDir ?? runtime.dirs.data, "transcripts", `${safeConversation}-${stamp}.txt`);
+}
+export function createConversationName(now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:]/g, "").replace(/\..+$/, "").replace("T", "-");
+    return `thread-${stamp}`;
+}

package/dist/workbench/engine.d.ts

@@ -0,0 +1,66 @@
+import { type RenderMode, type WorkbenchAction, type WorkbenchCommand, type WorkbenchState } from "./state.js";
+import type { AgentTurnEvent, WorkdirAccessMode } from "../agent.js";
+export interface WorkbenchEngineOptions {
+    contextEnabled: boolean;
+    accessMode?: WorkdirAccessMode;
+    conversation?: string;
+    preset?: string;
+    model?: string;
+    renderMode?: RenderMode;
+    defaultPreset?: string | null;
+}
+export interface WorkbenchEngine {
+    snapshot(): WorkbenchState;
+    subscribe(listener: () => void): () => void;
+    dispatch(action: WorkbenchAction): void;
+    submit(input: string): WorkbenchSubmission;
+    handleCommand(command: WorkbenchCommand): WorkbenchCommandResult;
+    handleAgentEvent(event: AgentTurnEvent): WorkbenchEventResult;
+}
+export type WorkbenchSubmission = {
+    kind: "command";
+    command: WorkbenchCommand;
+} | {
+    kind: "prompt";
+    prompt: string;
+} | {
+    kind: "handled";
+};
+export type WorkbenchEffect = {
+    type: "exit";
+} | {
+    type: "login";
+} | {
+    type: "logout";
+} | {
+    type: "delete_profile";
+} | {
+    type: "switch_profile";
+    name?: string;
+} | {
+    type: "show_auth_status";
+} | {
+    type: "export_transcript";
+    path?: string;
+    transcript: string;
+    conversation: string;
+} | {
+    type: "clear_preset_tool_catalog_cache";
+};
+export type WorkbenchRuntimeEffect = {
+    type: "append_text_delta";
+    delta: string;
+} | {
+    type: "set_active_response_id";
+    responseID: string;
+} | {
+    type: "flush_text_delta_buffer";
+};
+export interface WorkbenchCommandResult {
+    handled: boolean;
+    effects: WorkbenchEffect[];
+}
+export interface WorkbenchEventResult {
+    effects: WorkbenchRuntimeEffect[];
+}
+export declare function createWorkbenchEngine(options: WorkbenchEngineOptions): WorkbenchEngine;