ajp-protocol 0.1.0

package/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to npm
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ilucky21c
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# ajp-protocol
+
+The Agent Job Protocol — standard interaction layer for the agent internet.
+Part of the [Provenance Protocol](https://provenance.dev) family.
+
+```bash
+npm install ajp-protocol
+```
+
+---
+
+## What it does
+
+AJP defines how any party — a human, an agent, or an orchestrator — hands a
+job to another agent, tracks its progress, and receives the result.
+
+Three endpoints. Three message types. Runs over standard HTTP.
+Trust verification via `provenance-protocol` built in.
+
+---
+
+## Quick start — receiving agent
+
+Add three routes to your agent. AJP handles verification, trust checks,
+and job lifecycle automatically.
+
+```js
+import { AJPServer } from 'ajp-protocol';
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+const server = new AJPServer({
+  provenanceId: 'provenance:github:alice/research-assistant',
+  secret: process.env.AJP_SECRET,
+
+  // Trust requirements for incoming agent senders
+  trustRequirements: {
+    requireDeclared: true,   // sender must have PROVENANCE.yml
+    requireClean: true,      // no open incidents
+    requireMinAge: 7,        // not a brand-new agent
+  },
+
+  // Your agent logic — receives the job, returns the result
+  onJob: async (job) => {
+    const papers = await searchPapers(job.task.instruction);
+    return { papers };
+  },
+});
+
+app.post('/jobs',         server.receive());
+app.get('/jobs/:id',      server.status());
+app.post('/jobs/:id/ack', server.ack());
+
+app.listen(3000);
+```
+
+---
+
+## Quick start — sending agent or platform
+
+```js
+import { AJPClient } from 'ajp-protocol';
+
+const client = new AJPClient({
+  from: {
+    type: 'agent',   // 'human' | 'agent' | 'orchestrator'
+    provenance_id: 'provenance:github:alice/orchestrator',
+  },
+  secret: process.env.AJP_SECRET,
+});
+
+const result = await client.send(
+  'provenance:github:bob/research-assistant',  // who to hire
+  {
+    type: 'research',
+    instruction: 'Find the top 3 papers on transformer attention in 2024.',
+    output_format: 'json',
+  },
+  {
+    max_usd: 0.50,       // budget cap
+    max_seconds: 120,    // timeout
+  }
+);
+
+console.log(result.output);
+// { papers: [...] }
+```
+
+---
+
+## Three use cases, one protocol
+
+### Human hiring an agent
+```js
+const client = new AJPClient({
+  from: { type: 'human', id: 'user_alice_123' },
+  secret: process.env.AJP_SECRET,
+});
+const result = await client.send(agentId, task, budget);
+```
+
+### Agent hiring an agent
+```js
+const client = new AJPClient({
+  from: { type: 'agent', provenance_id: 'provenance:github:alice/pipeline' },
+  secret: process.env.AJP_SECRET,
+});
+// Receiving agent automatically verifies sender via Provenance
+const result = await client.send(agentId, task, budget);
+```
+
+### Orchestrator delegating to sub-agents (with audit chain)
+```js
+const [resultA, resultB] = await Promise.all([
+  client.send(agentA, taskA, budget, { parentJobId: parentJobId }),
+  client.send(agentB, taskB, budget, { parentJobId: parentJobId }),
+]);
+// All sub-jobs linked to parent — full execution tree is auditable
+```
+
+---
+
+## How trust works
+
+When an agent or orchestrator sends a job, the receiving `AJPServer`
+automatically calls `provenance-protocol` to verify the sender:
+
+```
+AJPServer.receive()
+  → verify signature
+  → provenance.gate(offer.from.provenance_id, trustRequirements)
+      → is sender in Provenance index?
+      → has PROVENANCE.yml?
+      → any open incidents?
+      → old enough?
+  → run onJob() only if all checks pass
+  → return 403 with reason if any check fails
+```
+
+Human senders (`from.type: 'human'`) skip Provenance verification.
+Platform-level auth is assumed for humans.
+
+---
+
+## Declare AJP in your PROVENANCE.yml
+
+```yaml
+provenance: "0.1"
+name: "Research Assistant"
+
+capabilities:
+  - read:web
+  - ajp:receiver      # accepts incoming AJP jobs
+  - ajp:sender        # sends AJP jobs to other agents
+
+ajp:
+  endpoint: "https://alice.dev/api/agent"
+  version: "0.1"
+```
+
+The Provenance crawler reads `ajp.endpoint` and indexes it.
+Senders can discover your endpoint without out-of-band configuration.
+
+---
+
+## Next.js API route example
+
+```js
+// app/api/agent/jobs/route.js
+import { AJPServer } from 'ajp-protocol';
+import { NextResponse } from 'next/server';
+
+const server = new AJPServer({
+  provenanceId: process.env.PROVENANCE_ID,
+  secret: process.env.AJP_SECRET,
+  onJob: async (job) => {
+    // your agent logic
+    return { result: '...' };
+  },
+});
+
+export async function POST(req) {
+  return server.receive()(req, NextResponse);
+}
+```
+
+---
+
+## The protocol family
+
+| Package | Purpose |
+|---|---|
+| `provenance-protocol` | Query the agent identity index |
+| `ajp-protocol` | Send and receive agent jobs (this package) |
+| `PROVENANCE.yml` | Declare your agent's identity and capabilities |
+
+---
+
+## MIT License — provenance.dev/ajp

package/examples/agent-to-agent/example.js

@@ -0,0 +1,67 @@
+// Example 2: Agent hiring an agent
+// A data pipeline agent needs PDF extraction.
+// It hires a specialist PDF agent to handle that step.
+//
+// Key difference from human→agent: the receiving agent
+// MUST verify the sender's Provenance ID before accepting.
+
+import { AJPClient } from 'ajp-protocol';
+import { provenance } from 'provenance-protocol';
+
+// ── Sending side (data pipeline agent) ───────────────────────────────────
+
+const client = new AJPClient({
+  from: {
+    type: 'agent',
+    provenance_id: 'provenance:github:alice/data-pipeline',
+  },
+  secret: process.env.AJP_SECRET,
+});
+
+// Send job to a specialist PDF extractor
+const result = await client.send(
+  'provenance:pypi:bob-pdf-extractor',
+  {
+    type: 'extract',
+    instruction: 'Extract all tables from this PDF and return them as structured JSON.',
+    input: { url: 'https://example.com/annual-report.pdf' },
+    output_format: 'json',
+  },
+  {
+    max_usd: 0.25,
+    max_seconds: 60,
+  }
+);
+
+console.log(result.output.tables);
+
+// ── Receiving side (PDF extractor agent) ─────────────────────────────────
+// This runs inside the PDF extractor's server
+
+import { AJPServer } from 'ajp-protocol';
+
+const server = new AJPServer({
+  provenanceId: 'provenance:pypi:bob-pdf-extractor',
+  secret: process.env.AJP_SECRET,
+
+  // Trust requirements for incoming agent jobs
+  trustRequirements: {
+    requireDeclared: true,    // sender must have PROVENANCE.yml
+    requireClean: true,       // no open incidents
+    requireMinAge: 7,         // not a brand-new agent
+  },
+
+  onJob: async (job) => {
+    // job.from.provenance_id already verified by AJPServer
+    // before this function is called
+
+    const tables = await extractTablesFromPdf(job.task.input.url);
+    return { tables };
+  },
+});
+
+// Wire up to your HTTP framework
+// Express:
+app.post('/jobs',         server.receive());
+app.get('/jobs/:id',      server.status());
+app.post('/jobs/:id/ack', server.ack());

package/examples/human-to-agent/example.js

@@ -0,0 +1,83 @@
+// Example 1: Human hiring an agent
+// A user on ClawMarket hires a research agent.
+// The platform wraps their request in a JobOffer and sends it.
+
+// ── What the platform sends ───────────────────────────────────────────────
+
+const jobOffer = {
+  ajp: "0.1",
+  job_id: "job_01J8X2K9M3N4P5Q6R7S8T9U0V1",
+  parent_job_id: null,
+
+  from: {
+    type: "human",
+    id: "user_alice_123",       // ClawMarket user ID
+    provenance_id: null,        // humans don't have Provenance IDs
+  },
+
+  to: {
+    provenance_id: "provenance:github:bob/research-assistant",
+  },
+
+  task: {
+    type: "research",
+    instruction: "Find the three most cited papers on transformer attention mechanisms published in 2024. Return titles, authors, citation counts, and a 2-sentence summary of each.",
+    input: {},
+    output_format: "json",
+  },
+
+  context: {
+    credentials: {},
+    memory: [],
+    constraints: [],
+  },
+
+  budget: {
+    max_usd: 0.50,
+    max_seconds: 120,
+    max_llm_tokens: 10000,
+  },
+
+  callback: {
+    url: "https://clawmarket.com/api/jobs/job_01J8X2K9M3N4P5Q6R7S8T9U0V1/result",
+    headers: { "Authorization": "Bearer clawmarket_token_xyz" },
+  },
+
+  issued_at: "2026-03-05T10:00:00Z",
+  expires_at: "2026-03-05T10:02:00Z",
+  signature: "sha256:a1b2c3d4e5f6...",
+};
+
+// ── What the agent returns ────────────────────────────────────────────────
+
+const jobResult = {
+  ajp: "0.1",
+  job_id: "job_01J8X2K9M3N4P5Q6R7S8T9U0V1",
+  status: "completed",
+
+  output: {
+    papers: [
+      {
+        title: "FlashAttention-3: Fast and Accurate Attention with Asynchrony and Low-precision",
+        authors: ["Jay Shah", "Ganesh Bikshandi", "Ying Zhang", "Vijay Thakkar", "Pradeep Ramani", "Tri Dao"],
+        citations: 412,
+        summary: "Introduces hardware-aware optimizations for H100 GPUs achieving 1.5-2x speedup over FlashAttention-2. Combines asynchronous execution with low-precision arithmetic while maintaining numerical accuracy.",
+      },
+    ],
+  },
+
+  usage: {
+    llm_tokens: 4821,
+    duration_seconds: 18,
+    cost_usd: 0.12,
+  },
+
+  agent: {
+    provenance_id: "provenance:github:bob/research-assistant",
+    version: "1.2.0",
+    model: { provider: "anthropic", model_id: "claude-sonnet-4-5" },
+  },
+
+  completed_at: "2026-03-05T10:00:19Z",
+  signature: "sha256:e5f6g7h8...",
+};

package/examples/orchestrator/example.js

@@ -0,0 +1,55 @@
+// Example 3: Orchestrator delegating to sub-agents
+// A research orchestrator breaks a complex task into parallel sub-tasks.
+// Each sub-job references parent_job_id — creating a full audit chain.
+
+import { AJPClient } from 'ajp-protocol';
+
+const client = new AJPClient({
+  from: {
+    type: 'orchestrator',
+    provenance_id: 'provenance:github:alice/research-orchestrator',
+  },
+  secret: process.env.AJP_SECRET,
+});
+
+const PARENT_JOB_ID = 'job_parent_01J8X2K9M3N4P5Q6';
+
+// ── Dispatch sub-tasks in parallel ───────────────────────────────────────
+
+const [webResults, pdfResults] = await Promise.all([
+
+  // Sub-task 1: web research agent
+  client.send(
+    'provenance:github:alice/research-assistant',
+    {
+      type: 'research',
+      instruction: 'Find recent papers on transformer attention mechanisms (2024).',
+      output_format: 'json',
+    },
+    { max_usd: 0.25, max_seconds: 60 },
+    { parentJobId: PARENT_JOB_ID }   // links to parent for audit trail
+  ),
+
+  // Sub-task 2: PDF extraction agent
+  client.send(
+    'provenance:pypi:bob-pdf-extractor',
+    {
+      type: 'extract',
+      instruction: 'Extract tables from the provided PDF.',
+      input: { url: 'https://example.com/survey.pdf' },
+      output_format: 'json',
+    },
+    { max_usd: 0.25, max_seconds: 60 },
+    { parentJobId: PARENT_JOB_ID }
+  ),
+
+]);
+
+// ── Audit chain: all three jobs are linked ────────────────────────────────
+//
+// job_parent_01J8X2K9M3N4P5Q6       ← orchestrator job (from human)
+//   ├── job_sub_A_...               ← web research   (parent_job_id set)
+//   └── job_sub_B_...               ← PDF extraction (parent_job_id set)
+//
+// Anyone querying the Provenance log can see the full chain.
+// What was delegated, to whom, when, and what it cost.

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "ajp-protocol",
+  "version": "0.1.0",
+  "description": "Agent Job Protocol — standard interaction layer for the agent internet",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": ["ai-agent", "agent-protocol", "ajp", "provenance", "llm", "agent-to-agent"],
+  "license": "MIT",
+  "dependencies": {
+    "provenance-protocol": "^0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ilucky21c/ajp-protocol"
+  },
+  "homepage": "https://provenance.dev/ajp"
+}

package/schema/job-offer.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://provenance.dev/ajp/schema/0.1/job-offer.json",
+  "title": "AJP JobOffer",
+  "description": "Agent Job Protocol v0.1 — JobOffer message",
+  "type": "object",
+  "required": ["ajp", "job_id", "from", "to", "task", "budget", "issued_at", "expires_at", "signature"],
+
+  "properties": {
+
+    "ajp": { "type": "string", "enum": ["0.1"] },
+
+    "job_id": {
+      "type": "string",
+      "description": "Unique job identifier. Use ULID or UUID.",
+      "minLength": 8
+    },
+
+    "parent_job_id": {
+      "type": ["string", "null"],
+      "description": "Set when this job was created by an orchestrator as a sub-task."
+    },
+
+    "from": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "enum": ["human", "agent", "orchestrator"] },
+        "id": { "type": ["string", "null"], "description": "Platform user ID for human senders" },
+        "provenance_id": { "type": ["string", "null"], "description": "Required when type is agent or orchestrator" }
+      },
+      "if": { "properties": { "type": { "enum": ["agent", "orchestrator"] } } },
+      "then": { "required": ["provenance_id"] }
+    },
+
+    "to": {
+      "type": "object",
+      "required": ["provenance_id"],
+      "properties": {
+        "provenance_id": { "type": "string" }
+      }
+    },
+
+    "task": {
+      "type": "object",
+      "required": ["type", "instruction"],
+      "properties": {
+        "type": { "type": "string", "description": "Domain-specific task type e.g. research, extract, summarize" },
+        "instruction": { "type": "string", "description": "Natural language task description", "minLength": 1 },
+        "input": { "type": "object", "description": "Structured input data" },
+        "output_format": { "type": "string", "enum": ["json", "text", "markdown", "html", "any"] }
+      }
+    },
+
+    "context": {
+      "type": "object",
+      "properties": {
+        "credentials": { "type": "object", "description": "Any credentials the agent needs to complete the task" },
+        "memory": { "type": "array", "description": "Prior conversation or context to include" },
+        "constraints": { "type": "array", "items": { "type": "string" }, "description": "Additional constraints for this specific job" }
+      }
+    },
+
+    "budget": {
+      "type": "object",
+      "required": ["max_usd"],
+      "properties": {
+        "max_usd": { "type": "number", "minimum": 0, "description": "Maximum cost in USD" },
+        "max_seconds": { "type": "number", "minimum": 1, "description": "Maximum execution time" },
+        "max_llm_tokens": { "type": "number", "minimum": 1, "description": "Maximum LLM tokens across all calls" }
+      }
+    },
+
+    "callback": {
+      "type": ["object", "null"],
+      "description": "Where to POST the JobResult when complete. Null = polling only.",
+      "properties": {
+        "url": { "type": "string", "format": "uri" },
+        "headers": { "type": "object" }
+      },
+      "required": ["url"]
+    },
+
+    "issued_at": { "type": "string", "format": "date-time" },
+    "expires_at": { "type": "string", "format": "date-time" },
+
+    "signature": {
+      "type": "string",
+      "description": "HMAC-SHA256 of the message body excluding this field. Format: sha256:hex",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    }
+  },
+
+  "additionalProperties": false
+}