@deepwatch/dsh-live 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oxbshw
+
+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.

package/README.md

@@ -0,0 +1,87 @@
+# @deepwatch/dsh-live
+
+Live mode — cursors, gaps, clocks, reconnect and a bounded buffer
+
+Part of **DeepWatch** — the agent workspace built on the official
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
+and powered by [Watch Skill](https://github.com/oxbshw/watch-skill) for perception, evidence, memory and
+independent verification.
+
+> **Host plugin — runs beside the agent in the DSH process.**
+> Composed by the bundle. Needed for live and browser sessions.
+
+## Exports
+
+- `@deepwatch/dsh-live`
+- `@deepwatch/dsh-live/capture`
+- `@deepwatch/dsh-live/client`
+- `@deepwatch/dsh-live/components`
+- `@deepwatch/dsh-live/live-mode`
+- `@deepwatch/dsh-live/sources-catalogue`
+- `@deepwatch/dsh-live/synthetic-source`
+
+## Peers
+
+Provided by the host rather than installed here:
+
+- `@deepseek-ai/cordis@4.0.2`
+- `react@^18.2.0`
+
+## Install
+
+> **Not on npm yet.** Nothing exists under the `@deepwatch` scope. This
+> package is published for the first time by the `deepwatch-v0.1.0`
+> release; until then the command below resolves nothing, and
+> [the workspace README](https://github.com/oxbshw/watch-skill/tree/main/workspace#readme) has the path
+> that works from a checkout.
+
+```sh
+npm install @deepwatch/dsh-live
+```
+
+Rarely on its own. [`@deepwatch/dsh-bundle`](https://github.com/oxbshw/watch-skill/tree/main/workspace/packages/watch/bundle#readme)
+composes this package with the rest of DeepWatch and is what a profile
+normally depends on; installing this one directly is for embedding a
+single piece in a composition you control.
+
+## Requirements
+
+- Node `^22.19.0 || >=24.0.0`
+- The peers above, supplied by the host composition
+
+Core built with the `[loop]` extra, and a browser installed by `playwright install chromium`, for anything that drives a page.
+
+## Stability
+
+`0.1.0` — a stable release.
+
+Stable means tested, documented and supported — not 1.0. This is a
+pre-1.0 line, and semantic versioning gives `0.x` no compatibility
+guarantee across minor versions: **a `0.MINOR` bump may change or remove
+surface, and a patch will not.** Depend on it with a tilde range
+(`~0.1.0`) if you want that difference enforced by your lockfile
+rather than by a changelog. The usual major-version promise starts at 1.0.
+
+## Side effects
+
+Importing a module from this package evaluates no side effects, so a
+bundler may drop what a build does not use. Mounting it in a host is a
+separate matter: what it then reads or writes is governed by the
+workspace boundary and the host's permissions, not by this flag.
+
+## Where this fits
+
+One clock across streams, with cursors, declared gaps, a bounded buffer and a reconnect policy — so "what was on screen when that was said" has an answer rather than a guess.
+
+The twenty packages and how they compose:
+[the package map](https://github.com/oxbshw/watch-skill/blob/main/workspace/docs/packages.md).
+Running DeepWatch, and the gates a change has to pass:
+[the workspace README](https://github.com/oxbshw/watch-skill/tree/main/workspace#readme).
+
+## Attribution
+
+Built on DeepSeek Harness · Powered by Watch Skill
+
+DeepWatch and Watch Skill are independent projects and are not affiliated
+with or endorsed by DeepSeek. MIT licensed; third-party notices are in
+[THIRD_PARTY_NOTICES.md](https://github.com/oxbshw/watch-skill/blob/main/workspace/THIRD_PARTY_NOTICES.md).

package/lib/capture.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The live capture lifecycle.
+ *
+ * A session is a small state machine, and writing it as one is the point: every
+ * way a capture can end — stopped, cancelled, timed out, denied, failed, the
+ * source disappearing underneath it — is a named state with a named transition
+ * rather than an early return somewhere. The states that get skipped in ad-hoc
+ * implementations are exactly the ones that leak: a cancel during startup, a
+ * source vanishing mid-stream, a stop arriving twice.
+ *
+ * Three rules hold the design together.
+ *
+ * **Permission is never implied.** A session moves `idle → requested →
+ * granted` only through an explicit call that a user action caused. Nothing in
+ * construction, discovery or rendering asks for anything; a prompt on page load
+ * teaches people to allow without reading, and after that the prompt means
+ * nothing.
+ *
+ * **Observing is not operating.** The browser appears twice in the source
+ * catalogue because watching a page and acting on one carry different
+ * consequences. A single capability would grant the second while a person
+ * believed they were enabling the first.
+ *
+ * **Stopping always releases.** `stop`, `cancel`, `fail` and `timeout` all run
+ * the same teardown, exactly once, whatever order they arrive in. A capture
+ * that leaks a handle on the unhappy path leaks it on the path that actually
+ * happens.
+ *
+ * @module @deepwatch/dsh-live/capture
+ */
+/** Where a session is. Every terminal state is reachable and named. */
+export type CaptureState = 'idle' | 'requesting_permission' | 'starting' | 'active' | 'paused' | 'stopping' | 'stopped' | 'cancelled' | 'denied' | 'unavailable' | 'timed_out' | 'failed';
+/** Whether the person has agreed, and whether they were ever asked. */
+export type PermissionState = 'not_requested' | 'requested' | 'granted' | 'denied';
+/** One thing the source produced, with the clock that makes it citable. */
+export interface Observation {
+    readonly observationId: string;
+    /** ISO-8601. An observation without a time cannot be cited. */
+    readonly at: string;
+    readonly kind: 'frame' | 'audio' | 'text' | 'event';
+    /** What was observed. Verbatim; never a summary. */
+    readonly text: string;
+    /** Milliseconds from the session's start, for a relative timeline. */
+    readonly offsetMs: number;
+}
+/** The receipt a finished session leaves behind. */
+export interface CaptureReceipt {
+    readonly sessionId: string;
+    readonly sourceId: string;
+    readonly runId: string | null;
+    readonly startedAt: string | null;
+    readonly endedAt: string | null;
+    readonly finalState: CaptureState;
+    readonly observationCount: number;
+    /** Why it ended, in words. Empty for an ordinary stop. */
+    readonly reason: string;
+    /**
+     * Evidence minted from this session, if any.
+     *
+     * Always empty here. A capture produces observations; only Watch Core turns
+     * an observation into evidence, and this module cannot and must not.
+     */
+    readonly evidenceIds: readonly string[];
+}
+/** A source's own view of itself, before anything has been started. */
+export interface SourceAvailability {
+    readonly available: boolean;
+    /** Why not, when not. Shown to a person, so it has to be actionable. */
+    readonly reason: string;
+}
+/**
+ * What a real source has to provide.
+ *
+ * Deliberately tiny. An adapter that can be described in four methods can be
+ * tested deterministically with a fake, which is what lets the lifecycle above
+ * be exercised on a machine that has no camera.
+ */
+export interface CaptureAdapter {
+    readonly sourceId: string;
+    /** Can this run here, now? Must not prompt and must not open anything. */
+    probe(): Promise<SourceAvailability> | SourceAvailability;
+    /** Ask the person. Called only from an explicit user action. */
+    requestPermission(): Promise<boolean> | boolean;
+    /** Begin producing. `emit` may be called until `stop` resolves. */
+    start(emit: (observation: Observation) => void): Promise<void> | void;
+    /** Release everything. Must be safe to call more than once. */
+    stop(): Promise<void> | void;
+}
+export interface CaptureOptions {
+    readonly sessionId: string;
+    readonly runId?: string | null;
+    /** Give up if the source has not started within this long. */
+    readonly startTimeoutMs?: number;
+    /** Injected so tests are not slow and not flaky. */
+    readonly now?: () => Date;
+}
+/** One live capture, from nothing to a receipt. */
+export declare class CaptureSession {
+    #private;
+    readonly sessionId: string;
+    readonly sourceId: string;
+    readonly runId: string | null;
+    constructor(adapter: CaptureAdapter, options: CaptureOptions);
+    get state(): CaptureState;
+    get permission(): PermissionState;
+    get observations(): readonly Observation[];
+    get startedAt(): string | null;
+    get reason(): string;
+    /** True once the session can no longer change state. */
+    get finished(): boolean;
+    subscribe(listener: (session: CaptureSession) => void): () => void;
+    /**
+     * Ask whether the source can run here.
+     *
+     * Explicitly not a permission request. Probing must be safe to do while
+     * rendering a list of sources, so an adapter that prompted here would make
+     * merely opening the tab ask for the camera.
+     */
+    probe(): Promise<SourceAvailability>;
+    /**
+     * Ask the person for permission.
+     *
+     * Called only from an explicit user action — that is the contract, and the
+     * reason `start` refuses to do it implicitly.
+     */
+    requestPermission(): Promise<boolean>;
+    /**
+     * Begin capturing.
+     *
+     * Refuses without permission rather than requesting it. A start that silently
+     * prompts is a start that can be triggered by something other than a person,
+     * and the whole point of the boundary is that it cannot.
+     */
+    start(): Promise<boolean>;
+    /** Stop producing without ending the session. */
+    pause(): boolean;
+    resume(): boolean;
+    /** End normally. Safe to call twice; the second call is a no-op. */
+    stop(): Promise<CaptureReceipt>;
+    /**
+     * End before it began, or during startup.
+     *
+     * Distinct from `stop` because the states differ for a person: a cancelled
+     * capture produced nothing on purpose, a stopped one produced what it
+     * produced.
+     */
+    cancel(reason?: string): Promise<CaptureReceipt>;
+    /** The source went away underneath us. */
+    sourceLost(reason: string): Promise<CaptureReceipt>;
+    /** What happened, in a form that outlives the session object. */
+    receipt(): CaptureReceipt;
+}
+/** Build an observation with a clock, so it can be cited. */
+export declare function observationAt(base: Date, now: Date, kind: Observation['kind'], text: string, index: number): Observation;
+//# sourceMappingURL=capture.d.ts.map

package/lib/capture.js

@@ -0,0 +1,301 @@
+/**
+ * The live capture lifecycle.
+ *
+ * A session is a small state machine, and writing it as one is the point: every
+ * way a capture can end — stopped, cancelled, timed out, denied, failed, the
+ * source disappearing underneath it — is a named state with a named transition
+ * rather than an early return somewhere. The states that get skipped in ad-hoc
+ * implementations are exactly the ones that leak: a cancel during startup, a
+ * source vanishing mid-stream, a stop arriving twice.
+ *
+ * Three rules hold the design together.
+ *
+ * **Permission is never implied.** A session moves `idle → requested →
+ * granted` only through an explicit call that a user action caused. Nothing in
+ * construction, discovery or rendering asks for anything; a prompt on page load
+ * teaches people to allow without reading, and after that the prompt means
+ * nothing.
+ *
+ * **Observing is not operating.** The browser appears twice in the source
+ * catalogue because watching a page and acting on one carry different
+ * consequences. A single capability would grant the second while a person
+ * believed they were enabling the first.
+ *
+ * **Stopping always releases.** `stop`, `cancel`, `fail` and `timeout` all run
+ * the same teardown, exactly once, whatever order they arrive in. A capture
+ * that leaks a handle on the unhappy path leaks it on the path that actually
+ * happens.
+ *
+ * @module @deepwatch/dsh-live/capture
+ */
+const DEFAULT_START_TIMEOUT = 10_000;
+/** One live capture, from nothing to a receipt. */
+export class CaptureSession {
+    sessionId;
+    sourceId;
+    runId;
+    #adapter;
+    #state = 'idle';
+    #permission = 'not_requested';
+    #observations = [];
+    #startedAt = null;
+    #endedAt = null;
+    #reason = '';
+    #now;
+    #startTimeout;
+    #torndown = false;
+    #timer = null;
+    #listeners = new Set();
+    constructor(adapter, options) {
+        this.#adapter = adapter;
+        this.sessionId = options.sessionId;
+        this.sourceId = adapter.sourceId;
+        this.runId = options.runId ?? null;
+        this.#now = options.now ?? (() => new Date());
+        this.#startTimeout = options.startTimeoutMs ?? DEFAULT_START_TIMEOUT;
+    }
+    get state() { return this.#state; }
+    get permission() { return this.#permission; }
+    get observations() { return this.#observations; }
+    get startedAt() { return this.#startedAt?.toISOString() ?? null; }
+    get reason() { return this.#reason; }
+    /** True once the session can no longer change state. */
+    get finished() {
+        return ['stopped', 'cancelled', 'denied', 'unavailable', 'timed_out', 'failed'].includes(this.#state);
+    }
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => { this.#listeners.delete(listener); };
+    }
+    #announce() {
+        for (const listener of this.#listeners)
+            listener(this);
+    }
+    #settle(state, reason) {
+        if (this.finished)
+            return;
+        this.#state = state;
+        this.#reason = reason;
+        this.#endedAt = this.#now();
+        this.#announce();
+    }
+    /**
+     * Ask whether the source can run here.
+     *
+     * Explicitly not a permission request. Probing must be safe to do while
+     * rendering a list of sources, so an adapter that prompted here would make
+     * merely opening the tab ask for the camera.
+     */
+    async probe() {
+        const availability = await this.#adapter.probe();
+        if (!availability.available && this.#state === 'idle') {
+            this.#state = 'unavailable';
+            this.#reason = availability.reason;
+            this.#announce();
+        }
+        return availability;
+    }
+    /**
+     * Ask the person for permission.
+     *
+     * Called only from an explicit user action — that is the contract, and the
+     * reason `start` refuses to do it implicitly.
+     */
+    async requestPermission() {
+        if (this.finished)
+            return this.#permission === 'granted';
+        this.#state = 'requesting_permission';
+        this.#permission = 'requested';
+        this.#announce();
+        let granted = false;
+        try {
+            granted = await this.#adapter.requestPermission();
+        }
+        catch (error) {
+            this.#permission = 'denied';
+            this.#settle('failed', `The permission request failed: ${String(error)}`);
+            return false;
+        }
+        if (!granted) {
+            this.#permission = 'denied';
+            this.#settle('denied', 'Permission was refused. Nothing was captured.');
+            return false;
+        }
+        this.#permission = 'granted';
+        this.#state = 'idle';
+        this.#announce();
+        return true;
+    }
+    /**
+     * Begin capturing.
+     *
+     * Refuses without permission rather than requesting it. A start that silently
+     * prompts is a start that can be triggered by something other than a person,
+     * and the whole point of the boundary is that it cannot.
+     */
+    async start() {
+        if (this.finished)
+            return false;
+        if (this.#permission !== 'granted') {
+            this.#settle('denied', 'Start needs permission, and permission is only ever asked for by an explicit action.');
+            return false;
+        }
+        const availability = await this.#adapter.probe();
+        if (!availability.available) {
+            this.#settle('unavailable', availability.reason);
+            return false;
+        }
+        this.#state = 'starting';
+        this.#startedAt = this.#now();
+        this.#announce();
+        // A source that never starts must not hold the session open forever.
+        const timedOut = new Promise(resolve => {
+            this.#timer = setTimeout(() => { resolve('timeout'); }, this.#startTimeout);
+        });
+        try {
+            const outcome = await Promise.race([
+                Promise.resolve(this.#adapter.start(observation => { this.#record(observation); })).then(() => 'started'),
+                timedOut,
+            ]);
+            this.#clearTimer();
+            // A cancel that arrived while we were starting wins. Without this check
+            // the session would come back to life after the user stopped it.
+            //
+            // The adapter is stopped directly rather than through `#teardown`, and
+            // that distinction is the whole fix for a real leak: the cancel already
+            // ran teardown, so the once-guard is set — but it ran *before* the
+            // adapter allocated anything, so it stopped nothing. Whatever `start`
+            // just created would have been left running forever. The adapter
+            // contract requires `stop` to be safe more than once precisely so this
+            // case can be handled without tracking who allocated what.
+            if (this.finished) {
+                try {
+                    await this.#adapter.stop();
+                }
+                catch {
+                    // Nothing left to do: the session has already ended.
+                }
+                return false;
+            }
+            if (outcome === 'timeout') {
+                await this.#teardown();
+                this.#settle('timed_out', `The source did not start within ${String(this.#startTimeout)}ms.`);
+                return false;
+            }
+        }
+        catch (error) {
+            this.#clearTimer();
+            await this.#teardown();
+            this.#settle('failed', `The source failed to start: ${String(error)}`);
+            return false;
+        }
+        this.#state = 'active';
+        this.#announce();
+        return true;
+    }
+    /** Record an observation. Ignored unless the session is actually running. */
+    #record(observation) {
+        if (this.#state !== 'active')
+            return;
+        this.#observations.push(observation);
+        this.#announce();
+    }
+    /** Stop producing without ending the session. */
+    pause() {
+        if (this.#state !== 'active')
+            return false;
+        this.#state = 'paused';
+        this.#announce();
+        return true;
+    }
+    resume() {
+        if (this.#state !== 'paused')
+            return false;
+        this.#state = 'active';
+        this.#announce();
+        return true;
+    }
+    /** End normally. Safe to call twice; the second call is a no-op. */
+    async stop() {
+        if (!this.finished) {
+            this.#state = 'stopping';
+            this.#announce();
+            await this.#teardown();
+            this.#settle('stopped', '');
+        }
+        return this.receipt();
+    }
+    /**
+     * End before it began, or during startup.
+     *
+     * Distinct from `stop` because the states differ for a person: a cancelled
+     * capture produced nothing on purpose, a stopped one produced what it
+     * produced.
+     */
+    async cancel(reason = 'Cancelled.') {
+        if (!this.finished) {
+            await this.#teardown();
+            this.#settle('cancelled', reason);
+        }
+        return this.receipt();
+    }
+    /** The source went away underneath us. */
+    async sourceLost(reason) {
+        if (!this.finished) {
+            await this.#teardown();
+            this.#settle('unavailable', reason);
+        }
+        return this.receipt();
+    }
+    #clearTimer() {
+        if (this.#timer !== null) {
+            clearTimeout(this.#timer);
+            this.#timer = null;
+        }
+    }
+    /**
+     * Release everything, exactly once.
+     *
+     * Every ending routes through here, and the guard is what makes that safe: a
+     * stop racing a timeout would otherwise call the adapter's `stop` twice, and
+     * an adapter is entitled to assume it is torn down once.
+     */
+    async #teardown() {
+        this.#clearTimer();
+        if (this.#torndown)
+            return;
+        this.#torndown = true;
+        try {
+            await this.#adapter.stop();
+        }
+        catch {
+            // A teardown that throws must not prevent the session from ending; the
+            // alternative is a session stuck in `stopping` forever.
+        }
+    }
+    /** What happened, in a form that outlives the session object. */
+    receipt() {
+        return {
+            sessionId: this.sessionId,
+            sourceId: this.sourceId,
+            runId: this.runId,
+            startedAt: this.#startedAt?.toISOString() ?? null,
+            endedAt: this.#endedAt?.toISOString() ?? null,
+            finalState: this.#state,
+            observationCount: this.#observations.length,
+            reason: this.#reason,
+            evidenceIds: [],
+        };
+    }
+}
+/** Build an observation with a clock, so it can be cited. */
+export function observationAt(base, now, kind, text, index) {
+    return {
+        observationId: `obs-${String(index)}`,
+        at: now.toISOString(),
+        kind,
+        text,
+        offsetMs: Math.max(0, now.getTime() - base.getTime()),
+    };
+}
+//# sourceMappingURL=capture.js.map

package/lib/client/components.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The Live surface.
+ *
+ * The header is deliberately busy. A live view's job is to be trustworthy
+ * about time, and that means the clocks, the latency, the connection state and
+ * the continuity line are all present at once rather than behind a disclosure.
+ * The moment one of them is hidden, the surface starts implying a continuity
+ * it has not checked.
+ *
+ * @module @deepwatch/dsh-live/components
+ */
+import type { ReactNode } from 'react';
+import { type LiveEvent, type LiveSessionState } from '../session.js';
+/** Props for {@link LiveHeader}. */
+export interface LiveHeaderProps {
+    readonly state: LiveSessionState;
+}
+/**
+ * Session, media and wall clocks, side by side.
+ *
+ * Three readings rather than one, because they answer three questions and
+ * disagree constantly during a live observation. A single "time" field would
+ * be right about one of them and quietly wrong about the other two.
+ */
+export declare function LiveHeader({ state }: LiveHeaderProps): ReactNode;
+/** Props for {@link LiveEventRow}. */
+export interface LiveEventRowProps {
+    readonly event: LiveEvent;
+    readonly onSelect: (event: LiveEvent) => void;
+}
+/**
+ * One observed event.
+ *
+ * A gap draws as a gap — dashed, glyphed and labelled — and is never
+ * collapsed into the events around it.
+ */
+export declare function LiveEventRow({ event, onSelect }: LiveEventRowProps): ReactNode;
+/** Props for {@link LiveSurface}. */
+export interface LiveSurfaceProps {
+    readonly state: LiveSessionState;
+    readonly onStart: () => void;
+    readonly onStop: (finalize: boolean) => void;
+    readonly onAsk: (question: string) => void;
+    readonly onSelect: (event: LiveEvent) => void;
+    readonly onPin: () => void;
+}
+/**
+ * The Live mode body.
+ *
+ * `Resnapshot needed` is rendered as a banner rather than a toast. A transient
+ * notification for "your view of this is not continuous" is a notification
+ * that will be missed exactly when it matters.
+ */
+export declare function LiveSurface(props: LiveSurfaceProps): ReactNode;
+//# sourceMappingURL=components.d.ts.map