@agentdeck/bridge 0.2.2 → 0.2.3

package/dist/windows-service.js

@@ -0,0 +1,145 @@
+/**
+ * Windows daemon autostart via a per-user Scheduled Task (logon trigger).
+ *
+ * The macOS LaunchAgent analog on Windows is a per-user Scheduled Task with a
+ * logon trigger — NOT a real Windows Service. A service runs in session 0 with
+ * no desktop and restricted device access, which breaks the daemon's USB-HID
+ * (D200H), audio (wake-word), mDNS, and Stream Deck app integration. A logon
+ * task runs in the interactive user session, needs no admin elevation, and uses
+ * only the built-in schtasks.exe (no npm dependency).
+ *
+ * The pure XML/args builder is unit-tested (cross-platform); the schtasks
+ * /Create|/Run|/Query|/Delete calls are integration-only (real Windows host +
+ * side effects) and are exercised manually per docs/daemon.md.
+ */
+import { writeFileSync, unlinkSync } from 'fs';
+import { homedir, tmpdir, userInfo } from 'os';
+import { dirname, join } from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+export const TASK_NAME = 'AgentDeckDaemon';
+export function xmlEscape(s) {
+    return s
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+// Resolve node.exe + cli.js directly rather than the `agentdeck` npm shim: the
+// global bin on Windows is an `agentdeck.cmd` wrapper whose quoting breaks the
+// Task Scheduler <Command>/<Arguments> split. process.execPath is the running
+// node; cli.js sits next to this module in the dist dir.
+export function getDaemonNodeTarget() {
+    const distDir = dirname(fileURLToPath(import.meta.url));
+    return { node: process.execPath, cliJs: join(distDir, 'cli.js') };
+}
+export function getCurrentTaskUser() {
+    const domain = process.env.USERDOMAIN;
+    const user = process.env.USERNAME || userInfo().username;
+    return domain ? `${domain}\\${user}` : user;
+}
+export function buildScheduledTaskXml(opts) {
+    const { node, cliJs } = { ...getDaemonNodeTarget(), ...opts };
+    const user = opts?.user ?? getCurrentTaskUser();
+    const workingDir = join(homedir(), '.agentdeck');
+    const command = xmlEscape(node);
+    // cli.js wrapped in quotes to survive paths with spaces; --foreground so the
+    // task process IS the daemon (lets RestartOnFailure track the real process).
+    const args = xmlEscape(`"${cliJs}" daemon start --foreground`);
+    const userEsc = xmlEscape(user);
+    // schtasks /XML requires UTF-16 with a BOM (see installWindowsTask); declaring
+    // UTF-8 triggers "unable to switch the encoding". The bytes are written as
+    // UTF-16LE+BOM at install time to match this declaration.
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>AgentDeck monitoring daemon (auto-start on logon)</Description>
+    <URI>\\${TASK_NAME}</URI>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${userEsc}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${userEsc}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>3</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${command}</Command>
+      <Arguments>${args}</Arguments>
+      <WorkingDirectory>${xmlEscape(workingDir)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>`;
+}
+/**
+ * Register (or overwrite) the AgentDeckDaemon scheduled task.
+ * Throws if schtasks /Create fails (e.g. group policy disabling user task creation).
+ */
+export function installWindowsTask() {
+    const xml = buildScheduledTaskXml();
+    const tmpFile = join(tmpdir(), `agentdeck-task-${process.pid}-${Date.now()}.xml`);
+    // Write UTF-16LE with a BOM (U+FEFF) — schtasks /XML rejects UTF-8 here.
+    writeFileSync(tmpFile, '' + xml, 'utf16le');
+    try {
+        // /F overwrites an existing task (idempotent; mirrors macOS unload-before-load).
+        execSync(`schtasks /Create /TN "${TASK_NAME}" /XML "${tmpFile}" /F`, { stdio: 'pipe' });
+    }
+    finally {
+        try {
+            unlinkSync(tmpFile);
+        }
+        catch { /* temp cleanup best-effort */ }
+    }
+}
+/** True if the AgentDeckDaemon scheduled task is registered. */
+export function taskExists() {
+    try {
+        execSync(`schtasks /Query /TN "${TASK_NAME}"`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Start the registered task immediately (so no logout is required). */
+export function runWindowsTask() {
+    execSync(`schtasks /Run /TN "${TASK_NAME}"`, { stdio: 'pipe' });
+}
+/** Stop a running task instance (best-effort; ignores "not running"). */
+export function endWindowsTask() {
+    execSync(`schtasks /End /TN "${TASK_NAME}"`, { stdio: 'pipe' });
+}
+/** Delete the registered task (/F suppresses the confirm prompt). */
+export function deleteWindowsTask() {
+    execSync(`schtasks /Delete /TN "${TASK_NAME}" /F`, { stdio: 'pipe' });
+}
+//# sourceMappingURL=windows-service.js.map

package/dist/windows-service.js.map

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

package/dist/ws-server.d.ts

@@ -8,13 +8,26 @@ export declare class WsServer {
     private onConnectCallback;
     private onDisconnectCallback;
     private clientAlive;
+    private esp32Clients;
+    private eventTransformer;
+    private ulanziClients;
+    private ulanziPresenceCallback;
+    private tuiClients;
     private pingTimer;
     constructor(server: Server);
     private broadcastHooks;
     /** Register a hook that gets called on every broadcast (e.g., ESP32 serial relay). */
     onBroadcast(hook: (event: BridgeEvent) => void): void;
+    setEventTransformer(transformer: ((event: BridgeEvent, client: WebSocket) => BridgeEvent | null) | null): void;
+    isEsp32Client(ws: WebSocket): boolean;
+    markEsp32Client(ws: WebSocket): void;
+    private payloadFor;
     broadcast(event: BridgeEvent): void;
     onCommand(callback: (cmd: PluginCommand) => void): void;
+    /** Register a callback invoked when the Ulanzi-plugin presence flips (true =
+     *  at least one connected, false = none). Fires once immediately with the
+     *  current state so the consumer can sync on startup. */
+    onUlanziPluginPresence(callback: (present: boolean) => void): void;
     /** Inject a command from a non-WS source (e.g., D200H agent via stdout/stdin pipe). */
     dispatchCommand(cmd: PluginCommand): void;
     /** Register a callback for raw messages before PluginCommand dispatch. Return true to consume. */
@@ -22,9 +35,17 @@ export declare class WsServer {
     /** Broadcast to all clients except the sender */
     broadcastExcept(event: BridgeEvent, except: WebSocket): void;
     onClientConnect(callback: (ws: WebSocket) => void): void;
-    onClientDisconnect(callback: () => void): void;
+    onClientDisconnect(callback: (ws: WebSocket) => void): void;
     sendTo(ws: WebSocket, event: BridgeEvent): void;
     getClientCount(): number;
+    getUlanziClientCount(): number;
+    /** Registered TUI dashboards (`client_register {clientType:"tui"}`), deduped
+     *  by client id so a TUI that reconnects (new WS, same host+pid) yields one
+     *  entry while both sockets briefly overlap. */
+    getTuiClients(): Array<{
+        id: string;
+        name: string;
+    }>;
     close(): void;
 }
 //# sourceMappingURL=ws-server.d.ts.map

package/dist/ws-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws-server.d.ts","sourceRoot":"","sources":["../src/ws-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAE,MAAM,IAAI,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAmB,MAAM,MAAM,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK7D,qBAAa,QAAQ;IACnB,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,kBAAkB,CAA+E;IACzG,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,SAAS,CAAiC;gBAEtC,MAAM,EAAE,MAAM;IAqF1B,OAAO,CAAC,cAAc,CAA2C;IAEjE,sFAAsF;IACtF,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAIrD,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAenC,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAIvD,uFAAuF;IACvF,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAIzC,kGAAkG;IAClG,YAAY,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,IAAI;IAI1F,iDAAiD;IACjD,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAS5D,eAAe,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;IAIxD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI;IAI9C,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAM/C,cAAc,IAAI,MAAM;IAIxB,KAAK,IAAI,IAAI;CASd"}
+{"version":3,"file":"ws-server.d.ts","sourceRoot":"","sources":["../src/ws-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,SAAS,EAAE,MAAM,IAAI,CAAC;AAChD,OAAO,KAAK,EAAE,MAAM,EAAmB,MAAM,MAAM,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK7D,qBAAa,QAAQ;IACnB,OAAO,CAAC,GAAG,CAAkB;IAC7B,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,kBAAkB,CAA+E;IACzG,OAAO,CAAC,iBAAiB,CAA0C;IACnE,OAAO,CAAC,oBAAoB,CAA0C;IACtE,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,gBAAgB,CAAgF;IAIxG,OAAO,CAAC,aAAa,CAAwB;IAC7C,OAAO,CAAC,sBAAsB,CAA6C;IAK3E,OAAO,CAAC,UAAU,CAAsD;IACxE,OAAO,CAAC,SAAS,CAAiC;gBAEtC,MAAM,EAAE,MAAM;IAmH1B,OAAO,CAAC,cAAc,CAA2C;IAEjE,sFAAsF;IACtF,WAAW,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI;IAIrD,mBAAmB,CAAC,WAAW,EAAE,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,KAAK,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI;IAI9G,aAAa,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO;IAIrC,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI;IAIpC,OAAO,CAAC,UAAU;IAOlB,SAAS,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAiBnC,SAAS,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAIvD;;6DAEyD;IACzD,sBAAsB,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAKlE,uFAAuF;IACvF,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAIzC,kGAAkG;IAClG,YAAY,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,IAAI;IAI1F,iDAAiD;IACjD,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,GAAG,IAAI;IAW5D,eAAe,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;IAIxD,kBAAkB,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;IAI3D,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAQ/C,cAAc,IAAI,MAAM;IAIxB,oBAAoB,IAAI,MAAM;IAI9B;;oDAEgD;IAChD,aAAa,IAAI,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAMpD,KAAK,IAAI,IAAI;CASd"}

package/dist/ws-server.js

@@ -9,6 +9,18 @@ export class WsServer {
     onConnectCallback = null;
     onDisconnectCallback = null;
     clientAlive = new Map();
+    esp32Clients = new Set();
+    eventTransformer = null;
+    // Clients that registered as the Ulanzi Studio plugin. While any are present,
+    // the daemon's direct-HID D200H module stands down so the two don't fight over
+    // the device (Ulanzi Studio drives it through the official plugin instead).
+    ulanziClients = new Set();
+    ulanziPresenceCallback = null;
+    // TUI dashboards (`agentdeck dashboard`) that registered via
+    // `client_register {clientType:"tui"}`. Volunteer-roster model like the
+    // Stream Deck plugin — presence only lives as long as the WS does, so the
+    // topology row disappears the moment the TUI exits.
+    tuiClients = new Map();
     pingTimer;
     constructor(server) {
         this.wss = new WebSocketServer({ server });
@@ -49,6 +61,11 @@ export class WsServer {
                 }
                 debug('WS', `Remote client authenticated from ${remoteIp}`);
             }
+            const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
+            if (url.searchParams.get('clientType') === 'esp32' || url.searchParams.get('esp32') === '1') {
+                this.esp32Clients.add(ws);
+                debug('WS', 'ESP32 WiFi client tagged from query');
+            }
             debug('WS', 'Plugin connected');
             this.clientAlive.set(ws, true);
             // Send current state to newly connected client
@@ -62,6 +79,23 @@ export class WsServer {
                 try {
                     const msg = JSON.parse(data.toString());
                     debug('WS', `recv cmd: ${msg.type}`);
+                    // Track Ulanzi plugin presence (device-ownership arbitration).
+                    if (msg.type === 'client_register' && msg.clientType === 'ulanzi-plugin') {
+                        const was = this.ulanziClients.size > 0;
+                        this.ulanziClients.add(ws);
+                        if (!was) {
+                            debug('WS', 'Ulanzi plugin registered — direct-HID D200H stands down');
+                            this.ulanziPresenceCallback?.(true);
+                        }
+                    }
+                    // Track TUI dashboard presence (topology row on all dashboards).
+                    if (msg.type === 'client_register' && msg.clientType === 'tui') {
+                        const dev = (Array.isArray(msg.devices) ? msg.devices[0] : null);
+                        const name = typeof dev?.name === 'string' && dev.name ? dev.name : 'terminal';
+                        const id = typeof dev?.id === 'string' && dev.id ? dev.id : name;
+                        this.tuiClients.set(ws, { id, name });
+                        debug('WS', `TUI dashboard registered: ${id}`);
+                    }
                     // Allow raw message callback to intercept relay events (e.g. deck_slot_map)
                     if (this.rawMessageCallback && this.rawMessageCallback(msg, ws)) {
                         return; // handled
@@ -77,8 +111,14 @@ export class WsServer {
             ws.on('close', () => {
                 debug('WS', 'Plugin disconnected');
                 this.clientAlive.delete(ws);
+                this.esp32Clients.delete(ws);
+                this.tuiClients.delete(ws);
+                if (this.ulanziClients.delete(ws) && this.ulanziClients.size === 0) {
+                    debug('WS', 'Ulanzi plugin gone — direct-HID D200H may resume');
+                    this.ulanziPresenceCallback?.(false);
+                }
                 if (this.onDisconnectCallback) {
-                    this.onDisconnectCallback();
+                    this.onDisconnectCallback(ws);
                 }
             });
             ws.on('error', (err) => {
@@ -91,14 +131,34 @@ export class WsServer {
     onBroadcast(hook) {
         this.broadcastHooks.push(hook);
     }
+    setEventTransformer(transformer) {
+        this.eventTransformer = transformer;
+    }
+    isEsp32Client(ws) {
+        return this.esp32Clients.has(ws);
+    }
+    markEsp32Client(ws) {
+        this.esp32Clients.add(ws);
+    }
+    payloadFor(event, client, cachedPayload) {
+        if (!this.eventTransformer)
+            return cachedPayload ?? JSON.stringify(event);
+        const transformed = this.eventTransformer(event, client);
+        if (!transformed)
+            return null;
+        return transformed === event ? (cachedPayload ?? JSON.stringify(event)) : JSON.stringify(transformed);
+    }
     broadcast(event) {
         const payload = JSON.stringify(event);
         const clientCount = this.wss.clients.size;
         debug('WS', `broadcast(${event.type}) to ${clientCount} clients`);
         for (const client of this.wss.clients) {
             if (client.readyState === WebSocket.OPEN) {
+                const clientPayload = this.payloadFor(event, client, payload);
+                if (!clientPayload)
+                    continue;
                 try {
-                    client.send(payload);
+                    client.send(clientPayload);
                 }
                 catch { /* client disconnecting */ }
             }
@@ -114,6 +174,13 @@ export class WsServer {
     onCommand(callback) {
         this.commandCallback = callback;
     }
+    /** Register a callback invoked when the Ulanzi-plugin presence flips (true =
+     *  at least one connected, false = none). Fires once immediately with the
+     *  current state so the consumer can sync on startup. */
+    onUlanziPluginPresence(callback) {
+        this.ulanziPresenceCallback = callback;
+        callback(this.ulanziClients.size > 0);
+    }
     /** Inject a command from a non-WS source (e.g., D200H agent via stdout/stdin pipe). */
     dispatchCommand(cmd) {
         this.commandCallback?.(cmd);
@@ -127,8 +194,11 @@ export class WsServer {
         const payload = JSON.stringify(event);
         for (const client of this.wss.clients) {
             if (client !== except && client.readyState === WebSocket.OPEN) {
+                const clientPayload = this.payloadFor(event, client, payload);
+                if (!clientPayload)
+                    continue;
                 try {
-                    client.send(payload);
+                    client.send(clientPayload);
                 }
                 catch { /* client disconnecting */ }
             }
@@ -142,8 +212,11 @@ export class WsServer {
     }
     sendTo(ws, event) {
         if (ws.readyState === WebSocket.OPEN) {
+            const payload = this.payloadFor(event, ws);
+            if (!payload)
+                return;
             try {
-                ws.send(JSON.stringify(event));
+                ws.send(payload);
             }
             catch { /* client disconnecting */ }
         }
@@ -151,6 +224,18 @@ export class WsServer {
     getClientCount() {
         return this.wss.clients.size;
     }
+    getUlanziClientCount() {
+        return this.ulanziClients.size;
+    }
+    /** Registered TUI dashboards (`client_register {clientType:"tui"}`), deduped
+     *  by client id so a TUI that reconnects (new WS, same host+pid) yields one
+     *  entry while both sockets briefly overlap. */
+    getTuiClients() {
+        const byId = new Map();
+        for (const info of this.tuiClients.values())
+            byId.set(info.id, info);
+        return [...byId.values()];
+    }
     close() {
         clearInterval(this.pingTimer);
         this.clientAlive.clear();

package/dist/ws-server.js.map

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

package/fm-helper/AgentDeckFMHelper.swift

@@ -0,0 +1,112 @@
+import Foundation
+#if canImport(FoundationModels)
+import FoundationModels
+#endif
+
+struct HelperRequest: Decodable {
+    let id: Int
+    let type: String?
+    let prompt: String?
+    let instructions: String?
+    let temperature: Double?
+}
+
+@main
+struct AgentDeckFMHelper {
+    static func main() async {
+        do {
+            for try await line in FileHandle.standardInput.bytes.lines {
+                await handle(line)
+            }
+        } catch {
+            write(["id": -1, "error": "stdin_error", "reason": String(describing: error)])
+        }
+    }
+
+    private static func handle(_ line: String) async {
+        guard let data = line.data(using: .utf8),
+              let request = try? JSONDecoder().decode(HelperRequest.self, from: data) else {
+            write(["id": -1, "error": "bad_request", "reason": "invalid JSON line"])
+            return
+        }
+
+        if request.type == "health" {
+            write(healthResponse(id: request.id))
+            return
+        }
+
+        guard let prompt = request.prompt, !prompt.isEmpty else {
+            write(["id": request.id, "error": "bad_request", "reason": "missing prompt"])
+            return
+        }
+
+#if canImport(FoundationModels)
+        if #available(macOS 26.0, *) {
+            guard case .available = SystemLanguageModel.default.availability else {
+                write([
+                    "id": request.id,
+                    "error": "unavailable",
+                    "reason": unavailableReason(),
+                ])
+                return
+            }
+
+            do {
+                let session = LanguageModelSession(
+                    instructions: request.instructions ?? "You are an exacting code evaluator. Reply with strict JSON only."
+                )
+                let options = GenerationOptions(temperature: request.temperature ?? 0)
+                let response = try await session.respond(to: prompt, options: options)
+                write(["id": request.id, "text": response.content])
+            } catch {
+                write(["id": request.id, "error": "session_error", "reason": String(describing: error)])
+            }
+        } else {
+            write(["id": request.id, "error": "unavailable", "reason": "macOS 26 or later required"])
+        }
+#else
+        write(["id": request.id, "error": "unavailable", "reason": "FoundationModels framework not present"])
+#endif
+    }
+
+    private static func healthResponse(id: Int) -> [String: Any] {
+#if canImport(FoundationModels)
+        if #available(macOS 26.0, *) {
+            if case .available = SystemLanguageModel.default.availability {
+                return ["id": id, "status": "ready"]
+            }
+            return ["id": id, "status": "unavailable", "reason": unavailableReason()]
+        }
+        return ["id": id, "status": "unavailable", "reason": "macOS 26 or later required"]
+#else
+        return ["id": id, "status": "unavailable", "reason": "FoundationModels framework not present"]
+#endif
+    }
+
+    private static func unavailableReason() -> String {
+#if canImport(FoundationModels)
+        if #available(macOS 26.0, *) {
+            switch SystemLanguageModel.default.availability {
+            case .available:
+                return "available"
+            case .unavailable(let reason):
+                return "unavailable: \(reason)"
+            @unknown default:
+                return "unavailable: unknown state"
+            }
+        }
+        return "macOS 26 or later required"
+#else
+        return "FoundationModels framework not present"
+#endif
+    }
+
+    private static func write(_ object: [String: Any]) {
+        guard JSONSerialization.isValidJSONObject(object),
+              let data = try? JSONSerialization.data(withJSONObject: object),
+              let text = String(data: data, encoding: .utf8) else {
+            return
+        }
+        FileHandle.standardOutput.write(Data((text + "\n").utf8))
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentdeck/bridge",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -10,7 +10,11 @@
   },
   "files": [
     "dist",
-    "!dist/__tests__"
+    "!dist/__tests__",
+    "assets/fonts",
+    "assets/fm-helper",
+    "fm-helper",
+    "scripts/build-fm-helper.mjs"
   ],
   "main": "./dist/index.js",
   "bin": {
@@ -23,7 +27,8 @@
     "qrcode": "^1.5.4",
     "strip-ansi": "^7.2.0",
     "ws": "^8.20.0",
-    "@agentdeck/shared": "0.2.0"
+    "@agentdeck/hooks": "0.2.3",
+    "@agentdeck/shared": "0.2.3"
   },
   "optionalDependencies": {
     "@picovoice/porcupine-node": "^4.0.2",
@@ -43,6 +48,7 @@
   },
   "scripts": {
     "build": "tsc",
+    "build:fm-helper": "node scripts/build-fm-helper.mjs",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",

package/scripts/build-fm-helper.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)));
+const source = join(root, 'fm-helper', 'AgentDeckFMHelper.swift');
+const out = join(root, 'assets', 'fm-helper', 'agentdeck-fm-helper');
+const arch = process.arch === 'arm64' ? 'arm64' : 'x86_64';
+const target = `${arch}-apple-macos26.0`;
+
+if (process.platform !== 'darwin') {
+  console.log('[fm-helper] skipped: darwin only');
+  process.exit(0);
+}
+
+mkdirSync(dirname(out), { recursive: true });
+const swiftc = execFileSync('/usr/bin/xcrun', ['--find', 'swiftc'], { encoding: 'utf8' }).trim();
+// swiftc is run directly (not via `xcrun swiftc`), so SDKROOT isn't set and the
+// stdlib can't be found ("unable to load standard library for target ..."). Pass
+// the SDK path explicitly so the build is reproducible from the npm lifecycle.
+const sdk = execFileSync('/usr/bin/xcrun', ['--sdk', 'macosx', '--show-sdk-path'], { encoding: 'utf8' }).trim();
+execFileSync(swiftc, ['-parse-as-library', '-sdk', sdk, '-target', target, source, '-o', out], { stdio: 'inherit' });
+chmodSync(out, 0o755);
+console.log(`[fm-helper] built ${out}`);

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 SerendipityBound
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.