# AgentTeam Echo App Example

Echo App is an example AgentTeam App. It demonstrates how an App receives `agentteam.message.mention` deliveries and writes replies through the App runtime API.

The example supports both runtime transports:

- callback transport through `callback-server.mjs`;
- runner stream / claim transport through `runner.mjs`.

## App manifest

`manifest.json` declares the App capability:

- event: `agentteam.message.mention`;
- scopes: `app.mentions.read`, `messages.write`;
- transports: `callback`, `runner_stream`;
- runtime config schema: `response_prefix`, `allow_fail_command`.

In the workspace Apps page, choose **Create App**, enter the App name and
connection method, and submit. A workspace owner/admin creates it directly and
receives the initial runner token or callback secret once. A normal member
submits an App creation request and waits for an admin to approve it before
claiming that one-time credential. The creator then adds the App to a channel
and mentions it from that channel or one of its reply threads.

## Try the App

After the App is created and added to a target, send a direct mention:

```text
@echo-app multi hello AgentTeam
```

The App writes a progress reply and a completion reply, then explicitly acks the delivery.

A diagnostic failure path is available:

```text
@echo-app fail deploy
```

The App writes a short diagnostic reply and fails the delivery with the stable code `example_command_failed`.

## Callback transport

Run a local callback server:

```bash
cd kits/app-example/echo-app
AGENTTEAM_RUNTIME_BASE_URL=https://agentteam.example.test \
AGENTTEAM_WORKSPACE_ID=<workspace-id> \
AGENTTEAM_RUNTIME_TOKEN=<runtime-or-delivery-token> \
AGENTTEAM_CALLBACK_SIGNING_SECRET=<callback-signing-secret> \
PORT=8787 \
npm run callback
```

Expose `http://127.0.0.1:8787/events` through a TLS ingress or tunnel and enter the HTTPS base URL when creating the App. AgentTeam posts callback deliveries to `<configured base URL>/events`.

## Runner stream / claim transport

Run a private runner host that connects outbound to AgentTeam:

```bash
cd kits/app-example/echo-app
AGENTTEAM_RUNTIME_BASE_URL=https://agentteam.example.test \
AGENTTEAM_WORKSPACE_ID=<workspace-id> \
AGENTTEAM_RUNNER_TOKEN=<runner-token> \
AGENTTEAM_RUNNER_ID=staging-host-1 \
AGENTTEAM_RUNNER_MODE=stream \
npm run runner
```

Use `AGENTTEAM_RUNNER_MODE=claim` when the runner should use the HTTP claim fallback. The runner sends heartbeat metadata and processes delivery leases with the same reply, ack, and fail APIs.

## Local validation

The local test suite validates the manifest fixture, command parsing, callback signature verification, multi-reply behavior, explicit ack, and fail behavior:

```bash
cd kits/app-example/echo-app
npm test
```

These tests use an in-memory fake runtime client. They validate the example runtime contract without requiring a live AgentTeam server.