@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/sequences/exports.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Pure interchange-format builders over `SequenceTimeline` — SRT, WebVTT,
+ * CMX3600 EDL, OpenTimelineIO JSON, and the contact-sheet manifest. mp4
+ * rendering needs ffmpeg and stays product-side; everything here is
+ * deterministic frame math producing strings or JSON-serializable documents.
+ *
+ * Builders throw instead of emitting empty documents: an empty subtitle file
+ * or zero-event EDL downloads "successfully" and then fails silently inside
+ * the user's player or NLE — the worst failure mode for an agent-driven
+ * editor. The one exception is OTIO, which meaningfully round-trips sequence
+ * settings (fps, dimensions, track structure) even with zero clips.
+ *
+ * Disabled clips are excluded from every format: an export reflects what
+ * renders, and a cue or event for an invisible clip is a lie.
+ */
+import { type SequenceMediaKind, type SequenceTimeline } from './model';
+/** Define options to export captions filtered by an optional BCP-47 language tag */
+export interface CaptionExportOptions {
+    /** BCP-47 tag; matched case-insensitively against `clip.language`. Clips
+     *  with no language never match a language-scoped export. */
+    language?: string;
+}
+/** Numbered SubRip cues from caption-track clips, in timeline order. Throws
+ *  when no cue survives filtering — see module doc on empty documents. */
+export declare function buildSrt(timeline: SequenceTimeline, opts?: CaptionExportOptions): string;
+/** WebVTT with numbered cue identifiers; same filtering and frame math as
+ *  `buildSrt`, dot millisecond separator per the VTT grammar. */
+export declare function buildVtt(timeline: SequenceTimeline, opts?: CaptionExportOptions): string;
+/** CMX3600-style EDL: one event per enabled video/audio clip in record-start
+ *  order. Source in/out come from `sourceInFrame` + `durationFrames`; record
+ *  in/out from `startFrame`. Timecodes are non-drop `HH:MM:SS:FF` at the
+ *  sequence fps. Throws when the timeline has no video/audio clips. */
+export declare function buildEdl(timeline: SequenceTimeline): string;
+/** Represent a rational time value with a specific rate and numeric value for OTIO schema */
+export interface OtioRationalTime {
+    OTIO_SCHEMA: 'RationalTime.1';
+    rate: number;
+    value: number;
+}
+/** Define a time range with a start time and duration using OtioRationalTime values */
+export interface OtioTimeRange {
+    OTIO_SCHEMA: 'TimeRange.1';
+    start_time: OtioRationalTime;
+    duration: OtioRationalTime;
+}
+/** Define the structure for an external media reference with schema, URL, and optional time range */
+export interface OtioExternalReference {
+    OTIO_SCHEMA: 'ExternalReference.1';
+    target_url: string;
+    /** Natural extent of the source media when known; null when unknown. */
+    available_range: OtioTimeRange | null;
+}
+/** Represent missing references in OTIO with a fixed schema identifier */
+export interface OtioMissingReference {
+    OTIO_SCHEMA: 'MissingReference.1';
+}
+/** Define the structure for a gap element with schema, name, and source time range properties */
+export interface OtioGap {
+    OTIO_SCHEMA: 'Gap.1';
+    name: string;
+    source_range: OtioTimeRange;
+}
+/** Define a clip object with metadata, source range, and media reference according to OTIO schema */
+export interface OtioClip {
+    OTIO_SCHEMA: 'Clip.2';
+    name: string;
+    source_range: OtioTimeRange;
+    media_reference: OtioExternalReference | OtioMissingReference;
+    metadata: Record<string, unknown>;
+}
+/** Define a track containing video or audio clips with metadata and child elements */
+export interface OtioTrack {
+    OTIO_SCHEMA: 'Track.1';
+    name: string;
+    kind: 'Video' | 'Audio';
+    metadata: Record<string, unknown>;
+    children: Array<OtioClip | OtioGap>;
+}
+/** Represent a stack container holding a named collection of OtioTrack children */
+export interface OtioStack {
+    OTIO_SCHEMA: 'Stack.1';
+    name: string;
+    children: OtioTrack[];
+}
+/** Define the structure of a timeline with metadata, tracks, and global start time in OTIO format */
+export interface OtioTimeline {
+    OTIO_SCHEMA: 'Timeline.1';
+    name: string;
+    global_start_time: OtioRationalTime;
+    metadata: Record<string, unknown>;
+    tracks: OtioStack;
+}
+/**
+ * OpenTimelineIO `Timeline.1` document. Serialize with `JSON.stringify` at the
+ * file-write edge.
+ *
+ * OTIO track children are SEQUENTIAL — position comes from accumulated child
+ * durations, so timeline gaps become explicit `Gap.1` children and two enabled
+ * clips overlapping on one track are unrepresentable (throws). Caption and
+ * reference tracks export as `Video` tracks (OTIO has no caption kind) with
+ * the original kind preserved in `metadata.sequenceTrackKind`; agent tracks
+ * carry decision markers, never media, and are excluded.
+ */
+export declare function buildOtio(timeline: SequenceTimeline): OtioTimeline;
+/** Describe a single entry in a contact sheet with timing and media source details */
+export interface ContactSheetEntry {
+    clipId: string;
+    trackId: string;
+    label: string;
+    /** Timeline frame the sample represents — the clip midpoint. */
+    frame: number;
+    /** `m:ss.ff` timecode of `frame`, for human-readable sheet labels. */
+    timecode: string;
+    /** Source-media frame to extract: `sourceInFrame` + midpoint offset for
+     *  video, always 0 for stills (a seek into an image yields nothing). */
+    sourceFrame: number;
+    sourceSeconds: number;
+    url: string;
+    mediaKind: SequenceMediaKind;
+}
+/** Define the structure for a contact sheet manifest including metadata and entries */
+export interface ContactSheetManifest {
+    sequenceId: string;
+    title: string;
+    fps: number;
+    width: number;
+    height: number;
+    entries: ContactSheetEntry[];
+}
+/**
+ * One sample frame per enabled video-track clip with resolved, completed
+ * media — the product side renders the actual sheet (needs ffmpeg/canvas).
+ * Clips whose media is still rendering upstream (`providerStatus` queued/
+ * processing/failed) have no extractable frame and are excluded; audio media
+ * on a video track likewise. Throws when nothing is sampleable — see module
+ * doc on empty documents.
+ */
+export declare function buildContactSheetManifest(timeline: SequenceTimeline): ContactSheetManifest;

package/dist/sequences/index.d.ts

@@ -1,341 +1,20 @@
-import { j as SequenceMediaKind, f as SequenceTimeline, k as TimelineInterval, b as SequenceStore } from '../store-B7LLlk9p.js';
-export { M as MIN_SEQUENCE_CLIP_FRAMES, N as NewSequenceClip, l as NewSequenceDecision, m as NewSequenceTrack, g as SequenceClip, a as SequenceClipMedia, n as SequenceClipPatch, o as SequenceDecision, d as SequenceExportFormat, h as SequenceExportRecord, p as SequenceExportStatus, q as SequenceFrameSnapshot, i as SequenceMeta, r as SequenceStatus, S as SequenceStoreScope, e as SequenceTrack, c as SequenceTrackKind, T as TimelineClipBounds, s as assertClipFitsSequence, t as chooseCaptionPlacement, u as clampClipDuration, v as clampClipStart, w as formatSeconds, x as formatTimecode, y as framesToSeconds, z as secondsToFrames, A as snapshotFrame, B as trackIntervals } from '../store-B7LLlk9p.js';
-export { A as AddCaptionOperation, C as CaptionTargetResolution, a as CreateTrackOperation, D as DeleteClipOperation, E as ExtendSequenceOperation, M as MoveClipOperation, P as PlaceClipOperation, Q as QueueExportOperation, S as SEQUENCE_OPERATION_TYPES, b as SequenceApplyResult, c as SequenceOperation, d as SequenceOperationContext, e as SequenceOperationType, f as SequencePlan, g as SetClipDisabledOperation, h as SetClipTextOperation, i as SplitClipOperation, T as TrimClipOperation, j as applySequenceOperation, k as applySequenceOperations, l as assertSequenceMediaUrl, m as captionTrackNameForLanguage, n as lastClipEndFrame, p as parseSequenceOperations, r as resolveCaptionPlacement, o as resolveCaptionTarget, q as resolvePlaceClipTrack, v as validateAddCaption, s as validateCreateTrack, t as validateDeleteClip, u as validateExtendSequence, w as validateMoveClip, x as validatePlaceClip, y as validateQueueExport, z as validateSequenceOperation, B as validateSequenceOperations, F as validateSetClipDisabled, G as validateSetClipText, H as validateSplitClip, I as validateTrimClip } from '../apply-6wlMOLf8.js';
-import { S as ScopedMcpServerEntryOptions, A as AppToolMcpServer } from '../mcp-xxoZZfor.js';
-export { M as SEQUENCES_MCP_PROTOCOL_VERSIONS } from '../mcp-rpc-DYwPlYbZ.js';
-import '@tangle-network/agent-interface';
-import '../types-B25Mib1r.js';
-import '../auth-BYtiazA4.js';
-
 /**
- * Pure interchange-format builders over `SequenceTimeline` — SRT, WebVTT,
- * CMX3600 EDL, OpenTimelineIO JSON, and the contact-sheet manifest. mp4
- * rendering needs ffmpeg and stays product-side; everything here is
- * deterministic frame math producing strings or JSON-serializable documents.
- *
- * Builders throw instead of emitting empty documents: an empty subtitle file
- * or zero-event EDL downloads "successfully" and then fails silently inside
- * the user's player or NLE — the worst failure mode for an agent-driven
- * editor. The one exception is OTIO, which meaningfully round-trips sequence
- * settings (fps, dimensions, track structure) even with zero clips.
- *
- * Disabled clips are excluded from every format: an export reflects what
- * renders, and a cue or event for an invisible clip is a lie.
- */
-
-/** Define options to export captions filtered by an optional BCP-47 language tag */
-interface CaptionExportOptions {
-    /** BCP-47 tag; matched case-insensitively against `clip.language`. Clips
-     *  with no language never match a language-scoped export. */
-    language?: string;
-}
-/** Numbered SubRip cues from caption-track clips, in timeline order. Throws
- *  when no cue survives filtering — see module doc on empty documents. */
-declare function buildSrt(timeline: SequenceTimeline, opts?: CaptionExportOptions): string;
-/** WebVTT with numbered cue identifiers; same filtering and frame math as
- *  `buildSrt`, dot millisecond separator per the VTT grammar. */
-declare function buildVtt(timeline: SequenceTimeline, opts?: CaptionExportOptions): string;
-/** CMX3600-style EDL: one event per enabled video/audio clip in record-start
- *  order. Source in/out come from `sourceInFrame` + `durationFrames`; record
- *  in/out from `startFrame`. Timecodes are non-drop `HH:MM:SS:FF` at the
- *  sequence fps. Throws when the timeline has no video/audio clips. */
-declare function buildEdl(timeline: SequenceTimeline): string;
-/** Represent a rational time value with a specific rate and numeric value for OTIO schema */
-interface OtioRationalTime {
-    OTIO_SCHEMA: 'RationalTime.1';
-    rate: number;
-    value: number;
-}
-/** Define a time range with a start time and duration using OtioRationalTime values */
-interface OtioTimeRange {
-    OTIO_SCHEMA: 'TimeRange.1';
-    start_time: OtioRationalTime;
-    duration: OtioRationalTime;
-}
-/** Define the structure for an external media reference with schema, URL, and optional time range */
-interface OtioExternalReference {
-    OTIO_SCHEMA: 'ExternalReference.1';
-    target_url: string;
-    /** Natural extent of the source media when known; null when unknown. */
-    available_range: OtioTimeRange | null;
-}
-/** Represent missing references in OTIO with a fixed schema identifier */
-interface OtioMissingReference {
-    OTIO_SCHEMA: 'MissingReference.1';
-}
-/** Define the structure for a gap element with schema, name, and source time range properties */
-interface OtioGap {
-    OTIO_SCHEMA: 'Gap.1';
-    name: string;
-    source_range: OtioTimeRange;
-}
-/** Define a clip object with metadata, source range, and media reference according to OTIO schema */
-interface OtioClip {
-    OTIO_SCHEMA: 'Clip.2';
-    name: string;
-    source_range: OtioTimeRange;
-    media_reference: OtioExternalReference | OtioMissingReference;
-    metadata: Record<string, unknown>;
-}
-/** Define a track containing video or audio clips with metadata and child elements */
-interface OtioTrack {
-    OTIO_SCHEMA: 'Track.1';
-    name: string;
-    kind: 'Video' | 'Audio';
-    metadata: Record<string, unknown>;
-    children: Array<OtioClip | OtioGap>;
-}
-/** Represent a stack container holding a named collection of OtioTrack children */
-interface OtioStack {
-    OTIO_SCHEMA: 'Stack.1';
-    name: string;
-    children: OtioTrack[];
-}
-/** Define the structure of a timeline with metadata, tracks, and global start time in OTIO format */
-interface OtioTimeline {
-    OTIO_SCHEMA: 'Timeline.1';
-    name: string;
-    global_start_time: OtioRationalTime;
-    metadata: Record<string, unknown>;
-    tracks: OtioStack;
-}
-/**
- * OpenTimelineIO `Timeline.1` document. Serialize with `JSON.stringify` at the
- * file-write edge.
- *
- * OTIO track children are SEQUENTIAL — position comes from accumulated child
- * durations, so timeline gaps become explicit `Gap.1` children and two enabled
- * clips overlapping on one track are unrepresentable (throws). Caption and
- * reference tracks export as `Video` tracks (OTIO has no caption kind) with
- * the original kind preserved in `metadata.sequenceTrackKind`; agent tracks
- * carry decision markers, never media, and are excluded.
- */
-declare function buildOtio(timeline: SequenceTimeline): OtioTimeline;
-/** Describe a single entry in a contact sheet with timing and media source details */
-interface ContactSheetEntry {
-    clipId: string;
-    trackId: string;
-    label: string;
-    /** Timeline frame the sample represents — the clip midpoint. */
-    frame: number;
-    /** `m:ss.ff` timecode of `frame`, for human-readable sheet labels. */
-    timecode: string;
-    /** Source-media frame to extract: `sourceInFrame` + midpoint offset for
-     *  video, always 0 for stills (a seek into an image yields nothing). */
-    sourceFrame: number;
-    sourceSeconds: number;
-    url: string;
-    mediaKind: SequenceMediaKind;
-}
-/** Define the structure for a contact sheet manifest including metadata and entries */
-interface ContactSheetManifest {
-    sequenceId: string;
-    title: string;
-    fps: number;
-    width: number;
-    height: number;
-    entries: ContactSheetEntry[];
-}
-/**
- * One sample frame per enabled video-track clip with resolved, completed
- * media — the product side renders the actual sheet (needs ffmpeg/canvas).
- * Clips whose media is still rendering upstream (`providerStatus` queued/
- * processing/failed) have no extractable frame and are excluded; audio media
- * on a video track likewise. Throws when nothing is sampleable — see module
- * doc on empty documents.
- */
-declare function buildContactSheetManifest(timeline: SequenceTimeline): ContactSheetManifest;
-
-/**
- * Caption planning — pure, server-safe helpers that turn transcripts into
- * frame-typed caption chunks and answer "are captions complete?" per language.
- * No store access, no React, no provider coupling: products feed transcript
- * segments in (from any transcription provider) and get chunk bounds out,
- * ready to become `add_caption` operations.
- *
- * All outputs are integer frames at the sequence fps. Seconds appear only on
- * the transcript-segment inputs, because that is what transcription providers
- * emit; the conversion happens exactly once, here.
- */
-
-/** Server twin of `TranscriptionSegment` (../sequences-react/contracts) —
- *  structurally identical so react-side transcription output feeds
- *  `buildCaptionChunks` without mapping. Keep the shapes in lockstep. */
-interface TranscriptSegment {
-    text: string;
-    startSeconds: number;
-    endSeconds: number;
-}
-/** One caption clip's worth of text with its timeline bounds. */
-interface CaptionChunk {
-    text: string;
-    startFrame: number;
-    durationFrames: number;
-}
-/** Define options to configure caption chunk size, duration, and frame rate constraints */
-interface BuildCaptionChunksOptions {
-    /** Upper bound on words per caption; segments split on word boundaries. */
-    maxWordsPerChunk?: number;
-    /** Readability floor — chunks shorter than this are extended, never
-     *  overlapped: the following chunk's start is pushed forward instead. */
-    minDurationSeconds?: number;
-    fps: number;
-}
-/**
- * Split transcript segments into caption chunks. Within each segment, time is
- * apportioned to chunks by word count (a constant words-per-second estimate).
- * Guarantees, across the WHOLE output regardless of segment boundaries:
- *
- * - starts are strictly increasing and chunks never overlap
- * - every chunk lasts at least the min-duration clamp (and at least
- *   `MIN_SEQUENCE_CLIP_FRAMES`)
- * - a chunk may extend past its segment's end by at most the clamp — the cost
- *   of the readability floor on short tails
- *
- * Whitespace-only segments produce no chunks. Segments may arrive unsorted
- * (providers emit per-channel batches); they are ordered by start before
- * chunking so the no-overlap guarantee holds.
- */
-declare function buildCaptionChunks(segments: TranscriptSegment[], opts: BuildCaptionChunksOptions): CaptionChunk[];
-/**
- * Normalize a BCP-47 tag to conventional casing: primary subtag lowercase,
- * 4-letter script subtags Title Case, 2-letter region subtags UPPER, all other
- * subtags lowercase. Throws on empty or structurally invalid tags.
- */
-declare function normalizeLanguageTag(tag: string): string;
-/** Define options to specify target languages and an optional source language for fan-out operations */
-interface LanguageFanoutOptions {
-    languages: string[];
-    /** Excluded from the plan (exact normalized match only — 'en' does not
-     *  exclude 'en-US'; a regional variant of the source is still a valid
-     *  fan-out target). */
-    sourceLanguage?: string;
-}
-/**
- * Plan which caption languages to generate: normalized, deduped (first
- * occurrence wins), source excluded. Throws on an empty request or any
- * invalid tag — a malformed fan-out request must fail before any generation
- * is queued. Returns [] when every requested language IS the source; the
- * caller reports "nothing to fan out" rather than erroring.
- */
-declare function planLanguageFanout(opts: LanguageFanoutOptions): string[];
-/** Coverage for one caption language across the sequence. `language` is the
- *  clip's stored tag verbatim (no normalization — coverage reports what is
- *  actually on the timeline); null groups caption clips with no tag. */
-interface CaptionCoverageEntry {
-    language: string | null;
-    coveredFrames: number;
-    totalFrames: number;
-    /** Uncovered intervals, ascending; endFrame exclusive. */
-    gaps: TimelineInterval[];
-}
-/**
- * Per-language caption coverage over [0, durationFrames). A frame counts as
- * covered when an enabled, non-empty-text clip on a caption-kind track spans
- * it. Overlapping clips merge (no double counting). Returns one entry per
- * distinct language, null first then lexicographic; [] when the timeline has
- * no caption clips at all.
- */
-declare function captionCoverage(timeline: SequenceTimeline): CaptionCoverageEntry[];
-
-/**
- * The sequences MCP tool registry — what the in-sandbox agent sees over the
- * live agent→timeline channel. Each entry carries an LLM-facing description,
- * a JSON Schema for the arguments, and the typed dispatch that converts
- * seconds→frames exactly once, validates the resulting operations, applies
- * them through the store, and records ONE decision row per mutating call.
- *
- * Tool arguments speak SECONDS (the unit an LLM reasons in); everything past
- * this edge is integer frames at the sequence fps. Results come back in
- * snake_case with both seconds and `m:ss.ff` timecodes so the model can quote
- * positions back to the user without doing frame math.
- *
- * Every mutation funnels through the ./validate + ./apply kernel: the WHOLE
- * operation batch validates against pre-state before the first write. Errors
- * thrown anywhere in a tool run (argument shape, validation, store) carry the
- * precise reason — the handler surfaces them verbatim as `isError` tool
- * results the model can act on.
- */
-
-/** Everything one tool invocation needs. Constructed per request by the
- *  handler — the store is already scoped + authorized by the product. The
- *  playhead is server-set (never a tool argument) so auto-placed captions
- *  anchor to what the user is actually looking at. */
-interface SequenceMcpToolEnv {
-    store: SequenceStore;
-    playheadFrame: number;
-}
-/** Define a tool with metadata and a run method for processing input within a specific environment */
-interface SequenceMcpToolDefinition {
-    name: string;
-    description: string;
-    inputSchema: Record<string, unknown>;
-    run(args: Record<string, unknown>, env: SequenceMcpToolEnv): Promise<unknown>;
-}
-/** Define supported export formats for sequence outputs including video, subtitle, and metadata types */
-declare const SEQUENCE_EXPORT_FORMATS: readonly ["mp4", "otio", "xml", "edl", "vtt", "srt", "contact_sheet"];
-/** Define immutable sequence track kinds for video, audio, caption, reference, and agent */
-declare const SEQUENCE_TRACK_KINDS: readonly ["video", "audio", "caption", "reference", "agent"];
-/** Define the allowed media kinds for sequences including video, image, and audio */
-declare const SEQUENCE_MEDIA_KINDS: readonly ["video", "image", "audio"];
-/** Largest accepted `add_captions` batch — bounds one decision row / one
- *  validation pass to a size the store can absorb in a single request. */
-declare const MAX_CAPTION_BATCH = 500;
-/** Resolve an array of immutable sequence MCP tool definitions for timeline and frame operations */
-declare const SEQUENCE_MCP_TOOLS: readonly SequenceMcpToolDefinition[];
-/** Resolve the SequenceMcpToolDefinition matching the given name or return undefined */
-declare function findSequenceMcpTool(name: string): SequenceMcpToolDefinition | undefined;
-
-/**
- * Streamable-HTTP MCP server for one sequence — the live agent→timeline
- * channel. JSON-RPC 2.0 over POST, stateless per request (Workers-compatible:
- * no session table, no SSE — a tools-only server answers every request with a
- * single `application/json` body, which the streamable-HTTP transport
- * explicitly permits).
- *
- * Trust boundary: the PRODUCT authenticates the request (capability token,
- * workspace RBAC) BEFORE constructing the scoped {@link SequenceStore} and
- * calling this handler — the handler trusts its store completely. Tool
- * execution failures (argument shape, validation, store throws) become
- * `isError` tool results carrying the thrown message verbatim so the model can
- * read WHY and retry; only protocol-level misuse becomes a JSON-RPC error.
- *
- * The envelope (JSON-RPC framing, initialize/ping/tools/list/tools/call,
- * notification 202, -32601) lives in {@link createMcpToolHandler}; this module
- * is a thin adapter wiring the sequences tool list + playhead env.
- */
-
-/** Describe server information including name and version for Sequences MCP integration */
-interface SequencesMcpServerInfo {
-    name: string;
-    version: string;
-}
-/** Define options for creating sequences MCP handler including store, playhead frame, and server info */
-interface CreateSequencesMcpHandlerOptions {
-    /** Already scoped + authorized for one (workspace, sequence, actor). */
-    store: SequenceStore;
-    /** Editor playhead at request time, in frames; anchors auto-placed captions.
-     *  Default 0 (sequence start) for headless callers. */
-    playheadFrame?: number;
-    serverInfo?: SequencesMcpServerInfo;
-}
-/** Create a handler to process MCP sequence requests with optional playhead frame and server info */
-declare function createSequencesMcpHandler(opts: CreateSequencesMcpHandlerOptions): (request: Request) => Promise<Response>;
-
-/**
- * Profile entry for the sequences MCP server — what a product spreads into its
- * sandbox `AgentProfile.mcp` map so the in-sandbox agent gets the live
- * timeline channel. A thin wrapper over the shared `buildScopedMcpServerEntry`
- * mechanism (../tools/mcp): transport 'http', capability token in the
- * Authorization header (server-set, never a tool argument). The only
- * domain-specific values are this channel's default description and name.
- */
-
-/** Describe live timeline editor features for current video sequence including clip and caption management */
-declare const DEFAULT_SEQUENCES_MCP_DESCRIPTION = "Live timeline editor for the current video sequence: read timeline state, place/move/trim/split clips, add captions, manage tracks, and queue exports. All times are seconds.";
-/** Extend ScopedMcpServerEntryOptions to configure MCP server entry options for sequence building */
-type BuildSequencesMcpServerEntryOptions = ScopedMcpServerEntryOptions;
-/** Build the `AgentProfileMcpServer`-shaped entry for the sequences channel. */
-declare function buildSequencesMcpServerEntry(opts: BuildSequencesMcpServerEntryOptions): AppToolMcpServer;
-
-export { type BuildCaptionChunksOptions, type BuildSequencesMcpServerEntryOptions, type CaptionChunk, type CaptionCoverageEntry, type CaptionExportOptions, type ContactSheetEntry, type ContactSheetManifest, type CreateSequencesMcpHandlerOptions, DEFAULT_SEQUENCES_MCP_DESCRIPTION, type LanguageFanoutOptions, MAX_CAPTION_BATCH, type OtioClip, type OtioExternalReference, type OtioGap, type OtioMissingReference, type OtioRationalTime, type OtioStack, type OtioTimeRange, type OtioTimeline, type OtioTrack, SEQUENCE_EXPORT_FORMATS, SEQUENCE_MCP_TOOLS, SEQUENCE_MEDIA_KINDS, SEQUENCE_TRACK_KINDS, type SequenceMcpToolDefinition, type SequenceMcpToolEnv, SequenceMediaKind, SequenceStore, SequenceTimeline, type SequencesMcpServerInfo, TimelineInterval, type TranscriptSegment, buildCaptionChunks, buildContactSheetManifest, buildEdl, buildOtio, buildSequencesMcpServerEntry, buildSrt, buildVtt, captionCoverage, createSequencesMcpHandler, findSequenceMcpTool, normalizeLanguageTag, planLanguageFanout };
+ * Sequence timeline module: frame-accurate timeline model, the closed
+ * operation union, the store seam, the validate/apply kernel, caption +
+ * export builders, and the MCP tool surface.
+ *
+ * Drizzle-backed persistence (schema factory + store implementation) lives in
+ * './drizzle' (`@tangle-network/agent-app/sequences/drizzle`) because it
+ * imports `drizzle-orm` at module top — this barrel must stay importable for
+ * consumers without that optional peer installed.
+ */
+export * from './model';
+export * from './operations';
+export * from './store';
+export * from './validate';
+export * from './apply';
+export * from './exports';
+export * from './captions';
+export * from './mcp-tools';
+export * from './mcp-handler';
+export * from './mcp-entry';

package/dist/sequences/mcp-entry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Profile entry for the sequences MCP server — what a product spreads into its
+ * sandbox `AgentProfile.mcp` map so the in-sandbox agent gets the live
+ * timeline channel. A thin wrapper over the shared `buildScopedMcpServerEntry`
+ * mechanism (../tools/mcp): transport 'http', capability token in the
+ * Authorization header (server-set, never a tool argument). The only
+ * domain-specific values are this channel's default description and name.
+ */
+import type { AppToolMcpServer, ScopedMcpServerEntryOptions } from '../tools/mcp';
+/** Describe live timeline editor features for current video sequence including clip and caption management */
+export declare const DEFAULT_SEQUENCES_MCP_DESCRIPTION = "Live timeline editor for the current video sequence: read timeline state, place/move/trim/split clips, add captions, manage tracks, and queue exports. All times are seconds.";
+/** Extend ScopedMcpServerEntryOptions to configure MCP server entry options for sequence building */
+export type BuildSequencesMcpServerEntryOptions = ScopedMcpServerEntryOptions;
+/** Build the `AgentProfileMcpServer`-shaped entry for the sequences channel. */
+export declare function buildSequencesMcpServerEntry(opts: BuildSequencesMcpServerEntryOptions): AppToolMcpServer;

package/dist/sequences/mcp-handler.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Streamable-HTTP MCP server for one sequence — the live agent→timeline
+ * channel. JSON-RPC 2.0 over POST, stateless per request (Workers-compatible:
+ * no session table, no SSE — a tools-only server answers every request with a
+ * single `application/json` body, which the streamable-HTTP transport
+ * explicitly permits).
+ *
+ * Trust boundary: the PRODUCT authenticates the request (capability token,
+ * workspace RBAC) BEFORE constructing the scoped {@link SequenceStore} and
+ * calling this handler — the handler trusts its store completely. Tool
+ * execution failures (argument shape, validation, store throws) become
+ * `isError` tool results carrying the thrown message verbatim so the model can
+ * read WHY and retry; only protocol-level misuse becomes a JSON-RPC error.
+ *
+ * The envelope (JSON-RPC framing, initialize/ping/tools/list/tools/call,
+ * notification 202, -32601) lives in {@link createMcpToolHandler}; this module
+ * is a thin adapter wiring the sequences tool list + playhead env.
+ */
+import type { SequenceStore } from './store';
+/** The supported MCP protocol versions are an envelope-level (engine) concern
+ *  owned by the shared `createMcpToolHandler`. Re-exported under the historical
+ *  name to keep the public surface stable without a second source of truth. */
+export { MCP_PROTOCOL_VERSIONS as SEQUENCES_MCP_PROTOCOL_VERSIONS } from '../tools/mcp-rpc';
+/** Describe server information including name and version for Sequences MCP integration */
+export interface SequencesMcpServerInfo {
+    name: string;
+    version: string;
+}
+/** Define options for creating sequences MCP handler including store, playhead frame, and server info */
+export interface CreateSequencesMcpHandlerOptions {
+    /** Already scoped + authorized for one (workspace, sequence, actor). */
+    store: SequenceStore;
+    /** Editor playhead at request time, in frames; anchors auto-placed captions.
+     *  Default 0 (sequence start) for headless callers. */
+    playheadFrame?: number;
+    serverInfo?: SequencesMcpServerInfo;
+}
+/** Create a handler to process MCP sequence requests with optional playhead frame and server info */
+export declare function createSequencesMcpHandler(opts: CreateSequencesMcpHandlerOptions): (request: Request) => Promise<Response>;

package/dist/sequences/mcp-tools.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The sequences MCP tool registry — what the in-sandbox agent sees over the
+ * live agent→timeline channel. Each entry carries an LLM-facing description,
+ * a JSON Schema for the arguments, and the typed dispatch that converts
+ * seconds→frames exactly once, validates the resulting operations, applies
+ * them through the store, and records ONE decision row per mutating call.
+ *
+ * Tool arguments speak SECONDS (the unit an LLM reasons in); everything past
+ * this edge is integer frames at the sequence fps. Results come back in
+ * snake_case with both seconds and `m:ss.ff` timecodes so the model can quote
+ * positions back to the user without doing frame math.
+ *
+ * Every mutation funnels through the ./validate + ./apply kernel: the WHOLE
+ * operation batch validates against pre-state before the first write. Errors
+ * thrown anywhere in a tool run (argument shape, validation, store) carry the
+ * precise reason — the handler surfaces them verbatim as `isError` tool
+ * results the model can act on.
+ */
+import type { SequenceStore } from './store';
+/** Everything one tool invocation needs. Constructed per request by the
+ *  handler — the store is already scoped + authorized by the product. The
+ *  playhead is server-set (never a tool argument) so auto-placed captions
+ *  anchor to what the user is actually looking at. */
+export interface SequenceMcpToolEnv {
+    store: SequenceStore;
+    playheadFrame: number;
+}
+/** Define a tool with metadata and a run method for processing input within a specific environment */
+export interface SequenceMcpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    run(args: Record<string, unknown>, env: SequenceMcpToolEnv): Promise<unknown>;
+}
+/** Define supported export formats for sequence outputs including video, subtitle, and metadata types */
+export declare const SEQUENCE_EXPORT_FORMATS: readonly ["mp4", "otio", "xml", "edl", "vtt", "srt", "contact_sheet"];
+/** Define immutable sequence track kinds for video, audio, caption, reference, and agent */
+export declare const SEQUENCE_TRACK_KINDS: readonly ["video", "audio", "caption", "reference", "agent"];
+/** Define the allowed media kinds for sequences including video, image, and audio */
+export declare const SEQUENCE_MEDIA_KINDS: readonly ["video", "image", "audio"];
+/** Largest accepted `add_captions` batch — bounds one decision row / one
+ *  validation pass to a size the store can absorb in a single request. */
+export declare const MAX_CAPTION_BATCH = 500;
+/** Resolve an array of immutable sequence MCP tool definitions for timeline and frame operations */
+export declare const SEQUENCE_MCP_TOOLS: readonly SequenceMcpToolDefinition[];
+/** Resolve the SequenceMcpToolDefinition matching the given name or return undefined */
+export declare function findSequenceMcpTool(name: string): SequenceMcpToolDefinition | undefined;