# assistant

### uOS Assistant

Your intelligent companion that understands, learns, and executes tasks within the Third Space.

#### What it is

* **Intelligent task management**: The assistant doesn't just chat—it thinks, plans, and executes complex tasks across your entire operating system environment.
* **System-native**: Runs inside uOS, interacting with installed apps, system storage, and policies.
* **Transparent**: Agent Mode streams its reasoning, progress, and status in real-time.

#### Submit any task

Tell the assistant what you want to accomplish. It analyzes intent, selects the right app or tool, and executes.

* **Examples**:
  * "Play pokemon on uGAME"
  * "Organize my desktop files"
  * "Check my token balance"

### UI Overview

The assistant UI (implemented in `app/components/ai-assistant.tsx`) has two primary modes:

* **Standard mode**: Conversational Q\&A and lightweight actions.
* **Agent Mode**: Full autonomous task execution with live thinking and progress.

#### Main elements

* **Chat panel**: Conversation history, streaming replies, and rich cards (e.g., token launch summaries).
* **Agent Mode panel (AI Thinking Process)**: Real-time reasoning logs, context location, and app-specific visuals (e.g., uGAME screenshots).
* **Active Task status card**: Current task, progress bar, step/total, current action, and active app label.
* **Input bar**: Enter questions or commands. Tasks are detected automatically (or prefix with `Task:`).

#### Agent Mode — live example

Active Task: Play pokemon | App: uGAME | Step 1 of 5: Initializing task...

```
AI Thinking Process
Location: Unknown (0, 0)
Analyzing objective: play pokemon
Memory read from 0xd163: [0x00]
Screen changed: Unknown → Overworld
Memory read from 0xd35e: [0x00]
Current task: play pokemon
Exploring: ROUTE 1
Using varied movement pattern
$ _
```

### How it interacts with the Operating System

* **App orchestration**: Opens and controls apps like `uGAME` and `uTOKENIZE` via OS windowing and callbacks.
* **Background execution**: Tasks continue even if the UI is closed; state is persisted (localStorage) and restored.
* **Events**: Emits `aiTaskStateChange` and `aiTaskProgress` browser events for cross-app coordination.
* **Bridges & providers**:
  * `uGAME`: integrates with `gameboy-ai-bridge` to read screen/memory and drive inputs.
  * `uTOKENIZE`: integrates with `TokenDeploymentProvider` to deploy tokens and (optionally) create liquidity.
* **Permissions & policy**: The assistant requests consent when needed and respects OS-level budgets and limits.

Key functions in `ai-assistant.tsx`:

* **`analyzeTask`**: Classifies intent (uGAME, uTOKENIZE, browser, files, settings, general).
* **`submitBackgroundTask`**: Launches tasks end-to-end; opens required app; streams progress.
* **`toggleAgentMode` / `stopBackgroundTask`**: Control autonomous execution.
* **`aiTaskProgress` event**: Broadcasts step, totalSteps, and currentAction.

### Task Submission — Economic Model (v2)

USDC → Escrow → Meridian (x402) → Agent Execution → User Accepts → Escrow Release

#### Actors

* **User**: Submits task and funds escrow in USDC.
* **uOS**: Quotes price/SLA, routes tasks, enforces policy.
* **Meridian (x402)**: Payment layer; escrow and settlement rails.
* **Agent Directory**: Marketplace of agents/capabilities (ACP) discoverable by uOS.
* **Developer (Agent owner)**: Executes and delivers results.
* **Treasury / Protocol**: Receives fees and distributes to stakers/reserve.

#### End-to-end flow

1. **User asks** → uOS returns USDC quote and SLA.
2. **User pays** → USDC moves into on-chain escrow (Meridian x402).
3. **Route** → uOS selects an Agent from the Agent Directory; execution window starts.
4. **Deliver** → Agent submits result; User accepts.
5. **Release** → Escrow settles payouts and fees.
6. **Alternative** → If no response from user, auto-release after 24h challenge period; disputes pause release.

#### Settlement split (example; configurable by category)

* **Developer (Agent owner)**: 80%
* **uOS Treasury**: 5% (flows to veuOS stakers)
* **Meridian (payment layer)**: 5%
* **Protocol reserve**: 5%

####