sello 0.1.16 → 0.1.17

package/README.md

@@ -104,11 +104,13 @@ SELLO_SUBMIT_MODE=background
 
 Sello works with your own log server. Using `sello.build` is an optional convenience, not a protocol requirement.
 
-To scaffold a tiny emitter or HTTP route:
+To scaffold a tiny demo for each boundary:
 
 ```bash
 npx --yes sello init-demo
 npx --yes sello init-http-demo
+npx --yes sello init-mcp-demo
+npx --yes sello init-a2a-demo
 ```
 
 ## Add Sello to an MCP Server
@@ -166,6 +168,15 @@ By default, Sello hashes the A2A JSON-RPC `method` and `params`, excluding reque
 
 See [docs/a2a.md](docs/a2a.md) for token handling, hash boundaries, unknown-method behavior, and action viewing.
 
+## Examples
+
+| What you want to wire | Start here |
+| --- | --- |
+| A normal tool handler | [SDK Quickstart](docs/sdk-quickstart.md) and [`quickstart-tool.ts`](sdks/typescript/examples/quickstart-tool.ts) |
+| An MCP tool | `npx --yes sello init-mcp-demo`, [MCP Integration](docs/mcp.md), and [`mcp-minimal-server.ts`](sdks/typescript/examples/mcp-minimal-server.ts) |
+| An A2A message handler | `npx --yes sello init-a2a-demo`, [A2A Integration](docs/a2a.md), and [`a2a-minimal-server.ts`](sdks/typescript/examples/a2a-minimal-server.ts) |
+| Verified action viewing | `npx sello actions` or `http://localhost:8787/actions` |
+
 ## See Logged Actions
 
 ```bash
@@ -207,8 +218,6 @@ Sello does not prove that the agent called every service it should have called,
 - [Protocol Walkthrough](docs/protocol-walkthrough.md): the primitive receipt loop for implementers.
 - [SPEC.md](SPEC.md): the Sello protocol draft.
 - [Notarized Agents paper](https://arxiv.org/abs/2606.04193): design rationale, threat model, and prior art.
-- [sdks/typescript/examples/mcp-minimal-server.ts](sdks/typescript/examples/mcp-minimal-server.ts): a small MCP integration.
-- [sdks/typescript/examples/a2a-minimal-server.ts](sdks/typescript/examples/a2a-minimal-server.ts): a small A2A integration.
 - [docs/security-review.md](docs/security-review.md) and [docs/sdk-security-audit.md](docs/sdk-security-audit.md): current review notes.
 
 The TypeScript SDK is published on [npm](https://www.npmjs.com/package/sello) and lives in [`sdks/typescript/`](sdks/typescript/). The Python SDK is published on [PyPI](https://pypi.org/project/sello/) and lives in [`sdks/python/`](sdks/python/). Both SDKs support the same service-side `sello.service()` flow; Python uses the `@receipts.tool(...)` decorator. MCP and A2A helpers are currently TypeScript-first. Live Rekor proof verification and production identity operations are still future work.

package/dist/cli/sello.js

@@ -96,6 +96,12 @@ try {
     case "init-http-demo":
       initHttpDemoCommand(process.argv.slice(3));
       break;
+    case "init-mcp-demo":
+      initMcpDemoCommand(process.argv.slice(3));
+      break;
+    case "init-a2a-demo":
+      initA2aDemoCommand(process.argv.slice(3));
+      break;
     case "keys":
       keysCommand(process.argv.slice(3));
       break;
@@ -337,13 +343,13 @@ function initDemoCommand(args          )       {
   console.log(`Created ${output}`);
   console.log("");
   console.log("Terminal 1: keep the local dev log running");
-  console.log("  npx sello dev");
+  console.log(`  ${devCommandHint()}`);
   console.log("");
   console.log("Terminal 2: emit and view a receipt");
   console.log(`  node ${output}`);
   console.log("  npx sello actions");
   console.log("");
-  console.log("Then open http://localhost:8787/actions");
+  console.log(`Then open ${actionViewerUrlHint()}`);
 }
 
 function initHttpDemoCommand(args          )       {
@@ -359,7 +365,7 @@ function initHttpDemoCommand(args          )       {
   console.log(`Created ${output}`);
   console.log("");
   console.log("Terminal 1: keep the local dev log running");
-  console.log("  npx sello dev");
+  console.log(`  ${devCommandHint()}`);
   console.log("");
   console.log("Terminal 2: start the route");
   console.log(`  node ${output}`);
@@ -368,7 +374,51 @@ function initHttpDemoCommand(args          )       {
   console.log("  npx sello call-http-demo");
   console.log("  npx sello actions");
   console.log("");
-  console.log("Then open http://localhost:8787/actions");
+  console.log(`Then open ${actionViewerUrlHint()}`);
+}
+
+function initMcpDemoCommand(args          )       {
+  const output = readFlag(args, "--output") ?? "sello-mcp-demo.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, mcpDemoSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log(`  ${devCommandHint()}`);
+  console.log("");
+  console.log("Terminal 2: run the MCP-shaped tool call and view the receipt");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+  console.log("");
+  console.log(`Then open ${actionViewerUrlHint()}`);
+}
+
+function initA2aDemoCommand(args          )       {
+  const output = readFlag(args, "--output") ?? "sello-a2a-demo.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, a2aDemoSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log(`  ${devCommandHint()}`);
+  console.log("");
+  console.log("Terminal 2: run the A2A-shaped message and view the receipt");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+  console.log("");
+  console.log(`Then open ${actionViewerUrlHint()}`);
 }
 
 function keysCommand(args          )       {
@@ -851,6 +901,8 @@ function printHelp()       {
   sello call-http-demo [--url http://localhost:8790/calendar/events] [--title title]
   sello init-demo [--output emit-receipt.mjs] [--force]
   sello init-http-demo [--output sello-http-route.mjs] [--force]
+  sello init-mcp-demo [--output sello-mcp-demo.mjs] [--force]
+  sello init-a2a-demo [--output sello-a2a-demo.mjs] [--force]
   sello actions [--token agent-token]
   sello keys service
   sello inspect-env
@@ -917,6 +969,25 @@ function formatHttpDemoResponse(responseText        )         {
   }
 }
 
+function devCommandHint()         {
+  const state = loadDevStateIfPresent();
+  const port = state ? portFromDevState(state) : undefined;
+  return port && port !== "8787" ? `npx sello dev --port ${port}` : "npx sello dev";
+}
+
+function actionViewerUrlHint()         {
+  const state = loadDevStateIfPresent();
+  return state ? actionViewerUrl(state) : "http://localhost:8787/actions";
+}
+
+function portFromDevState(state          )                     {
+  try {
+    return new URL(state.logEndpoint).port;
+  } catch {
+    return undefined;
+  }
+}
+
 function slug(value        )         {
   return value
     .toLowerCase()
@@ -1080,3 +1151,124 @@ function slug(value) {
 }
 `;
 }
+
+function mcpDemoSource()         {
+  return `import { readFileSync } from "node:fs";
+import { sello } from "sello";
+
+const state = JSON.parse(readFileSync(".sello/dev.json", "utf8"));
+
+const receipts = sello.service({
+  service: state.serviceId,
+  serviceKey: state.serviceKey,
+  tokenIssuer: state.tokenIssuerPublicKey,
+  log: sello.logs.http(state.logUrl, { endpoint: state.logEndpoint }),
+  submit: { mode: "await" },
+});
+
+const createEvent = receipts.mcpTool("calendar.create_event", async (args) => {
+  const title = readString(args.title, "title");
+  return {
+    content: [
+      {
+        type: "text",
+        text: "created " + title,
+      },
+    ],
+  };
+});
+
+const response = await createEvent(
+  {
+    title: "MCP launch checklist",
+  },
+  {
+    requestInfo: {
+      headers: new Headers({
+        authorization: "Bearer " + state.agentToken,
+      }),
+    },
+  },
+);
+
+await receipts.flush();
+
+console.log("MCP tool response:");
+console.log(JSON.stringify(response, null, 2));
+
+function readString(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(name + " must be a non-empty string");
+  }
+  return value;
+}
+`;
+}
+
+function a2aDemoSource()         {
+  return `import { readFileSync } from "node:fs";
+import { sello } from "sello";
+
+const state = JSON.parse(readFileSync(".sello/dev.json", "utf8"));
+
+const receipts = sello.service({
+  service: state.serviceId,
+  serviceKey: state.serviceKey,
+  tokenIssuer: state.tokenIssuerPublicKey,
+  log: sello.logs.http(state.logUrl, { endpoint: state.logEndpoint }),
+  submit: { mode: "await" },
+});
+
+const sendMessage = receipts.a2aMessage(async (request) => ({
+  jsonrpc: "2.0",
+  id: request.id,
+  result: {
+    kind: "message",
+    messageId: "calendar-reply-1",
+    role: "agent",
+    parts: [
+      {
+        kind: "text",
+        text: "created " + readMessageText(request),
+      },
+    ],
+  },
+}));
+
+const response = await sendMessage(
+  {
+    jsonrpc: "2.0",
+    id: "a2a-demo-1",
+    method: "message/send",
+    params: {
+      message: {
+        role: "user",
+        parts: [
+          {
+            kind: "text",
+            text: "A2A launch checklist",
+          },
+        ],
+      },
+    },
+  },
+  {
+    headers: new Headers({
+      authorization: "Bearer " + state.agentToken,
+    }),
+  },
+);
+
+await receipts.flush();
+
+console.log("A2A message response:");
+console.log(JSON.stringify(response, null, 2));
+
+function readMessageText(request) {
+  return request.params.message.parts
+    .filter((part) => part.kind === "text")
+    .map((part) => part.text)
+    .join(" ") || "untitled";
+}
+`;
+}

package/docs/a2a.md

@@ -122,6 +122,18 @@ For a specific agent token:
 npx sello actions --token <agent-token>
 ```
 
+## Runnable Demo
+
+To generate a tiny A2A-shaped demo in your project:
+
+```bash
+npx --yes sello init-a2a-demo
+node sello-a2a-demo.mjs
+npx --yes sello actions
+```
+
+Keep `npx sello dev` running in another terminal while you run the generated file.
+
 ## Example
 
 See [`sdks/typescript/examples/a2a-minimal-server.ts`](../sdks/typescript/examples/a2a-minimal-server.ts) for a dependency-free A2A-shaped example. It wraps one `message/send` handler and leaves unknown methods unreceipted.

package/docs/mcp.md

@@ -132,6 +132,18 @@ For a specific agent token:
 npx sello actions --token <agent-token>
 ```
 
+## Runnable Demo
+
+To generate a tiny MCP-shaped demo in your project:
+
+```bash
+npx --yes sello init-mcp-demo
+node sello-mcp-demo.mjs
+npx --yes sello actions
+```
+
+Keep `npx sello dev` running in another terminal while you run the generated file.
+
 ## Example
 
 See [`sdks/typescript/examples/mcp-minimal-server.ts`](../sdks/typescript/examples/mcp-minimal-server.ts) for a dependency-free MCP-shaped example. It wraps one `tools/call` handler and leaves unknown tools unreceipted.

package/docs/sdk-quickstart.md

@@ -72,18 +72,43 @@ npx --yes sello call-http-demo
 npx --yes sello actions
 ```
 
+To try the same local loop around MCP or A2A-shaped handlers:
+
+```bash
+npx --yes sello init-mcp-demo
+node sello-mcp-demo.mjs
+npx --yes sello actions
+```
+
+```bash
+npx --yes sello init-a2a-demo
+node sello-a2a-demo.mjs
+npx --yes sello actions
+```
+
 ## What Just Happened?
 
-`sello dev` created local development keys, a demo authorization token, a service registry, and a local transparency log. The wrapped tool or route verified the token before running your handler. After the handler returned, Sello signed an encrypted receipt for the observed action and submitted it to the local log. The log stored encrypted receipt data, not plaintext action details. `sello actions` used the owner key from local dev state to fetch, verify, decrypt, and print the action.
+`sello dev` created local development keys, a demo authorization token, a service registry, and a local transparency log. The wrapped function, route, MCP tool, or A2A message callback verified the token before running your code. After your code returned, Sello signed an encrypted receipt for the observed action and submitted it to the local log. The log stored encrypted receipt data, not plaintext action details. `sello actions` used the owner key from local dev state to fetch, verify, decrypt, and print the action.
 
 Local dev state lives under `.sello/`. The encrypted dev log is stored in `.sello/dev-log.jsonl`, so receipts survive restarting `sello dev` without being committed to git.
 
+## Which Wrapper?
+
+| Existing boundary | Use |
+| --- | --- |
+| Plain function or HTTP route | `receipts.tool("calendar.create_event", handler)` |
+| MCP `tools/call` callback | `receipts.mcpTool("calendar.create_event", handler)` |
+| A2A JSON-RPC message handler | `receipts.a2aMessage(handler)` |
+| Owner action viewing | `npx sello actions` |
+
 ## Troubleshooting
 
 - **Port already in use:** run `npx sello dev --port 8791`.
 - **No actions found:** make sure `sello dev` is running from the same project folder where you emitted the receipt.
 - **Missing token:** run `npx sello dev` first so `.sello/dev.json` exists.
 
+## Contributing From This Repo
+
 Inside this repo, start the local log and action viewer:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sello",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",

package/sdks/typescript/src/cli/sello.ts

@@ -97,6 +97,12 @@ try {
     case "init-http-demo":
       initHttpDemoCommand(process.argv.slice(3));
       break;
+    case "init-mcp-demo":
+      initMcpDemoCommand(process.argv.slice(3));
+      break;
+    case "init-a2a-demo":
+      initA2aDemoCommand(process.argv.slice(3));
+      break;
     case "keys":
       keysCommand(process.argv.slice(3));
       break;
@@ -338,13 +344,13 @@ function initDemoCommand(args: string[]): void {
   console.log(`Created ${output}`);
   console.log("");
   console.log("Terminal 1: keep the local dev log running");
-  console.log("  npx sello dev");
+  console.log(`  ${devCommandHint()}`);
   console.log("");
   console.log("Terminal 2: emit and view a receipt");
   console.log(`  node ${output}`);
   console.log("  npx sello actions");
   console.log("");
-  console.log("Then open http://localhost:8787/actions");
+  console.log(`Then open ${actionViewerUrlHint()}`);
 }
 
 function initHttpDemoCommand(args: string[]): void {
@@ -360,7 +366,7 @@ function initHttpDemoCommand(args: string[]): void {
   console.log(`Created ${output}`);
   console.log("");
   console.log("Terminal 1: keep the local dev log running");
-  console.log("  npx sello dev");
+  console.log(`  ${devCommandHint()}`);
   console.log("");
   console.log("Terminal 2: start the route");
   console.log(`  node ${output}`);
@@ -369,7 +375,51 @@ function initHttpDemoCommand(args: string[]): void {
   console.log("  npx sello call-http-demo");
   console.log("  npx sello actions");
   console.log("");
-  console.log("Then open http://localhost:8787/actions");
+  console.log(`Then open ${actionViewerUrlHint()}`);
+}
+
+function initMcpDemoCommand(args: string[]): void {
+  const output = readFlag(args, "--output") ?? "sello-mcp-demo.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, mcpDemoSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log(`  ${devCommandHint()}`);
+  console.log("");
+  console.log("Terminal 2: run the MCP-shaped tool call and view the receipt");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+  console.log("");
+  console.log(`Then open ${actionViewerUrlHint()}`);
+}
+
+function initA2aDemoCommand(args: string[]): void {
+  const output = readFlag(args, "--output") ?? "sello-a2a-demo.mjs";
+  const force = args.includes("--force");
+
+  if (existsSync(output) && !force) {
+    throw new TypeError(`${output} already exists. Pass --force to overwrite it.`);
+  }
+
+  writeFileSync(output, a2aDemoSource(), { mode: 0o644 });
+
+  console.log(`Created ${output}`);
+  console.log("");
+  console.log("Terminal 1: keep the local dev log running");
+  console.log(`  ${devCommandHint()}`);
+  console.log("");
+  console.log("Terminal 2: run the A2A-shaped message and view the receipt");
+  console.log(`  node ${output}`);
+  console.log("  npx sello actions");
+  console.log("");
+  console.log(`Then open ${actionViewerUrlHint()}`);
 }
 
 function keysCommand(args: string[]): void {
@@ -852,6 +902,8 @@ function printHelp(): void {
   sello call-http-demo [--url http://localhost:8790/calendar/events] [--title title]
   sello init-demo [--output emit-receipt.mjs] [--force]
   sello init-http-demo [--output sello-http-route.mjs] [--force]
+  sello init-mcp-demo [--output sello-mcp-demo.mjs] [--force]
+  sello init-a2a-demo [--output sello-a2a-demo.mjs] [--force]
   sello actions [--token agent-token]
   sello keys service
   sello inspect-env
@@ -918,6 +970,25 @@ function formatHttpDemoResponse(responseText: string): string {
   }
 }
 
+function devCommandHint(): string {
+  const state = loadDevStateIfPresent();
+  const port = state ? portFromDevState(state) : undefined;
+  return port && port !== "8787" ? `npx sello dev --port ${port}` : "npx sello dev";
+}
+
+function actionViewerUrlHint(): string {
+  const state = loadDevStateIfPresent();
+  return state ? actionViewerUrl(state) : "http://localhost:8787/actions";
+}
+
+function portFromDevState(state: DevState): string | undefined {
+  try {
+    return new URL(state.logEndpoint).port;
+  } catch {
+    return undefined;
+  }
+}
+
 function slug(value: string): string {
   return value
     .toLowerCase()
@@ -1081,3 +1152,124 @@ function slug(value) {
 }
 `;
 }
+
+function mcpDemoSource(): string {
+  return `import { readFileSync } from "node:fs";
+import { sello } from "sello";
+
+const state = JSON.parse(readFileSync(".sello/dev.json", "utf8"));
+
+const receipts = sello.service({
+  service: state.serviceId,
+  serviceKey: state.serviceKey,
+  tokenIssuer: state.tokenIssuerPublicKey,
+  log: sello.logs.http(state.logUrl, { endpoint: state.logEndpoint }),
+  submit: { mode: "await" },
+});
+
+const createEvent = receipts.mcpTool("calendar.create_event", async (args) => {
+  const title = readString(args.title, "title");
+  return {
+    content: [
+      {
+        type: "text",
+        text: "created " + title,
+      },
+    ],
+  };
+});
+
+const response = await createEvent(
+  {
+    title: "MCP launch checklist",
+  },
+  {
+    requestInfo: {
+      headers: new Headers({
+        authorization: "Bearer " + state.agentToken,
+      }),
+    },
+  },
+);
+
+await receipts.flush();
+
+console.log("MCP tool response:");
+console.log(JSON.stringify(response, null, 2));
+
+function readString(value, name) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(name + " must be a non-empty string");
+  }
+  return value;
+}
+`;
+}
+
+function a2aDemoSource(): string {
+  return `import { readFileSync } from "node:fs";
+import { sello } from "sello";
+
+const state = JSON.parse(readFileSync(".sello/dev.json", "utf8"));
+
+const receipts = sello.service({
+  service: state.serviceId,
+  serviceKey: state.serviceKey,
+  tokenIssuer: state.tokenIssuerPublicKey,
+  log: sello.logs.http(state.logUrl, { endpoint: state.logEndpoint }),
+  submit: { mode: "await" },
+});
+
+const sendMessage = receipts.a2aMessage(async (request) => ({
+  jsonrpc: "2.0",
+  id: request.id,
+  result: {
+    kind: "message",
+    messageId: "calendar-reply-1",
+    role: "agent",
+    parts: [
+      {
+        kind: "text",
+        text: "created " + readMessageText(request),
+      },
+    ],
+  },
+}));
+
+const response = await sendMessage(
+  {
+    jsonrpc: "2.0",
+    id: "a2a-demo-1",
+    method: "message/send",
+    params: {
+      message: {
+        role: "user",
+        parts: [
+          {
+            kind: "text",
+            text: "A2A launch checklist",
+          },
+        ],
+      },
+    },
+  },
+  {
+    headers: new Headers({
+      authorization: "Bearer " + state.agentToken,
+    }),
+  },
+);
+
+await receipts.flush();
+
+console.log("A2A message response:");
+console.log(JSON.stringify(response, null, 2));
+
+function readMessageText(request) {
+  return request.params.message.parts
+    .filter((part) => part.kind === "text")
+    .map((part) => part.text)
+    .join(" ") || "untitled";
+}
+`;
+}