ajp-protocol 0.1.0 → 0.2.2

package/.github/workflows/publish.yml

@@ -8,13 +8,72 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
+      contents: read
+      # Mints the short-lived OIDC token npm trades for publish rights.
+      # Without it npm looks for a token instead and fails with a 404 on
+      # write, which reads like "package not found" rather than "not
+      # authorised". Do not remove.
       id-token: write
     steps:
       - uses: actions/checkout@v4
+
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          # Trusted publishing needs Node >= 22.14 and npm >= 11.5.1.
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
-      - run: npm publish --access public --provenance
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # Upgrade npm explicitly rather than trusting whatever version the
+      # runner's Node bundles, and print both. A too-old npm ignores OIDC
+      # and fails with that same misleading 404, so keep the versions in
+      # the log where they can be read.
+      - run: npm install -g npm@latest
+      - run: node -v && npm -v
+
+      # Install before testing. Not every package here is dependency-free —
+      # ajp-protocol depends on provenance-protocol and its tests import it, and
+      # omitting this step made the test fail to resolve the module rather than
+      # fail a real assertion. `npm install` rather than `npm ci` because these
+      # packages carry no lockfile.
+      - run: npm install --no-audit --no-fund
+
+      # A release that fails its own tests must not reach the registry.
+      - run: npm test --if-present
+
+      # No NODE_AUTH_TOKEN: npm exchanges this workflow's OIDC identity for
+      # publish rights, configured as a trusted publisher on npmjs.com against
+      # this repository and this workflow filename. Provenance attestations are
+      # generated automatically, so --provenance is not passed.
+      # Skip rather than fail when this version is already on npm. A tag may
+      # exist to release a sibling package in this repo, and a red run that
+      # actually means "nothing to publish here" trains people to ignore red
+      # runs. The log says which happened.
+      - name: Publish the protocol package if its version is new
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          VERSION=$(node -p "require('./package.json').version")
+          if npm view "$NAME@$VERSION" version >/dev/null 2>&1; then
+            echo "::notice::$NAME@$VERSION is already published — skipping. Bump package.json to release it."
+          else
+            echo "Publishing $NAME@$VERSION"
+            npm publish --access public
+          fi
+
+      # The CLI is a second package in this repo with its own version. Publish it
+      # from the same tag, but only when its version is actually new — otherwise
+      # every release after an unchanged CLI would fail on "cannot publish over
+      # the previously published version".
+      #
+      # A skip and a publish must not look alike in the log: one means "nothing
+      # to do", the other means "shipped".
+      - name: Publish the CLI if its version is new
+        working-directory: cli
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          VERSION=$(node -p "require('./package.json').version")
+          if npm view "$NAME@$VERSION" version >/dev/null 2>&1; then
+            echo "::notice::$NAME@$VERSION is already published — skipping. Bump cli/package.json to release it."
+          else
+            echo "Publishing $NAME@$VERSION"
+            npm publish --access public
+          fi

package/README.md

@@ -1,7 +1,7 @@
 # ajp-protocol
 
 The Agent Job Protocol — standard interaction layer for the agent internet.
-Part of the [Provenance Protocol](https://provenance.dev) family.
+Part of the [Provenance Protocol](https://getprovenance.dev) family.
 
 ```bash
 npm install ajp-protocol
@@ -25,7 +25,8 @@ Add three routes to your agent. AJP handles verification, trust checks,
 and job lifecycle automatically.
 
 ```js
-import { AJPServer } from 'ajp-protocol';
+import { AJPServer, declarationKeyResolver, indexStandingCheck } from 'ajp-protocol';
+import { Provenance } from 'provenance-protocol';
 import express from 'express';
 
 const app = express();
@@ -33,14 +34,29 @@ app.use(express.json());
 
 const server = new AJPServer({
   provenanceId: 'provenance:github:alice/research-assistant',
+  privateKey: process.env.PROVENANCE_PRIVATE_KEY,  // signs results with Ed25519
+
+  // Constraints from your PROVENANCE.yml — asserted in every signed JobResult.
+  // Creates a cryptographic receipt: "this agent declared it honored these constraints for this job."
+  constraints: ['no:pii', 'no:persist:data'],
+
+  // Optional: accept human callers (platforms) with a shared HMAC secret
   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
-  },
+  // Identity: resolved from the sender's own signed declaration, offline.
+  // This is the default — no index is consulted to check a signature.
+  resolveSenderKey: declarationKeyResolver(),
+
+  // Standing (revocation, incidents, freshness) cannot be checked offline, so
+  // it is opt-in and you choose whom to ask. Omit it entirely to accept any
+  // sender whose identity verifies.
+  checkStanding: indexStandingCheck(new Provenance(), {
+    requireDeclared: true,
+    requireCapabilities: ['delegate:agents'],
+    requireClean: true,
+    requireMinAge: 7,
+  }),
+  onStandingUnavailable: 'deny',   // an unreachable attester is not an accusation
 
   // Your agent logic — receives the job, returns the result
   onJob: async (job) => {
@@ -68,7 +84,8 @@ const client = new AJPClient({
     type: 'agent',   // 'human' | 'agent' | 'orchestrator'
     provenance_id: 'provenance:github:alice/orchestrator',
   },
-  secret: process.env.AJP_SECRET,
+  // Agent/orchestrator callers sign with Ed25519 — no shared secret needed
+  privateKey: process.env.PROVENANCE_PRIVATE_KEY,
 });
 
 const result = await client.send(
@@ -94,6 +111,7 @@ console.log(result.output);
 
 ### Human hiring an agent
 ```js
+// Human callers use a shared HMAC secret (agreed out of band with the agent)
 const client = new AJPClient({
   from: { type: 'human', id: 'user_alice_123' },
   secret: process.env.AJP_SECRET,
@@ -103,11 +121,12 @@ const result = await client.send(agentId, task, budget);
 
 ### Agent hiring an agent
 ```js
+// Agent callers sign with Ed25519 — no shared secret, no prior setup
+// The receiving agent verifies by fetching your public key from Provenance index
 const client = new AJPClient({
   from: { type: 'agent', provenance_id: 'provenance:github:alice/pipeline' },
-  secret: process.env.AJP_SECRET,
+  privateKey: process.env.PROVENANCE_PRIVATE_KEY,
 });
-// Receiving agent automatically verifies sender via Provenance
 const result = await client.send(agentId, task, budget);
 ```
 
@@ -124,21 +143,28 @@ const [resultA, resultB] = await Promise.all([
 
 ## How trust works
 
-When an agent or orchestrator sends a job, the receiving `AJPServer`
-automatically calls `provenance-protocol` to verify the sender:
+Two separate questions, and only one of them needs a network service.
 
 ```
 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
+  → validate the offer's shape
+  → IDENTITY  (offline, always)
+      fetch the sender's declaration from from.declaration_url
+      → does it verify against the key inside it?
+      → was it served from the location its provenance id names?
+      → is that id the one the offer claims?
+      → has this sender's key changed since last time?
+      then check the offer's signature with that key
+  → STANDING  (online, optional, you choose the attester)
+      → revoked? open incidents? evidence stale? old enough?
+      → unreachable attester → your policy, not a failed trust check
+  → run onJob() only if both pass
+  → 403 with a reason and a code if either does not
 ```
 
+Identity never depends on anyone's uptime. Only standing does, and you decide
+whose — one index, several, your own attester, or none at all.
+
 Human senders (`from.type: 'human'`) skip Provenance verification.
 Platform-level auth is assumed for humans.
 
@@ -198,4 +224,28 @@ export async function POST(req) {
 
 ---
 
-## MIT License — provenance.dev/ajp
+## CLI
+
+```bash
+# Send a job to any indexed agent from the terminal
+npx @ilucky21c/ajp-cli hire provenance:github:alice/summarizer \
+  --instruction "Summarize this paper: https://arxiv.org/abs/..." \
+  --budget 0.50 --timeout 60
+
+# Check job status
+npx @ilucky21c/ajp-cli jobs job_m0abc123 --endpoint https://alice-agent.example.com/api/agent
+```
+
+Requires Provenance identity — set up first with `npx provenance-protocol keygen` and `npx provenance-protocol register`.
+
+Full CLI reference: [getprovenance.dev/docs/ajp#cli](https://getprovenance.dev/docs/ajp#cli)
+
+---
+
+## Full documentation
+
+[getprovenance.dev/docs/ajp](https://getprovenance.dev/docs/ajp)
+
+---
+
+## MIT License — getprovenance.dev

package/cli/index.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * ajp-cli — Agent Job Protocol CLI
+ *
+ * Requires Provenance identity (PROVENANCE_ID + PROVENANCE_PRIVATE_KEY).
+ * For identity setup: npx provenance-protocol keygen / npx provenance-protocol register
+ *
+ * Usage:
+ *   ajp hire <provenance_id> --instruction <text> [--budget <usd>] [--timeout <s>]
+ *   ajp jobs <job_id> --endpoint <url>
+ */
+
+import { createPrivateKey, sign as nodeSign, randomBytes } from 'crypto';
+
+const API     = process.env.PROVENANCE_API_URL || 'https://getprovenance.dev';
+const VERSION = '0.1.0';
+
+// ── Colours ───────────────────────────────────────────────────────────────────
+
+const c = {
+  reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m',
+  green: '\x1b[32m', amber: '\x1b[33m', red: '\x1b[31m', blue: '\x1b[34m', white: '\x1b[97m',
+};
+const ok  = s => `${c.green}✓${c.reset} ${s}`;
+const err = s => `${c.red}✗${c.reset} ${s}`;
+const dim = s => `${c.dim}${s}${c.reset}`;
+const hi  = s => `${c.white}${c.bold}${s}${c.reset}`;
+const amb = s => `${c.amber}${s}${c.reset}`;
+
+// ── Arg parsing ───────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) { args[key] = next; i += 2; }
+      else { args[key] = true; i++; }
+    } else { args._.push(a); i++; }
+  }
+  return args;
+}
+
+// ── Signing ───────────────────────────────────────────────────────────────────
+
+function generateJobId() {
+  return `job_${Date.now().toString(36)}${randomBytes(6).toString('hex')}`;
+}
+
+function signOffer(offer, privateKeyBase64) {
+  const { signature: _, ...rest } = offer;
+  const canonical = JSON.stringify(rest, Object.keys(rest).sort());
+  const key = createPrivateKey({ key: Buffer.from(privateKeyBase64, 'base64'), format: 'der', type: 'pkcs8' });
+  return `ed25519:${nodeSign(null, Buffer.from(canonical, 'utf8'), key).toString('base64')}`;
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+async function cmdHire(args) {
+  const targetId     = args._[1];
+  const instruction  = args.instruction || args.i;
+  const budget       = parseFloat(args.budget  || args.b || '1.0');
+  const timeout      = parseInt(args.timeout   || args.t || '120');
+  const privateKey   = args['private-key'] || process.env.PROVENANCE_PRIVATE_KEY;
+  const provenanceId = args['from-id']     || process.env.PROVENANCE_ID;
+
+  if (!targetId)     { console.error(err('Usage: ajp hire <provenance_id> --instruction <text>')); process.exit(1); }
+  if (!instruction)  { console.error(err('--instruction required')); process.exit(1); }
+  if (!privateKey)   { console.error(err('PROVENANCE_PRIVATE_KEY not set. Run: npx provenance-protocol keygen')); process.exit(1); }
+  if (!provenanceId) { console.error(err('PROVENANCE_ID not set. Run: npx provenance-protocol register')); process.exit(1); }
+
+  console.log(`\n${amb('Hiring')} ${hi(targetId)}...\n`);
+
+  // Resolve endpoint
+  process.stdout.write(dim('  Resolving endpoint...'));
+  const agentRes  = await fetch(`${API}/api/agent/${targetId.replace('provenance:', '').replace(':', '/')}`);
+  const agentData = await agentRes.json();
+  if (!agentData?.ajp?.endpoint) {
+    console.log('\n' + err('Agent has no AJP endpoint. Ask them to add ajp.endpoint to PROVENANCE.yml.'));
+    process.exit(1);
+  }
+  const endpoint = agentData.ajp.endpoint.replace(/\/$/, '');
+  console.log(` ${c.green}${endpoint}${c.reset}`);
+
+  // Build and sign offer
+  const now       = new Date();
+  const expiresAt = new Date(now.getTime() + timeout * 1000);
+  const jobId     = generateJobId();
+
+  const offer = {
+    ajp: '0.1', job_id: jobId, parent_job_id: null,
+    from: { type: 'orchestrator', id: null, provenance_id: provenanceId },
+    to:   { provenance_id: targetId },
+    task: { type: 'task', instruction, input: {}, output_format: 'json' },
+    context: { credentials: {}, memory: [], constraints: [] },
+    budget:  { max_usd: budget, max_seconds: timeout, max_llm_tokens: 10000 },
+    callback: null,
+    issued_at:  now.toISOString(),
+    expires_at: expiresAt.toISOString(),
+    signature: '',
+  };
+  offer.signature = signOffer(offer, privateKey);
+
+  // Submit
+  process.stdout.write(dim('  Submitting job...'));
+  const submitRes  = await fetch(`${endpoint}/jobs`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(offer),
+  });
+  const submitData = await submitRes.json().catch(() => ({}));
+
+  if (!submitRes.ok) {
+    console.log('\n' + err(submitData.error || submitData.reason || `HTTP ${submitRes.status}`));
+    process.exit(1);
+  }
+  console.log(` ${c.green}${jobId}${c.reset}`);
+
+  // Poll
+  const deadline = Date.now() + timeout * 1000;
+  const frames   = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
+  let   fi       = 0;
+
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, 2000));
+    const pollRes  = await fetch(`${endpoint}/jobs/${jobId}`);
+    const pollData = await pollRes.json().catch(() => ({}));
+
+    process.stdout.write(`\r  ${c.blue}${frames[fi++ % frames.length]}${c.reset} ${dim(pollData.status || 'polling...')}   `);
+
+    if (pollData.status === 'completed') {
+      await fetch(`${endpoint}/jobs/${jobId}/ack`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ received: true }),
+      }).catch(() => {});
+
+      const dur = pollData.usage?.duration_seconds?.toFixed(1);
+      process.stdout.write(`\r${ok(`Completed${dur ? ` in ${dur}s` : ''}`)}                    \n\n`);
+
+      const out = pollData.output;
+      console.log(typeof out === 'string' ? out : JSON.stringify(out, null, 2));
+
+      if (pollData.usage) {
+        const u = pollData.usage;
+        const parts = [];
+        if (u.duration_seconds != null) parts.push(`${u.duration_seconds.toFixed(1)}s`);
+        if (u.cost_usd > 0)             parts.push(`$${u.cost_usd.toFixed(4)}`);
+        if (u.llm_tokens > 0)           parts.push(`${u.llm_tokens} tokens`);
+        if (parts.length) console.log('\n' + dim(parts.join(' · ')));
+      }
+      console.log();
+      return;
+    }
+
+    if (['failed','expired','rejected'].includes(pollData.status)) {
+      process.stdout.write(`\r${err(pollData.status + (pollData.message ? ': ' + pollData.message : ''))}                    \n\n`);
+      process.exit(1);
+    }
+  }
+
+  console.log('\n' + err(`Timed out after ${timeout}s`));
+  process.exit(1);
+}
+
+async function cmdJobs(args) {
+  const jobId    = args._[1];
+  const endpoint = args.endpoint;
+  if (!jobId)    { console.error(err('Usage: ajp jobs <job_id> --endpoint <url>')); process.exit(1); }
+  if (!endpoint) { console.error(err('--endpoint required')); process.exit(1); }
+
+  const res  = await fetch(`${endpoint.replace(/\/$/, '')}/jobs/${jobId}`);
+  const data = await res.json();
+
+  const statusColor = { completed: c.green, failed: c.red, expired: c.red, running: c.blue, accepted: c.amber }[data.status] || c.dim;
+  console.log(`\n${dim('job_id:')} ${data.job_id}`);
+  console.log(`${dim('status:')} ${statusColor}${data.status}${c.reset}`);
+  if (data.output)  console.log(`\n${JSON.stringify(data.output, null, 2)}`);
+  if (data.message) console.log(`${c.red}${data.message}${c.reset}`);
+  console.log();
+}
+
+function cmdHelp() {
+  console.log(`
+${hi('ajp')} ${dim(`v${VERSION}`)} — Agent Job Protocol CLI
+
+${amb('Commands:')}
+  ${hi('hire')}  <provenance_id>            Send a job to an agent via AJP
+         --instruction <text>       What you want the agent to do
+         [--budget <usd>]           Max cost ceiling (default: 1.00)
+         [--timeout <seconds>]      Max wait time (default: 120)
+         [--from-id <id>]           Your Provenance ID (default: $PROVENANCE_ID)
+         [--private-key <key>]      Your private key (default: $PROVENANCE_PRIVATE_KEY)
+
+  ${hi('jobs')}  <job_id>                   Check status of a job
+         --endpoint <url>           The agent's AJP endpoint URL
+
+${amb('Environment variables:')}
+  PROVENANCE_ID           Your Provenance ID  (set up with: npx provenance-protocol register)
+  PROVENANCE_PRIVATE_KEY  Your Ed25519 private key  (set up with: npx provenance-protocol keygen)
+  PROVENANCE_API_URL      Override Provenance API base URL
+
+${amb('Examples:')}
+  ajp hire provenance:github:alice/summarizer \\
+    --instruction "Summarize https://arxiv.org/abs/2501.00001" \\
+    --budget 0.50 --timeout 60
+
+  ajp jobs job_m0abc123 --endpoint https://alice-agent.example.com/api/agent
+
+${amb('Identity setup (first time):')}
+  npx provenance-protocol keygen
+  npx provenance-protocol register --id provenance:github:your-org/your-agent --url <url>
+  ${dim('Then set PROVENANCE_ID and PROVENANCE_PRIVATE_KEY in your environment.')}
+`);
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+const args = parseArgs(argv);
+const cmd  = args._[0];
+
+try {
+  if (!cmd || cmd === 'help' || args.help) cmdHelp();
+  else if (cmd === 'hire') await cmdHire(args);
+  else if (cmd === 'jobs') await cmdJobs(args);
+  else { console.error(err(`Unknown command: ${cmd}\nRun \`ajp help\` for usage.`)); process.exit(1); }
+} catch (e) {
+  console.error(err(e.message));
+  process.exit(1);
+}

package/cli/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@ilucky21c/ajp-cli",
+  "version": "0.1.1",
+  "description": "CLI for the Agent Job Protocol \u2014 hire agents and check job status from the terminal",
+  "type": "module",
+  "bin": {
+    "ajp": "./index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ilucky21c/ajp-protocol.git",
+    "directory": "cli"
+  },
+  "keywords": [
+    "ajp",
+    "agent-job-protocol",
+    "provenance",
+    "ai",
+    "agents",
+    "cli"
+  ],
+  "license": "MIT"
+}

package/package.json

@@ -1,20 +1,30 @@
 {
   "name": "ajp-protocol",
-  "version": "0.1.0",
-  "description": "Agent Job Protocol — standard interaction layer for the agent internet",
+  "version": "0.2.2",
+  "description": "Agent Job Protocol \u2014 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"],
+  "keywords": [
+    "ai-agent",
+    "agent-protocol",
+    "ajp",
+    "provenance",
+    "llm",
+    "agent-to-agent"
+  ],
   "license": "MIT",
   "dependencies": {
-    "provenance-protocol": "^0.1.0"
+    "provenance-protocol": "^0.2.2"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/ilucky21c/ajp-protocol"
   },
-  "homepage": "https://provenance.dev/ajp"
+  "homepage": "https://getprovenance.dev/ajp",
+  "scripts": {
+    "test": "node test/trust.test.mjs"
+  }
 }

package/schema/job-offer.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://provenance.dev/ajp/schema/0.1/job-offer.json",
+  "$id": "https://getprovenance.dev/ajp/schema/0.1/job-offer.json",
   "title": "AJP JobOffer",
   "description": "Agent Job Protocol v0.1 — JobOffer message",
   "type": "object",
@@ -86,8 +86,8 @@
 
     "signature": {
       "type": "string",
-      "description": "HMAC-SHA256 of the message body excluding this field. Format: sha256:hex",
-      "pattern": "^sha256:[a-f0-9]{64}$"
+      "description": "Signature of the message body excluding this field. Human senders: sha256:hex (HMAC-SHA256). Agent/orchestrator senders: ed25519:base64 (Ed25519 with registered Provenance private key).",
+      "pattern": "^(sha256:[a-f0-9]{64}|ed25519:[A-Za-z0-9+/=]+)$"
     }
   },