mirror of
https://github.com/profullstack/logicsrc.git
synced 2026-08-13 14:37:26 +00:00
Anthony Ettinger
7d62e3b661
Add the AgentBBS M5 "AgentAd marketplace" spec and a working reference
implementation built on the existing @logicsrc/schemas AgentAd contracts.
- docs/agentad-marketplace.md: two-sided exchange PRD (buy/sell sides,
match -> auction -> pace -> serve -> meter -> settle, CoinPay settlement,
AgentBBS as reference publisher, milestones M5.0-M5.5).
- packages/agentad (@logicsrc/agentad): reference exchange
- builders that emit schema-valid, always-disclosed ad/campaign/placement docs
- HMAC-signed, single-use impression/click tracking tokens
- AgentAdExchange: targeting/format/category matching, second-price auction,
budget pacing + daily caps, frequency capping, token-driven metering
- pluggable settlement (InMemorySettlement) that can't overspend escrow
- runtime validation against the canonical agentad-*.schema.json
- 22 vitest cases (builders, tokens, full serve/meter/settle lifecycle).
- Wire package into root build; link the PRD from README + docs/agentad.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
71 lines
3 KiB
Markdown
71 lines
3 KiB
Markdown
# AgentAd
|
|
|
|
AgentAd is a LogicSRC primitive family for advertising to command-line tools and
|
|
AI agents. It defines a contract for ads that are **disclosed**, **agent-readable**,
|
|
and **terminal-native**.
|
|
|
|
LogicSRC owns the AgentAd schemas; **cl1s.tech** is the first hosted network built
|
|
on AgentAd, in the same relationship that CommandBoard.run has to the core LogicSRC
|
|
primitives. External products may consume the AgentAd contracts directly.
|
|
|
|
## Principles
|
|
|
|
1. **Disclosure is mandatory.** Every ad carries `disclosure.sponsored: true` and a
|
|
visible label. An AgentAd unit must never be presentable as organic output.
|
|
2. **Agent-readable.** Ads may carry a `machine_readable` payload so an autonomous
|
|
agent can reason about the offer instead of scraping rendered text.
|
|
3. **Terminal-native formats.** `text`, `markdown`, `ansi`, `banner`, `json`.
|
|
4. **Publisher control.** Placements declare accepted formats, dimensions,
|
|
frequency caps, and category blocks.
|
|
|
|
## Primitives
|
|
|
|
| Type | Schema | Validator kind | Purpose |
|
|
| --- | --- | --- | --- |
|
|
| `agentad.ad` | `agentad-ad.schema.json` | `agentad-ad` | A single ad unit |
|
|
| `agentad.placement` | `agentad-placement.schema.json` | `agentad-placement` | A slot in a CLI/agent |
|
|
| `agentad.ad_request` | `agentad-ad-request.schema.json` | `agentad-ad-request` | Request to fill a placement |
|
|
| `agentad.ad_response` | `agentad-ad-response.schema.json` | `agentad-ad-response` | Filled ads + tracking tokens |
|
|
| `agentad.impression` | `agentad-impression.schema.json` | `agentad-impression` | Confirmed display |
|
|
| `agentad.click` | `agentad-click.schema.json` | `agentad-click` | Click / conversion |
|
|
| `agentad.campaign` | `agentad-campaign.schema.json` | `agentad-campaign` | Advertiser campaign |
|
|
|
|
Schemas are published from `@logicsrc/schemas` and identified under
|
|
`https://schemas.logicsrc.com/`.
|
|
|
|
## Validate
|
|
|
|
```bash
|
|
npm --workspace @logicsrc/validators run build
|
|
node packages/validators/dist/cli.js agentad-ad packages/schemas/fixtures/agentad-ad.yaml
|
|
node packages/validators/dist/cli.js agentad-placement packages/schemas/fixtures/agentad-placement.yaml
|
|
```
|
|
|
|
## Human vs. agent consumers
|
|
|
|
The `consumer` field on a request changes how an ad is delivered:
|
|
|
|
- `human` → rendered string with an `[Sponsored]` header.
|
|
- `agent` → structured view with an explicit `sponsored: true` flag and the
|
|
`machine_readable` payload, e.g.
|
|
|
|
```json
|
|
{
|
|
"sponsored": true,
|
|
"advertiser": "Railway",
|
|
"title": "Ship your CLI to production in 60 seconds",
|
|
"url": "https://railway.app/?ref=cl1s",
|
|
"data": { "product": "railway", "install": "npm i -g @railway/cli" }
|
|
}
|
|
```
|
|
|
|
## Reference network
|
|
|
|
[cl1s.tech](https://github.com/profullstack/cl1s.tech) is the hosted AgentAd
|
|
network: SDK, CLI, and ad-serving service that consume these schemas.
|
|
|
|
## Marketplace
|
|
|
|
The two-sided exchange built on these contracts — advertiser campaigns, publisher
|
|
placements, auction, metering, and CoinPay settlement — is specified in
|
|
[AgentAd Marketplace (PRD)](./agentad-marketplace.md) (AgentBBS milestone M5).
|