@crewhaus/tool-message-channel 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@crewhaus/tool-message-channel",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Built-in `SendMessage` tool for cross-channel addressing (Section 12). Permission-gated; fail-closed without an explicit allow rule.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/channel-adapter-slack": "0.0.0",
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/tool-builder": "0.0.0",
+    "@crewhaus/tool-catalog": "0.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@crewhaus/permission-engine": "0.0.0",
+    "@crewhaus/tool-executor": "0.0.0",
+    "@crewhaus/tool-permission-matcher": "0.0.0",
+    "@crewhaus/tool-validate": "0.0.0"
+  },
+  "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/tool-message-channel"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/tool-message-channel#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,174 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  type ChannelAdapter,
+  type InboundEvent,
+  createSlackAdapter,
+} from "@crewhaus/channel-adapter-slack";
+import {
+  BUILTIN_DEFAULT_RULES,
+  type RuleSet,
+  emptyRuleSet,
+  evaluate,
+} from "@crewhaus/permission-engine";
+import { executeTool } from "@crewhaus/tool-executor";
+import { _resetChannelAdapters, registerChannelAdapter, sendMessage } from "./index";
+
+afterEach(() => {
+  _resetChannelAdapters();
+});
+
+function dummyAdapter(): {
+  adapter: ChannelAdapter;
+  captured: Array<{ event: InboundEvent; text: string }>;
+} {
+  const captured: Array<{ event: InboundEvent; text: string }> = [];
+  const adapter: ChannelAdapter = {
+    id: "slack",
+    verify: () => true,
+    parseInbound: () => ({ kind: "skip" }),
+    sendReply: async (a) => {
+      captured.push(a);
+    },
+    setTyping: async () => undefined,
+  };
+  return { adapter, captured };
+}
+
+describe("sendMessage tool — shape (T1)", () => {
+  test("declares destructive: true so default mode evaluates fail-closed", () => {
+    expect(sendMessage.name).toBe("SendMessage");
+    expect(sendMessage.destructive).toBe(true);
+    expect(sendMessage.readOnly).toBe(false);
+  });
+});
+
+describe("sendMessage permission gating (T8 — security)", () => {
+  test("evaluates to ASK in default mode without an explicit allow rule", () => {
+    const decision = evaluate(
+      {
+        toolName: "SendMessage",
+        input: { channel: "slack:T:C", text: "x" },
+        readOnly: false,
+        destructive: true,
+      },
+      "default",
+      { ...emptyRuleSet, builtin: BUILTIN_DEFAULT_RULES },
+    );
+    // ASK with no askApproval prompter => the runtime treats it as deny.
+    // The point is: it does NOT auto-allow. (alwaysAllow Read is in builtins
+    // but never matches SendMessage.)
+    expect(decision).toBe("ask");
+  });
+
+  test("evaluates to ASK in auto mode (destructive default)", () => {
+    const decision = evaluate(
+      { toolName: "SendMessage", input: {}, readOnly: false, destructive: true },
+      "auto",
+      { ...emptyRuleSet, builtin: BUILTIN_DEFAULT_RULES },
+    );
+    expect(decision).toBe("ask");
+  });
+
+  test("plan mode denies SendMessage outright (not readOnly)", () => {
+    const decision = evaluate(
+      { toolName: "SendMessage", input: {}, readOnly: false, destructive: true },
+      "plan",
+      { ...emptyRuleSet, builtin: BUILTIN_DEFAULT_RULES },
+    );
+    expect(decision).toBe("deny");
+  });
+
+  test("explicit alwaysAllow rule unlocks SendMessage", () => {
+    const rules: RuleSet = {
+      ...emptyRuleSet,
+      yaml: [{ type: "alwaysAllow", pattern: "SendMessage", source: "yaml" }],
+      builtin: BUILTIN_DEFAULT_RULES,
+    };
+    const decision = evaluate(
+      { toolName: "SendMessage", input: {}, readOnly: false, destructive: true },
+      "default",
+      rules,
+    );
+    expect(decision).toBe("allow");
+  });
+
+  test("alwaysDeny rule wins over alwaysAllow due to source priority", () => {
+    const rules: RuleSet = {
+      ...emptyRuleSet,
+      flag: [{ type: "alwaysDeny", pattern: "SendMessage", source: "flag" }],
+      yaml: [{ type: "alwaysAllow", pattern: "SendMessage", source: "yaml" }],
+    };
+    const decision = evaluate(
+      { toolName: "SendMessage", input: {}, readOnly: false, destructive: true },
+      "default",
+      rules,
+    );
+    expect(decision).toBe("deny");
+  });
+});
+
+describe("sendMessage execution", () => {
+  test("dispatches to the registered adapter and returns success", async () => {
+    const { adapter, captured } = dummyAdapter();
+    registerChannelAdapter("slack", adapter);
+    const result = await executeTool(
+      sendMessage,
+      { channel: "slack:T9:C7:1700000000.000", text: "hi from tool" },
+      { toolUseId: "u1" },
+    );
+    expect(result.isError).toBe(false);
+    expect(result.content).toBe("sent to slack:T9:C7:1700000000.000");
+    expect(captured).toHaveLength(1);
+    expect(captured[0]?.event.workspaceId).toBe("T9");
+    expect(captured[0]?.event.channelId).toBe("C7");
+    expect(captured[0]?.event.threadTs).toBe("1700000000.000");
+    expect(captured[0]?.text).toBe("hi from tool");
+  });
+
+  test("returns isError when no adapter is registered", async () => {
+    const result = await executeTool(
+      sendMessage,
+      { channel: "slack:T:C:1.0", text: "x" },
+      { toolUseId: "u2" },
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toMatch(/no adapter registered/);
+  });
+
+  test("returns isError on a malformed routing key", async () => {
+    const result = await executeTool(
+      sendMessage,
+      { channel: "slack-only", text: "x" },
+      { toolUseId: "u3" },
+    );
+    expect(result.isError).toBe(true);
+    expect(result.content).toMatch(/invalid channel/);
+  });
+
+  test("integrates with createSlackAdapter for end-to-end dispatch", async () => {
+    const fetchCalls: Array<{ url: string; body: string }> = [];
+    const fakeFetch: typeof fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      fetchCalls.push({
+        url: typeof input === "string" ? input : input.toString(),
+        body: typeof init?.body === "string" ? init.body : "",
+      });
+      return new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+    const adapter = createSlackAdapter(
+      { botToken: "xoxb", signingSecret: "s" },
+      { apiBaseUrl: "https://slack.test/api", fetch: fakeFetch },
+    );
+    registerChannelAdapter("slack", adapter);
+    const result = await executeTool(
+      sendMessage,
+      { channel: "slack:T:C:1.0", text: "ok" },
+      { toolUseId: "u4" },
+    );
+    expect(result.isError).toBe(false);
+    expect(fetchCalls).toHaveLength(1);
+    expect(fetchCalls[0]?.url).toBe("https://slack.test/api/chat.postMessage");
+  });
+});

package/src/index.ts

@@ -0,0 +1,105 @@
+import type { ChannelAdapter, InboundEvent } from "@crewhaus/channel-adapter-slack";
+import { CrewhausError } from "@crewhaus/errors";
+import { buildTool } from "@crewhaus/tool-builder";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { z } from "zod";
+
+/**
+ * Catalog R4 `tool-message-channel` — `SendMessage(channel, text)` for
+ * cross-channel addressing. Section 12.
+ *
+ * `channel` is an opaque routing key (the adapter id is the prefix before
+ * the first `:`, e.g. `slack:T123:C456:1700000000.000`). The tool dispatches
+ * to the matching adapter registered via `registerChannelAdapter` at boot
+ * (the codegen-emitted `daemon.ts` calls this after `createSlackAdapter`).
+ *
+ * SECURITY: declared `destructive: true` so the permission engine treats it
+ * as fail-closed in `default` mode — the agent can only invoke `SendMessage`
+ * when an explicit `alwaysAllow` rule names it. The hello-channel example
+ * documents this contract.
+ */
+export class ChannelToolError extends CrewhausError {
+  override readonly name = "ChannelToolError";
+  constructor(message: string, cause?: unknown) {
+    super("tool", message, cause);
+  }
+}
+
+const adapters = new Map<string, ChannelAdapter>();
+
+export function registerChannelAdapter(id: string, adapter: ChannelAdapter): void {
+  adapters.set(id, adapter);
+}
+
+export function getChannelAdapter(id: string): ChannelAdapter | undefined {
+  return adapters.get(id);
+}
+
+/** Test-only — clears the per-process registry between tests. */
+export function _resetChannelAdapters(): void {
+  adapters.clear();
+}
+
+/**
+ * Parse a routing key into an adapter id + the InboundEvent fields needed
+ * by `sendReply`. The format is intentionally flat and human-typeable so
+ * the model can construct routing keys from prior tool results.
+ *
+ * Slack format: `slack:<workspaceId>:<channelId>[:<threadTs>]`
+ * Future channels follow the same shape under their own adapter id.
+ */
+function parseRoutingKey(channel: string): { adapterId: string; event: InboundEvent } {
+  const parts = channel.split(":");
+  if (parts.length < 3) {
+    throw new ChannelToolError(
+      `SendMessage: invalid channel "${channel}" — expected "<adapterId>:<workspaceId>:<channelId>[:<threadTs>]"`,
+    );
+  }
+  const adapterId = parts[0] ?? "";
+  const workspaceId = parts[1] ?? "";
+  const channelId = parts[2] ?? "";
+  const threadTs = parts[3];
+  return {
+    adapterId,
+    event: {
+      idempotencyKey: `synthetic_${Date.now()}`,
+      workspaceId,
+      channelId,
+      userId: "<bot>",
+      ...(threadTs !== undefined ? { threadTs } : {}),
+      ts: threadTs ?? "0",
+      text: "",
+      subtype: "message" as const,
+    },
+  };
+}
+
+const sendMessageSchema = z.object({
+  channel: z.string().min(1),
+  text: z.string().min(1),
+});
+
+export const sendMessage: RegisteredTool = buildTool({
+  name: "SendMessage",
+  description:
+    'Send a message to a channel/thread/DM identified by a routing key (e.g. "slack:T123:C456:1700000000.000"). Permission-gated.',
+  inputSchema: sendMessageSchema,
+  destructive: true,
+  // Pillar 3 sink-side: channel send is the textbook lateral-comm sink.
+  // egress-classifier scans the `text` payload for cross-origin lineage.
+  scope: "external",
+  // Pillar 3 intent gate: sending a message is irreversible-ish and visible
+  // to humans on the other end, so demand justification.
+  requireJustification: true,
+  execute: async (input) => {
+    const { adapterId, event } = parseRoutingKey(input.channel);
+    const adapter = getChannelAdapter(adapterId);
+    if (!adapter) {
+      throw new ChannelToolError(
+        `SendMessage: no adapter registered for "${adapterId}" — known: [${[...adapters.keys()].join(", ") || "<none>"}]`,
+      );
+    }
+    await adapter.sendReply({ event, text: input.text });
+    return `sent to ${input.channel}`;
+  },
+});