@crewhaus/a2a-protocol 0.1.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@crewhaus/a2a-protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "In-crew agent-to-agent SendMessage tool with traceparent envelopes (Section 22)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/agent-context-isolation": "0.0.0",
+    "@crewhaus/tool-builder": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "@crewhaus/trace-event-bus": "0.0.0",
+    "zod": "^3.23.8"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/a2a-protocol"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/a2a-protocol#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "bun:test";
+import type { CrewMailbox } from "@crewhaus/agent-context-isolation";
+import { isValidSpanId, isValidTraceId, parseTraceparent } from "@crewhaus/trace-event-bus";
+import { type A2AEnvelope, buildEnvelope, createSendMessageA2ATool } from "./index.js";
+
+function makeMailbox(
+  roles: string[],
+  onSend?: (to: string, payload: string) => string,
+): CrewMailbox {
+  return {
+    knownRoles: roles,
+    currentRole: () => roles[0] ?? "",
+    currentTraceparent: () => "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+    requestHandoff: () => {
+      throw new Error("not used in this test");
+    },
+    sendA2A: async (to, payload) => (onSend ? onSend(to, payload) : `<<reply from ${to}>>`),
+  };
+}
+
+describe("createSendMessageA2ATool", () => {
+  test("delivers payload to peer and returns peer's reply verbatim", async () => {
+    let capturedTarget: string | undefined;
+    let capturedPayload: string | undefined;
+    const mailbox = makeMailbox(["critic", "researcher"], (to, payload) => {
+      capturedTarget = to;
+      capturedPayload = payload;
+      return "the answer is 42";
+    });
+    const tool = createSendMessageA2ATool({ from: "critic", targets: ["critic", "researcher"] });
+
+    const result = await tool.execute(
+      { target: "researcher", payload: "what is the answer?", kind: "question" },
+      { bridge: { crewMailbox: mailbox } as never },
+    );
+
+    expect(capturedTarget).toBe("researcher");
+    expect(capturedPayload).toBe("what is the answer?");
+    expect(result).toBe("the answer is 42");
+  });
+
+  test("refuses self-message", async () => {
+    const mailbox = makeMailbox(["solo"]);
+    const tool = createSendMessageA2ATool({ from: "solo", targets: ["solo"] });
+
+    const result = await tool.execute(
+      { target: "solo", payload: "hi me" },
+      { bridge: { crewMailbox: mailbox } as never },
+    );
+
+    expect(result).toContain("cannot send a message to yourself");
+  });
+
+  test("refuses unknown peer with helpful list", async () => {
+    const mailbox = makeMailbox(["a", "b"]);
+    const tool = createSendMessageA2ATool({ from: "a", targets: ["a", "b"] });
+
+    const result = await tool.execute(
+      { target: "c", payload: "hi" },
+      { bridge: { crewMailbox: mailbox } as never },
+    );
+
+    expect(result).toContain('unknown peer "c"');
+    expect(result).toContain("a");
+    expect(result).toContain("b");
+  });
+
+  test("returns clean error when no bridge / no mailbox is present", async () => {
+    const tool = createSendMessageA2ATool({ from: "x", targets: ["x", "y"] });
+
+    const r1 = await tool.execute({ target: "y", payload: "hi" }, {});
+    expect(r1).toContain("crew mailbox is not available");
+
+    const r2 = await tool.execute({ target: "y", payload: "hi" }, { bridge: {} as never });
+    expect(r2).toContain("crew mailbox is not available");
+  });
+
+  test("flag profile: read-only, not destructive, classifier enabled", () => {
+    const tool = createSendMessageA2ATool({ from: "a", targets: ["a", "b"] });
+    expect(tool.readOnly).toBe(true);
+    expect(tool.destructive).toBe(false);
+    // Default true — peer text could carry attacker-supplied content.
+    expect(tool.classifyOutput).toBe(true);
+  });
+});
+
+describe("buildEnvelope", () => {
+  test("packs all wire fields with default kind=question", () => {
+    const env: A2AEnvelope = buildEnvelope({
+      from: "critic",
+      to: "researcher",
+      payload: "where did the data come from?",
+      traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+    });
+
+    expect(env.from).toBe("critic");
+    expect(env.to).toBe("researcher");
+    expect(env.kind).toBe("question");
+    expect(env.payload).toBe("where did the data come from?");
+    expect(env.traceparent).toBe("00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01");
+  });
+
+  test("traceparent parses to a valid W3C trace context (T9 envelope invariant)", () => {
+    const env = buildEnvelope({
+      from: "a",
+      to: "b",
+      payload: "hi",
+      traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01",
+    });
+    const parsed = parseTraceparent(env.traceparent);
+    expect(parsed).not.toBeNull();
+    expect(parsed && isValidTraceId(parsed.traceId)).toBe(true);
+    expect(parsed && isValidSpanId(parsed.parentSpanId)).toBe(true);
+  });
+});

package/src/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Catalog R5 `a2a-protocol` — Section 22.
+ *
+ * In-crew agent-to-agent peer messaging. Distinct from Section 12's
+ * channel-bot `SendMessage` (which posts to Slack/etc.) — this one routes
+ * INSIDE the crew via the orchestrator's mailbox.
+ *
+ * Wire shape (the Google A2A inspiration):
+ *   { from, to, kind, payload, traceparent }
+ *
+ * `traceparent` is the W3C trace-context header. The orchestrator's
+ * mailbox stamps it from the bus's `currentTraceparent()` so subscribers
+ * see every A2A message under the same trace id, even when the
+ * receiving role's `runChatLoop` opens its own spans. The crew's OTel
+ * exporter therefore stitches every role's spans into one trace.
+ *
+ * The tool itself is synchronous-from-the-sender's-POV: `SendMessage`
+ * waits for the target role's reply and returns it as the tool result
+ * so the sender's model can continue its turn with the answer in hand.
+ */
+import type { CrewMailbox, RuntimeBridge } from "@crewhaus/agent-context-isolation";
+import { buildTool } from "@crewhaus/tool-builder";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+
+/** Wire envelope an A2A SendMessage produces. */
+export type A2AEnvelope = {
+  readonly from: string;
+  readonly to: string;
+  readonly kind: A2AMessageKind;
+  readonly payload: string;
+  readonly traceparent: string;
+};
+
+export type A2AMessageKind = "question" | "answer" | "notify";
+
+export type CreateSendMessageA2AToolOptions = {
+  readonly from: string;
+  readonly targets: ReadonlyArray<string>;
+};
+
+const inputSchemaTemplate = z
+  .object({
+    target: z
+      .string()
+      .min(1)
+      .describe("Role name to message — must be a peer in this crew, not yourself."),
+    payload: z
+      .string()
+      .min(1)
+      .describe(
+        "The question or notification you want to send. The peer agent runs once with this as its input and returns a single reply string.",
+      ),
+    kind: z
+      .enum(["question", "answer", "notify"])
+      .optional()
+      .describe(
+        "Optional message classifier. Defaults to 'question'. Used by trace subscribers to colour-code A2A flows; semantically a no-op.",
+      ),
+  })
+  .strict();
+
+/**
+ * Build the description with the live target list so the model sees
+ * which peers are actually addressable.
+ */
+function describe(opts: CreateSendMessageA2AToolOptions): string {
+  const others = opts.targets.filter((t) => t !== opts.from);
+  if (others.length === 0) {
+    return "Ask a peer agent in this crew a question and receive its reply. (No other roles defined — calling SendMessage will return an error.)";
+  }
+  return `Ask a peer agent in this crew a question and receive its reply synchronously. Use this when you need a brief, focused response from another role WITHOUT yielding control. The peer runs one turn with your payload as input and returns a single reply. Available peers: ${others.join(", ")}.`;
+}
+
+export function createSendMessageA2ATool(opts: CreateSendMessageA2AToolOptions): RegisteredTool {
+  return buildTool({
+    name: "SendMessage",
+    description: describe(opts),
+    inputSchema: inputSchemaTemplate,
+    concurrencySafe: false,
+    readOnly: true,
+    destructive: false,
+    // The peer reply is model-generated text — keep the post-tool
+    // injection classifier on (default) so prompt-injection hidden in a
+    // peer's response is caught.
+    execute: async (input, ctx) => {
+      const bridge = ctx?.bridge as RuntimeBridge | undefined;
+      const mailbox: CrewMailbox | undefined = bridge?.crewMailbox;
+      if (mailbox === undefined) {
+        return "[A2A error] crew mailbox is not available — SendMessage can only be invoked from inside a crew-orchestrator turn.";
+      }
+      if (input.target === opts.from) {
+        return `[A2A error] cannot send a message to yourself ("${opts.from}").`;
+      }
+      if (!mailbox.knownRoles.includes(input.target)) {
+        return `[A2A error] unknown peer "${input.target}". Known peers: ${mailbox.knownRoles.join(", ")}.`;
+      }
+      try {
+        const reply = await mailbox.sendA2A(input.target, input.payload);
+        return reply;
+      } catch (err) {
+        return `[A2A error] ${(err as Error).message ?? String(err)}`;
+      }
+    },
+  });
+}
+
+/**
+ * Compose a wire envelope from raw fields. Exported so the orchestrator
+ * (which actually emits the trace event) can build a consistent object
+ * shape; tests also use it to assert envelope structure.
+ */
+export function buildEnvelope(args: {
+  from: string;
+  to: string;
+  kind?: A2AMessageKind;
+  payload: string;
+  traceparent: string;
+}): A2AEnvelope {
+  return {
+    from: args.from,
+    to: args.to,
+    kind: args.kind ?? "question",
+    payload: args.payload,
+    traceparent: args.traceparent,
+  };
+}
+
+export { createSendMessageA2ATool as default };