crewly 1.11.5 → 1.12.0

package/dist/cli/backend/src/services/backup/backup.types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Types for the Workspace Backup feature.
+ *
+ * A backup is a single `.tar.gz` archive containing a top-level
+ * `manifest.json` plus the captured `CREWLY_HOME` globals, each project's
+ * `.crewly/` tree, and (optionally) `chat.db`. See
+ * specs/2026-06-07-workspace-backup.md.
+ *
+ * @module services/backup/backup.types
+ */
+/** Manifest schema version — bump on any breaking layout/field change. */
+export declare const BACKUP_SCHEMA_VERSION = 1;
+/** A single captured file recorded in the manifest for integrity + listing. */
+export interface BackupFileEntry {
+    /** Path inside the archive, relative to the archive root. */
+    path: string;
+    /** SHA-256 of the file content (hex). */
+    sha256: string;
+    /** Size in bytes. */
+    bytes: number;
+}
+/** Git provenance for a captured project so restore can re-clone the source tree. */
+export interface BackupProjectGit {
+    /** `origin` remote URL, or null when not a git repo / no origin. */
+    remote: string | null;
+    /** HEAD commit sha, or null when unavailable. */
+    commit: string | null;
+}
+/** One project's captured `.crewly/` data + provenance. */
+export interface BackupProjectEntry {
+    /** Stable project id (from projects.json). */
+    id: string;
+    /** Human-readable project name. */
+    name: string;
+    /** Absolute path on the SOURCE machine (used for restore path-rewriting). */
+    sourcePath: string;
+    /** Git provenance for re-clone on restore. */
+    git: BackupProjectGit;
+    /** Captured files under `projects/<id>/` in the archive. */
+    files: BackupFileEntry[];
+}
+/** chat.db capture record. */
+export interface BackupChatDb {
+    /** Whether chat.db was included (false when excluded or the native module is absent). */
+    included: boolean;
+    /** SHA-256 of the captured db, when included. */
+    sha256?: string;
+    /** Size in bytes, when included. */
+    bytes?: number;
+    /** Reason it was skipped, when not included. */
+    skippedReason?: string;
+}
+/** Encryption envelope descriptor. v1 archives are unencrypted on disk; Cloud adds SSE. */
+export interface BackupCrypto {
+    /** `none` for v1 local archives. `sse` once parked in the cloud. */
+    mode: 'none' | 'sse';
+}
+/** Top-level archive manifest. */
+export interface BackupManifest {
+    schemaVersion: number;
+    crewlyVersion: string;
+    /** ISO timestamp — the logical point-in-time of the snapshot. */
+    createdAt: string;
+    /** Source device id (observability only; NEVER restored). */
+    sourceDeviceId: string | null;
+    sourceDeviceName: string | null;
+    /** Source `CREWLY_HOME` absolute path — restore uses it for path rewriting. */
+    sourceHomePath: string;
+    /** Owner account (JWT `sub`/googleId). Null for local-only archives; stamped by Cloud on upload. */
+    ownerSub: string | null;
+    /** Captured CREWLY_HOME global files (relative to `home/` in the archive). */
+    global: BackupFileEntry[];
+    /** Captured per-project `.crewly/` data. */
+    projects: BackupProjectEntry[];
+    chatDb: BackupChatDb;
+    crypto: BackupCrypto;
+}
+/** Options for building an archive. */
+export interface CreateBackupOptions {
+    /** Output archive path. Defaults to `CREWLY_HOME/backups/workspace-<ts>.tar.gz`. */
+    outPath?: string;
+    /** Exclude chat.db (smaller archive, avoids SQLite capture). Default false. */
+    excludeChatDb?: boolean;
+    /** Override CREWLY_HOME (tests). Defaults to getCrewlyHomePath(). */
+    homePath?: string;
+    /** ISO timestamp for the snapshot point. Defaults to caller-supplied now (no Date in lib). */
+    createdAt: string;
+    /** Owner sub to stamp (usually null locally; Cloud stamps on upload). */
+    ownerSub?: string | null;
+    /** Source device id/name for the manifest (observability). */
+    sourceDeviceId?: string | null;
+    sourceDeviceName?: string | null;
+}
+/** Result of a successful archive build. */
+export interface CreateBackupResult {
+    archivePath: string;
+    manifest: BackupManifest;
+    /** Total uncompressed bytes captured (for quota/UX). */
+    totalBytes: number;
+}
+/** How to handle a target that already has overlapping data. */
+export type RestoreMode = 'abort' | 'overwrite';
+/** Options for restoring an archive onto this machine. */
+export interface RestoreOptions {
+    /** Archive (.tar.gz) to restore. */
+    archivePath: string;
+    /** Target CREWLY_HOME. Defaults to getCrewlyHomePath(). */
+    homePath?: string;
+    /** Conflict policy. Default 'abort'. */
+    mode?: RestoreMode;
+    /**
+     * Source→target absolute path remap for projects, e.g.
+     * `{ '/Users/alice/web': '/Users/bob/web' }`. When a source path isn't
+     * mapped, restore reuses it if it exists on the target, else records a
+     * warning and skips that project's `.crewly/` write.
+     */
+    pathMap?: Record<string, string>;
+    /** ISO timestamp used to name the pre-restore rollback snapshot. */
+    now: string;
+}
+/** One project's restore plan entry. */
+export interface RestoreProjectPlan {
+    id: string;
+    name: string;
+    sourcePath: string;
+    /** Resolved target path (pathMap → existing sourcePath → null when unresolved). */
+    targetPath: string | null;
+    git: {
+        remote: string | null;
+        commit: string | null;
+    };
+    /** Whether the resolved target path currently exists on this machine. */
+    targetExists: boolean;
+}
+/** Non-destructive restore plan (dry-run). */
+export interface RestorePlan {
+    /** False when mode='abort' and conflicts exist (apply would refuse). */
+    ok: boolean;
+    manifestCreatedAt: string;
+    sourceHomePath: string;
+    /** Stable ids present on BOTH the backup and this machine (would be overwritten). */
+    conflicts: {
+        teams: string[];
+        projects: string[];
+    };
+    globalFileCount: number;
+    projects: RestoreProjectPlan[];
+    chatDbIncluded: boolean;
+    /** Things to regenerate (device identity) / discard (runtime/session). */
+    regenerated: string[];
+    discarded: string[];
+    warnings: string[];
+}
+/** Result of an applied restore. */
+export interface RestoreResult {
+    restoredGlobalFiles: number;
+    restoredProjects: number;
+    chatDbRestored: boolean;
+    /** Where the pre-restore snapshot of the current CREWLY_HOME was saved. */
+    rollbackSnapshotPath: string;
+    warnings: string[];
+}
+//# sourceMappingURL=backup.types.d.ts.map

package/dist/cli/backend/src/services/backup/backup.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.types.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/backup/backup.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,oEAAoE;IACpE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iDAAiD;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,GAAG,EAAE,gBAAgB,CAAC;IACtB,4DAA4D;IAC5D,KAAK,EAAE,eAAe,EAAE,CAAC;CAC1B;AAED,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC3B,yFAAyF;IACzF,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;CACtB;AAED,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB,oGAAoG;IACpG,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,8EAA8E;IAC9E,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,4CAA4C;AAC5C,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC;IACzB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;AAEhD,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,GAAG,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACtD,yEAAyE;IACzE,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,8CAA8C;AAC9C,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,EAAE,EAAE,OAAO,CAAC;IACZ,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,cAAc,EAAE,OAAO,CAAC;IACxB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,oCAAoC;AACpC,MAAM,WAAW,aAAa;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB"}

package/dist/cli/backend/src/services/backup/backup.types.js

@@ -0,0 +1,13 @@
+/**
+ * Types for the Workspace Backup feature.
+ *
+ * A backup is a single `.tar.gz` archive containing a top-level
+ * `manifest.json` plus the captured `CREWLY_HOME` globals, each project's
+ * `.crewly/` tree, and (optionally) `chat.db`. See
+ * specs/2026-06-07-workspace-backup.md.
+ *
+ * @module services/backup/backup.types
+ */
+/** Manifest schema version — bump on any breaking layout/field change. */
+export const BACKUP_SCHEMA_VERSION = 1;
+//# sourceMappingURL=backup.types.js.map

package/dist/cli/backend/src/services/backup/backup.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.types.js","sourceRoot":"","sources":["../../../../../../backend/src/services/backup/backup.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC"}

package/dist/cli/backend/src/services/cloud/cloud-client.service.d.ts

@@ -0,0 +1,410 @@
+/**
+ * Cloud Client Service
+ *
+ * Singleton service responsible for all interactions with CrewlyAI Cloud.
+ * Handles authentication, premium template fetching, and subscription
+ * status synchronization.
+ *
+ * Premium templates are loaded into memory only — never written to disk
+ * to prevent IP leakage.
+ *
+ * @module services/cloud/cloud-client.service
+ */
+import { type CloudTier, type CloudConnectionStatus } from '../../constants.js';
+/**
+ * Persisted cloud config stored at ~/.crewly/cloud/config.json.
+ * Enables auto-reconnect on backend restart.
+ */
+export interface PersistedCloudConfig {
+    cloudUrl: string;
+    token: string;
+    tier: string;
+    connectedAt: string;
+    /** Refresh token for auto-renewing expired access tokens */
+    refreshToken?: string;
+    /**
+     * Relay-signed access JWT (distinct from the access `token`). Persisted so
+     * the BrowserProxy can re-register on backend restart without waiting for a
+     * fresh validate round-trip. Never the Google/Supabase token — see the
+     * RELAY-TOKEN-TYPE invariant in the long-term browser-relay fix design.
+     */
+    relayToken?: string;
+}
+/**
+ * Decode the `exp` (expiry, seconds since epoch) claim from a JWT without
+ * verifying its signature. Returns null when the token is malformed or has
+ * no `exp`. Used to schedule proactive relay-token refresh before expiry so
+ * a continuously-open relay socket never carries an expired token.
+ *
+ * @param token - JWT string (may be null)
+ * @returns The `exp` claim in seconds, or null when unavailable
+ */
+export declare function decodeJwtExp(token: string | null): number | null;
+/** Summary of a premium template returned by the cloud listing endpoint. */
+export interface CloudTemplateSummary {
+    /** Unique template identifier */
+    id: string;
+    /** Human-readable template name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Minimum subscription tier required */
+    requiredTier: CloudTier;
+    /** Category tag (e.g. "dev-team", "marketing") */
+    category: string;
+}
+/** Full detail for a single premium template (in-memory only). */
+export interface CloudTemplateDetail {
+    /** Unique template identifier */
+    id: string;
+    /** Human-readable template name */
+    name: string;
+    /** Full description */
+    description: string;
+    /** Minimum subscription tier required */
+    requiredTier: CloudTier;
+    /** Category tag */
+    category: string;
+    /** Team member role definitions */
+    roles: Array<{
+        role: string;
+        prompt: string;
+    }>;
+    /** Task orchestration config */
+    orchestration: Record<string, unknown>;
+}
+/** A relay device returned by the Cloud devices API. */
+export interface CloudRelayDevice {
+    /** Device/session ID */
+    sessionId: string;
+    /** Device role */
+    role: 'orchestrator' | 'agent';
+    /** Device state */
+    state: 'waiting' | 'paired' | 'disconnected';
+    /** Paired peer device ID */
+    pairedWith: string | null;
+    /** ISO registration timestamp */
+    registeredAt: string;
+    /** ISO last heartbeat timestamp */
+    lastHeartbeatAt: string;
+    /** Human-readable device name (legacy field) */
+    name?: string;
+    /** Human-readable device name returned by Cloud API */
+    deviceName?: string;
+    /** Unique device identifier */
+    deviceId?: string;
+}
+/** Current cloud connection state exposed by getStatus(). */
+export interface CloudStatus {
+    /** Whether the client is currently connected */
+    connectionStatus: CloudConnectionStatus;
+    /** Cloud API base URL (set after connect) */
+    cloudUrl: string | null;
+    /** Current subscription tier */
+    tier: CloudTier;
+    /** ISO timestamp of last successful sync */
+    lastSyncAt: string | null;
+}
+/**
+ * CloudClientService singleton.
+ *
+ * Manages the lifecycle of the connection between a local Crewly instance
+ * and CrewlyAI Cloud. All cloud API calls are made via native fetch with
+ * bearer-token authentication.
+ */
+export declare class CloudClientService {
+    private static instance;
+    private readonly logger;
+    /** Cloud API base URL (e.g. "https://api.crewlyai.com") */
+    private cloudUrl;
+    /** Bearer token obtained during connect() */
+    private token;
+    /** Refresh token for auto-renewing expired access tokens */
+    private refreshToken;
+    /** Current connection status */
+    private connectionStatus;
+    /** Subscription tier reported by cloud */
+    private tier;
+    /** Timestamp of the most recent successful cloud API call */
+    private lastSyncAt;
+    /** Timer for proactive token refresh (fires 5 min before expiry) */
+    private refreshTimer;
+    /** Guard to prevent concurrent refresh attempts */
+    private refreshInProgress;
+    /** Callbacks invoked when the access token is refreshed */
+    private tokenRefreshCallbacks;
+    /**
+     * Relay-signed access JWT used by BrowserProxyService to register with the
+     * Cloud Relay as role 'agent'. First-class, stored credential — distinct
+     * from the access `token` and decoupled from socket lifetime. NEVER the
+     * Google/Supabase access token (RELAY-TOKEN-TYPE invariant).
+     */
+    private relayToken;
+    /** Parsed `exp` (seconds) of {@link relayToken}, for proactive refresh. */
+    private relayTokenExp;
+    /** Timer for proactive relay-token refresh (fires SKEW before exp). */
+    private relayRefreshTimer;
+    /** Callbacks invoked when the relay token is refreshed (distinct channel). */
+    private relayTokenRefreshCallbacks;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns CloudClientService instance
+     */
+    static getInstance(): CloudClientService;
+    /**
+     * Reset the singleton (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Connect to CrewlyAI Cloud by verifying the provided token.
+     *
+     * Calls the cloud auth endpoint to validate credentials and retrieve
+     * the subscription tier. On success the service transitions to
+     * "connected" status.
+     *
+     * @param cloudUrl - Base URL of the CrewlyAI Cloud API
+     * @param token - Authentication token (API key or JWT)
+     * @returns Object with connection result
+     * @throws Error when the auth request fails or token is invalid
+     *
+     * @example
+     * ```ts
+     * const client = CloudClientService.getInstance();
+     * await client.connect('https://api.crewlyai.com', 'sk-abc123');
+     * ```
+     */
+    connect(cloudUrl: string, token: string, refreshToken?: string): Promise<{
+        success: boolean;
+        tier: CloudTier;
+    }>;
+    /**
+     * Connect using a locally verified JWT (no remote API call needed).
+     *
+     * Used when the JWT was issued by this same instance or the JWT secret
+     * is shared between OSS and Cloud. Avoids the round-trip to the cloud
+     * auth endpoint.
+     *
+     * @param cloudUrl - Base URL of the CrewlyAI Cloud API
+     * @param token - JWT access token (already verified locally)
+     * @param tier - Subscription tier extracted from the JWT payload
+     * @param refreshToken - Optional refresh token for auto-renewal
+     */
+    connectLocal(cloudUrl: string, token: string, tier: CloudTier, refreshToken?: string): void;
+    /**
+     * Disconnect from CrewlyAI Cloud.
+     *
+     * Clears stored credentials and resets the connection state.
+     */
+    disconnect(): void;
+    /**
+     * Path to the persisted cloud config file.
+     */
+    static getConfigPath(): string;
+    /**
+     * Load persisted cloud config from disk.
+     * Returns null if file doesn't exist or is invalid.
+     */
+    loadPersistedConfig(): Promise<PersistedCloudConfig | null>;
+    /**
+     * Persist current cloud connection config to disk for auto-reconnect.
+     */
+    private persistConfig;
+    /**
+     * Remove persisted cloud config from disk (on disconnect).
+     */
+    private removePersistedConfig;
+    /**
+     * Fetch the list of premium templates available on CrewlyAI Cloud.
+     *
+     * Requires an active cloud connection.
+     *
+     * @returns Array of template summaries
+     * @throws Error when not connected or fetch fails
+     *
+     * @example
+     * ```ts
+     * const templates = await client.getTemplates();
+     * console.log(templates.map(t => t.name));
+     * ```
+     */
+    getTemplates(): Promise<CloudTemplateSummary[]>;
+    /**
+     * Fetch full detail for a single premium template.
+     *
+     * The returned data is held in memory only and must never be
+     * persisted to disk.
+     *
+     * @param id - Template identifier
+     * @returns Template detail object
+     * @throws Error when not connected, template not found, or fetch fails
+     *
+     * @example
+     * ```ts
+     * const detail = await client.getTemplateDetail('tpl-tiktok-ops');
+     * ```
+     */
+    getTemplateDetail(id: string): Promise<CloudTemplateDetail>;
+    /**
+     * Get the stored cloud API base URL (set during connect).
+     *
+     * @returns Cloud URL or null if not connected
+     */
+    getCloudUrl(): string | null;
+    /**
+     * Get the current cloud connection status and subscription tier.
+     *
+     * @returns Current status snapshot
+     */
+    getStatus(): CloudStatus;
+    /**
+     * Check whether the client is currently connected to cloud.
+     *
+     * @returns true if connected
+     */
+    isConnected(): boolean;
+    /**
+     * Check whether the cloud token has expired (401/403 from cloud API).
+     *
+     * @returns true if the token has expired
+     */
+    isTokenExpired(): boolean;
+    /**
+     * Get the current subscription tier.
+     *
+     * @returns Current tier value
+     */
+    getTier(): CloudTier;
+    /**
+     * Fetch the list of devices registered to this user from Cloud.
+     *
+     * Proxies GET /api/v1/relay/devices on crewlyai.com and returns
+     * the device list for the authenticated user.
+     *
+     * @returns Array of cloud relay devices
+     * @throws Error when not connected or fetch fails
+     */
+    fetchCloudDevices(): Promise<CloudRelayDevice[]>;
+    /**
+     * Set the refresh token for auto-renewal.
+     *
+     * Called by the connect controller after OAuth login provides a refresh token.
+     *
+     * @param refreshToken - Refresh token string
+     */
+    setRefreshToken(refreshToken: string): void;
+    /**
+     * Get the current access token (for CloudSyncService token updates).
+     *
+     * @returns Current access token or null
+     */
+    getToken(): string | null;
+    /**
+     * Register a callback to be invoked whenever the access token is refreshed.
+     * Used by BrowserProxyService to update its relay auth token in real-time.
+     *
+     * @param callback - Function receiving the new access token string
+     */
+    onTokenRefresh(callback: (newToken: string) => void): void;
+    /**
+     * Get the current relay-signed token (for BrowserProxyService registration).
+     *
+     * This is DISTINCT from {@link getToken} (the access/HTTP token). The
+     * BrowserProxy must register with the relay token, never the access token —
+     * see the RELAY-TOKEN-TYPE invariant. Returns null until a relay token has
+     * been minted by the Cloud validate/refresh endpoint.
+     *
+     * @returns Current relay token or null
+     */
+    getRelayToken(): string | null;
+    /**
+     * Register a callback invoked whenever the relay token is refreshed.
+     *
+     * Distinct subscription channel from {@link onTokenRefresh}: subscribers
+     * here (BrowserProxyService) receive the relay-signed token, never the
+     * access token. Decoupling the channels prevents the proxy from ever being
+     * fed the wrong token type on refresh.
+     *
+     * @param callback - Function receiving the new relay token string
+     */
+    onRelayTokenRefresh(callback: (newRelayToken: string) => void): void;
+    /**
+     * Store a freshly-minted relay token as a first-class credential, parse its
+     * expiry, schedule proactive refresh, persist it, and notify subscribers.
+     *
+     * Centralizes relay-token handling so every code path that obtains one
+     * (connect, refresh, validate) treats it identically. Persistence is
+     * fire-and-forget; a persist failure must not break the refresh chain.
+     *
+     * @param relayToken - The relay-signed access JWT from Cloud
+     */
+    private storeRelayToken;
+    /**
+     * Attempt to refresh the access token using the stored refresh token.
+     *
+     * Issues a new access token locally (since both access and refresh tokens
+     * are signed with the same HMAC secret on this OSS instance).
+     *
+     * @returns true if refresh succeeded, false if no refresh token or refresh failed
+     */
+    tryRefreshToken(): Promise<boolean>;
+    /**
+     * Schedule a proactive token refresh 5 minutes before expiry.
+     *
+     * Parses the JWT `exp` claim and sets a timer. If the token has
+     * less than 5 minutes remaining, refreshes immediately.
+     *
+     * @param token - JWT access token to extract expiry from
+     */
+    private scheduleTokenRefresh;
+    /**
+     * Schedule a proactive relay-token refresh `RELAY_REFRESH_SKEW_S` seconds
+     * before the relay token's real `exp`.
+     *
+     * The relay token (~60min TTL) is decoupled from the access token, so it
+     * needs its own refresh schedule. When the timer fires it calls
+     * {@link fetchRelayTokenFromValidate}, which re-mints a relay token and
+     * stores it (re-arming this timer). This keeps a continuously-open relay
+     * socket from ever carrying an expired token — the DURABLE-CREDENTIAL
+     * invariant. Driven by the JWT `exp` claim, not a wall-clock heuristic.
+     */
+    private scheduleRelayTokenRefresh;
+    /**
+     * Fetch relay token by calling Cloud validate endpoint.
+     * Used after connectLocal() to get a Cloud-signed relay JWT
+     * without blocking the connection flow.
+     *
+     * @returns Promise that resolves when relay token is fetched (or skipped)
+     */
+    private fetchRelayTokenFromValidate;
+    /**
+     * Throw if the client is not in a connected state.
+     *
+     * @throws Error when not connected
+     */
+    private ensureConnected;
+    /**
+     * Build the standard authorization headers for cloud API requests.
+     *
+     * @returns Headers object with Authorization and Content-Type
+     */
+    private authHeaders;
+    /**
+     * Check if an HTTP status code indicates an authentication/authorization failure.
+     *
+     * @param status - HTTP status code
+     * @returns true if the status is 401 or 403
+     */
+    private isAuthError;
+    /**
+     * Handle a 401/403 response from the cloud API by transitioning
+     * the connection status to TOKEN_EXPIRED. This signals the frontend
+     * to show a reconnect prompt instead of a raw error.
+     *
+     * @param context - Description of the failed operation (for logging)
+     * @param status - HTTP status code from the cloud API
+     */
+    private handleAuthFailure;
+}
+//# sourceMappingURL=cloud-client.service.d.ts.map

package/dist/cli/backend/src/services/cloud/cloud-client.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-client.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/cloud/cloud-client.service.ts"],"names":[],"mappings":"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"}