sello 0.1.14 → 0.1.16

package/README.md

@@ -16,16 +16,10 @@
 <p align="center">
   <a href="#try-it">Quickstart</a> &middot;
   <a href="#add-sello-to-a-tool">Add Sello</a> &middot;
-  <a href="#add-sello-to-an-mcp-server">MCP</a> &middot;
+  <a href="docs/mcp.md">MCP</a> &middot;
   <a href="sdks/README.md">SDKs</a> &middot;
-  <a href="#see-logged-actions">Actions</a> &middot;
-  <a href="#how-it-works">How It Works</a> &middot;
-  <a href="#learn-more">Learn More</a> &middot;
   <a href="SPEC.md">Protocol</a> &middot;
-  <a href="https://arxiv.org/abs/2606.04193">Paper</a> &middot;
-  <a href="SECURITY.md">Security</a> &middot;
-  <a href="CONTRIBUTING.md">Contributing</a> &middot;
-  <a href="#license">License</a>
+  <a href="https://arxiv.org/abs/2606.04193">Paper</a>
 </p>
 
 Sello is a protocol for independently-verifiable records of AI agent actions.
@@ -150,6 +144,28 @@ receipts.mcpTool("calendar.create_event", handler, {
 });
 ```
 
+See [docs/mcp.md](docs/mcp.md) for token handling, hash boundaries, unknown-tool behavior, and action viewing.
+
+## Add Sello to an A2A Agent
+
+If your service receives Agent2Agent messages, wrap the message handler:
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+export const sendMessage = receipts.a2aMessage(async (request, context) => {
+  return agent.handleMessage(request, context);
+});
+```
+
+`a2aMessage` verifies the agent token before your handler runs, preserves the handler's return value, rethrows handler errors, and emits a receipt with action type `a2a.<method>`, such as `a2a.message/send`.
+
+By default, Sello hashes the A2A JSON-RPC `method` and `params`, excluding request ids, headers, bearer tokens, and runtime context.
+
+See [docs/a2a.md](docs/a2a.md) for token handling, hash boundaries, unknown-method behavior, and action viewing.
+
 ## See Logged Actions
 
 ```bash
@@ -184,15 +200,18 @@ Sello does not prove that the agent called every service it should have called,
 ## Learn More
 
 - [SDK Quickstart](docs/sdk-quickstart.md): local dev, HTTP demo, self-hosted config, and hosted config.
+- [MCP Integration](docs/mcp.md): where Sello wraps MCP tool callbacks.
+- [A2A Integration](docs/a2a.md): where Sello wraps Agent2Agent message handlers.
 - [SDKs](sdks/README.md): TypeScript and Python package layout.
 - [Python SDK](sdks/python/README.md): Python package install command, scope, and test command.
 - [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. Live Rekor proof verification and production identity operations are still future work.
+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.
 
 ## Core Terms
 

package/dist/cli/sello.js

@@ -199,6 +199,29 @@ async function devCommand(args          )                {
     console.log(`Local dev log: ${logPath}`);
     console.log(`Loaded ${devLogEntryCountLabel(loadedEntries)}.`);
   });
+  server.on("error", (error) => {
+    if (isPortInUse(error)) {
+      console.error(`sello: port ${port} is already in use.`);
+      console.error("");
+      console.error("Try:");
+      console.error(`  sello dev --port ${port + 1}`);
+      console.error("");
+      console.error("Or stop the process using that port:");
+      console.error(`  lsof -nP -iTCP:${port} -sTCP:LISTEN`);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (isListenError(error)) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`sello: could not start dev server on port ${port}.`);
+      console.error(message);
+      process.exitCode = 1;
+      return;
+    }
+
+    throw error;
+  });
 }
 
 async function emitDemoCommand(args          )                {
@@ -257,14 +280,7 @@ async function callHttpDemoCommand(args          )                {
   );
   const url = readFlag(args, "--url") ?? "http://localhost:8790/calendar/events";
   const title = readFlag(args, "--title") ?? "Ship Sello";
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${state.agentToken}`,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({ title }),
-  });
+  const response = await fetchHttpDemo(url, state.agentToken, title);
   const responseText = await response.text();
 
   if (!response.ok) {
@@ -283,6 +299,31 @@ async function callHttpDemoCommand(args          )                {
   console.log(`  ${actionViewerUrl(state)}`);
 }
 
+async function fetchHttpDemo(
+  url        ,
+  agentToken        ,
+  title        ,
+)                    {
+  try {
+    return await fetch(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${agentToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ title }),
+    });
+  } catch (error) {
+    if (isFetchFailed(error)) {
+      throw new TypeError(
+        `could not reach the HTTP demo route at ${url}.\n\nStart it in another terminal:\n  node sello-http-route.mjs`,
+      );
+    }
+
+    throw error;
+  }
+}
+
 function initDemoCommand(args          )       {
   const output = readFlag(args, "--output") ?? "emit-receipt.mjs";
   const force = args.includes("--force");
@@ -787,6 +828,22 @@ function isRecord(value         )                                   {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isPortInUse(error         )          {
+  return (
+    isRecord(error) &&
+    error.code === "EADDRINUSE" &&
+    error.syscall === "listen"
+  );
+}
+
+function isListenError(error         )          {
+  return isRecord(error) && error.syscall === "listen";
+}
+
+function isFetchFailed(error         )          {
+  return error instanceof TypeError && error.message === "fetch failed";
+}
+
 function printHelp()       {
   console.log(`Usage:
   sello dev [--port 8787] [--service service-id] [--dry-run]

package/dist/sdk/service.js

@@ -25,6 +25,8 @@ import {
          
                                   
 
+                                                                               
+
                                                      
                              
                         
@@ -71,6 +73,35 @@ import {
                                     
   
 
+                                                                     
+                   
+                   
+  
+
+                                                                            
+                   
+                   
+                                  
+
+                                                                            
+                                                                            
+                                          
+                                                
+                       
+    
+                       
+                                                            
+                  
+                                                          
+                                                     
+              
+                                                            
+                                  
+                    
+                                                            
+                                    
+  
+
                                   
                    
                                
@@ -100,6 +131,10 @@ import {
                                                           
                                                            
                                                   
+                                                   
+                                                                
+                                                                 
+                                                        
                          
   
 
@@ -150,11 +185,14 @@ export function createSelloService(input                    )                {
   }
 
   function wrapTool                   (
-    actionType        ,
+    actionType                          ,
     handler                                     ,
     options                                      = {},
   )                                      {
-    if (typeof actionType !== "string" || actionType.length === 0) {
+    if (
+      (typeof actionType === "string" && actionType.length === 0) ||
+      (typeof actionType !== "string" && typeof actionType !== "function")
+    ) {
       throw new TypeError("Sello action type must be a non-empty string");
     }
 
@@ -174,6 +212,7 @@ export function createSelloService(input                    )                {
         resolved.fallbackSelloLogs,
         resolved.log.logUrl,
       );
+      const resolvedActionType = resolveActionType(actionType, request);
       const base = {
         authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
         ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
@@ -182,7 +221,7 @@ export function createSelloService(input                    )                {
         servicePrivateKey: resolved.servicePrivateKey,
         serviceIdentifier: resolved.service,
         logUrl: resolved.log.logUrl,
-        actionType,
+        actionType: resolvedActionType,
         actionInputBytes: (options.canonicalizeInput ?? canonicalJsonBytes)(request),
         timestamp: resolved.now(),
       };
@@ -271,6 +310,32 @@ export function createSelloService(input                    )                {
         return await wrapped({ name, arguments: args, context });
       };
     },
+    a2aMessage                                      (
+      handler                                                    ,
+      options                                                     = {},
+    )                                                     {
+      const wrapped = wrapTool 
+                                                    
+                
+       (
+        options.actionType ?? defaultA2aActionType,
+        async (invocation) => handler(invocation.request, invocation.context),
+        {
+          authorizationToken:
+            options.authorizationToken ?? defaultA2aAuthorizationToken,
+          canonicalizeInput:
+            options.canonicalizeInput ?? defaultA2aCanonicalizeInput,
+          canonicalizeOutput: options.canonicalizeOutput,
+          canonicalizeError: options.canonicalizeError,
+          isDenied: options.isDenied,
+          deniedResponse: options.deniedResponse,
+        },
+      );
+
+      return async (request         , context         )                    => {
+        return await wrapped({ request, context });
+      };
+    },
     async flush()                {
       await publisher?.flush();
     },
@@ -587,6 +652,53 @@ function defaultMcpCanonicalizeInput(
   });
 }
 
+function defaultA2aAuthorizationToken(
+  invocation                                             ,
+)                      {
+  const fromContext = authorizationTokenFromUnknown(invocation.context);
+  if (fromContext) {
+    return fromContext;
+  }
+
+  const fromRequest = authorizationTokenFromUnknown(invocation.request);
+  if (fromRequest) {
+    return fromRequest;
+  }
+
+  throw new TypeError(
+    "Sello A2A authorization token not found. Pass authorizationToken or include an Authorization header in the A2A context.",
+  );
+}
+
+function defaultA2aActionType(
+  invocation                                             ,
+)         {
+  const method = methodFromA2aRequest(invocation.request);
+  return method ? `a2a.${method}` : "a2a.message/send";
+}
+
+function defaultA2aCanonicalizeInput(
+  invocation                                             ,
+)             {
+  if (isRecord(invocation.request) && typeof invocation.request.method === "string") {
+    return canonicalJsonBytes({
+      method: invocation.request.method,
+      params: invocation.request.params ?? null,
+    });
+  }
+
+  return canonicalJsonBytes(invocation.request);
+}
+
+function methodFromA2aRequest(request         )                     {
+  if (!isRecord(request)) {
+    return undefined;
+  }
+
+  const method = request.method;
+  return typeof method === "string" && method.length > 0 ? method : undefined;
+}
+
 function authorizationTokenFromUnknown(value         )                                  {
   if (!isRecord(value)) {
     return undefined;
@@ -692,6 +804,20 @@ function resolveValue                (
   return value;
 }
 
+function resolveActionType         (
+  actionType                          ,
+  request         ,
+)         {
+  const resolved =
+    typeof actionType === "function" ? actionType(request) : actionType;
+
+  if (typeof resolved !== "string" || resolved.length === 0) {
+    throw new TypeError("Sello action type must be a non-empty string");
+  }
+
+  return resolved;
+}
+
 function envSubmitMode(env             )                                              {
   const mode = env.SELLO_SUBMIT_MODE;
   if (mode === undefined) {

package/docs/a2a.md

@@ -0,0 +1,127 @@
+# Add Sello to an A2A Agent
+
+Sello belongs around the handler that receives an A2A message: after your server has accepted the request and before your agent logic runs.
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+export const sendMessage = receipts.a2aMessage(async (request, context) => {
+  return agent.handleMessage(request, context);
+});
+```
+
+## What It Does
+
+`receipts.a2aMessage(...)` returns a normal A2A message handler. When another agent sends a message, Sello:
+
+1. Reads the agent authorization token from the A2A context.
+2. Verifies the token before your handler runs.
+3. Runs your handler unchanged.
+4. Emits a `success`, `error`, or `denied` receipt.
+5. Preserves the handler return value and rethrows handler errors.
+
+For JSON-RPC requests, the default receipt action type is:
+
+```text
+a2a.<method>
+```
+
+For `message/send`, the action type is:
+
+```text
+a2a.message/send
+```
+
+## Token Source
+
+By default, Sello looks for `Authorization: Bearer ...` in common context or request shapes, including:
+
+```ts
+context.headers.authorization
+context.requestInfo.headers.authorization
+context.request.headers.authorization
+request.headers.authorization
+```
+
+Fetch-style `Headers` objects are supported too.
+
+If your A2A runtime stores the token somewhere else, pass an extractor:
+
+```ts
+receipts.a2aMessage(handler, {
+  authorizationToken: ({ context }) => context.session.token,
+});
+```
+
+The token should be the same authorization token the calling agent used for the A2A request. Sello hashes the exact token bytes into `sello_token_ref`; do not parse and reserialize it first.
+
+## What Gets Hashed
+
+For JSON-RPC-shaped A2A requests, the default input hash covers only the stable method boundary:
+
+```json
+{
+  "method": "message/send",
+  "params": {}
+}
+```
+
+Sello does not hash:
+
+- The bearer token.
+- Transport headers.
+- JSON-RPC request ids.
+- Connection/session objects.
+- Other context that may vary across runtimes.
+
+That keeps receipts stable without leaking secrets or transport details.
+
+If you need a different hash boundary, pass `canonicalizeInput`.
+
+## Unknown Methods
+
+Only wrap A2A methods you actually execute. If a request names an unknown method, return your normal JSON-RPC method-not-found error without emitting a Sello receipt.
+
+The minimal example does this:
+
+```ts
+if (request.body.method !== "message/send") {
+  return {
+    jsonrpc: "2.0",
+    id: request.body.id,
+    error: { code: -32601, message: "method not found" },
+  };
+}
+```
+
+## View Actions
+
+In local development:
+
+```bash
+npx sello dev
+```
+
+Run your A2A message call, then view verified actions:
+
+```bash
+npx sello actions
+```
+
+Or open:
+
+```text
+http://localhost:8787/actions
+```
+
+For a specific agent token:
+
+```bash
+npx sello actions --token <agent-token>
+```
+
+## 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

@@ -0,0 +1,137 @@
+# Add Sello to an MCP Server
+
+Sello belongs around the tool callback: after your MCP server has identified the tool, before your business logic runs.
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+server.registerTool(
+  "calendar.create_event",
+  { inputSchema: createEventInputSchema },
+  receipts.mcpTool("calendar.create_event", async (args) => {
+    const event = await calendar.events.create(args);
+    return {
+      content: [{ type: "text", text: event.id }],
+    };
+  }),
+);
+```
+
+Some MCP SDK versions call this registration method `tool` instead of `registerTool`. Use the same callback slot either way.
+
+## What It Does
+
+`receipts.mcpTool(...)` returns a normal MCP tool callback. When the agent calls the tool, Sello:
+
+1. Reads the agent authorization token from the MCP context.
+2. Verifies the token before your callback runs.
+3. Runs your callback unchanged.
+4. Emits a `success`, `error`, or `denied` receipt.
+5. Preserves the callback return value and rethrows callback errors.
+
+The default receipt action type is:
+
+```text
+mcp.tools/call.<tool-name>
+```
+
+For `calendar.create_event`, the action type is:
+
+```text
+mcp.tools/call.calendar.create_event
+```
+
+## Token Source
+
+By default, Sello looks for `Authorization: Bearer ...` in common MCP context shapes, including:
+
+```ts
+context.headers.authorization
+context.requestInfo.headers.authorization
+context.request.headers.authorization
+```
+
+Fetch-style `Headers` objects are supported too.
+
+If your transport stores the token somewhere else, pass an extractor:
+
+```ts
+receipts.mcpTool("calendar.create_event", handler, {
+  authorizationToken: ({ context }) => context.session.token,
+});
+```
+
+The token should be the same authorization token the agent used for the tool call. Sello hashes the exact token bytes into `sello_token_ref`; do not parse and reserialize it first.
+
+## What Gets Hashed
+
+The default MCP input hash covers only the stable MCP action shape:
+
+```json
+{
+  "method": "tools/call",
+  "params": {
+    "name": "calendar.create_event",
+    "arguments": {}
+  }
+}
+```
+
+Sello does not hash:
+
+- The bearer token.
+- Transport headers.
+- Connection/session objects.
+- Other context that may vary across runtimes.
+
+That keeps receipts stable without leaking secrets or transport details.
+
+If you need a different hash boundary, pass `canonicalizeInput`.
+
+## Unknown Tools
+
+Only wrap tools you actually execute. If a request names an unknown tool, return your normal MCP `method not found` or `tool not found` error without emitting a Sello receipt.
+
+The minimal example does this:
+
+```ts
+if (request.body.params.name !== "calendar.create_event") {
+  return {
+    jsonrpc: "2.0",
+    id: request.body.id,
+    error: { code: -32601, message: "tool not found" },
+  };
+}
+```
+
+## View Actions
+
+In local development:
+
+```bash
+npx sello dev
+```
+
+Run your MCP tool call, then view verified actions:
+
+```bash
+npx sello actions
+```
+
+Or open:
+
+```text
+http://localhost:8787/actions
+```
+
+For a specific agent token:
+
+```bash
+npx sello actions --token <agent-token>
+```
+
+## 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/release-checklist.md

@@ -16,6 +16,9 @@ Use this checklist before publishing a Sello release.
 
 ```bash
 node --run test
+node --run package:test
+node --run package:a2a-test
+node --run package:mcp-test
 npm pack --dry-run
 ```
 
@@ -28,6 +31,8 @@ cd "$tmpdir/sello"
 node -v # must be v22.7.0 or newer
 node --run test
 node --run package:test
+node --run package:a2a-test
+node --run package:mcp-test
 npm pack --dry-run
 node --experimental-strip-types sdks/typescript/src/cli/sello.ts --help
 node --experimental-strip-types sdks/typescript/src/cli/sello.ts dev --dry-run
@@ -67,6 +72,8 @@ git push origin main --tags
 After publishing:
 
 - Confirm `npm view sello version` shows the new version.
+- Confirm `SELLO_PACKAGE_SPEC=sello@$(node -p "require('./package.json').version") node --run package:a2a-test` passes against the published npm package.
+- Confirm `SELLO_PACKAGE_SPEC=sello@$(node -p "require('./package.json').version") node --run package:mcp-test` passes against the published npm package.
 - Publish a GitHub Release for the pushed tag so PyPI trusted publishing runs.
 - Confirm `python -m pip index versions sello` shows the new version after PyPI publishing.
 - Confirm `npx sello --help` works from a clean temp directory.

package/docs/sdk-quickstart.md

@@ -126,6 +126,30 @@ receipts.mcpTool("calendar.create_event", handler, {
 });
 ```
 
+For the complete MCP placement notes, see [MCP Integration](mcp.md).
+
+For an A2A agent, wrap the message handler you already expose:
+
+```ts
+import { sello } from "sello";
+
+const receipts = sello.service();
+
+export const sendMessage = receipts.a2aMessage(async (request, context) => {
+  return agent.handleMessage(request, context);
+});
+```
+
+`receipts.a2aMessage(...)` uses action type `a2a.<method>`, for example `a2a.message/send`, and hashes only the A2A JSON-RPC method and params. It excludes request ids, headers, bearer tokens, and runtime context. If your transport stores the token somewhere else, pass an extractor:
+
+```ts
+receipts.a2aMessage(handler, {
+  authorizationToken: ({ context }) => context.session.token,
+});
+```
+
+For the complete A2A placement notes, see [A2A Integration](a2a.md).
+
 Or run the matching Python example:
 
 ```bash

package/docs/sdk-security-audit.md

@@ -30,6 +30,7 @@ These notes cover the first Stripe-style SDK implementation pass. They are writt
 - Success, error, and denied paths emit receipts without including plaintext request or response bodies.
 - The wrapper uses the configured service identity and key for every receipt.
 - `receipts.mcpTool(...)` reuses the same wrapper path. It defaults to hashing the MCP `tools/call` method, tool name, and arguments, while excluding bearer tokens and transport context from the action input hash.
+- `receipts.a2aMessage(...)` reuses the same wrapper path. It defaults to hashing the A2A JSON-RPC method and params, while excluding bearer tokens, request ids, headers, and runtime context from the action input hash.
 
 ## Phase 4: Logs And Action Viewing
 
@@ -44,6 +45,7 @@ These notes cover the first Stripe-style SDK implementation pass. They are writt
 - The example uses `submit: { mode: "await" }` so the command succeeds only after the receipt append completes.
 - The example canonicalizes only tool input fields and excludes the authorization token wrapper from the action input hash.
 - The MCP-style example reads the bearer token from the transport header, but hashes only the `tools/call` method and params.
+- The A2A-style example reads the bearer token from the transport header, but hashes only the JSON-RPC method and params.
 - README and quickstart docs keep self-hosting first-class and describe `sello.build` as optional convenience.
 
 ## Residual Risks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sello",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Reference implementation of the Sello protocol for service-signed AI agent receipts.",
   "type": "module",
   "license": "Apache-2.0",
@@ -31,10 +31,13 @@
     "bench": "node --experimental-strip-types sdks/typescript/src/cli/bench.ts",
     "demo": "node --experimental-strip-types sdks/typescript/src/cli/demo.ts",
     "dev": "node --experimental-strip-types sdks/typescript/src/cli/sello.ts dev",
+    "example:a2a:minimal": "node --test --experimental-strip-types sdks/typescript/test/examples/a2a-minimal-server.test.ts",
     "example:mcp:minimal": "node --test --experimental-strip-types sdks/typescript/test/examples/mcp-minimal-server.test.ts",
     "example:mcp": "node --experimental-strip-types sdks/typescript/examples/mcp-tool-server.ts",
     "example:tool": "node --experimental-strip-types sdks/typescript/examples/quickstart-tool.ts",
     "build": "node --disable-warning=ExperimentalWarning sdks/typescript/scripts/build-dist.mjs",
+    "package:a2a-test": "node sdks/typescript/scripts/package-a2a-smoke.mjs",
+    "package:mcp-test": "node sdks/typescript/scripts/package-mcp-smoke.mjs",
     "package:test": "node sdks/typescript/scripts/package-smoke.mjs",
     "pack:check": "node sdks/typescript/scripts/pack-check.mjs",
     "prepack": "node --disable-warning=ExperimentalWarning sdks/typescript/scripts/build-dist.mjs",
@@ -49,7 +52,8 @@
     "transparency-log",
     "cose",
     "hpke",
-    "mcp"
+    "mcp",
+    "a2a"
   ],
   "publishConfig": {
     "access": "public"

package/sdks/README.md

@@ -2,7 +2,7 @@
 
 The protocol, paper, and project docs live at the repository root. Language SDKs live here:
 
-- [`typescript/`](typescript/): npm package source, CLI, examples, fixtures, and Node tests.
+- [`typescript/`](typescript/): npm package source, CLI, MCP/A2A helpers, examples, fixtures, and Node tests.
 - [`python/`](python/): Python package source and tests.
 
 Root commands still work from the repository top level:

package/sdks/typescript/examples/a2a-minimal-server.ts

@@ -0,0 +1,85 @@
+import { sello, type SelloReceipts } from "../src/index.ts";
+
+export type MinimalA2aRequest = {
+  headers: {
+    authorization?: string;
+    Authorization?: string;
+  };
+  body: {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    method: string;
+    params: {
+      message: {
+        role: "user" | "agent";
+        parts: { kind: "text"; text: string }[];
+      };
+    };
+  };
+};
+
+export type MinimalA2aResponse = {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: {
+    kind: "message";
+    messageId: string;
+    role: "agent";
+    parts: { kind: "text"; text: string }[];
+  };
+  error?: {
+    code: number;
+    message: string;
+  };
+};
+
+export function createCalendarA2aAgent(
+  receipts: SelloReceipts = sello.service(),
+) {
+  const sendMessage = receipts.a2aMessage<
+    MinimalA2aRequest["body"],
+    MinimalA2aResponse,
+    MinimalA2aRequest
+  >(async (body) => {
+    const text = body.params.message.parts
+      .filter((part) => part.kind === "text")
+      .map((part) => part.text)
+      .join(" ");
+    const title = text || "untitled";
+
+    return {
+      jsonrpc: "2.0",
+      id: body.id,
+      result: {
+        kind: "message",
+        messageId: "calendar-reply-1",
+        role: "agent",
+        parts: [
+          {
+            kind: "text",
+            text: `created ${title}`,
+          },
+        ],
+      },
+    };
+  });
+
+  return {
+    async handle(request: MinimalA2aRequest): Promise<MinimalA2aResponse> {
+      if (request.body.method !== "message/send") {
+        return {
+          jsonrpc: "2.0",
+          id: request.body.id,
+          error: {
+            code: -32601,
+            message: "method not found",
+          },
+        };
+      }
+
+      return await sendMessage(request.body, request);
+    },
+
+    flush: () => receipts.flush(),
+  };
+}

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

@@ -200,6 +200,29 @@ async function devCommand(args: string[]): Promise<void> {
     console.log(`Local dev log: ${logPath}`);
     console.log(`Loaded ${devLogEntryCountLabel(loadedEntries)}.`);
   });
+  server.on("error", (error) => {
+    if (isPortInUse(error)) {
+      console.error(`sello: port ${port} is already in use.`);
+      console.error("");
+      console.error("Try:");
+      console.error(`  sello dev --port ${port + 1}`);
+      console.error("");
+      console.error("Or stop the process using that port:");
+      console.error(`  lsof -nP -iTCP:${port} -sTCP:LISTEN`);
+      process.exitCode = 1;
+      return;
+    }
+
+    if (isListenError(error)) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(`sello: could not start dev server on port ${port}.`);
+      console.error(message);
+      process.exitCode = 1;
+      return;
+    }
+
+    throw error;
+  });
 }
 
 async function emitDemoCommand(args: string[]): Promise<void> {
@@ -258,14 +281,7 @@ async function callHttpDemoCommand(args: string[]): Promise<void> {
   );
   const url = readFlag(args, "--url") ?? "http://localhost:8790/calendar/events";
   const title = readFlag(args, "--title") ?? "Ship Sello";
-  const response = await fetch(url, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${state.agentToken}`,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({ title }),
-  });
+  const response = await fetchHttpDemo(url, state.agentToken, title);
   const responseText = await response.text();
 
   if (!response.ok) {
@@ -284,6 +300,31 @@ async function callHttpDemoCommand(args: string[]): Promise<void> {
   console.log(`  ${actionViewerUrl(state)}`);
 }
 
+async function fetchHttpDemo(
+  url: string,
+  agentToken: string,
+  title: string,
+): Promise<Response> {
+  try {
+    return await fetch(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${agentToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ title }),
+    });
+  } catch (error) {
+    if (isFetchFailed(error)) {
+      throw new TypeError(
+        `could not reach the HTTP demo route at ${url}.\n\nStart it in another terminal:\n  node sello-http-route.mjs`,
+      );
+    }
+
+    throw error;
+  }
+}
+
 function initDemoCommand(args: string[]): void {
   const output = readFlag(args, "--output") ?? "emit-receipt.mjs";
   const force = args.includes("--force");
@@ -788,6 +829,22 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function isPortInUse(error: unknown): boolean {
+  return (
+    isRecord(error) &&
+    error.code === "EADDRINUSE" &&
+    error.syscall === "listen"
+  );
+}
+
+function isListenError(error: unknown): boolean {
+  return isRecord(error) && error.syscall === "listen";
+}
+
+function isFetchFailed(error: unknown): boolean {
+  return error instanceof TypeError && error.message === "fetch failed";
+}
+
 function printHelp(): void {
   console.log(`Usage:
   sello dev [--port 8787] [--service service-id] [--dry-run]

package/sdks/typescript/src/sdk/service.ts

@@ -26,6 +26,8 @@ export type SelloValueOrGetter<Request, Value> =
   | Value
   | ((request: Request) => Value);
 
+export type SelloActionType<Request> = string | ((request: Request) => string);
+
 export type SelloReceiptEvent<Response = unknown> = {
   resultStatus: ResultStatus;
   receipt: BuiltReceipt;
@@ -72,6 +74,35 @@ export type SelloMcpToolOptions<Args, Response, Context = unknown> = {
   ) => Response | Promise<Response>;
 };
 
+export type SelloA2aMessageInvocation<Request, Context = unknown> = {
+  request: Request;
+  context: Context;
+};
+
+export type SelloA2aMessageHandler<Request, Response, Context = unknown> = (
+  request: Request,
+  context: Context,
+) => Response | Promise<Response>;
+
+export type SelloA2aMessageOptions<Request, Response, Context = unknown> = {
+  actionType?: SelloActionType<SelloA2aMessageInvocation<Request, Context>>;
+  authorizationToken?: SelloValueOrGetter<
+    SelloA2aMessageInvocation<Request, Context>,
+    string | Uint8Array
+  >;
+  canonicalizeInput?: (
+    invocation: SelloA2aMessageInvocation<Request, Context>,
+  ) => Uint8Array;
+  canonicalizeOutput?: (response: Response) => Uint8Array;
+  canonicalizeError?: (error: unknown) => Uint8Array;
+  isDenied?: (
+    invocation: SelloA2aMessageInvocation<Request, Context>,
+  ) => boolean | Promise<boolean>;
+  deniedResponse?: (
+    invocation: SelloA2aMessageInvocation<Request, Context>,
+  ) => Response | Promise<Response>;
+};
+
 export type SelloServiceConfig = {
   service?: string;
   serviceKey?: ServiceKeyInput;
@@ -101,6 +132,10 @@ export type SelloReceipts = {
     handler: SelloMcpToolHandler<Args, Response, Context>,
     options?: SelloMcpToolOptions<Args, Response, Context>,
   ): SelloMcpToolHandler<Args, Response, Context>;
+  a2aMessage<Request, Response, Context = unknown>(
+    handler: SelloA2aMessageHandler<Request, Response, Context>,
+    options?: SelloA2aMessageOptions<Request, Response, Context>,
+  ): SelloA2aMessageHandler<Request, Response, Context>;
   flush(): Promise<void>;
 };
 
@@ -151,11 +186,14 @@ export function createSelloService(input?: SelloServiceInput): SelloReceipts {
   }
 
   function wrapTool<Request, Response>(
-    actionType: string,
+    actionType: SelloActionType<Request>,
     handler: SelloToolHandler<Request, Response>,
     options: SelloToolOptions<Request, Response> = {},
   ): SelloToolHandler<Request, Response> {
-    if (typeof actionType !== "string" || actionType.length === 0) {
+    if (
+      (typeof actionType === "string" && actionType.length === 0) ||
+      (typeof actionType !== "string" && typeof actionType !== "function")
+    ) {
       throw new TypeError("Sello action type must be a non-empty string");
     }
 
@@ -175,6 +213,7 @@ export function createSelloService(input?: SelloServiceInput): SelloReceipts {
         resolved.fallbackSelloLogs,
         resolved.log.logUrl,
       );
+      const resolvedActionType = resolveActionType(actionType, request);
       const base = {
         authorizationTokenBytes: verifiedToken.authorizationTokenBytes,
         ownerHpkePublicKey: verifiedToken.ownerHpkePublicKey,
@@ -183,7 +222,7 @@ export function createSelloService(input?: SelloServiceInput): SelloReceipts {
         servicePrivateKey: resolved.servicePrivateKey,
         serviceIdentifier: resolved.service,
         logUrl: resolved.log.logUrl,
-        actionType,
+        actionType: resolvedActionType,
         actionInputBytes: (options.canonicalizeInput ?? canonicalJsonBytes)(request),
         timestamp: resolved.now(),
       };
@@ -272,6 +311,32 @@ export function createSelloService(input?: SelloServiceInput): SelloReceipts {
         return await wrapped({ name, arguments: args, context });
       };
     },
+    a2aMessage<Request, Response, Context = unknown>(
+      handler: SelloA2aMessageHandler<Request, Response, Context>,
+      options: SelloA2aMessageOptions<Request, Response, Context> = {},
+    ): SelloA2aMessageHandler<Request, Response, Context> {
+      const wrapped = wrapTool<
+        SelloA2aMessageInvocation<Request, Context>,
+        Response
+      >(
+        options.actionType ?? defaultA2aActionType,
+        async (invocation) => handler(invocation.request, invocation.context),
+        {
+          authorizationToken:
+            options.authorizationToken ?? defaultA2aAuthorizationToken,
+          canonicalizeInput:
+            options.canonicalizeInput ?? defaultA2aCanonicalizeInput,
+          canonicalizeOutput: options.canonicalizeOutput,
+          canonicalizeError: options.canonicalizeError,
+          isDenied: options.isDenied,
+          deniedResponse: options.deniedResponse,
+        },
+      );
+
+      return async (request: Request, context: Context): Promise<Response> => {
+        return await wrapped({ request, context });
+      };
+    },
     async flush(): Promise<void> {
       await publisher?.flush();
     },
@@ -588,6 +653,53 @@ function defaultMcpCanonicalizeInput(
   });
 }
 
+function defaultA2aAuthorizationToken(
+  invocation: SelloA2aMessageInvocation<unknown, unknown>,
+): string | Uint8Array {
+  const fromContext = authorizationTokenFromUnknown(invocation.context);
+  if (fromContext) {
+    return fromContext;
+  }
+
+  const fromRequest = authorizationTokenFromUnknown(invocation.request);
+  if (fromRequest) {
+    return fromRequest;
+  }
+
+  throw new TypeError(
+    "Sello A2A authorization token not found. Pass authorizationToken or include an Authorization header in the A2A context.",
+  );
+}
+
+function defaultA2aActionType(
+  invocation: SelloA2aMessageInvocation<unknown, unknown>,
+): string {
+  const method = methodFromA2aRequest(invocation.request);
+  return method ? `a2a.${method}` : "a2a.message/send";
+}
+
+function defaultA2aCanonicalizeInput(
+  invocation: SelloA2aMessageInvocation<unknown, unknown>,
+): Uint8Array {
+  if (isRecord(invocation.request) && typeof invocation.request.method === "string") {
+    return canonicalJsonBytes({
+      method: invocation.request.method,
+      params: invocation.request.params ?? null,
+    });
+  }
+
+  return canonicalJsonBytes(invocation.request);
+}
+
+function methodFromA2aRequest(request: unknown): string | undefined {
+  if (!isRecord(request)) {
+    return undefined;
+  }
+
+  const method = request.method;
+  return typeof method === "string" && method.length > 0 ? method : undefined;
+}
+
 function authorizationTokenFromUnknown(value: unknown): string | Uint8Array | undefined {
   if (!isRecord(value)) {
     return undefined;
@@ -693,6 +805,20 @@ function resolveValue<Request, Value>(
   return value;
 }
 
+function resolveActionType<Request>(
+  actionType: SelloActionType<Request>,
+  request: Request,
+): string {
+  const resolved =
+    typeof actionType === "function" ? actionType(request) : actionType;
+
+  if (typeof resolved !== "string" || resolved.length === 0) {
+    throw new TypeError("Sello action type must be a non-empty string");
+  }
+
+  return resolved;
+}
+
 function envSubmitMode(env: Environment): SubmitMode | SelloSubmitOptions | undefined {
   const mode = env.SELLO_SUBMIT_MODE;
   if (mode === undefined) {