@oneie/claude 0.6.0 → 0.8.0

package/skills/mcp/SKILL.md

@@ -1,242 +1,272 @@
+---
+name: mcp
+description: Add or change a tool in @oneie/mcp — the MCP server exposing ONE to Claude Desktop, Cursor, and any MCP client. Use when adding an MCP tool, editing anything under packages/mcp/src/tools/, writing a tool inputSchema, fixing MCP_TOOLS manifest drift when `bun run check:tools` fails, or deciding whether a new capability needs a tool at all (usually it does not — signal/ask already reach every receiver). Triggers — "add an MCP tool", "new tool for the MCP server", "check:tools is failing", "MCP_TOOLS drift", "expose X to Claude Desktop", "wire the oneie MCP server".
+---
+
 # MCP tools — Model Context Protocol for agents
 
-MCP tools give agents programmatic access to ONE capabilities. They're scaffolded, typed, and auto-discovered.
+MCP tools give agents programmatic access to ONE capabilities. Each tool is a
+plain object registered on a router; the router is served over stdio.
 
 ## Structure
 
 ```
 packages/mcp/
 ├── src/
-│   ├── index.ts              # MCP server entrypoint
-│   ├── tools/                # tool implementations
-│   │   ├── index.ts          # tool registry + re-exports
-│   │   ├── chat/             # chat-related tools
-│   │   │   ├── index.ts
-│   │   │   └── memory.ts
-│   │   └── {domain}/
-│   │       ├── index.ts
-│   │       └── {action}.ts
-│   └── schema.ts             # Zod schemas for tool inputs
+│   ├── index.ts    # createOneRouter() + MCP_TOOLS + bin
+│   ├── serve.ts    # McpTool, McpRouter, apiCall(), serve()
+│   ├── env.ts      # readEnv() → { baseUrl, apiKey }
+│   ├── telemetry.ts
+│   └── tools/      # one file per group: <group>Tools()
+│       ├── substrate.ts     # 6 verbs + dims (locked)
+│       ├── lifecycle.ts     # agents, skills, pay
+│       ├── observability.ts # stats, health, export
+│       ├── discovery · social · video · broadcast
+│       ├── messaging · seo · views · workflow · tasks
+│       └── fn.ts            # generated per allowlisted fn
 ```
 
+There is no `src/schema.ts` and no per-domain subdirectory — a tool group is one
+flat file exporting one `<group>Tools(): McpTool[]` function.
+
 ## Pattern: Adding an MCP tool
 
-### 1. Define the schema (input + output types)
+**First ask whether you need one.** `signal` and `ask` address any receiver by
+name — the registry declares 273 of them today. (The registry is the capability
+*catalog*; a receiver is only reachable once a handler is bound in
+`world-receivers.ts` or a channels tool module. A declared-but-unbound name
+type-checks and 404s.) A new product action needs a receiver, not a tool.
+The documented exceptions (`views.ts`, `workflow.ts`, `tasks.ts`) exist because
+those are first-class product objects other clients address by name — and even
+they add no new receiver, they route through the `/api/ask` door.
 
-```typescript
-// packages/mcp/src/schema.ts
-import { z } from 'zod';
+### 1. Define the input schema (raw JSON Schema, not Zod)
 
-export const memoryToolSchema = z.object({
-  groupId: z.string().describe('Group ID'),
-  content: z.string().describe('Memory content to store'),
-});
+`McpTool.inputSchema` is `Record<string, unknown>` and is handed to the MCP
+client verbatim. Zod is an SDK dependency, not an MCP one.
 
-export type MemoryToolInput = z.infer<typeof memoryToolSchema>;
+```typescript
+// inside packages/mcp/src/tools/broadcast.ts
+const inputSchema = {
+  type: "object",
+  properties: {
+    broadcastId: { type: "string" },
+  },
+  required: ["broadcastId"],
+};
 ```
 
 ### 2. Implement the tool
 
 ```typescript
-// packages/mcp/src/tools/chat/memory.ts
-import { SubstrateClient } from '@oneie/sdk';
-import { memoryToolSchema, MemoryToolInput } from '../schema';
-
-export async function memoryTool(input: MemoryToolInput): Promise<string> {
-  const client = new SubstrateClient();
-  const memory = await client.memory(input.groupId);
-  
-  if (!memory) {
-    return 'No memory found for this group.';
-  }
-  
-  return JSON.stringify(memory);
+// packages/mcp/src/tools/broadcast.ts
+import { apiCall, type McpTool } from "../serve.js";
+
+function ask(env: { baseUrl: string; apiKey?: string }, receiver: string, data: unknown) {
+  return apiCall(env.baseUrl, env.apiKey, `/api/ask/${encodeURIComponent(receiver)}`, {
+    method: "POST",
+    body: JSON.stringify({ data }),
+  });
 }
 
-export const MEMORY_TOOL = {
-  name: 'memory',
-  description: 'Read or write group memory',
-  inputSchema: memoryToolSchema,
-  execute: memoryTool,
-};
+export function broadcastTools(): McpTool[] {
+  return [
+    {
+      name: "broadcast_send",
+      description: "Send a broadcast now (inline drain, suppression-checked).",
+      inputSchema: {
+        type: "object",
+        properties: { broadcastId: { type: "string" } },
+        required: ["broadcastId"],
+      },
+      handler: async (args, env) => ask(env, "broadcast:send", args),
+    },
+  ];
+}
 ```
 
 **Rules:**
-- Schema first (using Zod)
-- Function receives typed input
-- Function returns string (MCP protocol requirement)
-- Tool object has name, description, inputSchema, execute
-- Tool calls SDK methods, never direct HTTP/DB
-
-### 3. Register the tool
+- The tool shape is exactly `{ name, description, inputSchema, handler }` —
+  the field is `handler`, not `execute`
+- `handler(args, env)` receives `Record<string, unknown>` and the `readEnv()`
+  result; it returns `Promise<unknown>` — **not** a string. Return the parsed
+  JSON body; the transport serialises it
+- Tools call `apiCall(env.baseUrl, env.apiKey, path, init)` from `serve.ts`.
+  They do **not** construct a `SubstrateClient` — the SDK import in this package
+  is for the `RECIPES` contract catalog, not for transport
+- Every receiver a tool wraps must be a real key in `@oneie/sdk/receivers`
+- `apiCall` throws with the response body on a non-2xx, so the API's structured
+  error (`{error, field, expected, got, hint}`) reaches the agent. Let it throw
+
+### 3. Register the tool — in two places
 
 ```typescript
-// packages/mcp/src/tools/chat/index.ts
-export { MEMORY_TOOL } from './memory';
-export * as chatTools from './index';
-
-// packages/mcp/src/tools/index.ts
-import * as chatTools from './chat';
-export const TOOLS = [
-  chatTools.MEMORY_TOOL,
-  // other tools
-] as const;
-
 // packages/mcp/src/index.ts
-import { TOOLS } from './tools';
+export function createOneRouter() {
+  const router = createRouter();
+  for (const tool of [...substrateTools(), ...broadcastTools(), /* … */]) {
+    router.register(tool);
+  }
+  return router;
+}
 
-export const mcpServer = {
-  tools: TOOLS,
-  // other MCP config
+export const MCP_TOOLS = {
+  broadcast: ["broadcast_create", "broadcast_list", "broadcast_get",
+              "broadcast_send", /* … */] as const,
 };
 ```
 
-### 4. Test the tool
+`MCP_TOOLS` is hand-maintained and drifts. `toolManifestDrift()` diffs the
+manifest against the live router; `fn_*` is excluded by design because those are
+generated at runtime from `FN_MAP`.
 
-```typescript
-// packages/mcp/test/chat.memory.test.ts
-describe('Memory tool', () => {
-  it('returns memory for a group', async () => {
-    const result = await memoryTool({ groupId: 'group-123', content: 'test' });
-    expect(result).toContain('memory');
-  });
+### 4. Check and test
 
-  it('returns error message when no memory', async () => {
-    const result = await memoryTool({ groupId: 'nonexistent', content: 'test' });
-    expect(result).toContain('No memory');
-  });
+```bash
+cd packages/mcp && bun run check:tools
+# builds, then reports "MCP_TOOLS matches the router" or exits 1 with the diff
+```
 
-  it('validates input schema', () => {
-    expect(() => {
-      memoryToolSchema.parse({ groupId: 'g1' });  // missing content
-    }).toThrow();
-  });
-});
+There is no vitest suite in `packages/mcp` — `check:tools` and `bun run
+typecheck` are the gates. Exercise a tool end-to-end through a live client:
+
+```bash
+claude mcp add oneie -e ONEIE_API_KEY=one-<key> -- npx -y @oneie/mcp
 ```
 
 ## Naming conventions
 
-**Tool names:** kebab-case, verb-noun
-- ✓ `read-memory`, `create-task`, `list-actors`
-- ✗ `Memory`, `CREATE_TASK`, `list_actors` (inconsistent)
+**Tool names:** snake_case, `group_verb`
+- Correct: `broadcast_send`, `tasks_list`, `chat_send`, `workflow_run`
+- Wrong: `send-broadcast`, `Memory`, `CREATE_TASK` (nothing shipped uses kebab or caps)
+- The universal verbs are the bare exception — `signal`, `ask`, `mark`, `warn`,
+  `fade`, `follow` keep the locked verb name with no prefix
 
-**Tool descriptions:** one sentence, agent-perspective
-- ✓ "Read or write group memory" (what agent can do)
-- ✗ "Calls the memory API" (implementation detail)
+**Tool descriptions:** one sentence, agent-perspective, and say what comes back
+- Correct: "Send a broadcast now (inline drain, suppression-checked)."
+- Correct: "Get one broadcast by id. Returns { broadcast }."
+- Wrong: "Calls the broadcast API" (implementation detail, no return shape)
 
-**Input fields:** snake_case, self-documenting
-- ✓ `groupId`, `taskTitle`, `memberEmails`
-- ✗ `gid`, `t`, `e` (unclear)
+**Input fields:** match the receiver's zod request field-for-field
+- The handler forwards `args` straight through, so a renamed field is a silent
+  400. `broadcast:send` takes `broadcastId`; the tool takes `broadcastId`
 
 ## Tool categories
 
 | Category | Purpose | Example |
 |----------|---------|---------|
-| **Read** | Fetch data without side effects | `read-memory`, `list-tasks` |
-| **Create** | Add new entity | `create-task`, `create-group` |
-| **Update** | Modify existing entity | `update-memory`, `complete-task` |
-| **Delete** | Remove entity (rare) | `delete-task` |
-| **Execute** | Run an action with side effects | `send-message`, `approve-request` |
+| **Universal** | Reach any receiver by name | `signal`, `ask` |
+| **Read** | Fetch data without side effects | `broadcast_list`, `tasks_list`, `stats` |
+| **Create** | Add new entity | `broadcast_create`, `tasks_create`, `create_view` |
+| **Update** | Modify existing entity | `newsletter_update`, `tasks_status` |
+| **Delete** | Remove entity (rare) | `delete_room`, `unpublish_agent` |
+| **Execute** | Run an action with side effects | `broadcast_send`, `chat_send`, `workflow_run` |
 
 ## Anti-patterns
 
-❌ **Tool with no schema**
+**A new tool for a new product action**
 ```typescript
-// WRONG
-export const memoryTool = async (input: any) => { ... };
+// WRONG — a receiver already reaches this
+{ name: "commend_agent", handler: (a, e) => ask(e, "agents:commend", a) }
+```
+**Fix:** Let the agent call `signal` with `receiver: "agents:commend"`. Only add
+a tool for a first-class object clients address by name, and document why.
+
+**Zod in inputSchema**
+```typescript
+// WRONG — inputSchema is raw JSON Schema
+inputSchema: z.object({ broadcastId: z.string() })
 ```
-**Fix:** Define Zod schema, use typed input.
+**Fix:** Write the JSON Schema object literal, or derive it from the receiver
+with `ask("meta:schema", { receiver })`.
 
-❌ **Tool calls HTTP directly**
+**Returning a hand-serialised string**
 ```typescript
 // WRONG
-async function memoryTool(input: MemoryToolInput) {
-  const res = await fetch('/api/memory', { body: JSON.stringify(input) });
-  return res.text();
-}
+handler: async (args, env) => JSON.stringify(await ask(env, "broadcast:get", args))
 ```
-**Fix:** Use SDK client: `const client = new SubstrateClient(); client.memory(...)`
+**Fix:** Return the value. `handler` is `Promise<unknown>`; double-encoding
+gives the agent a string it has to re-parse.
 
-❌ **Tool without description**
+**Tool builds its own fetch**
 ```typescript
 // WRONG
-const MEMORY_TOOL = {
-  name: 'memory',
-  inputSchema: memoryToolSchema,
-  execute: memoryTool,
-};
+const res = await fetch(`${base}/api/ask/broadcast:send`, { … });
+return res.json();
+```
+**Fix:** Use `apiCall()` — it sets Accept/Content-Type/Authorization, handles
+204, and surfaces the structured error body on failure.
+
+**Registered in the router but not in MCP_TOOLS**
+```typescript
+// WRONG — check:tools exits 1 with "missing: [ 'broadcast_send' ]"
+router.register(broadcastSendTool);  // and nothing added to the manifest
 ```
-**Fix:** Add description for agent context.
+**Fix:** Add the name to its `MCP_TOOLS` group in the same edit.
 
-❌ **Tool that modifies global state**
+**Tool that modifies global state**
 ```typescript
 // WRONG
-let cachedMemory: any;
-export async function memoryTool(input: MemoryToolInput) {
-  cachedMemory = await client.memory(input.groupId);  // cache is a bug
-  return JSON.stringify(cachedMemory);
-}
+let cached: unknown;
+handler: async (args, env) => (cached ??= await ask(env, "broadcast:list", args))
 ```
 **Fix:** No caching in tools. Each invocation is independent.
 
 ## Composability rules
 
-**New tool composes SDK methods:**
+**New tool wraps an existing receiver:**
 ```typescript
-// GOOD — reuses existing SDK
-async function createTaskTool(input: CreateTaskInput) {
-  const client = new SubstrateClient();
-  const task = await client.createTask(input);  // SDK handles DB, validation
-  return JSON.stringify(task);
+// GOOD — the receiver owns validation, authority, and persistence
+{
+  name: "segment_preview",
+  description:
+    "Preview an audience segment definition — live count + up to 10 sample " +
+    "addresses (read-only). Pass a SegmentDef ({all,any?}), not an id.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      definition: { type: "object", description: "SegmentDef {all: SegmentRule[], any?: SegmentRule[]}" },
+      channel: { type: "string", enum: ["email", "sms", "whatsapp"] },
+    },
+    required: ["definition"],
+  },
+  handler: async (args, env) => ask(env, "segment:preview", args),
 }
 ```
 
-**New tool creates novel capability:**
+**New tool is generated from a catalog:**
 ```typescript
-// GOOD — when no SDK method exists yet
-async function analyzeMemoryTool(input: AnalyzeMemoryInput) {
-  const client = new SubstrateClient();
-  const memory = await client.memory(input.groupId);
-  // Analysis logic (not in SDK, because it's agent-specific)
-  const analysis = analyzeForSentiment(memory.content);
-  return JSON.stringify(analysis);
-}
+// GOOD — fn.ts builds one tool per FN_ALLOWLIST entry (20 today) from
+// @oneie/sdk/generated/fn-map, all routing through ask("fn:run"). Extending the
+// surface means allowlisting the fun in @oneie/sdk/fn-allowlist — one edit
+// reaches web, MCP, CLI, and channels. Never hand-write an fn_* tool.
 ```
 
 ## Error handling
 
 ```typescript
-export async function memoryTool(input: MemoryToolInput): Promise<string> {
-  try {
-    const client = new SubstrateClient();
-    const memory = await client.memory(input.groupId);
-    
-    if (!memory) {
-      return 'No memory found for this group. Create one first.';
-    }
-    
-    return JSON.stringify(memory);
-  } catch (error) {
-    if (error instanceof ValidationError) {
-      return `Invalid input: ${error.message}`;
-    }
-    if (error instanceof AuthenticationError) {
-      return 'You do not have permission to access this memory.';
-    }
-    throw error;  // Let parent handle unexpected errors
+handler: async (args, env) => {
+  const res = await ask(env, "broadcast:get", args) as { broadcast?: unknown };
+  if (!res.broadcast) {
+    return { ok: false, error: "not_found", hint: "Call broadcast_list for valid ids." };
   }
+  return res;
 }
 ```
 
 **Rules:**
-- Validate input (Zod does this for you)
-- Return user-facing error messages (not stack traces)
-- Don't catch unexpected errors (let them propagate)
-- Never expose sensitive data (API keys, DB queries) in error messages
+- Let `apiCall` throw on a non-2xx — its message already carries the API's
+  structured detail, which is what an agent self-corrects from
+- Return an error *shape* (`{ ok: false, error, hint }`) for domain-empty cases
+  the API considers a legitimate 200
+- Never expose the API key, raw TypeQL, or a stack trace in a returned value
+- Don't validate what the receiver already validates — the zod contract runs
+  server-side before dispatch
 
 ## See also
 
-- `packages/mcp/CLAUDE.md` — MCP development guide
-- `packages/sdk/src/receivers.ts` — receiver registry (every tool calls a receiver)
-- `text/receiver-names-shipped-vs-spec.md` — which receivers exist
+- `packages/mcp/CLAUDE.md` — the tool-file map, wiring, and the base-URL trap
+- `packages/mcp/src/serve.ts` — `McpTool`, `McpRouter`, `apiCall`
+- `packages/sdk/src/receivers.ts` — receiver registry (every tool wraps a receiver)
+- `text/signals-catalog.md` — the generated namespace map
 - `@modelcontextprotocol/sdk` — MCP protocol docs

package/skills/promise-make/SKILL.md

@@ -50,7 +50,7 @@ What the resolver does (so you don't re-do it): inserts the D1 `promises` row (s
 ## Process
 
 1. **Extract the terms.** One sentence of what will be true. If the ask is fuzzy, tighten it with the maker before emitting — frozen fuzz is worse than no promise.
-2. **Extract the ONE proof.** Ask: "what single check settles this?" If the answer is "well, A and B" → two promises. If the answer is "you'll know it when you see it" → refuse, with the reason stated.
+2. **Extract the ONE proof.** Ask: "what single check settles this?" If the answer is "well, A and B" → two promises. If the answer is "you'll know it when you see it" → refuse, with the reason stated. The check should be *false right now* (covenant clause 3, red before green) — a proof that already passes means the thing is already built, or the proof is too weak to gate anything. The resolver does not enforce this; you do.
 3. **Classify the proof rail.** Shell-shaped → tell the maker it settles at PROVE via CLI, not via `promise:settle`. Runtime-checkable → `promise:settle` works.
 4. **Pick the slug.** Kebab, stable, matches `^[a-zA-Z0-9_:/-]{1,128}$`. It becomes the path endpoint `promise:<slug>→proof` — choose like it's permanent, because it is.
 5. **Emit** `signal("promise:make", { slug, terms, proof })` — authenticated (the session's `ctx.ownerSlug` becomes the maker who alone may settle).
@@ -90,4 +90,4 @@ Counter-example (must refuse): *"Promise we'll make the client happy."* → No o
 - Receiver source: `one.ie/web/src/lib/resolvers/promises.ts` (`make`, lines 36–67)
 - Agent briefing (payloads, errors, recovery): `text/promise-signals-agents-docs.md`
 - The contract this skill serves: `text/promise-signals.md` (`world.skills` names this skill)
-- Build-time twin: `/do` PROMISE stage + `text/template-feature.md` (contract: block)
+- Build-time twin: `/do` PROMISE stage + `text/template-feature.md` (contract: block). "Never update the terms" is this rail's rule — a D1 row inert after `ON CONFLICT DO NOTHING`. The build-time rail differs: a *kept* `text/<slug>.md` promise grows, appending a follow-on deliverable whose `accept:` is already green and extending the `proof:` join (`.claude/rules/documentation.md` § "Promises grow with delivery"). Green-only and additive there; frozen here.