@synap-core/cli 1.10.0 → 1.12.2

package/dist/lib/pod.d.ts

@@ -9,17 +9,28 @@ export interface LocalPodConfig {
     hubApiKey: string;
     label?: string;
     savedAt: string;
+    /**
+     * "computer" = `hubApiKey` is THIS machine's own key on the pod, from the
+     * device flow (`device-connect.ts`); `agentUserId` is then the computer's id.
+     * Absent = a pasted key or an older operator key.
+     */
+    credential?: "computer";
+    /** When `hubApiKey` stops working (ISO), if the pod said. `synap login`/`init` renew it 7 days before. */
+    keyExpiresAt?: string;
+    /** The computer's name on the pod ("devbox"). */
+    computerName?: string;
 }
 /** SSOT for every connect/surface agent identity. The type is derived from this
  *  array so the two can't drift. */
-export declare const SURFACE_NAMES: readonly ["raycast", "claude-code", "claude-desktop", "cursor", "codex", "opencode", "aider", "windsurf", "goose", "zed", "vscode", "discord"];
+export declare const SURFACE_NAMES: readonly ["raycast", "claude-code", "claude-desktop", "cursor", "codex", "chatgpt", "chatgpt-oauth", "opencode", "aider", "windsurf", "goose", "zed", "vscode", "grok", "discord", "proton", "generic"];
 export type SurfaceName = (typeof SURFACE_NAMES)[number];
 /**
- * agentTypes already owned by OTHER doors — `POST /setup/agent` treats agentType
- * as a POD-WIDE SINGLETON, so `agents create` deriving a slug that collides with
- * one of these would silently hijack that door's agent + key. Superset of the
- * surfaces above plus the non-surface provisioning types (generic/openwebui MCP
- * mappings; openclaw/cli/memory). Single source of truth for the collision guard.
+ * agentTypes already owned by OTHER doors — provisioning is singleton per
+ * (createdByUserId, agentType), so `agents create` deriving a slug that collides
+ * with one of these would reuse that surface's agent for this user. Superset of
+ * the surfaces above plus the non-surface provisioning types (generic/openwebui
+ * MCP mappings; cli/memory, and the retired "openclaw", which pods may still
+ * hold an agent of). Single source of truth for the collision guard.
  */
 export declare const RESERVED_AGENT_TYPES: ReadonlySet<string>;
 export interface SurfaceAgentKey {
@@ -44,6 +55,18 @@ export interface ActiveProjectBinding {
     projectId: string;
     podName: string;
 }
+/**
+ * The active workspace pinned together with the pod profile it belongs to.
+ *
+ * A workspace exists on exactly ONE pod, but `activeWorkspaceId` is a single
+ * pod-agnostic global. Recording the pod it was set against lets resolution
+ * refuse to send a workspace to a pod it doesn't belong to (the cross-pod 403).
+ * Peer of {@link ActiveProjectBinding}.
+ */
+export interface ActiveWorkspaceBinding {
+    workspaceId: string;
+    podName: string;
+}
 export interface MultiPodConfig {
     activePod: string;
     /** Per-surface pod overrides. When set, takes priority over activePod for that surface. */
@@ -51,12 +74,27 @@ export interface MultiPodConfig {
     pods: Record<string, LocalPodConfig>;
     /** Active workspace override — set by `synap use <workspaceId>`. Takes priority over the pod's default workspaceId. */
     activeWorkspaceId?: string;
+    /** Pod-aware binding of the active workspace — records which pod `activeWorkspaceId` was set against, so cross-pod resolution can ignore it for other pods. */
+    activeWorkspace?: ActiveWorkspaceBinding;
     /** Active project override — set by `synap project use <projectId>`. Peer of activeWorkspaceId; independent (composable). */
     activeProjectId?: string;
     /** Pod-aware binding of the active project — set by cross-pod `synap project use <ref>` so later drift (active pod changed under the pin) can warn. */
     activeProject?: ActiveProjectBinding;
     /** Per-surface dedicated agent keys (provisioned with named agentType). Separate from pod profile keys. */
     agentKeys?: Partial<Record<SurfaceName, SurfaceAgentKey>>;
+    /**
+     * Multi-pod surface keys: surface → normalized podUrl → key.
+     * `agentKeys[surface]` remains the last-written default for backward compat;
+     * this map is the source of truth when a consumer knows which pod it is talking to.
+     */
+    agentKeysByPod?: Partial<Record<SurfaceName, Record<string, SurfaceAgentKey>>>;
+    /**
+     * Keys minted but NOT yet approved: surface → normalized podUrl → key. Never
+     * read for authentication. Kept so the next `connect` / `doctor --fix`
+     * resumes the SAME request instead of minting another (one approval, one key),
+     * and moved into `agentKeysByPod` only once the pod says it is live.
+     */
+    pendingAgentKeys?: Record<string, Record<string, PendingAgentKey>>;
     /** Workspace routing set by `synap connect` wizard — drives capture/recall defaults. */
     agentWorkspaceRouting?: AgentWorkspaceRouting;
 }
@@ -92,20 +130,61 @@ export declare function setPodOverrideByName(name: string): LocalPodConfig;
  * Consume a position-independent `--pod <name>` (or `--pod=<name>`) from argv and
  * register it as the per-invocation override. Mutates `argv` in place so commander
  * never sees the flag (it isn't registered per-command). No-op when the argv
- * targets a command that owns `--pod` itself (agents, bridge-setup). Throws with a
+ * targets a command that owns `--pod` itself (bridge-setup). Throws with a
  * helpful message when the named profile is unknown.
  */
 export declare function bootstrapPodOverride(argv: string[]): void;
 export declare function addPodProfile(name: string, podConfig: LocalPodConfig): void;
 export declare function setActivePod(name: string): LocalPodConfig;
-/** Get the active workspace ID: explicit override first, then the pod default. */
+/** The active pod's profile NAME (not its config), or undefined if none is set. */
+export declare function getActivePodName(): string | undefined;
+/** Find a saved pod profile NAME by its URL (trailing slashes ignored). */
+export declare function findPodNameByUrl(url: string): string | undefined;
+/**
+ * Resolve the workspace to use for a specific pod — PURE (no disk, no network),
+ * so the cross-pod rule is unit-testable.
+ *
+ * A workspace lives on exactly one pod, but `activeWorkspaceId` is a single
+ * pod-agnostic global. Sending it to the wrong pod is the "Access denied to
+ * workspace" 403. The rule: only honor the global override for the pod it
+ * actually belongs to; otherwise fall back to THAT pod's own default workspace.
+ *
+ *   1. No override set → the target pod's own default.
+ *   2. Override has a pod binding → honor it only for its bound pod; for any
+ *      other pod, use that pod's default.
+ *   3. Legacy override (no binding) that equals ANOTHER saved pod's default →
+ *      it clearly belongs to that pod → use the target's default.
+ *   4. Otherwise no evidence it's foreign → assume it's the target pod's (the
+ *      legacy `synap use <custom-ws-on-this-pod>` case) → honor it.
+ */
+export declare function resolveWorkspaceForPod(config: MultiPodConfig, podName: string | undefined): string | undefined;
+/**
+ * Get the active workspace ID for a pod (by profile NAME). Applies the cross-pod
+ * rule in {@link resolveWorkspaceForPod}. Omit `podName` for the active pod.
+ */
+export declare function getActiveWorkspaceIdForPod(podName?: string): string | undefined;
+/**
+ * Get the active workspace ID for the ACTIVE pod: explicit override first (only
+ * if it belongs to this pod), then the pod default. Cross-pod-safe: a global
+ * override left over from another pod is ignored rather than sent (avoids the
+ * "Access denied to workspace" 403).
+ */
 export declare function getActiveWorkspaceId(): string | undefined;
-/** Persist a workspace as the active context for all subsequent commands. */
-export declare function setActiveWorkspaceId(workspaceId: string): void;
+/**
+ * Persist a workspace as the active context for all subsequent commands.
+ * Records the pod the workspace belongs to (defaults to the active pod) so
+ * later cross-pod resolution can tell whether the override applies.
+ */
+export declare function setActiveWorkspaceId(workspaceId: string, podName?: string): void;
 /** Get the active project ID: durable override set by `synap project use`. */
 export declare function getActiveProjectId(): string | undefined;
-/** Persist a project as the active context for all subsequent commands. */
-export declare function setActiveProjectId(projectId: string): void;
+/**
+ * Persist a project as the active context for all subsequent commands.
+ * Records the pod it was set against (defaults to the active pod) so
+ * {@link resolveHubConfig} can refuse to send it to a foreign pod.
+ * Peer of {@link setActiveWorkspaceId}.
+ */
+export declare function setActiveProjectId(projectId: string, podName?: string): void;
 /**
  * Pin project AND the pod it lives on together — the cross-pod `project use`
  * door. Stores the binding so later drift (active pod switched away from the
@@ -116,17 +195,40 @@ export declare function setActiveProjectBinding(binding: ActiveProjectBinding):
 export declare function getActiveProjectBinding(): ActiveProjectBinding | undefined;
 /** Remove the active project override — subsequent commands see all projects. */
 export declare function clearActiveProjectId(): void;
-/** Store a dedicated agent key for a specific surface (e.g. "raycast", "claude-code"). */
+/**
+ * Store a dedicated agent key for a specific surface (e.g. "raycast", "claude-code").
+ * Always writes `agentKeys[surface]` (last-write, backward compat). When `key.podUrl`
+ * is set, also stores under `agentKeysByPod[surface][normalizedPodUrl]` so multi-pod
+ * surfaces can look up the key for the pod they are actually talking to.
+ */
 export declare function setSurfaceAgentKey(surface: SurfaceName, key: SurfaceAgentKey): void;
-/** Read back the stored agent key for a surface. Returns null if not provisioned. */
-export declare function getSurfaceAgentKey(surface: SurfaceName): SurfaceAgentKey | null;
+/**
+ * Read back the stored agent key for a surface.
+ * When `podUrl` is provided, prefer `agentKeysByPod` for that pod; if only a legacy
+ * `agentKeys[surface]` entry exists, return it only when its podUrl matches (or is
+ * unset). Never return a key known to belong to a different pod.
+ */
+export declare function getSurfaceAgentKey(surface: SurfaceName, podUrl?: string): SurfaceAgentKey | null;
+/** A minted agent key waiting for its owner's approval (see `pendingAgentKeys`). */
+export interface PendingAgentKey {
+    hubApiKey: string;
+    agentUserId: string;
+    podUrl: string;
+    /** The key's id on the pod (the approval page names it). */
+    keyId: string;
+    approvalUrl: string;
+    /** This computer's instance label the key was minted with. */
+    instanceId?: string;
+    createdAt: string;
+}
+export declare function getPendingAgentKey(surface: string, podUrl: string): PendingAgentKey | null;
+export declare function setPendingAgentKey(surface: string, key: PendingAgentKey): void;
+export declare function clearPendingAgentKey(surface: string, podUrl: string): void;
 export declare function setAgentWorkspaceRouting(routing: AgentWorkspaceRouting): void;
 export declare function getAgentWorkspaceRouting(): AgentWorkspaceRouting | undefined;
 /** Remove the active workspace override — subsequent commands see all workspaces. */
 export declare function clearActiveWorkspaceId(): void;
 export declare function removePodProfile(name: string): void;
-/** @deprecated Use addPodProfile("default", config) */
-export declare function saveLocalPodConfig(podConfig: LocalPodConfig): void;
 export interface PodStatus {
     url: string;
     healthy: boolean;
@@ -142,101 +244,3 @@ export declare function checkPodHealth(podUrl: string): Promise<PodStatus>;
  * Install Docker and start a self-hosted Synap pod.
  */
 export declare function startSelfHostedPod(): void;
-/**
- * Install the synap skill into OpenClaw.
- */
-/**
- * Open a Pod session for the CP-authenticated user.
- * Calls the issuer for a short-lived generic assertion, then exchanges that
- * assertion directly with the Pod. The issuer never receives a Pod session.
- *
- * Returns the Kratos session token the Pod mints after its own membership check.
- * That token authenticates subsequent pod tRPC calls (e.g.
- * `apiKeys.connectIntegration`) as the pod user, via the X-Session-Token header.
- * `sessionToken` is null only if the pod handshake returned no token (e.g. 409).
- */
-export declare function provisionUserOnPod(podUrl: string, cpToken: string): Promise<{
-    sessionToken: string | null;
-}>;
-/**
- * Issue a scoped Hub Protocol API key on the pod for an authenticated user.
- *
- * Canonical path: the pod's `apiKeys.connectIntegration` tRPC procedure — the
- * same one the pod-admin `/connect` page and the browser's LocalCliRow use.
- * Auth is the Kratos session token minted by {@link provisionUserOnPod},
- * forwarded as the `X-Session-Token` header. (Replaces the removed CP relay
- * `POST /pods/setup-agent`, which now returns 410.)
- *
- * Backend tRPC uses the superjson transformer, so the input rides in a
- * `{ json: ... }` envelope and the output is unwrapped from `result.data.json`.
- */
-export declare function setupAgentViaPod(podUrl: string, sessionToken: string, integration?: "cli" | "openclaw" | "raycast" | "custom"): Promise<{
-    hubApiKey: string;
-    agentUserId: string;
-    workspaceId: string;
-}>;
-/**
- * Enable OpenClaw as a free addon on a SELF-HOSTED pod.
- * Uses the PROVISIONING_TOKEN directly against the pod.
- *
- * Routes through the shared `provisionAgentKey()` wrapper (dynamic import to
- * avoid a circular pod.ts <-> targets.ts static import). `workspaceId` is no
- * longer part of the response — agents are pod-wide singletons now; scope is
- * granted separately via `enrollAgentIfNeeded()`, not returned from setup.
- */
-export declare function enableOpenClawAddon(podUrl: string, provisioningToken: string): Promise<{
-    hubApiKey: string;
-    agentUserId: string;
-    workspaceId: string;
-}>;
-/**
- * Enable OpenClaw as an addon on a MANAGED pod via the Control Plane.
- * Calls POST /openclaw/provision on the CP (requires CP session token).
- * Returns the podId so the caller can poll status if needed.
- */
-export declare function enableOpenClawAddonManaged(cpToken: string, podUrl: string): Promise<{
-    podId: string;
-}>;
-/**
- * Check server resources (RAM, disk).
- */
-export declare function checkServerResources(): {
-    ramTotal: number;
-    ramFree: number;
-    diskFree: string;
-};
-/**
- * Start OpenClaw as a Docker addon on the local server.
- * Writes env vars to the pod's .env file and runs docker compose --profile openclaw.
- * Only works when the CLI is running ON the pod server.
- */
-/**
- * Find the Synap deploy directory — where the .env and docker-compose files live.
- *
- * Strategy (most reliable first):
- *   1. Docker label — inspect any running synap container for
- *      com.docker.compose.project.working_dir (always accurate, zero guessing)
- *   2. Walk up from cwd — works when running from inside the repo
- *   3. Common install paths as a last resort
- */
-export declare function findSynapDeployDir(): string | null;
-/**
- * Write OpenClaw env vars into the deploy dir .env and start the container.
- * Does NOT wait for health — OpenClaw can take several minutes to initialize
- * (first run pulls ~1GB image + runs setup). Caller should tell user to run
- * `synap finish` once it's up.
- *
- * Returns the deploy dir used.
- */
-export declare function startOpenClawOnServer(hubApiKey: string, agentUserId: string, workspaceId: string, podUrl: string, projectId?: string): string;
-/**
- * Install the synap skill into OpenClaw.
- * Automatically chooses the right execution path:
- *   - Local install: runs `openclaw skills install synap` directly
- *   - Docker container: runs `docker exec <container> openclaw skills install synap`
- */
-export declare function installSynapSkill(containerName?: string): void;
-/**
- * Check whether the synap skill is installed inside a Docker container.
- */
-export declare function isSynapSkillInstalledInDocker(containerName: string): boolean;