@synap-core/sdk 1.3.0 → 1.5.0

package/src/connect/client.ts

@@ -1,23 +1,58 @@
 /**
  * A server-side Hub REST client for one PodConnection: `<pod>/api/hub/*` with
  * the connection's Bearer token. Results, not throws: `{ ok: true, … }` or
- * `{ ok: false, error }` with a typed `code`.
+ * `{ ok: false, error }` with a typed `code`, a malformed path included.
  *
  *  - `expired`: the access token is past its expiry here; nothing was sent
  *    (refresh in `proxy.ts` / a route handler, or connect again);
- *  - `unauthorized`: the pod refused the token (revoked, or expired there);
+ *  - `unauthorized`: the pod refused the token. With a `renew` (a client that
+ *    can persist cookies) the connection is renewed once and the request
+ *    retried once first; `unauthorized` then means the pod refused the
+ *    connection itself. Without one, `refreshable` says a renewal may help;
  *  - `forbidden`: not granted; `door_unsupported`: a door a space-scoped app
- *    token can never use (403 GRANT_DOOR_UNSUPPORTED, spec 17 §5);
- *  - `rate_limited` with `retryAfterSec`; `pod_unreachable` (network, 502-504).
+ *    token can never use (403 GRANT_DOOR_UNSUPPORTED);
+ *  - `rate_limited` with `retryAfterSec`; `pod_unreachable` (network, a
+ *    timeout, 502-504); `pod_moved` (a redirect: connect again);
+ *  - `invalid`: the pod refused the input (400/422), or the SDK did (a path
+ *    that could leave the Hub API: encode each segment, `encodeURIComponent`).
  *
  * Writes are governed: `proposed` is SUCCESS (queued for the person's review,
- * never retry it), with `reviewUrl` on the pod.
+ * never retry it), with `reviewUrl` on the pod. That is the rule of an AGENT
+ * connection (`actsAs: "agent"`, every app but an official Synap one): its
+ * writes are proposals. A PERSON connection (`actsAs: "person"`, an official
+ * Synap app) writes as the person, directly: its writes apply and come back
+ * `applied`, with no review step and no proposal. The result
+ * still reports what the pod did, so a `proposed` answer to a person (a space
+ * that reviews even its members' changes) is still success, never an error.
  *
- * The token goes to the pod's own origin only: paths are pod-relative, no
- * redirect is followed.
+ * Typed methods (1.5) for the doors a pod app reads: `listEntities`,
+ * `getEntity`, `getEntityConnections`, `getDocument`, `listFocusSessions`,
+ * `getFileUrl`, `listPendingProposals`, `approveProposal`. Same results, same
+ * codes; a refusal the SDK can decide alone (no grant, an agent approving, a
+ * bad id) answers with `status: null` and a `reason`, and sends nothing.
+ *
+ * The token goes to the pod's own origin only: paths are pod-relative and
+ * checked again after URL resolution, no redirect is followed. Each request
+ * is bounded: 10 s and 8 MiB by default (`timeoutMs`, `maxResponseBytes`).
  */
-import { retryAfterSeconds } from "./errors";
-import type { PodConnection, PodGrant } from "./types";
+import { isConnectError, retryAfterSeconds, type ConnectError } from "./errors";
+import { readCapped, timeoutSignal } from "./http";
+import type {
+  ApproveProposalOptions,
+  GetDocumentOptions,
+  GetEntityConnectionsOptions,
+  ListEntitiesOptions,
+  ListFocusSessionsOptions,
+  PodApproval,
+  PodDocument,
+  PodEntity,
+  PodEntityConnection,
+  PodEntityConnections,
+  PodFileUrl,
+  PodFocusSession,
+  PodSessionSlot,
+} from "./hub-types";
+import type { PodActsAs, PodConnection, PodGrant, PodSpace } from "./types";
 
 export type PodErrorCode =
   | "expired"
@@ -29,8 +64,19 @@ export type PodErrorCode =
   | "conflict"
   | "rate_limited"
   | "pod_unreachable"
+  /** The pod answered a redirect (a moved pod answers 308 from its old name): connect again at its new address. */
+  | "pod_moved"
   | "server";
 
+/**
+ * Why the SDK refused before sending anything (`status: null`):
+ *  - `agent_cannot_approve`: an agent connection asked to approve (the pod
+ *    never lets an agent credential approve; `code: "forbidden"`);
+ *  - `not_granted`: the connection holds no permission for it (`forbidden`);
+ *  - `invalid_input`: an id, a path or an option the pod would refuse (`invalid`).
+ */
+export type PodRefusalReason = "agent_cannot_approve" | "not_granted" | "invalid_input";
+
 export interface PodError {
   code: PodErrorCode;
   /** The HTTP status, or null when nothing was answered. */
@@ -38,6 +84,17 @@ export interface PodError {
   retryAfterSec?: number;
   /** The pod's own error text, for logs only. */
   detail?: string;
+  /** Set when the SDK refused locally (1.5). */
+  reason?: PodRefusalReason;
+  /**
+   * On `unauthorized` (1.5): the pod refused the access token, the connection
+   * still holds a refresh token, and this client could not renew it (no
+   * `renew`). A forced refresh may restore it (a narrow, or a pod-side "Revoke
+   * key", ends the key, not the connection): run `refreshIfNeeded(request,
+   * { force: true })` where cookies can be set. Absent = the pod refused the
+   * connection itself: connect again.
+   */
+  refreshable?: true;
 }
 
 export type PodResult<T> = { ok: true; data: T } | { ok: false; error: PodError };
@@ -49,17 +106,105 @@ export type PodWriteResult<T> =
 
 export type QueryValue = string | number | boolean | null | undefined | ReadonlyArray<string | number | boolean>;
 
+/** One pending proposal, the pod's summary row (`GET /proposals?view=basic`). */
+export interface PendingProposal {
+  id: string;
+  proposalType: string;
+  targetType: string;
+  targetId: string | null;
+  workspaceId: string | null;
+  /** ISO 8601, as the pod sent it. */
+  createdAt: string;
+  /** The agent that filed it (this app's agent, or another one), when known. */
+  agentUserId: string | null;
+  sessionId: string | null;
+  summary?: string;
+  /** Where the person reviews it: the pod's deep link. */
+  reviewUrl: string;
+}
+
+export interface PendingProposals {
+  /** Every pending proposal the connection can see, not only this page (the pod COUNTs it). */
+  total: number;
+  proposals: PendingProposal[];
+  hasMore: boolean;
+}
+
+export interface ListPendingProposalsOptions {
+  /** One granted space only. */
+  workspaceId?: string;
+  /** 1-200, default 20. */
+  limit?: number;
+  offset?: number;
+  /**
+   * Only these proposals (at most 100 ids; the pod's `proposalIds` filter,
+   * pods that do not filter are filtered here). An empty list matches nothing (answered without a request).
+   */
+  proposalIds?: readonly string[];
+}
+
 export interface PodClientOptions {
   fetch?: typeof fetch;
   now?: () => number;
+  /** Per Hub request, default 10 000 ms; a request past it is `pod_unreachable`. */
+  timeoutMs?: number;
+  /** The most a Hub answer may weigh, default 8 MiB; a bigger one is `server` (the body is not read further). */
+  maxResponseBytes?: number;
+  /**
+   * Renew the connection after the pod refused its access token (401) while it
+   * holds a refresh token: rotate it, PERSIST the result (the old refresh token
+   * is spent once the pod answers), then return it; throw the refresh's
+   * `ConnectError` when it fails. The client calls it at most once (concurrent
+   * 401s share the call), retries the refused request once with the result, and
+   * uses it from then on. `PodAppAuth.client(connection, { persist })` builds
+   * one. Without it a 401 stays `unauthorized` (with `refreshable`).
+   */
+  renew?: (connection: PodConnection) => Promise<PodConnection>;
 }
 
 export interface PodClient {
   podUrl: string;
-  user: PodConnection["user"];
-  grant: PodGrant[];
+  /** The connection's, or the renewed one's after a 401 (`renew`). */
+  readonly user: PodConnection["user"];
+  readonly grant: PodGrant[];
+  /** Who the token acts as (`connectionActsAs`): `"agent"` unless the pod said `"person"`. */
+  readonly actsAs: PodActsAs;
   /** Whether the connection was granted `permission` (in `workspaceId` when given). */
   can(permission: string, workspaceId?: string): boolean;
+  /** The granted spaces, each with its permissions (`spaces(connection)`). */
+  spaces(): PodSpace[];
+  /**
+   * "Waiting for review: N". The person's pending proposals in the spaces this
+   * connection may read proposals in (any agent's, not only this app's), from
+   * the pod's seamed `GET /proposals` door. Needs the `proposal.read`
+   * permission (ask for it in `requests`): without it the pod would answer an
+   * empty list, so this answers `forbidden` instead, without a request.
+   */
+  listPendingProposals(opts?: ListPendingProposalsOptions): Promise<PodResult<PendingProposals>>;
+  /** `GET /entities` (no full-text `q`: a space-scoped token may list, never search). */
+  listEntities(opts?: ListEntitiesOptions): Promise<PodResult<PodEntity[]>>;
+  /** `GET /entities/:id`; `not_found` when it does not exist or is not readable. */
+  getEntity(id: string): Promise<PodResult<PodEntity>>;
+  /** `GET /entities/:id/connections`: its relations, property links, threads and sessions. */
+  getEntityConnections(id: string, opts?: GetEntityConnectionsOptions): Promise<PodResult<PodEntityConnections>>;
+  /** `GET /documents/:id`: content, revision, sections. */
+  getDocument(id: string, opts?: GetDocumentOptions): Promise<PodResult<PodDocument>>;
+  /**
+   * `GET /focus-sessions` in a space (or a project), newest first, with their
+   * slots (`expectedOutputs`; `humanSlots(session)` = what waits on the person).
+   * `invalid` without a request when neither `workspaceId` nor `projectId` is given.
+   */
+  listFocusSessions(opts: ListFocusSessionsOptions): Promise<PodResult<PodFocusSession[]>>;
+  /** `GET /files/:id/url`: a signed download URL for a file entity (about an hour). */
+  getFileUrl(entityId: string): Promise<PodResult<PodFileUrl>>;
+  /**
+   * `POST /proposals/:id/approve`, as the person. Only a PERSON connection
+   * (`actsAs: "person"`) holding `proposal.approve` can: an agent connection
+   * gets `forbidden` / `agent_cannot_approve` and NOTHING is sent (the pod
+   * never lets an agent approve); without the permission, `forbidden` /
+   * `not_granted`, also without a request.
+   */
+  approveProposal(id: string, opts?: ApproveProposalOptions): Promise<PodResult<PodApproval>>;
   get<T = unknown>(path: string, query?: Record<string, QueryValue>): Promise<PodResult<T>>;
   post<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
   patch<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
@@ -67,18 +212,62 @@ export interface PodClient {
   delete<T = unknown>(path: string, body?: unknown): Promise<PodWriteResult<T>>;
 }
 
+/** Who `connection`'s token acts as: `"person"` only when the pod said so, else `"agent"`. */
+export function connectionActsAs(connection: Pick<PodConnection, "actsAs">): PodActsAs {
+  return connection.actsAs === "person" ? "person" : "agent";
+}
+
+/**
+ * The slots of `session` that wait on the person (Home's "needs you"):
+ * `owner: "human"`, not done, not retired.
+ */
+export function humanSlots(session: Pick<PodFocusSession, "expectedOutputs">): PodSessionSlot[] {
+  return session.expectedOutputs.filter((slot) => slot.owner === "human" && slot.status !== "done" && !slot.retiredAt);
+}
+
 /** Whether `connection` was granted `permission` (in `workspaceId` when given). Exact match: grants carry no wildcard. */
 export function can(connection: Pick<PodConnection, "grant">, permission: string, workspaceId?: string): boolean {
   return connection.grant.some((g) => g.permission === permission && (workspaceId === undefined || g.workspaceId === workspaceId));
 }
 
+/**
+ * The grant by space, in the grant's order, each permission once. The pod
+ * sends one row per permission per space; a space switcher wants one per space.
+ */
+export function spaces(connection: Pick<PodConnection, "grant">): PodSpace[] {
+  const bySpace = new Map<string, PodSpace>();
+  for (const g of connection.grant) {
+    const space = bySpace.get(g.workspaceId) ?? { workspaceId: g.workspaceId, workspaceName: g.workspaceName, permissions: [] };
+    if (!space.workspaceName && g.workspaceName) space.workspaceName = g.workspaceName;
+    if (!space.templateSlug && g.templateSlug) space.templateSlug = g.templateSlug;
+    if (!space.permissions.includes(g.permission)) space.permissions.push(g.permission);
+    bySpace.set(g.workspaceId, space);
+  }
+  return [...bySpace.values()];
+}
+
+/** An id the SDK puts in a path: uuids, the pod's short ids, the mock's ids. */
+const ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+const PROPOSAL_IDS_MAX = 100;
+
 const SAFE_PATH = /^\/(?!\/)[A-Za-z0-9\-._~!$&'()*+,;=:@%/]*$/;
+const TIMEOUT_MS = 10_000;
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 
-function hubUrl(podUrl: string, path: string, query?: Record<string, QueryValue>): URL {
-  if (!SAFE_PATH.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) {
-    throw new TypeError(`Not a Hub API path: ${path}`);
+/**
+ * `<pod>/api/hub<path>`, or null when `path` could leave the Hub API: not
+ * pod-relative, a dot segment, plain or percent-encoded (WHATWG resolves
+ * `%2e%2e` as `..`), a backslash, a query. The resolved URL is checked too.
+ */
+function hubUrl(podUrl: string, path: string, query?: Record<string, QueryValue>): URL | null {
+  if (!SAFE_PATH.test(path) || /%2e/i.test(path) || /(^|\/)\.\.?(\/|$)/.test(path) || path.includes("\\")) return null;
+  let url: URL;
+  try {
+    url = new URL(`${podUrl}/api/hub${path}`);
+  } catch {
+    return null;
   }
-  const url = new URL(`${podUrl}/api/hub${path}`);
+  if (url.origin !== new URL(podUrl).origin || !(url.pathname === "/api/hub" || url.pathname.startsWith("/api/hub/"))) return null;
   for (const [key, value] of Object.entries(query ?? {})) {
     if (value === undefined || value === null) continue;
     for (const v of Array.isArray(value) ? value : [value]) url.searchParams.append(key, String(v));
@@ -86,6 +275,28 @@ function hubUrl(podUrl: string, path: string, query?: Record<string, QueryValue>
   return url;
 }
 
+/** A failed renewal (`renew` threw) as the result of the request it was for. */
+function renewalError(err: unknown): PodError {
+  const e: ConnectError | null = isConnectError(err) ? err : null;
+  const detail = e?.message ?? (err instanceof Error ? err.message : "The connection could not be renewed");
+  switch (e?.code) {
+    case "revoked":
+      // The pod refused the connection itself: connect again.
+      return { code: "unauthorized", status: 401, detail };
+    case "expired":
+      // It lapsed, or its renewal could not be stored: connect again.
+      return { code: "expired", status: null, detail };
+    case "rate_limited":
+      return { code: "rate_limited", status: null, detail, ...(e.retryAfterSec !== undefined ? { retryAfterSec: e.retryAfterSec } : {}) };
+    case "pod_unreachable":
+      return { code: "pod_unreachable", status: null, detail };
+    case "pod_moved":
+      return { code: "pod_moved", status: null, detail };
+    default:
+      return { code: "server", status: null, detail };
+  }
+}
+
 function errorFor(status: number, body: unknown, retryAfter: string | null, now: number): PodError {
   const obj = body && typeof body === "object" ? (body as Record<string, unknown>) : {};
   const detail = typeof obj.error === "string" ? obj.error : typeof obj.message === "string" ? obj.message : undefined;
@@ -100,6 +311,7 @@ function errorFor(status: number, body: unknown, retryAfter: string | null, now:
     return { code: "rate_limited", ...base, ...(retryAfterSec !== undefined ? { retryAfterSec } : {}) };
   }
   if (status === 502 || status === 503 || status === 504) return { code: "pod_unreachable", ...base };
+  if (status >= 300 && status < 400) return { code: "pod_moved", ...base };
   return { code: "server", ...base };
 }
 
@@ -119,14 +331,44 @@ export function reviewUrlFor(podUrl: string, reviewUrl: unknown, proposalId: str
   return proposalId ? `${podUrl}/open/${encodeURIComponent(proposalId)}` : podUrl;
 }
 
+function refused(code: PodErrorCode, reason: PodRefusalReason, detail: string): { ok: false; error: PodError } {
+  return { ok: false, error: { code, status: null, detail, reason } };
+}
+
+function asObject(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}
+
+function hasId(value: unknown): value is Record<string, unknown> & { id: string } {
+  return asObject(value) !== null && typeof (value as Record<string, unknown>).id === "string";
+}
+
 export function createPodClient(connection: PodConnection, opts: PodClientOptions = {}): PodClient {
   const now = opts.now ?? Date.now;
   const doFetch = () => opts.fetch ?? fetch;
+  /** The connection in use: `connection`, or what `renew` returned after a 401. */
+  let current = connection;
+  /** The one renewal this client may run: a 401 forces ONE refresh, never a loop. */
+  let renewal: Promise<PodResult<PodConnection>> | null = null;
 
-  async function request(method: string, path: string, body: unknown, query?: Record<string, QueryValue>): Promise<PodResult<unknown>> {
-    const url = hubUrl(connection.podUrl, path, query);
-    if (connection.accessExpiresAt <= now()) return { ok: false, error: { code: "expired", status: null } };
-    const headers: Record<string, string> = { Accept: "application/json", Authorization: `Bearer ${connection.accessToken}` };
+  function renewOnce(refused: PodConnection): Promise<PodResult<PodConnection>> {
+    if (current !== refused) return Promise.resolve({ ok: true, data: current });
+    renewal ??= opts.renew!(refused).then(
+      (next): PodResult<PodConnection> => {
+        current = next;
+        return { ok: true, data: next };
+      },
+      (err: unknown): PodResult<PodConnection> => ({ ok: false, error: renewalError(err) }),
+    );
+    return renewal;
+  }
+
+  async function request(method: string, path: string, body: unknown, query?: Record<string, QueryValue>, retried = false): Promise<PodResult<unknown>> {
+    const sent = current;
+    const url = hubUrl(sent.podUrl, path, query);
+    if (!url) return refused("invalid", "invalid_input", "Not a Hub API path: encode each path segment (encodeURIComponent)");
+    if (sent.accessExpiresAt <= now()) return { ok: false, error: { code: "expired", status: null } };
+    const headers: Record<string, string> = { Accept: "application/json", Authorization: `Bearer ${sent.accessToken}` };
     if (body !== undefined) headers["Content-Type"] = "application/json";
     let res: Response;
     try {
@@ -135,20 +377,35 @@ export function createPodClient(connection: PodConnection, opts: PodClientOption
         headers,
         body: body === undefined ? undefined : JSON.stringify(body),
         redirect: "manual",
+        signal: timeoutSignal(opts.timeoutMs ?? TIMEOUT_MS),
       });
     } catch {
       return { ok: false, error: { code: "pod_unreachable", status: null } };
     }
+    const read = await readCapped(res, opts.maxResponseBytes ?? MAX_RESPONSE_BYTES);
+    if (!read.ok) {
+      return read.reason === "too_large"
+        ? { ok: false, error: { code: "server", status: res.status, detail: "The pod's answer is larger than maxResponseBytes" } }
+        : { ok: false, error: { code: "pod_unreachable", status: res.status, detail: "The pod's answer broke off" } };
+    }
     let data: unknown = null;
-    const text = await res.text().catch(() => "");
-    if (text) {
+    if (read.text) {
       try {
-        data = JSON.parse(text);
+        data = JSON.parse(read.text);
       } catch {
         data = null;
       }
     }
     if (res.status >= 200 && res.status < 300) return { ok: true, data };
+    if (res.status === 401 && sent.refreshToken) {
+      // The key was refused, not necessarily the connection (a narrow or a pod-side "Revoke key" ends the key only).
+      if (!opts.renew) return { ok: false, error: { ...errorFor(401, data, null, now()), refreshable: true } };
+      if (!retried) {
+        const renewed = await renewOnce(sent);
+        if (!renewed.ok) return renewed;
+        return request(method, path, body, query, true);
+      }
+    }
     return { ok: false, error: errorFor(res.status, data, res.headers.get("retry-after"), now()) };
   }
 
@@ -162,18 +419,207 @@ export function createPodClient(connection: PodConnection, opts: PodClientOption
         ok: true,
         status: "proposed",
         proposalId,
-        reviewUrl: reviewUrlFor(connection.podUrl, obj.reviewUrl, proposalId),
+        reviewUrl: reviewUrlFor(current.podUrl, obj.reviewUrl, proposalId),
         data: result.data as T,
       };
     }
     return { ok: true, status: "applied", data: result.data as T };
   }
 
+  async function listPendingProposals(opts: ListPendingProposalsOptions = {}): Promise<PodResult<PendingProposals>> {
+    if (!can(current, "proposal.read", opts.workspaceId)) {
+      return refused("forbidden", "not_granted", "The connection was not granted proposal.read in that space");
+    }
+    let only: Set<string> | null = null;
+    if (opts.proposalIds !== undefined) {
+      if (opts.proposalIds.length > PROPOSAL_IDS_MAX || opts.proposalIds.some((id) => !ID_RE.test(id))) {
+        return refused("invalid", "invalid_input", `proposalIds must be at most ${PROPOSAL_IDS_MAX} proposal ids`);
+      }
+      // `?proposalIds=` matches nothing on the pod; our query builder would drop it and ask for ALL.
+      if (opts.proposalIds.length === 0) return { ok: true, data: { total: 0, proposals: [], hasMore: false } };
+      only = new Set(opts.proposalIds);
+    }
+    const limit = Math.min(Math.max(Math.floor(opts.limit ?? 20), 1), 200);
+    const offset = Math.max(Math.floor(opts.offset ?? 0), 0);
+    const result = await request("GET", "/proposals", undefined, {
+      status: "pending",
+      view: "basic",
+      limit,
+      offset,
+      workspaceId: opts.workspaceId,
+      ...(only ? { proposalIds: [...only].join(",") } : {}),
+    });
+    if (!result.ok) return result;
+    const obj = result.data && typeof result.data === "object" ? (result.data as Record<string, unknown>) : {};
+    if (!Array.isArray(obj.proposals) || typeof obj.total !== "number") {
+      return { ok: false, error: { code: "server", status: 200, detail: "The pod's /proposals answer has no proposals or total" } };
+    }
+    const str = (v: unknown): string | null => (typeof v === "string" && v ? v : null);
+    const proposals: PendingProposal[] = [];
+    for (const row of obj.proposals as unknown[]) {
+      if (!row || typeof row !== "object") continue;
+      const r = row as Record<string, unknown>;
+      const id = str(r.id);
+      // A pod older than the filter ignores it: never hand back a proposal that was not asked for.
+      if (!id || (only && !only.has(id))) continue;
+      proposals.push({
+        id,
+        proposalType: str(r.proposalType) ?? "",
+        targetType: str(r.targetType) ?? "",
+        targetId: str(r.targetId),
+        workspaceId: str(r.workspaceId),
+        createdAt: str(r.createdAt) ?? "",
+        agentUserId: str(r.agentUserId),
+        sessionId: str(r.sessionId),
+        ...(str(r.summary) ? { summary: str(r.summary)! } : {}),
+        reviewUrl: reviewUrlFor(current.podUrl, null, id),
+      });
+    }
+    return {
+      ok: true,
+      data: { total: obj.total, proposals, hasMore: obj.hasMore === true || offset + proposals.length < obj.total },
+    };
+  }
+
+  /** A read whose 2xx body must pass `shape`; anything else is the pod answering what the SDK cannot use. */
+  async function read<T>(path: string, query: Record<string, QueryValue> | undefined, shape: (data: unknown) => T | null): Promise<PodResult<T>> {
+    const result = await request("GET", path, undefined, query);
+    if (!result.ok) return result;
+    const data = shape(result.data);
+    if (data === null) return { ok: false, error: { code: "server", status: 200, detail: `The pod's ${path.split("/")[1]} answer is not the expected shape` } };
+    return { ok: true, data };
+  }
+
+  const badId = (what: string) => refused("invalid", "invalid_input", `Not a ${what} id`);
+  const clamp = (n: number | undefined, min: number, max: number) => (n === undefined ? undefined : Math.min(Math.max(Math.floor(n), min), max));
+
+  function listEntities(opts: ListEntitiesOptions = {}): Promise<PodResult<PodEntity[]>> {
+    return read("/entities", {
+      workspaceId: opts.workspaceId,
+      profileSlug: opts.profileSlug,
+      limit: clamp(opts.limit, 1, 1000),
+      offset: clamp(opts.offset, 0, Number.MAX_SAFE_INTEGER),
+      sort: opts.sort,
+      includePodWide: opts.includePodWide,
+    }, (data) => (Array.isArray(data) ? (data.filter(hasId) as PodEntity[]) : null));
+  }
+
+  async function getEntity(id: string): Promise<PodResult<PodEntity>> {
+    if (!ID_RE.test(id)) return badId("entity");
+    return read(`/entities/${id}`, undefined, (data) => (hasId(data) ? (data as PodEntity) : null));
+  }
+
+  async function getEntityConnections(id: string, opts: GetEntityConnectionsOptions = {}): Promise<PodResult<PodEntityConnections>> {
+    if (!ID_RE.test(id)) return badId("entity");
+    return read(`/entities/${id}/connections`, { workspaceId: opts.workspaceId, limit: clamp(opts.limit, 1, 200) }, (data) => {
+      const obj = asObject(data);
+      if (!obj || !Array.isArray(obj.connections)) return null;
+      const connections = obj.connections.filter(
+        (c): c is PodEntityConnection => !!c && typeof c === "object" && typeof (c as Record<string, unknown>).entityId === "string",
+      );
+      const counts = asObject(obj.counts) ?? {};
+      const count = (key: string, source: string) =>
+        typeof counts[key] === "number" ? (counts[key] as number) : connections.filter((c) => c.source === source).length;
+      return {
+        connections,
+        counts: {
+          total: typeof counts.total === "number" ? counts.total : connections.length,
+          graph: count("graph", "graph"),
+          structural: count("structural", "property"),
+          threads: count("threads", "thread"),
+          contextChannels: count("contextChannels", "context_channel"),
+          focusSessions: count("focusSessions", "focus_session"),
+        },
+      };
+    });
+  }
+
+  async function getDocument(id: string, opts: GetDocumentOptions = {}): Promise<PodResult<PodDocument>> {
+    if (!ID_RE.test(id)) return badId("document");
+    return read(`/documents/${id}`, { format: opts.format }, (data) => {
+      const doc = asObject(asObject(data)?.document);
+      if (!doc || typeof doc.id !== "string" || typeof doc.content !== "string") return null;
+      return { ...doc, sections: Array.isArray(doc.sections) ? doc.sections : [] } as PodDocument;
+    });
+  }
+
+  async function listFocusSessions(opts: ListFocusSessionsOptions): Promise<PodResult<PodFocusSession[]>> {
+    if (!opts?.workspaceId && !opts?.projectId) return refused("invalid", "invalid_input", "workspaceId or projectId is required");
+    return read("/focus-sessions", {
+      workspaceId: opts.workspaceId,
+      projectId: opts.projectId,
+      status: opts.status,
+      limit: clamp(opts.limit, 1, 50),
+      lens: opts.lens,
+      kind: opts.kind,
+      subjectEntityId: opts.subjectEntityId,
+    }, (data) => {
+      if (!Array.isArray(data)) return null;
+      return data.filter(hasId).map((row) => ({
+        ...row,
+        expectedOutputs: Array.isArray(row.expectedOutputs)
+          ? row.expectedOutputs.filter((s): s is PodSessionSlot => !!s && typeof s === "object" && typeof (s as Record<string, unknown>).label === "string")
+          : [],
+      })) as PodFocusSession[];
+    });
+  }
+
+  async function getFileUrl(entityId: string): Promise<PodResult<PodFileUrl>> {
+    if (!ID_RE.test(entityId)) return badId("file");
+    return read(`/files/${entityId}/url`, undefined, (data) => {
+      const obj = asObject(data);
+      if (!obj || typeof obj.url !== "string" || typeof obj.expiresAt !== "string") return null;
+      return { url: obj.url, expiresAt: obj.expiresAt, mimeType: typeof obj.mimeType === "string" ? obj.mimeType : null };
+    });
+  }
+
+  async function approveProposal(id: string, opts: ApproveProposalOptions = {}): Promise<PodResult<PodApproval>> {
+    // Checked first, before anything else: an agent credential never reaches the approve door.
+    if (connectionActsAs(current) !== "person") {
+      return refused("forbidden", "agent_cannot_approve", "An agent connection can never approve: approval is the person's");
+    }
+    if (!can(current, "proposal.approve", opts.workspaceId)) {
+      return refused("forbidden", "not_granted", "The connection was not granted proposal.approve in that space");
+    }
+    if (!ID_RE.test(id)) return badId("proposal");
+    const result = await request("POST", `/proposals/${id}/approve`, {});
+    if (!result.ok) return result;
+    const obj = asObject(result.data);
+    if (!obj || typeof obj.proposalId !== "string") {
+      return { ok: false, error: { code: "server", status: 200, detail: "The pod's approve answer names no proposalId" } };
+    }
+    return {
+      ok: true,
+      data: {
+        proposalId: obj.proposalId,
+        ...(typeof obj.primaryId === "string" ? { primaryId: obj.primaryId } : {}),
+        ...(typeof obj.linked === "number" ? { linked: obj.linked } : {}),
+        proposal: asObject(obj.proposal),
+      },
+    };
+  }
+
   return {
     podUrl: connection.podUrl,
-    user: connection.user,
-    grant: connection.grant,
-    can: (permission, workspaceId) => can(connection, permission, workspaceId),
+    get user() {
+      return current.user;
+    },
+    get grant() {
+      return current.grant;
+    },
+    get actsAs() {
+      return connectionActsAs(current);
+    },
+    can: (permission, workspaceId) => can(current, permission, workspaceId),
+    spaces: () => spaces(current),
+    listPendingProposals,
+    listEntities,
+    getEntity,
+    getEntityConnections,
+    getDocument,
+    listFocusSessions,
+    getFileUrl,
+    approveProposal,
     get<T>(path: string, query?: Record<string, QueryValue>) {
       return request("GET", path, undefined, query) as Promise<PodResult<T>>;
     },