@ccmsg/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoshiaki Kawazu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,33 @@
+# ccmsg-protocol
+
+> 🇯🇵 [README-ja.md](./README-ja.md)
+
+The **contract of record** shared by the ccmsg daemon and its web UI. It holds the shape of
+every op, event, error code and identifier as a schema, and both sides validate against it.
+
+The contract is decided here and the daemon and web UI follow it. Neither side learns the
+other's internals by any route that does not pass through it.
+
+## Install
+
+```bash
+bun add @ccmsg/protocol
+```
+
+## Usage
+
+```ts
+import { isValid, MessageSendRequest, OP_ATTRIBUTES, opErrors } from "@ccmsg/protocol";
+
+isValid(MessageSendRequest, incoming); // validating the wire is the contract's job
+OP_ATTRIBUTES.message_send.roles; // authorization reads the table, not a branch
+opErrors("session_rename"); // the codes this op may answer with
+```
+
+## Documentation
+
+- [DESIGN.md](./docs/DESIGN.md) — layers, planes, the op attribute table, and the conventions
+
+## License
+
+MIT License, Yoshiaki Kawazu (@kawaz)

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ccmsg/protocol",
+  "version": "0.1.0",
+  "description": "Wire contract (schema + types + op attribute table) shared by the ccmsg daemon and web UI",
+  "license": "MIT",
+  "author": "kawaz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kawaz/ccmsg-protocol.git"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.33"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "oxfmt": "0.58.0",
+    "oxlint": "1.73.0",
+    "oxlint-tsgolint": "0.24.0",
+    "typescript": "7.0.2"
+  }
+}

package/src/attributes.ts

@@ -0,0 +1,353 @@
+import type { ErrorCode } from "./errors.ts";
+import type { Capability, Role } from "./identifiers.ts";
+
+/** Which face of the contract an op belongs to. `common` is the transport
+ * level (connect / subscribe), which every face uses. `mesh` holds no ops: an
+ * op crosses instances by carrying the envelope's mesh fields, not by being a
+ * different op. */
+export type Plane = "common" | "messaging" | "control" | "mesh";
+
+/** `instance-local` ops answer for one instance's processes, paths and
+ * handles, so they are forwarded to the instance that owns the subject.
+ * `cluster` ops are answerable by whichever instance is asked. */
+export type Locality = "instance-local" | "cluster";
+
+export interface OpAttributes {
+  readonly plane: Plane;
+  /** Roles allowed to call the op. A role outside this set gets `forbidden`. */
+  readonly roles: readonly Role[];
+  /** Whether the op requires an identity settled by `hello`. */
+  readonly needs_hello: boolean;
+  /** The capability the op needs, when it needs one. */
+  readonly capability?: Capability;
+  readonly locality: Locality;
+  /** Present when the role changes what the reply may contain rather than
+   * whether the call is allowed. */
+  readonly scope?: "role";
+  /** Codes specific to this op. The codes that follow from the attributes
+   * above are added by `opErrors` instead of being repeated here. */
+  readonly errors: readonly ErrorCode[];
+}
+
+const ALL_ROLES = ["session", "user", "instance"] as const;
+const AGENT_AND_USER = ["session", "user"] as const;
+const USER_ONLY = ["user"] as const;
+const SESSION_ONLY = ["session"] as const;
+
+/** The whole op vocabulary, with the attributes that decide who may call each
+ * op, what it needs, and where it runs. This table is the single place those
+ * facts live: authorization, capability gating and forwarding all read it
+ * rather than each carrying their own copy. */
+export const OP_ATTRIBUTES = {
+  // --- common: connect and subscribe (5) ---
+  // `hello` and `instance_ping` address the instance the caller reached, so
+  // there is nothing to forward and no unreachable instance to report — which
+  // is why they are `cluster` despite answering about one instance.
+  hello: {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: false,
+    locality: "cluster",
+    errors: [],
+  },
+  instance_ping: {
+    plane: "common",
+    roles: ALL_ROLES,
+    needs_hello: false,
+    locality: "cluster",
+    errors: [],
+  },
+  instance_shutdown: {
+    plane: "common",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: [],
+  },
+  topic_subscribe: {
+    plane: "common",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "cluster",
+    errors: ["topic_unknown"],
+  },
+  topic_unsubscribe: {
+    plane: "common",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "cluster",
+    errors: ["topic_unknown"],
+  },
+
+  // --- messaging: one-to-one delivery (4) ---
+  message_send: {
+    plane: "messaging",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "cluster",
+    errors: ["session_not_found"],
+  },
+  say_post: {
+    plane: "messaging",
+    roles: SESSION_ONLY,
+    needs_hello: true,
+    locality: "cluster",
+    errors: [],
+  },
+  say_mark_read: {
+    plane: "messaging",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "cluster",
+    errors: [],
+  },
+  notify_send: {
+    plane: "messaging",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "cluster",
+    errors: [],
+  },
+
+  // --- control: session observation and operation (8) ---
+  session_kill: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["session_not_found"],
+  },
+  session_rename: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "terminal",
+    locality: "instance-local",
+    errors: ["session_not_found"],
+  },
+  session_env_read: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["session_not_found"],
+  },
+  session_search: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: [],
+  },
+  session_dump_write: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["not_found"],
+  },
+  transcript_read: {
+    plane: "control",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "instance-local",
+    scope: "role",
+    errors: ["not_found"],
+  },
+  session_fork_origin: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "fork",
+    locality: "instance-local",
+    errors: ["not_found"],
+  },
+  session_last_live_remove: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: [],
+  },
+
+  // --- control: file access (9) ---
+  dir_list: {
+    plane: "control",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "instance-local",
+    scope: "role",
+    errors: ["path_forbidden", "not_found"],
+  },
+  file_read: {
+    plane: "control",
+    roles: AGENT_AND_USER,
+    needs_hello: true,
+    locality: "instance-local",
+    scope: "role",
+    errors: ["path_forbidden", "not_found"],
+  },
+  file_write: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["path_not_writable", "file_exists"],
+  },
+  file_create: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["file_exists", "path_forbidden"],
+  },
+  file_edit: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["file_conflict", "not_a_text_file"],
+  },
+  file_delete: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["path_forbidden", "not_found"],
+  },
+  file_find: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: ["path_forbidden"],
+  },
+  file_stat_batch: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "instance-local",
+    errors: [],
+  },
+  dir_tree: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "launcher",
+    locality: "instance-local",
+    errors: [],
+  },
+
+  // --- control: launcher / sandbox / translate / llm (7) ---
+  launcher_config_read: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "launcher",
+    locality: "instance-local",
+    errors: [],
+  },
+  launcher_run: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "launcher",
+    locality: "instance-local",
+    errors: [],
+  },
+  sandbox_grant: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "sandbox",
+    locality: "instance-local",
+    errors: ["path_forbidden"],
+  },
+  sandbox_revoke: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "sandbox",
+    locality: "instance-local",
+    errors: [],
+  },
+  translate_run: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "translate",
+    locality: "instance-local",
+    errors: ["translate_helper_failed"],
+  },
+  llm_usage_read: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "llm_usage",
+    locality: "instance-local",
+    errors: [],
+  },
+  llm_stats_read: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    capability: "llm_stats",
+    locality: "instance-local",
+    errors: [],
+  },
+
+  // --- control: the shared key-value store (3) ---
+  // The only control ops that are not instance-local: a value is held by every
+  // instance rather than by one, so whichever is asked can answer.
+  kv_read: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "cluster",
+    errors: ["not_found"],
+  },
+  kv_write: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "cluster",
+    errors: [],
+  },
+  kv_delete: {
+    plane: "control",
+    roles: USER_ONLY,
+    needs_hello: true,
+    locality: "cluster",
+    errors: [],
+  },
+} as const satisfies Record<string, OpAttributes>;
+
+export type OpName = keyof typeof OP_ATTRIBUTES;
+
+export const OP_NAMES = Object.keys(OP_ATTRIBUTES) as OpName[];
+
+export function opAttributes(op: OpName): OpAttributes {
+  return OP_ATTRIBUTES[op];
+}
+
+/** Every code the op may answer with: the ones it declares, plus the ones its
+ * attributes imply. Keeping the implied codes out of the table means adding a
+ * capability to an op cannot leave its error list stale. */
+export function opErrors(op: OpName): ErrorCode[] {
+  const attrs: OpAttributes = OP_ATTRIBUTES[op];
+  const codes = new Set<ErrorCode>(["invalid_args", ...attrs.errors]);
+  if (attrs.needs_hello) codes.add("hello_required");
+  if (attrs.roles.length < ALL_ROLES.length) codes.add("forbidden");
+  if (attrs.capability !== undefined) codes.add("capability_unavailable");
+  if (attrs.locality === "instance-local") codes.add("instance_unreachable");
+  return [...codes];
+}
+
+/** Whether a connection speaking `role` may call `op`. */
+export function isRoleAllowed(op: OpName, role: Role): boolean {
+  return (OP_ATTRIBUTES[op].roles as readonly Role[]).includes(role);
+}
+
+export function opsOfPlane(plane: Plane): OpName[] {
+  return OP_NAMES.filter((op) => OP_ATTRIBUTES[op].plane === plane);
+}

package/src/common/hello.ts

@@ -0,0 +1,73 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response } from "../envelope.ts";
+import { Capability, InstanceId, Role, Sid, Timestamp } from "../identifiers.ts";
+
+/** The mesh handshake's opening claim, carried by a `role: "instance"` hello.
+ *
+ * It is not signed and proves nothing on its own: it names the peer and says
+ * where its one-off key can be fetched. The proof that binds this connection to
+ * `iss` follows on a separate exchange (mesh-peer-auth §5). */
+export const MeshHello = Type.Object(
+  {
+    /** Generation of the mesh handshake format, apart from the protocol
+     * generation so the handshake can change without the wire changing. */
+    ver: Type.Integer({ minimum: 1 }),
+    /** The endpoint URL the connecting instance claims to be. */
+    iss: InstanceId,
+    /** The endpoint URL it believes it is connecting to. Compared whole
+     * against the receiver's own URL, which is what stops a signature made for
+     * one instance from being replayed at another on the same host. */
+    aud: InstanceId,
+    /** Names the ephemeral key the receiver is to fetch for this connection. */
+    kid: Type.String({ minLength: 16 }),
+  },
+  { $id: "MeshHello" },
+);
+export type MeshHello = Static<typeof MeshHello>;
+
+export const HelloArgs = Type.Object({
+  role: Role,
+  /** The generation the caller speaks. A hello announcing another generation
+   * is refused with `bad_request`; there is no path that serves it anyway. */
+  protocol_version: Type.Integer({ minimum: 1 }),
+  /** Required for `role: "session"`: the session the connection speaks for. */
+  sid: Type.Optional(Sid),
+  /** Required for `role: "instance"`: the mesh handshake claim. */
+  mesh: Type.Optional(MeshHello),
+  /** The client build, for display in diagnostics. Nothing gates on it. */
+  client_version: Type.Optional(Type.String()),
+});
+export type HelloArgs = Static<typeof HelloArgs>;
+
+/** One instance as seen from the instance answering `hello`. */
+export const InstanceInfo = Type.Object(
+  {
+    id: InstanceId,
+    /** The host it runs on. An attribute of the instance, not its identity —
+     * one host may run several instances. */
+    host: Type.String({ minLength: 1 }),
+    /** Whether the answering instance can currently reach it. */
+    reachable: Type.Boolean(),
+  },
+  { $id: "InstanceInfo" },
+);
+export type InstanceInfo = Static<typeof InstanceInfo>;
+
+export const HelloResult = Type.Object({
+  protocol_version: Type.Integer({ minimum: 1 }),
+  /** The instance answering. Every other id in the reply is relative to it. */
+  instance: InstanceId,
+  /** The instances this one knows of, itself included. */
+  instances: Type.Array(InstanceInfo),
+  /** What this instance can do. An op whose `capability` is absent here
+   * answers `capability_unavailable`, so a client can tell which ops are worth
+   * offering before it calls any of them. */
+  capabilities: Type.Array(Capability),
+  /** The daemon build, for display. */
+  version: Type.String(),
+  started_at: Timestamp,
+});
+export type HelloResult = Static<typeof HelloResult>;
+
+export const HelloRequest = request("hello", HelloArgs);
+export const HelloResponse = response("hello", HelloResult);

package/src/common/ping.ts

@@ -0,0 +1,37 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response } from "../envelope.ts";
+import { InstanceId, Timestamp } from "../identifiers.ts";
+
+export const InstancePingArgs = Type.Object({});
+export type InstancePingArgs = Static<typeof InstancePingArgs>;
+
+/** How the answering daemon process is running.
+ *
+ * This is about one process, which is why the op is instance-local: the health
+ * of the cluster is `hello`'s `instances[]`, not a ping fanned out. */
+export const InstancePingResult = Type.Object({
+  instance: InstanceId,
+  version: Type.String(),
+  pid: Type.Integer({ minimum: 1 }),
+  started_at: Timestamp,
+  /** Connected clients right now. */
+  clients: Type.Integer({ minimum: 0 }),
+  /** The interpreter and entry script the daemon runs from. Which plugin cache
+   * the entry script sits in is what tells two same-host instances apart when
+   * one is running a stale build. */
+  exe: Type.Optional(Type.String()),
+  script: Type.Optional(Type.String()),
+  /** Bound HTTP/WS addresses as `host:port`; empty when HTTP is off. */
+  http: Type.Array(Type.String()),
+  /** The daemon's current view of the host link. */
+  network: Type.Union([
+    Type.Literal("off"),
+    Type.Literal("unknown"),
+    Type.Literal("online"),
+    Type.Literal("offline"),
+  ]),
+});
+export type InstancePingResult = Static<typeof InstancePingResult>;
+
+export const InstancePingRequest = request("instance_ping", InstancePingArgs);
+export const InstancePingResponse = response("instance_ping", InstancePingResult);

package/src/common/shutdown.ts

@@ -0,0 +1,13 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response } from "../envelope.ts";
+
+export const InstanceShutdownArgs = Type.Object({});
+export type InstanceShutdownArgs = Static<typeof InstanceShutdownArgs>;
+
+/** Answered before the process goes down, so the caller learns the request was
+ * accepted rather than inferring it from the socket closing. */
+export const InstanceShutdownResult = Type.Object({});
+export type InstanceShutdownResult = Static<typeof InstanceShutdownResult>;
+
+export const InstanceShutdownRequest = request("instance_shutdown", InstanceShutdownArgs);
+export const InstanceShutdownResponse = response("instance_shutdown", InstanceShutdownResult);

package/src/common/topics.ts

@@ -0,0 +1,99 @@
+import { type Static, Type } from "@sinclair/typebox";
+import { request, response } from "../envelope.ts";
+import type { Capability, Role } from "../identifiers.ts";
+
+/** Topics naming one thing for the whole instance. */
+export const PLAIN_TOPICS = [
+  "inbox",
+  "notify",
+  "peers",
+  "agents",
+  "session_errors",
+  "llm_requests",
+  "llm_status",
+] as const;
+
+/** Topics naming one session, written `<topic>:<sid>`. */
+export const SESSION_SCOPED_TOPICS = ["session_status", "transcript"] as const;
+
+/** Topics naming one namespace, written `<topic>:<ns>`. The parameter is a name
+ * its users choose rather than an identifier this contract issues, so it is
+ * spelled apart from the session-scoped topics above. */
+export const NAMESPACE_SCOPED_TOPICS = ["kv"] as const;
+
+/** What a namespace may be called. Kept to an identifier because the name
+ * appears inside a topic name, where a separator or a space would make the two
+ * halves impossible to tell apart. */
+export const NAMESPACE_PATTERN = "[a-z][a-z0-9_]{0,63}";
+
+export type PlainTopic = (typeof PLAIN_TOPICS)[number];
+export type SessionScopedTopic = (typeof SESSION_SCOPED_TOPICS)[number];
+export type NamespaceScopedTopic = (typeof NAMESPACE_SCOPED_TOPICS)[number];
+export type TopicName =
+  | PlainTopic
+  | `${SessionScopedTopic}:${string}`
+  | `${NamespaceScopedTopic}:${string}`;
+
+export const Topic = Type.String({
+  $id: "Topic",
+  pattern: [
+    "^(?:",
+    PLAIN_TOPICS.join("|"),
+    `|(?:${SESSION_SCOPED_TOPICS.join("|")}):[0-9a-f-]{36}`,
+    `|(?:${NAMESPACE_SCOPED_TOPICS.join("|")}):${NAMESPACE_PATTERN}`,
+    ")$",
+  ].join(""),
+});
+
+export interface TopicAttributes {
+  readonly roles: readonly Role[];
+  readonly capability?: Capability;
+}
+
+/** Who may subscribe to what. The same question the op table answers for ops:
+ * a subscribe from a role outside the set answers `forbidden`, and one naming
+ * a capability the instance lacks answers `capability_unavailable`. */
+export const TOPIC_ATTRIBUTES = {
+  inbox: { roles: ["session", "user"] },
+  notify: { roles: ["session", "user"] },
+  peers: { roles: ["session", "user"] },
+  agents: { roles: ["user"] },
+  session_errors: { roles: ["user"] },
+  llm_requests: { roles: ["user"], capability: "llm_events" },
+  llm_status: { roles: ["user"], capability: "llm_status" },
+  session_status: { roles: ["user"] },
+  transcript: { roles: ["user"] },
+  kv: { roles: ["user"] },
+} as const satisfies Record<
+  PlainTopic | SessionScopedTopic | NamespaceScopedTopic,
+  TopicAttributes
+>;
+
+export type TopicKind = PlainTopic | SessionScopedTopic | NamespaceScopedTopic;
+
+/** The part of a topic name before any `:` — the key into TOPIC_ATTRIBUTES. */
+export function topicKind(topic: string): TopicKind | undefined {
+  const head = topic.split(":", 1)[0] as TopicKind;
+  return head in TOPIC_ATTRIBUTES ? head : undefined;
+}
+
+export const TopicSubscribeArgs = Type.Object({ topic: Topic });
+export type TopicSubscribeArgs = Static<typeof TopicSubscribeArgs>;
+
+/** The reply only acknowledges the subscription. The value itself arrives as
+ * the first frame, marked `snapshot: true`, so a subscriber has one code path
+ * for the current value and for every change after it. */
+export const TopicSubscribeResult = Type.Object({ topic: Topic });
+export type TopicSubscribeResult = Static<typeof TopicSubscribeResult>;
+
+export const TopicSubscribeRequest = request("topic_subscribe", TopicSubscribeArgs);
+export const TopicSubscribeResponse = response("topic_subscribe", TopicSubscribeResult);
+
+export const TopicUnsubscribeArgs = Type.Object({ topic: Topic });
+export type TopicUnsubscribeArgs = Static<typeof TopicUnsubscribeArgs>;
+
+export const TopicUnsubscribeResult = Type.Object({ topic: Topic });
+export type TopicUnsubscribeResult = Static<typeof TopicUnsubscribeResult>;
+
+export const TopicUnsubscribeRequest = request("topic_unsubscribe", TopicUnsubscribeArgs);
+export const TopicUnsubscribeResponse = response("topic_unsubscribe", TopicUnsubscribeResult);