@mengine/medeo-tool 1.0.1-alpha.0

package/README.md

@@ -0,0 +1,44 @@
+# `@mengine/medeo-tool`
+
+Node tool surface for editing a Medeo video document through the deterministic
+edit sandbox.
+
+The package owns the complete tool path:
+
+- compact snapshot projection;
+- trusted worker execution of an agent-authored JavaScript edit script;
+- op-journal `ChangePlan` caching;
+- versioned or per-op-preflight commit through `MengineDocSession`;
+- session cache and shutdown.
+
+A host supplies only environment facts: Mengine HTTP origin, optional request
+identity headers, `fetch`, and a stable agent peer id.
+
+```ts
+import { createMedeoTool } from '@mengine/medeo-tool';
+
+const medeo = createMedeoTool({
+  httpOrigin: process.env.MENGINE_HTTP_ORIGIN!,
+  userId: () => process.env.MED_USER_ID,
+  peerId: () => process.env.MED_AGENT_PEER_ID,
+});
+
+const snapshot = await medeo.handle({ op: 'snapshot', doc_id: docId });
+const run = await medeo.handle({
+  op: 'run-edit-script',
+  doc_id: docId,
+  script: 'await edit.deleteBgm({})',
+});
+if (!run.ok || run.op !== 'run-edit-script') throw new Error('edit script failed');
+const commit = await medeo.handle({
+  op: 'commit-plan',
+  doc_id: docId,
+  plan_id: run.plan_id,
+});
+
+await medeo.close();
+```
+
+The sandbox has no network, storage, clock, or generation access. Materialize
+speech/media side effects in the host first and pass stable facts through
+`inputs`.

package/dist/index.d.mts

@@ -0,0 +1,457 @@
+import { JournalEntry, MengineDocSession, PartIdFactory, SemanticOpName, VideoDocument, fromVideoDocument } from "@mengine/medeo-client";
+import { AddSpeechesInput, AddVideoClipsInput, AdjustBgmVolumeInput, AdjustSpeechVolumeInput, AdjustVideoClipDurationInput, AdjustVideoClipVolumeInput, ChangeSpeechScriptInput, ChangeSpeechVoiceInput, DeleteBgmInput, DeleteSpeechesInput, DeleteVideoClipsInput, MoveSpeechesInput, MoveVideoClipsInput, ReplaceVideoClipContentInput, SetBgmInput, SetCaptionStyleInput, SetCaptionVisibilityInput, SetVideoClipSpeedShiftInput } from "@mengine/medeo-client/schemas";
+
+//#region src/document/compact-projection.d.ts
+/**
+ * Compact text projection of a `VideoDocument` for sandbox ChangePlan
+ * `preview` (and pipeline dry-run preview). Pure, runtime-neutral: solves
+ * via `solveVideoDocument`, emits one header line plus one row per timeline
+ * item (library orphans are never rendered). Row intervals and per-kind
+ * effective durations align with `toReadViewPartLibrary` /
+ * `fromVideoDocument`.
+ */
+interface CompactProjectionOptions {
+  /** Only render these parts (header still reports the full timeline total). Default = all. */
+  onlyPartIds?: ReadonlySet<string>;
+  /** Caption text preview truncation length. Default 24. */
+  textPreviewLength?: number;
+}
+/**
+ * Render a `VideoDocument` as compact text: one header line plus one row per
+ * timeline part (optionally filtered by `onlyPartIds`). Deterministic and
+ * side-effect free — same document always yields the same string.
+ */
+declare function renderCompactProjection(document: VideoDocument, options?: CompactProjectionOptions): string;
+//#endregion
+//#region src/sandbox/preview.d.ts
+/** Extract every part id a journal entry touches (payload refs + minted ids). */
+declare function collectAffectedPartIds(journal: readonly JournalEntry[]): Set<string>;
+/**
+ * Render a ChangePlan preview: header + rows for journal-affected parts only.
+ * Empty journal → empty `onlyPartIds` (header alone), matching the T2 contract.
+ */
+declare function renderPreview(document: VideoDocument, journal: readonly JournalEntry[]): string;
+//#endregion
+//#region src/sandbox/script-session.d.ts
+/**
+ * Runtime-neutral edit-sandbox session: `edit.*` / `timeline.*` / checkpoint
+ * facade over a forked `VideoDocument`, self-maintained journal, and console
+ * log buffer. No `node:*` imports — host/worker layers inject this into vm.
+ *
+ * Known gap (not solved here): `Math.random` / `Date.now` remain reachable in
+ * the vm; purity is by convention.
+ */
+interface SandboxCheckpoint {
+  readonly index: number;
+}
+interface ChangePlan {
+  doc_id: string;
+  base_version: string;
+  ops: readonly JournalEntry[];
+  preview: string;
+  logs: string[];
+}
+interface EditSandboxSessionOptions {
+  idFactory?: PartIdFactory;
+  onEntry?: (entry: JournalEntry) => void;
+  onLog?: (line: string) => void;
+  /** Notify host that the streamed journal was truncated to `index` (rollback). */
+  onTruncate?: (index: number) => void;
+}
+interface TimelineClipDescriptor {
+  id: string;
+  start_ms: number;
+  end_ms: number;
+  duration_ms: number;
+  speed_shift: unknown;
+  volume: number | undefined;
+  media_id: string | undefined;
+}
+interface TimelinePartDescriptor {
+  id: string;
+  kind: string;
+  lane: string;
+  start_ms: number;
+  end_ms: number;
+  duration_ms: number;
+  part: unknown;
+}
+/** Session core for one forked document; globals stay identity-stable across rollback. */
+declare class EditSandboxSession {
+  private readonly original;
+  private readonly idFactory;
+  private readonly onEntry;
+  private readonly onLog;
+  private readonly onTruncate;
+  private current;
+  /** Adapter journal length already accounted for — new slices are real commits. */
+  private adapterJournalSeen;
+  private readonly entries;
+  private readonly logs;
+  private logBytes;
+  private logCapped;
+  readonly edit: EditFacade;
+  readonly timeline: TimelineFacade;
+  readonly console: ConsoleShim;
+  readonly checkpoint: () => SandboxCheckpoint;
+  readonly rollbackTo: (cp: SandboxCheckpoint) => void;
+  constructor(document: VideoDocument, options?: EditSandboxSessionOptions);
+  /** Assemble a ChangePlan from the self-maintained journal + current preview. */
+  buildPlan(baseVersion: string): ChangePlan;
+  getEntries(): readonly JournalEntry[];
+  getLogs(): readonly string[];
+  private boot;
+  private doRollbackTo;
+  private captureNewEntries;
+  private appendLog;
+  private buildConsoleShim;
+  private buildEditFacade;
+  private buildTimelineFacade;
+  private clipsInRange;
+  private part;
+}
+interface EditFacade {
+  addSpeeches: (input: AddSpeechesInput) => Promise<void>;
+  addVideoClips: (input: AddVideoClipsInput) => Promise<void>;
+  adjustBgmVolume: (input: AdjustBgmVolumeInput) => Promise<void>;
+  adjustSpeechVolume: (input: AdjustSpeechVolumeInput) => Promise<void>;
+  adjustVideoClipDuration: (input: AdjustVideoClipDurationInput) => Promise<void>;
+  adjustVideoClipVolume: (input: AdjustVideoClipVolumeInput) => Promise<void>;
+  changeSpeechScript: (input: ChangeSpeechScriptInput) => Promise<void>;
+  changeSpeechVoice: (input: ChangeSpeechVoiceInput) => Promise<void>;
+  deleteBgm: (input: DeleteBgmInput) => Promise<void>;
+  deleteSpeeches: (input: DeleteSpeechesInput) => Promise<void>;
+  deleteVideoClips: (input: DeleteVideoClipsInput) => Promise<void>;
+  moveSpeeches: (input: MoveSpeechesInput) => Promise<void>;
+  moveVideoClips: (input: MoveVideoClipsInput) => Promise<void>;
+  replaceVideoClipContent: (input: ReplaceVideoClipContentInput) => Promise<void>;
+  setBgm: (input: SetBgmInput) => Promise<void>;
+  setCaptionStyle: (input: SetCaptionStyleInput) => Promise<void>;
+  setCaptionVisibility: (input: SetCaptionVisibilityInput) => Promise<void>;
+  setVideoClipSpeedShift: (input: SetVideoClipSpeedShiftInput) => Promise<void>;
+}
+interface TimelineFacade {
+  snapshot: () => ReturnType<typeof fromVideoDocument>;
+  clipsInRange: (startMs: number, endMs: number) => TimelineClipDescriptor[];
+  part: (id: string) => TimelinePartDescriptor | null;
+}
+interface ConsoleShim {
+  log: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+//#endregion
+//#region src/sandbox/node-host.d.ts
+/**
+ * Host API for running an agent edit script in an isolated Node worker.
+ *
+ * Requires Node.js >= 24.15 (engines) so the worker can load TypeScript via
+ * `--experimental-transform-types`. Do not inherit `process.execArgv` — vitest
+ * injects loaders that break worker boot.
+ */
+interface RunEditScriptOptions {
+  document: VideoDocument;
+  baseVersion: string;
+  script: string;
+  inputs?: Record<string, unknown>;
+  /** Deterministic id mint label for tests; omit to use the default ULID factory. */
+  idLabel?: string;
+  /** Hard wall-clock timeout; default 2000 ms. */
+  timeoutMs?: number;
+  /** V8 old-generation ceiling for the worker; default 256 MB. */
+  memoryLimitMb?: number;
+  /** Override worker module URL (defaults to sibling `worker-entry.ts`). */
+  workerEntryUrl?: URL;
+}
+type EditScriptResult = {
+  ok: true;
+  plan: ChangePlan; /** Script execution time after worker readiness; excludes cold start. */
+  durationMs: number;
+} | {
+  ok: false;
+  phase: 'parse' | 'runtime' | 'timeout' | 'memory';
+  error: {
+    message: string;
+    line?: number;
+    column?: number;
+    stack?: string;
+  };
+  partial: {
+    ops: readonly JournalEntry[];
+    logs: string[];
+  };
+};
+/** Run `script` against a forked document snapshot; always resolves (never rejects). */
+declare function runEditScript(options: RunEditScriptOptions): Promise<EditScriptResult>;
+//#endregion
+//#region src/prompt.d.ts
+declare const MEDEO_TOOL_DESCRIPTION: string;
+//#endregion
+//#region src/schema.d.ts
+declare const MEDEO_TOOL_NAME = "medeo";
+type MedeoToolOp = 'snapshot' | 'run-edit-script' | 'commit-plan';
+/**
+ * JSON Schema for the host-facing three-op `medeo` tool surface.
+ *
+ * The schema intentionally does not return or accept the full op journal:
+ * journals stay in the tool process and are referenced by `plan_id`. This keeps
+ * large intermediate products out of model context while preserving the exact
+ * journal used for commit.
+ */
+declare const MEDEO_TOOL_PARAMETERS: {
+  readonly type: 'object';
+  readonly required: readonly ['op', 'doc_id'];
+  readonly additionalProperties: false;
+  readonly properties: {
+    readonly op: {
+      readonly type: 'string';
+      readonly enum: readonly ['snapshot', 'run-edit-script', 'commit-plan'];
+      readonly description: 'Which Medeo document operation to run.';
+    };
+    readonly doc_id: {
+      readonly type: 'string';
+      readonly minLength: 1;
+      readonly description: 'Medeo document id. Copy it from the host context; never invent it.';
+    };
+    readonly script: {
+      readonly type: 'string';
+      readonly minLength: 1;
+      readonly description: 'JavaScript body for run-edit-script. It receives edit, timeline, checkpoint, rollbackTo, inputs, and console; perform all calculations in the script.';
+    };
+    readonly inputs: {
+      readonly type: 'object';
+      readonly description: 'Pre-materialized, side-effect-free values passed into the script. Generation and network IO must happen in the host before this call.';
+    };
+    readonly timeout_ms: {
+      readonly type: 'integer';
+      readonly minimum: 1;
+      readonly description: 'Maximum script wall-clock time after worker startup (default 2000).';
+    };
+    readonly memory_limit_mb: {
+      readonly type: 'integer';
+      readonly minimum: 16;
+      readonly description: 'Worker old-generation memory ceiling in MB (default 256).';
+    };
+    readonly auto_commit: {
+      readonly type: 'boolean';
+      readonly description: 'Commit the returned plan immediately after the sandbox succeeds. Default false: return preview plus plan_id for explicit commit.';
+    };
+    readonly plan_id: {
+      readonly type: 'string';
+      readonly minLength: 1;
+      readonly description: 'Plan id returned by run-edit-script; required by commit-plan.';
+    };
+    readonly validation: {
+      readonly type: 'string';
+      readonly enum: readonly ['version', 'preflight'];
+      readonly description: 'commit-plan mode: version rejects any concurrent change; preflight revalidates each op against the current snapshot.';
+    };
+  };
+  readonly oneOf: readonly [{
+    readonly required: readonly ['op', 'doc_id'];
+    readonly properties: {
+      readonly op: {
+        readonly const: 'snapshot';
+      };
+      readonly doc_id: {
+        readonly $ref: '#/properties/doc_id';
+      };
+    };
+    readonly additionalProperties: false;
+  }, {
+    readonly required: readonly ['op', 'doc_id', 'script'];
+    readonly properties: {
+      readonly op: {
+        readonly const: 'run-edit-script';
+      };
+      readonly doc_id: {
+        readonly $ref: '#/properties/doc_id';
+      };
+      readonly script: {
+        readonly $ref: '#/properties/script';
+      };
+      readonly inputs: {
+        readonly $ref: '#/properties/inputs';
+      };
+      readonly timeout_ms: {
+        readonly $ref: '#/properties/timeout_ms';
+      };
+      readonly memory_limit_mb: {
+        readonly $ref: '#/properties/memory_limit_mb';
+      };
+      readonly auto_commit: {
+        readonly $ref: '#/properties/auto_commit';
+      };
+    };
+    readonly additionalProperties: false;
+  }, {
+    readonly required: readonly ['op', 'doc_id', 'plan_id'];
+    readonly properties: {
+      readonly op: {
+        readonly const: 'commit-plan';
+      };
+      readonly doc_id: {
+        readonly $ref: '#/properties/doc_id';
+      };
+      readonly plan_id: {
+        readonly $ref: '#/properties/plan_id';
+      };
+      readonly validation: {
+        readonly $ref: '#/properties/validation';
+      };
+    };
+    readonly additionalProperties: false;
+  }];
+};
+//#endregion
+//#region src/session/commit-plan.d.ts
+/**
+ * A sandbox journal plus the opaque version token taken at fork time.
+ * `commitPlan` rejects the whole plan when the live session has moved on
+ * (phase-1 version gate), or localizes a business conflict to a journal
+ * entry under `{ validation: 'preflight' }`.
+ */
+interface CommitPlan {
+  /** `session.version()` at the moment the sandbox was forked. */
+  base_version: string;
+  ops: readonly JournalEntry[];
+}
+type CommitPlanResult = {
+  kind: 'committed';
+  ops_applied: number;
+} | {
+  kind: 'rejected';
+  reason: 'version_mismatch';
+  expected: string;
+  actual: string;
+} | {
+  kind: 'rejected';
+  reason: 'op_conflict'; /** Failing entry index in the journal — agent rerun anchor. */
+  index: number;
+  op_kind: SemanticOpName; /** Validator message, passed through verbatim (never a raw Error). */
+  message: string;
+};
+interface CommitPlanOptions {
+  /** `'version'` (default, phase-1 hard gate) | `'preflight'` (phase-2 per-op revalidation). */
+  validation?: 'version' | 'preflight';
+}
+/**
+ * Replay a sandbox journal into a live session through its document adapter
+ * (SemanticEditor → Loro → mengine-server).
+ *
+ * - Default / `{ validation: 'version' }`: if `session.version()` ≠
+ *   `plan.base_version`, reject with zero writes.
+ * - `{ validation: 'preflight' }`: skip the version gate; revalidate each op
+ *   against a PlainMemoryAdapter seeded from the current live snapshot, then
+ *   replay for real. A SchemaValidator failure becomes `op_conflict` with the
+ *   failing entry's index. Journal integrity errors (unrecorded/unconsumed
+ *   ids) still propagate as throws in both modes.
+ */
+declare function commitPlan(session: MengineDocSession, plan: CommitPlan, options?: CommitPlanOptions): Promise<CommitPlanResult>;
+//#endregion
+//#region src/host-tool.d.ts
+type ContextualValue<T> = T | ((docId: string) => T | undefined);
+interface CreateMedeoToolOptions {
+  /**
+   * Mengine HTTP origin for a document. The host owns environment routing
+   * (local/stg/prd/lane) and may return a different origin per document.
+   * Sessions cache by doc id, so the origin must remain stable for that doc.
+   */
+  httpOrigin: ContextualValue<string>;
+  /** Optional bearer token, evaluated for each HTTP request. */
+  authToken?: ContextualValue<string>;
+  /** Optional end-user id header, evaluated for each HTTP request. */
+  userId?: ContextualValue<string>;
+  /** Stable agent peer id. Supply a host-scoped value so audit provenance is durable. */
+  peerId?: ContextualValue<string>;
+  fetchImpl?: typeof fetch;
+  sseReconnectDelayMs?: number;
+  /** Defaults passed to runEditScript; each call may override them. */
+  sandbox?: {
+    timeoutMs?: number;
+    memoryLimitMb?: number;
+  };
+  /** Maximum cached plans; oldest plans are evicted (default 16). */
+  maxPlans?: number;
+}
+type MedeoToolInput = {
+  op: 'snapshot';
+  doc_id: string;
+} | {
+  op: 'run-edit-script';
+  doc_id: string;
+  script: string;
+  inputs?: Record<string, unknown>;
+  timeout_ms?: number;
+  memory_limit_mb?: number;
+  auto_commit?: boolean;
+} | {
+  op: 'commit-plan';
+  doc_id: string;
+  plan_id: string;
+  validation?: 'version' | 'preflight';
+};
+type MedeoToolResult = {
+  ok: true;
+  op: 'snapshot';
+  doc_id: string;
+  version: string;
+  preview: string;
+} | {
+  ok: true;
+  op: 'run-edit-script';
+  doc_id: string;
+  plan_id: string;
+  base_version: string;
+  ops_count: number;
+  preview: string;
+  logs: string[];
+  duration_ms: number;
+  committed?: boolean;
+  commit_result?: CommitPlanResult;
+} | {
+  ok: false;
+  op: 'run-edit-script';
+  doc_id: string;
+  phase: 'parse' | 'runtime' | 'timeout' | 'memory';
+  error: {
+    message: string;
+    line?: number;
+    column?: number;
+    stack?: string;
+  };
+  partial: {
+    ops_count: number;
+    logs: string[];
+  };
+} | {
+  ok: true;
+  op: 'commit-plan';
+  doc_id: string;
+  plan_id: string;
+  committed: boolean;
+  result: CommitPlanResult;
+} | {
+  ok: false;
+  op: MedeoToolOp;
+  error: string;
+};
+interface MedeoTool {
+  name: typeof MEDEO_TOOL_NAME;
+  description: typeof MEDEO_TOOL_DESCRIPTION;
+  parameters: typeof MEDEO_TOOL_PARAMETERS;
+  handle(input: unknown): Promise<MedeoToolResult>;
+  close(): Promise<void>;
+}
+/**
+ * Create the self-contained Medeo LLM tool.
+ *
+ * The package owns session construction, compact projection, sandbox execution,
+ * plan caching, commit, and shutdown. The host supplies only environment facts:
+ * HTTP origin, credentials, fetch implementation, and a stable peer id.
+ */
+declare function createMedeoTool(options: CreateMedeoToolOptions): MedeoTool;
+//#endregion
+export { type ChangePlan, type CommitPlan, type CommitPlanOptions, type CommitPlanResult, type CompactProjectionOptions, type ConsoleShim, type CreateMedeoToolOptions, type EditFacade, EditSandboxSession, type EditSandboxSessionOptions, type EditScriptResult, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RunEditScriptOptions, type SandboxCheckpoint, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
+//# sourceMappingURL=index.d.mts.map