@synap-core/cli 1.8.0 → 1.11.0

package/node_modules/@synap/hub-rest-client/src/client.ts

@@ -33,6 +33,7 @@ import type {
   CaptureStructureResponse,
   CaptureExecuteInput,
   CaptureExecuteResponse,
+  AskResponse,
   HubDocument,
   HubRelation,
   HubGraphResult,
@@ -40,6 +41,9 @@ import type {
   HubProfile,
   HubPropertyDef,
   HubDiscoverResult,
+  HubDiscoverOptions,
+  HubOrientOptions,
+  HubOrientResult,
   HubThread,
   HubMessage,
   HubThreadContext,
@@ -52,9 +56,29 @@ import type {
   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,
@@ -73,8 +97,17 @@ export interface HubRestClientConfig {
   apiKey: string;
   /** Default workspace ID — used when not specified per call */
   workspaceId?: string;
-  /** Optional request timeout in ms (default: 30000) */
+  /** 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 {
@@ -108,9 +141,7 @@ function unwrapList<T>(result: T[] | HubListResponse<T>): T[] {
 /** Hub GET /workspaces returns `{ workspaces }`, not `{ data }`. */
 function unwrapWorkspacesResponse(
   result:
-    | HubWorkspace[]
-    | HubListResponse<HubWorkspace>
-    | HubWorkspacesListResponse
+    HubWorkspace[] | HubListResponse<HubWorkspace> | HubWorkspacesListResponse
 ): HubWorkspace[] {
   if (Array.isArray(result)) return result;
   if (result && typeof result === "object" && "workspaces" in result) {
@@ -131,6 +162,9 @@ 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. */
@@ -144,6 +178,9 @@ export class HubRestClient {
     };
     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). */
@@ -154,33 +191,112 @@ export class HubRestClient {
     return me.id;
   }
 
-  private async request<T>(
+  /**
+   * 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 url = `${this.base}${path}`;
-    const timeout = AbortSignal.timeout(this.timeoutMs);
-    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
-
-    const res = await fetch(url, {
-      method,
-      headers: this.headers,
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-      signal: combined,
-    });
+    const res = await this.fetchWithRetry(method, path, body, signal);
+    if (!res.ok) throw await this.toHubError(res);
+    return this.parseBody<T>(res);
+  }
 
-    if (!res.ok) {
-      const errorBody = await res.json().catch(() => ({}));
-      throw new HubApiError(
-        formatHubErrorMessage(res.status, res.statusText, errorBody),
-        res.status,
-        errorBody
-      );
-    }
+  /**
+   * 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);
+  }
 
-    return res.json() as Promise<T>;
+  /**
+   * 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 ─────────────────────────────────────────────────────────────
@@ -292,9 +408,22 @@ export class HubRestClient {
   }
 
   async createEntity(input: CreateEntityInput): Promise<HubGovernanceResult> {
+    const { content, url, status, priority, dueDate, properties, ...rest } =
+      input;
     return this.request<HubGovernanceResult>("POST", "/api/hub/entities", {
-      ...input,
-      workspaceId: input.workspaceId ?? this.workspaceId,
+      ...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 } : {}),
+      },
     });
   }
 
@@ -305,10 +434,22 @@ export class HubRestClient {
     // 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}`,
-      input
+      {
+        ...rest,
+        metadata: {
+          ...properties,
+          ...(content !== undefined ? { content } : {}),
+          ...(url !== undefined ? { url } : {}),
+          ...(status !== undefined ? { status } : {}),
+          ...(priority !== undefined ? { priority } : {}),
+          ...(dueDate !== undefined ? { dueDate } : {}),
+        },
+      }
     );
   }
 
@@ -389,6 +530,29 @@ export class HubRestClient {
     });
   }
 
+  /**
+   * 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()).
    */
@@ -427,10 +591,10 @@ export class HubRestClient {
   }
 
   /**
-   * Unified view of everything connected to an entity. Merges three sources:
+   * 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 — entities whose `entity_id` properties point to this entity
-   *   3. Thread connections — chat threads that touched this entity
+   *   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
@@ -457,6 +621,23 @@ export class HubRestClient {
     );
   }
 
+  // ─── 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 ────────────────────────────────────────────────────
 
   /**
@@ -464,9 +645,13 @@ export class HubRestClient {
    * Always call before creating entities to discover what types are available.
    * Returns system profiles (always present) + custom workspace profiles.
    */
-  async listProfiles(workspaceId: string): Promise<HubProfile[]> {
+  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}`);
@@ -496,10 +681,21 @@ export class HubRestClient {
    * schemas (including custom workspace profiles) and the canonical CLI
    * command map. Replaces static skill file profile descriptions.
    */
-  async discover(workspaceId?: string): Promise<HubDiscoverResult> {
+  async discover(
+    options?: string | HubDiscoverOptions
+  ): Promise<HubDiscoverResult> {
     const userId = await this.resolveUserId();
-    const wsId = workspaceId ?? this.workspaceId ?? "";
-    const params = new URLSearchParams({ userId, workspaceId: wsId });
+    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}`
@@ -724,13 +920,23 @@ export class HubRestClient {
   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 wsId = options?.workspaceId ?? this.workspaceId;
     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 (wsId) params.set("workspaceId", wsId);
     if (options?.limit) params.set("limit", String(options.limit));
     const result = await this.request<
       HubProposal[] | HubListResponse<HubProposal>
@@ -791,9 +997,59 @@ export class HubRestClient {
       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 ────────────────────────────────────────────────────────────
 
   /**
@@ -802,10 +1058,11 @@ export class HubRestClient {
   async getDocument(documentId: string): Promise<HubDocument> {
     const userId = await this.resolveUserId();
     const params = new URLSearchParams({ userId });
-    return this.request<HubDocument>(
+    const result = await this.request<HubDocument | { document: HubDocument }>(
       "GET",
       `/api/hub/documents/${documentId}?${params}`
     );
+    return "document" in result ? result.document : result;
   }
 
   /**
@@ -821,9 +1078,174 @@ export class HubRestClient {
       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 ────────────────────────────────────────────────────
 
   /**
@@ -933,10 +1355,76 @@ export class HubRestClient {
         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 ───────────────────────────────────────────────────────────
 
   /**