@synap-core/cli 1.11.0 → 1.13.0

package/dist/lib/pod-reach.js

@@ -0,0 +1,117 @@
+/**
+ * Why a pod probe failed, told apart: the network between this machine and the
+ * pod (egress proxy, DNS, firewall, TLS) versus the pod itself answering badly.
+ *
+ * `checkPodHealth` used to fold every failure into `healthy: false`, so `synap
+ * init` behind an egress proxy that answers 403 to CONNECT printed a pod-side
+ * checklist ("is the container running?") for a pod that was never contacted.
+ * This is the one place that taxonomy lives for the probe.
+ */
+const PROXY_ENV = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "ALL_PROXY", "all_proxy"];
+/** The env proxy that applies to `podUrl`, credentials removed. Honors NO_PROXY. */
+export function proxyInUse(podUrl, env = process.env) {
+    let target;
+    try {
+        target = new URL(podUrl);
+    }
+    catch {
+        return undefined;
+    }
+    const noProxy = (env.NO_PROXY ?? env.no_proxy ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const bypass = noProxy.some((p) => p === "*" ||
+        target.hostname === p.replace(/^\./, "") ||
+        target.hostname.endsWith(p.startsWith(".") ? p : `.${p}`));
+    if (bypass)
+        return undefined;
+    const order = target.protocol === "https:" ? PROXY_ENV : [...PROXY_ENV.slice(2, 4), ...PROXY_ENV.slice(0, 2), ...PROXY_ENV.slice(4)];
+    for (const name of order) {
+        const raw = env[name];
+        if (!raw)
+            continue;
+        try {
+            const u = new URL(raw);
+            u.username = "";
+            u.password = "";
+            return { env: name, url: u.origin };
+        }
+        catch {
+            return { env: name, url: "(unparseable)" };
+        }
+    }
+    return undefined;
+}
+function codeOf(err) {
+    const cause = err?.cause;
+    for (const e of [cause, err]) {
+        const c = e?.code;
+        if (typeof c === "string")
+            return c;
+    }
+    return "";
+}
+/** Classify a fetch that threw (no HTTP answer from the pod). */
+export function classifyFetchError(err, podUrl, env = process.env) {
+    const proxy = proxyInUse(podUrl, env);
+    const cause = err?.cause;
+    const message = [cause?.message, err instanceof Error ? err.message : String(err)].filter(Boolean)[0] ?? "unknown error";
+    const code = codeOf(err);
+    // undici's ProxyAgent: "Proxy response (403) !== 200 when HTTP Tunneling";
+    // Node's env-proxy support surfaces "Tunnel ... 403" / ERR_PROXY_TUNNEL.
+    const tunnel = /proxy response \((\d{3})\)|tunnel.*?(\d{3})|ERR_PROXY_TUNNEL/i.exec(`${code} ${message}`);
+    if (tunnel || code === "UND_ERR_PRX_TLS" || code === "ERR_PROXY_TUNNEL") {
+        const status = tunnel?.[1] ?? tunnel?.[2];
+        return {
+            kind: "proxy",
+            detail: status ? `the egress proxy refused the tunnel (HTTP ${status} to CONNECT)` : `the egress proxy refused the tunnel (${message})`,
+            proxy,
+        };
+    }
+    const name = err instanceof Error ? err.name : "";
+    const label = code || (name === "TimeoutError" || name === "AbortError" ? "TIMEOUT" : message);
+    return {
+        kind: "network",
+        detail: `${label}${label === message ? "" : `: ${message}`}`,
+        proxy,
+    };
+}
+/** Classify a /health that answered with a non-2xx status. */
+export function classifyHttpStatus(status, podUrl, env = process.env) {
+    return { kind: "pod", detail: `/health answered HTTP ${status}`, proxy: proxyInUse(podUrl, env) };
+}
+/** The lines `synap init` / `synap doctor` print under "not reachable", by cause. */
+export function reachChecklist(f) {
+    const proxyLine = f?.proxy ? [`Proxy in use: ${f.proxy.url} (from ${f.proxy.env})`] : [];
+    if (f?.kind === "proxy") {
+        return [
+            ...proxyLine,
+            "Your network's egress proxy blocked the connection. The pod was not contacted.",
+            "- Ask the proxy's owner to allow CONNECT to the pod host (port 443).",
+            "- Or bypass the proxy for it: export NO_PROXY=<pod-host>",
+        ];
+    }
+    if (f?.kind === "network") {
+        return [
+            ...proxyLine,
+            "This machine could not reach the pod host. The pod itself may be fine.",
+            "- Is the pod URL correct? (scheme + host + port)",
+            "- Are you online, on the right network/VPN, behind a firewall or proxy?",
+            "- Can you open the URL in a browser from this machine?",
+        ];
+    }
+    return [
+        ...proxyLine,
+        "- Is the pod URL correct? (scheme + host + port)",
+        "- Is the pod container running? On the server: ./synap health",
+        "- Is there a firewall or reverse proxy in the way?",
+        "- For localhost setups, did you start the stack? ./synap start",
+    ];
+}
+/** The one-line headline: names the underlying error, not just "not reachable". */
+export function unreachableMessage(podUrl, failure) {
+    if (!failure)
+        return `Pod at ${podUrl} is not reachable.`;
+    return failure.kind === "pod"
+        ? `Pod at ${podUrl} is not healthy: ${failure.detail}.`
+        : `Could not reach ${podUrl}: ${failure.detail}.`;
+}
+//# sourceMappingURL=pod-reach.js.map

package/dist/lib/pod-reach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pod-reach.js","sourceRoot":"","sources":["../../src/lib/pod-reach.ts"],"names":[],"mappings":"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"}

package/dist/lib/pod-reach.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/pod-reach.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+import { checkPodHealth } from "./pod.js";
+import { classifyFetchError, proxyInUse, reachChecklist, unreachableMessage } from "./pod-reach.js";
+const POD = "https://pod.example.com";
+/** What undici throws when the proxy answers CONNECT with 403. */
+function proxy403() {
+    const err = new TypeError("fetch failed");
+    err.cause = Object.assign(new Error("Proxy response (403) !== 200 when HTTP Tunneling"), {
+        code: "UND_ERR_PRX_TUNNEL",
+    });
+    return err;
+}
+function refused() {
+    const err = new TypeError("fetch failed");
+    err.cause = Object.assign(new Error("connect ECONNREFUSED 127.0.0.1:443"), { code: "ECONNREFUSED" });
+    return err;
+}
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+});
+describe("classifyFetchError", () => {
+    it("a proxy 403 on CONNECT is a proxy failure naming the status and the env proxy used", () => {
+        const f = classifyFetchError(proxy403(), POD, { HTTPS_PROXY: "http://user:secret@egress.corp:3128" });
+        expect(f.kind).toBe("proxy");
+        expect(f.detail).toContain("403");
+        expect(f.proxy).toEqual({ env: "HTTPS_PROXY", url: "http://egress.corp:3128" });
+        expect(JSON.stringify(f)).not.toContain("secret");
+    });
+    it("ECONNREFUSED is a network failure that names the code", () => {
+        const f = classifyFetchError(refused(), POD, {});
+        expect(f.kind).toBe("network");
+        expect(f.detail).toContain("ECONNREFUSED");
+        expect(f.proxy).toBeUndefined();
+    });
+    it("NO_PROXY bypass means no proxy is reported", () => {
+        expect(proxyInUse(POD, { HTTPS_PROXY: "http://egress:3128", NO_PROXY: ".example.com" })).toBeUndefined();
+    });
+});
+describe("checkPodHealth carries the cause", () => {
+    it("proxy 403: not healthy, failure.kind proxy", async () => {
+        vi.stubGlobal("fetch", vi.fn().mockRejectedValue(proxy403()));
+        const h = await checkPodHealth(POD);
+        expect(h.healthy).toBe(false);
+        expect(h.failure?.kind).toBe("proxy");
+    });
+    it("pod answering 503: failure.kind pod", async () => {
+        vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response("down", { status: 503 })));
+        const h = await checkPodHealth(POD);
+        expect(h.failure).toMatchObject({ kind: "pod", detail: "/health answered HTTP 503" });
+    });
+});
+describe("init message and checklist branch on the cause", () => {
+    it("proxy failure: headline has the status; checklist is not the pod-container list", () => {
+        const f = classifyFetchError(proxy403(), POD, { HTTPS_PROXY: "http://egress.corp:3128" });
+        expect(unreachableMessage(POD, f)).toContain("403");
+        const list = reachChecklist(f).join("\n");
+        expect(list).toContain("HTTPS_PROXY");
+        expect(list).toContain("NO_PROXY");
+        expect(list).not.toContain("container running");
+    });
+    it("pod failure keeps the pod-side checklist", () => {
+        const list = reachChecklist({ kind: "pod", detail: "/health answered HTTP 503" }).join("\n");
+        expect(list).toContain("container running");
+    });
+});
+//# sourceMappingURL=pod-reach.test.js.map

package/dist/lib/pod-reach.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pod-reach.test.js","sourceRoot":"","sources":["../../src/lib/pod-reach.test.ts"],"names":[],"mappings":"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"}

package/dist/lib/pod-wide.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pod-wide vocabulary — ONE canonical spelling for "not scoped to a workspace".
+ *
+ * The CLI had four different spellings of the pod-wide idea:
+ *
+ *   1. `--global`            boolean flag on `capture` (index.ts:648 → knowledge.ts:628)
+ *   2. omitting `--workspace` documented as "(omit for pod-wide)" on ask/capture/
+ *                            knowledge/cell (index.ts:318, 623, 896, 1858)
+ *   3. omitting `--pin-workspace` documented as "(default: pod-wide lens)" (index.ts:116)
+ *   4. `__pod_wide__`        internal sentinel in the launch picker (launch.ts:576)
+ *
+ * Only #1 is a knob the user TYPES to opt in; #2 and #3 are absences (a
+ * different mechanism — you cannot alias "not passing a flag"), and #4 never
+ * leaves the process. So the unification here is narrow and honest: canonicalise
+ * the typed opt-in, and leave the absences alone rather than pretend they are
+ * spellings of the same switch.
+ *
+ * CANONICAL: `--pod-wide`. Chosen over `--global` because "global" is already
+ * overloaded in this CLI to mean "durable rather than per-session" — `synap use`
+ * and `synap project use` both report `scope: "global"` for exactly that other
+ * meaning (data.ts:229,281; lens.ts:227,355,396). "Pod-wide" is the term the
+ * data model and every help string already use for the scope axis, so it is the
+ * one that cannot be misread.
+ *
+ * `--global` remains an accepted ALIAS — it is what every existing script and
+ * the `synap capture --global` line in CLAUDE.md types, and breaking that to win
+ * a naming argument would be a worse defect than the inconsistency.
+ */
+/** Every accepted spelling of the pod-wide opt-in. First entry is canonical. */
+export declare const POD_WIDE_FLAGS: readonly ["pod-wide", "global"];
+/** True when a user-supplied scope value spells "pod-wide" rather than naming a workspace. */
+export declare function isPodWideToken(value: string | undefined | null): boolean;
+/**
+ * Resolve the pod-wide opt-in from parsed options, accepting every spelling.
+ * Commander camel-cases `--pod-wide` to `podWide`.
+ */
+export declare function resolvePodWide(opts: {
+    podWide?: boolean;
+    global?: boolean;
+}): boolean;

package/dist/lib/pod-wide.js

@@ -0,0 +1,46 @@
+/**
+ * Pod-wide vocabulary — ONE canonical spelling for "not scoped to a workspace".
+ *
+ * The CLI had four different spellings of the pod-wide idea:
+ *
+ *   1. `--global`            boolean flag on `capture` (index.ts:648 → knowledge.ts:628)
+ *   2. omitting `--workspace` documented as "(omit for pod-wide)" on ask/capture/
+ *                            knowledge/cell (index.ts:318, 623, 896, 1858)
+ *   3. omitting `--pin-workspace` documented as "(default: pod-wide lens)" (index.ts:116)
+ *   4. `__pod_wide__`        internal sentinel in the launch picker (launch.ts:576)
+ *
+ * Only #1 is a knob the user TYPES to opt in; #2 and #3 are absences (a
+ * different mechanism — you cannot alias "not passing a flag"), and #4 never
+ * leaves the process. So the unification here is narrow and honest: canonicalise
+ * the typed opt-in, and leave the absences alone rather than pretend they are
+ * spellings of the same switch.
+ *
+ * CANONICAL: `--pod-wide`. Chosen over `--global` because "global" is already
+ * overloaded in this CLI to mean "durable rather than per-session" — `synap use`
+ * and `synap project use` both report `scope: "global"` for exactly that other
+ * meaning (data.ts:229,281; lens.ts:227,355,396). "Pod-wide" is the term the
+ * data model and every help string already use for the scope axis, so it is the
+ * one that cannot be misread.
+ *
+ * `--global` remains an accepted ALIAS — it is what every existing script and
+ * the `synap capture --global` line in CLAUDE.md types, and breaking that to win
+ * a naming argument would be a worse defect than the inconsistency.
+ */
+/** Every accepted spelling of the pod-wide opt-in. First entry is canonical. */
+export const POD_WIDE_FLAGS = ["pod-wide", "global"];
+/** Accepted string tokens meaning "pod-wide" where a scope VALUE is parsed. */
+const POD_WIDE_TOKENS = new Set(["pod", "pod-wide", "podwide", "pod_wide", "global"]);
+/** True when a user-supplied scope value spells "pod-wide" rather than naming a workspace. */
+export function isPodWideToken(value) {
+    if (!value)
+        return false;
+    return POD_WIDE_TOKENS.has(value.trim().toLowerCase());
+}
+/**
+ * Resolve the pod-wide opt-in from parsed options, accepting every spelling.
+ * Commander camel-cases `--pod-wide` to `podWide`.
+ */
+export function resolvePodWide(opts) {
+    return Boolean(opts.podWide || opts.global);
+}
+//# sourceMappingURL=pod-wide.js.map

package/dist/lib/pod-wide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pod-wide.js","sourceRoot":"","sources":["../../src/lib/pod-wide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAU,CAAC;AAE9D,+EAA+E;AAC/E,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEtF,8FAA8F;AAC9F,MAAM,UAAU,cAAc,CAAC,KAAgC;IAC7D,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAA6C;IAC1E,OAAO,OAAO,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC"}

package/dist/lib/pod.d.ts

@@ -1,6 +1,7 @@
 /**
  * Synap pod connection and management utilities.
  */
+import { type ReachFailure } from "./pod-reach.js";
 export interface LocalPodConfig {
     podUrl: string;
     podId?: string;
@@ -9,17 +10,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 {
@@ -71,6 +83,19 @@ export interface MultiPodConfig {
     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;
 }
@@ -106,7 +131,7 @@ 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;
@@ -154,8 +179,13 @@ export declare function getActiveWorkspaceId(): string | undefined;
 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
@@ -166,23 +196,53 @@ 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;
     version?: string;
     entityCount?: number;
     workspaceId?: string;
+    /**
+     * The address redirects to ANOTHER host — the pod has most likely moved
+     * (pod-moved.ts). Never followed; `synap doctor` asks the Control Plane.
+     */
+    moved?: boolean;
+    /** Why the probe failed, when it did (network / proxy / pod). Absent when healthy or moved. */
+    failure?: ReachFailure;
 }
 /**
  * Check if a Synap pod is healthy.
@@ -192,101 +252,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;