@agent-api/app-engine 0.0.1

package/dist/workbench/lifecycle-controller.js

@@ -0,0 +1,75 @@
+import { checkForUpdate, formatUpdateNotice } from "../update.js";
+export function createWorkbenchLifecycleController(options) {
+    const checkForUpdateImpl = options.checkForUpdateImpl ?? checkForUpdate;
+    const formatUpdateNoticeImpl = options.formatUpdateNoticeImpl ?? formatUpdateNotice;
+    const formatError = options.formatError ?? userFacingError;
+    const refreshWindowMs = options.refreshWindowMs ?? 5 * 60_000;
+    const updateCheckEnabled = options.updateCheckEnabled ?? process.env.AGENT_TUI_UPDATE_CHECK !== "0";
+    let updateNoticeShown = false;
+    let authRefreshWarningShown = false;
+    let initialPromptSubmitted = false;
+    return {
+        async maybeCheckForUpdate() {
+            if (updateNoticeShown || !updateCheckEnabled)
+                return [];
+            updateNoticeShown = true;
+            try {
+                const result = await checkForUpdateImpl();
+                return updateNoticeEffects(result, formatUpdateNoticeImpl);
+            }
+            catch {
+                return [];
+            }
+        },
+        async refreshAuth(profile) {
+            try {
+                const result = await options.authController.refresh(profile, refreshWindowMs);
+                if (!result.refreshed)
+                    return [];
+                authRefreshWarningShown = false;
+                return [
+                    { type: "dispatch", action: { type: "activity.add", level: "success", text: "Auth session refreshed" } },
+                ];
+            }
+            catch (error) {
+                if (authRefreshWarningShown)
+                    return [];
+                authRefreshWarningShown = true;
+                return [
+                    {
+                        type: "dispatch",
+                        action: {
+                            type: "message.add",
+                            role: "system",
+                            text: `${formatError(error)}\n\nClosing the workbench because authenticated agent conversations are unavailable.`,
+                        },
+                    },
+                    { type: "dispatch", action: { type: "activity.add", level: "error", text: "Auth session needs login; closing" } },
+                    { type: "close", delayMs: 1500 },
+                ];
+            }
+        },
+        initialPrompt(input) {
+            if (initialPromptSubmitted || input.busy || (input.requiresWorkdir && !input.workdir))
+                return undefined;
+            const prompt = input.promptParts.join(" ").trim();
+            if (!prompt)
+                return undefined;
+            initialPromptSubmitted = true;
+            return prompt;
+        },
+    };
+}
+export function updateNoticeEffects(result, formatNotice = formatUpdateNotice) {
+    if (!result?.updateAvailable)
+        return [];
+    return [
+        { type: "dispatch", action: { type: "activity.add", level: "warning", text: `Update available: ${result.latest}` } },
+        { type: "dispatch", action: { type: "message.add", role: "system", text: formatNotice(result) } },
+    ];
+}
+function userFacingError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}

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

@@ -0,0 +1,21 @@
+import { openWorkdir } from "../workdir/index.js";
+import type { WorkbenchState, WorkbenchWorkdirStatus } from "./state.js";
+import type { ShellIsolationPreferences } from "./shell-isolation.js";
+export interface WorkbenchLocalController {
+    load(path?: string): Promise<WorkbenchWorkdirStatus>;
+    isLoaded(): boolean;
+    summaryText(): Promise<string>;
+    searchText(query: string): Promise<{
+        text: string;
+        count: number;
+    }>;
+    approvalPreview(approval: LocalApprovalLike): string;
+    applyApproval(approval: LocalApprovalLike): Promise<string | Record<string, unknown>>;
+}
+export interface WorkbenchLocalControllerOptions {
+    openWorkdirImpl?: typeof openWorkdir;
+    getShellIsolation?: () => ShellIsolationPreferences | undefined;
+}
+type LocalApprovalLike = NonNullable<WorkbenchState["pendingLocalTool"]>;
+export declare function createWorkbenchLocalController(options?: WorkbenchLocalControllerOptions): WorkbenchLocalController;
+export {};

package/dist/workbench/local-controller.js

@@ -0,0 +1,94 @@
+import { createLocalShellToolRegistry, createLocalWorkdirToolRegistry } from "@agent-api/sdk/local";
+import { openWorkdir } from "../workdir/index.js";
+import { localShellIsolationOptions } from "./shell-isolation.js";
+export function createWorkbenchLocalController(options = {}) {
+    const openWorkdirImpl = options.openWorkdirImpl ?? openWorkdir;
+    let workdir = null;
+    return {
+        async load(path) {
+            const next = await openWorkdirImpl({ path });
+            const summary = await next.summarize();
+            workdir = next;
+            return {
+                root: next.root,
+                name: next.name,
+                fileCount: summary.file_count,
+                totalBytes: summary.total_bytes,
+                scanTruncated: summary.scan_truncated,
+            };
+        },
+        isLoaded() {
+            return Boolean(workdir);
+        },
+        async summaryText() {
+            const current = requireWorkdir();
+            const summary = await current.summarize();
+            const previews = summary.text_previews
+                .slice(0, 5)
+                .map((preview) => `- ${preview.path} (${formatBytes(preview.size)})`)
+                .join("\n");
+            return [
+                `Workdir summary for ${current.name}`,
+                `Files: ${summary.file_count}`,
+                `Size: ${formatBytes(summary.total_bytes)}`,
+                previews ? `Previews:\n${previews}` : "No text previews available.",
+            ].join("\n");
+        },
+        async searchText(query) {
+            const trimmed = query.trim();
+            if (!trimmed) {
+                return { text: "Usage: /search <query>", count: 0 };
+            }
+            const current = requireWorkdir();
+            const results = await current.workdir.grep({ pattern: trimmed, limit: 12 });
+            const matches = results.matches
+                .map((match) => `${match.path}:${match.line_number}: ${match.line.trim()}`)
+                .join("\n");
+            return {
+                text: matches || `No matches for "${trimmed}".`,
+                count: results.matches.length,
+            };
+        },
+        approvalPreview(approval) {
+            return formatLocalToolApproval(approval);
+        },
+        async applyApproval(approval) {
+            const current = requireWorkdir();
+            const workdirRegistry = createLocalWorkdirToolRegistry(current.workdir, { accessMode: "full" });
+            const shellRegistry = createLocalShellToolRegistry({
+                workdir: current.workdir,
+                accessMode: "full",
+                ...localShellIsolationOptions(options.getShellIsolation?.()),
+            });
+            if (approval.name === workdirRegistry.toolName) {
+                return await workdirRegistry.execute(approval.name, approval.arguments);
+            }
+            if (approval.name === shellRegistry.toolName) {
+                return await shellRegistry.execute(approval.name, approval.arguments);
+            }
+            throw new Error(`no local handler registered for function ${approval.name}`);
+        },
+    };
+    function requireWorkdir() {
+        if (!workdir)
+            throw new Error("Workdir is still loading.");
+        return workdir;
+    }
+}
+function formatLocalToolApproval(approval) {
+    return [
+        `Local approval requested: ${approval.name}${approval.action ? `.${approval.action}` : ""}`,
+        "Arguments:",
+        JSON.stringify(approval.arguments, null, 2),
+        approval.preview ? ["Preview:", JSON.stringify(approval.preview, null, 2)].join("\n") : "",
+        "",
+        "Use /apply to execute this action once, /apply-all to allow future local actions, or /reject to discard it.",
+    ].filter(Boolean).join("\n");
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}

package/dist/workbench/render-model.d.ts

@@ -0,0 +1,46 @@
+import type { RenderMode, WorkbenchState } from "./state.js";
+import { type TranscriptViewModel } from "./view-model.js";
+export interface WorkbenchRendererViewport {
+    rows: number;
+    columns: number;
+}
+export interface WorkbenchRenderModel {
+    activityHeight: number;
+    footerText: string;
+    header: {
+        accessMode: string;
+        contextEnabled: boolean;
+        conversation: string;
+        model: string;
+        pendingLocalLabel: string;
+        preset: string;
+        profile: string;
+        renderMode: RenderMode;
+        workdir: string;
+    };
+    input: {
+        busy: boolean;
+        draft: string;
+        fullAccess: boolean;
+        label: string;
+        waitingText: string;
+    };
+    terminalColumns: number;
+    terminalRows: number;
+    transcript: TranscriptViewModel;
+    transcriptWidth: number;
+    viewportHeight: number;
+    visibleActivities: WorkbenchState["activities"];
+}
+export interface BuildWorkbenchRenderModelInput {
+    draft: string;
+    profileName: string;
+    spinnerFrame: number;
+    state: WorkbenchState;
+    transcriptOffset: number;
+    viewport: Partial<WorkbenchRendererViewport>;
+    workdirFallback: string;
+}
+export declare function buildWorkbenchRenderModel(input: BuildWorkbenchRenderModelInput): WorkbenchRenderModel;
+export declare function pendingLocalLabel(state: WorkbenchState): string;
+export declare function busySpinner(frame: number): string;

package/dist/workbench/render-model.js

@@ -0,0 +1,61 @@
+import { buildTranscriptViewModel, elapsedDots, spinnerGlyph, } from "./view-model.js";
+export function buildWorkbenchRenderModel(input) {
+    const terminalRows = Math.max(18, input.viewport.rows || 32);
+    const terminalColumns = Math.max(80, input.viewport.columns || 100);
+    const viewportHeight = Math.max(6, terminalRows - 11);
+    const activityHeight = viewportHeight;
+    const transcriptWidth = Math.max(36, Math.floor(terminalColumns * 0.72) - 4);
+    const transcript = buildTranscriptViewModel({
+        activeAssistantMessageId: input.state.activeAssistantMessageId,
+        busy: input.state.busy,
+        messages: input.state.messages,
+        offset: input.transcriptOffset,
+        renderMode: input.state.renderMode,
+        spinnerFrame: input.spinnerFrame,
+        viewportHeight,
+        width: transcriptWidth,
+    });
+    return {
+        activityHeight,
+        footerText: [
+            "PgUp/PgDn scroll",
+            "End live",
+            "/export save",
+            "/transcript preview",
+            transcript.offset > 0 ? `${transcript.offset} rows from latest` : "live",
+        ].join(" · "),
+        header: {
+            accessMode: input.state.accessMode,
+            contextEnabled: input.state.contextEnabled,
+            conversation: input.state.currentConversation,
+            model: input.state.runModel || "auto",
+            pendingLocalLabel: pendingLocalLabel(input.state),
+            preset: input.state.runPreset || "none",
+            profile: input.profileName,
+            renderMode: input.state.renderMode,
+            workdir: input.state.workdir?.root || input.workdirFallback,
+        },
+        input: {
+            busy: input.state.busy,
+            draft: input.draft,
+            fullAccess: input.state.accessMode === "full",
+            label: input.state.busy ? "working" : "you",
+            waitingText: `waiting for agent ${elapsedDots(input.spinnerFrame)}`,
+        },
+        terminalColumns,
+        terminalRows,
+        transcript,
+        transcriptWidth,
+        viewportHeight,
+        visibleActivities: input.state.activities.slice(-Math.max(1, activityHeight - 2)),
+    };
+}
+export function pendingLocalLabel(state) {
+    if (state.pendingLocalTool) {
+        return `${state.pendingLocalTool.name}${state.pendingLocalTool.action ? `.${state.pendingLocalTool.action}` : ""}`;
+    }
+    return "none";
+}
+export function busySpinner(frame) {
+    return spinnerGlyph(frame);
+}

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

@@ -0,0 +1,12 @@
+import type { WorkbenchAction } from "./state.js";
+import type { WorkbenchRuntimeEffect } from "./engine.js";
+export interface WorkbenchRuntimeController {
+    dispose(): void;
+    flushTextDeltaBuffer(): void;
+    runEffects(effects: WorkbenchRuntimeEffect[], assistantId: string): void;
+}
+export interface WorkbenchRuntimeControllerOptions {
+    dispatch(action: WorkbenchAction): void;
+    flushDelayMs?: number;
+}
+export declare function createWorkbenchRuntimeController(options: WorkbenchRuntimeControllerOptions): WorkbenchRuntimeController;

package/dist/workbench/runtime-controller.js

@@ -0,0 +1,57 @@
+export function createWorkbenchRuntimeController(options) {
+    let textDeltaBuffer = null;
+    let textDeltaFlushTimer = null;
+    const flushDelayMs = options.flushDelayMs ?? 80;
+    return {
+        dispose() {
+            if (textDeltaFlushTimer) {
+                clearTimeout(textDeltaFlushTimer);
+                textDeltaFlushTimer = null;
+            }
+            textDeltaBuffer = null;
+        },
+        flushTextDeltaBuffer,
+        runEffects(effects, assistantId) {
+            for (const effect of effects) {
+                switch (effect.type) {
+                    case "append_text_delta":
+                        appendTextDeltaBuffered(assistantId, effect.delta);
+                        break;
+                    case "set_active_response_id":
+                        break;
+                    case "flush_text_delta_buffer":
+                        flushTextDeltaBuffer();
+                        break;
+                }
+            }
+        },
+    };
+    function appendTextDeltaBuffered(id, delta) {
+        if (!delta)
+            return;
+        if (!textDeltaBuffer || textDeltaBuffer.id !== id) {
+            flushTextDeltaBuffer();
+            textDeltaBuffer = { id, text: delta };
+        }
+        else {
+            textDeltaBuffer.text += delta;
+        }
+        if (textDeltaFlushTimer)
+            return;
+        textDeltaFlushTimer = setTimeout(() => {
+            textDeltaFlushTimer = null;
+            flushTextDeltaBuffer();
+        }, flushDelayMs);
+    }
+    function flushTextDeltaBuffer() {
+        if (textDeltaFlushTimer) {
+            clearTimeout(textDeltaFlushTimer);
+            textDeltaFlushTimer = null;
+        }
+        if (!textDeltaBuffer || !textDeltaBuffer.text)
+            return;
+        const buffered = textDeltaBuffer;
+        textDeltaBuffer = null;
+        options.dispatch({ type: "message.append", id: buffered.id, delta: buffered.text });
+    }
+}

package/dist/workbench/session.d.ts

@@ -0,0 +1,29 @@
+import type { AgentRunOptions } from "../agent.js";
+import type { AgentEngineServices } from "../engine/services.js";
+import type { WorkbenchState } from "./state.js";
+import type { WorkbenchAuthController } from "./auth-controller.js";
+import { type WorkbenchConversationController } from "./conversation-controller.js";
+import { type WorkbenchEngine } from "./engine.js";
+import { type WorkbenchInputController } from "./input-controller.js";
+import { type WorkbenchLifecycleController } from "./lifecycle-controller.js";
+import { type WorkbenchLocalController } from "./local-controller.js";
+import { type WorkbenchRuntimeController } from "./runtime-controller.js";
+import { type WorkbenchSettingsController } from "./settings-controller.js";
+import { type WorkbenchTurnController } from "./turn-controller.js";
+export interface WorkbenchSession {
+    conversation: WorkbenchConversationController;
+    engine: WorkbenchEngine;
+    input: WorkbenchInputController;
+    lifecycle: WorkbenchLifecycleController;
+    local: WorkbenchLocalController;
+    runtime: WorkbenchRuntimeController;
+    settings: WorkbenchSettingsController;
+    turn: WorkbenchTurnController;
+}
+export interface WorkbenchSessionOptions {
+    authController: WorkbenchAuthController;
+    baseOptions: AgentRunOptions;
+    services?: Omit<AgentEngineServices, "auth">;
+}
+export declare function createWorkbenchSession(options: WorkbenchSessionOptions): WorkbenchSession;
+export declare function sessionState(session: Pick<WorkbenchSession, "engine">): WorkbenchState;

package/dist/workbench/session.js

@@ -0,0 +1,42 @@
+import { createWorkbenchConversationController } from "./conversation-controller.js";
+import { createWorkbenchEngine } from "./engine.js";
+import { createWorkbenchInputController } from "./input-controller.js";
+import { createWorkbenchLifecycleController } from "./lifecycle-controller.js";
+import { createWorkbenchLocalController } from "./local-controller.js";
+import { createWorkbenchRuntimeController } from "./runtime-controller.js";
+import { createWorkbenchSettingsController } from "./settings-controller.js";
+import { createWorkbenchTurnController } from "./turn-controller.js";
+export function createWorkbenchSession(options) {
+    const engine = options.services?.engine ?? createWorkbenchEngine({
+        accessMode: options.baseOptions.accessMode,
+        conversation: options.baseOptions.conversation,
+        contextEnabled: Boolean(options.baseOptions.includeLocalContext || options.baseOptions.workdir),
+        model: options.baseOptions.model,
+        preset: options.baseOptions.preset,
+    });
+    const local = options.services?.local ?? createWorkbenchLocalController({
+        getShellIsolation: () => engine.snapshot().shellIsolation,
+    });
+    const runtime = options.services?.runtime ?? createWorkbenchRuntimeController({ dispatch: engine.dispatch });
+    const turn = options.services?.turn ?? createWorkbenchTurnController({
+        baseOptions: options.baseOptions,
+        dispatch: engine.dispatch,
+        engine,
+        flushTextDeltaBuffer: runtime.flushTextDeltaBuffer,
+        getState: engine.snapshot,
+        runRuntimeEffects: runtime.runEffects,
+    });
+    return {
+        conversation: options.services?.conversation ?? createWorkbenchConversationController(),
+        engine,
+        input: options.services?.input ?? createWorkbenchInputController(),
+        lifecycle: options.services?.lifecycle ?? createWorkbenchLifecycleController({ authController: options.authController }),
+        local,
+        runtime,
+        settings: options.services?.settings ?? createWorkbenchSettingsController(),
+        turn,
+    };
+}
+export function sessionState(session) {
+    return session.engine.snapshot();
+}

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

@@ -0,0 +1,80 @@
+import { clearPresetToolCatalogCache, isAvailablePreset, listAvailablePresets, type AgentRunOptions } from "../agent.js";
+import { loadWorkbenchPreferences, updateWorkbenchPreferences, type WorkbenchPreferences } from "../config.js";
+import type { RenderMode } from "./state.js";
+import type { ShellIsolationMode, ShellIsolationPreferences } from "./shell-isolation.js";
+import { type IsolatorInstallOptions } from "./isolator-installer.js";
+export interface WorkbenchSettingsSnapshot {
+    defaultPreset?: string | null;
+    runPreset?: string;
+    shellIsolation?: ShellIsolationPreferences;
+    activity?: string;
+    notice?: string;
+    warning?: string;
+}
+export interface WorkbenchSettingsController {
+    loadInitial(options: Pick<AgentRunOptions, "modelExplicit" | "preset" | "presetExplicit">): Promise<WorkbenchSettingsSnapshot>;
+    saveDefaultPreset(input: {
+        value: string;
+        profileName?: string;
+        options: Pick<AgentRunOptions, "modelExplicit" | "preset" | "presetExplicit">;
+    }): Promise<WorkbenchSettingsSnapshot & {
+        message: string;
+        activity: string;
+    }>;
+    saveShellIsolationMode(value: string): Promise<WorkbenchSettingsSnapshot & {
+        message: string;
+        activity: string;
+    }>;
+    saveIsolatorPath(value: string): Promise<WorkbenchSettingsSnapshot & {
+        message: string;
+        activity: string;
+    }>;
+    saveIsolatorSource(value: string): Promise<WorkbenchSettingsSnapshot & {
+        message: string;
+        activity: string;
+    }>;
+    validatePreset(profileName: string | undefined, preset: string): Promise<boolean>;
+    presetListText(input: {
+        profileName?: string;
+        currentPreset?: string;
+        prefix: string;
+    }): Promise<string>;
+    configText(input: {
+        accessMode: string;
+        contextEnabled: boolean;
+        defaultPreset?: string | null;
+        profileName: string;
+        runModel?: string;
+        runPreset?: string;
+        renderMode: RenderMode;
+        shellIsolation?: ShellIsolationPreferences;
+    }): string;
+    defaultPresetHelp(defaultPreset?: string | null): string;
+    shellIsolationHelp(shellIsolation?: ShellIsolationPreferences): string;
+    isolatorPathHelp(shellIsolation?: ShellIsolationPreferences): string;
+    clearPresetToolCatalogCache(baseURL?: string): void;
+}
+export interface WorkbenchSettingsControllerOptions {
+    loadWorkbenchPreferencesImpl?: typeof loadWorkbenchPreferences;
+    updateWorkbenchPreferencesImpl?: typeof updateWorkbenchPreferences;
+    isAvailablePresetImpl?: typeof isAvailablePreset;
+    listAvailablePresetsImpl?: typeof listAvailablePresets;
+    clearPresetToolCatalogCacheImpl?: typeof clearPresetToolCatalogCache;
+    isolatorInstallOptions?: IsolatorInstallOptions;
+    formatError?: (error: unknown) => string;
+}
+export declare function createWorkbenchSettingsController(options?: WorkbenchSettingsControllerOptions): WorkbenchSettingsController;
+export declare class UnknownPresetError extends Error {
+    readonly preset: string;
+    constructor(preset: string);
+}
+export declare function normalizeDefaultPreset(value: string): string | null | undefined;
+export declare function formatDefaultPreset(value: string | null | undefined): string;
+export declare function normalizeShellIsolationMode(value: string): ShellIsolationMode;
+export declare function normalizeIsolatorPath(value: string): string | null;
+export declare function normalizeIsolatorSource(value: string): string | null;
+export declare function formatShellIsolation(value: ShellIsolationPreferences | undefined): ShellIsolationMode;
+export declare function formatIsolatorPath(value: ShellIsolationPreferences | undefined): string;
+export declare function formatIsolatorSource(value: ShellIsolationPreferences | undefined): string;
+export declare function effectiveDefaultPreset(preferences: WorkbenchPreferences, builtInPreset?: string): string | undefined;
+export declare function formatPresetList(presets: Awaited<ReturnType<typeof listAvailablePresets>>, currentPreset?: string): string[];