@aotui/runtime 1.0.0

package/dist/engine/view/snapshot/formatter.js

@@ -0,0 +1,297 @@
+/**
+ * SnapshotFormatter - TUI Snapshot Formatter
+ *
+ * [RFC-007] Transforms Worker fragments and Desktop metadata into
+ * complete TUI snapshots conforming to TUI_DEMO.md format.
+ * [RFC-014] Added structured output for semantic separation.
+ *
+ * @module @aotui/runtime/engine/view/snapshot/formatter
+ */
+import { SYSTEM_INSTRUCTION, SYSTEM_INSTRUCTION_PURE, formatTimestamp, formatAppStatus } from './templates.js';
+/**
+ * SnapshotFormatter Implementation
+ *
+ * Assembles complete TUI snapshots from:
+ * 1. Desktop metadata (`<desktop>` section)
+ * 2. Worker fragments (`<application>` sections)
+ *
+ * [RFC-014] Now also returns structured output for semantic separation.
+ *
+ * @example
+ * ```typescript
+ * const formatter = new SnapshotFormatter();
+ * const { markup, indexMap, structured } = formatter.format(fragments, metadata);
+ * ```
+ */
+export class SnapshotFormatter {
+    systemLogLimit;
+    appLogLimit;
+    constructor(config) {
+        this.systemLogLimit = config?.systemLogLimit ?? 5;
+        this.appLogLimit = config?.appLogLimit ?? 3;
+    }
+    resolveUniqueToolKey(rawKey, mergedIndexMap) {
+        if (!(rawKey in mergedIndexMap)) {
+            return rawKey;
+        }
+        const toolPrefix = 'tool:';
+        const normalized = rawKey.startsWith(toolPrefix) ? rawKey.slice(toolPrefix.length) : rawKey;
+        const dashIndex = normalized.indexOf('-');
+        const appName = dashIndex > 0 ? normalized.slice(0, dashIndex) : normalized;
+        const rest = dashIndex > 0 ? normalized.slice(dashIndex + 1) : '';
+        let suffix = 2;
+        while (true) {
+            const candidateCore = rest.length > 0
+                ? `${appName}_${suffix}-${rest}`
+                : `${appName}_${suffix}`;
+            const candidate = `${toolPrefix}${candidateCore}`;
+            if (!(candidate in mergedIndexMap)) {
+                return candidate;
+            }
+            suffix += 1;
+        }
+    }
+    /**
+     * Format complete TUI snapshot
+     *
+     * [RFC-014] Now returns both legacy markup and structured output.
+     */
+    format(fragments, metadata) {
+        const parts = [];
+        const mergedIndexMap = {};
+        // 1. Build <desktop> section (legacy - includes SYSTEM_INSTRUCTION)
+        parts.push(this.buildDesktopSection(metadata));
+        // 2. Build <application> sections for each running app
+        const appStates = [];
+        const viewStates = [];
+        for (const fragment of fragments) {
+            parts.push(this.buildApplicationSection(fragment, metadata));
+            // [RFC-014] Collect app state for structured output
+            const apps = metadata.getInstalledApps();
+            const appInfo = apps.find(a => a.appId === fragment.appId);
+            appStates.push({
+                appId: fragment.appId,
+                appName: appInfo?.name ?? fragment.appId,
+                markup: this.buildApplicationSection(fragment, metadata),
+                timestamp: fragment.timestamp,
+                role: appInfo?.promptRole
+            });
+            if (fragment.views && fragment.views.length > 0) {
+                for (const view of fragment.views) {
+                    viewStates.push({
+                        appId: fragment.appId,
+                        appName: appInfo?.name ?? fragment.appId,
+                        viewId: view.viewId,
+                        viewType: view.viewType,
+                        viewName: view.viewName,
+                        markup: view.markup,
+                        timestamp: view.timestamp,
+                        role: appInfo?.promptRole,
+                    });
+                }
+            }
+            // Merge indexMap with appId namespace
+            // fragment.indexMap keys are in "viewId:refId" format
+            // BUT: operation metadata keys are "tool:app_0.view_0.op_name" (already complete)
+            // console.log(`[SnapshotFormatter] Fragment from ${fragment.appId}, indexMap keys:`, Object.keys(fragment.indexMap));
+            for (const [key, value] of Object.entries(fragment.indexMap)) {
+                // Skip operation metadata (already contains full path)
+                if (key.startsWith('tool:')) {
+                    // console.log(`[SnapshotFormatter] Preserving operation metadata: ${key}`);
+                    const resolvedKey = this.resolveUniqueToolKey(key, mergedIndexMap);
+                    mergedIndexMap[resolvedKey] = value;
+                    continue;
+                }
+                // Only add appId prefix for data references
+                const fullKey = `${fragment.appId}:${key}`;
+                // console.log(`[SnapshotFormatter] Adding data ref: ${key} → ${fullKey}`);
+                mergedIndexMap[fullKey] = value;
+            }
+        }
+        // [RFC-014] Build structured output
+        const structured = {
+            systemInstruction: SYSTEM_INSTRUCTION_PURE,
+            desktopState: this.buildDesktopStateOnly(metadata),
+            appStates,
+            viewStates,
+        };
+        return {
+            markup: parts.join('\n\n'),
+            indexMap: mergedIndexMap,
+            structured
+        };
+    }
+    /**
+     * [RFC-014] Build desktop state without system instruction
+     *
+     * Returns only "Where" information:
+     * - Installed Applications
+     * - System Logs
+     */
+    buildDesktopStateOnly(metadata) {
+        let apps = [];
+        let logs = [];
+        try {
+            apps = metadata.getInstalledApps();
+        }
+        catch { /* graceful degradation */ }
+        try {
+            logs = metadata.getSystemLogs(this.systemLogLimit);
+        }
+        catch { /* graceful degradation */ }
+        // Format apps
+        const appsMarkup = this.formatAppsMarkup(apps);
+        // Format logs
+        const logsMarkup = logs.length > 0
+            ? logs.map(log => `- [${formatTimestamp(log.timestamp)}] ${log.message}`).join('\n')
+            : '- No recent activity.';
+        return `<desktop>
+
+    ## Installed TUI Applications
+    ${appsMarkup}
+
+## System Logs
+${logsMarkup}
+
+</desktop>`;
+    }
+    /**
+     * Format apps list markup (shared between legacy and structured output)
+     */
+    formatAppsMarkup(apps) {
+        if (apps.length === 0) {
+            return '- No applications installed.';
+        }
+        return apps.map((app, index) => {
+            const name = app.name || app.appId;
+            const whatItIs = app.whatItIs ?? app.description ?? 'Not provided';
+            const whenToUse = app.whenToUse ?? 'Not provided';
+            const lines = [
+                `${index + 1}. ${name}`,
+                `    - Status: ${formatAppStatus(app.status)}`,
+                `    - What it is: ${whatItIs}`,
+                `    - When to use: ${whenToUse}`,
+            ];
+            return lines.join('\n');
+        }).join('\n');
+    }
+    /**
+     * Build <desktop> section with system info
+     */
+    buildDesktopSection(metadata) {
+        let apps = [];
+        let logs = [];
+        // Graceful degradation for missing methods
+        try {
+            apps = metadata.getInstalledApps();
+        }
+        catch {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn('[SnapshotFormatter] getInstalledApps() failed, using empty array');
+            }
+        }
+        try {
+            logs = metadata.getSystemLogs(this.systemLogLimit);
+        }
+        catch {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn('[SnapshotFormatter] getSystemLogs() failed, using empty array');
+            }
+        }
+        // Format installed apps list
+        // [RFC-014] Group apps by status: Running vs Available (Pending)
+        const runningApps = apps.filter(a => a.status === 'running' || a.status === 'collapsed' || a.status === 'closed');
+        const pendingApps = apps.filter(a => a.status === 'pending');
+        let appsMarkup = '';
+        if (runningApps.length > 0) {
+            appsMarkup += '### Running Applications\n';
+            appsMarkup += runningApps.map(app => {
+                const lines = [
+                    `- [${app.name}](application:${app.appId})`,
+                    `    - State: ${formatAppStatus(app.status)}`
+                ];
+                if (app.description) {
+                    lines.push(`    - Description: ${app.description}`);
+                }
+                return lines.join('\n');
+            }).join('\n');
+            appsMarkup += '\n\n';
+        }
+        if (pendingApps.length > 0) {
+            appsMarkup += '### Available Applications (Not Started)\n';
+            appsMarkup += pendingApps.map(app => {
+                const lines = [
+                    `- [${app.name}](application:${app.appId})`, // Same link format as running apps
+                    `    - State: pending`,
+                    `    - Description: ${app.description || 'No description available'}`,
+                    `    - Action: Call \`open_app({ app_id: "${app.appId}" })\` to start`
+                ];
+                return lines.join('\n');
+            }).join('\n');
+        }
+        if (apps.length === 0) {
+            appsMarkup = '- No applications installed.';
+        }
+        // Format system logs (most recent first)
+        const logsMarkup = logs.length > 0
+            ? logs.map(log => `- [${formatTimestamp(log.timestamp)}] ${log.message}`).join('\n')
+            : '- No recent activity.';
+        return `<desktop>
+
+    ${SYSTEM_INSTRUCTION}
+
+    ## Installed TUI Applications
+    ${appsMarkup}
+
+## System Logs
+${logsMarkup}
+
+</desktop>`;
+    }
+    /**
+     * Build <application> section with app info and views
+     *
+     * [RFC-017] Removed "## Recent Operations" section - feedback now provided
+     * via AI SDK standard tool-result messages (RFC-015)
+     */
+    buildApplicationSection(fragment, metadata) {
+        // Get app info from metadata
+        const apps = metadata.getInstalledApps();
+        const appInfo = apps.find(a => a.appId === fragment.appId);
+        const appName = appInfo?.name ?? fragment.appId;
+        // Use viewTree from fragment or default message
+        const viewTree = fragment.viewTree ?? '## Application View Tree\n- No views.';
+        // Prepare application_info block
+        const appInfoBlock = `<application_info>\n${viewTree}\n</application_info>`;
+        // [RFC-Fix] Avoid double wrapping if Transformer already output <application>
+        const trimmedMarkup = fragment.markup.trim();
+        if (trimmedMarkup.startsWith('<application')) {
+            // Find the end of the opening tag
+            const openTagMatch = trimmedMarkup.match(/^<application[^>]*>/);
+            if (openTagMatch) {
+                const openTag = openTagMatch[0];
+                // Check if it's a self-closing tag (e.g. collapsed/closed state)
+                if (openTag.endsWith('/>')) {
+                    // Expand self-closing tag to include info
+                    // <application ... /> -> <application ...>\n<info>\n</application>
+                    const expandedOpenTag = openTag.slice(0, -2) + '>';
+                    return `${expandedOpenTag}\n\n${appInfoBlock}\n\n</application>`;
+                }
+                else {
+                    // Standard tag: <application ...> ... </application>
+                    // Insert info after opening tag
+                    const content = trimmedMarkup.substring(openTag.length);
+                    return `${openTag}\n\n${appInfoBlock}\n${content}`;
+                }
+            }
+        }
+        return `<application id="${fragment.appId}" name="${appName}">
+
+${appInfoBlock}
+
+${fragment.markup}
+
+</application>`;
+    }
+}
+//# sourceMappingURL=formatter.js.map

package/dist/engine/view/snapshot/formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.js","sourceRoot":"","sources":["../../../../src/engine/view/snapshot/formatter.ts"],"names":[],"mappings":"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"}

package/dist/engine/view/snapshot/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Snapshot Module Exports
+ */
+export { SnapshotBuilder } from './builder.js';
+export type { SnapshotResult } from './builder.js';
+export { SYSTEM_INSTRUCTION, formatTimestamp, formatAppStatus } from './templates.js';
+export { SnapshotFormatter } from './formatter.js';
+export type { SnapshotFormatterConfig } from './formatter.js';

package/dist/engine/view/snapshot/index.js

@@ -0,0 +1,8 @@
+/**
+ * Snapshot Module Exports
+ */
+export { SnapshotBuilder } from './builder.js';
+export { SYSTEM_INSTRUCTION, formatTimestamp, formatAppStatus } from './templates.js';
+// [RFC-007] SnapshotFormatter for TUI output
+export { SnapshotFormatter } from './formatter.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/view/snapshot/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/engine/view/snapshot/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtF,6CAA6C;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/engine/view/snapshot/templates.d.ts

@@ -0,0 +1,41 @@
+/**
+ * TUI Snapshot Templates
+ *
+ * [RFC-007] System Instruction and formatting templates for TUI output.
+ * [RFC-014] Added SYSTEM_INSTRUCTION_PURE for semantic separation.
+ *
+ * @module @aotui/runtime/engine/view/snapshot/templates
+ */
+/**
+ * [RFC-014] Pure System Instruction - 100% Stable Meta Instructions
+ * [RFC-017] Updated to encourage parallel tool calls
+ *
+ * This template contains ONLY:
+ * - Who: Agent's role definition
+ * - Why: Agent's purpose
+ * - How: Operational guidelines
+ *
+ * NO dynamic content (Apps, Logs, State) is included.
+ * This enables maximum LLM KV Cache hit rate.
+ */
+export declare const SYSTEM_INSTRUCTION_PURE = "# TUI Desktop System Instruction\n\n## Who You Are\n\nYou are the **sole operator** of this TUI (Text-based User Interface) Desktop.\nHuman users communicate with you **through applications** (e.g., Chat app), not directly.\n\n## Why You Exist\n\nThis is a text-based workspace designed for AI Agents to interact with applications and accomplish tasks.\nYou have full control over this Desktop: open/close applications, mount/dismount views, and execute tools.\n\n## How You Work\n\n### Function Calling Convention\n\n- App tools: `{app_id}-{view_id}-{tool_id}`\n- System tools: `system-{tool}`\n\n### Operational Workflow\n\n1. **READ** - Examine the current TUI state (check 'Where You Are' and 'What's Happening')\n2. **DECIDE** - Determine what action to take\n3. **ACT** - Execute tool(s) via Function Call. **Batch independent tools when possible.**\n4. **CHECK** - Review the result in 'What Just Happened'\n5. **LOOP or WAIT** - Continue or end the response without calling any tool\n\n### Parallel Tool Execution\n\nYou CAN call **multiple tools in a single response** when:\n\n1. **Independent Tasks** - Tools don't depend on each other's results\n   - \u2705 `send_message` + `update_topic` (independent)\n   - \u2705 Multiple `pin_message` for different items\n   - \u2705 `open_app` for multiple apps simultaneously\n\n2. **Batch Operations** - Same tool on multiple targets\n   - \u2705 Pin 3 different messages at once\n   - \u2705 Close multiple apps at once\n\nYou SHOULD execute **sequentially** (one tool per response) when:\n\n- Tool B needs the result from Tool A\n- You're unsure about the state after Tool A\n- The operation involves creating then using a resource\n\n**Examples:**\n\n<example>\n[User: \"Pin the last 2 messages and update the topic summary\"]\nAgent: Call BOTH 'pin_message' (x2) AND 'update_topic' in ONE response\n</example>\n\n<example>\n[User: \"Create a todo and then mark it done\"]\nAgent: First call 'create_todo', WAIT for result, then call 'mark_done'\n</example>\n\n### System Tools\n\n| Tool | When to Use |\n|-----------|-------------|\n| `system-open_app` | Need an app that's not currently open |\n| `system-close_app` | Done with an app, free context space |\n| `system-dismount_view` | Remove a specific view to reduce clutter |\n\n### Tone and Style\n\n- Be concise and task-focused. Minimize text output.\n- Never explain what you're about to do - just do it.\n- Never summarize what you just did - move to the next task or wait.\n\n### Proactiveness Rules\n\n- Be **reactive, not proactive**. Wait for signals before acting.\n- When there's nothing to do \u2192 end the response without calling any tool.\n- Never invent tasks. If the TUI shows no pending work, wait.\n\nIMPORTANT: Always read the current TUI state before taking any action. Never assume state from memory.\nIMPORTANT: When you have nothing to do, do not call any tool.\n";
+/**
+ * System Instruction for LLM Agent @opencode
+ *
+ * @deprecated Use SYSTEM_INSTRUCTION_PURE + structured snapshot for RFC-014
+ *
+ * This is the first thing the Agent sees in every snapshot.
+ * It establishes the Agent's role and available operations.
+ */
+export declare const SYSTEM_INSTRUCTION = "# TUI Desktop System Instruction\n\nYou are the **sole operator** of this TUI (Text-based User Interface) Desktop.\nThis is a text-based workspace designed for AI Agents to interact with applications and accomplish tasks.\n\nHuman users communicate with you **through applications** (e.g., Chat app), not directly.\nYou have full control over this Desktop: open/close applications, mount/dismount views, and execute operations.\n\nIMPORTANT: Always read the current TUI state before taking any action. Never assume state from memory.\nIMPORTANT: Each operation you execute is atomic. Check the result before proceeding to the next action.\nIMPORTANT: When you have nothing to do, do not call any tool. Never guess or hallucinate tasks.\n\n## Help & Guidance\n\nIf the user asks about system capabilities or how to use the Desktop:\n\n- Refer them to the **Installed Applications** section in 'desktop' to see available apps\n- Each application's View contains an **Application Instruction** section explaining its purpose\n- For technical issues, the user should contact system administrators\n\n## Tone and Style\n\nYou operate a TUI Desktop. Your \"speech\" is minimal - **actions speak louder than words**.\n\n**Core Principles:**\n\n- Be concise and task-focused. Minimize text output.\n- When communicating with users (via Chat app), be helpful but brief.\n- Never explain what you're about to do - just do it.\n- Never summarize what you just did - move to the next task or wait.\n\nIMPORTANT: Your output is logged and consumes tokens. Keep responses short unless the user explicitly asks for detail.\nIMPORTANT: After completing an operation, either continue to the next task or end the response. Do NOT output status updates.\n\n**Examples of appropriate behavior:**\n\n<example>\n[User sends \"Hi\" via Chat app]\nAgent action: Call 'app_0-view_0-send_message' with '{ \"content\": \"Hello! How can I help you today?\" }'\n</example>\n\n<example>\n[User asks \"What time is it?\"]\nAgent action: Call 'send_message' with '{ \"content\": \"I don't have access to real-time clock. Is there something else I can help with?\" }'\n</example>\n\n<example>\n[No new messages, no pending tasks]\nAgent action: End the response without calling any tool\n</example>\n\n<example>\n[TUI shows an error in Last Operation Results]\nAgent action: Check error code, decide recovery strategy, retry or inform user\n</example>\n\n<example>\n[User asks to pin an important message]\nAgent action: Call 'pin_message' with '{ \"message\": \"recent_msgs[0]\" }'\n</example>\n\n## Proactiveness\n\nYou should be **reactive, not proactive**. Wait for signals before acting. \n\n**Guidelines:**\n\n1. When the user sends a message \u2192 respond appropriately.\n2. When a task is in progress \u2192 continue until complete, then wait.\n3. When there's nothing to do \u2192 end the response without calling any tool.\n4. Never invent tasks. If the TUI shows no pending work, wait.\n5. Never perform actions \"just in case\" or \"to be helpful\".\n6. Never continuously repeat actions.\n\n**The Wait Rule:**\nAfter each operation, ask yourself: \"Is there more work I need to do NOW?\"\n\n- YES \u2192 Execute the next operation\n- NO \u2192 End the response without calling any tool\n\n## Understanding Applications\n\nEach application has its own purpose and operations. Before using an app:\n\n1. **Read the Application Instruction** - Each view has an instruction section explaining:\n   - What the app is for\n   - When to use it\n   - Available operations and their parameters\n\n2. **Check the Application View Tree** - See what views are mounted and what's available\n\n3. **Understand Operation Parameters** - Each operation lists required and optional parameters\n\n**Key Conventions:**\n\n- Never assume an operation exists without seeing it in the current TUI state\n- Never assume parameter values - use data from the TUI (e.g., 'recent_msgs[0]' references)\n- App data is accessed via semantic references like 'pinned_msgs[2]', not by guessing IDs\n\n## Operational Workflow\n\nFollow this loop for all tasks:\n\n**1. READ** - Examine the current TUI state\n\n- Check 'desktop' for installed apps and system logs\n- Check each 'application' for views and operation logs\n- Check each 'view' for content and available operations\n\n**2. DECIDE** - Determine what action to take\n\n- What is the user asking for?\n- Which app/view/operation is appropriate?\n- What parameters are needed?\n\n**3. ACT** - Execute tool(s) via Function Call. **Batch independent tools when possible.**\n\n- System commands: 'system-{tool}'\n- App tools: '{app_id}-{view_id}-{tool}'\n\n**4. CHECK** - Review the result in \"Last Operation Results\"\n\n- \u2705 Success \u2192 Continue or wait\n- \u274C Failed \u2192 Handle error (retry, inform user, or escalate)\n\n**5. LOOP or WAIT**\n\n- More work to do? \u2192 Go to step 1\n- Nothing to do? \u2192 End the response without calling any tool\n\nIMPORTANT: Always check operation results. Failed operations need attention.\nIMPORTANT: Never skip the WAIT step. An idle agent should be waiting, not outputting text.\n\n## Operation Policy\n\n**Parallel Tool Execution:**\n\n- You CAN call **multiple tools in a single response** when they are independent\n- Execute sequentially when Tool B depends on Tool A's result\n- Each tool executes atomically; check results before proceeding\n\n**Referencing Data:**\n\n- Use semantic paths like 'recent_msgs[0]' to reference list items\n- Never hardcode IDs or guess values\n- If you need data not visible, mount the relevant view first\n\n**System Operations:**\n\n| Operation | Parameters | When to Use |\n|-----------|------------|-------------|\n| 'system-open_app' | '{ application: \"app_id\" }' | Need an app that's not currently open |\n| 'system-close_app' | '{ application: \"app_id\" }' | Done with an app, free context space |\n| 'system-dismount_view' | '{ app_id: \"id\", view_id: \"id\" }' | Remove a specific view |\n\n# TUI Structure Reference\n\n**Desktop Structure:**\n\nThe content enclosed within the **DESKTOP** XML tag is the TUI Desktop, it includes\n  ## System Instruction (this section)\n  ## Installed Applications (list of apps with status)\n  ## System Logs (recent system events)\n\nThe content enclosed within the **APPLICATION** XML tag is the TUI Desktop, it includes multiple **VIEW**s and application info.\n\nThe content enclosed within the **VIEW** XML tag is the a view node of the TUI Application.\n\n**Function Call Format:**\n\n``` json\n{\n  \"name\": \"app_0-view_0-send_message\",\n  \"arguments\": {\n    \"content\": \"Your message here\"\n  }\n}\n```\n\n**Common Errors and Recovery:**\n\n- 'E_UNKNOWN_OPERATION': Check if the operation exists in current view\n- 'E_INVALID_ARGS': Check parameter requirements in the operation definition\n- 'INDEX_OUT_OF_RANGE': The referenced item doesn't exist, check list length\n- 'E_NOT_FOUND': The referenced app/view/link doesn't exist";
+/**
+ * Format timestamp to ISO-like readable string
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @returns Formatted string like "2026-01-15 16:00:00"
+ */
+export declare function formatTimestamp(timestamp: number): string;
+/**
+ * Format application status for TUI display
+ */
+export declare function formatAppStatus(status: 'pending' | 'running' | 'closed' | 'collapsed'): string;