@sjhmars/happy-bridge 0.1.0

package/lib/invariant.js

@@ -0,0 +1,15 @@
+//#region lib/types/invariant.js
+/** Package invariant companion for `@sjhmars/happy-bridge`. */
+const PACKAGE_NAME = "@sjhmars/happy-bridge";
+const name = "happy-bridge-invariant";
+const inject = ["invariants"];
+/** No runtime invariant: Happy relay I/O is an external event stream this package does not own. */
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Host context carrying the invariant registry.
+* @returns the registration disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/archive-sync.d.ts

@@ -0,0 +1,38 @@
+/** Hide/show a harness session in the sidebar archive set without a Host unarchive RPC. */
+import { SessionId } from '@deepseek-ai/dsh-session';
+/** `workspaceRegistry` fields this plugin uses for archive sync. */
+export interface ArchiveRegistry {
+    readonly archivedSessionIds: readonly SessionId[];
+    archiveSession(sessionId: SessionId): Promise<void>;
+}
+/**
+ * Ids that entered or left the archive set.
+ * @param previous - last observed set.
+ * @param next - current `archivedSessionIds`.
+ */
+export declare function archiveSetDiff(previous: ReadonlySet<string>, next: ReadonlySet<string>): {
+    hidden: string[];
+    shown: string[];
+};
+/**
+ * Keep Happy online when the row is still in the unarchived web sidebar.
+ * Opening an offline phone row does not start a heartbeat by itself.
+ * @param parked - plugin park flag.
+ * @param liveOnWeb - id is in the unarchived web sidebar.
+ */
+export declare function phoneParkAction(parked: boolean, liveOnWeb: boolean): 'park' | 'unpark' | 'keep';
+/**
+ * Archive on the Host (public API). Idempotent when already archived.
+ * @param registry - `ctx.workspaceRegistry`, if the profile loaded it.
+ * @param sessionId - harness session id.
+ */
+export declare function hideOnHarness(registry: ArchiveRegistry | undefined, sessionId: string): Promise<void>;
+/**
+ * Take one id out of the Host archive set so grouping surfaces show it again
+ * in its kept `sessionIds` slot. Uses the registry write chain; does not add
+ * a Harness API.
+ * @param registry - `ctx.workspaceRegistry`, if the profile loaded it.
+ * @param sessionId - harness session id.
+ */
+export declare function revealOnHarness(registry: ArchiveRegistry | undefined, sessionId: string): Promise<void>;
+//# sourceMappingURL=archive-sync.d.ts.map

package/lib/types/attachments.d.ts

@@ -0,0 +1,19 @@
+/** Phone file events: sniff image bytes and split them from other attachments. */
+import type { EncodedImageAttachment, ImageMediaType } from '@deepseek-ai/dsh-attachment/types';
+import type { PendingFile } from './types.ts';
+/**
+ * Detect a DSH image media type from magic bytes, then declared MIME, then filename.
+ * @param file - decrypted Happy attachment.
+ * @returns a version-one image media type, or `undefined` for other files.
+ */
+export declare function sniffImageMime(file: PendingFile): ImageMediaType | undefined;
+/**
+ * Split decrypted Happy files into DSH image uploads and leftover binaries.
+ * @param files - drained phone attachments in arrival order.
+ * @returns encoded images plus non-image files.
+ */
+export declare function splitPendingFiles(files: readonly PendingFile[]): {
+    encoded: EncodedImageAttachment[];
+    extras: PendingFile[];
+};
+//# sourceMappingURL=attachments.d.ts.map

package/lib/types/bridge.d.ts

@@ -0,0 +1,227 @@
+/** Host orchestrator: pair, mirror sessions, map chat/approvals/questions onto Happy. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config, PairingStatus } from './types.ts';
+/**
+ * Live Happy bridge for one Host process.
+ */
+export declare class HappyBridge {
+    private readonly ctx;
+    private config;
+    private readonly log;
+    private credentials;
+    private pairing;
+    private machine;
+    private readonly links;
+    private readonly happyToDsh;
+    private readonly models;
+    /** Last model/effort we wrote to Happy, so the metadata echo is not a phone pick. */
+    private readonly lastPublished;
+    /** Count of in-flight phone-originated Host `selectModel` calls. */
+    private hostSelectFromPhone;
+    /** Per-agent selection installed on phone wake / spawn, matching Host `selectionFor`. */
+    private readonly selections;
+    /** In-flight phone wakes, so two inbound texts do not double-resume. */
+    private readonly waking;
+    /** Phone stop-session / archive: do not recreate these Happy rows. */
+    private readonly dismissed;
+    /** Phone New (spawn) blanks stay linked; web placeholders do not. */
+    private readonly phoneSpawned;
+    /** Last Host archive set, so web archive/restore can park or unpark Happy. */
+    private lastArchivedIds;
+    /** Serialize phone text so two messages cannot split one attachment batch. */
+    private readonly inboundTail;
+    private error;
+    private running;
+    private scanTimer;
+    /**
+     * @param ctx - Host context.
+     * @param config - resolved plugin config.
+     * @param log - logger.
+     */
+    constructor(ctx: Context, config: Config, log: (message: string) => void);
+    /** Replace config after a settings write that keeps the same relay. */
+    setConfig(config: Config): void;
+    /**
+     * Apply a settings write in place when the Happy relay identity is unchanged.
+     * Grant changes take effect immediately; URL / credential-dir / enabled
+     * changes must rebuild.
+     * @param next - resolved settings section.
+     * @returns true when the live bridge kept running.
+     */
+    acceptSettings(next: Config): boolean;
+    /** Snapshot for the settings card. */
+    status(): PairingStatus;
+    /** Load credentials, connect machine, mirror live root agents. */
+    start(): Promise<void>;
+    /** Tear down sockets. Web UI keeps running. */
+    dispose(): void;
+    /** Start or resume pairing. */
+    beginPairing(): Promise<void>;
+    /**
+     * Drop the current Happy login and show a new QR. Keeps the same machine id
+     * so already-mirrored sessions stay on this Host after the phone scans again.
+     */
+    rePair(): Promise<void>;
+    /** Disconnect Happy without killing dsh web. */
+    disconnect(): Promise<void>;
+    private connectCloud;
+    private installHooks;
+    private isHarnessArchived;
+    private seedArchiveSet;
+    private reconcileArchiveSet;
+    private listedUnarchived;
+    private syncMirrors;
+    private ensureMirror;
+    private dropLink;
+    /**
+     * Remove a web New Session placeholder from Happy without remembering a
+     * dismiss: the first real turn should remirror it.
+     */
+    private abandonBlankMirror;
+    /**
+     * Drop Happy rows for dismissed or blank dsh tags. The App archive button
+     * only sets inactive; without this sweep a keepalive ghost stays in the list.
+     */
+    private sweepHappyGhosts;
+    private sessionIsBlank;
+    private linkEvents;
+    private requireAgent;
+    /** Bind a live agent onto an existing Happy socket without reminting it. */
+    private attachAgent;
+    /** Copy log events newer than {@link Link.lastForwardedSeq} onto Happy. */
+    private drainNewEvents;
+    /**
+     * Live agent for this Happy socket, resuming the persisted session when the
+     * web has never opened it. Same preset the Host would mount on a web open.
+     */
+    private ensureAgent;
+    private wakeAgent;
+    private resumeSession;
+    /**
+     * Resume/create composition matching Host `composeAgent`: install model
+     * selection, then mount the preset when a roster exists.
+     * @param presetHint - logged or requested preset id; omitted uses the roster default.
+     */
+    private composeAgentSetup;
+    /**
+     * Same lazy selection Host `selectionFor` installs: remembered pick, else
+     * the session's last `request/header`, else `agentDefaultModel`. A missing
+     * thinking level keeps the web picker's effort when it is the same model.
+     * Unlike Host `installModelSelection`, an absent effort does not clear
+     * inherited thinking.
+     */
+    private installWakeSelection;
+    /**
+     * Pin provider/model for a phone-woken agent without wiping thinking when
+     * the selection names no effort.
+     */
+    private bindWakeSelection;
+    /** Host default model, when the web profile mounted `agentDefaultModel`. */
+    private defaultModelSelection;
+    /** Registered workspace for this session, or `undefined` when it is not in the sidebar. */
+    private workspaceFor;
+    private loadStored;
+    private shouldSkip;
+    private workspaces;
+    private mirrorAgent;
+    private mirrorDormant;
+    private unmapHappy;
+    /**
+     * Phone archive: park a real conversation so a later send resumes it.
+     * Blank placeholders are forgotten and not remirrored.
+     */
+    private onPhoneArchive;
+    private handlePhoneArchive;
+    /**
+     * Park a real conversation on Happy. `hideHost` archives the same row on
+     * the web (phone archive). Web-initiated archive only parks Happy.
+     */
+    private parkPhoneSession;
+    private onPhoneRestore;
+    private undismiss;
+    /**
+     * Put this Happy row back online. Opening an offline chat on the phone
+     * does not start heartbeats; the web sidebar still showing the row, a
+     * phone send, or Happy's resume RPC all come through here.
+     * @param refreshCatalog - republish metadata (web open / phone resume).
+     */
+    private wakePhone;
+    private unpark;
+    /**
+     * Honor a phone archive/delete: stop keepalive, drop the Happy row, and do
+     * not remirror this harness session until the plugin is unpaired.
+     */
+    private forgetPhoneSession;
+    /**
+     * Happy App continues an offline row with `resume-happy-session`.
+     * Reuse the existing harness session; do not mint a new one.
+     * @param happySessionId - Happy cloud session id from the App.
+     */
+    private resumeHappySession;
+    private spawn;
+    private applySpawnMeta;
+    private queueInbound;
+    private onInbound;
+    private applyMessageMeta;
+    private applyPhoneCatalog;
+    private applyModel;
+    private applyEffort;
+    /** Keep the last Host pick so Happy metadata can echo the web composer. */
+    private rememberModel;
+    /**
+     * Write the web picker's Host selection (`session.selectModel`) so the
+     * composer model seat reloads without a click on the computer.
+     */
+    private syncHostSelection;
+    /**
+     * After the web picker (or any Host caller) lands a selection, publish it
+     * to Happy. Phone-originated calls set {@link hostSelectFromPhone} and push themselves.
+     */
+    private afterHostSelect;
+    /**
+     * Put a concrete reasoningEffort on a phone-spawned / phone-woken agent
+     * before the first LLM request, matching the effort Happy metadata advertises.
+     */
+    private ensurePinnedEffort;
+    private applyPermission;
+    /**
+     * Queue the phone text as a user followup. The App already shows the typed
+     * bubble; do not send a second user envelope. Images ride as DSH
+     * attachments; other files land under `happy-inbox` for Harness `read`.
+     */
+    private followup;
+    /**
+     * Claim every download started before this text, wait, keep the successes.
+     * Swap-then-await so a later file event cannot join this batch.
+     */
+    private drainPhoneFiles;
+    private downloadPhoneFile;
+    private onSessionEvent;
+    private onApproval;
+    private onAsk;
+    /**
+     * Happy App `sessionAbort` for Rig: empty params, RPC name `abort`.
+     * Watch grant keeps the button from doing work; chat and above cancel the turn.
+     */
+    private onPhoneAbort;
+    private onPermission;
+    private pushRequests;
+    private clearRequest;
+    private pushMetadata;
+    private pushAllMetadata;
+    private queueOutboundUser;
+    /**
+     * Upload web-side images with Happy CLI's encrypt-then-request-upload path,
+     * then emit file events and any remaining user text.
+     */
+    private pushUserToPhone;
+    private uploadOutboundImage;
+    private replayHistory;
+    private emitHistory;
+    private pulseThink;
+    private flushReasoning;
+    private finishThink;
+    private startTool;
+    private currentModel;
+}
+//# sourceMappingURL=bridge.d.ts.map

package/lib/types/bytes.d.ts

@@ -0,0 +1,16 @@
+/** Base64 helpers matching Happy CLI `encodeBase64` / `decodeBase64`. */
+/**
+ * Encode bytes as standard or URL-safe base64.
+ * @param buffer - bytes to encode.
+ * @param variant - `base64` (default) or `base64url` without padding.
+ * @returns encoded string.
+ */
+export declare function encodeBase64(buffer: Uint8Array, variant?: 'base64' | 'base64url'): string;
+/**
+ * Decode a standard or URL-safe base64 string.
+ * @param value - encoded string.
+ * @param variant - encoding used by `value`.
+ * @returns decoded bytes.
+ */
+export declare function decodeBase64(value: string, variant?: 'base64' | 'base64url'): Uint8Array;
+//# sourceMappingURL=bytes.d.ts.map

package/lib/types/catalogs.d.ts

@@ -0,0 +1,119 @@
+/** Build Happy session metadata catalogs from the live harness context. */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { RemoteGrant } from './types.ts';
+/** One model row Happy's Rig picker understands (slash `code` plus provider/id). */
+export interface HappyModelRow {
+    code: string;
+    value: string;
+    description?: string;
+    id: string;
+    name: string;
+    providerId: string;
+    providerKind: 'custom';
+    providerName: string;
+    thinkingLevels: string[];
+    defaultThinkingLevel?: string;
+    effortOptions: {
+        code: string;
+        value: string;
+    }[];
+}
+/** Current Host pick published so the phone can echo model + effort. */
+export interface HappySelection {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** Plain metadata object written into the encrypted Happy session metadata field. */
+export interface SessionMetadata {
+    path: string;
+    host: string;
+    homeDir: string;
+    version: string;
+    name: string;
+    summary: {
+        text: string;
+        updatedAt: number;
+    };
+    os: string;
+    machineId: string;
+    flavor: 'acp';
+    startedBy: 'terminal';
+    lifecycleState: string;
+    lifecycleStateSince: number;
+    happyHomeDir: string;
+    happyLibDir: string;
+    happyToolsDir: string;
+    slashCommands: string[];
+    skills: string[];
+    models: HappyModelRow[];
+    operatingModes: {
+        code: string;
+        value: string;
+        description: string;
+    }[];
+    currentModelCode?: string;
+    currentModelProviderId?: string;
+    modelMode?: string;
+    currentOperatingModeCode?: string;
+    thoughtLevels?: {
+        code: string;
+        value: string;
+    }[];
+    currentThoughtLevelCode?: string;
+    effortLevel?: string;
+    reasoning?: {
+        current: string | null;
+        levels: string[];
+    };
+    client: {
+        id: 'rig';
+        name: string;
+        version: string;
+    };
+    rigMetadataVersion: 1;
+    capabilities: {
+        abort: true;
+        attachments: {
+            enabled: true;
+            maxBytes: number;
+            mediaTypes: string[];
+        };
+        files: {
+            browse: false;
+            read: false;
+            search: false;
+            write: false;
+        };
+        modelSelection: true;
+        reasoningSelection: true;
+        permissionModeSelection: true;
+        resume: false;
+        rpcMethods: string[];
+        shell: false;
+        steering: false;
+    };
+    tools?: string[];
+}
+/**
+ * Snapshot catalogs for one session, live or still sitting in the sidebar.
+ * @param ctx - Host context.
+ * @param source - real cwd for skills, POSIX `happyPath` for the App list, log, and optional live agent.
+ * @param machineId - Happy machine id.
+ * @param title - session display name.
+ * @param selection - current provider/model/effort, when known.
+ * @param grant - unused in metadata; kept for future capability bits.
+ * @returns plaintext metadata.
+ */
+export declare function buildSessionMetadata(ctx: Context, source: {
+    cwd: string;
+    /** POSIX path under {@link VIRTUAL_HOME}; Happy groups the list by this. */
+    happyPath: string;
+    events: readonly {
+        type: string;
+        data: unknown;
+    }[];
+    agent?: Agent;
+}, machineId: string, title: string, selection: HappySelection | undefined, _grant: RemoteGrant): Promise<SessionMetadata>;
+//# sourceMappingURL=catalogs.d.ts.map

package/lib/types/client/HappyBridgeCard.d.ts

@@ -0,0 +1,41 @@
+/** Settings → Plugins card: pairing QR, copy links, remote grant. */
+import { type ReactNode } from 'react';
+import type { SettingsScopeSnapshot } from '@deepseek-ai/dsh-client-runtime/client';
+import type { InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PairingStatus, RemoteGrant } from '../types.ts';
+import { NS } from './locales.ts';
+/** Fields this card reads from the `happy-bridge` settings namespace. */
+export interface HappyBridgeSettings {
+    enabled?: boolean;
+    remoteGrant?: RemoteGrant;
+}
+/** Injected Host RPC + settings writes. Snapshot rides `hooks.happySettings`. */
+export interface HappyBridgeInjected {
+    /** Poll pairing status (includes QR data URL). */
+    getStatus: () => Promise<PairingStatus>;
+    /** Start or resume pairing. */
+    startPairing: () => Promise<PairingStatus>;
+    /** Disconnect Happy; the web UI stays up. */
+    disconnect: () => Promise<PairingStatus>;
+    /** Drop the current login and show a new QR. */
+    rePair: () => Promise<PairingStatus>;
+    /** Persist the remote-grant field. */
+    setGrant: (grant: RemoteGrant) => Promise<void>;
+    /** Persist the enabled field. */
+    setEnabled: (enabled: boolean) => Promise<void>;
+    hooks: {
+        /** Live settings snapshot for this namespace. */
+        happySettings: {
+            getSnapshot(): SettingsScopeSnapshot<HappyBridgeSettings>;
+            subscribe(fn: () => void): () => void;
+        };
+    };
+}
+/** Card props: locale seat plus injected RPC. */
+export type HappyBridgeCardProps = PropsLocale<typeof NS> & InjectFace<HappyBridgeInjected>;
+/**
+ * Render the Happy remote plugin card.
+ * @param props - locale + injected Host RPC.
+ */
+export declare function HappyBridgeCard(props: HappyBridgeCardProps): ReactNode;
+//# sourceMappingURL=HappyBridgeCard.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,16 @@
+/** Browser half: Happy remote card on Settings → Plugins. */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type HappyBridgeKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        'happy-bridge': HappyBridgeKey;
+    }
+}
+/** Required client services. */
+export declare const inject: string[];
+/**
+ * Register the Happy remote card under the `happy-bridge` settings namespace.
+ * @param ctx - browser plugin context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,34 @@
+/** Locale namespace owned by the Happy remote settings card. */
+export declare const NS = "happy-bridge";
+/** Simplified-Chinese copy. */
+export declare const zh: {
+    readonly title: "Happy 远程";
+    readonly description: "用手机 Happy App 遥控已经在跑的对话。";
+    readonly expand: "展开";
+    readonly collapse: "收起";
+    readonly 'status.unpaired': "还没配对";
+    readonly 'status.pairing': "等待手机扫码…请在 Happy App 里扫，不要用系统相机。";
+    readonly 'status.paired': "已连接到 Happy";
+    readonly 'status.linked': "已接通对话";
+    readonly 'qr.alt': "Happy 配对二维码";
+    readonly 'copy.mobile': "复制手机链接";
+    readonly 'copy.web': "复制网页链接";
+    readonly copied: "已复制";
+    readonly start: "开始配对";
+    readonly repair: "重新配对";
+    readonly disconnect: "断开";
+    readonly grant: "手机能管多深";
+    readonly 'grant.watch': "只看";
+    readonly 'grant.chat': "能聊";
+    readonly 'grant.approve': "能批";
+    readonly 'grant.full': "完整";
+    readonly 'grant.hint': "改成「完整」后，手机换模型和思考强度会同步到电脑。电脑上换也会同步到手机。";
+    readonly readOnly: "这份设置现在不能改。";
+    readonly enabled: "启用";
+    readonly error: "出错";
+};
+/** English copy. */
+export declare const en: Record<keyof typeof zh, string>;
+/** Stable locale keys. */
+export type HappyBridgeKey = keyof typeof zh;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/credentials.d.ts

@@ -0,0 +1,59 @@
+/** Load and store Happy credentials. Prefer `~/.happy/access.key`, else plugin dir. */
+import type { Credentials } from './types.ts';
+/**
+ * Resolve the plugin credential directory.
+ * @param configured - Config.credentialDir; empty means the default under home.
+ * @returns absolute directory path.
+ */
+export declare function resolveCredentialDir(configured: string): string;
+/**
+ * Load credentials: Happy CLI file first, then this plugin's file.
+ * @param credentialDir - plugin directory.
+ * @returns credentials, or `undefined` when nothing usable is on disk.
+ */
+export declare function loadCredentials(credentialDir: string): Promise<Credentials | undefined>;
+/**
+ * Persist credentials in the plugin directory. Does not overwrite `~/.happy/access.key`.
+ * @param credentialDir - plugin directory.
+ * @param credentials - token + encryption + machineId.
+ */
+export declare function saveCredentials(credentialDir: string, credentials: Credentials): Promise<void>;
+/**
+ * Mark the plugin disconnected without deleting Happy CLI credentials.
+ * Clears phone-dismissed ids so a later pair remirrors those sessions.
+ * @param credentialDir - plugin directory.
+ * @param machineId - last known machine id to keep stable.
+ */
+export declare function markDisconnected(credentialDir: string, machineId?: string): Promise<void>;
+/**
+ * Clear the local disconnected flag so existing credentials can be reused.
+ * @param credentialDir - plugin directory.
+ * @param machineId - machine id to keep.
+ */
+export declare function markConnected(credentialDir: string, machineId: string): Promise<void>;
+/**
+ * Last stored machine id, even when locally disconnected.
+ * @param credentialDir - plugin directory.
+ * @returns machine id, or `undefined`.
+ */
+export declare function peekMachineId(credentialDir: string): Promise<string | undefined>;
+/**
+ * Session ids the phone asked to stop mirroring. stop-session / archive
+ * persist here so a later scan does not recreate the Happy row.
+ * @param credentialDir - plugin directory.
+ * @returns harness session ids, possibly empty.
+ */
+export declare function loadDismissed(credentialDir: string): Promise<string[]>;
+/**
+ * Forget a previously dismissed harness session so it can remirror.
+ * @param credentialDir - plugin directory.
+ * @param dshId - harness session id.
+ */
+export declare function removeDismissed(credentialDir: string, dshId: string): Promise<void>;
+/**
+ * Remember that the phone dismissed this harness session.
+ * @param credentialDir - plugin directory.
+ * @param dshId - harness session id.
+ */
+export declare function addDismissed(credentialDir: string, dshId: string): Promise<void>;
+//# sourceMappingURL=credentials.d.ts.map