### Install Dependencies and Start Development Server

Source: https://github.com/openkursar/hello-halo/blob/main/CONTRIBUTING.md

Clone the repository, install project dependencies, and start the development server using npm commands.

```bash
git clone https://github.com/openkursar/hello-halo.git
cd hello-halo

npm install

npm run dev
```

--------------------------------

### Development Setup for Halo

Source: https://github.com/openkursar/hello-halo/blob/main/docs/README.en.md

Use these commands to clone the repository, install dependencies, and start the development server. Ensure you have Git and Node.js installed.

```bash
# Development setup
git clone https://github.com/openkursar/hello-halo.git
cd hello-halo
npm install
npm run prepare        # Download binary dependencies for your platform
npm run dev
```

--------------------------------

### Build from Source Installation

Source: https://github.com/openkursar/hello-halo/blob/main/README.md

Instructions for cloning the repository, installing dependencies, and running the development server to build Hello Halo from source.

```bash
git clone https://github.com/openkursar/hello-halo.git
cd hello-halo
npm install
npm run prepare
npm run dev
```

--------------------------------

### Build Hello Halo from Source

Source: https://github.com/openkursar/hello-halo/blob/main/docs/README.en.md

Clone the repository, install dependencies, download binary dependencies, and run the development server. Ensure you have Node.js and npm installed.

```bash
git clone https://github.com/openkursar/hello-halo.git
cd hello-halo
npm install
npm run prepare        # Download binary dependencies for your platform
npm run dev
```

--------------------------------

### Install App

Source: https://context7.com/openkursar/hello-halo/llms.txt

Installs a new application into the system using a provided specification object and user configuration.

```APIDOC
## POST /api/apps/install

### Description
Installs an app from a spec object and user configuration.

### Method
POST

### Endpoint
/api/apps/install

### Parameters
#### Request Body
- **spaceId** (string) - Required - The ID of the space to install the app into.
- **spec** (object) - Required - The specification object for the app.
  - **name** (string) - Required - The name of the app.
  - **version** (string) - Required - The version of the app.
  - **author** (string) - Required - The author of the app.
  - **description** (string) - Required - A description of the app.
  - **type** (string) - Required - The type of the app (e.g., "automation").
  - **system_prompt** (string) - Required - The system prompt for the agent.
  - **subscriptions** (array) - Optional - List of subscriptions for the app.
    - **source** (object) - Required - The source of the subscription.
      - **type** (string) - Required - The type of the source (e.g., "schedule").
      - **config** (object) - Optional - Configuration for the source.
        - **cron** (string) - Required if type is "schedule" - The cron expression for the schedule.
  - **config_schema** (array) - Optional - The schema for user configuration.
    - **key** (string) - Required - The key for the configuration field.
    - **label** (string) - Required - The label for the configuration field.
    - **type** (string) - Required - The type of the configuration field (e.g., "email").
    - **required** (boolean) - Optional - Whether the field is required.
- **userConfig** (object) - Required - The user-specific configuration for the app.
  - **email** (string) - Example field, replace with actual config keys.

### Request Example
```bash
curl -X POST http://localhost:PORT/api/apps/install \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ \
    "spaceId": "uuid-...", \
    "spec": { \
      "name": "HN Daily", \
      "version": "1.0", \
      "author": "alice", \
      "description": "Daily Hacker News digest at 08:00", \
      "type": "automation", \
      "system_prompt": "You are an HN digest assistant. Fetch top 10 stories and email a summary.", \
      "subscriptions": [{ "source": { "type": "schedule", "config": { "cron": "0 8 * * *" } } }], \
      "config_schema": [{ "key": "email", "label": "Recipient Email", "type": "email", "required": true }] \
    }, \
    "userConfig": { "email": "user@example.com" } \
  }'
```
```

--------------------------------

### Install App from Store

Source: https://context7.com/openkursar/hello-halo/llms.txt

Install an application from the app store. Requires `spaceId` and optionally `userConfig` for app-specific settings.

```bash
curl -X POST http://localhost:PORT/api/store/apps/price-hunter/install \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ \
    "spaceId": "uuid-...", \
    "userConfig": { "product_url": "https://www.amazon.com/dp/B0...", "target_price": 299 } \
  }'
```

--------------------------------

### Install App from Store

Source: https://context7.com/openkursar/hello-halo/llms.txt

Installs an application from the app store into a specific space with user configuration.

```APIDOC
## POST /api/store/apps/{appSlug}/install

### Description
Installs an application from the app store into a specific space with user configuration.

### Method
POST

### Endpoint
/api/store/apps/{appSlug}/install

### Parameters
#### Path Parameters
- **appSlug** (string) - Required - The unique slug of the application to install.
#### Request Body
- **spaceId** (string) - Required - The ID of the space to install the app into.
- **userConfig** (object) - Optional - User-specific configuration for the installed app.
```

--------------------------------

### Install App (Digital Human - Electron IPC)

Source: https://context7.com/openkursar/hello-halo/llms.txt

Installs a new application, potentially a digital human app, by providing its specification and user configuration. Returns the appId upon successful installation.

```typescript
// Install an app
const { data: { appId } } = await window.halo.appInstall({
  spaceId: 'uuid-...',
  spec: { name: 'HN Daily', type: 'automation', version: '1.0', ... },
  userConfig: { email: 'user@example.com' }
})
```

--------------------------------

### Start Performance Monitoring

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/services/perf/README.md

Starts real-time performance monitoring. Optionally accepts configuration options.

```APIDOC
## perfStart

### Description
Starts real-time performance monitoring for main and renderer processes.

### Method
JavaScript API (called via `window.halo.perfStart`)

### Parameters
#### Options Object (Optional)
- **sampleInterval** (number) - Optional - The interval in milliseconds for sampling performance data. Defaults to a system-defined value.
- **warnOnThreshold** (boolean) - Optional - If true, warnings will be logged when performance thresholds are exceeded. Defaults to false.

### Request Example
```javascript
// Basic usage
await window.halo.perfStart()

// With options
await window.halo.perfStart({
  sampleInterval: 2000,
  warnOnThreshold: true
})
```

### Response
No explicit response data is documented for success. The monitoring starts in the background.
```

--------------------------------

### Install App API

Source: https://context7.com/openkursar/hello-halo/llms.txt

Installs a new application using a provided specification object and user configuration. Requires authentication and a JSON payload containing space ID, app spec, and user configuration.

```bash
curl -X POST http://localhost:PORT/api/apps/install \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "spaceId": "uuid-...".
    "spec": {
      "name": "HN Daily",
      "version": "1.0",
      "author": "alice",
      "description": "Daily Hacker News digest at 08:00",
      "type": "automation",
      "system_prompt": "You are an HN digest assistant. Fetch top 10 stories and email a summary.",
      "subscriptions": [{ "source": { "type": "schedule", "config": { "cron": "0 8 * * *" } } }],
      "config_schema": [{ "key": "email", "label": "Recipient Email", "type": "email", "required": true }]
    },
    "userConfig": { "email": "user@example.com" }
  }'
```

--------------------------------

### Full Automation App Example (Price Hunter)

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/PROTOCOL.md

A complete example of an automation app that monitors product prices and sends notifications. It includes system prompts, requirements, subscriptions, filters, memory schema, configuration schema, output, permissions, escalation, and store details.

```yaml
spec_version: "1"
name: "Price Hunter"
version: "1.0.0"
author: "alice"
description: "Monitors product prices and sends a notification when the target price is reached"
type: automation
icon: "shopping"

system_prompt: |
  You are a professional price-comparison agent.
  Check all price variants (official, third-party, coupons, membership) and compare against
  the 30-day price trend to determine whether the current price is at a low point.
  When a price drop meets the user's threshold, report via report_to_user(type="milestone").
  Always call report_to_user(type="run_complete") at the end of each run.

requires:
  mcps:
    - id: ai-browser
      reason: "Required for web interaction and price scraping"

subscriptions:
  - id: price-check
    source:
      type: webpage
      config:
        watch: "price-element"
    frequency:
      default: "30m"
      min: "10m"
      max: "6h"
    config_key: product_url

filters:
  - field: price_change_percent
    op: gt
    value: 5

memory_schema:
  price_history:
    type: array
    description: "Historical price records (with timestamps)"
  last_low_date:
    type: date
    description: "Date of the last detected price low"
  purchase_decision:
    type: string
    description: "Buy / wait decision and rationale"

config_schema:
  - key: product_url
    label: "Product URL"
    type: url
    required: true
    placeholder: "https://www.amazon.com/dp/"
  - key: target_price
    label: "Target Price"
    type: number
    required: true
    description: "Notify when the price drops below this value"

output:
  notify:
    system: true
    channels:
      - email
  format: "Current lowest price: {price} — {trend_analysis}"

permissions:
  - ai-browser

escalation:
  enabled: true
  timeout_hours: 24

store:
  slug: "price-hunter"
  category: shopping
  tags: ["price", "shopping", "alert"]
  locale: en-US
  min_app_version: "0.5.0"
  license: MIT
```

--------------------------------

### MCP App Example (PostgreSQL)

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/PROTOCOL.md

An example of a Machine Communication Protocol (MCP) app that provides AI with PostgreSQL database access. It includes MCP server configuration and database connection URL schema.

```yaml
name: "PostgreSQL MCP"
version: "0.3.1"
author: "community"
description: "Provides AI with PostgreSQL database access"
type: mcp

mcp_server:
  command: npx
  args:
    - "-y"
    - "@modelcontextprotocol/server-postgres"
  env:
    DATABASE_URL: "{{config.database_url}}"

config_schema:
  - key: database_url
    label: "Database Connection URL"
    type: url
    required: true
    placeholder: "postgresql://user:pass@localhost/db"

store:
  slug: "postgres-mcp"
  category: data
  tags: ["database", "postgresql", "sql"]
  locale: en-US
  license: MIT
```

--------------------------------

### Fork and Set Up Local Development Environment

Source: https://github.com/openkursar/hello-halo/blob/main/CONTRIBUTING.md

Steps to fork the repository, clone it locally, install dependencies, and create a new feature branch for development.

```bash
# Fork and clone
git clone https://github.com/YOUR_USERNAME/hello-halo.git
cd hello-halo
npm install

# Create a feature branch from main
git checkout -b fix/issue-number-description
# or
git checkout -b feat/new-feature-name
```

--------------------------------

### MCP Server Configuration

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/PROTOCOL.md

Defines how to start an MCP server process. This configuration is only allowed when `type` is set to `mcp`.

```yaml
type: mcp
mcp_server:
  command: npx
  args:
    - "-y"
    - "@modelcontextprotocol/server-postgres"
  env:
    DATABASE_URL: "{{config.database_url}}"
  cwd: "/optional/working/dir"
```

--------------------------------

### List Installed Apps API

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves a list of all currently installed applications that have not been uninstalled. Requires authentication.

```bash
curl -H "Authorization: Bearer <token>" http://localhost:PORT/api/apps
```

--------------------------------

### Start and Stop Performance Monitoring

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/services/perf/README.md

Use `perfStart` to begin monitoring and `perfStop` to end it. These functions are accessible from the renderer process's DevTools console.

```javascript
await window.halo.perfStart()   // Start monitoring
await window.halo.perfStop()    // Stop monitoring
```

--------------------------------

### Get Store App Detail

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieve detailed information about a specific app from the store using its ID.

```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:PORT/api/store/apps/price-hunter
```

--------------------------------

### App (Digital Human) IPC Channels

Source: https://context7.com/openkursar/hello-halo/llms.txt

Manage installed applications, including installation, listing, triggering, pausing, resuming, and retrieving state and activity.

```APIDOC
## App (Digital Human) IPC Channels

### Install App
Installs a new application.

```typescript
const { data: { appId } } = await window.halo.appInstall({
  spaceId: 'uuid-string',
  spec: { name: 'App Name', type: 'app-type', version: '1.0', ... },
  userConfig: { email: 'user@example.com' }
});
```

### List Apps
Retrieves a list of installed applications.

```typescript
const { data: apps } = await window.halo.appList({ status: 'active' });
```

### Trigger App
Manually triggers a running application.

```typescript
await window.halo.appTrigger('app-id-string');
```

### Pause App
Pauses a running application.

```typescript
await window.halo.appPause('app-id-string');
```

### Resume App
Resumes a paused application.

```typescript
await window.halo.appResume('app-id-string');
```

### Get App State
Retrieves the current real-time state of an application.

```typescript
const { data: state } = await window.halo.appGetState('app-id-string');
// state: { isRunning: boolean, lastRun: { ts, outcome, summary }, nextScheduled: number }
```

### Get App Activity
Retrieves activity entries for a specific application.

```typescript
const { data: entries } = await window.halo.appGetActivity('app-id-string', { limit: 10 });
```

### Respond to Escalation
Responds to an escalation request from an application.

```typescript
await window.halo.appRespondEscalation('app-id-string', 'entry-id-string', {
  ts: Date.now(),
  choice: 'approve' | 'reject',
  text: 'Your response text'
});
```

### On App Status Changed
Subscribes to changes in application status.

```typescript
window.halo.onAppStatusChanged(({ appId, status, previousStatus }) => {
  console.log(`App ${appId}: ${previousStatus} → ${status}`);
});
```

### On App Activity Entry
Subscribes to new activity entries for applications.

```typescript
window.halo.onAppActivityEntry(({ appId, entry }) => {
  if (entry.type === 'escalation') {
    // Handle escalation
  }
});
```
```

--------------------------------

### List Installed Apps

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves a list of all installed applications (apps) within the system that have not been uninstalled.

```APIDOC
## GET /api/apps

### Description
Lists all installed apps (non-uninstalled).

### Method
GET

### Endpoint
/api/apps

### Request Example
```bash
curl -H "Authorization: Bearer <token>" http://localhost:PORT/api/apps
```
```

--------------------------------

### Get Store App Detail

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves detailed information about a specific application from the store.

```APIDOC
## GET /api/store/apps/{appSlug}/detail

### Description
Retrieves detailed information about a specific application from the store.

### Method
GET

### Endpoint
/api/store/apps/{appSlug}/detail

### Parameters
#### Path Parameters
- **appSlug** (string) - Required - The unique slug of the application.
```

--------------------------------

### List Installed Apps (Digital Human - Electron IPC)

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves a list of installed applications, optionally filtered by status. The result contains an array of app objects.

```typescript
// List installed apps
const { data: apps } = await window.halo.appList({ status: 'active' })
```

--------------------------------

### Product Configuration for Custom Provider

Source: https://github.com/openkursar/hello-halo/blob/main/docs/custom-providers.md

Example of how to register a custom AI provider in the product.json file. This includes essential details like type, display name, path to the provider's entry point, and enablement status.

```json
{
  "authProviders": [
    {
      "type": "myprovider",
      "displayName": "My Provider",
      "description": "My custom AI provider",
      "icon": "globe",
      "iconBgColor": "#3b82f6",
      "recommended": false,
      "path": "./auth/dist/providers/myprovider/index.js",
      "enabled": true
    }
  ]
}
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/openkursar/hello-halo/blob/main/CONTRIBUTING.md

Examples of commit messages following the conventional commit format, specifying the type (feat, fix, docs, etc.) and a description.

```bash
# Format: <type>: <description>
# Types: feat | fix | docs | style | refactor | test | chore

git commit -m "fix: resolve input method issue in chat"
git commit -m "feat: add multi-model support"
git commit -m "docs: update README translation"
```

--------------------------------

### Get All IM Channel Instance Statuses

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieve the status of all configured instant messaging channel instances.

```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:PORT/api/im-channels/status
```

--------------------------------

### Memory.md Structure Example

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/platform/memory/DESIGN.md

Illustrates the two-tier markdown structure for persistent AI memory, separating current state (`# now`) from historical events (`# History`).

```markdown
# now

## State | brief one-line summary of current state
- runs_completed: 84
- alerts_sent: 5
- last_result: AirPods ¥1199, no change

## AirPods Pro (JD.com)
- current_price: ¥1199
- lowest_seen: ¥1099 (2026-01-08)
- last_change: 2026-01-10, ¥1299→¥1199
- trend: stable (5 days)

## MacBook Air M3 (Taobao)
- current_price: ¥7999
- lowest_seen: ¥7499 (2026-01-12)
- last_change: 2026-01-13, ¥7499→¥7999
- trend: rising

## Patterns
- prices are lowest on weekday mornings, highest on weekends
- price drops >10% are usually flash sales, revert within 48h
- user prefers notification only when price drops below previous lowest

## Errors
- JD anti-bot: switch to mobile User-Agent header
- Taobao layout changed 2026-01-11: use selector .price-current

# History

## 2026-01-15-1430 | routine check, no change

## 2026-01-15-1400 | MacBook ¥7999↑, alerted user
### Details
- MacBook Air: ¥7499→¥7999
- exceeded previous highest, sent notification

## 2026-01-15-1330 | routine check, no change
...

```

--------------------------------

### Minimal Automation App Example (HN Daily)

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/PROTOCOL.md

A minimal automation app that delivers a Hacker News top-stories digest daily. It includes a cron trigger and email notification configuration.

```yaml
name: "HN Daily"
version: "1.0"
author: "alice"
description: "Delivers a Hacker News top-stories digest every morning at 08:00"
type: automation

system_prompt: |
  You are an HN digest assistant. On each trigger:
  1. Open https://news.ycombinator.com and retrieve today's Top 10 stories
  2. Write a concise summary for each (2–3 sentences)
  3. Send an email notification
  4. Call report_to_user to report completion

subscriptions:
  - source:
      type: schedule
      config:
        cron: "0 8 * * *"

config_schema:
  - key: email
    label: "Recipient Email"
    type: email
    required: true

output:
  notify:
    channels:
      - email
```

--------------------------------

### Get App Activity Log

Source: https://context7.com/openkursar/hello-halo/llms.txt

Fetch the activity log for a specific application. Supports pagination with the `limit` query parameter.

```bash
curl -H "Authorization: Bearer <token>" \
  "http://localhost:PORT/api/apps/app-uuid/activity?limit=20"
```

--------------------------------

### Automation App Spec YAML Example

Source: https://context7.com/openkursar/hello-halo/llms.txt

Defines an 'Automation' type app named 'Price Hunter'. It includes system prompts, required capabilities, subscriptions, filters, memory and configuration schemas, output settings, escalation rules, and store/i18n details.

```yaml
spec_version: "1"
name: "Price Hunter"
version: "1.0.0"
author: "alice"
description: "Monitors product prices and sends a notification when the target price is reached"
type: automation
icon: "shopping"

system_prompt: |
  You are a professional price-comparison agent.
  Check all price variants (official, third-party, coupons) and compare against the 30-day trend.
  When a price drop meets the user's threshold, call report_to_user(type="milestone").
  Always call report_to_user(type="run_complete") at the end of each run.

requires:
  mcps:
    - id: ai-browser
      reason: "Web interaction and price scraping"

subscriptions:
  - id: price-check
    source:
      type: schedule
      config:
        every: "30m"      # or use: cron: "0 8 * * *"
    frequency:
      default: "30m"
      min: "10m"
      max: "6h"
    config_key: product_url   # user-supplied URL passed as trigger input

filters:
  - field: price_change_percent
    op: gt
    value: 5

memory_schema:
  price_history:
    type: array
    description: "Historical price records with timestamps"
  purchase_decision:
    type: string
    description: "Buy/wait decision and rationale"

config_schema:
  - key: product_url
    label: "Product URL"
    type: url
    required: true
    placeholder: "https://www.amazon.com/dp/"
  - key: target_price
    label: "Target Price (USD)"
    type: number
    required: true
  - key: notify_format
    label: "Notification Format"
    type: select
    options:
      - label: "Brief"
        value: brief
      - label: "Detailed"
        value: detailed

output:
  notify:
    system: true
    channels:
      - email
      - wecom
  format: "Current price: {price} — {trend}"

escalation:
  enabled: true
  timeout_hours: 24

permissions:
  - ai-browser

store:
  slug: "price-hunter"
  category: shopping
  tags: ["price", "amazon", "alert"]
  locale: en-US
  license: MIT

i18n:
  zh-CN:
    name: 价格猎手
    description: 监控商品价格，达到目标价格时发送通知
    config_schema:
      product_url:
        label: 商品链接
        placeholder: "https://item.jd.com/"
      target_price:
        label: 目标价格
```

--------------------------------

### SQLite Schema for Installed Apps

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/manager/DESIGN.md

Defines the structure of the 'installed_apps' table, including columns for app identification, status, configuration, and execution history. Indexes are provided for efficient querying.

```sql
CREATE TABLE installed_apps (
  id TEXT PRIMARY KEY,
  spec_id TEXT NOT NULL,
  space_id TEXT NOT NULL,
  spec_json TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'active',
  pending_escalation_id TEXT,
  user_config_json TEXT DEFAULT '{}',
  user_overrides_json TEXT DEFAULT '{}',
  permissions_json TEXT DEFAULT '{"granted":[],"denied":[]}',
  installed_at INTEGER NOT NULL,
  last_run_at INTEGER,
  last_run_outcome TEXT,
  error_message TEXT,
  UNIQUE(spec_id, space_id)
);
CREATE INDEX idx_installed_apps_space ON installed_apps(space_id);
CREATE INDEX idx_installed_apps_status ON installed_apps(status);
```

--------------------------------

### PostgreSQL MCP Server Configuration

Source: https://context7.com/openkursar/hello-halo/llms.txt

Defines the configuration for a PostgreSQL MCP server, including its name, version, author, description, and command-line arguments for starting the server. It also specifies environment variables and a configuration schema for database access.

```yaml
name: "PostgreSQL MCP"
version: "0.3.1"
author: "community"
description: "Provides AI with PostgreSQL database access"
type: mcp

mcp_server:
  command: npx
  args: ["-y", "@modelcontextprotocol/server-postgres"]
  env:
    DATABASE_URL: "{{config.database_url}}"   # template: references userConfig key

config_schema:
  - key: database_url
    label: "Database URL"
    type: url
    required: true
    placeholder: "postgresql://user:pass@localhost/db"

store:
  slug: "postgres-mcp"
  category: data
  tags: ["database", "postgresql"]
```

--------------------------------

### Resolve Model Capabilities with Overrides

Source: https://context7.com/openkursar/hello-halo/llms.txt

Resolves model capabilities, allowing for overrides. This example demonstrates enabling 'supportsThinking' for a specific model.

```bash
curl -X POST http://localhost:PORT/api/model-capabilities/resolve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "modelId": "claude-opus-4-5",
    "overrides": { "claude-opus-4-5": { "supportsThinking": true } }
  }'
```

--------------------------------

### Structured Filter Rule Example

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/DESIGN.md

Demonstrates the structured format for filter rules, using an array of objects with 'field', 'op', and 'value'. This approach is preferred over string-based DSLs for better validation and execution.

```yaml
filters:
  - field: price_change_percent
    op: gt
    value: 5
```

--------------------------------

### Tailwind CSS Styling Example

Source: https://github.com/openkursar/hello-halo/blob/main/CONTRIBUTING.md

Demonstrates the correct usage of Tailwind CSS with theme variables for background, text, and border colors. Avoid hardcoded color values.

```tsx
<div className="bg-background text-foreground border-border">

// Bad
<div className="bg-white text-black border-gray-200">
```

--------------------------------

### Retrieve Global Configuration

Source: https://context7.com/openkursar/hello-halo/llms.txt

Use this endpoint to get the current global configuration of Halo, including AI settings, permissions, and remote access details. Ensure you have a valid authorization token.

```bash
# Get current config
curl -H "Authorization: Bearer <token>" http://localhost:PORT/api/config

# Expected response:
{
  "success": true,
  "data": {
    "aiSources": {
      "version": 2,
      "currentId": "anthropic-default",
      "sources": [{ "id": "anthropic-default", "provider": "anthropic", "apiKey": "sk-..." }]
    },
    "permissions": { "allow": [], "deny": [] },
    "remoteAccess": { "enabled": true, "port": 3000 },
    "appearance": { "theme": "system" }
  }
}
```

--------------------------------

### Implementation Plan Steps

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/platform/store/DESIGN.md

Outlines the sequential steps for implementing the store module, from type definitions to final verification.

```plaintext
1. Create type definitions (`types.ts`)
2. Implement DatabaseManager class (`database-manager.ts`)
3. Implement `initStore()` and exports (`index.ts`)
4. Write unit tests (`tests/unit/platform/store/`)
5. Verify TypeScript compilation (`tsc --noEmit`)
6. Install `better-sqlite3` + `@types/better-sqlite3` if needed
```

--------------------------------

### Prepare Binaries for All Platforms

Source: https://github.com/openkursar/hello-halo/blob/main/docs/README.en.md

This command downloads binary dependencies for all target platforms, which can be useful before building for multiple environments.

```bash
npm run prepare:all
```

--------------------------------

### Configure Performance Monitoring Options

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/services/perf/README.md

Customize monitoring behavior by providing an options object to `perfStart`. Options include `sampleInterval` for sampling frequency and `warnOnThreshold` to enable threshold warnings.

```javascript
await window.halo.perfStart({
  sampleInterval: 2000,    // Sample interval (ms)
  warnOnThreshold: true    // Warn when threshold exceeded
})
```

--------------------------------

### Subscription Shorthand Form

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/PROTOCOL.md

Demonstrates the shorthand form for subscription configuration, which is equivalent to the canonical form.

```yaml
# Shorthand (accepted)
subscriptions:
  - type: schedule
    config:
      every: "1h"

# Equivalent canonical form
subscriptions:
  - source:
      type: schedule
      config:
        every: "1h"
```

--------------------------------

### Check for App Updates

Source: https://context7.com/openkursar/hello-halo/llms.txt

Checks for available updates for installed applications.

```APIDOC
## GET /api/store/updates

### Description
Checks for available updates for installed applications.

### Method
GET

### Endpoint
/api/store/updates
```

--------------------------------

### File Structure Overview

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/platform/store/DESIGN.md

Illustrates the directory structure for the store module, indicating the purpose of each file within the implementation.

```plaintext
src/main/platform/store/
  index.ts          -- Public API: initStore(), DatabaseManager, types
  database-manager.ts -- DatabaseManager implementation
  types.ts          -- Migration, DatabaseManager interfaces
```

--------------------------------

### Get Performance State

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/services/perf/README.md

Retrieves the current state of the performance monitoring.

```APIDOC
## perfGetState

### Description
Retrieves the current state of the performance monitoring, including any collected metrics.

### Method
JavaScript API (called via `window.halo.perfGetState`)

### Parameters
None

### Request Example
```javascript
const currentState = await window.halo.perfGetState()
```

### Response
#### Success Response
- The structure of the returned state is not explicitly defined in the documentation, but it represents the current monitoring status and collected data.
```

--------------------------------

### Get Chat Status

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves the current status of the chat generation for an application.

```APIDOC
## GET /api/apps/{appId}/chat/status

### Description
Retrieves the current status of the chat generation for an application.

### Method
GET

### Endpoint
/api/apps/{appId}/chat/status

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.
```

--------------------------------

### Get App Runtime State

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves the current runtime state of an application.

```APIDOC
## GET /api/apps/{appId}/state

### Description
Retrieves the current runtime state of an application.

### Method
GET

### Endpoint
/api/apps/{appId}/state

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application to get the state for.
```

--------------------------------

### Initialization

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/platform/store/DESIGN.md

Initializes the store and returns a DatabaseManager instance. This function handles lazy initialization and retries on failure.

```APIDOC
## initStore

### Description
Initializes the store and returns a DatabaseManager instance. Handles lazy initialization and retries on failure.

### Method
`async function`

### Returns
- `Promise<DatabaseManager>`: A promise that resolves to the DatabaseManager instance.
```

--------------------------------

### Get Activity Log

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves the activity log for a specific application, with optional limit.

```APIDOC
## GET /api/apps/{appId}/activity

### Description
Retrieves the activity log for a specific application.

### Method
GET

### Endpoint
/api/apps/{appId}/activity

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application to get the activity log for.
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of log entries to retrieve.
```

--------------------------------

### Check for App Store Updates

Source: https://context7.com/openkursar/hello-halo/llms.txt

Check for available updates for installed applications in the app store.

```bash
curl -H "Authorization: Bearer <token>" http://localhost:PORT/api/store/updates
```

--------------------------------

### Background Service Initialization and Shutdown Functions

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/platform/background/DESIGN.md

Provides the main functions for initializing and shutting down the background services. `initBackground` sets up the service, and `shutdownBackground` performs necessary cleanup.

```typescript
export function initBackground(): BackgroundService
export function shutdownBackground(): void
```

--------------------------------

### Get Full Conversation

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves the complete conversation history, including messages and agent thoughts.

```APIDOC
## GET /api/spaces/{spaceId}/conversations/{conversationId}

### Description
Retrieves the full conversation, including messages and thoughts.

### Method
GET

### Endpoint
/api/spaces/{spaceId}/conversations/{conversationId}

### Request Example
```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:PORT/api/spaces/uuid-/conversations/conv-uuid
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the conversation details.
  - **id** (string) - The unique identifier for the conversation.
  - **title** (string) - The title of the conversation.
```

--------------------------------

### Startup Snapshot Event Emission

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/services/analytics/DESIGN.md

Describes the events emitted by the startup snapshot module: `installed_apps.snapshot` and `app.run.replay`. The replay event is bounded and updates the watermark on success.

```typescript
installed_apps.snapshot
app.run.replay
```

--------------------------------

### Get All IM Channel Instance Statuses

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves the status of all configured instant messaging channel instances.

```APIDOC
## GET /api/im-channels/status

### Description
Retrieves the status of all configured instant messaging channel instances.

### Method
GET

### Endpoint
/api/im-channels/status
```

--------------------------------

### AI Browser MCP Server with Scoped Context

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/services/ai-browser/DESIGN.md

Shows how to create the AI Browser MCP server using a scoped context and a working directory. This ensures proper isolation for agent sessions.

```typescript
createAIBrowserMcpServer(scopedCtx, workDir)
```

--------------------------------

### Background Service Initialization

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/platform/background/DESIGN.md

Initializes the background service and returns an object conforming to the BackgroundService interface.

```APIDOC
## initBackground

### Description
Initializes the background service.

### Signature
```typescript
function initBackground(): BackgroundService
```

### Returns
- `BackgroundService`: An object that provides methods to interact with the background service.
```

--------------------------------

### Run All Tests (Bash)

Source: https://github.com/openkursar/hello-halo/blob/main/tests/README.md

Execute all automated tests in the project. Recommended before a release to ensure comprehensive quality checks.

```bash
npm run test
```

--------------------------------

### AI Browser MCP Server Creation

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/services/ai-browser/DESIGN.md

This is the primary entry point for creating the AI Browser MCP server. All side effects are initialized here idempotently.

```typescript
createAIBrowserMcpServer()
(sdk-mcp-server.ts)
```

--------------------------------

### Get App Runtime State

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieve the current runtime state of an application. Requires the application's ID.

```bash
curl -H "Authorization: Bearer <token>" http://localhost:PORT/api/apps/app-uuid/state
```

--------------------------------

### List All Spaces

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves a list of all project workspaces (Spaces) managed by Halo. Requires an authorization token.

```bash
# List all spaces
curl -H "Authorization: Bearer <token>" http://localhost:PORT/api/spaces
```

--------------------------------

### Get File Tree View

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves a hierarchical file tree view of the artifacts within a given space.

```APIDOC
## GET /api/spaces/{spaceId}/artifacts/tree

### Description
Gets a file tree view of artifacts within a space.

### Method
GET

### Endpoint
/api/spaces/{spaceId}/artifacts/tree

### Request Example
```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:PORT/api/spaces/uuid-/artifacts/tree
```
```

--------------------------------

### Get Specific IM Channel Instance Status

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves the status of a specific instant messaging channel instance by its ID.

```APIDOC
## GET /api/im-channels/status?instanceId={instanceId}

### Description
Retrieves the status of a specific instant messaging channel instance by its ID.

### Method
GET

### Endpoint
/api/im-channels/status

### Parameters
#### Query Parameters
- **instanceId** (string) - Required - The ID of the instance to retrieve the status for.
```

--------------------------------

### Apply Theme Before Render (JavaScript)

Source: https://github.com/openkursar/hello-halo/blob/main/src/renderer/index.html

Applies the user's theme preference (light, dark, or system) by manipulating CSS classes on the document element. It checks localStorage for theme settings and uses prefers-color-scheme for system defaults. This runs before the main application renders to prevent visual flashes.

```javascript
html, body, #root { background-color: #0a0a0a; }
html.light, html.light body, html.light #root { background-color: #ffffff; }
// Anti-flash: apply theme before render (default: dark)
(function() {
  try {
    var theme = localStorage.getItem('halo-theme');
    if (theme === 'light') {
      document.documentElement.classList.add('light');
    } else if (theme === 'system') {
      // system: check preference
      if (!window.matchMedia('(prefers-color-scheme: dark)').matches) {
        document.documentElement.classList.add('light');
      }
    }
    // default (no localStorage or 'dark'): stay dark, do nothing
  } catch (e) {}
  // Platform class for conditional CSS (e.g. backdrop-filter only on GPU-enabled platforms)
  if (navigator.userAgent.indexOf('Windows') !== -1) {
    document.documentElement.classList.add('platform-win');
  }
})();
```

--------------------------------

### Get Full Conversation API

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieves the complete conversation history, including messages and agent thoughts. Requires authentication.

```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:PORT/api/spaces/uuid-/conversations/conv-uuid
```

--------------------------------

### Pause App (Digital Human - Electron IPC)

Source: https://context7.com/openkursar/hello-halo/llms.txt

Pauses the execution of an installed application identified by its appId. This is an asynchronous IPC call.

```typescript
// Pause / resume
await window.halo.appPause(appId)
```

--------------------------------

### Export App Spec as YAML

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieve the application specification in YAML format.

```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:PORT/api/apps/app-uuid/export-spec
```

--------------------------------

### Download File API

Source: https://context7.com/openkursar/hello-halo/llms.txt

Initiates a download for a specified file. Requires authentication and the file path as a query parameter. The output is saved to a local file.

```bash
curl -H "Authorization: Bearer <token>" \
  "http://localhost:PORT/api/artifacts/download?path=/path/to/file.ts" -o file.ts
```

--------------------------------

### Duration String Format Validation

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/PROTOCOL.md

Regular expression for validating duration fields. Examples include '10s', '30m', '2h', '1d'.

```regex
^\d+[smhd]$
```

--------------------------------

### Create Space with Custom Path (Space IPC - Electron)

Source: https://context7.com/openkursar/hello-halo/llms.txt

Creates a new space with a specified name, icon, and a custom working directory path. Returns the created space object.

```typescript
// Create space with custom working directory
const { data: space } = await window.halo.createSpace({
  name: 'Web App',
  icon: 'globe',
  customPath: '/Users/alice/projects/web-app'
})
```

--------------------------------

### Get Specific IM Channel Instance Status

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieve the status of a specific instant messaging channel instance using its `instanceId`.

```bash
curl -H "Authorization: Bearer <token>" \
  "http://localhost:PORT/api/im-channels/status?instanceId=instance-id"
```

--------------------------------

### Output Format Configuration

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/PROTOCOL.md

Defines a format string for displaying output. Currently informational and not interpolated at runtime.

```yaml
output:
  format: "Current lowest price: {price} — {trend_analysis}"
```

--------------------------------

### AI-Initiated Download Flow

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/services/ai-browser/DESIGN.md

Illustrates the sequence of events for AI-initiated downloads, bypassing the native Save-As dialog. This flow involves routing through a session-level `will-download` handler to a specific BrowserContext for silent saving.

```text
wc.downloadURL(url)
  → Electron fires will-download on persist:browser session
    → download-handler.ts routes to owning BrowserContext
      → ctx.registerDownload() sets savePath (silent save)
        → ctx.updateDownloadProgress() resolves waitForDownload()
```

--------------------------------

### AppManagerService Interface

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/manager/DESIGN.md

The AppManagerService interface defines the contract for managing applications, including installation, uninstallation, status updates, and retrieval of application information.

```APIDOC
## AppManagerService Interface

This interface defines the contract for managing applications.

### Methods

- **install(spaceId: string, spec: AppSpec, userConfig?: Record<string, unknown>): Promise<string>**
  Installs a new application.

- **uninstall(appId: string, options?: { purge?: boolean }): Promise<void>**
  Uninstalls an application.

- **pause(appId: string): void**
  Pauses an application.

- **resume(appId: string): void**
  Resumes a paused or errored application.

- **updateConfig(appId: string, config: Record<string, unknown>): void**
  Updates the configuration of an application.

- **updateFrequency(appId: string, subscriptionId: string, frequency: string): void**
  Updates the execution frequency for a specific subscription of an application.

- **updateStatus(appId: string, status: AppStatus, extra?: { errorMessage?: string; pendingEscalationId?: string }): void**
  Updates the status of an application. This is a general status setter used by the runtime for states like 'error', 'needs_login', or 'waiting_user'.

- **updateLastRun(appId: string, outcome: RunOutcome, errorMessage?: string): void**
  Records the outcome of the last execution of an application.

- **getApp(appId: string): InstalledApp | null**
  Retrieves details of a specific application by its ID.

- **listApps(filter?: AppListFilter): InstalledApp[]**
  Lists all installed applications, with optional filtering.

- **getAppWorkDir(appId: string): string**
  Gets the working directory for a given application.

- **clearAppMemory(appId: string): number**
  Clears the memory associated with an application and returns the number of cleared items.

- **grantPermission(appId: string, permission: string): void**
  Grants a specific permission to an application.

- **revokePermission(appId: string, permission: string): void**
  Revokes a specific permission from an application.

- **onAppStatusChange(handler: StatusChangeHandler): Unsubscribe**
  Registers a handler to be called when an application's status changes.
```

--------------------------------

### Cron Expression Format

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/spec/PROTOCOL.md

Standard 5-field cron expression format for scheduling tasks. Examples include '0 8 * * *' for daily at 08:00.

```cron
minute hour day month weekday
```

--------------------------------

### Create a New Space

Source: https://context7.com/openkursar/hello-halo/llms.txt

Creates a new project workspace with a specified name, icon, and custom path. The response includes the unique ID of the newly created space.

```bash
# Create a new space
curl -X POST http://localhost:PORT/api/spaces \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Project",
    "icon": "code",
    "customPath": "/Users/alice/projects/my-app"
  }'
# Response: { "success": true, "data": { "id": "uuid- બના", "name": "My Project", ... } }
```

--------------------------------

### Get App Chat Status

Source: https://context7.com/openkursar/hello-halo/llms.txt

Retrieve the current status of the app's chat generation. Indicates if an AI response is currently being generated.

```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:PORT/api/apps/app-uuid/chat/status
```

--------------------------------

### Create a Conversation

Source: https://context7.com/openkursar/hello-halo/llms.txt

Initiates a new conversation within a specified project workspace. Requires the space's ID and a title for the new conversation.

```bash
# Create a conversation
curl -X POST http://localhost:PORT/api/spaces/uuid-/conversations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Build a REST API" }'
```

--------------------------------

### Get File Tree API

Source: https://context7.com/openkursar/hello-halo/llms.txt

Fetches the file tree structure for a given space. This provides a hierarchical view of the artifacts. Requires authentication.

```bash
curl -H "Authorization: Bearer <token>" \
  http://localhost:PORT/api/spaces/uuid-/artifacts/tree
```

--------------------------------

### Runtime Application File Structure

Source: https://github.com/openkursar/hello-halo/blob/main/src/main/apps/runtime/DESIGN.md

Outlines the directory structure for the runtime application, indicating the purpose of key files like types, errors, migrations, store, prompt, and execution logic.

```plaintext
src/main/apps/runtime/
  DESIGN.md           -- This file
  types.ts            -- AppRuntimeService, AppRunResult, AutomationAppState, ActivityEntry
  errors.ts           -- Runtime-specific error types
  migrations.ts       -- Schema for automation_runs + activity_entries
  store.ts            -- ActivityStore (CRUD for runs and entries)
  prompt.ts           -- buildAppSystemPrompt() for automation sessions
  report-tool.ts      -- report_to_user SDK MCP tool
  concurrency.ts      -- Counting semaphore
  execute.ts          -- executeRun() core logic
  service.ts          -- AppRuntimeService implementation
  index.ts            -- initAppRuntime(), shutdownAppRuntime(), re-exports
```

--------------------------------

### Provider Export Patterns

Source: https://github.com/openkursar/hello-halo/blob/main/docs/custom-providers.md

Demonstrates the two recommended export patterns for custom providers in their index.ts file: a getter function (recommended) or a direct class export.

```typescript
// Option A: Getter function (recommended)
export function getMyProvider(): MyProvider { ... }
```

```typescript
// Option B: Class export
export class MyProvider implements AISourceProvider { ... }
```