@synap-core/cli 1.8.0 → 1.11.0

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

@@ -57,6 +57,9 @@ var HubRestClient = class {
   base;
   headers;
   timeoutMs;
+  readTimeoutMs;
+  writeTimeoutMs;
+  maxAttempts;
   workspaceId;
   /** Cached from GET /users/me — avoids repeated identity calls. */
   resolvedUserId = null;
@@ -68,6 +71,9 @@ var HubRestClient = class {
     };
     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() {
@@ -76,25 +82,80 @@ var HubRestClient = class {
     this.resolvedUserId = me.id;
     return me.id;
   }
-  async request(method, path, body, signal) {
+  /**
+   * 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 timeout = AbortSignal.timeout(this.timeoutMs);
-    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
-    const res = await fetch(url, {
-      method,
-      headers: this.headers,
-      body: body !== void 0 ? JSON.stringify(body) : void 0,
-      signal: combined
-    });
-    if (!res.ok) {
-      const errorBody = await res.json().catch(() => ({}));
-      throw new HubApiError(
-        formatHubErrorMessage(res.status, res.statusText, errorBody),
-        res.status,
-        errorBody
-      );
+    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;
+      }
     }
-    return res.json();
+    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() {
@@ -166,16 +227,39 @@ var HubRestClient = class {
     return unwrapList(result);
   }
   async createEntity(input) {
+    const { content, url, status, priority, dueDate, properties, ...rest } = input;
     return this.request("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 !== 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}`,
-      input
+      {
+        ...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 ───────────────────────────────────────────────────────
@@ -235,6 +319,28 @@ var HubRestClient = class {
       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()).
    */
@@ -268,10 +374,10 @@ var HubRestClient = class {
     );
   }
   /**
-   * 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
@@ -294,15 +400,31 @@ var HubRestClient = class {
       `/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) {
+  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);
   }
@@ -323,10 +445,16 @@ var HubRestClient = class {
    * schemas (including custom workspace profiles) and the canonical CLI
    * command map. Replaces static skill file profile descriptions.
    */
-  async discover(workspaceId) {
+  async discover(options) {
     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 });
+    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}`
@@ -488,10 +616,12 @@ var HubRestClient = class {
    */
   async listProposals(options) {
     const userId = await this.resolveUserId();
-    const wsId = options?.workspaceId ?? this.workspaceId;
     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 (wsId) params.set("workspaceId", wsId);
     if (options?.limit) params.set("limit", String(options.limit));
     const result = await this.request("GET", `/api/hub/proposals?${params}`);
     return unwrapList(result);
@@ -538,9 +668,51 @@ var HubRestClient = class {
       name: input.name,
       type: input.type,
       profileId: input.profileSlug,
-      config: input.config
+      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.
@@ -548,10 +720,11 @@ var HubRestClient = class {
   async getDocument(documentId) {
     const userId = await this.resolveUserId();
     const params = new URLSearchParams({ userId });
-    return this.request(
+    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.
@@ -563,9 +736,140 @@ var HubRestClient = class {
       userId,
       workspaceId: input.workspaceId ?? this.workspaceId,
       title: input.title,
-      content: input.content ?? ""
+      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.
@@ -649,10 +953,61 @@ var HubRestClient = class {
         userId,
         entities: input.entities,
         relations: input.relations ?? [],
-        workspaceId: input.workspaceId ?? this.workspaceId
+        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.
@@ -806,6 +1161,30 @@ var HubRestClient = class {
 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 };
@@ -822,7 +1201,8 @@ async function checkPodHealth(podUrl) {
   }
   return status;
 }
-async function setupAgent(podUrl, provisioningToken, agentType = "openclaw") {
+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",

package/node_modules/@synap/hub-rest-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap/hub-rest-client",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Zero-dependency TypeScript client for the Synap Hub Protocol REST API",
   "type": "module",
   "main": "./dist/index.cjs",