@sjhmars/happy-bridge 0.1.0

package/lib/types/machine.d.ts

@@ -0,0 +1,40 @@
+/** Machine-scoped Happy socket: spawn, stop-session, slim listDirectory. */
+import type { CryptoContext } from './encryption.ts';
+import type { SpawnSessionOptions, SpawnSessionResult, VirtualWorkspace } from './types.ts';
+/** Machine RPC handlers owned by the bridge. */
+export interface MachineHandlers {
+    spawn: (options: SpawnSessionOptions) => Promise<SpawnSessionResult>;
+    /** Continue an offline Happy row (`resume-happy-session`). */
+    resume: (happySessionId: string) => Promise<SpawnSessionResult>;
+    stopSession: (happySessionId: string) => void;
+    listWorkspaces: () => VirtualWorkspace[];
+    log: (message: string) => void;
+}
+/**
+ * Machine-scoped connection so the App New button reaches this Host.
+ */
+export declare class HappyMachineSocket {
+    readonly machineId: string;
+    private readonly token;
+    private readonly serverUrl;
+    private readonly crypto;
+    private readonly handlers;
+    private socket;
+    private aliveTimer;
+    private readonly rpcMethods;
+    /**
+     * @param machineId - stable machine id.
+     * @param token - bearer token.
+     * @param serverUrl - API origin.
+     * @param crypto - machine encryption.
+     * @param handlers - spawn / resume / list / stop.
+     */
+    constructor(machineId: string, token: string, serverUrl: string, crypto: CryptoContext, handlers: MachineHandlers);
+    /** Connect and register prefixed RPCs. Does not register bash/writeFile. */
+    connect(): Promise<void>;
+    private bindRpc;
+    private sendAlive;
+    /** Close the machine socket. */
+    dispose(): void;
+}
+//# sourceMappingURL=machine.d.ts.map

package/lib/types/pairing.d.ts

@@ -0,0 +1,23 @@
+/** Happy terminal pairing: POST /v1/auth/request, QR URL, poll until authorized. */
+import type { Credentials } from './types.ts';
+/** Live pairing attempt the settings card can display. */
+export interface PairingAttempt {
+    /** Mobile `happy://terminal?...` URL. */
+    mobileUrl: string;
+    /** Web App connect URL. */
+    webUrl: string;
+    /** QR PNG data URL of the mobile URL. */
+    qrDataUrl: string;
+    /** Stop polling. */
+    abort: () => void;
+    /** Resolves with credentials when the phone approves. */
+    done: Promise<Omit<Credentials, 'machineId'>>;
+}
+/**
+ * Start one terminal auth request and poll until authorized.
+ * @param serverUrl - Happy API origin.
+ * @param appUrl - Happy App origin for the web URL.
+ * @returns URLs plus a promise that settles on success or abort.
+ */
+export declare function startPairing(serverUrl: string, appUrl: string): Promise<PairingAttempt>;
+//# sourceMappingURL=pairing.d.ts.map

package/lib/types/paths.d.ts

@@ -0,0 +1,53 @@
+/** Map Happy picker paths onto registered workspace directories. Do not mkdir. */
+import type { VirtualWorkspace } from './types.ts';
+/** Virtual home the Happy directory picker starts in. */
+export declare const VIRTUAL_HOME = "/dsh-workspaces";
+/**
+ * Normalize a path for comparison: slashes, no trailing slash (except root), Windows drive case.
+ * @param value - real or virtual path.
+ * @returns comparable spelling.
+ */
+export declare function normalizePath(value: string): string;
+/**
+ * Build virtual workspace entries from real registered roots.
+ * @param workspaces - `{ path, title, id }` from `workspaceRegistry.list()`.
+ * @returns virtual POSIX paths under {@link VIRTUAL_HOME}.
+ */
+export declare function virtualWorkspaces(workspaces: readonly {
+    id: string;
+    path: string;
+    title: string;
+}[]): VirtualWorkspace[];
+/**
+ * Find the registered workspace that owns a real session cwd.
+ * Nested roots pick the longest matching path.
+ * @param realCwd - session `header.cwd` or persisted meta.cwd.
+ * @param workspaces - virtual mapping.
+ */
+export declare function matchVirtualWorkspace(realCwd: string, workspaces: readonly VirtualWorkspace[]): VirtualWorkspace | undefined;
+/**
+ * Resolve a spawn `directory` to a registered workspace real path.
+ * @param directory - Happy spawn directory (virtual or real).
+ * @param workspaces - virtual mapping.
+ * @returns real path, or `undefined` when it is not a registered workspace.
+ */
+export declare function resolveSpawnDirectory(directory: string, workspaces: readonly VirtualWorkspace[]): string | undefined;
+/**
+ * Slim `listDirectory`: only the virtual home and workspace roots.
+ * @param requestPath - path the App asked to list.
+ * @param workspaces - virtual mapping.
+ * @returns Happy listDirectory payload.
+ */
+export declare function listVirtualDirectory(requestPath: string, workspaces: readonly VirtualWorkspace[]): {
+    success: true;
+    entries: {
+        name: string;
+        type: 'directory';
+    }[];
+} | {
+    success: false;
+    error: string;
+};
+/** Windows-aware basename for a real workspace path shown as a fallback slug. */
+export declare function realBasename(realPath: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/lib/types/remote.d.ts

@@ -0,0 +1,34 @@
+/** Typert Remote for the settings card: pairing status, start, disconnect. */
+import type { Context } from '@deepseek-ai/cordis';
+import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import type { HappyBridge } from './bridge.ts';
+import type { PairingStatus } from './types.ts';
+/**
+ * Host RPC the browser settings card calls.
+ */
+export declare class HappyBridgeService extends TypertRemoteService {
+    /** Live bridge; swapped when settings rebuild. */
+    live: HappyBridge | undefined;
+    /**
+     * @param ctx - Host context.
+     */
+    constructor(ctx: Context);
+    /**
+     * Current pairing / connection snapshot, including a QR data URL while pairing.
+     * @returns status for the settings card.
+     */
+    getStatus(): Promise<PairingStatus>;
+    /**
+     * Start or resume pairing.
+     */
+    startPairing(): Promise<PairingStatus>;
+    /**
+     * Disconnect Happy. The web UI keeps running.
+     */
+    disconnect(): Promise<PairingStatus>;
+    /**
+     * Drop the current login and start a fresh QR pairing.
+     */
+    rePair(): Promise<PairingStatus>;
+}
+//# sourceMappingURL=remote.d.ts.map

package/lib/types/rpc.d.ts

@@ -0,0 +1,22 @@
+/** Prefixed Happy RPC: encrypt params/results, wait for `rpc-registered`. */
+import type { Socket } from 'socket.io-client';
+import { type CryptoContext } from './encryption.ts';
+/** Handler for one decrypted RPC method. */
+export type RpcHandler = (params: unknown) => unknown | Promise<unknown>;
+/**
+ * Register `{prefix}:{method}` and wait for the server ack (with timeout).
+ * @param socket - connected Socket.IO socket.
+ * @param prefix - machineId or sessionId.
+ * @param method - bare method name.
+ * @param crypto - same variant as chat.
+ * @param handler - decrypted params in, plaintext result out.
+ * @param log - warning logger.
+ */
+export declare function registerRpc(socket: Socket, prefix: string, method: string, crypto: CryptoContext, handler: RpcHandler, log: (message: string) => void): Promise<void>;
+/**
+ * Re-emit `rpc-register` after a Socket.IO reconnect without adding another handler.
+ * @param socket - connected socket.
+ * @param method - already-prefixed `{id}:{name}` method.
+ */
+export declare function requestRpcRegister(socket: Socket, method: string): void;
+//# sourceMappingURL=rpc.d.ts.map

package/lib/types/session-socket.d.ts

@@ -0,0 +1,145 @@
+/** One Happy session-scoped socket: encrypt chat, metadata, agentState, permission RPC. */
+import { type CryptoContext } from './encryption.ts';
+import { type HappyInbound } from './inbound.ts';
+import type { PermissionRpc } from './types.ts';
+/** Callbacks the bridge installs on one Happy session. */
+export interface SessionHandlers {
+    /** Decrypted inbound chat or file. */
+    onInbound: (message: InboundMessage) => void;
+    /** Phone answered a permission / fake-tool request. */
+    onPermission: (rpc: PermissionRpc) => void;
+    /** Phone tapped Stop. Happy App `sessionAbort` for Rig sends `{}`. */
+    onAbort: () => void;
+    /** App archived or deleted this Happy session. */
+    onArchived: () => void;
+    /** App restored an archived session (lifecycle back to running). */
+    onResumed: () => void;
+    /** Phone changed Happy session metadata (model picker, without sending). */
+    onCatalog: (meta: Record<string, unknown>) => void;
+    /** Log line. */
+    log: (message: string) => void;
+}
+/** Normalized inbound payload from Happy. */
+export type InboundMessage = HappyInbound;
+/**
+ * Session-scoped Happy client for one mirrored or spawned conversation.
+ */
+export declare class HappySessionSocket {
+    readonly happySessionId: string;
+    private readonly token;
+    private readonly serverUrl;
+    private readonly crypto;
+    private readonly handlers;
+    private socket;
+    private metadataVersion;
+    private agentStateVersion;
+    private aliveTimer;
+    private turnId;
+    private thinking;
+    private rpcReady;
+    private readonly rpcMethods;
+    /**
+     * @param happySessionId - Happy cloud session id.
+     * @param token - bearer token.
+     * @param serverUrl - API origin.
+     * @param crypto - content encryption for this session.
+     * @param handlers - inbound callbacks.
+     */
+    constructor(happySessionId: string, token: string, serverUrl: string, crypto: CryptoContext, handlers: SessionHandlers);
+    /** Connect, register permission + abort + killSession, start keepalive. */
+    connect(initialMetadataVersion?: number, initialAgentStateVersion?: number): Promise<void>;
+    /** Stop session-alive so an App archive can stick. */
+    stopKeepAlive(): void;
+    /** Close the socket and keepalive. */
+    dispose(): void;
+    /** Whether the Happy session-scoped socket is connected. */
+    isConnected(): boolean;
+    /** Current Happy turn id for agent envelopes. */
+    currentTurn(): string | undefined;
+    /**
+     * Open a Happy turn (turn-start).
+     * @param time - original log time when replaying history.
+     * @returns the new turn id.
+     */
+    startTurn(time?: number): string;
+    /**
+     * Close the Happy turn.
+     * @param status - completed / failed / cancelled.
+     * @param time - original log time when replaying history.
+     */
+    endTurn(status: 'completed' | 'failed' | 'cancelled', time?: number): void;
+    /**
+     * Send an agent text or service envelope.
+     * @param kind - `text` or `service`.
+     * @param text - markdown body.
+     * @param time - original log time when replaying history.
+     * @param thinking - `true` for a reasoning block the App can collapse.
+     */
+    sendText(kind: 'text' | 'service', text: string, time?: number, thinking?: boolean): void;
+    /**
+     * Send a user text envelope (history backfill or echo).
+     * @param text - markdown body.
+     * @param time - original log time when replaying history.
+     */
+    sendUser(text: string, time?: number): void;
+    /**
+     * Send a user file envelope after the encrypted blob is already on Happy.
+     * Matches CLI `uploadLocalImageAttachmentEnvelope`: `size` is plaintext bytes.
+     * @param file - Happy `ref` plus display fields.
+     * @param time - original log time when replaying history.
+     */
+    sendFile(file: {
+        ref: string;
+        name: string;
+        size: number;
+        mimeType?: string;
+    }, time?: number): void;
+    /**
+     * Send a tool-call card.
+     * @param call - matching id. A later start with the same id updates description.
+     * @param name - Happy tool name (PascalCase knownTools, or a camouflage).
+     * @param args - tool arguments. Happy merges by keeping already-seen keys.
+     * @param title - short heading (schema-required; App often ignores it).
+     * @param description - row subtitle the App actually shows.
+     * @param time - original log time when replaying history.
+     */
+    sendToolStart(call: string, name: string, args: Record<string, unknown>, title: string, description: string, time?: number): void;
+    /**
+     * Close a tool-call card.
+     * @param call - matching id.
+     * @param time - original log time when replaying history.
+     */
+    sendToolEnd(call: string, time?: number): void;
+    /**
+     * Emit session-alive so the App shows the session as linked / online.
+     * Happy CLI sends this immediately and every 2s; without it the list archives the row.
+     * @param thinking - `agent/status === running`.
+     */
+    keepAlive(thinking: boolean): void;
+    /**
+     * Restart session-alive if the timer was cleared. Happy lists the row as
+     * offline once heartbeats stop; opening the chat on the phone does not
+     * start them again.
+     */
+    ensureKeepAlive(): void;
+    private emitAlive;
+    private ensureAliveTimer;
+    /** Tell Happy this session process is gone so the App can archive or delete it. */
+    endSession(): void;
+    /**
+     * Encrypt and push session metadata.
+     * @param metadata - plaintext catalog object.
+     */
+    updateMetadata(metadata: unknown): void;
+    private emitMetadata;
+    /**
+     * Encrypt and push agentState (permission requests).
+     * @param agentState - plaintext agentState.
+     */
+    updateState(agentState: unknown): void;
+    private sendAgent;
+    private emitEnvelope;
+    private onMetadataUpdate;
+    private dispatchInbound;
+}
+//# sourceMappingURL=session-socket.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,104 @@
+/** Shared plugin types: config, credentials, remote grant, and Happy wire extras. */
+/** Remote-control depth the phone is allowed on this Host. */
+export type RemoteGrant = 'watch' | 'chat' | 'approve' | 'full';
+/** Validated plugin config. */
+export interface Config {
+    /** Master switch. */
+    enabled: boolean;
+    /** Happy API origin. */
+    serverUrl: string;
+    /** Happy App origin used to build the web pairing URL. */
+    appUrl: string;
+    /** Credential directory; empty means `%USERPROFILE%\.dsh\happy-bridge`. */
+    credentialDir: string;
+    /** Start or resume pairing when the plugin loads. */
+    pairOnStart: boolean;
+    /** How deeply the phone may control this Host. */
+    remoteGrant: RemoteGrant;
+}
+/** Encryption variant stored with the account credentials. */
+export type EncryptionVariant = 'legacy' | 'dataKey';
+/** Account credentials after pairing or loading `~/.happy/access.key`. */
+export interface Credentials {
+    /** Bearer token for HTTP and Socket.IO. */
+    token: string;
+    /** Content-encryption variant. */
+    encryption: {
+        type: 'legacy';
+        secret: Uint8Array;
+    } | {
+        type: 'dataKey';
+        publicKey: Uint8Array;
+        machineKey: Uint8Array;
+    };
+    /** Stable machine id for machine-scoped sockets. */
+    machineId: string;
+}
+/** Pairing / connection snapshot served to the settings card. */
+export interface PairingStatus {
+    /** Whether a usable token is on disk and not locally disconnected. */
+    paired: boolean;
+    /** Whether we are currently polling `/v1/auth/request`. */
+    pairing: boolean;
+    /** Mobile `happy://terminal?...` URL, when pairing. */
+    mobileUrl?: string;
+    /** Web App connect URL, when pairing. */
+    webUrl?: string;
+    /** QR PNG as a data URL for the mobile pairing URL. */
+    qrDataUrl?: string;
+    /** Last error shown on the card. */
+    error?: string;
+    /** Configured Happy API origin. */
+    serverUrl: string;
+    /** Machine id once known. */
+    machineId?: string;
+    /** How many mirrored Happy session sockets exist. */
+    sessionCount?: number;
+    /** How many of those sockets are currently connected. */
+    linkedCount?: number;
+}
+/** One pending Happy file waiting to ride with the next user text. */
+export interface PendingFile {
+    /** Original display name. */
+    name: string;
+    /** Decrypted bytes. */
+    bytes: Uint8Array;
+    /** Declared or sniffed media type. */
+    mimeType: string;
+}
+/** Spawn RPC input (Happy CLI `SpawnSessionOptions` subset). */
+export interface SpawnSessionOptions {
+    directory: string;
+    sessionId?: string;
+    permissionMode?: string;
+    modelMode?: string;
+    effortLevel?: string;
+}
+/** Spawn RPC result. */
+export type SpawnSessionResult = {
+    type: 'success';
+    sessionId: string;
+} | {
+    type: 'error';
+    errorMessage: string;
+};
+/** One registered workspace exposed as a virtual directory under `/dsh-workspaces`. */
+export interface VirtualWorkspace {
+    /** Virtual POSIX path the Happy picker can join. */
+    virtualPath: string;
+    /** Real workspace directory. */
+    realPath: string;
+    /** Display name. */
+    title: string;
+}
+/** Permission RPC body from the Happy App. */
+export interface PermissionRpc {
+    id: string;
+    approved: boolean;
+    /** Happy Allow-always; remembered in this process only. */
+    decision?: string;
+    updatedInput?: {
+        answers?: Record<string, string>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@sjhmars/happy-bridge",
+  "version": "0.1.0",
+  "description": "Pair an already-running dsh web/desktop client with Happy App so the phone remote-controls the same harness sessions",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "disclosure": {
+    "cloud": true,
+    "network": [
+      "api.cluster-fluster.com"
+    ],
+    "offlineMode": false,
+    "apiKeys": [],
+    "permissions": [
+      "file-system:credentials",
+      "network:happy-relay"
+    ],
+    "jurisdiction": [],
+    "retention": "credentials"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sjhmars/dsh-plugins.git",
+    "directory": "plugins/happy-bridge"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=0.1.0-rc.5",
+    "@deepseek-ai/schemastery": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-agent": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-attachment": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-connection": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-locale": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-runtime": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-client-ui-slots": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-commands": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-invariants": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-llm": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-permission-presets": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-session": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-skill": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-user-approval": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-user-questions": ">=0.1.0-rc.5",
+    "@deepseek-ai/dsh-workspace": ">=0.1.0-rc.5",
+    "react": "^18.2.0"
+  },
+  "dependencies": {
+    "@paralleldrive/cuid2": "^2.2.2",
+    "@slopus/happy-wire": "^0.1.0",
+    "qrcode": "^1.5.4",
+    "socket.io-client": "^4.8.1",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "@types/qrcode": "^1.5.5",
+    "@types/react": "~18.3.31",
+    "lightningcss": "^1.32.0",
+    "react": "^18.3.1",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsdown -c tsdown.config.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-strip-types --test tests/*.test.ts"
+  }
+}