/**
 * HubRestClient — typed HTTP client for the Synap Hub Protocol REST API.
 *
 * Uses the native `fetch` API (Node.js >= 18, browsers, Deno, Bun).
 * Zero runtime dependencies.
 *
 * @example
 * ```ts
 * const client = new HubRestClient({
 *   podUrl: "https://my-pod.synap.live",
 *   apiKey: "synap_hub_live_...",
 * });
 *
 * const entities = await client.searchEntities("meeting notes", { profileSlug: "note" });
 * ```
 */

import { HubApiError } from "./errors.js";
import type {
  HubEntity,
  HubChannel,
  HubWorkspace,
  HubUser,
  HubMemoryResult,
  HubListResponse,
  HubSingleResponse,
  HubWorkspacesListResponse,
  CreateEntityInput,
  UpdateEntityInput,
  StoreMemoryInput,
  SendToChannelInput,
  CaptureProposal,
  CaptureStructureResponse,
  CaptureExecuteInput,
  CaptureExecuteResponse,
  AskResponse,
  HubDocument,
  HubRelation,
  HubGraphResult,
  HubConnectionsResult,
  HubProfile,
  HubPropertyDef,
  HubDiscoverResult,
  HubDiscoverOptions,
  HubOrientOptions,
  HubOrientResult,
  HubThread,
  HubMessage,
  HubThreadContext,
  HubProposal,
  HubView,
  HubSearchResult,
  HubCommand,
  HubAgentUser,
  HubUserContext,
  HubGovernanceResult,
  CreateThreadInput,
  CreateRelationInput,
  AttachFacetInput,
  HubAttachFacetResult,
  CreateViewInput,
  UpdateViewInput,
  ArrangeBentoViewInput,
  HubBentoArrangementResult,
  ExecuteCommandInput,
  CreateDocumentInput,
  UpdateDocumentInput,
  CreateDocumentProposalInput,
  HubDocumentProposalResult,
  HubCapability,
  HubCapabilityCatalogResult,
  HubRunnableCapabilityActionsResult,
  ExecuteCapabilityInput,
  ExecuteCapabilityResult,
  ListAgentSkillsOptions,
  HubAgentSkillsResult,
  HubAgentSkill,
  GetCapabilityBriefsInput,
  HubCapabilityBriefsResult,
  SubmitCaptureGraphInput,
  SubmitCaptureGraphResult,
  HubAutomation,
  CreateAutomationInput,
  UpdateAutomationInput,
  AutomationStatus,
  ReactionKind,
  ReactionLens,
  HubReactionEvent,
  CreateNotificationInput,
  HubWebhookDelivery,
} from "./types.js";

export interface HubRestClientConfig {
  /** Pod URL, e.g. https://my-pod.synap.live */
  podUrl: string;
  /** Hub Protocol API key (Bearer token) */
  apiKey: string;
  /** Default workspace ID — used when not specified per call */
  workspaceId?: string;
  /** Optional request timeout in ms (default: 30000). Fallback when read/write timeouts are unset. */
  timeoutMs?: number;
  /** Optional read (GET) timeout in ms (default: timeoutMs ?? 30000). */
  readTimeoutMs?: number;
  /** Optional write (non-GET) timeout in ms (default: timeoutMs ?? 30000). */
  writeTimeoutMs?: number;
  /**
   * Max attempts for a request (default: 3). Retries ONLY on network failure or
   * 5xx — never on 4xx, never on a caller-provided abort. Set to 1 to disable.
   */
  maxAttempts?: number;
}

function normalizeUrl(url: string): string {
  return url.replace(/\/$/, "");
}

function formatHubErrorMessage(
  status: number,
  statusText: string,
  errorBody: unknown
): string {
  let detail = "";
  if (errorBody && typeof errorBody === "object" && "error" in errorBody) {
    detail = String((errorBody as { error: unknown }).error);
  }
  const base = `Hub API error: ${status} ${statusText}`;
  let msg = detail ? `${base} — ${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 → API keys on your pod).";
  }
  return msg;
}

function unwrapList<T>(result: T[] | HubListResponse<T>): T[] {
  return Array.isArray(result)
    ? result
    : ((result as HubListResponse<T>).data ?? []);
}

/** Hub GET /workspaces returns `{ workspaces }`, not `{ data }`. */
function unwrapWorkspacesResponse(
  result:
    HubWorkspace[] | HubListResponse<HubWorkspace> | HubWorkspacesListResponse
): HubWorkspace[] {
  if (Array.isArray(result)) return result;
  if (result && typeof result === "object" && "workspaces" in result) {
    const w = (result as HubWorkspacesListResponse).workspaces;
    return Array.isArray(w) ? w : [];
  }
  return unwrapList(result as HubWorkspace[] | HubListResponse<HubWorkspace>);
}

function unwrapSingle<T>(result: T | HubSingleResponse<T>): T {
  if (result && typeof result === "object" && "data" in result) {
    return (result as HubSingleResponse<T>).data;
  }
  return result as T;
}

export class HubRestClient {
  private readonly base: string;
  private readonly headers: Record<string, string>;
  private readonly timeoutMs: number;
  private readonly readTimeoutMs: number;
  private readonly writeTimeoutMs: number;
  private readonly maxAttempts: number;
  readonly workspaceId: string | undefined;

  /** Cached from GET /users/me — avoids repeated identity calls. */
  private resolvedUserId: string | null = null;

  constructor(config: HubRestClientConfig) {
    this.base = normalizeUrl(config.podUrl);
    this.headers = {
      Authorization: `Bearer ${config.apiKey}`,
      "Content-Type": "application/json",
    };
    this.workspaceId = config.workspaceId;
    this.timeoutMs = config.timeoutMs ?? 30_000;
    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). */
  private async resolveUserId(): Promise<string> {
    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).
   */
  private async fetchWithRetry(
    method: string,
    path: string,
    body?: unknown,
    signal?: AbortSignal,
    timeoutMsOverride?: number
  ): Promise<Response> {
    const url = `${this.base}${path}`;
    const perAttemptTimeout =
      timeoutMsOverride ??
      (method.toUpperCase() === "GET"
        ? this.readTimeoutMs
        : this.writeTimeoutMs);

    let lastError: unknown;
    for (let attempt = 0; attempt < this.maxAttempts; attempt++) {
      if (attempt > 0) {
        await new Promise((r) => setTimeout(r, 1_000 * attempt)); // 0, 1s, 2s, …
      }
      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 !== undefined ? JSON.stringify(body) : undefined,
          signal: combined,
        });
        if (res.status < 500) return res; // ok or 4xx — caller decides; never retry
        lastError = new Error(`HTTP ${res.status}`); // 5xx — retry until exhausted
      } catch (err) {
        if (signal?.aborted) throw err; // caller asked to abort — honor it
        lastError = err; // network/abort-timeout — retry
      }
    }
    throw lastError;
  }

  /** Build a HubApiError from a non-ok Response (reads the JSON error body). */
  private async toHubError(res: Response): Promise<HubApiError> {
    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). */
  private async parseBody<T>(res: Response): Promise<T> {
    const text = await res.text();
    return (text ? JSON.parse(text) : undefined) as T;
  }

  /**
   * Typed JSON request — throws `HubApiError` on any non-2xx. Protected so the IS
   * subclass reuses it. Tolerates an empty/204 body (returns `undefined`).
   */
  protected async request<T>(
    method: string,
    path: string,
    body?: unknown,
    signal?: AbortSignal
  ): Promise<T> {
    const res = await this.fetchWithRetry(method, path, body, signal);
    if (!res.ok) throw await this.toHubError(res);
    return this.parseBody<T>(res);
  }

  /**
   * Like `request<T>` but returns `null` on 404/403 (the "absent/forbidden →
   * empty" contract several IS reads use) instead of throwing.
   */
  protected async requestOrNull<T>(
    method: string,
    path: string,
    body?: unknown,
    signal?: AbortSignal
  ): Promise<T | null> {
    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<T | null>(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.
   */
  protected async requestRaw(
    method: string,
    path: string,
    body?: unknown,
    signal?: AbortSignal,
    timeoutMsOverride?: number
  ): Promise<Response> {
    return this.fetchWithRetry(method, path, body, signal, timeoutMsOverride);
  }

  // ─── Identity ─────────────────────────────────────────────────────────────

  async getMe(): Promise<HubUser> {
    return this.request<HubUser>("GET", "/api/hub/users/me");
  }

  async getWorkspaces(): Promise<HubWorkspace[]> {
    const result = await this.request<
      HubWorkspace[] | HubListResponse<HubWorkspace> | HubWorkspacesListResponse
    >("GET", "/api/hub/workspaces");
    return unwrapWorkspacesResponse(result);
  }

  async provisionAgentWorkspace(input: {
    agentUserId: string;
    workspaceName?: string;
  }): Promise<{ workspaceId: string; created: boolean }> {
    return this.request<{ workspaceId: string; created: boolean }>(
      "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: string,
    options?: { workspaceId?: string }
  ): Promise<HubUserContext> {
    const params = new URLSearchParams();
    const wsId = options?.workspaceId ?? this.workspaceId;
    if (wsId) params.set("workspaceId", wsId);
    const qs = params.toString() ? `?${params}` : "";
    return this.request<HubUserContext>(
      "GET",
      `/api/hub/users/${userId}/context${qs}`
    );
  }

  // ─── Entities ─────────────────────────────────────────────────────────────

  async searchEntities(
    query: string,
    options?: {
      profileSlug?: string;
      workspaceId?: string;
      /**
       * "workspace" (default) — applies the client workspaceId filter.
       * "all" — omits workspaceId entirely so results span all workspaces.
       */
      scope?: "workspace" | "all";
      limit?: number;
    },
    signal?: AbortSignal
  ): Promise<HubEntity[]> {
    const params = new URLSearchParams({ q: query });
    if (options?.profileSlug) params.set("profileSlug", options.profileSlug);
    // When scope === "all", intentionally omit workspaceId for cross-workspace search.
    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<HubEntity[] | HubListResponse<HubEntity>>(
      "GET",
      `/api/hub/entities?${params}`,
      undefined,
      signal
    );
    return unwrapList(result);
  }

  async getEntity(id: string): Promise<HubEntity> {
    const result = await this.request<HubEntity | HubSingleResponse<HubEntity>>(
      "GET",
      `/api/hub/entities/${id}`
    );
    return unwrapSingle(result);
  }

  async getRecentEntities(options?: {
    profileSlug?: string;
    workspaceId?: string;
    limit?: number;
    /** "all" — omits workspaceId so results span all workspaces the user can access. */
    scope?: "workspace" | "all";
  }): Promise<HubEntity[]> {
    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<HubEntity[] | HubListResponse<HubEntity>>(
      "GET",
      `/api/hub/entities?${params}`
    );
    return unwrapList(result);
  }

  async createEntity(input: CreateEntityInput): Promise<HubGovernanceResult> {
    const { content, url, status, priority, dueDate, properties, ...rest } =
      input;
    return this.request<HubGovernanceResult>("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 !== undefined ? { content } : {}),
      properties: {
        ...properties,
        ...(url !== undefined ? { url } : {}),
        ...(status !== undefined ? { status } : {}),
        ...(priority !== undefined ? { priority } : {}),
        ...(dueDate !== undefined ? { dueDate } : {}),
      },
    });
  }

  async updateEntity(
    id: string,
    input: UpdateEntityInput
  ): Promise<HubEntity | HubGovernanceResult> {
    // Backend may return a full entity (approved) or a governance envelope
    // (proposed/denied). Callers MUST check `status` first when governance
    // is likely — e.g., agent-owned workspaces, destructive updates.
    const { properties, content, url, status, priority, dueDate, ...rest } =
      input;
    return this.request<HubEntity | HubGovernanceResult>(
      "PATCH",
      `/api/hub/entities/${id}`,
      {
        ...rest,
        metadata: {
          ...properties,
          ...(content !== undefined ? { content } : {}),
          ...(url !== undefined ? { url } : {}),
          ...(status !== undefined ? { status } : {}),
          ...(priority !== undefined ? { priority } : {}),
          ...(dueDate !== undefined ? { 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: string,
    options?: {
      collections?: Array<"entities" | "documents" | "views">;
      workspaceId?: string;
      limit?: number;
    },
    signal?: AbortSignal
  ): Promise<HubSearchResult> {
    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<HubSearchResult>(
      "GET",
      `/api/hub/search?${params}`,
      undefined,
      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: string,
    options?: { workspaceId?: string }
  ): Promise<HubRelation[]> {
    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<
      HubRelation[] | HubListResponse<HubRelation>
    >("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: CreateRelationInput
  ): Promise<HubGovernanceResult> {
    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<HubGovernanceResult>("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: AttachFacetInput): Promise<HubAttachFacetResult> {
    const userId = await this.resolveUserId();
    return this.request<HubAttachFacetResult>(
      "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: string): Promise<void> {
    const userId = await this.resolveUserId();
    await this.request<unknown>("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: string,
    options?: { maxDepth?: number; workspaceId?: string }
  ): Promise<HubGraphResult> {
    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<HubGraphResult>(
      "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: string,
    options?: { workspaceId?: string; limit?: number }
  ): Promise<HubConnectionsResult> {
    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<HubConnectionsResult>(
      "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?: HubOrientOptions): Promise<HubOrientResult> {
    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<HubOrientResult>("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: string,
    options?: { detail?: "full" }
  ): Promise<HubProfile[]> {
    const userId = await this.resolveUserId();
    const params = new URLSearchParams({ userId, workspaceId });
    if (options?.detail) params.set("detail", options.detail);
    const result = await this.request<
      HubProfile[] | HubListResponse<HubProfile>
    >("GET", `/api/hub/profiles?${params}`);
    return unwrapList(result);
  }

  /**
   * List property definitions for a workspace, optionally filtered by profile.
   */
  async listPropertyDefs(
    workspaceId: string,
    options?: { profileSlug?: string }
  ): Promise<HubPropertyDef[]> {
    const userId = await this.resolveUserId();
    const params = new URLSearchParams({ userId, workspaceId });
    if (options?.profileSlug) params.set("profileId", options.profileSlug);
    const result = await this.request<
      HubPropertyDef[] | HubListResponse<HubPropertyDef>
    >("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?: string | HubDiscoverOptions
  ): Promise<HubDiscoverResult> {
    const userId = await this.resolveUserId();
    const normalized =
      typeof options === "string" ? { workspaceId: options } : (options ?? {});
    const params = new URLSearchParams({ userId });
    // No configured fallback: an omitted workspace asks for the base schema,
    // while an explicit one resolves only that workspace's overlays.
    if (normalized.workspaceId)
      params.set("workspaceId", normalized.workspaceId);
    if (normalized.summary !== undefined)
      params.set("summary", String(normalized.summary));
    if (normalized.profileSlugs?.length)
      params.set("profileSlugs", normalized.profileSlugs.join(","));
    return this.request<HubDiscoverResult>(
      "GET",
      `/api/hub/discover?${params}`
    );
  }

  // ─── Threads & Channels ───────────────────────────────────────────────────

  /**
   * List threads (channels) accessible to a user.
   */
  async listThreads(
    userId: string,
    options?: { workspaceId?: string; type?: string }
  ): Promise<HubThread[]> {
    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<HubThread[] | HubListResponse<HubThread>>(
      "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: string,
    workspaceId?: string
  ): Promise<HubThread> {
    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<HubThread>(
      "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: CreateThreadInput): Promise<HubThread> {
    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<HubThread>("POST", "/api/hub/threads", {
      userId,
      workspaceId: wsId,
      title: input.name,
      agentType: input.agentType,
      contextObjectType: input.entityId
        ? "entity"
        : input.documentId
          ? "document"
          : undefined,
      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: string): Promise<HubThreadContext> {
    return this.request<HubThreadContext>(
      "GET",
      `/api/hub/threads/${threadId}/context`
    );
  }

  /**
   * Get messages in a thread.
   */
  async getMessages(
    threadId: string,
    _options?: { limit?: number; before?: string }
  ): Promise<HubMessage[]> {
    // The backend GET /threads/:threadId/messages does not accept query params in
    // the current implementation — returns all messages ordered by timestamp.
    const result = await this.request<
      HubMessage[] | HubListResponse<HubMessage>
    >("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: string, entityId: string): Promise<void> {
    const userId = await this.resolveUserId();
    await this.request<unknown>(
      "POST",
      `/api/hub/threads/${threadId}/link-entity`,
      { userId, entityId }
    );
  }

  /**
   * Link a document to a thread.
   */
  async linkDocumentToThread(
    threadId: string,
    documentId: string
  ): Promise<void> {
    const userId = await this.resolveUserId();
    await this.request<unknown>(
      "POST",
      `/api/hub/threads/${threadId}/link-document`,
      { userId, documentId }
    );
  }

  /**
   * Get research branches of a thread — parallel AI investigations.
   */
  async getThreadBranches(
    threadId: string
  ): Promise<
    Array<{ channelId: string; branchPurpose: string | null; status: string }>
  > {
    const result = await this.request<{
      branches: Array<{
        channelId: string;
        branchPurpose: string | null;
        status: string;
      }>;
    }>("GET", `/api/hub/threads/${threadId}/branches`);
    return result.branches ?? [];
  }

  // ─── Memory ───────────────────────────────────────────────────────────────

  async storeMemory(input: StoreMemoryInput): Promise<{ id: string }> {
    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<{ id: string }>("POST", "/api/hub/memory", {
      userId,
      fact,
    });
  }

  async recallMemory(
    query: string,
    options?: { workspaceId?: string; limit?: number }
  ): Promise<HubMemoryResult[]> {
    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<
      HubMemoryResult[] | HubListResponse<HubMemoryResult>
    >("GET", `/api/hub/memory?${params}`);
    return unwrapList(result);
  }

  /**
   * Delete a stored memory fact by ID.
   */
  async deleteMemory(memoryId: string): Promise<void> {
    const userId = await this.resolveUserId();
    const params = new URLSearchParams({ userId });
    await this.request<unknown>(
      "DELETE",
      `/api/hub/memory/${memoryId}?${params}`
    );
  }

  // ─── Channels (Hub REST: channels are listed via GET /threads) ────────────

  async getChannels(options?: { workspaceId?: string }): Promise<HubChannel[]> {
    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<
      HubChannel[] | HubListResponse<HubChannel>
    >("GET", `/api/hub/threads?${params}`);
    return unwrapList(result);
  }

  async sendToChannel(input: SendToChannelInput): Promise<{ id: string }> {
    const userId = input.userId ?? (await this.resolveUserId());
    return this.request<{ id: string }>(
      "POST",
      `/api/hub/threads/${input.channelId}/messages`,
      {
        role: input.role ?? "user",
        content: input.content,
        userId,
        ...(input.autoRespond !== undefined
          ? { autoRespond: input.autoRespond }
          : {}),
      }
    );
  }

  // ─── Proposals ────────────────────────────────────────────────────────────

  /**
   * List proposals — pending AI writes awaiting human review.
   * Filter by status: "pending" (needs review), "approved", "rejected".
   */
  async listProposals(options?: {
    status?: "pending" | "approved" | "rejected";
    workspaceId?: string;
    /**
     * "workspace" (default) — applies the client workspaceId filter.
     * "all" — omits workspaceId so results span every workspace the user can see.
     */
    scope?: "workspace" | "all";
    limit?: number;
  }): Promise<HubProposal[]> {
    const userId = await this.resolveUserId();
    const params = new URLSearchParams({ userId });
    // When scope === "all", intentionally omit workspaceId — matches searchEntities/
    // getRecentEntities so a "review everything" caller isn't silently narrowed to
    // just the connection's default workspace.
    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<
      HubProposal[] | HubListResponse<HubProposal>
    >("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: string,
    decision: "approved" | "rejected",
    reason?: string
  ): Promise<HubProposal> {
    return this.request<HubProposal>(
      "PATCH",
      `/api/hub/proposals/${proposalId}`,
      {
        data: { status: decision },
        summary: reason,
      }
    );
  }

  // ─── Views ────────────────────────────────────────────────────────────────

  /**
   * List data views in a workspace.
   */
  async listViews(
    workspaceId: string,
    options?: { profileSlug?: string }
  ): Promise<HubView[]> {
    const userId = await this.resolveUserId();
    const params = new URLSearchParams({ userId, workspaceId });
    if (options?.profileSlug) params.set("profileId", options.profileSlug);
    const result = await this.request<HubView[] | HubListResponse<HubView>>(
      "GET",
      `/api/hub/views?${params}`
    );
    return unwrapList(result);
  }

  /**
   * Create a new view. Goes through governance.
   */
  async createView(input: CreateViewInput): Promise<HubGovernanceResult> {
    const userId = input.userId ?? (await this.resolveUserId());
    return this.request<HubGovernanceResult>("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: string,
    input: UpdateViewInput
  ): Promise<HubView | HubGovernanceResult> {
    const userId = input.userId ?? (await this.resolveUserId());
    return this.request<HubView | HubGovernanceResult>(
      "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: string,
    input: ArrangeBentoViewInput
  ): Promise<HubBentoArrangementResult> {
    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<HubBentoArrangementResult>(
      "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: string): Promise<HubDocument> {
    const userId = await this.resolveUserId();
    const params = new URLSearchParams({ userId });
    const result = await this.request<HubDocument | { document: HubDocument }>(
      "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: CreateDocumentInput & { workspaceId?: string }
  ): Promise<HubGovernanceResult> {
    const userId = await this.resolveUserId();
    return this.request<HubGovernanceResult>("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: string,
    input: UpdateDocumentInput
  ): Promise<HubDocumentProposalResult> {
    const userId = await this.resolveUserId();
    return this.request<HubDocumentProposalResult>(
      "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: CreateDocumentProposalInput
  ): Promise<HubDocumentProposalResult> {
    const userId = await this.resolveUserId();
    return this.request<HubDocumentProposalResult>(
      "POST",
      "/api/hub/documents/proposals",
      {
        userId,
        ...input,
      }
    );
  }

  // ─── Capabilities & teaching substrate ───────────────────────────────────

  /** Flat capability read-model. Prefer getCapabilityCatalog() for presentation. */
  async listCapabilities(options?: {
    workspaceId?: string;
  }): Promise<HubCapability[]> {
    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<{ capabilities: HubCapability[] }>(
      "GET",
      `/api/hub/capabilities?${params}`
    );
    return result.capabilities;
  }

  /** Status-computed, pack-grouped capability catalog for every external surface. */
  async getCapabilityCatalog(options?: {
    workspaceId?: string;
    extraKey?: string;
  }): Promise<HubCapabilityCatalogResult> {
    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<HubCapabilityCatalogResult>(
      "GET",
      `/api/hub/capabilities/catalog?${params}`
    );
  }

  /** List only approved, connected actions that this client can execute now. */
  async listRunnableCapabilityActions(options?: {
    workspaceId?: string;
    query?: string;
    kind?: string;
    limit?: number;
  }): Promise<HubRunnableCapabilityActionsResult> {
    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 !== undefined)
      params.set("limit", String(options.limit));
    return this.request<HubRunnableCapabilityActionsResult>(
      "GET",
      `/api/hub/capabilities/actions?${params}`
    );
  }

  /** Run one registered capability through the shared governance gate. */
  async executeCapability(
    input: ExecuteCapabilityInput
  ): Promise<ExecuteCapabilityResult> {
    return this.request<ExecuteCapabilityResult>(
      "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?: ListAgentSkillsOptions
  ): Promise<HubAgentSkillsResult> {
    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 !== undefined)
      params.set("system", String(options.system));
    const workspaceId = options?.workspaceId ?? this.workspaceId;
    if (workspaceId) params.set("workspaceId", workspaceId);
    if (options?.limit !== undefined)
      params.set("limit", String(options.limit));
    if (options?.offset !== undefined)
      params.set("offset", String(options.offset));
    const qs = params.toString() ? `?${params}` : "";
    return this.request<HubAgentSkillsResult>(
      "GET",
      `/api/hub/agent-skills${qs}`
    );
  }

  /** Load one skill body only when it is relevant to the agent's next action. */
  async getAgentSkillBySlug(
    slug: string,
    options?: { workspaceId?: string }
  ): Promise<HubAgentSkill> {
    const workspaceId = options?.workspaceId ?? this.workspaceId;
    const qs = workspaceId ? `?${new URLSearchParams({ workspaceId })}` : "";
    return this.request<HubAgentSkill>(
      "GET",
      `/api/hub/agent-skills/by-slug/${encodeURIComponent(slug)}${qs}`
    );
  }

  /** Compose just-in-time teaching and governance briefs for selected tools. */
  async getCapabilityBriefs(
    input: GetCapabilityBriefsInput
  ): Promise<HubCapabilityBriefsResult> {
    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<HubCapabilityBriefsResult>(
      "GET",
      `/api/hub/briefs?${params}`
    );
  }

  // ─── Commands & Agents ────────────────────────────────────────────────────

  /**
   * List available commands (automation shortcuts) in the workspace.
   */
  async listCommands(workspaceId?: string): Promise<HubCommand[]> {
    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<
      HubCommand[] | HubListResponse<HubCommand>
    >("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: ExecuteCommandInput
  ): Promise<{ status: string; result?: unknown }> {
    const userId = input.userId ?? (await this.resolveUserId());
    return this.request<{ status: string; result?: unknown }>(
      "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?: string): Promise<HubAgentUser[]> {
    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<
      HubAgentUser[] | HubListResponse<HubAgentUser>
    >("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: string,
    content: string,
    options?: { workspaceId?: string; type?: string }
  ): Promise<{ id: string }> {
    const wsId = options?.workspaceId ?? this.workspaceId;
    if (!wsId) throw new Error("workspaceId is required for postProactive");
    return this.request<{ id: string }>("POST", "/api/hub/proactive/post", {
      userId,
      workspaceId: wsId,
      content,
      proactiveType: options?.type ?? "insight",
    });
  }

  // ─── Capture pipeline ─────────────────────────────────────────────────────

  async captureStructure(input: {
    text: string;
    url?: string;
    workspaceId?: string;
    previousEntities?: CaptureProposal[];
  }): Promise<CaptureStructureResponse> {
    const userId = await this.resolveUserId();
    return this.request<CaptureStructureResponse>(
      "POST",
      "/api/hub/capture/structure",
      {
        userId,
        text: input.text,
        url: input.url,
        workspaceId: input.workspaceId ?? this.workspaceId,
        previousEntities: input.previousEntities,
      }
    );
  }

  async captureExecute(
    input: CaptureExecuteInput & { workspaceId?: string }
  ): Promise<CaptureExecuteResponse> {
    const userId = await this.resolveUserId();
    return this.request<CaptureExecuteResponse>(
      "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: SubmitCaptureGraphInput
  ): Promise<SubmitCaptureGraphResult> {
    const { workspaceId, relations, bindings, ...body } = input;
    return this.request<SubmitCaptureGraphResult>(
      "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: {
    query: string;
    workspaceId?: string;
    limit?: number;
    /**
     * Return just the glass-box understanding + routing (no retrieval) — for a
     * caller that routes a query before fetching results (e.g. a palette
     * completing a type word). `answers` comes back empty.
     */
    parseOnly?: boolean;
  }): Promise<AskResponse> {
    return this.request<AskResponse>("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?: {
    workspaceId?: string;
    status?: AutomationStatus;
    limit?: number;
  }): Promise<HubAutomation[]> {
    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<
      HubAutomation[] | HubListResponse<HubAutomation>
    >("GET", `/api/hub/automations?${params}`);
    return unwrapList(result);
  }

  /**
   * Get a single automation by ID.
   */
  async getAutomation(
    automationId: string,
    options?: { workspaceId?: string }
  ): Promise<HubAutomation> {
    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<HubAutomation>(
      "GET",
      `/api/hub/automations/${automationId}?${params}`
    );
  }

  /**
   * Create an automation. Defaults to status=draft.
   * Use activateAutomation() to enable it.
   */
  async createAutomation(input: CreateAutomationInput): Promise<HubAutomation> {
    const userId = input.userId ?? (await this.resolveUserId());
    const wsId = input.workspaceId ?? this.workspaceId;
    return this.request<HubAutomation>("POST", "/api/hub/automations/create", {
      ...input,
      userId,
      workspaceId: wsId ?? null,
    });
  }

  /**
   * Update an automation's definition or metadata.
   */
  async updateAutomation(
    automationId: string,
    input: UpdateAutomationInput
  ): Promise<HubAutomation> {
    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<HubAutomation>(
      "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: string,
    options?: {
      payload?: Record<string, unknown>;
      workspaceId?: string;
    }
  ): Promise<{ status: string; runId?: string; result?: unknown }> {
    const userId = await this.resolveUserId();
    const wsId = options?.workspaceId ?? this.workspaceId;
    return this.request<{ status: string; runId?: string; result?: unknown }>(
      "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: string,
    options?: { workspaceId?: string }
  ): Promise<HubAutomation> {
    const userId = await this.resolveUserId();
    const wsId = options?.workspaceId ?? this.workspaceId;
    if (!wsId)
      throw new Error("workspaceId is required for activateAutomation");
    return this.request<HubAutomation>(
      "POST",
      `/api/hub/automations/${automationId}/activate`,
      { userId, workspaceId: wsId }
    );
  }

  /**
   * Pause an active automation (sets status=paused).
   */
  async pauseAutomation(
    automationId: string,
    options?: { workspaceId?: string }
  ): Promise<HubAutomation> {
    const userId = await this.resolveUserId();
    const wsId = options?.workspaceId ?? this.workspaceId;
    if (!wsId) throw new Error("workspaceId is required for pauseAutomation");
    return this.request<HubAutomation>(
      "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?: {
    workspaceId?: string;
    kind?: ReactionKind;
    eventType?: string;
    lens?: ReactionLens;
    limit?: number;
  }): Promise<HubReactionEvent[]> {
    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<
      HubReactionEvent[] | HubListResponse<HubReactionEvent>
    >("GET", `/api/hub/subscriptions${qs}`);
    return unwrapList(result);
  }

  /**
   * Get the reaction fan-out for a single event — full reactions[] populated.
   */
  async getSubscriptionFanout(
    eventId: string,
    options?: { lens?: ReactionLens }
  ): Promise<HubReactionEvent> {
    const params = new URLSearchParams();
    if (options?.lens) params.set("lens", options.lens);
    const qs = params.toString() ? `?${params}` : "";
    return this.request<HubReactionEvent>(
      "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: CreateNotificationInput
  ): Promise<{ id: string }> {
    return this.request<{ id: string }>(
      "POST",
      "/api/hub/notifications",
      input
    );
  }

  // ─── Webhooks ──────────────────────────────────────────────────────────────

  /**
   * List delivery log for a webhook subscription.
   * Powers the Reactions Health tab and replay flows.
   */
  async getWebhookDeliveries(
    subscriptionId: string,
    options?: { limit?: number }
  ): Promise<HubWebhookDelivery[]> {
    const params = new URLSearchParams();
    if (options?.limit) params.set("limit", String(options.limit));
    const qs = params.toString() ? `?${params}` : "";
    const result = await this.request<
      HubWebhookDelivery[] | HubListResponse<HubWebhookDelivery>
    >("GET", `/api/hub/webhooks/${subscriptionId}/deliveries${qs}`);
    return unwrapList(result);
  }
}