# VCorp Super Agent: guide for agents

A personal Super Agent: the brain runs in the cloud, the user's own devices are its hands. Hand it a task in words and it does the whole job in a sandbox built for that kind of work, reaching the user's Chrome (with their logins), desktop apps, shared folders and phone when the task needs them: finished videos, research and form-filling on any website, social posts, live landing pages and web games, circuit layouts in EasyEDA, 3D-printable parts. It acts only in the user's own accounts; passwords and one-time codes are always entered by the user, and sending, posting or paying waits for the user's confirmation on their device. Tasks take minutes to an hour, can repeat on a schedule, and are billed to the account balance.

- MCP: `https://maker-dev-test.vcorp.ai/mcp` (Streamable HTTP, stateless, POST only)
- REST: `https://maker-dev-test.vcorp.ai/v1`, described by [OpenAPI](https://maker-dev-test.vcorp.ai/openapi.json)
- Overview for LLMs: [llms.txt](https://maker-dev-test.vcorp.ai/llms.txt) · Agent Skill: [SKILL.md](https://maker-dev-test.vcorp.ai/agents/SKILL.md)

## Accounts and auth

Accounts are made by the site's admin, and each has credits (from a subscription plan and credit packs) that tasks are paid with. A connected agent acts as the account's owner: it reaches everything the account owns (its tasks, its paired devices, its credits) and nothing of anyone else's. It cannot change the password, API keys or device pairings. Two ways to authenticate:

1. **OAuth 2.1** (MCP only): the MCP endpoint answers 401 with `WWW-Authenticate: Bearer resource_metadata="https://maker-dev-test.vcorp.ai/.well-known/oauth-protected-resource/mcp"`. Authorization server metadata is at `https://maker-dev-test.vcorp.ai/.well-known/oauth-authorization-server`; clients register at `/oauth/register` (RFC 7591), use the code flow with PKCE S256, and get one-hour access tokens with rotating refresh tokens. Scope: `tasks`. The user can revoke an app in the web app.
2. **API key** (MCP and REST): `Authorization: Bearer ovm_...`, made in the web app under 接入 Agent (up to 10, shown once, revocable).

## Setup by client

### Clients that log in with OAuth (no key to copy)

- **Claude.ai / Claude Desktop**: Settings → Connectors → Add custom connector, URL `https://maker-dev-test.vcorp.ai/mcp`. You are sent here to log in and approve.
- **ChatGPT**: add a custom connector (MCP) with URL `https://maker-dev-test.vcorp.ai/mcp` and OAuth authentication.
- **Cursor**: `~/.cursor/mcp.json`
  ```json
  { "mcpServers": { "vcorp-super-agent": { "url": "https://maker-dev-test.vcorp.ai/mcp" } } }
  ```
  Cursor opens the login page on first use. Use OAuth here: Cursor starts OAuth whenever a server offers it, even with an Authorization header configured.
- **VS Code**: `.vscode/mcp.json`
  ```json
  { "servers": { "vcorp-super-agent": { "type": "http", "url": "https://maker-dev-test.vcorp.ai/mcp" } } }
  ```

### Clients that use an API key

Create a key in the web app under 接入 Agent. It is shown once.

- **Claude Code**: `claude mcp add --transport http vcorp-super-agent https://maker-dev-test.vcorp.ai/mcp --header "Authorization: Bearer ovm_..."` (or leave out `--header` and log in with `/mcp`)
- **Codex CLI**: `~/.codex/config.toml`, with the key in the environment variable `OVM_API_KEY`
  ```toml
  [mcp_servers.vcorp-super-agent]
  url = "https://maker-dev-test.vcorp.ai/mcp"
  bearer_token_env_var = "OVM_API_KEY"
  ```
- **Gemini CLI**: `settings.json`
  ```json
  { "mcpServers": { "vcorp-super-agent": { "httpUrl": "https://maker-dev-test.vcorp.ai/mcp", "headers": { "Authorization": "Bearer ovm_..." } } } }
  ```
- **Anything else** (n8n, Dify, Coze, GPT Actions, scripts): the REST API, see below.

## Kinds of task on this server

- `video`: A finished MP4 (promo, explainer, motion graphics, music video, edit of their footage): plans the shots, animates in code, renders frame by frame, adds voice-over. 10-60 min.

## How a task runs

VCorp Super Agent is the user's own agent in the cloud, with the user's devices as its hands. Hand it a task in words (plus files or links) and it does the whole job in a sandbox built for that kind of work, then reports back: a finished video, work done in the user's own Chrome, desktop apps or phone (with their real logins), a social post, a live landing page or web game, a circuit layout, a program analysis, a 3D-printable part. Everything this account owns is yours to use: its tasks, its paired devices, its balance.

Workflow:
1. get_capabilities lists the kinds of task this server runs. list_devices shows the user's browsers, computers and phones, and which can run unattended.
2. create_task(kind, prompt, ...) returns a job_id immediately. The job is queued with the user's other tasks.
3. Call wait_for_task(job_id) repeatedly. Each call returns within about a minute, sooner if the task ends or needs you. Follow its "next" field.
   If you cannot wait, give the job_id to the user and check back later with get_task: the task keeps running without you.
4. When status is "done": report (for most kinds), video_url (video), site_url (landing, game) and files hold the results. Links last 7 days; call get_task again for fresh ones.
5. To follow up on a finished task, or change a plan that waits for review, send_message. A failed, interrupted or cancelled task resumes with continue_task.

Beyond the deliverables, list_task_files and read_task_file reach every file of a task (its input, notes, drafts). When the server has the user's library, library_list/read/upload/mkdir/delete work on their cloud drive, and get_profile / update_profile on their standing defaults (PROFILE.md: avatar, voice, brand), which every task follows on its own.

Instead of polling you may pass callback_url (https, public): the server POSTs there when the task is done, failed, cancelled, waiting for plan review, or left interrupted by a restart, and retries for about a day until it gets a 2xx. Requests follow Standard Webhooks (https://www.standardwebhooks.com/): verify the "webhook-signature" header with the webhook.secret returned by create_task; the body is {type, timestamp, data} where data is what get_task returns. Events may arrive more than once or out of order; use data.updated_at, and answer 410 to stop them.

Plans are not reviewed by default: a video renders straight after planning, a landing page goes live. With review=true the task stops at "awaiting_approval"; then approve_task or send_message with changes. A publish task always stops there before posting.
Browser, desktop and EDA tasks may repeat on a schedule (repeat): each run starts fresh, remembers the last through its files, and stops itself on repeated failures or when the user must step in; repeat_task pauses and resumes it.
The user's devices enforce their own rules: only sites and apps the user approved, and a confirmation on the device before payments or sends unless the user turned that off.
Pass a client_request_id with create_task and reuse it when retrying, so a retry after a timeout does not start (and bill) a second task.
Every task is paid in credits from the account and capped by budget (credits); get_account shows the credits, plan and limits before you start.

Statuses: `queued` → `planning` → (`awaiting_approval` when review is on, always for publish) → `rendering` (the main work, whatever the kind) → `done`. Tasks of the other kinds have no plan to review and work from the start. A task can also end `failed`, `cancelled`, or `interrupted` (cut off by a server restart; tasks that act on the outside world do not resume by themselves). `continue_task` resumes the last three. Every view has `kind`, `next` (what to do now, in words) and `poll_after_seconds`; a finished task has `report` (its REPORT.md or PLAN.md) and `files`, a video `video_url`, a site `site_url`.

A typical agent turn:

1. `get_capabilities` (once) and `get_account`, if unsure the credits cover a new task. `list_devices` when the task needs the user's browser, computer or phone.
2. `create_task` with `kind` and a `client_request_id` → `job_id`.
3. Tell the user the job_id and roughly how long it takes.
4. `wait_for_task` in a loop while the status is queued, planning or rendering; or stop and check back later with `get_task`; or rely on the webhook.
5. On `done`: hand over the results (links valid 7 days; `get_task` gives fresh ones). To change something or go on, `send_message`.

## Using the user's devices

Browser, desktop, publish and EDA tasks work in the user's own Chrome through the vcorp-chrome extension, and on their computer's apps and shared folders through its desktop part; browser tasks also reach a phone paired through Pinky. The rules live on the device: a task only reaches sites and apps the user approved, and sends, posts and payments wait for the user's confirmation unless they turned that off in the extension. Passwords and one-time codes are always left to the user. `device_id` locks a task to one browser or phone; `deny_devices` keeps it off some.

## Repeating tasks

`repeat` on a browse, desktop, eda, mcn task runs it again every `every_minutes` (5-1440), within an optional `from_hour`-`to_hour` window of the user's day, up to `daily_cap` credits a day (required) with `budget` credits per run. Nobody is there to confirm, so it needs a browser with `unattended: true` in `list_devices` (the user turns on 自动允许新任务 and 对外动作不再逐条确认 in the extension). Each run starts a fresh session and remembers earlier runs through its files. A run is skipped while the last one runs, the browser is offline, the credits are short or the daily cap is reached; three failures in a row, or a step only the user can do (a QR login), pause the repeats. `repeat_task` pauses, resumes or runs it now; `get_task` shows `repeat`.

## Files, library and profile

A task keeps three folders: `input/` (what it was given), `work/` (its notes, drafts, scripts and intermediate files) and `output/` (what it delivered). `get_task` links the `output/` files; `list_task_files` lists all three with links and `read_task_file` returns a small text file inline, or an image as an image.

This server has no library connected, so the library and profile tools are not offered.

Links to files are signed and last 7 days, like the others.

## Tools

### get_capabilities

What this server can do: the kinds of task it runs (with what each delivers, whether it can stop for review or repeat), video styles, voices, and whether AI-generated media and the user's library are available.

### get_account

Balance, what a new task needs to start, tasks queued or running, and the limits that apply. Check it before create_task if you are unsure the account can pay.

### list_devices

The user's paired devices: browsers (Chrome with vcorp-chrome), computers (desktop apps and shared folders), phones, and whether each is online. A browser with unattended=true can serve repeating tasks. Use a device_id to lock a task to one device or keep it off one.

### create_task

Hand a task to the Super Agent. Returns a job_id at once; the work takes minutes to an hour. Follow up with wait_for_task or get_task. Options that do not apply to the kind are ignored.

| Argument | Type | Notes |
|---|---|---|
| `kind` | `video` | What kind of task. video: A finished MP4 (promo, explainer, motion graphics, music video, edit of their footage): plans the shots, animates in code, renders frame by frame, adds voice-over. 10-60 min. Default `"video"`. |
| `prompt` * | string | The task in full: goal, audience or sites involved, what to deliver, must-haves, how to use the attached material. Any language. |
| `files` | array of object | Small attachments inline, at most 20 MB decoded in total per call: images, audio, video, PDF, Word (.docx), txt, md. Put larger material behind links. |
| `links` | array of string | http(s) links to articles, pages or PDFs to use as material. Fetched inside the task's sandbox, not by this server. |
| `refs` | array of string | job_ids of your ended tasks (done, or failed/interrupted/cancelled with partial results) whose results this one builds on, e.g. a research report for a video. Their deliverables (not their sessions) arrive read-only; with more than 3, their video and audio files stay behind. Say in the prompt what to take from them. The task given as `after` may also be listed while it is still running: this one waits for it and gets its results when it starts. |
| `after` | string | job_id of one of your tasks this one waits for: it starts when that one is done and gets its results. |
| `budget` | integer | Hard cap on what this task may spend, in credits. For a repeating task, per run. The account's plan may allow less (get_account limits.budget_credits). Default `2500`. |
| `effort` | `low` / `medium` / `high` / `xhigh` / `max` | How hard the agent thinks. Higher is slower and costs more. Default `"high"`. |
| `review` | boolean | video, landing, game: stop after planning for approve_task / send_message instead of going straight on. A publish task always stops for review. Default `false`. |
| `device_id` | string | Lock the task to this one browser or phone (from list_devices); it uses no other device. |
| `deny_devices` | array of string | device_ids this task must not use. |
| `aspect` | `16:9` / `9:16` / `1:1` / `4:3` | video: frame shape. 9:16 for vertical phone video. Default `"16:9"`. |
| `duration_seconds` | integer | video: length. Default `30`. |
| `style` | `auto` / `explainer` / `news` / `product` / `art` / `motion` / `mv` / `edit` | video: kind of video. auto: 由你按内容判断; explainer: 知识解说／科普动画; news: 竖屏资讯／评测; product: 产品宣传片; art: 艺术风格动画（按需求里描述的画风）; motion: 抽象动效／动态字体／showreel; mv: 跟音乐卡点的 MV; edit: 在用户的视频素材上剪辑、加字幕 Default `"auto"`. |
| `voice` | `none` / `中文` / `英文` / `中英双语` | video: voice-over: none, Chinese (中文), English (英文), or one version in each (中英双语). Default `"中文"`. |
| `auto_gen` | boolean | video: generate stills and short clips when needed. Each costs about 125 credits against budget. Ignored when the server has not enabled it. Default `false`. |
| `ruler` | boolean | video, landing, game: push the design away from the generic (反平庸). Default `false`. |
| `auto_publish` | string | video, without review: once rendered, publish it from the user's browser. Say where and how (platforms, title, tags). |
| `slug` | string | landing, game: subdomain to publish on (3-63 lowercase letters, digits, -). Reusing one of your own replaces that site. Default: a random one. |
| `repeat` | object | browse, desktop, eda: run again on a schedule after the first run, e.g. to watch a site and answer new messages. Needs a browser with unattended=true (list_devices). Runs that overlap, find the browser offline or hit the daily cap are skipped. |
| `client_request_id` | string | Your own id for this request. Retrying with the same id within 24 hours returns the existing task instead of starting another. |
| `callback_url` | string | Optional https URL on a public host to POST to when the task settles (Standard Webhooks; the signing secret comes back as webhook.secret). Lets you stop polling. |

### wait_for_task

Wait for a task to end or need attention, up to timeout_seconds (default 45, max 55), then return its state like get_task. Call it again while status is queued, planning or rendering.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |
| `timeout_seconds` | integer |  Default `45`. |

### get_task

Current state of a task: status, queue position, cost, recent progress, its report, and download links for every output file. When a video plan awaits review, the contact sheet is attached as an image.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |

### list_tasks

Recent tasks of this account, newest first.

| Argument | Type | Notes |
|---|---|---|
| `status` | string | Only tasks in this status (queued, planning, awaiting_approval, rendering, done, failed, cancelled, interrupted). |
| `kind` | string | Only tasks of this kind. |
| `limit` | integer |  Default `10`. |

### approve_task

For a task in awaiting_approval: accept the plan and go on (render the video, build the site, post). Optional feedback is applied on the way.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |
| `feedback` | string |  |

### send_message

Talk to a task that is not running. In awaiting_approval this redoes the plan with your changes; on a done task it is a follow-up in the same session (change the video, the old cut kept as final_vN.mp4; do more on the site; ask about the report). May bring new files and links.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |
| `text` * | string | What to change or do next. |
| `files` | array of object | Small attachments inline, at most 20 MB decoded in total per call: images, audio, video, PDF, Word (.docx), txt, md. Put larger material behind links. |
| `links` | array of string | http(s) links to articles, pages or PDFs to use as material. Fetched inside the task's sandbox, not by this server. |

### continue_task

Resume a failed, interrupted or cancelled task from where it stopped. A task that acts on the outside world checks first what it already did.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |
| `note` | string | Optional extra instructions. |
| `files` | array of object | Small attachments inline, at most 20 MB decoded in total per call: images, audio, video, PDF, Word (.docx), txt, md. Put larger material behind links. |
| `links` | array of string | http(s) links to articles, pages or PDFs to use as material. Fetched inside the task's sandbox, not by this server. |
| `budget` | integer | Raise the task's budget (credits) when it stopped at its cap. |

### repeat_task

For a repeating task: pause its runs, resume them (also after it paused itself), or run once now. run_now on a paused task runs once and leaves it paused.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |
| `action` * | `pause` / `resume` / `run_now` |  |

### cancel_task

Stop a queued or running task, or drop a plan that waits for approval. What it has spent so far stays billed; continue_task can pick it up again.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |

### list_task_files

Every file of a task, not only its deliverables: input/ (the material it was given), work/ (its notes, drafts, scripts, intermediate files) and output/ (what it delivered), each with a signed download link.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |
| `folder` | `input` / `work` / `output` | Only this folder. |
| `prefix` | string | Only paths starting with this, e.g. work/research/. |
| `limit` | integer |  Default `200`. |

### read_task_file

One file of a task by its path from list_task_files (e.g. work/notes.md). Text comes back inline (the first 100 KB), an image up to 1.5 MB as an image; every answer has a download link.

| Argument | Type | Notes |
|---|---|---|
| `job_id` * | string | The job_id returned by create_task. |
| `path` * | string |  |


## Limits

- Inline files: 20 MB decoded per call in total; put larger material behind `links` (fetched inside the sandbox, never by this server).
- A long poll waits at most 55 seconds.
- Each account has room for at least 5 tasks queued or running (more with more browsers paired); repeating tasks and tasks waiting for another take no room. A task made when there is no room is still accepted: it waits in line (`waiting_for_room`) and starts by itself when one of the others ends.
- 120 requests per minute per key or app.
- A new task needs a minimum of credits (see `get_account`); each task is capped by `budget` (credits, at most the plan's `limits.budget_credits`).

## REST

The same operations, with an API key. Bodies and answers are the MCP arguments and views as JSON. Errors are `{"error": {"status", "message"}}`.

| | |
|---|---|
| `GET /v1/capabilities` | get_capabilities |
| `GET /v1/account` | get_account |
| `GET /v1/devices` | list_devices |
| `POST /v1/tasks` | create_task. `Idempotency-Key` header works like `client_request_id`. 202 when created, 200 for a repeat. |
| `GET /v1/tasks?status=&kind=&limit=` | list_tasks |
| `GET /v1/tasks/{id}` | get_task |
| `GET /v1/tasks/{id}/wait?timeout=45` | wait_for_task |
| `POST /v1/tasks/{id}/approve` `{feedback?}` | approve_task |
| `POST /v1/tasks/{id}/message` `{text, files?, links?}` | send_message |
| `POST /v1/tasks/{id}/continue` `{note?, files?, links?, budget?}` | continue_task |
| `POST /v1/tasks/{id}/repeat` `{action}` | repeat_task |
| `POST /v1/tasks/{id}/cancel` | cancel_task |
| `GET /v1/tasks/{id}/files?folder=&prefix=&limit=` | list_task_files |
| `GET /v1/tasks/{id}/file?path=` | read_task_file |
| `GET /v1/library?path=` | library_list |
| `GET /v1/library/file?path=` | library_read |
| `POST /v1/library/upload` `{path, files, replace?}` | library_upload |
| `POST /v1/library/mkdir` `{path}` | library_mkdir |
| `DELETE /v1/library?path=&type=` | library_delete |
| `GET /v1/profile` | get_profile |
| `PUT /v1/profile` `{text, base}` | update_profile |

```sh
curl -s https://maker-dev-test.vcorp.ai/v1/tasks -H "Authorization: Bearer $OVM_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: competitor-prices-1" \
  -d '{"kind": "browse", "prompt": "Collect the prices of the three plans on example.com and example.org into a table"}'
curl -s "https://maker-dev-test.vcorp.ai/v1/tasks/<job_id>/wait?timeout=45" -H "Authorization: Bearer $OVM_API_KEY"
```

## Webhooks

Pass `callback_url` (https, public host) to create_task. The server POSTs `{type, timestamp, data}` when the task is `done` (`task.done`), `failed`, `cancelled`, waiting for review (`task.awaiting_approval`), or left `interrupted`; `data` is what get_task returns. Signed per [Standard Webhooks](https://www.standardwebhooks.com/): headers `webhook-id`, `webhook-timestamp`, `webhook-signature: v1,<base64 HMAC-SHA256 of "id.timestamp.body">`, keyed with the base64 part of `webhook.secret` (`whsec_...`) from create_task. Any 2xx counts as delivered; otherwise retried for about a day. Answer 410 to stop. Deliveries can repeat or arrive out of order: dedupe on `webhook-id`, order by `data.updated_at`.

## Building on earlier tasks

Pass `refs` (up to 10 job_ids of your own tasks that have ended; one that failed or was cancelled hands on whatever it got to) to build on their results, e.g. a video from a browser task's research. Only their deliverables reach the new task, read-only, never their sessions or scratch files. With more than 3, their video and audio files stay behind; their notes, stills and storyboards still come. Say in `prompt` what to take from them. `after` instead makes the new task wait until one task is done, then start with its results. The server must have its library (Seafile) connected (`get_capabilities`.library).

## Shared results

A task the owner shares has a public page `https://maker-dev-test.vcorp.ai/s/<token>`; a video's carries schema.org `VideoObject` JSON-LD, and the same content is JSON at `https://maker-dev-test.vcorp.ai/s/<token>.json`.
