@brightbeamai/chap-coordinator-mcp 0.3.4 → 0.3.5

package/dist/cli.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
+import { mkdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { Coordinator } from "@brightbeamai/chap-coordinator";
 
@@ -9,7 +12,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
-  ErrorCode as ErrorCode2
+  ErrorCode as ErrorCode3
 } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 
@@ -78,6 +81,18 @@ var SCHEMAS = {
         enum: ["shadow", "trial", "production"],
         default: "production",
         description: "Highest mode a task in this workspace may request. A task.create above the ceiling is refused with -32040. The ceiling can be changed afterwards with chap.control.set_mode_ceiling."
+      },
+      join_policy: {
+        type: "string",
+        enum: ["open", "invite"],
+        default: "open",
+        description: "Who may join. 'open' admits anyone. 'invite' admits only a participant an admin invited with chap.workspace.invite, and the workspace's first member, which becomes its admin; any other join is refused with -32011. It cannot be changed afterwards."
+      },
+      review_rule: {
+        type: "string",
+        pattern: "^(any_one_approves|all_approve|quorum:[1-9][0-9]*)$",
+        default: "any_one_approves",
+        description: "The rule of every review that task.complete opens here: any_one_approves, all_approve or quorum:<n>. An author cannot open a review of their own review-required task, so this is how a workspace asks for more than one approval. It cannot be changed afterwards."
       }
     },
     additionalProperties: false
@@ -99,6 +114,26 @@ var SCHEMAS = {
     },
     required: ["workspace", "profiles"]
   },
+  "chap.workspace.invite": {
+    type: "object",
+    properties: {
+      workspace: WORKSPACE_ID,
+      from: { ...PARTICIPANT_URI, description: "The admin who invites. Any other sender is refused with -32011." },
+      uri: { ...PARTICIPANT_URI, description: "The participant invited. Its scheme must name type, as at a join." },
+      type: {
+        type: "string",
+        enum: ["human", "agent", "service"],
+        description: "The kind of participant invited, which the scheme of uri must name. The member takes this type. group: and workspace: URIs name address scopes, which cannot join, and are refused with -32602."
+      },
+      role: { type: "string", description: "The role the member takes when it joins, whatever role the join names. Only an invitation grants 'admin' after the first member, and only to a human or a service." },
+      jwks: {
+        type: "object",
+        description: "Keys to pin, as {keys: [JWK, ...]}, each with a kid. The join's keys must be among them, and the member holds them. For a member that holds no key in force, the call registers these keys at once: the way back for a member whose keys were all revoked."
+      },
+      oidc_sub: { type: "string", description: "The OIDC subject whose token admits the invitee: the join must carry an oidc_token for it. Needs a token verifier on the coordinator." }
+    },
+    required: ["workspace", "from", "uri", "type"]
+  },
   "chap.participant.join": {
     type: "object",
     properties: {
@@ -106,10 +141,10 @@ var SCHEMAS = {
       from: PARTICIPANT_URI,
       type: {
         type: "string",
-        enum: ["human", "agent", "service", "group", "workspace"],
-        description: "The kind of participant. Only members of type 'human' are eligible for the review that chap.task.complete opens on a task marked review_required, and a completion with no eligible human is refused with -32011."
+        enum: ["human", "agent", "service"],
+        description: "The kind of participant, which the scheme of from must name: 'agent:' for an agent, and so on. Any other join is refused with -32602, and so is a join of a group: or workspace: URI, which names an address scope. Only members of type 'human' are eligible for the review that chap.task.complete opens on a task marked review_required, and a completion with no eligible human is refused with -32011. In a workspace that requires signatures, a participant that signs joins with a key."
       },
-      role: { type: "string", description: "Operator-defined role, e.g. 'reviewer' or 'drafter'. One value is read by the coordinator: 'admin' permits revoking another member's key." },
+      role: { type: "string", description: "Operator-defined role, e.g. 'reviewer' or 'drafter'. One value is read by the coordinator: 'admin', which changes the profiles, invites, and revokes another member's key. It is granted, never claimed: only the workspace's first member, or a participant an admin's invitation names as admin, may name it at a join, and any other join naming it is refused with -32011. Only a human or a service holds it. An invitation's role replaces the one named here." },
       display_name: { type: "string", description: "Human-readable name for interfaces. Not used in authorisation." }
     },
     required: ["workspace", "from", "type"]
@@ -225,6 +260,11 @@ var SCHEMAS = {
     },
     required: ["workspace", "from", "task_id", "to", "artefact"]
   },
+  "chap.review.acknowledge": {
+    type: "object",
+    properties: { workspace: WORKSPACE_ID, from: PARTICIPANT_URI, task_id: TASK_ID },
+    required: ["workspace", "from", "task_id"]
+  },
   "chap.decide.approve": {
     type: "object",
     properties: {
@@ -729,19 +769,21 @@ var TOOL_DESCRIPTIONS = {
   "chap.workspace.create": "Create a workspace: the container for the participants, tasks and audit log of one piece of collaborative work. Returns the workspace id, which every later call carries.",
   "chap.workspace.describe": "Report the current state of a workspace: its members, enabled profiles, audit length, and task and override counts.",
   "chap.workspace.set_profiles": "Replace the whole set of profiles enabled on a workspace. The list is not merged: any profile absent from it is dropped, so send the complete set you want. Enabling audit-scitt/1.0 on a workspace that already has entries starts the chain from that point and leaves the earlier entries permanently outside it, which chap.audit.verify_chain then reports as not_evaluated. Prefer setting profiles at chap.workspace.create, where no entries exist yet to strand.",
+  "chap.workspace.invite": "Invite a participant to a workspace, as its admin. The invitation names the type and role the member takes when it joins, and may pin its keys and its OIDC subject. A workspace whose join policy is 'invite' admits nobody else. For a member that holds no key in force, the call registers the keys it names at once, so a member whose keys were all revoked can sign again. Where a token or credential verifier is configured, an invitation names no keys for a person: their keys arrive with the token they join with (-32602).",
   "chap.participant.join": "Add a participant to a workspace. The type given, human, agent, service, group or workspace, decides whether they are eligible to review work that requires it.",
   "chap.participant.leave": "Remove a participant from a workspace. Entries they have already written stay in the audit log and their past signatures still verify, so leaving is not a way to withdraw a decision. They can no longer be assigned tasks or act as a reviewer, and returning means a fresh chap.participant.join.",
   "chap.task.create": "Create a task: a unit of work assigned to one participant. Set review_required to make completion depend on a reviewer decision rather than on the assignee. Returns a task_id that the rest of the lifecycle takes. Supplying idempotency_key is what makes a retry safe: a repeat carrying a key already seen returns the original task, while a repeat without one creates a second task. Assigning to a paused member is refused.",
-  "chap.task.update": "Move a task to a new state. Only the transitions in the specification's lifecycle table are accepted, and a task that requires review cannot be completed here.",
+  "chap.task.update": "Move a task to a new state. Only the transitions in the specification's lifecycle table are accepted, and a task that requires review cannot be completed here. A task whose review no decision has closed, or a successor that carries one on, is not declined (-32602).",
   "chap.task.complete": "Submit a task's output. A task that requires review does not complete: the output is held as the artefact under review, the task moves to review_requested, and a reviewer decision completes it. Any other task completes immediately.",
   "chap.audit.read": "Read entries from a workspace's audit log, optionally within a sequence range and filtered by method, sender, task or outcome. This is the query surface for everything the workspace has recorded, decisions and overrides included. An accepted call is under 'envelope'. A refused attempt the coordinator recorded, such as a decision by someone the review was not addressed to, is under 'request' with an 'outcome' giving the error code, and it did not take effect. Reads only: it records nothing, so it never appears in its own output. Entries come back as recorded, without aggregation, so grouping them, by tag for instance, is the reader's job.",
   // review/1.0
-  "chap.review.request": "Open a review on a task and address it to one or more reviewers. They then call chap.decide.approve, chap.decide.reject, chap.decide.override or chap.abstain.declare. Repeating the request with the same artefact adds reviewers to the open review.",
+  "chap.review.request": "Open a review on a task and address it to one or more reviewers. They then call chap.decide.approve, chap.decide.reject, chap.decide.override or chap.abstain.declare, and may first say they have begun with chap.review.acknowledge. Repeating the request with the same artefact adds reviewers to the open review. A task marked review_required is reviewed through chap.task.complete, which opens its review under the workspace's rule; on such a task this tool only adds people to a review already open, and before it opens is refused with -32011.",
+  "chap.review.acknowledge": "Say that this reviewer has begun the open review on a task, before deciding it. The call is recorded, so the audit log shows when each reviewer took the review up as well as when they decided. It decides nothing: the review stays open and the acknowledgement counts towards no rule. Only someone who may decide the review may send it, and anyone else is refused with -32011. A task with no open review is refused with -32010, and a second acknowledgement from the same reviewer in the same round with -32602. Returns requested_at, the time the round opened, which names it.",
   "chap.decide.approve": "Approve the artefact under review as it stands. Only a reviewer the review was addressed to may decide, and anyone else is refused with -32011. The task completes once the review's rule is satisfied, so under all_approve or quorum:N an approval may leave the review open awaiting others. Use chap.decide.override instead to accept a corrected version.",
   "chap.decide.reject": "Reject the artefact under review. The task is declined, or returns to in_progress when request_revision is set, which is the choice between ending the work and sending it back. Only a reviewer the review was addressed to may decide. Use chap.decide.override instead to correct the artefact and accept it rather than refuse it.",
   "chap.decide.override": "Correct the artefact under review with an RFC 6902 JSON Patch and accept the result. The patch, the rationale and any tags are recorded together, so the audit log holds what was changed and why, rather than only that the work was not accepted as written.",
   "chap.abstain.declare": "Stand aside from a review this participant cannot decide, for example on a conflict of interest or for want of context. Use it in place of chap.decide.reject, which judges the work; abstaining judges nothing and leaves the artefact intact. It requires an open review addressed to the caller and answers -32010 otherwise. The task moves to abstained, which is not terminal: chap.escalate.raise or a fresh chap.review.request can still carry it forward.",
-  "chap.escalate.raise": "Hand a task upwards, where the current holder can act but should not decide alone. The original moves to escalated and is linked to a new task for whoever takes it on. Use chap.handoff.propose to pass work sideways without that link, and chap.control.supersede to replace a task outright. The successor starts with an empty input unless one is supplied, so restate whatever the new assignee needs. A completed, cancelled or superseded task cannot be escalated. The successor takes the mode new_task.mode names, or else the original's, and requires review when the original did, or when it is a trial task under modes/1.0. A paused assignee is refused with -32063, and a mode above the workspace's current ceiling with -32040; after the ceiling is lowered, name a mode within it.",
+  "chap.escalate.raise": "Hand a task upwards, where the current holder can act but should not decide alone. The original moves to escalated and is linked to a new task for whoever takes it on. Use chap.handoff.propose to pass work sideways without that link, and chap.control.supersede to replace a task outright. The successor starts with an empty input unless one is supplied, so restate whatever the new assignee needs. A completed, cancelled or superseded task cannot be escalated. The successor takes the mode new_task.mode names, or else the original's, and requires review when the original did or held a review, or when it is a trial task under modes/1.0. Whoever made the original's work counts as an author of the successor's review. A paused assignee is refused with -32063, and a mode above the workspace's current ceiling with -32040; after the ceiling is lowered, name a mode within it.",
   // whisper/1.0
   "chap.whisper.ask": "Put one question to one or more participants, with a deadline and a default. If the deadline passes unanswered the default applies, so a task is never blocked waiting on a reply.",
   "chap.whisper.answer": "Answer an open whisper. Where the question carried options, the answer must name one of their ids and any other value is refused with -32022. A whisper already answered is refused with -32020 and one past its deadline with -32021, in which case the default supplied at chap.whisper.ask has already been applied.",
@@ -757,10 +799,10 @@ var TOOL_DESCRIPTIONS = {
   // control/1.0
   "chap.control.pause": "Pause work. Scoped to a task it moves that task to paused; to a participant it stops new tasks being assigned to them; to the workspace it refuses every method except describing, reading the audit log, joining, leaving and resuming.",
   "chap.control.resume": "Resume work paused at the same scope: a task returns to the state it held at the pause, a participant can be assigned tasks again, a workspace returns to active.",
-  "chap.control.cancel": "Cancel a task. Cancelled is terminal, and a task that has already settled cannot be cancelled.",
+  "chap.control.cancel": "Cancel a task. Cancelled is terminal, and a task that has already settled cannot be cancelled. From the moment a review the task requires opens until a reviewer rejects the work, the authors of the work cannot cancel it, even once they take the work back, nor a successor that carries its review (-32011).",
   "chap.control.snapshot": "Capture the workspace state as an artefact before a change you may want to undo. Returns a snapshot artefact id, which is the only thing chap.control.rollback accepts as a target; the label is for a human reading the log and cannot be used to select it. Taking a snapshot changes nothing. Note that a rollback restores only the mode ceiling and member roles, so a snapshot is a narrow safety net rather than a general undo.",
   "chap.control.rollback": "Restore workspace state from a snapshot. The mode ceiling and member roles are restored; the rollback is appended to the audit log rather than rewriting it.",
-  "chap.control.supersede": "Replace a task with a successor in one call. The original moves to superseded and stays linked to its replacement. The successor requires review when the original did, whatever its own review_required says, and a paused assignee is refused with -32063.",
+  "chap.control.supersede": "Replace a task with a successor in one call. The original moves to superseded and stays linked to its replacement. The successor requires review when the original did, whatever its own review_required says, and whoever made the original's work counts as an author of the successor's review. A paused assignee is refused with -32063, and from the moment a review the original requires opens until a reviewer rejects the work, the authors of the work cannot supersede it, nor a successor that carries its review (-32011).",
   "chap.control.set_mode_ceiling": "Set the highest operating mode tasks in this workspace may request. A task above the ceiling is refused.",
   // routing/1.0
   "chap.task.route": "Choose an assignee for a task from a list of candidates and reassign the task to the one selected. Use it where the choice itself belongs on the record: it writes a route_decision artefact naming the policy, the candidate chosen and the alternatives passed over, none of which is captured by setting assignee directly on chap.task.create. The default policy takes the first candidate that is a workspace member and is not paused. An operator-supplied policy may choose on any basis, and the call is refused with -32510 when its choice is not a member, or with -32063 when its choice is paused.",
@@ -811,8 +853,10 @@ var IDEMPOTENT = /* @__PURE__ */ new Set([
   // pausing an already paused target changes nothing
   "chap.control.set_mode_ceiling",
   // setting the ceiling it already has changes nothing
-  "chap.deliberate.close"
+  "chap.deliberate.close",
   // returns the same outcome, recomputing nothing
+  "chap.review.acknowledge"
+  // a second acknowledgement in the round is refused and records nothing
 ]);
 var OPEN_WORLD = /* @__PURE__ */ new Set([
   "chap.audit.submit_to_scitt",
@@ -822,6 +866,7 @@ var TITLES = {
   "chap.workspace.create": "Create workspace",
   "chap.workspace.describe": "Describe workspace",
   "chap.workspace.set_profiles": "Replace workspace profiles",
+  "chap.workspace.invite": "Invite participant",
   "chap.participant.join": "Add participant",
   "chap.participant.leave": "Remove participant",
   "chap.task.create": "Create task",
@@ -829,6 +874,7 @@ var TITLES = {
   "chap.task.complete": "Submit task output",
   "chap.audit.read": "Read audit log",
   "chap.review.request": "Request review",
+  "chap.review.acknowledge": "Acknowledge review",
   "chap.decide.approve": "Approve",
   "chap.decide.reject": "Reject",
   "chap.decide.override": "Override with a correction",
@@ -869,6 +915,19 @@ var TOOL_ANNOTATIONS = Object.fromEntries(
     openWorldHint: OPEN_WORLD.has(name)
   }])
 );
+var AGENT_MCP_TOOLS = /* @__PURE__ */ new Set([
+  "chap.task.create",
+  "chap.task.update",
+  "chap.task.complete",
+  "chap.whisper.ask",
+  "chap.decide.approve",
+  "chap.decide.reject",
+  "chap.decide.override",
+  "chap.review.acknowledge",
+  "chap.workspace.describe",
+  "chap.audit.read",
+  "chap.audit.verify_chain"
+]);
 
 // src/envelope.ts
 import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
@@ -920,6 +979,78 @@ function readMeta(params) {
   return meta;
 }
 
+// src/remote.ts
+var REMOTE_TIMEOUT_MS = 3e4;
+var ChapEndpointError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChapEndpointError";
+  }
+};
+function remoteDispatcher(endpoint, timeoutMs = REMOTE_TIMEOUT_MS) {
+  return {
+    async dispatch(envelope) {
+      let response;
+      let text;
+      try {
+        response = await fetch(endpoint, {
+          method: "POST",
+          headers: { "content-type": "application/json", accept: "application/json" },
+          body: JSON.stringify(envelope),
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+        text = await response.text();
+      } catch (err) {
+        throw new ChapEndpointError(`The CHAP server at ${endpoint} could not be reached (${reason(err)}). Start it, or check --url.`);
+      }
+      let body;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        throw new ChapEndpointError(`The CHAP server at ${endpoint} answered HTTP ${response.status} with a body that is not JSON.`);
+      }
+      if (isResponseEnvelope(body)) return body;
+      const said = typeof body?.error === "string" ? `: ${body.error}` : "";
+      throw new ChapEndpointError(`The CHAP server at ${endpoint} refused the call with HTTP ${response.status}${said}`);
+    }
+  };
+}
+function reason(err) {
+  if (err instanceof Error && err.name === "TimeoutError") return "timed out";
+  const cause = err.cause;
+  if (typeof cause?.code === "string") return cause.code;
+  if (typeof cause?.message === "string" && cause.message) return cause.message;
+  return err instanceof Error ? err.message : String(err);
+}
+function isResponseEnvelope(body) {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) return false;
+  const b = body;
+  return b.jsonrpc === "2.0" && ("result" in b || typeof b.error === "object" && b.error !== null);
+}
+
+// src/http.ts
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import {
+  ErrorCode as ErrorCode2,
+  SUPPORTED_PROTOCOL_VERSIONS as SDK_PROTOCOL_VERSIONS,
+  isJSONRPCNotification,
+  isJSONRPCRequest
+} from "@modelcontextprotocol/sdk/types.js";
+var HEADER_MISMATCH = -32020;
+var DEFAULT_MAX_BODY_BYTES = 1048576 + 65536;
+var HANDSHAKE_VERSIONS = SDK_PROTOCOL_VERSIONS.filter(
+  (v) => !MODERN_PROTOCOL_VERSIONS.includes(v)
+);
+var STATUS_FOR_CODE = /* @__PURE__ */ new Map([
+  [ErrorCode2.ParseError, 400],
+  [ErrorCode2.InvalidRequest, 400],
+  [ErrorCode2.InvalidParams, 400],
+  [HEADER_MISMATCH, 400],
+  [UNSUPPORTED_PROTOCOL_VERSION, 400],
+  [ErrorCode2.MethodNotFound, 404]
+]);
+var INTERNAL = { code: ErrorCode2.InternalError, message: "Internal error" };
+
 // src/index.ts
 var META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
 var LIST_TTL_MS = 36e5;
@@ -930,10 +1061,32 @@ var ServerDiscoverRequestSchema = z.object({
   // exist in zod 3, where it stopped the package at import.
   params: z.optional(z.object({ _meta: z.optional(z.record(z.string(), z.unknown())) }).passthrough())
 });
+var INTERNAL_ERROR = -32603;
+var FAILED_INSIDE = { chap_error: INTERNAL_ERROR, message: "The CHAP call failed inside the server; its log has the detail." };
+function refusePerson(participant) {
+  if (participant?.startsWith("human:")) {
+    throw new Error(`participant ${participant} names a person. This server acts for an agent, and a person decides in a desk; give the agent's own URI, such as agent:assistant.`);
+  }
+}
+function pinnedSchema(schema, participant) {
+  if (!schema.properties?.from) return schema;
+  return {
+    ...schema,
+    properties: {
+      ...schema.properties,
+      from: {
+        type: "string",
+        description: `This server acts as ${participant}: it fills this in, and refuses a call that names anyone else.`
+      }
+    },
+    required: (schema.required ?? []).filter((key) => key !== "from")
+  };
+}
 function makeChapMcpServer(coord, options = {}) {
+  refusePerson(options.participant);
   const serverInfo = {
     name: options.name ?? "chap",
-    version: options.version ?? "0.3.4"
+    version: options.version ?? "0.3.5"
   };
   const server = new Server(
     serverInfo,
@@ -954,7 +1107,7 @@ function makeChapMcpServer(coord, options = {}) {
       // not already see. The annotation carries a readable one.
       title: ann?.title ?? name,
       description: TOOL_DESCRIPTIONS[name] ?? `CHAP method ${methodForTool(name)}.`,
-      inputSchema: SCHEMAS[name],
+      inputSchema: options.participant === void 0 ? SCHEMAS[name] : pinnedSchema(SCHEMAS[name], options.participant),
       // Behavioural hints. Without these a client has only the prose to go
       // on when deciding whether a call is safe to make or to retry.
       ...ann ? { annotations: ann } : {}
@@ -973,7 +1126,7 @@ function makeChapMcpServer(coord, options = {}) {
   });
   server.setRequestHandler(ServerDiscoverRequestSchema, async (request) => {
     if (classifyEnvelope(request.params) === "legacy") {
-      throw new ProtocolError(ErrorCode2.MethodNotFound, "Method not found", "server/discover");
+      throw new ProtocolError(ErrorCode3.MethodNotFound, "Method not found", "server/discover");
     }
     return {
       resultType: "complete",
@@ -990,13 +1143,10 @@ function makeChapMcpServer(coord, options = {}) {
     const terminal = (result) => era === "modern" ? { resultType: "complete", ...result } : result;
     const toolName = request.params.name;
     const rawArgs = request.params.arguments ?? {};
-    const method = methodForTool(toolName);
-    if (!method) {
-      return terminal({
-        isError: true,
-        content: [{ type: "text", text: `Unknown CHAP tool: ${toolName}` }]
-      });
+    if (!Object.hasOwn(SCHEMAS, toolName)) {
+      throw new ProtocolError(ErrorCode3.InvalidParams, `Unknown tool: ${toolName}`);
     }
+    const method = methodForTool(toolName);
     if (!filter(toolName)) {
       return terminal({
         isError: true,
@@ -1024,20 +1174,25 @@ function makeChapMcpServer(coord, options = {}) {
     };
     let response;
     try {
-      response = coord.dispatch(envelope);
+      response = await coord.dispatch(envelope);
     } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
+      if (e instanceof ChapEndpointError) {
+        return terminal({ isError: true, content: [{ type: "text", text: e.message }] });
+      }
+      console.error("CHAP dispatch failed:", e);
       return terminal({
         isError: true,
-        content: [{ type: "text", text: `CHAP dispatch threw: ${msg}` }]
+        content: [{ type: "text", text: FAILED_INSIDE.message }]
       });
     }
     if (response.error) {
+      const internal = response.error.code === INTERNAL_ERROR;
+      if (internal) console.error("CHAP call failed:", response.error);
       return terminal({
         isError: true,
         content: [{
           type: "text",
-          text: JSON.stringify({
+          text: JSON.stringify(internal ? FAILED_INSIDE : {
             chap_error: response.error.code,
             message: response.error.message,
             ...response.error.data !== void 0 ? { data: response.error.data } : {}
@@ -1056,7 +1211,7 @@ function makeChapMcpServer(coord, options = {}) {
 }
 
 // src/cli.ts
-var VERSION = "0.3.4";
+var VERSION = "0.3.5";
 var DEFAULT_PROFILES = [
   "core/1.0",
   "review/1.0",
@@ -1068,41 +1223,167 @@ var DEFAULT_PROFILES = [
   "modes/1.0",
   "audit-scitt/1.0"
 ];
-var profiles = process.env.CHAP_PROFILES ? process.env.CHAP_PROFILES.split(",").map((p) => p.trim()).filter(Boolean) : DEFAULT_PROFILES;
-if (profiles.length === 0) {
-  process.stderr.write("CHAP_PROFILES was set but empty. Unset it to use the defaults.\n");
-  process.exit(1);
+var DEFAULT_PARTICIPANT = "agent:assistant";
+var USAGE = `Usage: chap-mcp-server [options]
+
+Serves CHAP to one MCP client on stdio, making every call as one participant.
+
+Options:
+  --as <uri>          the participant every call is made as (CHAP_PARTICIPANT,
+                      default ${DEFAULT_PARTICIPANT}). A human: URI is refused:
+                      a person decides in a desk, never through the assistant
+  --tools agent|all   agent, the default: the tools an agent's own work needs,
+                      listed below; all: every CHAP method
+  --url <endpoint>    forward every call to a running CHAP server's JSON-RPC
+                      endpoint, such as http://127.0.0.1:8792/chap, which
+                      keeps the workspaces
+  --db <path>         keep the workspaces in this SQLite file (CHAP_DB_PATH);
+                      a leading ~ is the home directory. Without --db or
+                      --url, state is in memory only
+  --profiles <list>   comma-separated profiles for new workspaces
+                      (CHAP_PROFILES, default those listed below)
+  --help              print this and exit
+
+The agent tools:
+${[...AGENT_MCP_TOOLS].sort().map((name) => `  ${name}`).join("\n")}
+
+The default profiles:
+${DEFAULT_PROFILES.map((profile) => `  ${profile}`).join("\n")}
+`;
+var URI_RE = /^[a-z][a-z0-9+.-]*:[\x21\x23-\x5b\x5d-\x7e]+$/;
+var UsageError = class extends Error {
+};
+function fromEnv(name) {
+  const value = process.env[name]?.trim();
+  return value ? value : void 0;
+}
+function expandHome(path) {
+  return /^~(?=$|[\\/])/.test(path) ? homedir() + path.slice(1) : path;
+}
+function parseArgs(argv) {
+  const given = {};
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      help = true;
+      continue;
+    }
+    const m = /^(--as|--tools|--url|--db|--profiles)(?:=(.*))?$/.exec(arg);
+    if (!m) throw new UsageError(arg.startsWith("-") ? `Unknown option ${arg}` : `Unexpected argument ${arg}`);
+    const value = m[2] ?? argv[++i];
+    if (value === void 0 || value === "") throw new UsageError(`${m[1]} needs a value`);
+    given[m[1]] = value;
+  }
+  const [participant, participantFrom] = given["--as"] !== void 0 ? [given["--as"], "--as"] : fromEnv("CHAP_PARTICIPANT") !== void 0 ? [fromEnv("CHAP_PARTICIPANT"), "CHAP_PARTICIPANT"] : [DEFAULT_PARTICIPANT, "--as"];
+  if (!URI_RE.test(participant)) {
+    throw new UsageError(`${participantFrom} ${participant} is not a participant URI. Use the form agent:name@example.org.`);
+  }
+  if (participant.startsWith("human:")) {
+    throw new UsageError(
+      `${participantFrom} ${participant} names a person. This server acts for an assistant, and a person decides in a desk; give the assistant's own URI, such as agent:assistant.`
+    );
+  }
+  const tools = given["--tools"] ?? "agent";
+  if (tools !== "agent" && tools !== "all") throw new UsageError(`--tools takes agent or all; ${tools} is neither`);
+  let url;
+  if (given["--url"] !== void 0) {
+    let parsed;
+    try {
+      parsed = new URL(given["--url"]);
+    } catch {
+      parsed = void 0;
+    }
+    if (!parsed || parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new UsageError(`--url takes the http or https address of a CHAP JSON-RPC endpoint, such as http://127.0.0.1:8792/chap; ${given["--url"]} is not one`);
+    }
+    url = parsed.href;
+  }
+  const [rawDb, dbFrom] = given["--db"] !== void 0 ? [given["--db"], "--db"] : [fromEnv("CHAP_DB_PATH"), "CHAP_DB_PATH"];
+  const [rawProfiles, profilesFrom] = given["--profiles"] !== void 0 ? [given["--profiles"], "--profiles"] : [fromEnv("CHAP_PROFILES"), "CHAP_PROFILES"];
+  if (url && rawDb !== void 0) {
+    throw new UsageError(`--url forwards to a server that keeps its own store, so ${dbFrom} does not apply. Set one or the other.`);
+  }
+  if (url && rawProfiles !== void 0) {
+    throw new UsageError(`--url forwards to a server that sets its own profiles, so ${profilesFrom} does not apply. Set one or the other.`);
+  }
+  let profiles = DEFAULT_PROFILES;
+  if (rawProfiles !== void 0) {
+    profiles = rawProfiles.split(",").map((p) => p.trim()).filter(Boolean);
+    if (profiles.length === 0) throw new UsageError(`${profilesFrom} names no profiles. Leave it unset for the defaults.`);
+  }
+  return {
+    help,
+    participant,
+    tools,
+    url,
+    profiles,
+    ...rawDb !== void 0 ? { db: resolve(expandHome(rawDb)) } : {}
+  };
 }
 async function openStore(dbPath) {
   try {
+    mkdirSync(dirname(dbPath), { recursive: true });
     const { SqliteStore } = await import("@brightbeamai/chap-coordinator/storage/sqlite");
     return new SqliteStore(dbPath);
   } catch (err) {
     const detail = err instanceof Error ? err.message : String(err);
     process.stderr.write(
-      `CHAP_DB_PATH is set to ${dbPath} but the SQLite store could not be opened.
+      `The SQLite store at ${dbPath} could not be opened.
 ${detail}
 better-sqlite3 is an optional native dependency; reinstall with build tools
-available, or unset CHAP_DB_PATH to run in memory without persistence.
+available, or leave --db and CHAP_DB_PATH unset to run in memory without persistence.
 `
     );
     process.exit(1);
   }
 }
 async function main() {
-  const dbPath = process.env.CHAP_DB_PATH?.trim();
-  const store = dbPath ? await openStore(dbPath) : void 0;
-  const coord = new Coordinator({ defaultProfiles: profiles, ...store ? { store } : {} });
-  await coord.start();
-  const server = makeChapMcpServer(coord, { name: "chap", version: VERSION });
-  process.stderr.write(`CHAP MCP server ${VERSION} on stdio.
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    if (!(err instanceof UsageError)) throw err;
+    process.stderr.write(`${err.message}
+Run chap-mcp-server --help for the options.
 `);
-  process.stderr.write(`Profiles: ${profiles.join(", ")}
+    process.exit(2);
+  }
+  if (options.help) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  const toolSet = options.tools === "agent" ? "the agent tools" : "every CHAP tool";
+  process.stderr.write(`CHAP MCP server ${VERSION} on stdio, acting as ${options.participant} with ${toolSet}.
 `);
-  process.stderr.write(
-    dbPath ? `Persisting to ${dbPath}
-` : "In memory. Set CHAP_DB_PATH to keep workspaces across restarts.\n"
-  );
+  let dispatcher;
+  if (options.url) {
+    dispatcher = remoteDispatcher(options.url);
+    process.stderr.write(`Forwarding every call to ${options.url}, whose coordinator keeps the workspaces.
+`);
+  } else {
+    const store = options.db ? await openStore(options.db) : void 0;
+    const coord = new Coordinator({ defaultProfiles: options.profiles, ...store ? { store } : {} });
+    await coord.start();
+    dispatcher = coord;
+    process.stderr.write(`Profiles: ${options.profiles.join(", ")}
+`);
+    process.stderr.write(
+      options.db ? `Persisting to ${options.db}
+` : "State is in memory only: the workspaces are lost when this process exits. Set --db or CHAP_DB_PATH to keep them.\n"
+    );
+    if (options.tools === "agent" && coord.workspaces.size === 0) {
+      process.stderr.write(
+        "No workspace exists yet, and the agent tools cannot create one: run once with --tools all, or use --url to reach a server that has one.\n"
+      );
+    }
+  }
+  const server = makeChapMcpServer(dispatcher, {
+    name: "chap",
+    version: VERSION,
+    participant: options.participant,
+    ...options.tools === "agent" ? { toolFilter: (name) => AGENT_MCP_TOOLS.has(name) } : {}
+  });
   await server.connect(new StdioServerTransport());
 }
 main().catch((err) => {