# Resident SI and engine-link artifacts

An engine artifact supplies curated external engine links and implementation
instructions, much like supplying 3D printing instructions without doing the
printing. It does not run the engines, fabricate objects, include provider
subscriptions, or grant exclusive rights to external output.

The resident model is Gemini 3.1 Pro Preview via the existing Replit integration.
Each explicitly requested task consumes Replit AI credits. No background daily
agent trading or automatic publication is enabled by these interfaces.

## Delegation

Create a connection in **Personal agents** and select only the scopes you need.
The new **resident:run** scope is opt-in; existing read and actions:propose
connections do not acquire permission to spend AI credits.
Send credentials only in `Authorization: Bearer <token>`, never in URLs.

- MCP: `POST /api/agent/mcp` (stateless Streamable HTTP, JSON responses).
- A2A: `POST /api/agent/a2a` (A2A 0.3 JSON-RPC, non-streaming).
- Discovery: `GET /api/agent/.well-known/agent-card.json`.

Use your app's actual origin with these paths. The development preview is not
a published endpoint. Each connection stays bound to its network, human sponsor,
scopes, expiration and revocation policy.

## MCP

Supports `initialize`, `ping`, `tools/list`, `tools/call`, and notifications.
Negotiate protocol version 2025-11-25, 2025-06-18, or 2025-03-26.
Only authorized tools are listed:
`network_read`, `marketplace_list`, `wallet_read`, `library_list`,
`action_propose`, and `resident_run`.

For resident_run, arguments are:

```json
{"agentId":"your-active-resident-id","mode":"curate",
 "prompt":"Select an engine and explain how I can implement a 3D model.",
 "idempotencyKey":"a-unique-stable-request-key"}
```

Modes are `ask`, `curate`, and `create`. Create additionally requires `title`
and a configured `category`, and only a commissioner may request it.
It creates a private engine-link JSON package in **Stock**, awaiting commissioner
review and pricing. It never automatically creates external engine output,
publishes, buys, transfers Solar, or issues Solar.
Use `action_propose` for existing human-approved marketplace and wallet actions.

## A2A

Supports `message/send` and `tasks/get`; streaming, push notifications,
task cancellation and arbitrary outbound agent calls are not supported.
Text-only messages ask the first active sponsored resident in the delegated
network. An optional data part can specify the same resident_run fields
(except idempotencyKey, which comes from messageId):

```json
{"jsonrpc":"2.0","id":1,"method":"message/send","params":{
 "message":{"kind":"message","role":"user","messageId":"unique-message-id",
 "parts":[{"kind":"text","text":"Help me select a video engine."}]}}}
```

The returned task has a persisted ID. Retrieve it with:

```json
{"jsonrpc":"2.0","id":2,"method":"tasks/get","params":{"id":"returned-task-id"}}
```

Task access is bound to the originating connection. Reusing the same messageId
and identical input reuses the task rather than charging for duplicate inference.
Changing an input while reusing the key is rejected.

## Files and previews

Existing uploaded files remain supported (50 MiB maximum per file). Supported
images, audio, video, PDFs and text have previews. HTML/SVG are sandboxed with no
scripts or external resources. Engine-package links must match the catalog to be
clickable. Other formats offer metadata and bounded text/hex inspection plus
download, not a promise of rendering every proprietary format.

Previews use the same member/commissioner authorization as private downloads.
Marketplace visitors cannot access original files before their purchase.
Files are not malware-scanned. Provider account access and licensing are the
user's responsibility. App payments remain disabled unless separately authorized.