@roamcode.ai/server 1.2.0 → 1.4.0

package/dist/start.d.ts

@@ -1,4 +1,5 @@
 import { FastifyInstance } from 'fastify';
+import { z } from 'zod';
 
 /**
  * Wiring for the mcp-send server (Claude → user attachments). When present, the spawn layer writes a
@@ -184,7 +185,7 @@ type AuthCheckResult = {
  * WebSocket upgrade.
  *
  * Proxy lockout caveat: the lockout is keyed by `clientKey` (`request.ip`).
- * Behind a reverse proxy (Caddy / Cloudflare) `request.ip` is the proxy's IP
+ * Behind a reverse proxy, `request.ip` is the proxy's IP
  * for EVERY client, collapsing the per-client lockout to one shared key. To
  * stop that from self-DoS-ing the sole legitimate user, {@link check} validates
  * the token FIRST: a CORRECT token is ALWAYS accepted, even while its key is
@@ -369,6 +370,134 @@ interface PairingTicket {
     scopes: DeviceScope[];
 }
 
+declare const CloudAutomationWebhookRegistrationSchema: z.ZodObject<{
+    hookId: z.ZodString;
+    automationId: z.ZodString;
+    triggerId: z.ZodString;
+    secretHash: z.ZodString;
+    enabled: z.ZodBoolean;
+}, z.core.$strict>;
+declare const CloudAutomationInvocationSchema: z.ZodObject<{
+    id: z.ZodUUID;
+    automationId: z.ZodString;
+    triggerId: z.ZodString;
+    hookId: z.ZodString;
+    createdAt: z.ZodNumber;
+}, z.core.$strict>;
+type CloudAutomationWebhookRegistration = z.infer<typeof CloudAutomationWebhookRegistrationSchema>;
+type CloudAutomationInvocation = z.infer<typeof CloudAutomationInvocationSchema>;
+
+type TeamStoreMode = "sqlite" | "memory-fallback";
+type TeamMemberKind = "person" | "service";
+type TeamMemberStatus = "active" | "suspended" | "removed";
+type TeamRole = "viewer" | "operator" | "node-admin" | "workspace-manager" | "extension-manager" | "policy-admin" | "organization-admin";
+type TeamScopeType = "team" | "host" | "workspace";
+type TeamPrincipalType = "device" | "host" | "local" | "relay";
+type TeamPermission = "team:read" | "sessions:read" | "sessions:operate" | "attention:read" | "attention:manage" | "presence:read" | "presence:write" | "workspaces:manage" | "extensions:manage" | "policy:manage" | "members:manage" | "node-access:manage" | "audit:read" | "fleet:read";
+interface TeamRecord {
+    id: string;
+    name: string;
+    authorizationEnabled: boolean;
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+}
+interface TeamMember {
+    id: string;
+    displayName: string;
+    kind: TeamMemberKind;
+    status: TeamMemberStatus;
+    revision: number;
+    createdAt: number;
+    updatedAt: number;
+}
+interface TeamRoleBinding {
+    id: string;
+    memberId: string;
+    role: TeamRole;
+    scopeType: TeamScopeType;
+    scopeId?: string;
+    createdAt: number;
+}
+interface TeamPrincipalBinding {
+    actorType: TeamPrincipalType;
+    actorId: string;
+    memberId: string;
+    createdAt: number;
+}
+interface TeamAuthorizationResource {
+    hostId?: string;
+    workspaceId?: string;
+}
+interface TeamAuthorizationDecision {
+    allowed: boolean;
+    reason: "local-break-glass" | "not-enforced" | "unbound" | "inactive" | "role" | "missing-permission";
+    member?: TeamMember;
+    roles: TeamRole[];
+}
+interface TeamStore {
+    readonly mode: TeamStoreMode;
+    getTeam(): TeamRecord | null;
+    createTeam(input: {
+        name: string;
+        ownerName: string;
+        ownerPrincipal: {
+            actorType: TeamPrincipalType;
+            actorId: string;
+        };
+    }, now?: number): {
+        team: TeamRecord;
+        owner: TeamMember;
+    };
+    updateTeam(input: {
+        name?: string;
+        authorizationEnabled?: boolean;
+    }, expectedRevision: number, now?: number): TeamRecord;
+    listMembers(opts?: {
+        includeRemoved?: boolean;
+    }): TeamMember[];
+    getMember(id: string): TeamMember | undefined;
+    createMember(input: {
+        displayName: string;
+        kind?: TeamMemberKind;
+    }, now?: number): TeamMember;
+    updateMember(id: string, input: {
+        displayName?: string;
+        status?: TeamMemberStatus;
+    }, expectedRevision: number, now?: number): TeamMember | undefined;
+    listRoleBindings(memberId?: string): TeamRoleBinding[];
+    grantRole(input: {
+        memberId: string;
+        role: TeamRole;
+        scopeType?: TeamScopeType;
+        scopeId?: string;
+    }, now?: number): TeamRoleBinding;
+    setNodeAccessRole(input: {
+        memberId: string;
+        nodeId: string;
+        role: "viewer" | "operator" | "node-admin";
+    }, now?: number): TeamRoleBinding;
+    revokeRole(id: string, now?: number): boolean;
+    listPrincipalBindings(memberId?: string): TeamPrincipalBinding[];
+    bindPrincipal(input: {
+        memberId: string;
+        actorType: TeamPrincipalType;
+        actorId: string;
+    }, now?: number): TeamPrincipalBinding;
+    unbindPrincipal(actorType: TeamPrincipalType, actorId: string, now?: number): boolean;
+    memberForPrincipal(actorType: TeamPrincipalType, actorId: string): TeamMember | undefined;
+    authorize(actorType: TeamPrincipalType, actorId: string, permission: TeamPermission, resource?: TeamAuthorizationResource): TeamAuthorizationDecision;
+    close(): void;
+}
+
+type CloudAuthorizationSnapshotStatus = "unavailable" | "pending" | "active" | "expired";
+interface CloudAuthorizationState {
+    status: CloudAuthorizationSnapshotStatus;
+    revision?: number;
+    notBefore?: number;
+    expiresAt?: number;
+}
+
 declare global {
     /** Stable package version injected by tsup. Source/test builds fall back to package.json. */
     const __SERVER_VERSION__: string | undefined;
@@ -689,6 +818,17 @@ declare class TerminalManager {
     private cleanupRecordPaths;
     private applyRuntimeSignal;
     write(id: string, data: string): void;
+    /**
+     * Start a newly-created automation Session and submit its task exactly once. `create()` is intentionally
+     * lazy, so writing before an attach would be a silent no-op; this method first owns a private attachment,
+     * waits for the provider TUI's idle composer (not merely a banner/auth/trust frame), then sends one bracketed
+     * paste and releases the attachment.
+     * The task never enters argv, logs, audit metadata, or a WebSocket URL.
+     */
+    bootstrapTask(id: string, task: string, options?: {
+        readyTimeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
     resize(id: string, cols: number, rows: number): void;
     stop(id: string): void;
     get(id: string): TerminalMeta | undefined;
@@ -788,102 +928,27 @@ declare class InputLeaseCoordinator {
     private emit;
 }
 
-type TeamStoreMode = "sqlite" | "memory-fallback";
-type TeamMemberKind = "person" | "service";
-type TeamMemberStatus = "active" | "suspended" | "removed";
-type TeamRole = "viewer" | "operator" | "workspace-manager" | "extension-manager" | "policy-admin" | "organization-admin";
-type TeamScopeType = "team" | "host" | "workspace";
-type TeamPrincipalType = "device" | "host" | "local" | "relay";
-type TeamPermission = "team:read" | "sessions:read" | "sessions:operate" | "attention:read" | "attention:manage" | "presence:read" | "presence:write" | "workspaces:manage" | "extensions:manage" | "policy:manage" | "members:manage" | "audit:read" | "fleet:read";
-interface TeamRecord {
-    id: string;
-    name: string;
-    authorizationEnabled: boolean;
-    revision: number;
-    createdAt: number;
-    updatedAt: number;
-}
-interface TeamMember {
-    id: string;
-    displayName: string;
-    kind: TeamMemberKind;
-    status: TeamMemberStatus;
-    revision: number;
-    createdAt: number;
-    updatedAt: number;
-}
-interface TeamRoleBinding {
-    id: string;
-    memberId: string;
-    role: TeamRole;
-    scopeType: TeamScopeType;
-    scopeId?: string;
-    createdAt: number;
-}
-interface TeamPrincipalBinding {
-    actorType: TeamPrincipalType;
-    actorId: string;
-    memberId: string;
-    createdAt: number;
-}
-interface TeamAuthorizationResource {
-    hostId?: string;
-    workspaceId?: string;
-}
-interface TeamAuthorizationDecision {
-    allowed: boolean;
-    reason: "local-break-glass" | "not-enforced" | "unbound" | "inactive" | "role" | "missing-permission";
-    member?: TeamMember;
-    roles: TeamRole[];
-}
-interface TeamStore {
-    readonly mode: TeamStoreMode;
-    getTeam(): TeamRecord | null;
-    createTeam(input: {
-        name: string;
-        ownerName: string;
-        ownerPrincipal: {
-            actorType: TeamPrincipalType;
-            actorId: string;
-        };
-    }, now?: number): {
-        team: TeamRecord;
-        owner: TeamMember;
-    };
-    updateTeam(input: {
-        name?: string;
-        authorizationEnabled?: boolean;
-    }, expectedRevision: number, now?: number): TeamRecord;
-    listMembers(opts?: {
-        includeRemoved?: boolean;
-    }): TeamMember[];
-    getMember(id: string): TeamMember | undefined;
-    createMember(input: {
-        displayName: string;
-        kind?: TeamMemberKind;
-    }, now?: number): TeamMember;
-    updateMember(id: string, input: {
-        displayName?: string;
-        status?: TeamMemberStatus;
-    }, expectedRevision: number, now?: number): TeamMember | undefined;
-    listRoleBindings(memberId?: string): TeamRoleBinding[];
-    grantRole(input: {
-        memberId: string;
-        role: TeamRole;
-        scopeType?: TeamScopeType;
-        scopeId?: string;
-    }, now?: number): TeamRoleBinding;
-    revokeRole(id: string, now?: number): boolean;
-    listPrincipalBindings(memberId?: string): TeamPrincipalBinding[];
-    bindPrincipal(input: {
-        memberId: string;
-        actorType: TeamPrincipalType;
-        actorId: string;
-    }, now?: number): TeamPrincipalBinding;
-    unbindPrincipal(actorType: TeamPrincipalType, actorId: string, now?: number): boolean;
-    memberForPrincipal(actorType: TeamPrincipalType, actorId: string): TeamMember | undefined;
-    authorize(actorType: TeamPrincipalType, actorId: string, permission: TeamPermission, resource?: TeamAuthorizationResource): TeamAuthorizationDecision;
-    close(): void;
+interface CloudHostRuntimeStatus {
+    running: boolean;
+    heartbeatFailures: number;
+    authorizationFailures: number;
+    automationFailures: number;
+    authorizationIssue?: CloudHostAuthorizationIssue;
+    lastHeartbeatAt?: number;
+    lastAuthorizationAt?: number;
+    authorization: CloudAuthorizationState;
+}
+type CloudHostAuthorizationIssue = "connectivity" | "credential-rejected" | "invalid-control-plane-response" | "authorization-verification-failed" | "trust-expired";
+interface CloudHostRuntime {
+    start(): void;
+    stop(): Promise<void>;
+    sendHeartbeat(state?: "ready" | "draining"): Promise<void>;
+    refreshAuthorizationKeyset(): Promise<boolean>;
+    refreshAuthorizationSnapshot(): Promise<number>;
+    syncAuthorization(): Promise<number>;
+    /** Waits out an older in-flight poll, then starts a snapshot request from the resulting durable revision. */
+    syncAuthorizationFresh(): Promise<number>;
+    status(): CloudHostRuntimeStatus;
 }
 
 type PolicyStoreMode = "sqlite" | "memory-fallback";
@@ -1078,6 +1143,10 @@ interface CreateServerResult {
     presence: PresenceCoordinator;
     /** False when tmux/node-pty is unavailable → terminal sessions are disabled (startServer warns loudly). */
     terminalAvailable: boolean;
+    /** Privacy-bounded webhook routing records synchronized to an optional managed control plane. */
+    automationWebhookRegistrations(): CloudAutomationWebhookRegistration[];
+    /** Durably accepts one control-plane signal; the invocation id makes redelivery idempotent. */
+    acceptCloudAutomationInvocation(invocation: CloudAutomationInvocation): Promise<void>;
 }
 
 type RelayHostStatus = "idle" | "connecting" | "online" | "reconnecting" | "stopped";
@@ -1121,11 +1190,22 @@ declare function claudePreflightWarning(availability: ClaudeAvailability): strin
  * (the probe is short-timeout-guarded). Injectable probe + log sink so it's testable without a spawn.
  */
 declare function runClaudePreflight(probe: ClaudeVersionProbe, warn?: (msg: string) => void): Promise<void>;
-declare function startServer(env?: NodeJS.ProcessEnv): Promise<CreateServerResult & {
+interface StartServerOptions {
+    /** Shared control-plane transport seam for isolated embedding and startup tests. */
+    fetch?: typeof globalThis.fetch;
+}
+declare function cloudHostCapabilities(input: {
+    authorizationVersion: number;
+    terminalAvailable: boolean;
+    relayEnabled: boolean;
+    managedDeviceEnrollmentEnabled: boolean;
+}): string[];
+declare function startServer(env?: NodeJS.ProcessEnv, options?: StartServerOptions): Promise<CreateServerResult & {
     url: string;
     token?: string;
     tokenGenerated: boolean;
     relayHost?: RelayHostConnector;
+    cloudHostRuntime?: CloudHostRuntime;
 }>;
 
-export { claudePreflightWarning, providerPreflightWarning, runClaudePreflight, runProviderPreflight, startServer };
+export { type StartServerOptions, claudePreflightWarning, cloudHostCapabilities, providerPreflightWarning, runClaudePreflight, runProviderPreflight, startServer };