uxnan-bridge 0.0.1-alpha.20260621

package/dist/src/agents/attachments.js

@@ -0,0 +1,121 @@
+/**
+ * Turn attachment delivery.
+ *
+ * The phone sends inline image attachments on `turn/send { attachments }`. No
+ * agent CLI accepts inline base64 over the headless stdio path, but every
+ * supported agent (Claude, Codex, OpenCode, pi, Gemini) can OPEN a local file
+ * with its own file/vision tools. So the bridge materializes each attachment to
+ * a file and references the path in the prompt — CLI-agnostic, no per-adapter
+ * image handling required.
+ *
+ * IMPORTANT: the file is written **inside the agent's working directory**
+ * (`<cwd>/.uxnan-attachments/<turnId>/`) and referenced by a **cwd-relative**
+ * path, because sandboxed agents confine file reads to the workspace (Gemini
+ * `--approval-mode`, Codex `workspace-write`, Claude `acceptEdits`) and reject a
+ * path outside it. The dir is cleaned up when the turn ends (see AgentManager).
+ *
+ * Source: architecture/02a-system-architecture.md §5.8 (agent turns) +
+ * uxnanmobile/FOR-DEV.md → Conversation / timeline → Attach.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+/** Sub-directory (under the thread cwd) the bridge drops turn attachments into. */
+export const ATTACHMENTS_DIRNAME = '.uxnan-attachments';
+/** Extension for a known image MIME type (no leading dot). */
+function extensionFor(mimeType) {
+    switch (mimeType.toLowerCase()) {
+        case 'image/png':
+            return 'png';
+        case 'image/jpeg':
+        case 'image/jpg':
+            return 'jpg';
+        case 'image/webp':
+            return 'webp';
+        case 'image/gif':
+            return 'gif';
+        case 'image/heic':
+            return 'heic';
+        case 'image/bmp':
+            return 'bmp';
+        default:
+            return 'bin';
+    }
+}
+/**
+ * Writes each inline attachment to a file under the thread's working directory
+ * and returns the absolute paths plus a ready-to-append prompt note (which
+ * references the files by a cwd-relative path). Tolerant: attachments without
+ * usable `base64Data` are skipped (an attachment that is only a workspace
+ * `path` is referenced by that path). Never throws on a single bad attachment.
+ */
+export async function materializeAttachments(attachments, turnId, options = {}) {
+    if (attachments.length === 0)
+        return { paths: [], note: '' };
+    const cwd = options.cwd;
+    const baseDir = cwd ? join(cwd, ATTACHMENTS_DIRNAME) : join(tmpdir(), 'uxnan-attachments');
+    const dir = join(baseDir, sanitizeSegment(turnId));
+    const paths = [];
+    const refs = [];
+    let madeDir = false;
+    for (let i = 0; i < attachments.length; i += 1) {
+        const att = attachments[i];
+        if (!att)
+            continue;
+        // An attachment that is already an on-disk workspace file: reference it
+        // directly (no need to copy), the agent can open it in place.
+        if (!att.base64Data && att.path) {
+            paths.push(att.path);
+            refs.push(referencePath(att.path, cwd));
+            continue;
+        }
+        if (!att.base64Data)
+            continue;
+        let bytes;
+        try {
+            bytes = Buffer.from(att.base64Data, 'base64');
+        }
+        catch {
+            continue;
+        }
+        if (bytes.length === 0)
+            continue;
+        if (!madeDir) {
+            await mkdir(dir, { recursive: true });
+            madeDir = true;
+        }
+        const file = join(dir, `image-${i}.${extensionFor(att.mimeType ?? 'image/png')}`);
+        try {
+            await writeFile(file, bytes);
+            paths.push(file);
+            refs.push(referencePath(file, cwd));
+        }
+        catch {
+            // Best-effort: a single write failure must not abort the turn.
+        }
+    }
+    if (paths.length === 0)
+        return { paths: [], note: '' };
+    const label = paths.length > 1 ? 'images' : 'image';
+    const list = refs.map((p) => `- ${p}`).join('\n');
+    const note = `[Attached ${label} (open with your file/vision tools):\n${list}\n]`;
+    return { paths, ...(madeDir ? { dir } : {}), note };
+}
+/**
+ * Reference path used in the prompt: relative to `cwd` (POSIX separators) when
+ * the file lives inside it, otherwise the path as-is. Relative keeps the
+ * reference inside the agent's sandbox.
+ */
+function referencePath(absPath, cwd) {
+    if (!cwd)
+        return absPath;
+    const rel = relative(cwd, absPath);
+    if (!rel || rel.startsWith('..'))
+        return absPath;
+    return rel.split(sep).join('/');
+}
+/** Strip path separators / unsafe chars from a path segment. */
+function sanitizeSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]/g, '_') || 'turn';
+}
+//# sourceMappingURL=attachments.js.map

package/dist/src/agents/attachments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.js","sourceRoot":"","sources":["../../../src/agents/attachments.ts"],"names":[],"mappings":"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"}

package/dist/src/bridge-context.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared context passed to every JSON-RPC handler.
+ */
+import type { DaemonConfig } from './daemon-config.js';
+import type { DaemonState } from './daemon-state.js';
+import type { SecureDeviceState } from './secure-device-state.js';
+import type { SessionState } from './session-state.js';
+import type { SessionRegistry } from './transport/session-registry.js';
+import type { TrustStore } from './transport/trust-store.js';
+import type { ThreadStore } from './conversation/thread-store.js';
+import type { SessionHistoryReader } from './conversation/session-history.js';
+import type { AgentManager } from './agents/agent-manager.js';
+import type { ProjectRegistry } from './projects/project-registry.js';
+import type { BrowseService } from './workspace/browse-service.js';
+import type { PushService } from './push/push-service.js';
+import type { Logger } from './logger.js';
+export interface BridgeContext {
+    readonly version: string;
+    readonly startedAt: number;
+    readonly config: DaemonConfig;
+    readonly state: DaemonState;
+    readonly deviceState: SecureDeviceState;
+    readonly sessions: SessionState;
+    /** Live encrypted sinks for connected phones (bridge → phone notifications). */
+    readonly sessionRegistry: SessionRegistry;
+    /** Persisted trusted phones (Ed25519 identity + metadata, no secrets). */
+    readonly trustStore: TrustStore;
+    /** Persistent conversation store. */
+    readonly threadStore: ThreadStore;
+    /** Reads agent on-disk session logs as a `turn/list` fallback (§5.8.8). */
+    readonly sessionHistory: SessionHistoryReader;
+    /** Agent turn orchestration. */
+    readonly agentManager: AgentManager;
+    /** The project directories the phone may open. */
+    readonly projects: ProjectRegistry;
+    /** Root-confined directory browsing for plug-and-play project selection. */
+    readonly browse: BrowseService;
+    /** Push-notification coordination (token registration + turn-end delivery). */
+    readonly pushService: PushService;
+    readonly logger: Logger;
+    /** Whether at least one relay connection is currently serving a phone. */
+    relayConnected(): boolean;
+    /** Injected clock (epoch ms) for testability. */
+    now(): number;
+}

package/dist/src/bridge-context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bridge-context.js.map

package/dist/src/bridge-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-context.js","sourceRoot":"","sources":["../../src/bridge-context.ts"],"names":[],"mappings":""}

package/dist/src/bridge-status.d.ts

@@ -0,0 +1,12 @@
+import type { BridgeStatus } from '@uxnan/shared';
+export interface BridgeStatusInput {
+    version: string;
+    relayConnected: boolean;
+    lanEnabled: boolean;
+    activeSessions: number;
+    /** Process start time in epoch ms. */
+    startedAt: number;
+    /** Current time in epoch ms (injected for testability). */
+    now: number;
+}
+export declare function buildBridgeStatus(input: BridgeStatusInput): BridgeStatus;

package/dist/src/bridge-status.js

@@ -0,0 +1,17 @@
+/**
+ * Heartbeat / status snapshot of the bridge.
+ *
+ * Source: architecture/02a-system-architecture.md §5.8.2 (bridge-status).
+ */
+import { platform } from 'node:os';
+export function buildBridgeStatus(input) {
+    return {
+        version: input.version,
+        relayConnected: input.relayConnected,
+        lanEnabled: input.lanEnabled,
+        activeSessions: input.activeSessions,
+        platform: platform(),
+        uptimeMs: Math.max(0, input.now - input.startedAt),
+    };
+}
+//# sourceMappingURL=bridge-status.js.map

package/dist/src/bridge-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-status.js","sourceRoot":"","sources":["../../src/bridge-status.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAcnC,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACxD,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,cAAc,EAAE,KAAK,CAAC,cAAc;QACpC,QAAQ,EAAE,QAAQ,EAAE;QACpB,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC;KACnD,CAAC;AACJ,CAAC"}

package/dist/src/bridge.d.ts

@@ -0,0 +1,37 @@
+import { type BridgeStatus, type PairingPayload } from '@uxnan/shared';
+import type { BridgeContext } from './bridge-context.js';
+import { HandlerRouter } from './handler-router.js';
+import type { SecretStore } from './secret-store.js';
+import { type LogLevel } from './logger.js';
+import { type TrustStore } from './transport/trust-store.js';
+export interface StartBridgeOptions {
+    /** Override the daemon state directory (defaults to `~/.uxnan`). */
+    baseDir?: string;
+    /** Inject a secret store (defaults to an in-memory one). */
+    secretStore?: SecretStore;
+    logLevel?: LogLevel;
+    /** Inject a clock (epoch ms) for testability. */
+    now?: () => number;
+}
+export interface Bridge {
+    readonly context: BridgeContext;
+    readonly router: HandlerRouter;
+    readonly trustStore: TrustStore;
+    status(): BridgeStatus;
+    generatePairingQr(): PairingPayload;
+    /** The current manual-pairing code to show on the PC (rotates on expiry). */
+    currentPairingCode(): string;
+    /** Connect to the relay as `mac` and serve a phone for the given session. */
+    connectRelay(sessionId: string): Promise<void>;
+    /** Start the direct-LAN WebSocket server; resolves with the bound port. */
+    startLan(): Promise<{
+        port: number;
+    }>;
+    /**
+     * Push a JSON-RPC notification to a connected phone. Returns `true` if it was
+     * sent live, `false` if the device is offline and it was buffered.
+     */
+    notify(deviceId: string, method: string, params?: unknown): boolean;
+    stop(): Promise<void>;
+}
+export declare function startBridge(options?: StartBridgeOptions): Promise<Bridge>;