# CHASM Assistants

CHASM is Chaser's assistant runtime layer. It lets you create managed AI assistants that can execute code, browse the web, and interact with users through external messaging channels -- all backed by Chaser's session infrastructure.

## How it works

A CHASM assistant is a managed entity with:

- A **configuration** that defines its model, tools, memory policy, and alert thresholds
- **Channel bindings** that connect it to external messaging platforms (Telegram, Discord)
- **Credentials** stored securely in Chaser's vault for API keys and tokens the assistant needs
- **Runtime state** that persists across interactions
- A **dedicated workspace** for durable file storage and code execution

Assistants use the same `terminal` and `browser` MCP tools as any other Chaser integration. The difference is that Chaser handles authentication on behalf of signed-in product users, so the assistant does not need a separate API key.

## Assistant lifecycle

```bash
# Create an assistant
curl -sS "$CHASER_API_URL/v1/assistants" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-assistant",
    "config": {
      "model": {"provider": "anthropic", "model_id": "claude-sonnet-4-20250514"},
      "system_prompt": "You are a helpful coding assistant.",
      "tools": {"sandbox": true, "browser": true}
    }
  }' | jq

# List assistants
curl -sS "$CHASER_API_URL/v1/assistants" \
  -H "Authorization: Bearer $CHASER_API_KEY" | jq

# Pause/resume
curl -sS -X POST "$CHASER_API_URL/v1/assistants/<id>/pause" \
  -H "Authorization: Bearer $CHASER_API_KEY"
curl -sS -X POST "$CHASER_API_URL/v1/assistants/<id>/resume" \
  -H "Authorization: Bearer $CHASER_API_KEY"
```

## Channel bindings

Connect an assistant to external messaging platforms so it can receive and respond to messages.

```bash
# Bind to a Telegram channel
curl -sS "$CHASER_API_URL/v1/assistants/<id>/channels" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_type": "telegram",
    "channel_id": "<telegram_chat_id>",
    "config": {}
  }' | jq

# Remove a channel binding
curl -sS -X DELETE "$CHASER_API_URL/v1/assistants/<id>/channels/<binding_id>" \
  -H "Authorization: Bearer $CHASER_API_KEY"
```

Supported channel types: **Telegram** and **Discord**.

## Credentials vault

Store secrets the assistant needs (API keys, tokens) securely:

```bash
# Store a credential
curl -sS "$CHASER_API_URL/v1/assistants/credentials" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "OPENAI_API_KEY",
    "secret_value": "sk-..."
  }' | jq

# Resolve a credential (returns metadata, not the secret)
curl -sS "$CHASER_API_URL/v1/assistants/resolve-credential" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "OPENAI_API_KEY"}' | jq
```

Credentials are encrypted at rest and only accessible to the assistant runtime.

## Config change requests

For controlled updates to assistant configuration, use the approval-gated workflow:

```bash
# Propose a config change
curl -sS "$CHASER_API_URL/v1/assistants/<id>/config-change-requests" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proposed_change": {
      "config": {"system_prompt": "Updated prompt."}
    }
  }' | jq

# Approve or deny
curl -sS -X POST "$CHASER_API_URL/v1/assistants/<id>/config-change-requests/<request_id>/approve" \
  -H "Authorization: Bearer $CHASER_API_KEY"
```

## Runtime state

Assistants maintain persistent runtime state that survives across interactions:

```bash
# Get runtime state
curl -sS "$CHASER_API_URL/v1/assistants/<id>/runtime-state" \
  -H "Authorization: Bearer $CHASER_API_KEY" | jq

# Update runtime state
curl -sS "$CHASER_API_URL/v1/assistants/<id>/runtime-state" \
  -H "Authorization: Bearer $CHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -X PUT \
  -d '{"state": {"last_task": "deploy", "context": {}}}' | jq
```

## Usage tracking

Monitor assistant resource consumption:

```bash
# Get usage events
curl -sS "$CHASER_API_URL/v1/assistants/<id>/usage-events" \
  -H "Authorization: Bearer $CHASER_API_KEY" | jq
```

Usage events track token consumption, tool invocations, and session usage. Alert policies in the assistant config can trigger webhooks when thresholds are exceeded.

## Codex login for CHASM

CHASM supports OpenAI Codex authentication for assistants that need access to OpenAI services. The login flow uses a localhost callback URL pattern:

1. Call `GET /auth/codex/login-url` to get the authorization URL and PKCE verifier
2. Open the URL in a browser and authenticate with OpenAI
3. OpenAI redirects to a localhost callback URL
4. Copy the full localhost redirect URL and submit it to complete the authentication

This localhost callback approach is intentional -- OpenAI's Codex OAuth does not support remote callback URLs, so the redirect must go to localhost and be manually submitted back to Chaser.

## API reference

| Endpoint | Description |
|----------|-------------|
| `POST /v1/assistants` | Create assistant |
| `GET /v1/assistants` | List assistants |
| `GET /v1/assistants/{id}` | Get assistant details |
| `PATCH /v1/assistants/{id}` | Update assistant |
| `POST /v1/assistants/{id}/pause` | Pause execution |
| `POST /v1/assistants/{id}/resume` | Resume execution |
| `POST /v1/assistants/{id}/channels` | Add channel binding |
| `DELETE /v1/assistants/{id}/channels/{binding_id}` | Remove channel binding |
| `PUT /v1/assistants/credentials` | Store credential |
| `POST /v1/assistants/resolve-credential` | Resolve credential |
| `POST /v1/assistants/resolve-channel` | Resolve channel |
| `GET /v1/assistants/{id}/runtime-state` | Get runtime state |
| `PUT /v1/assistants/{id}/runtime-state` | Update runtime state |
| `POST /v1/assistants/{id}/usage-events` | Record usage event |
| `GET /v1/assistants/{id}/usage-events` | List usage events |
| `POST /v1/assistants/{id}/config-change-requests` | Propose config change |
| `POST /v1/assistants/{id}/config-change-requests/{rid}/approve` | Approve change |
| `POST /v1/assistants/{id}/config-change-requests/{rid}/deny` | Deny change |