@phuetz/code-buddy 1.2.0 → 1.3.0

package/dist/sensory/heartbeat-scheduler.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Heartbeat scheduler — turns the nervous-system heartbeat into a PACEMAKER for
+ * periodic processing in Code Buddy. Register "treatments" that fire every N
+ * beats; the daemon's heart rate (BUDDY_SENSE_HEARTBEAT_MS) dials how often they
+ * run — a faster heart triggers more processing, a slower one less.
+ *
+ * This is the heartbeat-paced analogue of Hermes's curator/cron and OpenClaw's
+ * cron-jobs + dreaming: scheduled background work, but driven by the heart rather
+ * than a wall clock. Each beat carries vital signs (uptime, load) the treatments
+ * can read — so a treatment can also adapt to the body's state.
+ *
+ * @module sensory/heartbeat-scheduler
+ */
+export interface HeartbeatContext {
+    beat: number;
+    uptimeMs?: number;
+    load1?: number | null;
+}
+export type HeartbeatHandler = (ctx: HeartbeatContext) => void | Promise<void>;
+export interface HeartbeatTask {
+    name: string;
+    /** Fire when `beat % everyBeats === 0` (1 = every beat). */
+    everyBeats: number;
+    handler: HeartbeatHandler;
+}
+export declare class HeartbeatScheduler {
+    private readonly tasks;
+    private listenerId?;
+    /** Register a treatment to run every N beats. Re-registering replaces it. */
+    register(task: HeartbeatTask): void;
+    unregister(name: string): void;
+    list(): HeartbeatTask[];
+    /** Subscribe to the sensory bus and start pacing. Idempotent. */
+    start(): void;
+    stop(): void;
+    private onBeat;
+}
+export declare function getHeartbeatScheduler(): HeartbeatScheduler;

package/dist/sensory/heartbeat-scheduler.js

@@ -0,0 +1,72 @@
+/**
+ * Heartbeat scheduler — turns the nervous-system heartbeat into a PACEMAKER for
+ * periodic processing in Code Buddy. Register "treatments" that fire every N
+ * beats; the daemon's heart rate (BUDDY_SENSE_HEARTBEAT_MS) dials how often they
+ * run — a faster heart triggers more processing, a slower one less.
+ *
+ * This is the heartbeat-paced analogue of Hermes's curator/cron and OpenClaw's
+ * cron-jobs + dreaming: scheduled background work, but driven by the heart rather
+ * than a wall clock. Each beat carries vital signs (uptime, load) the treatments
+ * can read — so a treatment can also adapt to the body's state.
+ *
+ * @module sensory/heartbeat-scheduler
+ */
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+export class HeartbeatScheduler {
+    tasks = new Map();
+    listenerId;
+    /** Register a treatment to run every N beats. Re-registering replaces it. */
+    register(task) {
+        if (!Number.isInteger(task.everyBeats) || task.everyBeats < 1) {
+            throw new Error(`heartbeat task "${task.name}": everyBeats must be an integer >= 1`);
+        }
+        this.tasks.set(task.name, task);
+    }
+    unregister(name) {
+        this.tasks.delete(name);
+    }
+    list() {
+        return [...this.tasks.values()];
+    }
+    /** Subscribe to the sensory bus and start pacing. Idempotent. */
+    start() {
+        if (this.listenerId)
+            return;
+        const bus = getGlobalEventBus();
+        this.listenerId = bus.on('sensory:perception', (evt) => {
+            const m = evt.metadata;
+            if (m?.modality !== 'vital' || m?.kind !== 'heartbeat')
+                return;
+            const beat = Number(m.payload?.beat ?? 0);
+            if (!Number.isFinite(beat) || beat < 1)
+                return;
+            void this.onBeat({ beat, uptimeMs: m.payload?.uptime_ms, load1: m.payload?.load1 });
+        });
+    }
+    stop() {
+        if (this.listenerId) {
+            getGlobalEventBus().off(this.listenerId);
+            this.listenerId = undefined;
+        }
+    }
+    async onBeat(ctx) {
+        for (const task of this.tasks.values()) {
+            if (ctx.beat % task.everyBeats !== 0)
+                continue;
+            try {
+                await task.handler(ctx);
+            }
+            catch (err) {
+                logger.warn(`[heartbeat] treatment "${task.name}" failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+}
+let singleton;
+export function getHeartbeatScheduler() {
+    if (!singleton)
+        singleton = new HeartbeatScheduler();
+    return singleton;
+}
+//# sourceMappingURL=heartbeat-scheduler.js.map

package/dist/sensory/reactions.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sensory reactions — subscribers that turn `sensory:perception` events from the
+ * nervous-system daemon into Code Buddy behaviour. Phase 1 logs + exposes a hook;
+ * Phase 2 will route (speech_end → STT → turn; motion → camera_analyze).
+ *
+ * @module sensory/reactions
+ */
+import type { BaseEvent } from '../events/types.js';
+export interface Perception {
+    modality?: string;
+    kind?: string;
+    salience?: number;
+    /** Sense-relative timestamp (frame-relative for audio, unix-millis for vital). */
+    tsMs?: number;
+    /** Ingest wall-clock (one consistent clock across senses — used for dream windows). */
+    receivedAt?: number;
+    payload?: unknown;
+}
+export declare function perceptionOf(evt: BaseEvent): Perception;
+/**
+ * Wire reactions to the sensory bus. Returns an unsubscribe fn. `onPerception`
+ * is an injectable hook (tests + future routing).
+ */
+export declare function wireSensoryReactions(onPerception?: (p: Perception, evt: BaseEvent) => void): () => void;

package/dist/sensory/reactions.js

@@ -0,0 +1,31 @@
+/**
+ * Sensory reactions — subscribers that turn `sensory:perception` events from the
+ * nervous-system daemon into Code Buddy behaviour. Phase 1 logs + exposes a hook;
+ * Phase 2 will route (speech_end → STT → turn; motion → camera_analyze).
+ *
+ * @module sensory/reactions
+ */
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+import { getSensoryMemory } from './sensory-memory.js';
+export function perceptionOf(evt) {
+    const meta = evt.metadata ?? {};
+    return { ...meta, receivedAt: evt.timestamp };
+}
+/**
+ * Wire reactions to the sensory bus. Returns an unsubscribe fn. `onPerception`
+ * is an injectable hook (tests + future routing).
+ */
+export function wireSensoryReactions(onPerception) {
+    const bus = getGlobalEventBus();
+    const id = bus.on('sensory:perception', (evt) => {
+        const p = perceptionOf(evt);
+        logger.info(`[sensory] ${p.modality}/${p.kind} (salience ${p.salience ?? 0})`);
+        getSensoryMemory().push(p); // short-term memory → consolidated by dreaming
+        onPerception?.(p, evt);
+    });
+    return () => {
+        bus.off(id);
+    };
+}
+//# sourceMappingURL=reactions.js.map

package/dist/sensory/screen-reaction.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Screen reaction — on a `screen/change` event from the nervous-system daemon,
+ * record a companion percept and (optionally) run an injected analyzer (OCR /
+ * vision describe). DEBOUNCED, opt-in (`CODEBUDDY_SENSORY_SCREEN=true`),
+ * never-throws. The heavy OCR/describe is pluggable so we don't duplicate Code
+ * Buddy's existing OCR/vision; inject an analyzer to wire it.
+ *
+ * @module sensory/screen-reaction
+ */
+export interface ScreenAnalysis {
+    description?: string;
+}
+export interface ScreenAnalyzer {
+    analyze(): Promise<ScreenAnalysis>;
+}
+export interface ScreenReactionOptions {
+    /** Injectable OCR/vision describe (default: none — just record the change). */
+    analyzer?: ScreenAnalyzer;
+    debounceMs?: number;
+    cwd?: string;
+    now?: () => number;
+}
+export declare function wireScreenReaction(options?: ScreenReactionOptions): () => void;

package/dist/sensory/screen-reaction.js

@@ -0,0 +1,59 @@
+/**
+ * Screen reaction — on a `screen/change` event from the nervous-system daemon,
+ * record a companion percept and (optionally) run an injected analyzer (OCR /
+ * vision describe). DEBOUNCED, opt-in (`CODEBUDDY_SENSORY_SCREEN=true`),
+ * never-throws. The heavy OCR/describe is pluggable so we don't duplicate Code
+ * Buddy's existing OCR/vision; inject an analyzer to wire it.
+ *
+ * @module sensory/screen-reaction
+ */
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+import { perceptionOf } from './reactions.js';
+export function wireScreenReaction(options = {}) {
+    const bus = getGlobalEventBus();
+    const debounceMs = options.debounceMs ?? Number(process.env.CODEBUDDY_SCREEN_DEBOUNCE_MS ?? 5000);
+    const now = options.now ?? (() => Date.now());
+    let lastAt = Number.NEGATIVE_INFINITY;
+    let inFlight = false;
+    const id = bus.on('sensory:perception', (evt) => {
+        const p = perceptionOf(evt);
+        if (p.modality !== 'screen' || p.kind !== 'change')
+            return;
+        const t = now();
+        if (t - lastAt < debounceMs) {
+            logger.info('[screen] change (debounced)');
+            return;
+        }
+        if (inFlight)
+            return; // a prior analyze() is still running — don't stampede
+        lastAt = t;
+        inFlight = true;
+        void (async () => {
+            try {
+                const analysis = options.analyzer ? await options.analyzer.analyze() : {};
+                const { recordCompanionPercept } = await import('../companion/percepts.js');
+                const score = p.payload?.score;
+                await recordCompanionPercept({
+                    modality: 'screen',
+                    source: 'sensory_screen_reaction',
+                    summary: `Screen changed${analysis.description ? ` → ${analysis.description}` : ''}`,
+                    confidence: 0.85,
+                    payload: { score, description: analysis.description },
+                    tags: ['screen', 'change'],
+                }, options.cwd ? { cwd: options.cwd } : {});
+                logger.info(`[screen] change recorded${analysis.description ? ` → ${analysis.description}` : ''}`);
+            }
+            catch (err) {
+                logger.warn(`[screen] reaction failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                inFlight = false;
+            }
+        })();
+    });
+    return () => {
+        bus.off(id);
+    };
+}
+//# sourceMappingURL=screen-reaction.js.map

package/dist/sensory/sensory-bridge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Sensory bridge — the ingress for the Rust `buddy-sense` nervous-system daemon.
+ *
+ * A loopback-only WebSocket server that receives `SensoryEvent` JSON frames from
+ * the daemon and re-emits them onto Code Buddy's internal event bus as
+ * `sensory:perception` events. Reactions (reactions.ts) subscribe to the bus.
+ *
+ * Opt-in via `CODEBUDDY_SENSORY=true` (wired in `buddy server`). Loopback-only +
+ * optional shared token. Never throws on a malformed frame.
+ *
+ * @module sensory/sensory-bridge
+ */
+export interface SensoryBridgeOptions {
+    host?: string;
+    port?: number;
+    /** If set, frames must carry a matching `token` field. */
+    token?: string;
+}
+export interface SensoryBridgeHandle {
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startSensoryBridge(options?: SensoryBridgeOptions): SensoryBridgeHandle;

package/dist/sensory/sensory-bridge.js

@@ -0,0 +1,85 @@
+/**
+ * Sensory bridge — the ingress for the Rust `buddy-sense` nervous-system daemon.
+ *
+ * A loopback-only WebSocket server that receives `SensoryEvent` JSON frames from
+ * the daemon and re-emits them onto Code Buddy's internal event bus as
+ * `sensory:perception` events. Reactions (reactions.ts) subscribe to the bus.
+ *
+ * Opt-in via `CODEBUDDY_SENSORY=true` (wired in `buddy server`). Loopback-only +
+ * optional shared token. Never throws on a malformed frame.
+ *
+ * @module sensory/sensory-bridge
+ */
+import { WebSocketServer } from 'ws';
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+/** The trust boundary: only known modalities pass; kinds are sanitized to a safe
+ * shape (no control chars / newlines, ≤64 chars) so a crafted local frame can't
+ * inject content downstream (e.g. into CODEBUDDY_MEMORY.md via dreaming). */
+const KNOWN_MODALITIES = new Set(['audio', 'vision', 'screen', 'vital', 'ui']);
+function sanitizeKind(kind) {
+    return kind.replace(/[^a-zA-Z0-9_:.-]/g, '').slice(0, 64);
+}
+export function startSensoryBridge(options = {}) {
+    const host = options.host ?? '127.0.0.1';
+    const port = options.port ?? Number(process.env.CODEBUDDY_SENSORY_PORT ?? 8129);
+    const token = options.token ?? process.env.CODEBUDDY_SENSORY_TOKEN;
+    const bus = getGlobalEventBus();
+    const wss = new WebSocketServer({ host, port });
+    wss.on('connection', (ws, req) => {
+        // Reject cross-origin (CSWSH): the Rust daemon sends NO Origin header; a
+        // browser page / extension always does. This stops a local web origin from
+        // injecting frames (and, with the camera reaction on, triggering the webcam).
+        if (req.headers.origin) {
+            ws.close();
+            return;
+        }
+        // Loopback-only: exact match, tolerating IPv4-mapped IPv6 (::ffff:127.0.0.1).
+        const remote = (req.socket.remoteAddress ?? '').replace(/^::ffff:/, '');
+        if (remote !== '127.0.0.1' && remote !== '::1') {
+            ws.close();
+            return;
+        }
+        logger.info('[sensory] daemon connected');
+        ws.on('message', (data) => {
+            let frame;
+            try {
+                frame = JSON.parse(String(data));
+            }
+            catch {
+                return; // ignore malformed
+            }
+            if (token && frame.token !== token)
+                return;
+            if (!frame.modality || !frame.kind)
+                return;
+            // Validate the string fields at the trust boundary (not just the numbers):
+            // unknown modality is dropped, kind is sanitized — blocks memory injection.
+            if (!KNOWN_MODALITIES.has(frame.modality))
+                return;
+            const kind = sanitizeKind(frame.kind);
+            if (!kind)
+                return;
+            // Validate/clamp numeric fields so a malformed frame can't poison downstream.
+            const salience = Number.isFinite(frame.salience) ? Math.max(0, Math.min(255, Math.round(frame.salience))) : 0;
+            const tsMs = Number.isFinite(frame.ts_ms) && frame.ts_ms >= 0 ? frame.ts_ms : undefined;
+            bus.emit('sensory:perception', {
+                source: 'buddy-sense',
+                metadata: {
+                    modality: frame.modality,
+                    kind,
+                    salience,
+                    tsMs,
+                    payload: frame.payload,
+                },
+            });
+        });
+    });
+    wss.on('error', (err) => logger.warn(`[sensory] bridge error: ${err instanceof Error ? err.message : String(err)}`));
+    logger.info(`[sensory] bridge listening on ws://${host}:${port}`);
+    return {
+        port,
+        close: () => new Promise((resolve) => wss.close(() => resolve())),
+    };
+}
+//# sourceMappingURL=sensory-bridge.js.map

package/dist/sensory/sensory-memory.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Short-term sensory memory — a bounded rolling buffer of recent perceptions
+ * (the nervous system's working memory). Reactions push every perception here;
+ * the dreaming consolidator drains + summarizes it into long-term memory every N
+ * heartbeats (like OpenClaw's dreaming: short-term recall → consolidated store).
+ *
+ * @module sensory/sensory-memory
+ */
+import type { Perception } from './reactions.js';
+export declare class SensoryMemory {
+    private readonly cap;
+    private buf;
+    constructor(cap?: number);
+    push(p: Perception): void;
+    snapshot(): Perception[];
+    /** Take everything and clear (consolidation consumes the window). */
+    drain(): Perception[];
+    size(): number;
+}
+export declare function getSensoryMemory(): SensoryMemory;

package/dist/sensory/sensory-memory.js

@@ -0,0 +1,39 @@
+/**
+ * Short-term sensory memory — a bounded rolling buffer of recent perceptions
+ * (the nervous system's working memory). Reactions push every perception here;
+ * the dreaming consolidator drains + summarizes it into long-term memory every N
+ * heartbeats (like OpenClaw's dreaming: short-term recall → consolidated store).
+ *
+ * @module sensory/sensory-memory
+ */
+export class SensoryMemory {
+    cap;
+    buf = [];
+    constructor(cap = 1000) {
+        this.cap = cap;
+    }
+    push(p) {
+        this.buf.push(p);
+        if (this.buf.length > this.cap)
+            this.buf.shift();
+    }
+    snapshot() {
+        return [...this.buf];
+    }
+    /** Take everything and clear (consolidation consumes the window). */
+    drain() {
+        const out = this.buf;
+        this.buf = [];
+        return out;
+    }
+    size() {
+        return this.buf.length;
+    }
+}
+let singleton;
+export function getSensoryMemory() {
+    if (!singleton)
+        singleton = new SensoryMemory();
+    return singleton;
+}
+//# sourceMappingURL=sensory-memory.js.map

package/dist/sensory/speech-reaction.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Speech reaction — closes the perception→cognition loop. On a `speech_end` event
+ * that carries the source WAV (the daemon tags it), transcribe the utterance (STT)
+ * and record what was heard as a `hearing` percept; an optional `onHeard` hook can
+ * drive further action (a turn, a command). DEBOUNCED (one transcription per
+ * utterance — the energy VAD over-segments), opt-in (`CODEBUDDY_SENSORY_SPEECH=true`),
+ * injectable transcriber, never-throws.
+ *
+ * @module sensory/speech-reaction
+ */
+export type Transcriber = (wav: string) => Promise<string>;
+export interface SpeechReactionOptions {
+    /** Injectable STT (tests / custom). Default: faster-whisper via python ($0). */
+    transcriber?: Transcriber;
+    debounceMs?: number;
+    cwd?: string;
+    now?: () => number;
+    /** Action hook for the transcript (e.g. trigger an agent turn). */
+    onHeard?: (text: string) => void | Promise<void>;
+}
+export declare function wireSpeechReaction(options?: SpeechReactionOptions): () => void;

package/dist/sensory/speech-reaction.js

@@ -0,0 +1,83 @@
+/**
+ * Speech reaction — closes the perception→cognition loop. On a `speech_end` event
+ * that carries the source WAV (the daemon tags it), transcribe the utterance (STT)
+ * and record what was heard as a `hearing` percept; an optional `onHeard` hook can
+ * drive further action (a turn, a command). DEBOUNCED (one transcription per
+ * utterance — the energy VAD over-segments), opt-in (`CODEBUDDY_SENSORY_SPEECH=true`),
+ * injectable transcriber, never-throws.
+ *
+ * @module sensory/speech-reaction
+ */
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+import { perceptionOf } from './reactions.js';
+/** Default transcriber: local faster-whisper (base), best-effort, $0. */
+async function defaultTranscribe(wav) {
+    const { spawn } = await import('child_process');
+    const model = process.env.CODEBUDDY_SPEECH_MODEL ?? 'base';
+    const py = [
+        'import sys',
+        'from faster_whisper import WhisperModel',
+        `m = WhisperModel(${JSON.stringify(model)}, device='cpu', compute_type='int8')`,
+        'segs, _ = m.transcribe(sys.argv[1])',
+        "print(' '.join(s.text for s in segs).strip())",
+    ].join('\n');
+    return new Promise((resolve) => {
+        const proc = spawn('python3', ['-c', py, wav], { stdio: ['ignore', 'pipe', 'ignore'] });
+        let out = '';
+        proc.stdout.on('data', (d) => (out += String(d)));
+        proc.on('close', () => resolve(out.trim()));
+        proc.on('error', () => resolve(''));
+    });
+}
+export function wireSpeechReaction(options = {}) {
+    const bus = getGlobalEventBus();
+    const debounceMs = options.debounceMs ?? Number(process.env.CODEBUDDY_SPEECH_DEBOUNCE_MS ?? 4000);
+    const now = options.now ?? (() => Date.now());
+    const transcribe = options.transcriber ?? defaultTranscribe;
+    let lastAt = Number.NEGATIVE_INFINITY;
+    let inFlight = false;
+    const id = bus.on('sensory:perception', (evt) => {
+        const p = perceptionOf(evt);
+        if (p.modality !== 'audio' || p.kind !== 'speech_end')
+            return;
+        const wav = p.payload?.wav;
+        if (!wav)
+            return; // no audio to transcribe (e.g. a live-mic path not yet wired)
+        const t = now();
+        if (t - lastAt < debounceMs)
+            return; // one transcription per utterance
+        if (inFlight)
+            return; // a prior STT (faster-whisper, seconds) is still running
+        lastAt = t;
+        inFlight = true;
+        void (async () => {
+            try {
+                const text = await transcribe(wav);
+                if (!text)
+                    return;
+                const { recordCompanionPercept } = await import('../companion/percepts.js');
+                await recordCompanionPercept({
+                    modality: 'hearing',
+                    source: 'sensory_speech_reaction',
+                    summary: `Heard: ${text}`,
+                    confidence: 0.8,
+                    payload: { text, wav },
+                    tags: ['speech', 'stt'],
+                }, options.cwd ? { cwd: options.cwd } : {});
+                logger.info(`[speech] heard → ${text}`);
+                await options.onHeard?.(text);
+            }
+            catch (err) {
+                logger.warn(`[speech] reaction failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                inFlight = false;
+            }
+        })();
+    });
+    return () => {
+        bus.off(id);
+    };
+}
+//# sourceMappingURL=speech-reaction.js.map

package/dist/sensory/vision-reaction.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Vision reaction — on a `vision/motion` event from the nervous-system daemon,
+ * run `camera_analyze` (capture a frame + describe it with a local gemma vision
+ * model) and record a companion percept. DEBOUNCED (gemma is heavy: 3–10s warm),
+ * opt-in (`CODEBUDDY_SENSORY_CAMERA=true`), best-effort, never-throws.
+ *
+ * @module sensory/vision-reaction
+ */
+export interface VisionAnalysis {
+    success: boolean;
+    description?: string;
+    imagePath?: string;
+}
+export interface VisionAnalyzer {
+    analyze(prompt: string): Promise<VisionAnalysis>;
+}
+export interface VisionReactionOptions {
+    /** Injectable analyzer (tests / custom). Defaults to camera_analyze (local gemma). */
+    analyzer?: VisionAnalyzer;
+    debounceMs?: number;
+    cwd?: string;
+    now?: () => number;
+}
+/** Security invariant (pure + testable): the camera reaction may only be wired
+ * when explicitly enabled AND a shared token is set — a crafted local frame can
+ * trigger the webcam, so an unauthenticated bridge must not be able to. */
+export declare function shouldWireVisionReaction(env: {
+    camera?: string;
+    token?: string;
+}): boolean;
+export declare function wireVisionReaction(options?: VisionReactionOptions): () => void;

package/dist/sensory/vision-reaction.js

@@ -0,0 +1,74 @@
+/**
+ * Vision reaction — on a `vision/motion` event from the nervous-system daemon,
+ * run `camera_analyze` (capture a frame + describe it with a local gemma vision
+ * model) and record a companion percept. DEBOUNCED (gemma is heavy: 3–10s warm),
+ * opt-in (`CODEBUDDY_SENSORY_CAMERA=true`), best-effort, never-throws.
+ *
+ * @module sensory/vision-reaction
+ */
+import { getGlobalEventBus } from '../events/event-bus.js';
+import { logger } from '../utils/logger.js';
+import { perceptionOf } from './reactions.js';
+/** Default analyzer: Code Buddy's camera_analyze tool (ffmpeg capture + local gemma). */
+async function defaultAnalyze(prompt) {
+    const { CameraAnalyzeTool } = await import('../tools/registry/vision-tools.js');
+    const tool = new CameraAnalyzeTool({});
+    const result = await tool.execute({ prompt });
+    const data = result.data;
+    return { success: result.success, description: data?.description ?? result.output, imagePath: data?.imagePath };
+}
+/** Security invariant (pure + testable): the camera reaction may only be wired
+ * when explicitly enabled AND a shared token is set — a crafted local frame can
+ * trigger the webcam, so an unauthenticated bridge must not be able to. */
+export function shouldWireVisionReaction(env) {
+    return env.camera === 'true' && Boolean(env.token);
+}
+export function wireVisionReaction(options = {}) {
+    const bus = getGlobalEventBus();
+    const debounceMs = options.debounceMs ?? Number(process.env.CODEBUDDY_VISION_DEBOUNCE_MS ?? 8000);
+    const now = options.now ?? (() => Date.now());
+    const analyzer = options.analyzer ?? { analyze: defaultAnalyze };
+    let lastAt = Number.NEGATIVE_INFINITY;
+    let inFlight = false;
+    const id = bus.on('sensory:perception', (evt) => {
+        const p = perceptionOf(evt);
+        if (p.modality !== 'vision' || p.kind !== 'motion')
+            return;
+        const t = now();
+        if (t - lastAt < debounceMs) {
+            logger.info('[vision] motion (debounced — analysis throttled)');
+            return;
+        }
+        if (inFlight)
+            return; // a prior analyze() (ffmpeg+gemma, 3–10s) is still running
+        lastAt = t;
+        inFlight = true;
+        void (async () => {
+            try {
+                const res = await analyzer.analyze('Motion detected — describe the scene in one sentence.');
+                if (!res.success)
+                    return;
+                const { recordCompanionPercept } = await import('../companion/percepts.js');
+                await recordCompanionPercept({
+                    modality: 'vision',
+                    source: 'sensory_motion_reaction',
+                    summary: `Motion → ${res.description ?? '(no description)'}`,
+                    confidence: 0.9,
+                    payload: { description: res.description, imagePath: res.imagePath },
+                    tags: ['motion', 'camera', 'vision'],
+                }, options.cwd ? { cwd: options.cwd } : {});
+                logger.info(`[vision] motion analyzed → ${res.description ?? '(no description)'}`);
+            }
+            catch (err) {
+                logger.warn(`[vision] reaction failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                inFlight = false;
+            }
+        })();
+    });
+    return () => {
+        bus.off(id);
+    };
+}
+//# sourceMappingURL=vision-reaction.js.map