@sjhmars/happy-bridge 0.1.0

package/lib/types/encryption.d.ts

@@ -0,0 +1,104 @@
+/** Happy content encryption: legacy NaCl secretbox or AES-256-GCM dataKey. */
+import { decodeBase64, encodeBase64 } from './bytes.ts';
+import type { Credentials, EncryptionVariant } from './types.ts';
+/** Content key used for one session or machine. */
+export interface CryptoContext {
+    /** AES-GCM or secretbox key. */
+    key: Uint8Array;
+    /** Algorithm selected from the account credentials. */
+    variant: EncryptionVariant;
+}
+/**
+ * Encrypt a JSON value the way Happy CLI `encrypt()` does.
+ * @param ctx - session or machine crypto.
+ * @param data - JSON-serializable plaintext.
+ * @returns nonce+ciphertext bytes.
+ */
+export declare function encryptJson(ctx: CryptoContext, data: unknown): Uint8Array;
+/**
+ * Decrypt a Happy ciphertext into JSON.
+ * @param ctx - matching crypto.
+ * @param data - nonce+ciphertext bytes.
+ * @returns plaintext or `null` when the box does not open.
+ */
+export declare function decryptJson(ctx: CryptoContext, data: Uint8Array): unknown;
+/**
+ * Encrypt JSON and return the on-wire base64 string.
+ * @param ctx - session or machine crypto.
+ * @param data - JSON-serializable plaintext.
+ * @returns base64 ciphertext.
+ */
+export declare function encryptB64(ctx: CryptoContext, data: unknown): string;
+/**
+ * Decode base64 then decrypt JSON.
+ * @param ctx - matching crypto.
+ * @param value - base64 ciphertext.
+ * @returns plaintext or `null`.
+ */
+export declare function decryptB64(ctx: CryptoContext, value: string): unknown;
+/**
+ * Open the pairing `response` blob (ephemeral-box bundle).
+ * @param encryptedBundle - ephPublicKey + nonce + ciphertext.
+ * @param recipientSecretKey - our box secret key.
+ * @returns 32-byte shared secret, or versioned dataKey payload, or `null`.
+ */
+export declare function decryptWithEphemeralKey(encryptedBundle: Uint8Array, recipientSecretKey: Uint8Array): Uint8Array | null;
+/**
+ * Wrap a data-encryption key for the account public key.
+ * @param dataKey - 32-byte DEK.
+ * @param recipientPublicKey - account box public key.
+ * @returns versioned bundle Happy stores as `dataEncryptionKey`.
+ */
+export declare function wrapDataEncryptionKey(dataKey: Uint8Array, recipientPublicKey: Uint8Array): Uint8Array;
+/**
+ * Content crypto for a newly created Happy session.
+ * @param credentials - account credentials.
+ * @returns session key plus optional wrapped DEK for POST /v1/sessions.
+ */
+export declare function sessionCrypto(credentials: Credentials): {
+    ctx: CryptoContext;
+    dataEncryptionKey: Uint8Array | undefined;
+};
+/**
+ * Content crypto for the machine entity (uses `machineKey` on dataKey accounts).
+ * @param credentials - account credentials.
+ * @returns machine key plus optional wrapped DEK.
+ */
+export declare function machineCrypto(credentials: Credentials): {
+    ctx: CryptoContext;
+    dataEncryptionKey: Uint8Array | undefined;
+};
+/**
+ * Encrypt a binary blob with NaCl crypto_secretbox (XSalsa20-Poly1305).
+ * Wire format: nonce (24 bytes) then ciphertext plus 16-byte auth tag.
+ * Matches Happy App/CLI `encryptBlob`.
+ * @param data - plaintext bytes.
+ * @param key - 32-byte blob key from {@link deriveBlobKey}.
+ * @returns nonce + ciphertext.
+ */
+export declare function encryptBlob(data: Uint8Array, key: Uint8Array): Uint8Array;
+/**
+ * Decrypt a binary blob encrypted with NaCl crypto_secretbox.
+ * @param bundle - nonce + ciphertext from {@link encryptBlob}.
+ * @param key - matching 32-byte blob key.
+ * @returns plaintext bytes, or `null` when the box does not open.
+ */
+export declare function decryptBlob(bundle: Uint8Array, key: Uint8Array): Uint8Array | null;
+/**
+ * Session blob key for Happy file attachments.
+ * Legacy accounts: `deriveKey(secret, 'Happy Blobs', ['master'])`.
+ * DataKey accounts: `deriveKey(dataKey, 'Happy Blobs', ['session'])`.
+ * @param ctx - the same session crypto used for JSON envelopes.
+ * @returns 32-byte secretbox key.
+ */
+export declare function deriveBlobKey(ctx: CryptoContext): Promise<Uint8Array>;
+/**
+ * HMAC-SHA512 hierarchical key tree used by Happy CLI `deriveKey`.
+ * @param master - root secret.
+ * @param usage - domain string such as `Happy Blobs`.
+ * @param path - child indexes such as `['session']` or `['master']`.
+ * @returns 32-byte derived key.
+ */
+export declare function deriveKey(master: Uint8Array, usage: string, path: readonly string[]): Promise<Uint8Array>;
+export { encodeBase64, decodeBase64 };
+//# sourceMappingURL=encryption.d.ts.map

package/lib/types/grant.d.ts

@@ -0,0 +1,87 @@
+/** Remote-grant checks: what the phone is allowed to do. */
+import type { Config, RemoteGrant } from './types.ts';
+/**
+ * Whether `actual` is at least as deep as `needed`.
+ * @param actual - currently selected grant.
+ * @param needed - minimum required grant.
+ * @returns true when the phone may perform the action.
+ */
+export declare function grantAtLeast(actual: RemoteGrant, needed: RemoteGrant): boolean;
+/** Claude-only permissionMode strings that must not be treated as dsh presets. */
+export declare const CLAUDE_PERMISSION_MODES: ReadonlySet<string>;
+/**
+ * Decide how inbound `meta.permissionMode` maps onto a dsh preset.
+ * @param mode - Happy message meta.permissionMode.
+ * @param dshPresets - currently advertised preset names.
+ * @returns `apply` with the preset, `ignore` for Claude-only values, or `unknown`.
+ */
+export declare function classifyPermissionMode(mode: string, dshPresets: readonly string[]): {
+    kind: 'apply';
+    preset: string;
+} | {
+    kind: 'ignore';
+} | {
+    kind: 'unknown';
+};
+/**
+ * Split a Happy `meta.model` / spawn `modelMode` code into provider and model.
+ * @param code - `provider/model`, Rig `provider:model`, or a bare model id.
+ * @returns provider (empty when bare) and model.
+ */
+export declare function splitModelCode(code: string): {
+    provider: string;
+    model: string;
+};
+/**
+ * Model code from a Happy inbound message (`meta.model` plus optional provider).
+ * @param meta - Happy message meta object.
+ * @returns `provider/model` when both are known, otherwise the raw model string.
+ */
+export declare function messageModelCode(meta: Record<string, unknown>): string | undefined;
+/**
+ * Effort from a Happy inbound message. Current App wire uses `effort`;
+ * spawn and older clients send `effortLevel`.
+ * @param meta - Happy message meta object.
+ * @returns effort id, `null` when the field is explicitly cleared, or undefined when omitted.
+ */
+export declare function messageEffort(meta: Record<string, unknown>): string | null | undefined;
+/**
+ * Whether a settings write can land on the live bridge without disposing sockets.
+ * Grant / pairOnStart changes take effect in place; URL or credential-dir
+ * changes restart the relay.
+ * @param previous - config the live bridge is using.
+ * @param next - config just resolved from settings.
+ */
+export declare function sameHappyRuntime(previous: Config, next: Config): boolean;
+/** Provider / model / effort triple the phone and Host picker share. */
+export interface ModelOverrideFields {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/**
+ * Whether two overrides name the same Host selection.
+ * @param previous - last remembered override, if any.
+ * @param next - candidate override.
+ */
+export declare function sameModelOverride(previous: ModelOverrideFields | undefined, next: ModelOverrideFields): boolean;
+/**
+ * Model and effort Happy stores on session metadata.
+ * @param meta - decrypted Happy session metadata object.
+ * @returns the current model and/or effort, or undefined when neither is set.
+ */
+export declare function catalogModelPick(meta: Record<string, unknown>): CatalogModelPick | undefined;
+/** Model and/or effort Happy wrote into session metadata. */
+export interface CatalogModelPick {
+    model?: string;
+    effort?: string | null;
+}
+/**
+ * Whether an inbound Happy catalog is the same pick we last published.
+ * Slash and colon provider/model codes compare as one pair.
+ * @param previous - last pick we wrote, if any.
+ * @param next - pick decoded from inbound metadata.
+ * @returns true when the inbound pick is our own echo.
+ */
+export declare function sameCatalogPick(previous: CatalogModelPick | undefined, next: CatalogModelPick): boolean;
+//# sourceMappingURL=grant.d.ts.map

package/lib/types/happy-version.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Version strings the Happy App compares against its minimum CLI.
+ *
+ * This is a reported compatibility tag matching npm `happy`, not this
+ * plugin's package version and not an install of the official CLI.
+ * Bump when Happy publishes a newer CLI that the App starts nagging for.
+ */
+export declare const HAPPY_CLI_VERSION = "1.2.0";
+/** Official `X-Happy-Client` / socket `happyClient` value. */
+export declare const HAPPY_CLIENT = "cli-coding-session/1.2.0";
+//# sourceMappingURL=happy-version.d.ts.map

package/lib/types/history.d.ts

@@ -0,0 +1,184 @@
+/** Fold a session label and replayable chat items from the harness log. */
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment/types';
+/** Minimal log event the history fold reads. */
+export interface HistoryEvent {
+    type: string;
+    time?: number;
+    data: unknown;
+}
+/** One Happy envelope to emit when filling an empty mirrored session. */
+export type HistoryItem = {
+    kind: 'turn-start';
+    time: number;
+} | {
+    kind: 'turn-end';
+    time: number;
+    status: 'completed' | 'failed' | 'cancelled';
+} | {
+    kind: 'user';
+    time: number;
+    text: string;
+    images: ImageAttachmentRef[];
+} | {
+    kind: 'assistant';
+    time: number;
+    text: string;
+} | {
+    kind: 'tool-start';
+    time: number;
+    call: string;
+    name: string;
+    title: string;
+    description: string;
+    args: Record<string, unknown>;
+} | {
+    kind: 'tool-end';
+    time: number;
+    call: string;
+};
+/**
+ * Happy session-list title: logged title, else first human prompt, else the
+ * same "新会话" the web sidebar uses. Never the folder name — that belongs
+ * on Happy's project-group header via `metadata.path`.
+ * @param events - session log.
+ * @returns non-empty label.
+ */
+export declare function sessionLabel(events: readonly HistoryEvent[]): string;
+/**
+ * Same blank rule as the web sidebar: no `turn/start` yet means a
+ * provisional New Session placeholder, not a conversation.
+ * @param events - session log.
+ * @returns true when the sidebar would hide this row unless it is selected.
+ */
+export declare function isBlankSession(events: readonly HistoryEvent[]): boolean;
+/**
+ * Visible user/assistant/tool turns to copy onto an empty Happy session.
+ * Plugin-injected user rows stay off the phone. Assistant chunks are skipped
+ * in favor of the committed assistant/message. Reasoning blocks become a
+ * collapsible Think card; tool-call blocks become Happy-known tool cards.
+ * @param events - session log in seq order.
+ * @returns replay items in log order.
+ */
+export declare function historyItems(events: readonly HistoryEvent[]): HistoryItem[];
+/**
+ * Visible human prompt from a `user/message` log event.
+ * Plugin injects and tool-result rows return empty.
+ * @param event - one session log event.
+ * @returns trimmed concatenated text blocks, or `''`.
+ */
+export declare function visibleUserText(event: HistoryEvent): string;
+/**
+ * Image blocks from a human `user/message`. Plugin injects stay off the phone.
+ * @param event - one session log event.
+ * @returns attachment refs in content order.
+ */
+export declare function visibleUserImages(event: HistoryEvent): ImageAttachmentRef[];
+/** One committed assistant content block, already folded for Happy. */
+export type AssistantPart = {
+    kind: 'thinking';
+    text: string;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'tool';
+    call: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+/**
+ * Walk committed assistant content in log order: reasoning, visible text, tool calls.
+ * @param content - `assistant/message` content array.
+ * @returns Happy-ready parts, skipping empty text.
+ */
+export declare function assistantParts(content: unknown): AssistantPart[];
+/**
+ * Happy App hides `thinking: true` text and tools named `think` /
+ * `CodexReasoning` / `GeminiReasoning`. Names starting `mcp__` become a
+ * one-line MCP row with no body. `Note` is unknown to that table, so it
+ * stays a tappable card; full text rides in `args.text`.
+ */
+export declare const THINK_TOOL_NAME = "Note";
+/** One Happy tool-call-start payload. */
+export interface HappyToolCard {
+    name: string;
+    title: string;
+    description: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Collapsed Think row label. Happy compact rows show `description`.
+ * @param text - accumulated or committed reasoning.
+ * @returns `Think` or `Think ·` plus the first line.
+ */
+export declare function thinkLabel(text: string): string;
+/**
+ * Think card for a finished reasoning block. Full text rides in `args`
+ * so a tap opens the detail page; the row itself stays one line.
+ * @param text - committed reasoning.
+ */
+export declare function thinkCard(text: string): HappyToolCard;
+/**
+ * Map a dsh tool onto a Happy card. Compact rows only paint `description`,
+ * so that field is `Grep · pattern` (tool name plus the web summary).
+ * `name` stays PascalCase so Happy can still pick icons.
+ * @param name - registered dsh tool name.
+ * @param args - parsed tool arguments.
+ */
+export declare function happyTool(name: string, args: Record<string, unknown>): HappyToolCard;
+/**
+ * Web-style one-line label used in tests: `Grep · pattern`.
+ * @param name - registered tool name.
+ * @param args - parsed tool arguments.
+ */
+export declare function toolTitle(name: string, args: Record<string, unknown>): string;
+/**
+ * Preset the session actually runs: last `agent-preset/selected`, else the
+ * creation-header value. Phone wake must mount this same composition, not the
+ * header alone — a blank session may have switched before its first turn.
+ * @param events - session log, oldest first.
+ * @param headerAgentPreset - `header.agentPreset` from inspect.
+ */
+export declare function resolveSessionPreset(events: readonly HistoryEvent[], headerAgentPreset?: string): string | undefined;
+/** Provider, model, and optional effort used to start a phone-woken turn. */
+export interface WakeModelSelection {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/**
+ * Same precedence Host `selectionFor` uses: first usable provider/model
+ * wins; a later candidate may only fill a missing thinking level when it is
+ * that same model. Empty provider/model pairs are skipped.
+ * @param primary - process pick, else `session.requestHeader()?.config`.
+ * @param fallbacks - remaining sources, usually the log then `agentDefaultModel`.
+ */
+export declare function wakeModelSelection(primary: WakeModelSelection | undefined, ...fallbacks: Array<WakeModelSelection | undefined>): WakeModelSelection | undefined;
+/**
+ * Effort the first phone-spawn / phone-wake request should send.
+ * Current pick wins; otherwise a preferred (web) value or the model's
+ * advertised default, but only when the model lists that id.
+ * @param currentEffort - already chosen effort, if any.
+ * @param preferred - web picker effort to reuse when the model accepts it.
+ * @param modelDefault - `resolveModelInfo().reasoning.defaultEffort`.
+ * @param supported - advertised effort ids; empty/absent means any string is accepted.
+ */
+export declare function pinWakeEffort(currentEffort: string | undefined, preferred: string | undefined, modelDefault: string | undefined, supported: readonly string[] | undefined): string | undefined;
+/**
+ * Sidebar sessions that should stay linked on the phone: every workspace
+ * membership except the registry-global archive set.
+ * @param workspaces - `workspaceRegistry.list()` projections.
+ * @param archived - `workspaceRegistry.archivedSessionIds`.
+ */
+export declare function unarchivedSessionIds(workspaces: readonly {
+    sessionIds: readonly string[];
+}[], archived: readonly string[]): string[];
+/**
+ * Sidebar ids still eligible for a Happy socket: not archived on the web,
+ * and not dismissed from the phone.
+ * @param wanted - {@link unarchivedSessionIds} result.
+ * @param dismissed - phone stop-session / archive ids.
+ * @returns ids that should have a live Happy socket.
+ */
+export declare function mirrorTargets(wanted: readonly string[], dismissed: ReadonlySet<string>): string[];
+//# sourceMappingURL=history.d.ts.map

package/lib/types/http.d.ts

@@ -0,0 +1,108 @@
+/** Happy HTTP helpers: auth, sessions, machines, attachments. */
+import type { CryptoContext } from './encryption.ts';
+/**
+ * JSON POST/GET against the Happy API with the CLI client header.
+ * @param serverUrl - API origin.
+ * @param path - path beginning with `/`.
+ * @param init - method, token, JSON body.
+ * @returns parsed JSON, or throws with status text.
+ */
+export declare function happyFetch(serverUrl: string, path: string, init: {
+    method?: string;
+    token?: string;
+    body?: unknown;
+}): Promise<unknown>;
+/**
+ * Create or load a Happy session by tag.
+ * @param serverUrl - API origin.
+ * @param token - bearer token.
+ * @param tag - stable tag such as `dsh:<sessionId>`.
+ * @param crypto - content encryption for this session.
+ * @param metadata - plaintext metadata.
+ * @param agentState - plaintext agent state.
+ * @param dataEncryptionKey - wrapped DEK bytes when using dataKey.
+ * @returns Happy session id and versions.
+ */
+export declare function createOrLoadSession(input: {
+    serverUrl: string;
+    token: string;
+    tag: string;
+    crypto: CryptoContext;
+    metadata: unknown;
+    agentState: unknown;
+    dataEncryptionKey?: Uint8Array;
+}): Promise<{
+    id: string;
+    seq: number;
+    metadataVersion: number;
+    agentStateVersion: number;
+}>;
+/**
+ * Register or update the machine entity so the App can spawn onto this Host.
+ * @param input - machine id, encrypted metadata, optional daemon state.
+ * @returns versions from the server.
+ */
+export declare function createOrLoadMachine(input: {
+    serverUrl: string;
+    token: string;
+    machineId: string;
+    crypto: CryptoContext;
+    metadata: unknown;
+    daemonState: unknown;
+    dataEncryptionKey?: Uint8Array;
+}): Promise<{
+    metadataVersion: number;
+    daemonStateVersion: number;
+}>;
+/**
+ * Upload an already-encrypted attachment the way Happy CLI `uploadLocalImageAttachmentEnvelope` does:
+ * POST `/v1/sessions/:id/attachments/request-upload` `{ filename, size }` → `{ ref, uploadUrl, method }`
+ * then PUT octet-stream or POST multipart to `uploadUrl`.
+ * Presigned URLs must not receive extra headers; server-local URLs need Bearer.
+ * @param serverUrl - API origin.
+ * @param token - bearer token.
+ * @param sessionId - Happy session id that owns the blob.
+ * @param filename - display name sent to request-upload.
+ * @param encrypted - nonce+ciphertext from `encryptBlob`.
+ * @returns Happy `ref` to put on a user `file` event.
+ */
+export declare function uploadEncryptedAttachment(serverUrl: string, token: string, sessionId: string, filename: string, encrypted: Uint8Array): Promise<string>;
+/**
+ * Download an encrypted attachment blob the way Happy CLI does:
+ * POST `/v1/sessions/:id/attachments/request-download` → `{ downloadUrl }` → GET bytes.
+ * S3 presigned URLs must not receive extra headers; server-local URLs need Bearer.
+ * @param serverUrl - API origin.
+ * @param token - bearer token.
+ * @param sessionId - Happy session id that owns the blob.
+ * @param ref - file event `ref`.
+ * @returns encrypted nonce+ciphertext bytes.
+ */
+export declare function downloadEncryptedAttachment(serverUrl: string, token: string, sessionId: string, ref: string): Promise<Uint8Array>;
+/**
+ * Mark a Happy session inactive without deleting it. Accidental archive of a
+ * real conversation can still receive a later phone send.
+ * @param serverUrl - API origin.
+ * @param token - bearer token.
+ * @param sessionId - Happy session id.
+ */
+export declare function archiveHappySession(serverUrl: string, token: string, sessionId: string): Promise<void>;
+/**
+ * Remove a Happy cloud session so the App can drop it from the list.
+ * Already-gone ids are ignored.
+ * @param serverUrl - API origin.
+ * @param token - bearer token.
+ * @param sessionId - Happy session id.
+ */
+export declare function deleteHappySession(serverUrl: string, token: string, sessionId: string): Promise<void>;
+/**
+ * Happy cloud sessions this token can see. Used to drop blank ghosts the
+ * App can only archive, not delete.
+ * @param serverUrl - API origin.
+ * @param token - bearer token.
+ * @returns id and optional tag; empty when the list endpoint is unavailable.
+ */
+export declare function listHappySessions(serverUrl: string, token: string): Promise<{
+    id: string;
+    tag: string;
+}[]>;
+//# sourceMappingURL=http.d.ts.map

package/lib/types/inbound.d.ts

@@ -0,0 +1,88 @@
+/** Classify inbound Happy user text as a registered slash command or ordinary chat. */
+import type { PermissionRpc } from './types.ts';
+/** Normalized inbound payload from a decrypted Happy message. */
+export type HappyInbound = {
+    kind: 'text';
+    text: string;
+    meta: Record<string, unknown>;
+} | {
+    kind: 'file';
+    ref: string;
+    name: string;
+    mimeType?: string;
+    meta: Record<string, unknown>;
+};
+/**
+ * Read a user text or file event from a decrypted Happy payload.
+ * The App wraps file events as `{ role: 'session', content: { type: 'session', data: { ev } } }`.
+ * happy-wire envelopes put `ev` directly on `content`. Chat text from the phone
+ * is still `{ role: 'user', content: { type: 'text' } }`.
+ * @param plain - decrypted socket payload.
+ * @returns inbound chat or file, or `undefined` when the payload is not user input.
+ */
+export declare function parseHappyInbound(plain: unknown): HappyInbound | undefined;
+/**
+ * Parse a candidate slash line the same way `dsh-commands` `parseCommand` does.
+ * @param line - complete user text.
+ * @returns name + rawInput, or `undefined` when the line is not a command.
+ */
+export declare function parseSlashLine(line: string): {
+    name: string;
+    rawInput: string;
+} | undefined;
+/**
+ * Decide whether inbound phone text should run as a command or as followup.
+ * Unknown `/name` stays chat so user-invocable skills still inject.
+ * @param line - complete user text.
+ * @param commandNames - registered command names without the leading slash.
+ * @returns `command` when the whole line is a registered command, otherwise `chat`.
+ */
+export declare function classifyInboundText(line: string, commandNames: ReadonlySet<string>): 'command' | 'chat';
+/**
+ * Translate Happy AskUserQuestion `answers` (`{ [question text]: "a, b" }`)
+ * back into harness `{ id, selected }` rows.
+ * @param answers - permission RPC `updatedInput.answers`.
+ * @param questions - original harness questions in order.
+ * @returns selected labels keyed by question id.
+ */
+export declare function answersFromHappy(answers: Record<string, string> | undefined, questions: readonly {
+    id: string;
+    question: string;
+}[]): {
+    id: string;
+    selected: string[];
+}[];
+/**
+ * Fill every still-open question with the typed chat line as `custom`.
+ * @param questions - harness questions in order.
+ * @param text - the App composer line.
+ * @returns one answer row per question.
+ */
+export declare function customAnswersFromText(questions: readonly {
+    id: string;
+}[], text: string): {
+    id: string;
+    selected: [];
+    custom: string;
+}[];
+/**
+ * The option label that declines a plan-review question.
+ * @param question - first question of a plan-review `ask`.
+ * @returns the non-approve option label, or Keep planning.
+ */
+export declare function planReviewDeclineLabel(question: {
+    intent?: {
+        kind: string;
+        approve: string;
+    };
+    options?: readonly {
+        label: string;
+    }[];
+}): string;
+/**
+ * Decode a Happy `permission` RPC body.
+ * @param params - decrypted RPC params.
+ * @returns id, approved flag, optional Always-allow decision, and answers.
+ */
+export declare function parsePermissionRpc(params: unknown): PermissionRpc;
+//# sourceMappingURL=inbound.d.ts.map

package/lib/types/inbox.d.ts

@@ -0,0 +1,39 @@
+/** Save phone non-image files into the session workspace so Harness `read` can open them. */
+import type { PendingFile } from './types.ts';
+/** Directory under the session cwd that holds phone files for `read`. */
+export declare const HAPPY_INBOX_DIR = "happy-inbox";
+/**
+ * Strip path separators and reserved characters so the file stays inside `happy-inbox/`.
+ * @param name - Happy's original filename.
+ * @returns a single path segment, or `file` when nothing usable remains.
+ */
+export declare function sanitizeInboxName(name: string): string;
+/**
+ * Pick a basename that is not already taken in this inbox (on disk or in this batch).
+ * @param taken - basenames already used.
+ * @param name - Happy's original filename.
+ * @returns a unique basename under `happy-inbox/`.
+ */
+export declare function uniqueInboxName(taken: ReadonlySet<string>, name: string): string;
+/**
+ * Workspace-relative path the `read` tool resolves against session cwd. Always `/`.
+ * @param filename - a sanitized inbox basename.
+ * @returns `happy-inbox/<filename>`.
+ */
+export declare function inboxReadPath(filename: string): string;
+/**
+ * Append a `read`-tool instruction after the user's typed text.
+ * Harness web does not admit non-image composer uploads; ordinary files are workspace paths for `read`.
+ * @param text - what the phone typed, possibly empty.
+ * @param relativePaths - `happy-inbox/...` paths already written.
+ * @returns the followup text, or `text` when there are no files.
+ */
+export declare function inboxReadPrompt(text: string, relativePaths: readonly string[]): string;
+/**
+ * Write extras into `<cwd>/happy-inbox/` and return relative paths for `read`.
+ * @param cwd - session workspace root.
+ * @param files - decrypted non-image attachments.
+ * @returns posix-relative paths the model should pass to `read`.
+ */
+export declare function saveInboxFiles(cwd: string, files: readonly PendingFile[]): Promise<string[]>;
+//# sourceMappingURL=inbox.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Host half of Happy remote control: pair a running dsh web/desktop client
+ * with Happy App so the phone drives the same harness sessions.
+ * @module @sjhmars/happy-bridge
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import type { Config as HappyBridgeConfig } from './types.ts';
+export type { Config as HappyBridgeConfig, PairingStatus, RemoteGrant } from './types.ts';
+/** Cordis plugin name. */
+export declare const name = "happy-bridge";
+/** Settings namespace keyed by the Plugins tab card. */
+export declare const HAPPY_BRIDGE_NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Wait for the agent registry before mirroring sessions. */
+export declare const inject: string[];
+/** Validated plugin config. Illegal values fail at load. */
+export declare const Config: Schema<HappyBridgeConfig>;
+/**
+ * Mount the Host half: settings namespace, Typert Remote, Happy relay.
+ * @param ctx - Host context.
+ * @param config - composition entry config.
+ */
+export declare function apply(ctx: Context, config: HappyBridgeConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,11 @@
+/** Package invariant companion for `@sjhmars/happy-bridge`. */
+import type { Context } from '@deepseek-ai/cordis';
+export declare const name = "happy-bridge-invariant";
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Host context carrying the invariant registry.
+ * @returns the registration disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map