bbs.profullstack/logicsrc
1
0
Fork 0
mirror of https://github.com/profullstack/logicsrc.git synced 2026-08-13 14:37:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
logicsrc/docs/agentad.md
Anthony Ettinger 7d62e3b661
Some checks failed
CI / build (push) Has been cancelled
Details
test / test (push) Has been cancelled
Details
feat(agentad): AgentAd Marketplace PRD + reference exchange (M5) 
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>
2026-07-01 10:29:36 +00:00

3 KiB
Raw Blame History

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

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.
{
  "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 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) (AgentBBS milestone M5).