@scalebrowser/sdk 0.4.1 → 0.5.0

package/dist/index.d.ts

@@ -106,6 +106,281 @@ interface Persona {
     misc: PersonaMisc;
 }
 
+type RecordingKind = 'showcase' | 'proof';
+type RecordingState = 'recording' | 'finishing' | 'finished' | 'failed';
+type VideoState = 'queued' | 'rendering' | 'done' | 'failed' | 'cancelled';
+type ExportPresetName = 'web' | 'social' | '4k' | 'editing' | 'gif';
+type AudioStatus = 'ok' | 'silent' | 'off' | 'failed';
+type RenderStage = 'planning' | 'narration' | 'compositing' | 'encoding' | 'finishing';
+/** Which files a finished video has. Booleans on purpose, never paths. */
+interface VideoAssets {
+    video: boolean;
+    poster: boolean;
+    preview_gif: boolean;
+    srt: boolean;
+    vtt: boolean;
+    proof: boolean;
+    timestamp: boolean;
+    extras: ExportPresetName[];
+}
+interface RenderProgress {
+    stage: RenderStage;
+    frames_done: number;
+    frames_total: number | null;
+    eta_ms: number | null;
+    /** Which attempt this is; three is the last one. */
+    attempts: number;
+    heartbeat_at: number;
+}
+/** A chapter in OUTPUT time: it survives cuts and time-lapse. */
+interface Chapter {
+    out_ms: number;
+    src_ms: number;
+    label: string;
+    mark_id?: string | null;
+    step_seq?: number | null;
+}
+interface VideoFlags {
+    page_audio: AudioStatus;
+    tightened: boolean;
+    masked_regions: number;
+    gaps: number;
+    ai_label: boolean;
+    gpu: string;
+    h264_profile: string;
+}
+type TimestampState = {
+    state: 'pending';
+} | {
+    state: 'stamped';
+    at: number;
+    tsa: string;
+} | {
+    state: 'failed';
+    reason: string;
+};
+interface TranscriptWord {
+    text: string;
+    from_ms: number;
+    to_ms: number;
+}
+/** One video row: queued and rendering renders included. */
+interface Video {
+    id: string;
+    recording_id: string;
+    run_id: string | null;
+    profile_id: string;
+    job_id: string | null;
+    state: VideoState;
+    progress: RenderProgress | null;
+    title: string;
+    kind: RecordingKind;
+    preset_name: string;
+    /** The resolved recipe this video renders (or rendered) under. */
+    preset: unknown;
+    export: ExportPresetName;
+    assets: VideoAssets;
+    duration_ms: number | null;
+    width: number | null;
+    height: number | null;
+    fps: number | null;
+    bytes: number | null;
+    sha256: string | null;
+    timestamp: TimestampState | null;
+    chapters: Chapter[];
+    transcript: TranscriptWord[] | null;
+    flags: VideoFlags | null;
+    share: unknown | null;
+    error: string | null;
+    created_at: number;
+    updated_at: number;
+}
+/** One recording row. The row outlives its raw bytes (`raw_purged_at`). */
+interface Recording {
+    id: string;
+    profile_id: string;
+    run_id: string | null;
+    fence: number;
+    kind: RecordingKind;
+    state: RecordingState;
+    title: string | null;
+    preset_id: string | null;
+    preset: unknown;
+    manifest_version: number;
+    css_width: number;
+    css_height: number;
+    dpr: number;
+    capture_width: number;
+    started_at: number;
+    ended_at: number | null;
+    duration_ms: number | null;
+    frames: number;
+    frames_dropped: number;
+    gaps: number;
+    anchors: number;
+    bytes: number;
+    audio: AudioStatus;
+    audio_reason: string | null;
+    end_reason: string | null;
+    raw_purged_at: number | null;
+    purge_after: number | null;
+    error: string | null;
+}
+interface NarrationLine {
+    mark_id?: string;
+    step_seq?: number;
+    text: string;
+}
+/**
+ * Where a directing intent looks. `region` coordinates are page fractions
+ * in 0..1; the other kinds need no coordinates.
+ */
+interface ShotFocus {
+    kind: 'overview' | 'target' | 'container' | 'region';
+    x?: number;
+    y?: number;
+    w?: number;
+    h?: number;
+}
+/**
+ * One directing intent: you decide WHAT is on screen at a moment, the
+ * camera executes it smoothly and keeps its guarantees. Anchor it to one
+ * action (`at_anchor`, the ids listed in `plan.actions`) or to a source
+ * moment (`at_ms`). Malformed intents are refused as `shot_invalid`;
+ * anchors the recording does not know are skipped with a note.
+ */
+interface ShotIntent {
+    at_anchor?: string;
+    at_ms?: number;
+    focus: ShotFocus;
+    zoom?: 'off' | 'gentle' | 'medium' | 'strong';
+    /** Minimum dwell in ms before the next camera move (max 20000). */
+    hold_ms?: number;
+    note?: string;
+}
+/** The shared render-order schema (SPEC §5.2: one producer, every surface). */
+interface RenderRequestBody {
+    preset?: string;
+    export?: ExportPresetName;
+    title?: string;
+    subtitle?: string;
+    /** `auto`, or a BCP-47 tag such as `de` or `en-US`. */
+    language?: string;
+    narration?: NarrationLine[];
+    /** Directing intents; empty means the built-in direction decides. */
+    shots?: ShotIntent[];
+}
+interface ListVideosParams {
+    q?: string;
+    profile_id?: string;
+    run_id?: string;
+    kind?: RecordingKind;
+    preset?: string;
+    state?: VideoState;
+    page?: number;
+}
+interface VideosPage {
+    videos: Video[];
+    next: number | null;
+}
+/**
+ * Which file an access grant is minted for.
+ *
+ * The extras carry the same prefix the daemon's own key register uses
+ * (`extra:<preset>`), so a second export is reachable under the name it was
+ * stored with rather than a name a caller invents.
+ */
+type VideoAssetName = 'video' | 'poster' | 'preview' | 'srt' | 'vtt' | 'proof' | 'timestamp' | `extra:${ExportPresetName}`;
+interface VideoAccessGrant {
+    /** Relative URL carrying the grant; fetch it against the daemon base. */
+    url: string;
+    expires_at: number;
+}
+interface VideosStorage {
+    recordings_bytes: number;
+    videos_bytes: number;
+    link_bytes: number;
+    link_limit: number;
+    uploads_today: number;
+    uploads_limit: number;
+    capacity: {
+        recordings_active: number;
+        recordings_max: number;
+    };
+}
+/** What the machine can encode with, and the one switch an operator has. */
+interface CodecsStatus {
+    openh264: {
+        /** The operator's decision. */
+        enabled: boolean;
+        /** Measured now: the library is on disk and its hash is the pinned one. */
+        installed: boolean;
+        version: string | null;
+        /** `downloaded` | `manual` | `absent`. */
+        source: string;
+        notice: string;
+    };
+    /** Hardware encoders that passed a real test encode, in preference order. */
+    hardware: string[];
+}
+/** What kind of file a media asset is. */
+type MediaKind = 'image' | 'music' | 'subtitle_style';
+/** One uploaded file a preset refers to by id. */
+interface MediaAsset {
+    id: string;
+    kind: MediaKind;
+    name: string;
+    mime: string;
+    bytes: number;
+    /** The content's checksum. It is also the file name on disk, so the same
+     *  bytes are stored once however often they are uploaded. */
+    sha256: string;
+    created_at: number;
+}
+/** A speech provider that has a key stored.
+ *
+ *  There is deliberately no `api_key` here: the daemon answers with a hint and
+ *  never with the value. A client that could read it back would be the one
+ *  place it lands in a log again. */
+interface TtsProviderView {
+    provider: 'elevenlabs' | 'fish_audio' | 'openai';
+    /** The last few characters, never more. */
+    key_hint: string;
+    label: string | null;
+    verified_at: number | null;
+    updated_at: number;
+}
+/** What one real call to the provider proved.
+ *
+ *  A stored key and a working key are two things, so this speaks a short word
+ *  and reports what came back. Only an answer that carried both audio and word
+ *  timings counts: a 200 with an empty body proves nothing.
+ */
+interface TtsVerifyResult {
+    provider: 'elevenlabs' | 'fish_audio' | 'openai';
+    /** Unix seconds. The same value the provider row now carries. */
+    verified_at: number;
+    wav_bytes: number;
+    words: number;
+}
+/** Where a share link stands ON THIS MACHINE: an order, not a copy.
+ *
+ *  `outbox` is what is still owed: `pending` while the files are going up,
+ *  `live` once the control plane confirmed, `revoke_pending` after a revoke that
+ *  has not been acknowledged yet. A revoke-pending link STILL BLOCKS: between
+ *  the order and the confirmation the page may still answer. */
+interface ShareLinkLocal {
+    link_id: string;
+    url: string;
+    version: number;
+    outbox: 'pending' | 'live' | 'revoke_pending';
+    /** Whether the link asks for an access code. Never the code itself. */
+    passcode: boolean;
+    download: boolean;
+    updated_at: number;
+    error: string | null;
+}
+
 /**
  * Wire types: a 1:1 mirror of the daemon's serialized domain model
  * (`crates/core/src/model.rs`, `persona.rs`, `events.rs`) and the endpoint
@@ -227,6 +502,211 @@ interface Preset {
     config: PresetConfig;
     created_at: number;
 }
+/** Was hinter der Seite liegt: ein Verlauf, eine Farbe, ein Bild, oder nichts. */
+type VideoBackground = {
+    kind: 'gradient';
+    colors: string[];
+} | {
+    kind: 'solid';
+    color: string;
+} | {
+    kind: 'image';
+    media_id: string;
+} | {
+    kind: 'none';
+};
+/** Intro und Outro. `hold_result` haelt das letzte Bild statt einer Karte. */
+type VideoCard = {
+    style: 'title_card';
+    seconds: number;
+} | {
+    style: 'hold_result';
+    seconds: number;
+};
+/** Wohin das fertige Video geht. */
+type VideoDestination = {
+    kind: 'local';
+} | {
+    kind: 'link';
+    expires_days: number | null;
+    download: boolean;
+    passcode: boolean;
+};
+/** Eine Zusatz-Ausgabe mit eigenen Massen. Objekte, nie blosse Strings. */
+interface ExtraOutput {
+    preset: ExportPresetName;
+    width?: number | null;
+    height?: number | null;
+    fps?: number | null;
+    colors?: number | null;
+    max_bytes?: number | null;
+}
+/** Hintergrundmusik, per Medien-Id, mit dem Pegel. */
+interface MusicBed {
+    media_id: string;
+    gain_db: number;
+}
+/**
+ * Das Rezept eines Videos: alles ueber die FORM, nichts ueber den Inhalt.
+ *
+ * Schritte, Laenge, Titel und Sprechtext kommen aus dem Auftrag, nie von hier
+ * (AC-CTL-001); das einzige freie Textfeld ist `ai_label.text`.
+ */
+interface VideoPresetConfig {
+    output: {
+        aspect: '16:9' | '9:16' | '1:1';
+        resolution: '720p' | '1080p' | '4k';
+        fps: number;
+    };
+    frame: {
+        background: VideoBackground;
+        padding_pct: number;
+        corner_radius_px: number;
+        shadow: 'none' | 'soft' | 'hard';
+        inset_px: number;
+        window_chrome: 'none' | 'plain' | 'address_bar';
+    };
+    cursor: {
+        scale: number;
+        style: 'arrow_dark' | 'arrow_light' | 'dot' | 'touch';
+        click: 'ripple' | 'ring' | 'none';
+        /** `null` haelt den Zeiger fuer immer sichtbar. */
+        hide_after_ms: number | null;
+        loop: boolean;
+    };
+    camera: {
+        zoom: 'off' | 'gentle' | 'medium' | 'strong';
+        motion_blur: boolean;
+        tightening: 'none' | 'normal' | 'strong';
+        ride: 'calm' | 'standard' | 'brisk';
+        zoom_scope: 'canvas' | 'card';
+    };
+    audio: {
+        /** `"<anbieter>:<stimme>"` oder `null` fuer ein stummes Video. */
+        voice: string | null;
+        language: string;
+        subtitles: 'burned' | 'file' | 'off';
+        subtitle_style: string;
+        page_audio: boolean;
+        music: MusicBed | null;
+    };
+    cards: {
+        intro: VideoCard | null;
+        outro: VideoCard | null;
+    };
+    masking: {
+        level: 'off' | 'secrets' | 'secrets_and_ids';
+        style: 'bar' | 'pixelate' | 'blur' | 'placeholder';
+    };
+    export: {
+        preset: ExportPresetName;
+        also: ExtraOutput[];
+        destination: VideoDestination;
+    };
+    ai_label: {
+        enabled: boolean;
+        text: string;
+        position: 'top_left' | 'top_right' | 'bottom_left' | 'bottom_right';
+    };
+}
+/**
+ * A video RECIPE: how a recording becomes a video (`/v1/video-presets`).
+ *
+ * `config` was an open object for a long time, on the argument that a second
+ * TypeScript copy of a two-dozen-enum schema is a second place for it to rot.
+ * The copy exists now because a form over an open object is a pile of casts and
+ * a typo in it only surfaces as a 400 after somebody pressed save; what took
+ * the argument's teeth is that the copy is held against the Rust source field
+ * by field (`preset-schema-mirror`), so it cannot rot quietly.
+ */
+interface VideoPreset {
+    id: string;
+    name: string;
+    /** Shipped with the product; can be duplicated but not edited or deleted. */
+    builtin: boolean;
+    config: VideoPresetConfig;
+    created_at: number;
+    updated_at: number;
+}
+/** One named frame of the sample film the preview can jump to, with the clip window around it. */
+interface PreviewMoment {
+    key: string;
+    label: string;
+    frame: number;
+    from: number;
+    to: number;
+}
+/** A preset field the sample film cannot show, and why. */
+interface PreviewHidden {
+    field: string;
+    why: string;
+}
+/** `POST /v1/video-presets/preview`: one still of the sample film under an unsaved config. */
+interface VideoPresetPreviewBody {
+    config: VideoPresetConfig;
+    frame?: number;
+    moment?: string;
+    name?: string;
+    /** Draw at this short side instead of the recipe's own, 360 to 2160. */
+    proxy_short_side?: number;
+}
+/** The reply: the picture as a data URL plus what the film looks like under this config. */
+interface VideoPresetPreview {
+    width: number;
+    height: number;
+    fps: number;
+    frames: number;
+    frame: number;
+    moments: PreviewMoment[];
+    hidden: PreviewHidden[];
+    notes: string[];
+    image: string;
+}
+/** `POST /v1/video-presets/preview/clip`: frames `from_frame..to_frame` of the sample film as an MP4. */
+interface VideoPresetClipBody {
+    config: VideoPresetConfig;
+    /** Absent means the start of the film. */
+    from_frame?: number;
+    /** Exclusive; absent means the end of the film. */
+    to_frame?: number;
+    name?: string;
+    /** Draw at this short side instead of the recipe's own, 360 to 2160. */
+    proxy_short_side?: number;
+}
+/** One progress frame of the clip's SSE stream (`event: progress`). */
+interface VideoPresetClipProgress {
+    done: number;
+    total: number;
+}
+/**
+ * `event: started`, the FIRST frame of the SSE answer: the id under which the
+ * bytes can already be followed (`?follow=1`), and the shape of the film.
+ *
+ * It exists so a player can begin while the render still runs. Without it the
+ * id arrives with `done`, and by then there is nothing left to follow.
+ */
+interface VideoPresetClipStarted {
+    id: string;
+    frames: number;
+    fps: number;
+    width: number;
+    height: number;
+}
+/** The finished clip (`event: done`, or the blocking JSON reply); the bytes come from `GET /v1/video-presets/preview/clip/:id`. */
+interface VideoPresetClip {
+    id: string;
+    from_frame: number;
+    to_frame: number;
+    fps: number;
+    width: number;
+    height: number;
+    frames: number;
+    seconds: number;
+    bytes: number;
+    encoder: string;
+    cached: boolean;
+    audio: boolean;
+}
 /** `GET /v1/persona/constraints`: the values a preset may constrain to. */
 interface PersonaConstraintOptions {
     countries: string[];
@@ -329,7 +809,7 @@ type TrustedInputBody = {
     delta_y?: number;
     humanize?: boolean;
 };
-/** Who is driving: an agent holding a reservation, or a person at a window. */
+/** Who is driving: an agent holding a lease, or a person at a window. */
 type RunActor = 'agent' | 'human';
 /** How a run ended. `reached`/`partial` appear only when a source claimed it. */
 type RunOutcome = 'running' | 'reached' | 'partial' | 'blocked' | 'interrupted' | 'unknown';
@@ -379,6 +859,144 @@ interface ProfileActivity {
     /** The browser did not answer the last sweep; this is the last known value. */
     stale: boolean;
 }
+/** How far a claim reaches. `machine` means this computer has no account key yet. */
+type ExitScope = 'machine' | 'account';
+/** One exit address a profile owns. */
+interface ExitClaim {
+    /** The comparison unit: the whole address for IPv4, the `/64` block for IPv6. */
+    addr: string;
+    /** `mobile` | `residential` | `datacenter` | `unknown`. Sets how long it is held. */
+    class: string;
+    scope: ExitScope;
+    first_seen: number;
+    last_seen: number;
+    expires_at: number;
+}
+/** A profile's exit-address situation. */
+interface ExitStatus {
+    /** Whether the rule applies to this installation at all. */
+    enabled: boolean;
+    /** Derived from the newest claim, not from configuration. */
+    scope: ExitScope;
+    /** The address in use, when one is claimed. */
+    current: string | null;
+    owned: number;
+    claims: ExitClaim[];
+    /** Set when the profile has no proxy and is therefore exempt. */
+    note: string | null;
+}
+
+/**
+ * The per-profile task list and the profile's own durable memory.
+ *
+ * Mirrors `web-ui/src/api/types/tasks.ts`, the shared source of contract truth.
+ */
+/**
+ * Where a task stands.
+ *
+ * Four words and no more. There is deliberately no `blocked` and no `partial`:
+ * `in_progress` already carries "somebody tried and did not finish", and why it
+ * failed belongs in the run trail, which is built to hold exactly that.
+ *
+ * `cancelled` is `done` with a different word. Both are endings, both fall out
+ * of the list a day later; the separate word is so a reader can tell "we did it"
+ * from "we called it off".
+ */
+type TaskState = 'open' | 'in_progress' | 'done' | 'cancelled';
+/** One task on one profile. */
+interface ProfileTask {
+    id: string;
+    profile_id: string;
+    /** Carried along so a fleet-wide list can say whose task a row is. */
+    profile_name: string;
+    /**
+     * The IANA zone `due_at` should be READ in: the profile's own.
+     *
+     * Without it a viewer reads their own clock and acts on the wrong number, and
+     * an account posting at three in the morning local time is exactly the
+     * behavioural tell this product avoids everywhere else. Derived at query time,
+     * never stored on the task: `geo_mode = follow_exit` rewrites the persona's
+     * zone at every launch.
+     */
+    profile_timezone: string | null;
+    /** One line saying what to do. A task names its material, it does not hold it. */
+    title: string;
+    state: TaskState;
+    /**
+     * Deadline in unix seconds (UTC), or `null` for work that is owed but not owed
+     * at any particular moment.
+     *
+     * Read it in the PROFILE's timezone, not the viewer's: a task due at nine means
+     * nine where the identity lives, and an account that posts at three in the
+     * morning local time is a behavioural tell.
+     *
+     * It is a deadline, not a trigger. Nothing runs by itself.
+     */
+    due_at: number | null;
+    created_at: number;
+    /** When the current claim was taken; cleared when the task leaves `in_progress`. */
+    claimed_at: number | null;
+    finished_at: number | null;
+    /**
+     * Set when a claim nobody finished was handed back after six hours.
+     *
+     * Whoever picks such a task up has to check whether the work already happened:
+     * the previous run may have published the post and died before it could say so.
+     */
+    last_attempt_at: number | null;
+}
+/** Filters for listing tasks. All are narrowings; absent means unconstrained. */
+interface ListTasksParams {
+    profile_id?: string;
+    state?: TaskState;
+    /** Only tasks whose deadline is at or before this unix second. */
+    due_before?: number;
+    /** Substring of the title, case-insensitive. */
+    q?: string;
+    limit?: number;
+    offset?: number;
+}
+/** Add the same task to one or many profiles, one row each. */
+interface CreateTasksBody {
+    profile_ids: string[];
+    title: string;
+    due_at?: number | null;
+}
+/** What one create call did. */
+interface CreateTasksResult {
+    created: ProfileTask[];
+    /**
+     * Profiles that no longer exist. Named rather than dropped: adding a task to
+     * twenty profiles of which three were deleted writes seventeen rows and says
+     * which three it could not.
+     */
+    missing: string[];
+}
+/** The one transition this surface performs. */
+interface PatchTaskBody {
+    /** Only `cancelled`, and only on a task nobody has claimed. */
+    state: 'cancelled';
+}
+/**
+ * A profile's durable memory: the `PROFILE.md` at the top of its directory.
+ *
+ * Same purpose as a repository's `CLAUDE.md`. What goes in it is the customer's
+ * business; nothing writes a scaffold or seeds a value, and a profile starts with
+ * no file rather than an empty one.
+ */
+interface ProfileMemory {
+    /** `null` while nobody has written one. */
+    content: string | null;
+    /** The absolute path, so a person can open it in their own editor. */
+    path: string;
+    updated_at: number | null;
+    /** The ceiling a write is measured against, in bytes. */
+    max_bytes: number;
+}
+/** Replace a profile's memory. The text is stored verbatim. */
+interface WriteMemoryBody {
+    content: string;
+}
 
 /**
  * A daemon lifecycle event. Named `LifecycleEvent` (not `Event`) to avoid
@@ -461,11 +1079,73 @@ type LifecycleEvent = {
     profile_id: string;
     at: number;
 }
+/** A recording appeared or changed: the whole row, upsert it. */
+ | {
+    type: 'recording_changed';
+    recording: Recording;
+    at: number;
+}
+/**
+ * A video appeared or changed. Carries state AND progress: while it renders
+ * this fires every 2 % or 2 s, and the row is the whole truth.
+ */
+ | {
+    type: 'video_changed';
+    video: Video;
+    at: number;
+}
+/** A video is gone: deleted, remove its row. */
+ | {
+    type: 'video_gone';
+    video_id: string;
+    at: number;
+}
+/**
+ * A task appeared or changed. One variant for both, because the row is
+ * complete: a reader writes it whether or not it knew the task before, and a
+ * separate "created" event would only buy a distinction that goes wrong the
+ * first time one is missed.
+ */
+ | {
+    type: 'task_changed';
+    task: ProfileTask;
+    at: number;
+}
+/** A task is gone: cancelled and swept, finished and swept, or deleted. */
+ | {
+    type: 'task_gone';
+    task_id: string;
+    profile_id: string;
+    at: number;
+}
 /**
  * Frames were lost; re-read rather than carry on. Raised when the daemon
  * notices this connection fell behind. `dropped` counts what it skipped.
  */
+/**
+ * The exit-address guard's verdict for one running profile (DEC-017).
+ *
+ * The whole state, like every other live row here: a display rebuilt from
+ * parts is what makes it confidently wrong, and the one frame that matters
+ * most is the wire being cut.
+ */
  | {
+    type: 'exit_guard_changed';
+    profile_id: string;
+    state: 'ok' | 'degraded' | 'unverified' | 'severed';
+    addr: string;
+    class: string;
+    scope: ExitScope;
+    owned: number;
+    detail: string | null;
+    at: number;
+}
+/** A profile stopped: its guard row goes away. */
+ | {
+    type: 'exit_guard_gone';
+    profile_id: string;
+    at: number;
+} | {
     type: 'resync';
     dropped: number;
     at: number;
@@ -487,7 +1167,14 @@ type StreamedEvent = LifecycleEvent & {
  * Read as `text/event-stream` over `fetch` (so the Bearer header is attached, which
  * the browser `EventSource` cannot do that) and reconnect with backoff. A
  * `/v1/ws` websocket carries the same events; SSE is sufficient for one-way
- * fan-out. Mirrors `web-ui/src/api/events.ts`.
+ * fan-out.
+ *
+ * Mirrors `web-ui/src/api/events.ts` line for line, deliberately: this package
+ * ships to npm and should carry no dependency it does not need, so a shared
+ * package would cost more than the copy does. The copy pays for itself with a
+ * gate instead: `scripts/verify-mirrored-values.mjs` holds `MAX_BACKOFF_MS` and
+ * the backoff line itself against the other side. Two clients of the same daemon
+ * that come back at different speeds would be a decision nobody made.
  */
 
 /** Injectable `fetch`; defaults to the global at call time. */
@@ -693,7 +1380,7 @@ declare class ControlApi extends ClientCore {
     /**
      * Hand the daemon a file so `interact action=upload` has something to attach.
      *
-     * The bytes are bound to the PROFILE, not to a reservation: set a file up
+     * The bytes are bound to the PROFILE, not to a lease: set a file up
      * before leasing, and a lease released mid-task does not destroy it.
      */
     putArtifact(profileId: string, bytes: Uint8Array | ArrayBuffer, name?: string): Promise<ArtifactPutResult>;
@@ -790,6 +1477,12 @@ interface TakeoverResult {
 interface StopProfileResult {
     stopped: boolean;
 }
+/** `POST /v1/profiles/:id/release`: `released: false` is an honest no-op,
+ *  there was nothing to let go. */
+interface ReleaseProfileResult {
+    released: boolean;
+    stopped: boolean;
+}
 interface BulkCreateBody {
     preset_id: string;
     count: number;
@@ -1289,6 +1982,53 @@ declare class IdentityApi extends ClientCore {
     revealCookies(profileId: string, body: RevealCookiesBody): Promise<RevealCookiesResult>;
 }
 
+declare class TasksApi extends ClientCore {
+    /**
+     * What is still to be done. No filter means every task of every profile.
+     *
+     * Pass `state: 'open'` for what is outstanding; without it, tasks finished
+     * within the last day are included too.
+     */
+    listTasks(params?: ListTasksParams, signal?: AbortSignal): Promise<ProfileTask[]>;
+    /**
+     * Put the same task on one or many profiles, one row each.
+     *
+     * A task is a LINE, not a document: name the work and leave the material where
+     * it lives. `due_at` is a deadline, not a trigger; nothing runs by itself.
+     *
+     * Profiles that no longer exist come back in `missing` instead of failing the
+     * whole call.
+     */
+    createTasks(body: CreateTasksBody): Promise<CreateTasksResult>;
+    /**
+     * Call a task off.
+     *
+     * Only a task nobody has claimed can be cancelled here. One an agent is working
+     * on right now is stopped by telling that agent, which is a channel that already
+     * reaches it; this surface answers `409` for it rather than pretending.
+     */
+    cancelTask(id: string): Promise<ProfileTask>;
+    /** Remove a task outright. */
+    deleteTask(id: string): Promise<void>;
+    /**
+     * A profile's durable memory, the `PROFILE.md` at the top of its directory.
+     *
+     * `content` is `null` while nobody has written one: a profile starts with no
+     * file, not with an empty one.
+     */
+    getProfileMemory(profileId: string, signal?: AbortSignal): Promise<ProfileMemory>;
+    /**
+     * Replace a profile's memory.
+     *
+     * Stored verbatim: no trimming, no appended newline, no line-ending
+     * translation. The last write wins and nothing warns, exactly as with a file
+     * two people can open.
+     */
+    putProfileMemory(profileId: string, content: string): Promise<ProfileMemory>;
+    /** Remove a profile's memory. Removing one that is not there is not an error. */
+    deleteProfileMemory(profileId: string): Promise<void>;
+}
+
 /**
  * Agent runs and live activity (`/v1/runs`, `/v1/activity`).
  *
@@ -1308,7 +2048,7 @@ type OutcomeSource = 'agent' | 'check' | 'human' | 'derived';
 type GoalSource = 'agent' | 'derived';
 interface AgentRun {
     id: string;
-    /** Groups runs that shared one profile reservation. */
+    /** Groups runs that shared one profile lease. */
     session_id: string;
     profile_id: string;
     profile_name: string;
@@ -1367,6 +2107,96 @@ declare class RunsApi extends ClientCore {
     getActivity(signal?: AbortSignal): Promise<ActivitySnapshot>;
 }
 
+declare class VideosApi extends ClientCore {
+    /** One gallery page, newest first. Running renders are videos too. */
+    listVideos(params?: ListVideosParams, signal?: AbortSignal): Promise<VideosPage>;
+    /** One video row, progress included while it renders. */
+    getVideo(videoId: string, signal?: AbortSignal): Promise<Video>;
+    /** Rename. The title also lands in the MP4's metadata on the NEXT render. */
+    renameVideo(videoId: string, title: string, signal?: AbortSignal): Promise<Video>;
+    /**
+     * Delete a video (`raw: true` also purges its recording's raw material).
+     * A live share link is revoked first; 409 `job_running` while it renders.
+     */
+    deleteVideo(videoId: string, opts?: {
+        raw?: boolean;
+    }, signal?: AbortSignal): Promise<void>;
+    /** Cancel a queued or rendering video. `done` stays done (409). */
+    cancelVideo(videoId: string, signal?: AbortSignal): Promise<Video>;
+    /** Render a failed or cancelled video again: same id, new job. */
+    rerenderVideo(videoId: string, body?: RenderRequestBody, signal?: AbortSignal): Promise<Video>;
+    /** A short-lived fetchable address for one asset (default the video). */
+    videoAccess(videoId: string, asset?: VideoAssetName, signal?: AbortSignal): Promise<VideoAccessGrant>;
+    /** One asset's bytes, through a freshly minted grant. */
+    downloadVideoFile(videoId: string, asset?: VideoAssetName, signal?: AbortSignal): Promise<ArtifactBytes>;
+    /** What recordings and videos cost on disk, plus the caps. */
+    videosStorage(signal?: AbortSignal): Promise<VideosStorage>;
+    /** Recordings, newest first. The row outlives its raw bytes. */
+    listRecordings(params?: {
+        profile_id?: string;
+    }, signal?: AbortSignal): Promise<Recording[]>;
+    getRecording(recordingId: string, signal?: AbortSignal): Promise<Recording>;
+    /**
+     * Purge a recording's RAW material; the row stays forever
+     * (`raw_purged_at`). 409 `job_running` while a render of it is open.
+     */
+    deleteRecordingRaw(recordingId: string, signal?: AbortSignal): Promise<void>;
+    /** A NEW video from this recording (the same body the `video` tool takes). */
+    renderRecording(recordingId: string, body?: RenderRequestBody, signal?: AbortSignal): Promise<Video>;
+    /** What this machine can encode with. The hardware list is PROBED, not read
+     *  off the binary: `h264_nvenc` is always listed and fails without a driver. */
+    getCodecs(signal?: AbortSignal): Promise<CodecsStatus>;
+    /** Turn Cisco's OpenH264 on or off. The hardware encoders are not switchable. */
+    setCodecEnabled(codec: string, enabled: boolean, signal?: AbortSignal): Promise<CodecsStatus>;
+    /** Make a finished video public. Measures every file, asks the control plane
+     *  for permission, uploads, and has the result confirmed. */
+    share(videoId: string, body?: {
+        expires_days?: number | null;
+        passcode?: string | null;
+        download?: boolean;
+    }, signal?: AbortSignal): Promise<ShareLinkLocal>;
+    /** The share ORDER as this machine knows it. How many people watched and
+     *  whether the link still lives is read from the control plane, not from
+     *  here: a number carried along would be wrong the moment another machine
+     *  revoked. */
+    shareStatus(videoId: string, signal?: AbortSignal): Promise<ShareLinkLocal>;
+    /** Revoke the link. The files fall at once; the order stays until the control
+     *  plane confirms. */
+    revokeShare(videoId: string, signal?: AbortSignal): Promise<void>;
+    /** Files a preset points at: background image, music bed, subtitle font. */
+    listMedia(kind?: MediaKind, signal?: AbortSignal): Promise<MediaAsset[]>;
+    /** Upload one file. The body IS the file; `name` and `mime` ride in the query. */
+    uploadMedia(kind: MediaKind, name: string, mime: string, bytes: Uint8Array, signal?: AbortSignal): Promise<MediaAsset>;
+    /** Remove a file. Refuses with 409 while a preset still points at it. */
+    deleteMedia(id: string, signal?: AbortSignal): Promise<void>;
+    /** The file itself. */
+    mediaFile(id: string, signal?: AbortSignal): Promise<ArtifactBytes>;
+    /** Which speech providers have a key. The key itself never comes back: the
+     *  answer carries a hint, and that is on purpose. */
+    listTtsProviders(signal?: AbortSignal): Promise<TtsProviderView[]>;
+    /** Store a key, or rename one. Leaving `apiKey` out keeps the stored key.
+     *
+     *  `apiKey` may also be a secret reference (`{{sb:...}}`), which is what an
+     *  agent gets back after fetching a key from the provider's own site: it is
+     *  not allowed to read the value. A reference needs `profileId`, because the
+     *  value belongs to one profile and there is nothing to open without it.
+     */
+    putTtsProvider(provider: string, body: {
+        apiKey?: string;
+        label?: string;
+        profileId?: string;
+    }, signal?: AbortSignal): Promise<TtsProviderView>;
+    /** Call the provider once for real, and record that the key works.
+     *
+     *  Costs one short sentence of the account's own quota. Until this runs, a
+     *  provider row says `verified_at: null`, which means untested rather than
+     *  broken.
+     */
+    verifyTtsProvider(provider: string, signal?: AbortSignal): Promise<TtsVerifyResult>;
+    /** Forget a provider's key. */
+    deleteTtsProvider(provider: string, signal?: AbortSignal): Promise<void>;
+}
+
 /**
  * Direct-CDP driver (DEC-006, AC-FP-005): a minimal, nodriver-style Chrome
  * DevTools Protocol client over a raw websocket. This is the recommended SDK
@@ -1596,6 +2426,13 @@ declare class ScalebrowserClient extends ClientCore {
     /** Start a profile → CDP ws endpoint. Errors: 4002/4003/4005/4006/4008. */
     startProfile(id: string, body?: StartProfileBody): Promise<StartProfileResult>;
     stopProfile(id: string): Promise<StopProfileResult>;
+    /** Drop the profile's lease, the operator's way out.
+     *
+     *  An agent releases with its handle; this call needs none. The daemon stops
+     *  the browser first when one is still up, then lets the lease go, so a dead
+     *  session cannot park the profile until its TTL runs out. `released: false`
+     *  is an honest no-op: there was nothing to let go. */
+    releaseProfile(id: string): Promise<ReleaseProfileResult>;
     /** Ask for a profile that is open on another machine of this account.
      *
      *  Closes nothing here and nothing there: the control plane revokes the holder's
@@ -1631,6 +2468,31 @@ declare class ScalebrowserClient extends ClientCore {
     createPreset(body: CreatePresetBody): Promise<Preset>;
     updatePreset(id: string, body: UpdatePresetBody): Promise<Preset>;
     deletePreset(id: string): Promise<void>;
+    listVideoPresets(signal?: AbortSignal): Promise<VideoPreset[]>;
+    getVideoPreset(id: string, signal?: AbortSignal): Promise<VideoPreset>;
+    /** The daemon validates `config` strictly and names the failing field path. */
+    createVideoPreset(body: {
+        name: string;
+        config?: Record<string, unknown>;
+    }): Promise<VideoPreset>;
+    /** A built-in preset refuses edits. Duplicate it and edit the copy. */
+    updateVideoPreset(id: string, body: {
+        name?: string;
+        config?: Record<string, unknown>;
+    }): Promise<VideoPreset>;
+    /** The only way to make a built-in preset yours: copy, then edit the copy. */
+    duplicateVideoPreset(id: string, body?: {
+        name?: string;
+    }): Promise<VideoPreset>;
+    deleteVideoPreset(id: string): Promise<void>;
+    /** One still of the sample film under an UNSAVED config, drawn by the daemon's own renderer.
+     *  `moment` wins over `frame`; both absent means the daemon's default moment. */
+    previewVideoPreset(body: VideoPresetPreviewBody, signal?: AbortSignal): Promise<VideoPresetPreview>;
+    /** A clip of the sample film, blocking until it is encoded (the editor uses the SSE form of the
+     *  same route; a script waits). Fetch the bytes with `downloadVideoPresetClip`. */
+    previewVideoPresetClip(body: VideoPresetClipBody, signal?: AbortSignal): Promise<VideoPresetClip>;
+    /** The clip's MP4 bytes. */
+    downloadVideoPresetClip(id: string, signal?: AbortSignal): Promise<ArtifactBytes>;
     /**
      * The values a preset's `constraints` may take. Ask rather than hardcode: the
      * region list comes from the daemon's embedded persona model, so a pinned copy
@@ -1654,6 +2516,13 @@ declare class ScalebrowserClient extends ClientCore {
     startAudit(profileId: string): Promise<AuditStatus>;
     /** State plus the last stored report. */
     getAudit(profileId: string, signal?: AbortSignal): Promise<AuditStatus>;
+    /** Which exit addresses this profile owns, and how far the rule reaches.
+     *
+     * `scope` is `'machine'` while this computer has no account key. That is the
+     * ordinary state of a second machine until sync is unlocked there once, and it is
+     * reported rather than hidden: believing the rule spans three machines when it
+     * spans one is worse than knowing. */
+    getExitStatus(profileId: string, signal?: AbortSignal): Promise<ExitStatus>;
     exportSession(profileId: string, body: SessionExportBody): Promise<SessionExportResult>;
     importSession(profileId: string, body: SessionImportBody): Promise<unknown>;
     sendInput(profileId: string, body: TrustedInputBody): Promise<unknown>;
@@ -1673,14 +2542,14 @@ declare class ScalebrowserClient extends ClientCore {
      */
     launch(profileId: string, body?: StartProfileBody): Promise<LaunchHandle>;
 }
-interface ScalebrowserClient extends IdentityApi, RunsApi, ControlApi, ExtensionsApi {
+interface ScalebrowserClient extends IdentityApi, RunsApi, VideosApi, ControlApi, ExtensionsApi, TasksApi {
 }
 
 /**
  * Error model: stable numeric API error codes (SPEC §5,
  * `crates/core/src/error.rs`) and the typed exceptions the SDK throws.
  */
-/** Stable numeric API error codes (4001–4012, append-only: a retired code stays
+/** Stable numeric API error codes (4001–4013, append-only: a retired code stays
  * reserved rather than being reused). */
 declare const ErrorCode: {
     readonly NotFound: 4001;
@@ -1707,6 +2576,12 @@ declare const ErrorCode: {
      * browser): the caller's move here costs nothing. Close it on that machine, or
      * take it over from the app running there. */
     readonly ProfileInUse: 4012;
+    /** The exit address this start drew belongs to another profile (DEC-017).
+     * Distinct from ProxyGeo (4002 = wrong country or wrong kind of exit, so change
+     * the proxy): here the proxy is fine and the address is simply spoken for. Wait
+     * for a term to run out, let the daemon draw again, or turn exclusivity off for
+     * this profile. */
+    readonly ExitAddressTaken: 4013;
 };
 type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** Error body shape: `{ code, message }` (docs/features/api.md). */
@@ -1764,6 +2639,6 @@ declare function errorMessage(err: unknown): string;
  * ```
  */
 
-declare const VERSION = "0.4.1";
+declare const VERSION = "0.5.0";
 
-export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type ClickOptions, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, HOST_MODES, type HealthStatus, type HostMode, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type Profile, type ProfileActivity, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TrustedInputBody, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };
+export { type Account, type ActivitySnapshot, type AgentRun, ApiError, type ApiErrorBody, type ArtifactBytes, type ArtifactPutResult, type AttachOptions, type AudioStatus, type AuditDetectorReport, type AuditReport, type AuditStatus, type AuditVerdict, type BindInboxBody, type CdpConnectOptions, CdpError, type CdpEvent, CdpSession, type Chapter, type ClickOptions, type CodecsStatus, type CreateGroupBody, type CreateInboxBody, type CreatePresetBody, type CreateTasksBody, type CreateTasksResult, DEFAULT_CAPACITY, type DeleteInterruptionRuleParams, type EffectiveInterruptionLock, ErrorCode, type ErrorCodeValue, type EvaluateOptions, type ExitClaim, type ExitScope, type ExitStatus, type ExportPresetName, type ExtraOutput, type FetchLike, GEO_MODES, type GeoMode, type GoalSource, type Group, HOST_MODES, type HealthStatus, type HostMode, type Inbox, type InboxBinding, type InboxBindings, type InboxChannel, type InputClient, type InterruptionChoice, type InterruptionLock, type InterruptionLockRow, type InterruptionLockView, type InterruptionRuleRow, type LaunchHandle, type ListRunsParams, type ListStepsParams, type ListTasksParams, type ListVideosParams, type MediaAsset, type MediaKind, type MusicBed, type NarrationLine, type NavigateOptions, NetworkError, type OsFamily, type OutcomeSource, PROXY_KINDS, type PasskeyRow, type PatchTaskBody, type PersonaConstraintOptions, type Preset, type PresetConfig, type PresetConstraints, type PreviewHidden, type PreviewMoment, type Profile, type ProfileActivity, type ProfileMemory, type ProfileTask, type ProtectionLevel, type ProtectionStatus, type Proxy, type ProxyKind, ROTATIONS, RUNTIME_STATES, type ReadyStatus, type Recording, type RecordingKind, type RecordingState, type RenderProgress, type RenderRequestBody, type RenderStage, type RevealCookiesBody, type RevealCookiesResult, type RevealedCookie, type Rotation, type RunActor, type RunOutcome, type RunStep, type RuntimeState, ScalebrowserClient, type ScalebrowserClientOptions, ScalebrowserError, type ScrollOptions, type SecretBindingMode, type SecretDeleteResult, type SecretKind, type SecretListResult, type SecretOrigin, type SecretPatchBody, type SecretRow, type SecretRunBody, type SecretRunMention, type SecretRunResult, type SecretScrubResult, type SecretState, type SessionExportBody, type SessionExportResult, type SessionImportBody, type SessionKind, type SetInterruptionLockBody, type SetInterruptionRuleBody, type ShareLinkLocal, type ShotFocus, type ShotIntent, type StepKind, type StepTarget, type StreamHandlers, type StreamParams, type StreamStatus, type TaskState, type TimestampState, type TranscriptWord, type TrustedInputBody, type TtsProviderView, type TtsVerifyResult, type UpdateGroupBody, type UpdateInboxBody, type UpdatePresetBody, VERSION, type Video, type VideoAccessGrant, type VideoAssetName, type VideoAssets, type VideoBackground, type VideoCard, type VideoDestination, type VideoFlags, type VideoPreset, type VideoPresetClip, type VideoPresetClipBody, type VideoPresetClipProgress, type VideoPresetClipStarted, type VideoPresetConfig, type VideoPresetPreview, type VideoPresetPreviewBody, type VideoState, type VideosPage, type VideosStorage, type WriteMemoryBody, deriveMetricsFromProfiles, errorMessage, eventStream, openCdpSession, parseSseFrame, subscribeEvents };