@synap-core/cli 1.11.0 → 1.12.2

package/node_modules/@synap/hub-rest-client/dist/index.cjs

@@ -1,1261 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  HubApiError: () => HubApiError,
-  HubRestClient: () => HubRestClient,
-  checkPodHealth: () => checkPodHealth,
-  setupAgent: () => setupAgent
-});
-module.exports = __toCommonJS(index_exports);
-
-// src/errors.ts
-var HubApiError = class extends Error {
-  constructor(message, statusCode, body) {
-    super(message);
-    this.statusCode = statusCode;
-    this.body = body;
-    this.name = "HubApiError";
-  }
-  get isUnauthorized() {
-    return this.statusCode === 401;
-  }
-  get isForbidden() {
-    return this.statusCode === 403;
-  }
-  get isNotFound() {
-    return this.statusCode === 404;
-  }
-  get isServerError() {
-    return this.statusCode >= 500;
-  }
-};
-
-// src/client.ts
-function normalizeUrl(url) {
-  return url.replace(/\/$/, "");
-}
-function formatHubErrorMessage(status, statusText, errorBody) {
-  let detail = "";
-  if (errorBody && typeof errorBody === "object" && "error" in errorBody) {
-    detail = String(errorBody.error);
-  }
-  const base = `Hub API error: ${status} ${statusText}`;
-  let msg = detail ? `${base} \u2014 ${detail}` : base;
-  if (status === 403 && /hub-protocol\.write/i.test(detail)) {
-    msg += " Create or reconnect an API key that includes the hub-protocol.write scope (Settings \u2192 API keys on your pod).";
-  }
-  return msg;
-}
-function unwrapList(result) {
-  return Array.isArray(result) ? result : result.data ?? [];
-}
-function unwrapWorkspacesResponse(result) {
-  if (Array.isArray(result)) return result;
-  if (result && typeof result === "object" && "workspaces" in result) {
-    const w = result.workspaces;
-    return Array.isArray(w) ? w : [];
-  }
-  return unwrapList(result);
-}
-function unwrapSingle(result) {
-  if (result && typeof result === "object" && "data" in result) {
-    return result.data;
-  }
-  return result;
-}
-var HubRestClient = class {
-  base;
-  headers;
-  timeoutMs;
-  readTimeoutMs;
-  writeTimeoutMs;
-  maxAttempts;
-  workspaceId;
-  /** Cached from GET /users/me — avoids repeated identity calls. */
-  resolvedUserId = null;
-  constructor(config) {
-    this.base = normalizeUrl(config.podUrl);
-    this.headers = {
-      Authorization: `Bearer ${config.apiKey}`,
-      "Content-Type": "application/json"
-    };
-    this.workspaceId = config.workspaceId;
-    this.timeoutMs = config.timeoutMs ?? 3e4;
-    this.readTimeoutMs = config.readTimeoutMs ?? this.timeoutMs;
-    this.writeTimeoutMs = config.writeTimeoutMs ?? this.timeoutMs;
-    this.maxAttempts = Math.max(1, config.maxAttempts ?? 3);
-  }
-  /** User id for the current API key (Hub REST requires userId on several GETs). */
-  async resolveUserId() {
-    if (this.resolvedUserId) return this.resolvedUserId;
-    const me = await this.getMe();
-    this.resolvedUserId = me.id;
-    return me.id;
-  }
-  /**
-   * The ONE shared request loop. Per-method timeout (GET = read, else write, or a
-   * caller override) + up to `maxAttempts` with exponential backoff. Retries ONLY
-   * on a network failure or 5xx; NEVER on a 4xx or a caller abort. Returns the raw
-   * `Response` for any non-5xx (ok OR 4xx) — the typed entry points below decide
-   * how to interpret it. This is the single source of retry/timeout truth, shared
-   * by the CLI and the IS's `ISHubClient` (which reuses the protected entry points
-   * rather than re-implementing fetch).
-   */
-  async fetchWithRetry(method, path, body, signal, timeoutMsOverride) {
-    const url = `${this.base}${path}`;
-    const perAttemptTimeout = timeoutMsOverride ?? (method.toUpperCase() === "GET" ? this.readTimeoutMs : this.writeTimeoutMs);
-    let lastError;
-    for (let attempt = 0; attempt < this.maxAttempts; attempt++) {
-      if (attempt > 0) {
-        await new Promise((r) => setTimeout(r, 1e3 * attempt));
-      }
-      const timeout = AbortSignal.timeout(perAttemptTimeout);
-      const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
-      try {
-        const res = await fetch(url, {
-          method,
-          headers: this.headers,
-          body: body !== void 0 ? JSON.stringify(body) : void 0,
-          signal: combined
-        });
-        if (res.status < 500) return res;
-        lastError = new Error(`HTTP ${res.status}`);
-      } catch (err) {
-        if (signal?.aborted) throw err;
-        lastError = err;
-      }
-    }
-    throw lastError;
-  }
-  /** Build a HubApiError from a non-ok Response (reads the JSON error body). */
-  async toHubError(res) {
-    const errorBody = await res.json().catch(() => ({}));
-    return new HubApiError(
-      formatHubErrorMessage(res.status, res.statusText, errorBody),
-      res.status,
-      errorBody
-    );
-  }
-  /** Parse a 2xx body, tolerating an empty/204 response (returns undefined). */
-  async parseBody(res) {
-    const text = await res.text();
-    return text ? JSON.parse(text) : void 0;
-  }
-  /**
-   * Typed JSON request — throws `HubApiError` on any non-2xx. Protected so the IS
-   * subclass reuses it. Tolerates an empty/204 body (returns `undefined`).
-   */
-  async request(method, path, body, signal) {
-    const res = await this.fetchWithRetry(method, path, body, signal);
-    if (!res.ok) throw await this.toHubError(res);
-    return this.parseBody(res);
-  }
-  /**
-   * Like `request<T>` but returns `null` on 404/403 (the "absent/forbidden →
-   * empty" contract several IS reads use) instead of throwing.
-   */
-  async requestOrNull(method, path, body, signal) {
-    const res = await this.fetchWithRetry(method, path, body, signal);
-    if (res.status === 404 || res.status === 403) return null;
-    if (!res.ok) throw await this.toHubError(res);
-    return this.parseBody(res);
-  }
-  /**
-   * The raw `Response` (same retry/timeout infra), for the few callers that read
-   * `.text()`, branch on status themselves, or need a per-call timeout override.
-   */
-  async requestRaw(method, path, body, signal, timeoutMsOverride) {
-    return this.fetchWithRetry(method, path, body, signal, timeoutMsOverride);
-  }
-  // ─── Identity ─────────────────────────────────────────────────────────────
-  async getMe() {
-    return this.request("GET", "/api/hub/users/me");
-  }
-  async getWorkspaces() {
-    const result = await this.request("GET", "/api/hub/workspaces");
-    return unwrapWorkspacesResponse(result);
-  }
-  async provisionAgentWorkspace(input) {
-    return this.request(
-      "POST",
-      "/api/hub/workspaces/provision-agent",
-      input
-    );
-  }
-  /**
-   * Get full activity context for a user — recent entities, active threads, workspace summary.
-   * Use at session start to orient the agent to the user's current state.
-   */
-  async getUserContext(userId, options) {
-    const params = new URLSearchParams();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    if (wsId) params.set("workspaceId", wsId);
-    const qs = params.toString() ? `?${params}` : "";
-    return this.request(
-      "GET",
-      `/api/hub/users/${userId}/context${qs}`
-    );
-  }
-  // ─── Entities ─────────────────────────────────────────────────────────────
-  async searchEntities(query, options, signal) {
-    const params = new URLSearchParams({ q: query });
-    if (options?.profileSlug) params.set("profileSlug", options.profileSlug);
-    if (options?.scope !== "all") {
-      const wsId = options?.workspaceId ?? this.workspaceId;
-      if (wsId) params.set("workspaceId", wsId);
-    }
-    if (options?.limit) params.set("limit", String(options.limit));
-    const result = await this.request(
-      "GET",
-      `/api/hub/entities?${params}`,
-      void 0,
-      signal
-    );
-    return unwrapList(result);
-  }
-  async getEntity(id) {
-    const result = await this.request(
-      "GET",
-      `/api/hub/entities/${id}`
-    );
-    return unwrapSingle(result);
-  }
-  async getRecentEntities(options) {
-    const params = new URLSearchParams({
-      sort: "updatedAt:desc",
-      limit: String(options?.limit ?? 20)
-    });
-    if (options?.profileSlug) params.set("profileSlug", options.profileSlug);
-    if (options?.scope !== "all") {
-      const wsId = options?.workspaceId ?? this.workspaceId;
-      if (wsId) params.set("workspaceId", wsId);
-    }
-    const result = await this.request(
-      "GET",
-      `/api/hub/entities?${params}`
-    );
-    return unwrapList(result);
-  }
-  async createEntity(input) {
-    const { content, url, status, priority, dueDate, properties, ...rest } = input;
-    return this.request("POST", "/api/hub/entities", {
-      ...rest,
-      // Entity placement is a write decision, never an ambient client default.
-      // Omitted means pod/base behavior; an explicit workspace opts into its
-      // overlay/membership lens. This deliberately differs from read helpers.
-      ...rest.workspaceId ? { workspaceId: rest.workspaceId } : {},
-      ...content !== void 0 ? { content } : {},
-      properties: {
-        ...properties,
-        ...url !== void 0 ? { url } : {},
-        ...status !== void 0 ? { status } : {},
-        ...priority !== void 0 ? { priority } : {},
-        ...dueDate !== void 0 ? { dueDate } : {}
-      }
-    });
-  }
-  async updateEntity(id, input) {
-    const { properties, content, url, status, priority, dueDate, ...rest } = input;
-    return this.request(
-      "PATCH",
-      `/api/hub/entities/${id}`,
-      {
-        ...rest,
-        metadata: {
-          ...properties,
-          ...content !== void 0 ? { content } : {},
-          ...url !== void 0 ? { url } : {},
-          ...status !== void 0 ? { status } : {},
-          ...priority !== void 0 ? { priority } : {},
-          ...dueDate !== void 0 ? { dueDate } : {}
-        }
-      }
-    );
-  }
-  // ─── Unified Search ───────────────────────────────────────────────────────
-  /**
-   * Unified full-text search across entities, documents, and views.
-   * Use when you don't know the content type. For entity-only search use searchEntities().
-   *
-   * Note: The backend GET /search requires userId as a query param; this method resolves
-   * the current user automatically.
-   */
-  async search(query, options, signal) {
-    const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams({ userId, query });
-    if (wsId) params.set("workspaceId", wsId);
-    if (options?.collections?.length)
-      params.set("collections", options.collections.join(","));
-    if (options?.limit) params.set("limit", String(options.limit));
-    return this.request(
-      "GET",
-      `/api/hub/search?${params}`,
-      void 0,
-      signal
-    );
-  }
-  // ─── Relations & Graph ────────────────────────────────────────────────────
-  /**
-   * Get all relations for an entity — inbound and outbound.
-   * Use to discover connections before graph traversal.
-   *
-   * Note: The backend GET /relations requires both userId and workspaceId.
-   * This method resolves userId automatically; workspaceId falls back to client default.
-   */
-  async getRelations(entityId, options) {
-    const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    if (!wsId) throw new Error("workspaceId is required for getRelations");
-    const params = new URLSearchParams({ userId, workspaceId: wsId, entityId });
-    const result = await this.request("GET", `/api/hub/relations?${params}`);
-    return unwrapList(result);
-  }
-  /**
-   * Create a typed relation between two entities.
-   * Type is a free string — conventions: "related_to", "parent_of", "child_of",
-   * "belongs_to", "authored_by", "depends_on", "references".
-   * Goes through governance — may return "proposed".
-   */
-  async createRelation(input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    const wsId = input.workspaceId ?? this.workspaceId;
-    if (!wsId) throw new Error("workspaceId is required for createRelation");
-    return this.request("POST", "/api/hub/relations", {
-      userId,
-      workspaceId: wsId,
-      sourceEntityId: input.sourceEntityId,
-      targetEntityId: input.targetEntityId,
-      type: input.type
-    });
-  }
-  /**
-   * Attach a role-profile through the canonical governed facet door. A result
-   * may be `proposed`; callers must surface its review information instead of
-   * claiming the role was applied.
-   */
-  async attachFacet(input) {
-    const userId = await this.resolveUserId();
-    return this.request(
-      "POST",
-      `/api/hub/entities/${input.entityId}/facets`,
-      {
-        userId,
-        profileSlug: input.profileSlug,
-        profileId: input.profileId,
-        workspaceId: input.workspaceId ?? this.workspaceId,
-        contextEntityId: input.contextEntityId,
-        status: input.status,
-        properties: input.properties,
-        reasoning: input.reasoning
-      }
-    );
-  }
-  /**
-   * Delete a relation by ID (get from getRelations()).
-   */
-  async deleteRelation(relationId) {
-    const userId = await this.resolveUserId();
-    await this.request("DELETE", `/api/hub/relations/${relationId}`, {
-      userId
-    });
-  }
-  /**
-   * Traverse the knowledge graph from an entity using BFS.
-   * Returns nodes and edges up to maxDepth hops away.
-   * maxDepth: 1=direct neighbors, 2=neighborhood (recommended), 3=extended (expensive).
-   *
-   * @example
-   * const graph = await client.traverseGraph(projectId, { maxDepth: 2 });
-   * const tasks = graph.nodes.filter(n => n.profileSlug === "task");
-   */
-  async traverseGraph(entityId, options) {
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({
-      userId,
-      startEntityId: entityId,
-      maxDepth: String(options?.maxDepth ?? 2)
-    });
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    if (wsId) params.set("workspaceId", wsId);
-    return this.request(
-      "GET",
-      `/api/hub/graph/traverse?${params}`
-    );
-  }
-  /**
-   * Unified view of everything connected to an entity across the local graph:
-   *   1. Graph relations — explicit rows in the relations table (both directions)
-   *   2. Structural links — inbound and outbound `entity_id` property edges
-   *   3. Channel and focus-session connections around this entity
-   *
-   * Prefer this over `getRelations()` / `traverseGraph()` when you want the complete
-   * picture — those only see the relations table and miss property-based links that
-   * haven't been synced (notably custom profiles without a `relationDefId` mapping).
-   *
-   * Each connection carries a `source` field so callers can filter by origin.
-   *
-   * @example
-   * const { connections } = await client.getConnections(entityId);
-   * const tasks = connections.filter(c => c.entity?.profileSlug === "task");
-   */
-  async getConnections(entityId, options) {
-    const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams({ userId });
-    if (wsId) params.set("workspaceId", wsId);
-    if (options?.limit) params.set("limit", String(options.limit));
-    return this.request(
-      "GET",
-      `/api/hub/entities/${entityId}/connections?${params}`
-    );
-  }
-  // ─── Session orientation & profile discovery ─────────────────────────────
-  /**
-   * Canonical session bootstrap shared by the MCP, CLI, and external surfaces.
-   * It is deliberately a lens map, not a profile/schema dump; use discover()
-   * only for the selected profiles needed by the next action.
-   */
-  async orient(options) {
-    const params = new URLSearchParams();
-    if (options?.detail) params.set("detail", options.detail);
-    if (options?.scope?.length) params.set("scope", options.scope.join(","));
-    if (options?.workspaceId) params.set("workspaceId", options.workspaceId);
-    if (options?.projectId) params.set("projectId", options.projectId);
-    const qs = params.toString() ? `?${params}` : "";
-    return this.request("GET", `/api/hub/orient${qs}`);
-  }
-  // ─── Profiles & Schema ────────────────────────────────────────────────────
-  /**
-   * List all entity profile types in the workspace.
-   * Always call before creating entities to discover what types are available.
-   * Returns system profiles (always present) + custom workspace profiles.
-   */
-  async listProfiles(workspaceId, options) {
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({ userId, workspaceId });
-    if (options?.detail) params.set("detail", options.detail);
-    const result = await this.request("GET", `/api/hub/profiles?${params}`);
-    return unwrapList(result);
-  }
-  /**
-   * List property definitions for a workspace, optionally filtered by profile.
-   */
-  async listPropertyDefs(workspaceId, options) {
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({ userId, workspaceId });
-    if (options?.profileSlug) params.set("profileId", options.profileSlug);
-    const result = await this.request("GET", `/api/hub/property-defs?${params}`);
-    return unwrapList(result);
-  }
-  /**
-   * Runtime discovery — profiles with property schemas + command tree.
-   *
-   * Call once per session at session start. Returns ground-truth profile
-   * schemas (including custom workspace profiles) and the canonical CLI
-   * command map. Replaces static skill file profile descriptions.
-   */
-  async discover(options) {
-    const userId = await this.resolveUserId();
-    const normalized = typeof options === "string" ? { workspaceId: options } : options ?? {};
-    const params = new URLSearchParams({ userId });
-    if (normalized.workspaceId)
-      params.set("workspaceId", normalized.workspaceId);
-    if (normalized.summary !== void 0)
-      params.set("summary", String(normalized.summary));
-    if (normalized.profileSlugs?.length)
-      params.set("profileSlugs", normalized.profileSlugs.join(","));
-    return this.request(
-      "GET",
-      `/api/hub/discover?${params}`
-    );
-  }
-  // ─── Threads & Channels ───────────────────────────────────────────────────
-  /**
-   * List threads (channels) accessible to a user.
-   */
-  async listThreads(userId, options) {
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams({ userId });
-    if (wsId) params.set("workspaceId", wsId);
-    if (options?.type) params.set("type", options.type);
-    const result = await this.request(
-      "GET",
-      `/api/hub/threads?${params}`
-    );
-    return unwrapList(result);
-  }
-  /**
-   * Get the user's personal channel — their private AI conversation thread.
-   * Use as default destination for messages and proactive posts.
-   *
-   * Note: The backend GET /channels/personal requires both userId and workspaceId.
-   */
-  async getPersonalChannel(userId, workspaceId) {
-    const wsId = workspaceId ?? this.workspaceId;
-    if (!wsId)
-      throw new Error("workspaceId is required for getPersonalChannel");
-    const params = new URLSearchParams({ userId, workspaceId: wsId });
-    return this.request(
-      "GET",
-      `/api/hub/channels/personal?${params}`
-    );
-  }
-  /**
-   * Create a new thread. Pass entityId to auto-link on creation.
-   *
-   * Note: The backend POST /threads requires workspaceId in the body.
-   */
-  async createThread(input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    const wsId = input.workspaceId ?? this.workspaceId;
-    if (!wsId) throw new Error("workspaceId is required for createThread");
-    return this.request("POST", "/api/hub/threads", {
-      userId,
-      workspaceId: wsId,
-      title: input.name,
-      agentType: input.agentType,
-      contextObjectType: input.entityId ? "entity" : input.documentId ? "document" : void 0,
-      contextObjectId: input.entityId ?? input.documentId
-    });
-  }
-  /**
-   * Get full thread context: messages + all linked entities and documents.
-   * Call before sending a message to orient the AI with conversation history.
-   */
-  async getThreadContext(threadId) {
-    return this.request(
-      "GET",
-      `/api/hub/threads/${threadId}/context`
-    );
-  }
-  /**
-   * Get messages in a thread.
-   */
-  async getMessages(threadId, _options) {
-    const result = await this.request("GET", `/api/hub/threads/${threadId}/messages`);
-    return unwrapList(result);
-  }
-  /**
-   * Link an entity to a thread so it appears in thread context for AI.
-   */
-  async linkEntityToThread(threadId, entityId) {
-    const userId = await this.resolveUserId();
-    await this.request(
-      "POST",
-      `/api/hub/threads/${threadId}/link-entity`,
-      { userId, entityId }
-    );
-  }
-  /**
-   * Link a document to a thread.
-   */
-  async linkDocumentToThread(threadId, documentId) {
-    const userId = await this.resolveUserId();
-    await this.request(
-      "POST",
-      `/api/hub/threads/${threadId}/link-document`,
-      { userId, documentId }
-    );
-  }
-  /**
-   * Get research branches of a thread — parallel AI investigations.
-   */
-  async getThreadBranches(threadId) {
-    const result = await this.request("GET", `/api/hub/threads/${threadId}/branches`);
-    return result.branches ?? [];
-  }
-  // ─── Memory ───────────────────────────────────────────────────────────────
-  async storeMemory(input) {
-    const userId = await this.resolveUserId();
-    const fact = input.context && String(input.context).trim().length > 0 ? `[${String(input.context).trim()}] ${input.fact}` : input.fact;
-    return this.request("POST", "/api/hub/memory", {
-      userId,
-      fact
-    });
-  }
-  async recallMemory(query, options) {
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({
-      userId,
-      query,
-      limit: String(options?.limit ?? 10)
-    });
-    if (wsId) params.set("workspaceId", wsId);
-    const result = await this.request("GET", `/api/hub/memory?${params}`);
-    return unwrapList(result);
-  }
-  /**
-   * Delete a stored memory fact by ID.
-   */
-  async deleteMemory(memoryId) {
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({ userId });
-    await this.request(
-      "DELETE",
-      `/api/hub/memory/${memoryId}?${params}`
-    );
-  }
-  // ─── Channels (Hub REST: channels are listed via GET /threads) ────────────
-  async getChannels(options) {
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({ userId });
-    if (wsId) params.set("workspaceId", wsId);
-    const result = await this.request("GET", `/api/hub/threads?${params}`);
-    return unwrapList(result);
-  }
-  async sendToChannel(input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    return this.request(
-      "POST",
-      `/api/hub/threads/${input.channelId}/messages`,
-      {
-        role: input.role ?? "user",
-        content: input.content,
-        userId,
-        ...input.autoRespond !== void 0 ? { autoRespond: input.autoRespond } : {}
-      }
-    );
-  }
-  // ─── Proposals ────────────────────────────────────────────────────────────
-  /**
-   * List proposals — pending AI writes awaiting human review.
-   * Filter by status: "pending" (needs review), "approved", "rejected".
-   */
-  async listProposals(options) {
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({ userId });
-    if (options?.scope !== "all") {
-      const wsId = options?.workspaceId ?? this.workspaceId;
-      if (wsId) params.set("workspaceId", wsId);
-    }
-    if (options?.status) params.set("status", options.status);
-    if (options?.limit) params.set("limit", String(options.limit));
-    const result = await this.request("GET", `/api/hub/proposals?${params}`);
-    return unwrapList(result);
-  }
-  /**
-   * Approve or reject a proposal.
-   *
-   * Note: The backend PATCH /proposals/:id is an AI-revision endpoint that updates
-   * the proposal data/summary, not a review (approve/reject) endpoint.
-   * Use this to update proposal data before human review.
-   */
-  async reviewProposal(proposalId, decision, reason) {
-    return this.request(
-      "PATCH",
-      `/api/hub/proposals/${proposalId}`,
-      {
-        data: { status: decision },
-        summary: reason
-      }
-    );
-  }
-  // ─── Views ────────────────────────────────────────────────────────────────
-  /**
-   * List data views in a workspace.
-   */
-  async listViews(workspaceId, options) {
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({ userId, workspaceId });
-    if (options?.profileSlug) params.set("profileId", options.profileSlug);
-    const result = await this.request(
-      "GET",
-      `/api/hub/views?${params}`
-    );
-    return unwrapList(result);
-  }
-  /**
-   * Create a new view. Goes through governance.
-   */
-  async createView(input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    return this.request("POST", "/api/hub/views", {
-      userId,
-      workspaceId: input.workspaceId ?? this.workspaceId,
-      name: input.name,
-      type: input.type,
-      profileId: input.profileSlug,
-      config: input.config,
-      metadata: input.metadata,
-      agentUserId: input.agentUserId,
-      reasoning: input.reasoning,
-      sourceMessageId: input.sourceMessageId
-    });
-  }
-  /** Update a view through the existing governed Hub route. */
-  async updateView(viewId, input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    return this.request(
-      "PATCH",
-      `/api/hub/views/${viewId}`,
-      {
-        userId,
-        workspaceId: input.workspaceId ?? this.workspaceId,
-        name: input.name,
-        config: input.config,
-        metadata: input.metadata,
-        agentUserId: input.agentUserId,
-        reasoning: input.reasoning,
-        sourceMessageId: input.sourceMessageId
-      }
-    );
-  }
-  /** Replace a bento view's widget arrangement through the existing Hub route. */
-  async arrangeBentoView(viewId, input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    const workspaceId = input.workspaceId ?? this.workspaceId;
-    if (!workspaceId) {
-      throw new Error("workspaceId is required for arrangeBentoView");
-    }
-    return this.request(
-      "POST",
-      `/api/hub/views/${viewId}/arrange`,
-      {
-        userId,
-        workspaceId,
-        widgets: input.widgets,
-        agentUserId: input.agentUserId,
-        reasoning: input.reasoning,
-        sourceMessageId: input.sourceMessageId
-      }
-    );
-  }
-  // ─── Documents ────────────────────────────────────────────────────────────
-  /**
-   * Get a document by ID with full markdown content.
-   */
-  async getDocument(documentId) {
-    const userId = await this.resolveUserId();
-    const params = new URLSearchParams({ userId });
-    const result = await this.request(
-      "GET",
-      `/api/hub/documents/${documentId}?${params}`
-    );
-    return "document" in result ? result.document : result;
-  }
-  /**
-   * Create a document. Use for long-form content: meeting notes, research, writeups.
-   * Goes through governance.
-   */
-  async createDocument(input) {
-    const userId = await this.resolveUserId();
-    return this.request("POST", "/api/hub/documents", {
-      userId,
-      workspaceId: input.workspaceId ?? this.workspaceId,
-      title: input.title,
-      content: input.content ?? "",
-      type: input.type,
-      reasoning: input.reasoning,
-      agentUserId: input.agentUserId,
-      sourceMessageId: input.sourceMessageId,
-      sessionId: input.sessionId
-    });
-  }
-  /** Propose a full document-content replacement through the governed Hub route. */
-  async updateDocument(documentId, input) {
-    const userId = await this.resolveUserId();
-    return this.request(
-      "PATCH",
-      `/api/hub/documents/${documentId}`,
-      {
-        userId,
-        content: input.content,
-        title: input.title,
-        agentUserId: input.agentUserId,
-        sourceMessageId: input.sourceMessageId,
-        sessionId: input.sessionId
-      }
-    );
-  }
-  /** Submit a structured, reviewable document-edit proposal. */
-  async createDocumentProposal(input) {
-    const userId = await this.resolveUserId();
-    return this.request(
-      "POST",
-      "/api/hub/documents/proposals",
-      {
-        userId,
-        ...input
-      }
-    );
-  }
-  // ─── Capabilities & teaching substrate ───────────────────────────────────
-  /** Flat capability read-model. Prefer getCapabilityCatalog() for presentation. */
-  async listCapabilities(options) {
-    const workspaceId = options?.workspaceId ?? this.workspaceId;
-    if (!workspaceId) {
-      throw new Error("workspaceId is required for listCapabilities");
-    }
-    const params = new URLSearchParams({ workspaceId });
-    const result = await this.request(
-      "GET",
-      `/api/hub/capabilities?${params}`
-    );
-    return result.capabilities;
-  }
-  /** Status-computed, pack-grouped capability catalog for every external surface. */
-  async getCapabilityCatalog(options) {
-    const workspaceId = options?.workspaceId ?? this.workspaceId;
-    if (!workspaceId) {
-      throw new Error("workspaceId is required for getCapabilityCatalog");
-    }
-    const params = new URLSearchParams({ workspaceId });
-    if (options?.extraKey) params.set("extraKey", options.extraKey);
-    return this.request(
-      "GET",
-      `/api/hub/capabilities/catalog?${params}`
-    );
-  }
-  /** List only approved, connected actions that this client can execute now. */
-  async listRunnableCapabilityActions(options) {
-    const workspaceId = options?.workspaceId ?? this.workspaceId;
-    if (!workspaceId) {
-      throw new Error(
-        "workspaceId is required for listRunnableCapabilityActions"
-      );
-    }
-    const params = new URLSearchParams({ workspaceId });
-    if (options?.query) params.set("query", options.query);
-    if (options?.kind) params.set("kind", options.kind);
-    if (options?.limit !== void 0)
-      params.set("limit", String(options.limit));
-    return this.request(
-      "GET",
-      `/api/hub/capabilities/actions?${params}`
-    );
-  }
-  /** Run one registered capability through the shared governance gate. */
-  async executeCapability(input) {
-    return this.request(
-      "POST",
-      "/api/hub/capabilities/execute",
-      {
-        ...input,
-        // Graph proposals follow the same explicit-scope rule as direct writes.
-        ...input.workspaceId ? { workspaceId: input.workspaceId } : {}
-      }
-    );
-  }
-  /** List the compact system teaching catalog, or search the available skill index. */
-  async listAgentSkills(options) {
-    const params = new URLSearchParams();
-    if (options?.topic) params.set("topic", options.topic);
-    if (options?.query) params.set("q", options.query);
-    if (options?.tag) params.set("tag", options.tag);
-    if (options?.system !== void 0)
-      params.set("system", String(options.system));
-    const workspaceId = options?.workspaceId ?? this.workspaceId;
-    if (workspaceId) params.set("workspaceId", workspaceId);
-    if (options?.limit !== void 0)
-      params.set("limit", String(options.limit));
-    if (options?.offset !== void 0)
-      params.set("offset", String(options.offset));
-    const qs = params.toString() ? `?${params}` : "";
-    return this.request(
-      "GET",
-      `/api/hub/agent-skills${qs}`
-    );
-  }
-  /** Load one skill body only when it is relevant to the agent's next action. */
-  async getAgentSkillBySlug(slug, options) {
-    const workspaceId = options?.workspaceId ?? this.workspaceId;
-    const qs = workspaceId ? `?${new URLSearchParams({ workspaceId })}` : "";
-    return this.request(
-      "GET",
-      `/api/hub/agent-skills/by-slug/${encodeURIComponent(slug)}${qs}`
-    );
-  }
-  /** Compose just-in-time teaching and governance briefs for selected tools. */
-  async getCapabilityBriefs(input) {
-    if (input.tools.length === 0) return { briefs: {} };
-    const workspaceId = input.workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams({ tools: input.tools.join(",") });
-    if (workspaceId) params.set("workspaceId", workspaceId);
-    if (input.door) params.set("door", input.door);
-    return this.request(
-      "GET",
-      `/api/hub/briefs?${params}`
-    );
-  }
-  // ─── Commands & Agents ────────────────────────────────────────────────────
-  /**
-   * List available commands (automation shortcuts) in the workspace.
-   */
-  async listCommands(workspaceId) {
-    const wsId = workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams();
-    if (wsId) params.set("workspaceId", wsId);
-    const qs = params.toString() ? `?${params}` : "";
-    const result = await this.request("GET", `/api/hub/commands${qs}`);
-    return unwrapList(result);
-  }
-  /**
-   * Execute a command by slug.
-   *
-   * Note: The backend POST /commands/execute uses a `command` field (the shell command
-   * string) and `userId`, not a `slug`. This maps ExecuteCommandInput.slug to `command`.
-   */
-  async executeCommand(input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    return this.request(
-      "POST",
-      "/api/hub/commands/execute",
-      {
-        command: input.slug,
-        userId,
-        workspaceId: input.workspaceId ?? this.workspaceId,
-        ...input.parameters ? { parameters: input.parameters } : {}
-      }
-    );
-  }
-  /**
-   * List agent users provisioned in the workspace.
-   */
-  async listAgentUsers(workspaceId) {
-    const wsId = workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams();
-    if (wsId) params.set("workspaceId", wsId);
-    const qs = params.toString() ? `?${params}` : "";
-    const result = await this.request("GET", `/api/hub/agent-users${qs}`);
-    return unwrapList(result);
-  }
-  // ─── Proactive posting ────────────────────────────────────────────────────
-  /**
-   * Post a proactive message to the user's personal channel.
-   * For AI-initiated insights and summaries. Rate-limited: 3/hour, 10/day.
-   * proactiveType must be one of: insight, suggestion, alert, nudge,
-   * morning_briefing, weekly_digest, health_check.
-   */
-  async postProactive(userId, content, options) {
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    if (!wsId) throw new Error("workspaceId is required for postProactive");
-    return this.request("POST", "/api/hub/proactive/post", {
-      userId,
-      workspaceId: wsId,
-      content,
-      proactiveType: options?.type ?? "insight"
-    });
-  }
-  // ─── Capture pipeline ─────────────────────────────────────────────────────
-  async captureStructure(input) {
-    const userId = await this.resolveUserId();
-    return this.request(
-      "POST",
-      "/api/hub/capture/structure",
-      {
-        userId,
-        text: input.text,
-        url: input.url,
-        workspaceId: input.workspaceId ?? this.workspaceId,
-        previousEntities: input.previousEntities
-      }
-    );
-  }
-  async captureExecute(input) {
-    const userId = await this.resolveUserId();
-    return this.request(
-      "POST",
-      "/api/hub/capture/execute",
-      {
-        userId,
-        entities: input.entities,
-        relations: input.relations ?? [],
-        workspaceId: input.workspaceId ?? this.workspaceId,
-        // Keep this exact routing bundle in lockstep with CaptureExecuteInput
-        // and the REST codec. Dropping it here silently made CLI/Raycast capture
-        // behave differently from MCP despite all three using the same backend.
-        projectId: input.projectId,
-        targetWorkspaceId: input.targetWorkspaceId,
-        keepRaw: input.keepRaw,
-        file: input.file,
-        idempotencyKey: input.idempotencyKey,
-        workspaceRouting: input.workspaceRouting,
-        aiWorkspaceId: input.aiWorkspaceId,
-        aiWorkspaceConfidence: input.aiWorkspaceConfidence,
-        aiWorkspaceReason: input.aiWorkspaceReason
-      }
-    );
-  }
-  /**
-   * Submit a designed entity graph as ONE reviewable composite proposal.
-   *
-   * This is intentionally distinct from captureExecute(): execute materializes
-   * a prior structure result immediately, while this door keeps an autonomous
-   * graph plan reviewable and applies entities, relations, and bindings together
-   * only after approval.
-   */
-  async submitCaptureGraph(input) {
-    const { workspaceId, relations, bindings, ...body } = input;
-    return this.request(
-      "POST",
-      "/api/hub/capture/graph",
-      {
-        ...body,
-        // Proposal audience and schema overlays are explicit write choices.
-        ...workspaceId ? { workspaceId } : {},
-        relations: relations ?? [],
-        bindings: bindings ?? []
-      }
-    );
-  }
-  // ─── Recall: the one door ──────────────────────────────────────────────────
-  /**
-   * `ask` — the unified recall verb. Routes a natural-language question across
-   * all knowledge substrates (semantic entities, procedural runbooks, episodic
-   * facts) server-side and returns ONE provenance-tagged answer. The canonical
-   * recall door — prefer it over the fragmented searchEntities / recallMemory.
-   * The server builds the profile catalog from the caller's workspace; the
-   * client only sends the query (+ optional scope).
-   */
-  async ask(input) {
-    return this.request("POST", "/api/hub/knowledge/ask", {
-      query: input.query,
-      workspaceId: input.workspaceId ?? this.workspaceId,
-      limit: input.limit,
-      parseOnly: input.parseOnly
-    });
-  }
-  // ─── Automations ───────────────────────────────────────────────────────────
-  /**
-   * List automations for the current user, optionally filtered by workspace and status.
-   */
-  async listAutomations(options) {
-    const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams({ userId });
-    if (wsId) params.set("workspaceId", wsId);
-    if (options?.status) params.set("status", options.status);
-    if (options?.limit) params.set("limit", String(options.limit));
-    const result = await this.request("GET", `/api/hub/automations?${params}`);
-    return unwrapList(result);
-  }
-  /**
-   * Get a single automation by ID.
-   */
-  async getAutomation(automationId, options) {
-    const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams({ userId });
-    if (wsId) params.set("workspaceId", wsId);
-    return this.request(
-      "GET",
-      `/api/hub/automations/${automationId}?${params}`
-    );
-  }
-  /**
-   * Create an automation. Defaults to status=draft.
-   * Use activateAutomation() to enable it.
-   */
-  async createAutomation(input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    const wsId = input.workspaceId ?? this.workspaceId;
-    return this.request("POST", "/api/hub/automations/create", {
-      ...input,
-      userId,
-      workspaceId: wsId ?? null
-    });
-  }
-  /**
-   * Update an automation's definition or metadata.
-   */
-  async updateAutomation(automationId, input) {
-    const userId = input.userId ?? await this.resolveUserId();
-    const wsId = input.workspaceId ?? this.workspaceId;
-    if (!wsId) throw new Error("workspaceId is required for updateAutomation");
-    return this.request(
-      "PATCH",
-      `/api/hub/automations/${automationId}`,
-      { ...input, userId, workspaceId: wsId }
-    );
-  }
-  /**
-   * Manually trigger an automation once with an optional payload.
-   * Bypasses the automation's normal trigger config.
-   */
-  async triggerAutomation(automationId, options) {
-    const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    return this.request(
-      "POST",
-      `/api/hub/automations/${automationId}/trigger`,
-      { userId, workspaceId: wsId ?? null, payload: options?.payload }
-    );
-  }
-  /**
-   * Activate a draft or paused automation (sets status=active).
-   */
-  async activateAutomation(automationId, options) {
-    const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    if (!wsId)
-      throw new Error("workspaceId is required for activateAutomation");
-    return this.request(
-      "POST",
-      `/api/hub/automations/${automationId}/activate`,
-      { userId, workspaceId: wsId }
-    );
-  }
-  /**
-   * Pause an active automation (sets status=paused).
-   */
-  async pauseAutomation(automationId, options) {
-    const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    if (!wsId) throw new Error("workspaceId is required for pauseAutomation");
-    return this.request(
-      "POST",
-      `/api/hub/automations/${automationId}/pause`,
-      { userId, workspaceId: wsId }
-    );
-  }
-  // ─── Subscriptions / Reactions (Pulse) ────────────────────────────────────
-  /**
-   * List the user-wide Pulse feed — the timestamp-sorted union of reactive events.
-   * Call getSubscriptionFanout() on an individual event for its dense reactions[].
-   */
-  async listSubscriptions(options) {
-    const wsId = options?.workspaceId ?? this.workspaceId;
-    const params = new URLSearchParams();
-    if (wsId) params.set("workspaceId", wsId);
-    if (options?.kind) params.set("kind", options.kind);
-    if (options?.eventType) params.set("eventType", options.eventType);
-    if (options?.lens) params.set("lens", options.lens);
-    if (options?.limit) params.set("limit", String(options.limit));
-    const qs = params.toString() ? `?${params}` : "";
-    const result = await this.request("GET", `/api/hub/subscriptions${qs}`);
-    return unwrapList(result);
-  }
-  /**
-   * Get the reaction fan-out for a single event — full reactions[] populated.
-   */
-  async getSubscriptionFanout(eventId, options) {
-    const params = new URLSearchParams();
-    if (options?.lens) params.set("lens", options.lens);
-    const qs = params.toString() ? `?${params}` : "";
-    return this.request(
-      "GET",
-      `/api/hub/subscriptions/${eventId}/fanout${qs}`
-    );
-  }
-  // ─── Notifications ─────────────────────────────────────────────────────────
-  /**
-   * Persist a notification and emit notification:new to the frontend.
-   * Use for IS-originated events (skill.triggered, agent actions, etc.).
-   * Backend-originated notifications (vault, proposals) use NotificationService directly.
-   */
-  async createNotification(input) {
-    return this.request(
-      "POST",
-      "/api/hub/notifications",
-      input
-    );
-  }
-  // ─── Webhooks ──────────────────────────────────────────────────────────────
-  /**
-   * List delivery log for a webhook subscription.
-   * Powers the Reactions Health tab and replay flows.
-   */
-  async getWebhookDeliveries(subscriptionId, options) {
-    const params = new URLSearchParams();
-    if (options?.limit) params.set("limit", String(options.limit));
-    const qs = params.toString() ? `?${params}` : "";
-    const result = await this.request("GET", `/api/hub/webhooks/${subscriptionId}/deliveries${qs}`);
-    return unwrapList(result);
-  }
-};
-
-// src/setup.ts
-function normalizeUrl2(url) {
-  return url.replace(/\/$/, "");
-}
-function assertValidPodUrl(url, opts = {}) {
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch {
-    throw new HubApiError(`Invalid pod URL: ${url}`, 0, {
-      code: "INVALID_POD_URL"
-    });
-  }
-  if (parsed.username || parsed.password) {
-    throw new HubApiError("Pod URL must not contain embedded credentials", 0, {
-      code: "INVALID_POD_URL"
-    });
-  }
-  const isHttps = parsed.protocol === "https:";
-  const isHttp = parsed.protocol === "http:";
-  if (!isHttps && !(isHttp && opts.allowHttp)) {
-    throw new HubApiError(
-      `Pod URL must use https:// (got ${parsed.protocol}//)`,
-      0,
-      { code: "INSECURE_POD_URL" }
-    );
-  }
-}
-async function checkPodHealth(podUrl) {
-  const url = normalizeUrl2(podUrl);
-  const status = { url, healthy: false };
-  try {
-    const res = await fetch(`${url}/health`, {
-      signal: AbortSignal.timeout(5e3)
-    });
-    if (res.ok) {
-      status.healthy = true;
-      const data = await res.json();
-      status.version = data.version;
-    }
-  } catch {
-  }
-  return status;
-}
-async function setupAgent(podUrl, provisioningToken, agentType, opts = {}) {
-  assertValidPodUrl(podUrl, { allowHttp: opts.allowHttp });
-  const url = normalizeUrl2(podUrl);
-  const res = await fetch(`${url}/api/hub/setup/agent`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${provisioningToken}`
-    },
-    body: JSON.stringify({ agentType }),
-    signal: AbortSignal.timeout(15e3)
-  });
-  if (!res.ok) {
-    const body = await res.json().catch(() => ({}));
-    throw new HubApiError(
-      `Agent setup failed (HTTP ${res.status})`,
-      res.status,
-      body
-    );
-  }
-  return res.json();
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  HubApiError,
-  HubRestClient,
-  checkPodHealth,
-  setupAgent
-});