@tangle-network/agent-app 0.11.1 → 0.13.0

package/dist/sequences/index.d.ts

@@ -0,0 +1,331 @@
+import { j as SequenceMediaKind, o as SequenceTimeline, r as TimelineInterval, m as SequenceStore } from '../store-gckrNq-g.js';
+export { M as MIN_SEQUENCE_CLIP_FRAMES, N as NewSequenceClip, a as NewSequenceDecision, b as NewSequenceTrack, S as SequenceClip, c as SequenceClipMedia, d as SequenceClipPatch, e as SequenceDecision, f as SequenceExportFormat, g as SequenceExportRecord, h as SequenceExportStatus, i as SequenceFrameSnapshot, k as SequenceMeta, l as SequenceStatus, n as SequenceStoreScope, p as SequenceTrack, q 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-gckrNq-g.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-Cp8c3K9D.js';
+import { f as ToolHeaderNames, a as AppToolMcpServer } from '../mcp-CIupfjxV.js';
+import { b as AppToolContext } from '../types-By4B3K37.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.
+ */
+
+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;
+interface OtioRationalTime {
+    OTIO_SCHEMA: 'RationalTime.1';
+    rate: number;
+    value: number;
+}
+interface OtioTimeRange {
+    OTIO_SCHEMA: 'TimeRange.1';
+    start_time: OtioRationalTime;
+    duration: OtioRationalTime;
+}
+interface OtioExternalReference {
+    OTIO_SCHEMA: 'ExternalReference.1';
+    target_url: string;
+    /** Natural extent of the source media when known; null when unknown. */
+    available_range: OtioTimeRange | null;
+}
+interface OtioMissingReference {
+    OTIO_SCHEMA: 'MissingReference.1';
+}
+interface OtioGap {
+    OTIO_SCHEMA: 'Gap.1';
+    name: string;
+    source_range: OtioTimeRange;
+}
+interface OtioClip {
+    OTIO_SCHEMA: 'Clip.2';
+    name: string;
+    source_range: OtioTimeRange;
+    media_reference: OtioExternalReference | OtioMissingReference;
+    metadata: Record<string, unknown>;
+}
+interface OtioTrack {
+    OTIO_SCHEMA: 'Track.1';
+    name: string;
+    kind: 'Video' | 'Audio';
+    metadata: Record<string, unknown>;
+    children: Array<OtioClip | OtioGap>;
+}
+interface OtioStack {
+    OTIO_SCHEMA: 'Stack.1';
+    name: string;
+    children: OtioTrack[];
+}
+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;
+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;
+}
+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;
+}
+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;
+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;
+}
+interface SequenceMcpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    run(args: Record<string, unknown>, env: SequenceMcpToolEnv): Promise<unknown>;
+}
+declare const SEQUENCE_EXPORT_FORMATS: readonly ["mp4", "otio", "xml", "edl", "vtt", "srt", "contact_sheet"];
+declare const SEQUENCE_TRACK_KINDS: readonly ["video", "audio", "caption", "reference", "agent"];
+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;
+declare const SEQUENCE_MCP_TOOLS: readonly SequenceMcpToolDefinition[];
+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.
+ */
+
+/** Newest first. The handler echoes the client's requested version when
+ *  supported, else answers with the newest it speaks (per MCP negotiation the
+ *  client then disconnects if it cannot use it). */
+declare const SEQUENCES_MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+interface SequencesMcpServerInfo {
+    name: string;
+    version: string;
+}
+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;
+}
+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. Same shape and conventions as the app-tool bridges in
+ * ../tools/mcp: transport 'http', capability token in the Authorization
+ * header (server-set, never a tool argument), identity headers when the
+ * product recovers the user via `authenticateToolRequest`.
+ */
+
+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.";
+interface BuildSequencesMcpServerEntryOptions {
+    /** App base URL the sandbox reaches back to (trailing slash tolerated). */
+    baseUrl: string;
+    /** Product route serving `createSequencesMcpHandler` for ONE sequence —
+     *  the sequence id is part of the path, never a tool argument. */
+    path: string;
+    /** Capability token the product minted for this (user, sequence) scope.
+     *  With no token there is no entry to build — omit the server instead. */
+    token: string;
+    description?: string;
+    /** Identity headers for products whose route recovers the user via
+     *  `authenticateToolRequest`. Omit when the bearer token is self-contained. */
+    ctx?: AppToolContext;
+    headerNames?: ToolHeaderNames;
+}
+/** 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, SEQUENCES_MCP_PROTOCOL_VERSIONS, 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 };

package/dist/sequences/index.js

@@ -0,0 +1,114 @@
+import {
+  DEFAULT_SEQUENCES_MCP_DESCRIPTION,
+  MAX_CAPTION_BATCH,
+  SEQUENCES_MCP_PROTOCOL_VERSIONS,
+  SEQUENCE_EXPORT_FORMATS,
+  SEQUENCE_MCP_TOOLS,
+  SEQUENCE_MEDIA_KINDS,
+  SEQUENCE_OPERATION_TYPES,
+  SEQUENCE_TRACK_KINDS,
+  applySequenceOperation,
+  applySequenceOperations,
+  assertSequenceMediaUrl,
+  buildCaptionChunks,
+  buildContactSheetManifest,
+  buildEdl,
+  buildOtio,
+  buildSequencesMcpServerEntry,
+  buildSrt,
+  buildVtt,
+  captionCoverage,
+  captionTrackNameForLanguage,
+  createSequencesMcpHandler,
+  findSequenceMcpTool,
+  lastClipEndFrame,
+  normalizeLanguageTag,
+  parseSequenceOperations,
+  planLanguageFanout,
+  resolveCaptionPlacement,
+  resolveCaptionTarget,
+  resolvePlaceClipTrack,
+  validateAddCaption,
+  validateCreateTrack,
+  validateDeleteClip,
+  validateExtendSequence,
+  validateMoveClip,
+  validatePlaceClip,
+  validateQueueExport,
+  validateSequenceOperation,
+  validateSequenceOperations,
+  validateSetClipDisabled,
+  validateSetClipText,
+  validateSplitClip,
+  validateTrimClip
+} from "../chunk-6UOE5CTA.js";
+import {
+  MIN_SEQUENCE_CLIP_FRAMES,
+  assertClipFitsSequence,
+  chooseCaptionPlacement,
+  clampClipDuration,
+  clampClipStart,
+  formatSeconds,
+  formatTimecode,
+  framesToSeconds,
+  secondsToFrames,
+  snapshotFrame,
+  trackIntervals
+} from "../chunk-ZYBWGSAZ.js";
+import "../chunk-A76ZHWNF.js";
+export {
+  DEFAULT_SEQUENCES_MCP_DESCRIPTION,
+  MAX_CAPTION_BATCH,
+  MIN_SEQUENCE_CLIP_FRAMES,
+  SEQUENCES_MCP_PROTOCOL_VERSIONS,
+  SEQUENCE_EXPORT_FORMATS,
+  SEQUENCE_MCP_TOOLS,
+  SEQUENCE_MEDIA_KINDS,
+  SEQUENCE_OPERATION_TYPES,
+  SEQUENCE_TRACK_KINDS,
+  applySequenceOperation,
+  applySequenceOperations,
+  assertClipFitsSequence,
+  assertSequenceMediaUrl,
+  buildCaptionChunks,
+  buildContactSheetManifest,
+  buildEdl,
+  buildOtio,
+  buildSequencesMcpServerEntry,
+  buildSrt,
+  buildVtt,
+  captionCoverage,
+  captionTrackNameForLanguage,
+  chooseCaptionPlacement,
+  clampClipDuration,
+  clampClipStart,
+  createSequencesMcpHandler,
+  findSequenceMcpTool,
+  formatSeconds,
+  formatTimecode,
+  framesToSeconds,
+  lastClipEndFrame,
+  normalizeLanguageTag,
+  parseSequenceOperations,
+  planLanguageFanout,
+  resolveCaptionPlacement,
+  resolveCaptionTarget,
+  resolvePlaceClipTrack,
+  secondsToFrames,
+  snapshotFrame,
+  trackIntervals,
+  validateAddCaption,
+  validateCreateTrack,
+  validateDeleteClip,
+  validateExtendSequence,
+  validateMoveClip,
+  validatePlaceClip,
+  validateQueueExport,
+  validateSequenceOperation,
+  validateSequenceOperations,
+  validateSetClipDisabled,
+  validateSetClipText,
+  validateSplitClip,
+  validateTrimClip
+};
+//# sourceMappingURL=index.js.map

package/dist/sequences/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}