# External AI Quick Test

Use this scenario to test VOSCOM as a user-controlled AI agent.

## 1. Read public discovery

```http
GET /agent_manifest.php
GET /agent_context.php
GET /agent_quick_test.php
GET /agent_pair_api.php?action=manifest
```

Expected result:

- manifest returns JSON;
- context returns Markdown;
- pairing manifest returns JSON with `human_confirmation_required: true`.

## 2. Prepare pairing

```http
POST /agent_pair_api.php?action=prepare_pairing
Content-Type: application/json

{
  "owner_email": "human@example.com",
  "owner_username_hint": "human",
  "agent_name": "External Test Agent",
  "provider": "external-ai",
  "scopes": [
    "read_context",
    "read_projects",
    "read_library",
    "read_firmware",
    "create_project_draft",
    "request_validate",
    "request_build"
  ]
}
```

Expected result:

- response contains `pairing_token`;
- response contains `confirmation_url`;
- no agent token is issued yet.

## 3. Ask the human to confirm

Tell the human:

1. Register or log in to VOSCOM with the same email.
2. Confirm email and legal terms personally.
3. Open the returned `confirmation_url` or IDE tab `AI agent`.
4. Confirm the pairing.
5. Copy the issued `agent_token` once only if the agent can safely call APIs.

If the agent is a chat AI without direct API access, do not paste the token into chat. Use Manual Relay mode in IDE tab `AI agent`.

## 4. Read agent context with token

```http
GET /agent_api.php?action=context
Authorization: Bearer <agent_token>
```

Expected result:

- status is `ok`;
- response contains owner info, agent info, scopes, limits.

## 5. Read owner projects and library

```http
GET /agent_api.php?action=projects.list
Authorization: Bearer <agent_token>

GET /agent_api.php?action=library.list
Authorization: Bearer <agent_token>
```

Expected result:

- only this owner's projects are visible;
- no private data of other users is returned.

## 6. Create a pending project request

```http
POST /agent_api.php?action=project_draft.create
Authorization: Bearer <agent_token>
Content-Type: application/json

{
  "title": "External Agent Demo",
  "raw_mml": "PROJECT { name: External_Agent_Demo }\nMCU { selected: ESP32-S3 }\nMODULE sensor_demo { class: Sensor; bus: I2C; }\n"
}
```

Expected result:

- response contains `request_id`;
- status is `pending_user_confirmation`;
- no project is created until the human approves.

## 7. Human approves in IDE

The human opens IDE tab `AI agent`, reviews the request, and clicks approve.

Expected result:

- project is created only after approval;
- audit log contains the request and execution result.

## 8. Request validation or build

```http
POST /agent_api.php?action=project.validate.request
Authorization: Bearer <agent_token>
Content-Type: application/json

{ "project_id": 1 }
```

```http
POST /agent_api.php?action=project.build.request
Authorization: Bearer <agent_token>
Content-Type: application/json

{ "project_id": 1 }
```

Expected result:

- both calls create pending requests;
- build runs only after human approval;
- firmware artifact appears in the owner's firmware list.

## Hard rules

- Do not accept legal terms for the human.
- Do not ask the human to paste Bearer tokens into chat.
- Do not publish news, market products, or chat messages.
- Do not delete projects.
- Do not request database or shell access.
- Do not flash devices directly.
- Do not create repeated pending requests if the user has not approved or rejected the previous ones.
- Do not create another build request while one build request is already pending.

## Manual Relay quick check

If you cannot call the API directly:

1. Ask the human to open IDE tab `AI agent`.
2. Ask them to click `Prepare AI package`.
3. Read the exported context JSON.
4. Return one JSON command:

```json
{
  "action": "project.validate",
  "payload": {
    "project_id": 1
  },
  "human_summary": "Validate project #1 after the human imports this command."
}
```

The human imports the JSON. VOSCOM creates a pending request for approval.