Skip to content

Commit 7cda686

Browse files
ralyodioclaude
ralyodio
and
claude
authored
Add AgentAd ad schemas as a LogicSRC primitive (#10)
* Add AgentAd ad schemas as a LogicSRC primitive AgentAd is a disclosed, agent-readable advertising contract for CLI tools and AI agents. LogicSRC owns the canonical schemas; cl1s.tech is the reference network built on them. - packages/schemas: agentad-{ad,placement,ad-request,ad-response, impression,click,campaign} schemas (id under schemas.logicsrc.com) + ad/placement fixtures, exported from @logicsrc/schemas - packages/validators: register the 7 agentad kinds, wire fixture validation, add tests (disclosure.sponsored must be true) - docs/agentad.md: the AgentAd spec - README: list AgentAd under v1 priorities Validators build clean; all fixtures validate; vitest 4/4 green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * Prepare @logicsrc/schemas for npm publish Add license, repository, homepage, keywords, publishConfig (public), and a package README covering both the logicsrc-* core schemas and the agentad-* family. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
1 parent ad9f3a2 commit 7cda686

17 files changed

Lines changed: 483 additions & 5 deletions

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ It provides read-only resources for docs and schemas, validation/example tools,
5454
## v1.0.0 Priorities
5555

5656
- LogicSRC task, agent, run, event, permission, and plugin schemas.
57+
- AgentAd: disclosed, agent-readable ad schemas for CLI/agent advertising (see `docs/agentad.md`); cl1s.tech is the reference network.
5758
- LogicSRC CLI, SDK, TUI, PWA, MCP, and curl-compatible API conventions.
5859
- CommandBoard.run reference implementation.
5960
- Monorepo-maintained plugin system.

‎docs/agentad.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# AgentAd
2+
3+
AgentAd is a LogicSRC primitive family for advertising to command-line tools and
4+
AI agents. It defines a contract for ads that are **disclosed**, **agent-readable**,
5+
and **terminal-native**.
6+
7+
LogicSRC owns the AgentAd schemas; **cl1s.tech** is the first hosted network built
8+
on AgentAd, in the same relationship that CommandBoard.run has to the core LogicSRC
9+
primitives. External products may consume the AgentAd contracts directly.
10+
11+
## Principles
12+
13+
1. **Disclosure is mandatory.** Every ad carries `disclosure.sponsored: true` and a
14+
visible label. An AgentAd unit must never be presentable as organic output.
15+
2. **Agent-readable.** Ads may carry a `machine_readable` payload so an autonomous
16+
agent can reason about the offer instead of scraping rendered text.
17+
3. **Terminal-native formats.** `text`, `markdown`, `ansi`, `banner`, `json`.
18+
4. **Publisher control.** Placements declare accepted formats, dimensions,
19+
frequency caps, and category blocks.
20+
21+
## Primitives
22+
23+
| Type | Schema | Validator kind | Purpose |
24+
| --- | --- | --- | --- |
25+
| `agentad.ad` | `agentad-ad.schema.json` | `agentad-ad` | A single ad unit |
26+
| `agentad.placement` | `agentad-placement.schema.json` | `agentad-placement` | A slot in a CLI/agent |
27+
| `agentad.ad_request` | `agentad-ad-request.schema.json` | `agentad-ad-request` | Request to fill a placement |
28+
| `agentad.ad_response` | `agentad-ad-response.schema.json` | `agentad-ad-response` | Filled ads + tracking tokens |
29+
| `agentad.impression` | `agentad-impression.schema.json` | `agentad-impression` | Confirmed display |
30+
| `agentad.click` | `agentad-click.schema.json` | `agentad-click` | Click / conversion |
31+
| `agentad.campaign` | `agentad-campaign.schema.json` | `agentad-campaign` | Advertiser campaign |
32+
33+
Schemas are published from `@logicsrc/schemas` and identified under
34+
`https://schemas.logicsrc.com/`.
35+
36+
## Validate
37+
38+
```bash
39+
npm --workspace @logicsrc/validators run build
40+
node packages/validators/dist/cli.js agentad-ad packages/schemas/fixtures/agentad-ad.yaml
41+
node packages/validators/dist/cli.js agentad-placement packages/schemas/fixtures/agentad-placement.yaml
42+
```
43+
44+
## Human vs. agent consumers
45+
46+
The `consumer` field on a request changes how an ad is delivered:
47+
48+
- `human` → rendered string with an `[Sponsored]` header.
49+
- `agent` → structured view with an explicit `sponsored: true` flag and the
50+
`machine_readable` payload, e.g.
51+
52+
```json
53+
{
54+
"sponsored": true,
55+
"advertiser": "Railway",
56+
"title": "Ship your CLI to production in 60 seconds",
57+
"url": "https://railway.app/?ref=cl1s",
58+
"data": { "product": "railway", "install": "npm i -g @railway/cli" }
59+
}
60+
```
61+
62+
## Reference network
63+
64+
[cl1s.tech](https://github.com/profullstack/cl1s.tech) is the hosted AgentAd
65+
network: SDK, CLI, and ad-serving service that consume these schemas.

‎packages/schemas/README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# @logicsrc/schemas
2+
3+
Canonical JSON Schemas (draft 2020-12) for the LogicSRC open coordination
4+
standards, maintained by Profullstack, Inc.
5+
6+
Two schema families ship from this package:
7+
8+
- **LogicSRC core** — `logicsrc-*.schema.json`: tasks, agents, runs, events,
9+
plugins, connected accounts, email messages, social posts.
10+
- **AgentAd** — `agentad-*.schema.json`: a disclosed, agent-readable advertising
11+
contract for CLI tools and AI agents (ads, placements, requests, responses,
12+
impressions, clicks, campaigns). See `docs/agentad.md` in the repo;
13+
[cl1s.tech](https://github.com/profullstack/cl1s.tech) is the reference network.
14+
15+
## Install
16+
17+
```bash
18+
npm install @logicsrc/schemas
19+
```
20+
21+
## Use
22+
23+
```js
24+
import adSchema from "@logicsrc/schemas/agentad-ad" with { type: "json" };
25+
import taskSchema from "@logicsrc/schemas/task" with { type: "json" };
26+
```
27+
28+
Schema `$id`s resolve under `https://schemas.logicsrc.com/`. Validate with any
29+
draft 2020-12 validator (e.g. `ajv/dist/2020.js`), or use `@logicsrc/validators`
30+
from the monorepo.
31+
32+
## License
33+
34+
MIT © Profullstack, Inc.

‎packages/schemas/fixtures/agentad-ad.yaml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
type: agentad.ad
2+
version: "0.1"
3+
id: deploy-faster-railway
4+
campaign_id: railway-q3
5+
advertiser_did: railway.coinpay
6+
format: markdown
7+
title: Ship your CLI to production in 60 seconds
8+
body: Railway deploys any Node, Bun, or Go service straight from your terminal. No YAML wrangling.
9+
url: https://railway.app/?ref=cl1s
10+
cta: Deploy now
11+
disclosure:
12+
sponsored: true
13+
label: Sponsored
14+
advertiser_name: Railway
15+
machine_readable:
16+
product: railway
17+
category: infrastructure
18+
install: "npm i -g @railway/cli"
19+
targeting:
20+
surfaces:
21+
- cli
22+
- agent
23+
keywords:
24+
- deploy
25+
- hosting
26+
- infrastructure
27+
tools:
28+
- claude-code
29+
- gh
30+
pricing:
31+
model: cpc
32+
bid: 0.4
33+
currency: USDC

‎packages/schemas/fixtures/agentad-placement.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
type: agentad.placement
2+
version: "0.1"
3+
id: cli-footer-slot
4+
publisher_did: mytool.coinpay
5+
surface: cli
6+
accepted_formats:
7+
- text
8+
- ansi
9+
- json
10+
dimensions:
11+
max_width: 80
12+
max_lines: 4
13+
context_tags:
14+
- devtools
15+
- deploy
16+
frequency_cap:
17+
max_per_session: 1
18+
max_per_day: 5
19+
block_categories:
20+
- gambling
21+
- crypto-tokens

‎packages/schemas/package.json‎

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,19 @@
11
{
22
"name": "@logicsrc/schemas",
33
"version": "0.1.0",
4-
"description": "LogicSRC JSON schemas for tasks, agents, runs, events, and plugins.",
4+
"description": "LogicSRC JSON schemas for tasks, agents, runs, events, plugins, and the AgentAd ad standard.",
5+
"license": "MIT",
56
"type": "module",
7+
"repository": {
8+
"type": "git",
9+
"url": "git+https://github.com/profullstack/logicsrc.git",
10+
"directory": "packages/schemas"
11+
},
12+
"homepage": "https://github.com/profullstack/logicsrc/tree/master/packages/schemas",
13+
"keywords": ["logicsrc", "agentad", "json-schema", "agents", "cli", "advertising", "standards"],
14+
"publishConfig": {
15+
"access": "public"
16+
},
617
"exports": {
718
"./task": "./schemas/logicsrc-task.schema.json",
819
"./agent": "./schemas/logicsrc-agent.schema.json",
@@ -14,7 +25,14 @@
1425
"./account-grant": "./schemas/logicsrc-account-grant.schema.json",
1526
"./account-audit-event": "./schemas/logicsrc-account-audit-event.schema.json",
1627
"./email-message": "./schemas/logicsrc-email-message.schema.json",
17-
"./social-post": "./schemas/logicsrc-social-post.schema.json"
28+
"./social-post": "./schemas/logicsrc-social-post.schema.json",
29+
"./agentad-ad": "./schemas/agentad-ad.schema.json",
30+
"./agentad-placement": "./schemas/agentad-placement.schema.json",
31+
"./agentad-ad-request": "./schemas/agentad-ad-request.schema.json",
32+
"./agentad-ad-response": "./schemas/agentad-ad-response.schema.json",
33+
"./agentad-impression": "./schemas/agentad-impression.schema.json",
34+
"./agentad-click": "./schemas/agentad-click.schema.json",
35+
"./agentad-campaign": "./schemas/agentad-campaign.schema.json"
1836
},
1937
"files": [
2038
"schemas"

‎packages/schemas/schemas/agentad-ad-request.schema.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.logicsrc.com/agentad-ad-request.schema.json",
4+
"title": "AgentAd Ad Request",
5+
"description": "A request from a CLI/agent for an ad to fill a placement, with optional runtime context for relevance.",
6+
"type": "object",
7+
"required": ["type", "version", "placement_id"],
8+
"additionalProperties": false,
9+
"properties": {
10+
"type": { "const": "agentad.ad_request" },
11+
"version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
12+
"placement_id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
13+
"publisher_did": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.[a-z0-9][a-z0-9._-]*$" },
14+
"consumer": {
15+
"type": "string",
16+
"enum": ["human", "agent"],
17+
"description": "Who will read the ad. Agents SHOULD receive machine_readable payloads and clear disclosure."
18+
},
19+
"context": {
20+
"type": "object",
21+
"additionalProperties": false,
22+
"properties": {
23+
"tool": { "type": "string", "description": "Host tool identifier, e.g. 'claude-code'." },
24+
"keywords": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
25+
"language": { "type": "string" },
26+
"locale": { "type": "string" }
27+
}
28+
},
29+
"format_override": { "type": "string", "enum": ["text", "markdown", "ansi", "banner", "json"] },
30+
"count": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }
31+
}
32+
}

‎packages/schemas/schemas/agentad-ad-response.schema.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.logicsrc.com/agentad-ad-response.schema.json",
4+
"title": "AgentAd Ad Response",
5+
"description": "The network's response to an ad request: zero or more filled ads plus signed tracking tokens for impression/click events.",
6+
"type": "object",
7+
"required": ["type", "version", "request_id", "ads"],
8+
"additionalProperties": false,
9+
"properties": {
10+
"type": { "const": "agentad.ad_response" },
11+
"version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
12+
"request_id": { "type": "string", "minLength": 1 },
13+
"ads": {
14+
"type": "array",
15+
"items": {
16+
"type": "object",
17+
"required": ["ad", "impression_token"],
18+
"additionalProperties": false,
19+
"properties": {
20+
"ad": { "type": "object", "description": "An agentad.ad document; validate separately against agentad-ad.schema.json." },
21+
"impression_token": { "type": "string", "minLength": 1, "description": "Opaque token to confirm the impression and to mint a click token." },
22+
"rendered": { "type": "string", "description": "Server-rendered representation in the requested format." }
23+
}
24+
}
25+
},
26+
"no_fill_reason": {
27+
"type": "string",
28+
"enum": ["no_inventory", "frequency_capped", "blocked_category", "invalid_request"]
29+
}
30+
}
31+
}

‎packages/schemas/schemas/agentad-ad.schema.json‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.logicsrc.com/agentad-ad.schema.json",
4+
"title": "AgentAd Ad",
5+
"description": "A single advertising unit served to CLI tools and AI agents. Ads MUST be disclosed and SHOULD carry a machine-readable payload so agents can reason about them.",
6+
"type": "object",
7+
"required": ["type", "version", "id", "advertiser_did", "format", "title", "url", "disclosure"],
8+
"additionalProperties": false,
9+
"properties": {
10+
"type": { "const": "agentad.ad" },
11+
"version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
12+
"id": { "$ref": "#/$defs/id" },
13+
"campaign_id": { "$ref": "#/$defs/id" },
14+
"advertiser_did": { "$ref": "#/$defs/did" },
15+
"format": {
16+
"type": "string",
17+
"enum": ["text", "markdown", "ansi", "banner", "json"],
18+
"description": "Render format. 'json' is the agent-native structured format; 'ansi'/'banner' target human CLI surfaces."
19+
},
20+
"title": { "type": "string", "minLength": 1, "maxLength": 120 },
21+
"body": { "type": "string", "maxLength": 2000 },
22+
"url": { "type": "string", "format": "uri" },
23+
"cta": { "type": "string", "maxLength": 60, "description": "Call to action label, e.g. 'Install' or 'Read docs'." },
24+
"disclosure": {
25+
"type": "object",
26+
"description": "Transparency contract. Every ad is labeled as sponsored so humans and agents can distinguish it from organic output.",
27+
"required": ["sponsored", "label"],
28+
"additionalProperties": false,
29+
"properties": {
30+
"sponsored": { "const": true },
31+
"label": { "type": "string", "minLength": 1, "maxLength": 40, "default": "Sponsored" },
32+
"advertiser_name": { "type": "string", "maxLength": 120 }
33+
}
34+
},
35+
"machine_readable": {
36+
"type": "object",
37+
"description": "Optional structured payload an agent can parse instead of (or alongside) the rendered text.",
38+
"additionalProperties": true
39+
},
40+
"targeting": { "$ref": "#/$defs/targeting" },
41+
"media": {
42+
"type": "object",
43+
"additionalProperties": false,
44+
"properties": {
45+
"ansi_art": { "type": "string", "description": "Pre-rendered ANSI/ASCII art for banner format." },
46+
"icon": { "type": "string", "format": "uri" }
47+
}
48+
},
49+
"pricing": {
50+
"type": "object",
51+
"additionalProperties": false,
52+
"properties": {
53+
"model": { "type": "string", "enum": ["cpm", "cpc", "cpa", "flat"] },
54+
"bid": { "type": "number", "minimum": 0 },
55+
"currency": { "type": "string", "minLength": 2, "maxLength": 12 }
56+
}
57+
},
58+
"expires_at": { "type": "string", "format": "date-time" }
59+
},
60+
"$defs": {
61+
"id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$", "minLength": 1, "maxLength": 64 },
62+
"did": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.[a-z0-9][a-z0-9._-]*$" },
63+
"targeting": {
64+
"type": "object",
65+
"additionalProperties": false,
66+
"properties": {
67+
"surfaces": {
68+
"type": "array",
69+
"items": { "type": "string", "enum": ["cli", "tui", "agent", "ci"] },
70+
"uniqueItems": true
71+
},
72+
"keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
73+
"tools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true, "description": "Host CLI/agent identifiers to target, e.g. 'claude-code', 'gh'." },
74+
"languages": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
75+
"exclude_keywords": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
76+
}
77+
}
78+
}
79+
}

‎packages/schemas/schemas/agentad-campaign.schema.json‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://schemas.logicsrc.com/agentad-campaign.schema.json",
4+
"title": "AgentAd Campaign",
5+
"description": "An advertiser campaign grouping one or more ads under a shared budget, schedule, and targeting policy.",
6+
"type": "object",
7+
"required": ["type", "version", "id", "advertiser_did", "name", "budget"],
8+
"additionalProperties": false,
9+
"properties": {
10+
"type": { "const": "agentad.campaign" },
11+
"version": { "type": "string", "pattern": "^\\d+\\.\\d+(\\.\\d+)?$" },
12+
"id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$", "minLength": 1, "maxLength": 64 },
13+
"advertiser_did": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*\\.[a-z0-9][a-z0-9._-]*$" },
14+
"name": { "type": "string", "minLength": 1, "maxLength": 120 },
15+
"status": { "type": "string", "enum": ["draft", "active", "paused", "completed"], "default": "draft" },
16+
"budget": {
17+
"type": "object",
18+
"required": ["total", "currency"],
19+
"additionalProperties": false,
20+
"properties": {
21+
"total": { "type": "number", "minimum": 0 },
22+
"daily_cap": { "type": "number", "minimum": 0 },
23+
"currency": { "type": "string", "minLength": 2, "maxLength": 12 }
24+
}
25+
},
26+
"schedule": {
27+
"type": "object",
28+
"additionalProperties": false,
29+
"properties": {
30+
"start_at": { "type": "string", "format": "date-time" },
31+
"end_at": { "type": "string", "format": "date-time" }
32+
}
33+
},
34+
"ad_ids": {
35+
"type": "array",
36+
"items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]*$" },
37+
"uniqueItems": true
38+
}
39+
}
40+
}

0 commit comments

Comments
 (0)