@casimesh/sdk 0.1.0

package/index.js

@@ -0,0 +1,884 @@
+import { z } from 'zod';
+
+// ../contracts/src/agent.ts
+var CapabilityName = z.string().regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/, "Dotted lowercase name, e.g. terrain.analysis").max(100);
+var Capability = z.object({
+  name: CapabilityName,
+  version: z.string().max(32).default("1.0.0"),
+  description: z.string().max(500).optional()
+}).meta({ id: "Capability", description: "A machine-discoverable description of what an agent can perform." });
+var Timestamp = z.iso.datetime().meta({ example: "2026-09-28T09:28:12.123Z" });
+var Version = z.int().min(1).meta({ description: "Monotonic per-entity version" });
+var DisplayName = z.string().trim().min(1).max(120);
+var Slug = z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Lowercase letters, digits and single hyphens").max(63);
+var Metadata = z.record(z.string(), z.unknown());
+var EntityAudit = {
+  version: Version,
+  createdAt: Timestamp,
+  updatedAt: Timestamp
+};
+var ID_PREFIX = {
+  node: "node",
+  organization: "org",
+  agent: "agt",
+  link: "lnk",
+  event: "evt",
+  command: "cmd",
+  principal: "prn",
+  roleBinding: "rol",
+  apiKey: "key",
+  task: "tsk"
+};
+var ULID_PATTERN = "[0-9A-HJKMNP-TV-Z]{26}";
+var prefixedId = (kind) => z.string().regex(new RegExp(`^${ID_PREFIX[kind]}_${ULID_PATTERN}$`), `Expected a ${kind} id (${ID_PREFIX[kind]}_<ULID>)`).meta({ description: `${kind} identifier`, example: `${ID_PREFIX[kind]}_01J9Z3K7Q8R5T2V4W6X8Y0A1B2` });
+var NodeId = prefixedId("node");
+var OrganizationId = prefixedId("organization");
+var AgentId = prefixedId("agent");
+var LinkId = prefixedId("link");
+var EventId = prefixedId("event");
+var CommandId = prefixedId("command");
+var PrincipalId = prefixedId("principal");
+var RoleBindingId = prefixedId("roleBinding");
+var TaskId = prefixedId("task");
+
+// ../contracts/src/agent.ts
+var AgentKind = z.enum(["standard", "mesh"]);
+var AgentStatus = z.enum(["created", "starting", "running", "stopped", "error"]);
+var capabilityList = z.array(Capability).max(64).refine((caps) => new Set(caps.map((c) => c.name)).size === caps.length, "Capability names must be unique");
+var Agent = z.object({
+  id: AgentId,
+  organizationId: OrganizationId,
+  nodeId: NodeId,
+  name: DisplayName,
+  kind: AgentKind,
+  status: AgentStatus,
+  capabilities: capabilityList,
+  /** Model backing the agent, e.g. `claude-sonnet-5`; null for rule-based agents. */
+  model: z.string().max(100).nullable(),
+  metadata: Metadata,
+  ...EntityAudit
+}).meta({ id: "Agent", description: "An autonomous software entity with identity, capabilities and policies." });
+z.object({
+  name: DisplayName,
+  capabilities: capabilityList.default([]),
+  model: z.string().max(100).nullable().default(null),
+  metadata: Metadata.optional()
+}).meta({ id: "CreateAgentRequest" });
+z.object({
+  name: DisplayName.optional(),
+  capabilities: capabilityList.optional(),
+  model: z.string().max(100).nullable().optional(),
+  metadata: Metadata.optional()
+}).refine((body) => Object.keys(body).length > 0, "At least one field must be provided").meta({ id: "UpdateAgentRequest" });
+var PrincipalKind = z.enum(["user", "service"]);
+var Principal = z.object({
+  id: PrincipalId,
+  kind: PrincipalKind,
+  name: DisplayName,
+  publicKey: z.string().nullable(),
+  createdAt: Timestamp
+}).meta({ id: "Principal", description: "A user or service that can be authenticated and granted roles." });
+var Role = z.enum(["node_owner", "org_owner"]);
+var RoleScope = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("node"), nodeId: NodeId }),
+  z.object({ type: z.literal("organization"), organizationId: OrganizationId, nodeId: NodeId })
+]);
+var RoleBinding = z.object({
+  id: RoleBindingId,
+  principalId: PrincipalId,
+  role: Role,
+  scope: RoleScope,
+  createdAt: Timestamp
+}).refine(
+  (b) => b.role === "node_owner" ? b.scope.type === "node" : b.scope.type === "organization",
+  "node_owner must be node-scoped and org_owner organization-scoped"
+).meta({ id: "RoleBinding" });
+z.object({ principalId: PrincipalId }).meta({ id: "GrantOwnerRequest" });
+var TransportKind = z.enum(["memory", "ws-peer", "tcp", "mqtt", "meshtastic", "meshcore"]);
+var LinkState = z.enum(["requested", "up", "down"]);
+var LinkQuality = z.object({
+  latencyMs: z.number().nonnegative().optional(),
+  rssi: z.number().optional()
+});
+var Link = z.object({
+  id: LinkId,
+  aNodeId: NodeId,
+  bNodeId: NodeId,
+  transport: TransportKind,
+  state: LinkState,
+  quality: LinkQuality,
+  lastSeenAt: Timestamp.nullable(),
+  ...EntityAudit
+}).refine((link) => link.aNodeId !== link.bNodeId, "A link must connect two different nodes").meta({ id: "Link", description: "Transport-level adjacency between two nodes \u2014 the edges of the topology." });
+z.object({ aNodeId: NodeId, bNodeId: NodeId, transport: TransportKind }).refine((body) => body.aNodeId !== body.bNodeId, "A link must connect two different nodes").meta({ id: "CreateLinkRequest" });
+var NodeStatus = z.enum(["online", "degraded", "offline"]);
+var Node = z.object({
+  id: NodeId,
+  name: DisplayName,
+  publicKey: z.string().min(1),
+  /** Base URL where other nodes and clients reach this node, e.g. `https://node-a.example:7700` (ADR-0017). */
+  endpoint: z.url().nullable(),
+  status: NodeStatus,
+  metadata: Metadata,
+  lastSeenAt: Timestamp.nullable(),
+  ...EntityAudit
+}).meta({ id: "Node", description: "A physical or virtual endpoint connected to the mesh." });
+z.object({
+  name: DisplayName.optional(),
+  endpoint: z.url().nullable().optional(),
+  metadata: Metadata.optional()
+}).refine((body) => Object.keys(body).length > 0, "At least one field must be provided").meta({ id: "UpdateNodeRequest" });
+var Organization = z.object({
+  id: OrganizationId,
+  nodeId: NodeId,
+  name: DisplayName,
+  slug: Slug,
+  metadata: Metadata,
+  ...EntityAudit
+}).meta({ id: "Organization", description: "A logical boundary on a node that owns policies, identities and agents." });
+z.object({
+  name: DisplayName,
+  /** Derived from `name` when omitted. */
+  slug: Slug.optional(),
+  metadata: Metadata.optional(),
+  /** Principal to make the first org owner; defaults to the caller. */
+  ownerPrincipalId: PrincipalId.optional()
+}).meta({ id: "CreateOrganizationRequest" });
+z.object({
+  name: DisplayName.optional(),
+  metadata: Metadata.optional()
+}).refine((body) => Object.keys(body).length > 0, "At least one field must be provided").meta({ id: "UpdateOrganizationRequest" });
+var TaskStatus = z.enum(["requested", "accepted", "completed", "failed"]);
+var TaskParty = z.object({ agentId: AgentId, organizationId: OrganizationId, nodeId: NodeId });
+var TaskAssignee = z.object({ organizationId: OrganizationId, nodeId: NodeId, meshAgentId: AgentId });
+var TaskStep = z.object({
+  name: z.enum(["observe", "reason", "act", "verify"]),
+  at: Timestamp,
+  summary: z.string().max(1e3)
+});
+var TaskError = z.object({ code: z.string().max(64), message: z.string().max(1e3) });
+var Task = z.object({
+  id: TaskId,
+  capability: CapabilityName,
+  input: Metadata,
+  status: TaskStatus,
+  requester: TaskParty,
+  /** The requester organization's Mesh Agent, the first hop of the route. */
+  requesterMeshAgentId: AgentId,
+  assignee: TaskAssignee,
+  /** The agent that does the work, chosen by the assignee's Mesh Agent on acceptance. */
+  provider: TaskParty.nullable(),
+  output: Metadata.nullable(),
+  error: TaskError.nullable(),
+  steps: z.array(TaskStep).max(32),
+  /** Model that produced the result; null when a rule-based model did. */
+  model: z.string().max(100).nullable(),
+  version: Version,
+  createdAt: Timestamp,
+  updatedAt: Timestamp
+}).meta({
+  id: "Task",
+  description: "A capability request routed through Mesh Agents, with its result and provenance (ADR-0020)."
+});
+z.object({
+  capability: CapabilityName,
+  input: Metadata.default({})
+}).meta({ id: "RequestTaskRequest" });
+z.object({
+  agentId: AgentId,
+  agentName: z.string(),
+  organizationId: OrganizationId,
+  organizationName: z.string(),
+  nodeId: NodeId,
+  /** Running, on a node that is not offline — i.e. a task could be routed to it now. */
+  available: z.boolean()
+}).meta({ id: "CapabilityProvider" });
+
+// ../contracts/src/events.ts
+var subject = (kind, id2) => z.object({ kind: z.literal(kind), id: id2, version: Version });
+var NodeSubject = subject("node", NodeId);
+var OrganizationSubject = subject("organization", OrganizationId);
+var AgentSubject = subject("agent", AgentId);
+var LinkSubject = subject("link", LinkId);
+var RoleBindingSubject = subject("roleBinding", RoleBindingId);
+var TaskSubject = subject("task", TaskId);
+var event = (type, subjectSchema, payload) => z.object({ type: z.literal(type), subject: subjectSchema, payload });
+var AgentRegistration = z.object({
+  meshAgentId: AgentId,
+  agentId: AgentId,
+  organizationId: OrganizationId,
+  nodeId: NodeId
+});
+var NodeCreated = event("node.created", NodeSubject, z.object({ node: Node }));
+var NodeUpdated = event("node.updated", NodeSubject, z.object({ node: Node }));
+var NodeRemoved = event("node.removed", NodeSubject, z.object({ nodeId: NodeId }));
+var NodeStatusChanged = event(
+  "node.status_changed",
+  NodeSubject,
+  z.object({ nodeId: NodeId, status: NodeStatus, previousStatus: NodeStatus, lastSeenAt: Timestamp.nullable() })
+);
+var NodeHeartbeat = event("node.heartbeat", NodeSubject, z.object({ nodeId: NodeId, at: Timestamp }));
+var OrganizationCreated = event(
+  "organization.created",
+  OrganizationSubject,
+  z.object({ organization: Organization })
+);
+var OrganizationUpdated = event(
+  "organization.updated",
+  OrganizationSubject,
+  z.object({ organization: Organization })
+);
+var OrganizationRemoved = event(
+  "organization.removed",
+  OrganizationSubject,
+  z.object({ organizationId: OrganizationId, nodeId: NodeId })
+);
+var AgentCreated = event("agent.created", AgentSubject, z.object({ agent: Agent }));
+var AgentUpdated = event("agent.updated", AgentSubject, z.object({ agent: Agent }));
+var AgentStatusChanged = event(
+  "agent.status_changed",
+  AgentSubject,
+  z.object({ agent: Agent, previousStatus: AgentStatus })
+);
+var AgentRemoved = event(
+  "agent.removed",
+  AgentSubject,
+  z.object({ agentId: AgentId, organizationId: OrganizationId, nodeId: NodeId })
+);
+var MeshAgentAgentRegistered = event("mesh_agent.agent_registered", AgentSubject, AgentRegistration);
+var MeshAgentAgentDeregistered = event("mesh_agent.agent_deregistered", AgentSubject, AgentRegistration);
+var LinkRequested = event("link.requested", LinkSubject, z.object({ link: Link }));
+var LinkUp = event("link.up", LinkSubject, z.object({ link: Link }));
+var LinkUpdated = event("link.updated", LinkSubject, z.object({ link: Link }));
+var LinkDown = event("link.down", LinkSubject, z.object({ link: Link }));
+var LinkRemoved = event("link.removed", LinkSubject, z.object({ linkId: LinkId }));
+var RoleGranted = event("role.granted", RoleBindingSubject, z.object({ binding: RoleBinding }));
+var RoleRevoked = event("role.revoked", RoleBindingSubject, z.object({ binding: RoleBinding }));
+var TaskRequested = event("task.requested", TaskSubject, z.object({ task: Task }));
+var TaskAccepted = event("task.accepted", TaskSubject, z.object({ task: Task }));
+var TaskCompleted = event("task.completed", TaskSubject, z.object({ task: Task }));
+var TaskFailed = event("task.failed", TaskSubject, z.object({ task: Task }));
+var DomainEvent = z.discriminatedUnion("type", [
+  NodeCreated,
+  NodeUpdated,
+  NodeRemoved,
+  NodeStatusChanged,
+  NodeHeartbeat,
+  OrganizationCreated,
+  OrganizationUpdated,
+  OrganizationRemoved,
+  AgentCreated,
+  AgentUpdated,
+  AgentStatusChanged,
+  AgentRemoved,
+  MeshAgentAgentRegistered,
+  MeshAgentAgentDeregistered,
+  LinkRequested,
+  LinkUp,
+  LinkUpdated,
+  LinkDown,
+  LinkRemoved,
+  RoleGranted,
+  RoleRevoked,
+  TaskRequested,
+  TaskAccepted,
+  TaskCompleted,
+  TaskFailed
+]).meta({ id: "DomainEvent" });
+DomainEvent.options.map((o) => o.shape.type.value);
+var ENVELOPE_VERSION = 1;
+var EnvelopeMeta = z.object({
+  v: z.literal(ENVELOPE_VERSION),
+  id: EventId,
+  /** Monotonic per origin node; `(origin.nodeId, seq)` is the replication cursor. */
+  seq: z.int().min(1),
+  origin: z.object({ nodeId: NodeId, principalId: PrincipalId.nullable() }),
+  /** Groups the events produced by one command, e.g. a cascade (ADR-0005). */
+  causationId: CommandId,
+  timestamp: Timestamp,
+  /** Ed25519 signature over the canonical encoding; attached by the protocol layer (Phase 5). */
+  sig: z.string().nullable()
+});
+var MeshEvent = z.intersection(EnvelopeMeta, DomainEvent).meta({ id: "MeshEvent" });
+z.object({
+  status: z.enum(["ok", "degraded"]),
+  service: z.literal("node-server"),
+  /** The node this server runs as — clients use it to know where their writes are accepted (ADR-0004). */
+  nodeId: NodeId,
+  version: z.string(),
+  uptimeSeconds: z.number().nonnegative(),
+  timestamp: z.iso.datetime()
+}).meta({ id: "HealthResponse", description: "Liveness and version information for a Node Server." });
+z.object({ principal: Principal, roles: z.array(RoleBinding) }).meta({ id: "Me", description: "The authenticated principal and its role bindings." });
+z.object({ name: DisplayName, kind: PrincipalKind.default("user") }).meta({ id: "CreatePrincipalRequest" });
+var Credential = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("token"), token: z.string(), expiresAt: Timestamp }),
+  z.object({ type: z.literal("apiKey"), apiKey: z.string() })
+]).meta({ id: "Credential" });
+z.object({ principal: Principal, credential: Credential }).meta({ id: "CreatePrincipalResponse" });
+var MeshCursor = z.record(NodeId, z.int().min(0)).meta({ id: "MeshCursor" });
+z.object({
+  nodes: z.array(Node),
+  organizations: z.array(Organization),
+  agents: z.array(Agent),
+  links: z.array(Link),
+  /** The most recent tasks, newest first (ADR-0020). */
+  tasks: z.array(Task),
+  cursor: MeshCursor
+}).meta({ id: "MeshSnapshot", description: "Full mesh state plus the cursor to resume the event stream from." });
+z.object({
+  nodes: z.int().min(0),
+  online: z.int().min(0),
+  degraded: z.int().min(0),
+  offline: z.int().min(0),
+  organizations: z.int().min(0),
+  agents: z.int().min(0)
+}).meta({ id: "MeshStats", description: "Counters shown in the Monitor's mesh summary." });
+z.object({
+  node: Node,
+  organizations: z.array(Organization),
+  agents: z.array(Agent),
+  /** Distinct capabilities offered by the node's agents. */
+  capabilities: z.array(Capability)
+}).meta({ id: "NodeDetail", description: "Everything the Monitor's node detail panel shows (ui.md)." });
+function encodeCursor(cursor) {
+  const bytes = new TextEncoder().encode(JSON.stringify(cursor));
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeCursor(encoded) {
+  const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
+  const bytes = Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+  return MeshCursor.parse(JSON.parse(new TextDecoder().decode(bytes)));
+}
+
+// ../contracts/src/projection.ts
+function project(event2) {
+  switch (event2.type) {
+    case "node.created":
+    case "node.updated":
+      return { op: "upsert", kind: "node", entity: event2.payload.node };
+    case "node.removed":
+      return { op: "delete", kind: "node", id: event2.payload.nodeId };
+    case "node.status_changed":
+      return {
+        op: "presence",
+        nodeId: event2.payload.nodeId,
+        status: event2.payload.status,
+        lastSeenAt: event2.payload.lastSeenAt
+      };
+    case "organization.created":
+    case "organization.updated":
+      return { op: "upsert", kind: "organization", entity: event2.payload.organization };
+    case "organization.removed":
+      return { op: "delete", kind: "organization", id: event2.payload.organizationId };
+    case "agent.created":
+    case "agent.updated":
+    case "agent.status_changed":
+      return { op: "upsert", kind: "agent", entity: event2.payload.agent };
+    case "agent.removed":
+      return { op: "delete", kind: "agent", id: event2.payload.agentId };
+    case "link.requested":
+    case "link.up":
+    case "link.updated":
+    case "link.down":
+      return { op: "upsert", kind: "link", entity: event2.payload.link };
+    case "link.removed":
+      return { op: "delete", kind: "link", id: event2.payload.linkId };
+    case "role.granted":
+      return { op: "upsert", kind: "roleBinding", entity: event2.payload.binding };
+    case "role.revoked":
+      return { op: "delete", kind: "roleBinding", id: event2.payload.binding.id };
+    case "task.requested":
+    case "task.accepted":
+    case "task.completed":
+    case "task.failed":
+      return { op: "upsert", kind: "task", entity: event2.payload.task };
+    // Registration is implied by organization membership; heartbeats are handled by the presence detector.
+    case "mesh_agent.agent_registered":
+    case "mesh_agent.agent_deregistered":
+    case "node.heartbeat":
+      return { op: "none" };
+  }
+}
+
+// ../contracts/src/mesh-state.ts
+var byId = (items) => Object.fromEntries(items.map((item) => [item.id, item]));
+function meshStateFromSnapshot(snapshot) {
+  return {
+    nodes: byId(snapshot.nodes),
+    organizations: byId(snapshot.organizations),
+    agents: byId(snapshot.agents),
+    links: byId(snapshot.links),
+    // Nodes from before Phase 6 send no tasks; tolerate them during rolling upgrades.
+    tasks: byId(snapshot.tasks ?? []),
+    cursor: { ...snapshot.cursor }
+  };
+}
+function applyMeshEvent(state, event2) {
+  const seen = state.cursor[event2.origin.nodeId] ?? 0;
+  if (event2.seq <= seen) return state;
+  const cursor = { ...state.cursor, [event2.origin.nodeId]: event2.seq };
+  const op = project(event2);
+  switch (op.op) {
+    case "upsert":
+      switch (op.kind) {
+        case "node":
+          return { ...state, cursor, nodes: { ...state.nodes, [op.entity.id]: op.entity } };
+        case "organization":
+          return { ...state, cursor, organizations: { ...state.organizations, [op.entity.id]: op.entity } };
+        case "agent":
+          return { ...state, cursor, agents: { ...state.agents, [op.entity.id]: op.entity } };
+        case "link":
+          return { ...state, cursor, links: { ...state.links, [op.entity.id]: op.entity } };
+        case "roleBinding":
+          return { ...state, cursor };
+        case "task": {
+          const current = state.tasks[op.entity.id];
+          if (current && current.version >= op.entity.version) return { ...state, cursor };
+          return { ...state, cursor, tasks: { ...state.tasks, [op.entity.id]: op.entity } };
+        }
+      }
+      break;
+    case "delete": {
+      if (op.kind === "roleBinding") return { ...state, cursor };
+      const table = { node: "nodes", organization: "organizations", agent: "agents", link: "links" };
+      const key = table[op.kind];
+      const { [op.id]: _removed, ...rest } = state[key];
+      return { ...state, cursor, [key]: rest };
+    }
+    case "presence": {
+      const node = state.nodes[op.nodeId];
+      if (!node) return { ...state, cursor };
+      return {
+        ...state,
+        cursor,
+        nodes: { ...state.nodes, [node.id]: { ...node, status: op.status, lastSeenAt: op.lastSeenAt } }
+      };
+    }
+    case "none":
+      return { ...state, cursor };
+  }
+}
+z.object({
+  limit: z.coerce.number().int().min(1).max(200).default(50),
+  cursor: z.string().min(1).optional()
+});
+z.object({
+  type: z.string().meta({ example: "/problems/forbidden" }),
+  title: z.string(),
+  status: z.int().min(400).max(599),
+  detail: z.string().optional(),
+  instance: z.string().optional(),
+  code: z.string().meta({ description: "Stable machine-readable error code" }),
+  errors: z.array(z.object({ path: z.string(), message: z.string() })).optional()
+}).meta({ id: "ProblemDetails" });
+var Topic = z.enum(["node", "organization", "agent", "link", "roleBinding", "task"]);
+z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("hello"),
+    /** Bearer token or API key — sent in the first frame because browsers cannot set WebSocket headers. */
+    token: z.string().min(1),
+    /** Resume point, usually the cursor of the snapshot the client just loaded. */
+    cursor: MeshCursor.optional(),
+    topics: z.array(Topic).optional()
+  }),
+  z.object({ type: z.literal("subscribe"), topics: z.array(Topic) })
+]);
+z.discriminatedUnion("type", [
+  z.object({ type: z.literal("welcome"), principalId: PrincipalId, cursor: MeshCursor }),
+  z.object({ type: z.literal("event"), event: MeshEvent }),
+  z.object({ type: z.literal("resync.required"), reason: z.string() }),
+  z.object({ type: z.literal("error"), code: z.string(), message: z.string() })
+]);
+var RealtimeCloseCode = {
+  normal: 1e3,
+  unauthenticated: 4401,
+  resyncRequired: 4409
+};
+
+// src/errors.ts
+var MeshApiError = class extends Error {
+  constructor(status, message, problem) {
+    super(message);
+    this.status = status;
+    this.problem = problem;
+    this.name = "MeshApiError";
+  }
+  status;
+  problem;
+  /** Stable machine-readable code, e.g. `forbidden`, `version_conflict`, `not_owner`. */
+  get code() {
+    return this.problem?.code ?? `http_${this.status}`;
+  }
+};
+
+// src/http.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+async function resolveToken(token) {
+  return typeof token === "function" ? token() : token;
+}
+var HttpClient = class {
+  constructor(options) {
+    this.options = options;
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  options;
+  baseUrl;
+  doFetch;
+  token() {
+    return resolveToken(this.options.token);
+  }
+  async request(method, path, options = {}) {
+    const headers = { accept: "application/json" };
+    const token = await this.token();
+    if (token) headers["authorization"] = `Bearer ${token}`;
+    if (options.body !== void 0) headers["content-type"] = "application/json";
+    if (options.ifMatch !== void 0) headers["if-match"] = `"${options.ifMatch}"`;
+    if (options.idempotencyKey !== void 0) headers["idempotency-key"] = options.idempotencyKey;
+    const timeout = AbortSignal.timeout(this.options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const response = await this.doFetch(`${this.baseUrl}${path}${queryString(options.query)}`, {
+      method,
+      headers,
+      ...options.body !== void 0 && { body: JSON.stringify(options.body) },
+      signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout
+    });
+    if (!response.ok) throw await toError(method, path, response);
+    if (response.status === 204) return void 0;
+    return await response.json();
+  }
+};
+function queryString(query) {
+  if (!query) return "";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) if (value !== void 0) params.set(key, String(value));
+  const text = params.toString();
+  return text ? `?${text}` : "";
+}
+async function toError(method, path, response) {
+  const text = await response.text();
+  let problem;
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed.code === "string") problem = parsed;
+  } catch {
+  }
+  const message = problem?.detail ?? problem?.title ?? `${method} ${path} failed with ${response.status}`;
+  return new MeshApiError(response.status, message, problem);
+}
+
+// src/realtime.ts
+var RealtimeError = class extends Error {
+  constructor(message, fatal) {
+    super(message);
+    this.fatal = fatal;
+    this.name = "RealtimeError";
+  }
+  fatal;
+};
+var MeshRealtime = class {
+  constructor(deps, options = {}) {
+    this.deps = deps;
+    this.options = options;
+    this.currentCursor = { ...options.cursor ?? {} };
+    this.needsSnapshot = options.cursor === void 0;
+  }
+  deps;
+  options;
+  currentStatus = "connecting";
+  currentState;
+  currentCursor;
+  needsSnapshot;
+  socket;
+  attempt = 0;
+  stopped = false;
+  timer;
+  handlers = /* @__PURE__ */ new Map();
+  statusListeners = /* @__PURE__ */ new Set();
+  stateListeners = /* @__PURE__ */ new Set();
+  errorListeners = /* @__PURE__ */ new Set();
+  get status() {
+    return this.currentStatus;
+  }
+  /** The mirrored mesh, when the stream started from (or resynced to) a snapshot. */
+  get state() {
+    return this.currentState;
+  }
+  /** Last sequence received per origin node. */
+  get cursor() {
+    return { ...this.currentCursor };
+  }
+  start() {
+    void this.connect();
+  }
+  /** Subscribes to one event type, or `"*"` for all. Returns an unsubscribe function. */
+  on(type, handler) {
+    const set = this.handlers.get(type) ?? /* @__PURE__ */ new Set();
+    set.add(handler);
+    this.handlers.set(type, set);
+    return () => set.delete(handler);
+  }
+  onStatus(listener) {
+    return subscribe(this.statusListeners, listener);
+  }
+  onState(listener) {
+    return subscribe(this.stateListeners, listener);
+  }
+  onError(listener) {
+    return subscribe(this.errorListeners, listener);
+  }
+  /** Resolves once the stream is caught up and live; rejects if it closes for good first. */
+  ready() {
+    if (this.currentStatus === "live") return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const off = this.onStatus((status) => {
+        if (status === "live") {
+          off();
+          resolve();
+        } else if (status === "closed") {
+          off();
+          reject(new RealtimeError("The realtime connection closed", true));
+        }
+      });
+    });
+  }
+  close() {
+    this.stopped = true;
+    clearTimeout(this.timer);
+    this.socket?.close(RealtimeCloseCode.normal, "client closed");
+    this.socket = void 0;
+    this.setStatus("closed");
+  }
+  async connect() {
+    if (this.stopped) return;
+    this.setStatus(this.attempt === 0 ? "connecting" : "reconnecting");
+    try {
+      if (this.needsSnapshot) await this.loadSnapshot();
+      const token = await this.deps.token();
+      if (!token) throw new RealtimeError("A token is required for the realtime stream", true);
+      if (this.stopped) return;
+      this.open(token);
+    } catch (error) {
+      const realtimeError = error instanceof RealtimeError ? error : new RealtimeError(error instanceof Error ? error.message : String(error), false);
+      this.emitError(realtimeError);
+      if (realtimeError.fatal) this.close();
+      else this.scheduleReconnect(false);
+    }
+  }
+  async loadSnapshot() {
+    const snapshot = await this.deps.snapshot();
+    this.currentState = meshStateFromSnapshot(snapshot);
+    this.currentCursor = { ...snapshot.cursor };
+    this.needsSnapshot = false;
+    this.emitState();
+  }
+  open(token) {
+    const Socket = this.deps.WebSocket ?? globalThis.WebSocket;
+    if (!Socket) throw new RealtimeError("No WebSocket implementation available; pass one in the client options", true);
+    const socket = new Socket(`${this.deps.baseUrl.replace(/^http/, "ws")}/v1/realtime`);
+    this.socket = socket;
+    socket.onopen = () => socket.send(
+      JSON.stringify({
+        type: "hello",
+        token,
+        cursor: this.currentCursor,
+        ...this.options.topics && { topics: this.options.topics }
+      })
+    );
+    socket.onmessage = (event2) => this.onMessage(String(event2.data));
+    socket.onclose = (event2) => {
+      if (this.socket === socket) this.onClose(event2.code);
+    };
+    socket.onerror = () => {
+    };
+  }
+  onMessage(raw) {
+    let message;
+    try {
+      message = JSON.parse(raw);
+    } catch {
+      this.emitError(new RealtimeError("Received a malformed message", false));
+      return;
+    }
+    switch (message.type) {
+      case "event":
+        this.onEvent(message.event);
+        break;
+      case "welcome":
+        this.attempt = 0;
+        this.setStatus("live");
+        break;
+      case "resync.required":
+        this.needsSnapshot = true;
+        break;
+      case "error":
+        this.emitError(new RealtimeError(`${message.code}: ${message.message}`, message.code === "unauthenticated"));
+        break;
+    }
+  }
+  onEvent(event2) {
+    const seen = this.currentCursor[event2.origin.nodeId] ?? 0;
+    if (event2.seq <= seen) return;
+    this.currentCursor = { ...this.currentCursor, [event2.origin.nodeId]: event2.seq };
+    if (this.currentState) this.currentState = applyMeshEvent(this.currentState, event2);
+    for (const handler of [...this.handlers.get(event2.type) ?? [], ...this.handlers.get("*") ?? []]) handler(event2);
+    this.emitState();
+  }
+  onClose(code) {
+    this.socket = void 0;
+    if (this.stopped) return;
+    if (code === RealtimeCloseCode.unauthenticated) {
+      this.emitError(new RealtimeError("The node rejected the credential", true));
+      this.close();
+      return;
+    }
+    this.scheduleReconnect(code === RealtimeCloseCode.resyncRequired);
+  }
+  scheduleReconnect(immediately) {
+    if (this.options.reconnect === false) {
+      this.close();
+      return;
+    }
+    const { initialDelayMs = 500, maxDelayMs = 3e4 } = this.options.reconnect ?? {};
+    const ceiling = Math.min(maxDelayMs, initialDelayMs * 2 ** this.attempt);
+    const delay = immediately ? 0 : Math.round((this.options.random ?? Math.random)() * ceiling);
+    this.attempt += 1;
+    this.setStatus("reconnecting");
+    this.timer = setTimeout(() => void this.connect(), delay);
+  }
+  setStatus(status) {
+    if (status === this.currentStatus) return;
+    this.currentStatus = status;
+    for (const listener of this.statusListeners) listener(status);
+  }
+  emitState() {
+    const state = this.currentState;
+    if (state) for (const listener of this.stateListeners) listener(state);
+  }
+  emitError(error) {
+    for (const listener of this.errorListeners) listener(error);
+  }
+};
+function subscribe(set, listener) {
+  set.add(listener);
+  return () => set.delete(listener);
+}
+
+// src/client.ts
+var id = encodeURIComponent;
+async function* all(fetchPage) {
+  let cursor;
+  do {
+    const page = await fetchPage(cursor);
+    yield* page.items;
+    cursor = page.nextCursor ?? void 0;
+  } while (cursor);
+}
+function ownersOf(http, base) {
+  return {
+    list: async () => (await http.request("GET", `${base}/owners`)).items,
+    grant: (principalId, options = {}) => http.request("POST", `${base}/owners`, { body: { principalId }, ...options }),
+    revoke: (principalId) => http.request("DELETE", `${base}/owners/${id(principalId)}`)
+  };
+}
+function createMeshClient(options) {
+  const http = new HttpClient(options);
+  const client = {
+    /** Liveness and version (public). */
+    health: () => http.request("GET", "/v1/health"),
+    /** The caller and their ownership roles. */
+    me: () => http.request("GET", "/v1/me"),
+    snapshot: () => http.request("GET", "/v1/mesh/snapshot"),
+    stats: () => http.request("GET", "/v1/mesh/stats"),
+    capabilities: async (search) => (await http.request("GET", "/v1/capabilities", { query: { q: search } })).items,
+    /** Agents offering a capability, available ones first (ADR-0020). */
+    capabilityProviders: async (name) => (await http.request("GET", `/v1/capabilities/${id(name)}/providers`)).items,
+    principals: {
+      /** Node owners only. The credential is returned exactly once. */
+      create: (input, options2 = {}) => http.request("POST", "/v1/principals", { body: input, ...options2 })
+    },
+    nodes: {
+      list: (page = {}) => http.request("GET", "/v1/nodes", { query: { ...page } }),
+      all: () => all((cursor) => client.nodes.list({ cursor })),
+      get: (nodeId) => http.request("GET", `/v1/nodes/${id(nodeId)}`),
+      detail: (nodeId) => http.request("GET", `/v1/nodes/${id(nodeId)}/detail`),
+      organizations: (nodeId, page = {}) => http.request("GET", `/v1/nodes/${id(nodeId)}/organizations`, { query: { ...page } }),
+      update: (nodeId, changes, options2 = {}) => http.request("PATCH", `/v1/nodes/${id(nodeId)}`, { body: changes, ...options2 }),
+      /** Removes the node and, children first, everything on it. */
+      remove: (nodeId, options2 = {}) => http.request("DELETE", `/v1/nodes/${id(nodeId)}`, options2),
+      owners: (nodeId) => ownersOf(http, `/v1/nodes/${id(nodeId)}`),
+      /** Forgets an offline remote node, with its organizations, agents and links (owners of this node). */
+      forget: (nodeId) => http.request("POST", `/v1/nodes/${id(nodeId)}/forget`)
+    },
+    links: {
+      list: async () => (await http.request("GET", "/v1/links")).items,
+      /** Connects the node this client talks to with a peer, by URL or by the peer's node id (its advertised endpoint). */
+      connect: (target, options2 = {}) => http.request("POST", "/v1/links", { body: target, ...options2 }),
+      /** Disconnects the peer at the other end and removes the link. */
+      remove: (linkId) => http.request("DELETE", `/v1/links/${id(linkId)}`)
+    },
+    organizations: {
+      /** Creates an organization (and its Mesh Agent) on the node this client talks to. */
+      create: (input, options2 = {}) => http.request("POST", "/v1/organizations", { body: input, ...options2 }),
+      list: (filter = {}) => http.request("GET", "/v1/organizations", { query: { ...filter } }),
+      all: (filter = {}) => all((cursor) => client.organizations.list({ ...filter, cursor })),
+      get: (organizationId) => http.request("GET", `/v1/organizations/${id(organizationId)}`),
+      update: (organizationId, changes, options2 = {}) => http.request("PATCH", `/v1/organizations/${id(organizationId)}`, { body: changes, ...options2 }),
+      /** Removes the organization and all of its agents. */
+      remove: (organizationId, options2 = {}) => http.request("DELETE", `/v1/organizations/${id(organizationId)}`, options2),
+      owners: (organizationId) => ownersOf(http, `/v1/organizations/${id(organizationId)}`)
+    },
+    agents: {
+      /** Creates an agent; it is registered with its organization's Mesh Agent automatically. */
+      create: (organizationId, input, options2 = {}) => http.request("POST", `/v1/organizations/${id(organizationId)}/agents`, { body: input, ...options2 }),
+      list: (filter = {}) => http.request("GET", "/v1/agents", { query: { ...filter } }),
+      all: (filter = {}) => all((cursor) => client.agents.list({ ...filter, cursor })),
+      get: (agentId) => http.request("GET", `/v1/agents/${id(agentId)}`),
+      update: (agentId, changes, options2 = {}) => http.request("PATCH", `/v1/agents/${id(agentId)}`, { body: changes, ...options2 }),
+      /** Deregisters the agent from its Mesh Agent, then removes it. */
+      remove: (agentId, options2 = {}) => http.request("DELETE", `/v1/agents/${id(agentId)}`, options2),
+      start: (agentId) => http.request("POST", `/v1/agents/${id(agentId)}/start`),
+      stop: (agentId) => http.request("POST", `/v1/agents/${id(agentId)}/stop`)
+    },
+    tasks: {
+      /**
+       * Asks the mesh for a capability on behalf of `agentId` (node or org owners). The agent's Mesh Agent routes the
+       * request; the returned task is `requested`, and the provider's node completes it (ADR-0020).
+       */
+      request: (agentId, input, options2 = {}) => http.request("POST", `/v1/agents/${id(agentId)}/tasks`, { body: input, ...options2 }),
+      /** Newest first. */
+      list: (filter = {}) => http.request("GET", "/v1/tasks", { query: { ...filter } }),
+      all: (filter = {}) => all((cursor) => client.tasks.list({ ...filter, cursor })),
+      get: (taskId) => http.request("GET", `/v1/tasks/${id(taskId)}`),
+      /** Resolves with the task once it is `completed` or `failed`; rejects after `timeoutMs`. */
+      wait: async (taskId, waitOptions = {}) => {
+        const deadline = Date.now() + (waitOptions.timeoutMs ?? 3e4);
+        for (; ; ) {
+          const task = await client.tasks.get(taskId);
+          if (task.status === "completed" || task.status === "failed") return task;
+          if (Date.now() >= deadline) throw new Error(`Task ${taskId} still ${task.status} after waiting`);
+          await new Promise((resolve) => setTimeout(resolve, waitOptions.intervalMs ?? 250));
+        }
+      }
+    },
+    realtime: {
+      /**
+       * Opens the realtime stream. Without a `cursor` it first loads a snapshot and keeps `state` current;
+       * it reconnects with backoff and resumes from the last event it saw.
+       */
+      connect: (realtimeOptions = {}) => {
+        const realtime = new MeshRealtime(
+          { baseUrl: http.baseUrl, token: () => http.token(), snapshot: client.snapshot, WebSocket: options.WebSocket },
+          realtimeOptions
+        );
+        realtime.start();
+        return realtime;
+      }
+    }
+  };
+  return client;
+}
+
+export { MeshApiError, MeshRealtime, RealtimeError, applyMeshEvent, createMeshClient, decodeCursor, encodeCursor, meshStateFromSnapshot };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map