@mengine/medeo-tool 1.0.1-alpha.2 → 1.2.1-alpha.10

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { JournalEntry, MengineDocSession, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft, 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";
+import { _ as SandboxEntity, a as EntityFacade, b as UpdateEntityInput, c as JsonObject, d as KnownEntityKind, f as KnownRelationKind, g as ResourceEntityKind, h as RelationFacade, i as EntityCommand, l as JsonPrimitive, m as LinkRelationInput, n as CreateEntityInput, o as EntityPlanState, p as LinkGeneratedRelationInput, r as DeleteEntityInput, s as EntityStoreSnapshot, t as AuthorableRelationKind, u as JsonValue, v as SandboxRelation, y as UnlinkRelationInput } from "./entity-contract-C5HHaYKk.mjs";
+import { JournalEntry, ManualSyncDoc, MediaAssetFact, PartIdFactory, SemanticOpName, VideoDocument, VideoDraft, fromVideoDocument } from "@mengine/medeo-client";
+import { AddSpeechesInput, AddVideoClipsInput, AdjustBgmVolumeInput, AdjustSpeechVolumeInput, AdjustVideoClipDurationInput, AdjustVideoClipVolumeInput, ChangeSpeechScriptInput, ChangeSpeechVoiceInput, DeleteBgmInput, DeleteSpeechesInput, DeleteVideoClipsInput, MoveSpeechesInput, MoveVideoClipsByAnchorInput, MoveVideoClipsInput, ReplaceVideoClipContentInput, ReplaceVideoClipSequenceInput, SetBgmInput, SetCaptionStyleInput, SetCaptionVisibilityInput, SetVideoClipSpeedShiftInput } from "@mengine/medeo-client/schemas";
 
 //#region src/document/compact-projection.d.ts
 /**
@@ -32,6 +33,9 @@ declare function collectAffectedPartIds(journal: readonly JournalEntry[]): Set<s
  */
 declare function renderPreview(document: VideoDocument, journal: readonly JournalEntry[]): string;
 //#endregion
+//#region src/entity/entity-sandbox.d.ts
+type DomainIdFactory = (prefix: 'entity' | 'relation') => string;
+//#endregion
 //#region src/sandbox/script-session.d.ts
 /**
  * Runtime-neutral edit-sandbox session: `edit.*` / `timeline.*` / checkpoint
@@ -45,9 +49,15 @@ interface SandboxCheckpoint {
   readonly index: number;
 }
 interface ChangePlan {
+  readonly plan_kind: 'timeline' | 'entities';
   doc_id: string;
   base_version: string;
   ops: readonly JournalEntry[];
+  entity_base_revision: number;
+  entity_commands: readonly EntityCommand[];
+  entity_rows?: EntityStoreSnapshot;
+  deleted_entity_ids?: readonly string[];
+  deleted_relation_ids?: readonly string[];
   preview: string;
   logs: string[];
 }
@@ -57,6 +67,10 @@ interface EditSandboxSessionOptions {
   onLog?: (line: string) => void;
   /** Notify host that the streamed journal was truncated to `index` (rollback). */
   onTruncate?: (index: number) => void;
+  entityState?: EntityStoreSnapshot;
+  domainIdFactory?: DomainIdFactory;
+  onEntityCommand?: (command: EntityCommand) => void;
+  onEntityTruncate?: (index: number) => void;
 }
 interface TimelineClipDescriptor {
   id: string;
@@ -83,6 +97,7 @@ declare class EditSandboxSession {
   private readonly onEntry;
   private readonly onLog;
   private readonly onTruncate;
+  private readonly entitySandbox;
   private current;
   /** Adapter journal length already accounted for — new slices are real commits. */
   private adapterJournalSeen;
@@ -92,6 +107,8 @@ declare class EditSandboxSession {
   private logCapped;
   readonly edit: EditFacade;
   readonly timeline: TimelineFacade;
+  readonly entities: EntityFacade;
+  readonly relations: RelationFacade;
   readonly console: ConsoleShim;
   readonly checkpoint: () => SandboxCheckpoint;
   readonly rollbackTo: (cp: SandboxCheckpoint) => void;
@@ -124,7 +141,9 @@ interface EditFacade {
   deleteVideoClips: (input: DeleteVideoClipsInput) => Promise<void>;
   moveSpeeches: (input: MoveSpeechesInput) => Promise<void>;
   moveVideoClips: (input: MoveVideoClipsInput) => Promise<void>;
+  moveVideoClipsByAnchor: (input: MoveVideoClipsByAnchorInput) => Promise<void>;
   replaceVideoClipContent: (input: ReplaceVideoClipContentInput) => Promise<void>;
+  replaceVideoClipSequence: (input: ReplaceVideoClipSequenceInput) => Promise<void>;
   setBgm: (input: SetBgmInput) => Promise<void>;
   setCaptionStyle: (input: SetCaptionStyleInput) => Promise<void>;
   setCaptionVisibility: (input: SetCaptionVisibilityInput) => Promise<void>;
@@ -155,8 +174,12 @@ interface RunEditScriptOptions {
   baseVersion: string;
   script: string;
   inputs?: Record<string, unknown>;
+  /** Authoritative entity/relation rows and revision fetched for this document. */
+  entityState?: EntityStoreSnapshot;
   /** Deterministic id mint label for tests; omit to use the default ULID factory. */
   idLabel?: string;
+  /** @internal Select the graph-native Entity session used by the production host. */
+  entityOnly?: boolean;
   /** Hard wall-clock timeout; default 2000 ms. */
   timeoutMs?: number;
   /** V8 old-generation ceiling for the worker; default 256 MB. */
@@ -179,20 +202,53 @@ type EditScriptResult = {
   };
   partial: {
     ops: readonly JournalEntry[];
+    entityCommands: readonly EntityCommand[];
     logs: string[];
   };
 };
 /** Run `script` against a forked document snapshot; always resolves (never rejects). */
 declare function runEditScript(options: RunEditScriptOptions): Promise<EditScriptResult>;
 //#endregion
+//#region src/entity/generation-sync.d.ts
+/** Factual generation lineage for recalled Memota assets, supplied by the host. */
+interface AssetGenerationFact {
+  /** External asset id of the generation output (memota asset or speech result id). */
+  readonly outputAssetId: string;
+  /** Factual input asset ids; empty for text-only generation. */
+  readonly inputAssetIds: readonly string[];
+}
+/**
+ * Host callback resolving lineage by external asset id. Implementations return
+ * every known generation record involving the given ids in either role; an
+ * empty array means no known lineage and a rejection means the lineage query
+ * failed. Entity and Relation semantics stay inside this package.
+ */
+type GenerationFactsLoader = (docId: string, assetIds: readonly string[]) => Promise<readonly AssetGenerationFact[]>;
+/**
+ * Outcome of the post-commit lineage sync. `failed` is always also surfaced as
+ * a `generation_sync_failed` warning so an unavailable lineage query is never
+ * presented as synced state.
+ */
+interface GenerationSyncOutcome {
+  /**
+   * applied: new generated Relations were committed.
+   * current: the query succeeded and nothing was missing (no created asset,
+   * single side absent, text-only generation, or pair already linked).
+   * failed: the host query or the sync commit failed.
+   */
+  readonly status: 'applied' | 'current' | 'failed';
+  readonly created_relation_ids?: readonly string[];
+  readonly message?: string;
+}
+//#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';
+type MedeoToolOp = 'snapshot' | 'migrate-legacy' | 'run-edit-script' | 'commit-plan';
 /**
- * JSON Schema for the host-facing three-op `medeo` tool surface.
+ * JSON Schema for the host-facing `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
@@ -200,105 +256,223 @@ type MedeoToolOp = 'snapshot' | 'run-edit-script' | 'commit-plan';
  * journal used for commit.
  */
 declare const MEDEO_TOOL_PARAMETERS: {
-  readonly type: 'object';
-  readonly required: readonly ['op', 'doc_id'];
+  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 type: "string";
+      readonly enum: readonly ["snapshot", "migrate-legacy", "run-edit-script", "commit-plan"];
+      readonly description: "Which Medeo document operation to run.";
     };
     readonly doc_id: {
-      readonly type: 'string';
+      readonly type: "string";
       readonly minLength: 1;
-      readonly description: 'Medeo document id. Copy it from the host context; never invent it.';
+      readonly description: "Medeo document id. Copy it from the host context; never invent it.";
     };
     readonly script: {
-      readonly type: 'string';
+      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 description: "JavaScript body for run-edit-script. Use edit, timeline, entities, relations, checkpoint, rollbackTo, inputs, and console. Asset import, media relations, and timeline entity edits share one entity plan.";
     };
     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 type: "object";
+      readonly description: "Pre-materialized, side-effect-free values passed into the script, including recalled asset facts. Generation history is never an input: the host queries lineage itself and syncs generated Relations after each commit. Generation and network IO must happen in the host before this call.";
+    };
+    readonly asset_facts: {
+      readonly type: "array";
+      readonly description: "Factual asset metadata recalled by the host for migrate-legacy only. The package reads the canonical legacy snapshot and version itself; never supply a clip trim window as media duration.";
+      readonly items: {
+        readonly oneOf: readonly [{
+          readonly type: "object";
+          readonly additionalProperties: false;
+          readonly required: readonly ["assetId", "kind"];
+          readonly properties: {
+            readonly assetId: {
+              readonly type: "string";
+              readonly minLength: 1;
+            };
+            readonly kind: {
+              readonly const: "image";
+            };
+            readonly storageKey: {
+              readonly type: "string";
+              readonly minLength: 1;
+            };
+          };
+        }, {
+          readonly type: "object";
+          readonly additionalProperties: false;
+          readonly required: readonly ["assetId", "kind", "durationMs"];
+          readonly properties: {
+            readonly assetId: {
+              readonly type: "string";
+              readonly minLength: 1;
+            };
+            readonly kind: {
+              readonly const: "video";
+            };
+            readonly durationMs: {
+              readonly type: "integer";
+              readonly minimum: 1;
+            };
+            readonly storageKey: {
+              readonly type: "string";
+              readonly minLength: 1;
+            };
+          };
+        }, {
+          readonly type: "object";
+          readonly additionalProperties: false;
+          readonly required: readonly ["assetId", "kind", "durationMs", "storageKey"];
+          readonly properties: {
+            readonly assetId: {
+              readonly type: "string";
+              readonly minLength: 1;
+            };
+            readonly kind: {
+              readonly const: "audio";
+            };
+            readonly durationMs: {
+              readonly type: "integer";
+              readonly minimum: 1;
+            };
+            readonly storageKey: {
+              readonly type: "string";
+              readonly minLength: 1;
+            };
+          };
+        }, {
+          readonly type: "object";
+          readonly additionalProperties: false;
+          readonly required: readonly ["assetId", "kind", "durationMs", "storageKey", "voice"];
+          readonly properties: {
+            readonly kind: {
+              readonly const: "voice";
+            };
+            readonly assetId: {
+              readonly type: "string";
+              readonly minLength: 1;
+            };
+            readonly durationMs: {
+              readonly type: "integer";
+              readonly minimum: 1;
+            };
+            readonly storageKey: {
+              readonly type: "string";
+              readonly minLength: 1;
+            };
+            readonly voice: {
+              readonly type: "object";
+              readonly additionalProperties: false;
+              readonly required: readonly ["system", "key"];
+              readonly properties: {
+                readonly system: {
+                  readonly const: "voice-library";
+                };
+                readonly key: {
+                  readonly type: "string";
+                  readonly minLength: 1;
+                };
+                readonly name: {
+                  readonly type: "string";
+                };
+              };
+            };
+          };
+        }];
+      };
     };
     readonly timeout_ms: {
-      readonly type: 'integer';
+      readonly type: "integer";
       readonly minimum: 1;
-      readonly description: 'Maximum script wall-clock time after worker startup (default 2000).';
+      readonly description: "Maximum script wall-clock time after worker startup (default 2000).";
     };
     readonly memory_limit_mb: {
-      readonly type: 'integer';
+      readonly type: "integer";
       readonly minimum: 16;
-      readonly description: 'Worker old-generation memory ceiling in MB (default 256).';
+      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 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 type: "string";
       readonly minLength: 1;
-      readonly description: 'Plan id returned by run-edit-script; required by commit-plan.';
+      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 type: "string";
+      readonly enum: readonly ["version"];
+      readonly description: "Commit with Entity revision CAS; reject concurrent changes.";
     };
   };
   readonly oneOf: readonly [{
-    readonly required: readonly ['op', 'doc_id'];
+    readonly required: readonly ["op", "doc_id", "asset_facts"];
     readonly properties: {
       readonly op: {
-        readonly const: 'snapshot';
+        readonly const: "migrate-legacy";
       };
       readonly doc_id: {
-        readonly $ref: '#/properties/doc_id';
+        readonly $ref: "#/properties/doc_id";
+      };
+      readonly asset_facts: {
+        readonly $ref: "#/properties/asset_facts";
       };
     };
     readonly additionalProperties: false;
   }, {
-    readonly required: readonly ['op', 'doc_id', 'script'];
+    readonly required: readonly ["op", "doc_id"];
     readonly properties: {
       readonly op: {
-        readonly const: 'run-edit-script';
+        readonly const: "snapshot";
       };
       readonly doc_id: {
-        readonly $ref: '#/properties/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 $ref: "#/properties/script";
       };
       readonly inputs: {
-        readonly $ref: '#/properties/inputs';
+        readonly $ref: "#/properties/inputs";
       };
       readonly timeout_ms: {
-        readonly $ref: '#/properties/timeout_ms';
+        readonly $ref: "#/properties/timeout_ms";
       };
       readonly memory_limit_mb: {
-        readonly $ref: '#/properties/memory_limit_mb';
+        readonly $ref: "#/properties/memory_limit_mb";
       };
       readonly auto_commit: {
-        readonly $ref: '#/properties/auto_commit';
+        readonly $ref: "#/properties/auto_commit";
       };
     };
     readonly additionalProperties: false;
   }, {
-    readonly required: readonly ['op', 'doc_id', 'plan_id'];
+    readonly required: readonly ["op", "doc_id", "plan_id"];
     readonly properties: {
       readonly op: {
-        readonly const: 'commit-plan';
+        readonly const: "commit-plan";
       };
       readonly doc_id: {
-        readonly $ref: '#/properties/doc_id';
+        readonly $ref: "#/properties/doc_id";
       };
       readonly plan_id: {
-        readonly $ref: '#/properties/plan_id';
+        readonly $ref: "#/properties/plan_id";
       };
       readonly validation: {
-        readonly $ref: '#/properties/validation';
+        readonly $ref: "#/properties/validation";
       };
     };
     readonly additionalProperties: false;
@@ -308,23 +482,39 @@ declare const MEDEO_TOOL_PARAMETERS: {
 //#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
+ * `commitPlan` rejects the whole plan when the live document 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. */
+  /** Encoded `ManualSyncDoc.versionMark()` from when the sandbox was forked. */
   base_version: string;
   ops: readonly JournalEntry[];
 }
+interface CommitPlanWarning {
+  kind: 'pull_failed';
+  message: string;
+}
 type CommitPlanResult = {
   kind: 'committed';
   ops_applied: number;
+  collaborated: boolean;
+  warnings?: CommitPlanWarning[];
+} | {
+  kind: 'unconfirmed';
+  reason: 'push_failed';
+  ops_applied: number;
+  message: string;
 } | {
   kind: 'rejected';
   reason: 'version_mismatch';
   expected: string;
   actual: string;
+} | {
+  kind: 'rejected';
+  reason: 'push_rejected';
+  code?: string;
+  message: string;
 } | {
   kind: 'rejected';
   reason: 'op_conflict'; /** Failing entry index in the journal — agent rerun anchor. */
@@ -337,18 +527,18 @@ interface CommitPlanOptions {
   validation?: 'version' | 'preflight';
 }
 /**
- * Replay a sandbox journal into a live session through its document adapter
- * (SemanticEditor → Loro → mengine-server).
+ * Replay a sandbox journal into a manually-synchronized document and push the
+ * whole plan as one causally complete update.
  *
- * - Default / `{ validation: 'version' }`: if `session.version()` ≠
- *   `plan.base_version`, reject with zero writes.
+ * - Default / `{ validation: 'version' }`: if the current document mark differs
+ *   from `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>;
+declare function commitPlan(doc: ManualSyncDoc, plan: CommitPlan, options?: CommitPlanOptions): Promise<CommitPlanResult>;
 //#endregion
 //#region src/host-tool.d.ts
 type ContextualValue<T> = T | ((docId: string) => T | undefined);
@@ -356,7 +546,7 @@ 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.
+   * Documents cache by doc id, so the origin must remain stable for that doc.
    */
   httpOrigin: ContextualValue<string>;
   /** Optional bearer token, evaluated for each HTTP request. */
@@ -372,7 +562,17 @@ interface CreateMedeoToolOptions {
    * snapshot, and tolerates a concurrent creator winning the race.
    */
   loadInitialDraft?: (docId: string) => Promise<VideoDraft>;
+  /**
+   * Resolve factual generation lineage by external asset id after a confirmed
+   * entity commit. Return every known generation record involving the given
+   * ids in either role; an empty array means no known lineage and a rejection
+   * means the lineage query failed (surfaced as a warning, never as synced
+   * state). The package owns all Entity/Relation semantics: the host never
+   * names entities, relations, or endpoints.
+   */
+  loadGenerationFacts?: GenerationFactsLoader;
   fetchImpl?: typeof fetch;
+  /** @deprecated ManualSyncDoc has no SSE or reconnect loop. */
   sseReconnectDelayMs?: number;
   /** Defaults passed to runEditScript; each call may override them. */
   sandbox?: {
@@ -381,10 +581,28 @@ interface CreateMedeoToolOptions {
   };
   /** Maximum cached plans; oldest plans are evicted (default 16). */
   maxPlans?: number;
+  /** Maximum model-call version baselines retained across host contexts (default 128). */
+  maxModelContexts?: number;
+}
+interface MedeoModelContextInput {
+  /** Internal MEngine document id. This is host-supplied and never model-facing. */
+  doc_id: string;
+  /** Stable host conversation/session key used to compare consecutive model calls. */
+  context_id: string;
+}
+interface MedeoModelContext {
+  /** Complete MEngine-owned prompt: workflow, runtime state, and sandbox TypeScript interface. */
+  prompt: string;
+  document_version: string;
+  updated_since_previous_model_call: boolean | null;
 }
 type MedeoToolInput = {
   op: 'snapshot';
   doc_id: string;
+} | {
+  op: 'migrate-legacy';
+  doc_id: string;
+  asset_facts: readonly MediaAssetFact[];
 } | {
   op: 'run-edit-script';
   doc_id: string;
@@ -399,24 +617,68 @@ type MedeoToolInput = {
   plan_id: string;
   validation?: 'version' | 'preflight';
 };
+type MedeoToolWarning = {
+  kind: 'pull_failed';
+  message: string;
+} | {
+  kind: 'generation_sync_failed';
+  message: string;
+};
+type EntityCommitResult = {
+  kind: 'committed';
+  ops_applied: number;
+  collaborated: false;
+  entity_revision: number; /** Present only when the host supplies loadGenerationFacts. */
+  generation_sync?: GenerationSyncOutcome;
+  warnings?: MedeoToolWarning[];
+} | {
+  kind: 'unconfirmed';
+  reason: 'push_failed';
+  ops_applied: number;
+  message: string;
+} | {
+  kind: 'rejected';
+  reason: 'entity_revision_mismatch';
+  expected: number;
+  actual: number;
+} | {
+  kind: 'rejected';
+  reason: 'entity_state_rejected';
+  status: number;
+  message: string;
+};
+type MedeoCommitResult = CommitPlanResult | EntityCommitResult;
 type MedeoToolResult = {
+  ok: true;
+  op: 'migrate-legacy';
+  doc_id: string;
+  migration_status: 'committed' | 'already_entity';
+  entity_revision: number;
+  next_action: 'snapshot';
+} | {
   ok: true;
   op: 'snapshot';
   doc_id: string;
   version: string;
   preview: string;
+  collaborated?: boolean;
+  warnings?: MedeoToolWarning[];
 } | {
   ok: true;
   op: 'run-edit-script';
   doc_id: string;
   plan_id: string;
+  plan_kind: 'timeline' | 'entities';
   base_version: string;
+  entity_base_revision: number;
   ops_count: number;
   preview: string;
   logs: string[];
   duration_ms: number;
   committed?: boolean;
-  commit_result?: CommitPlanResult;
+  commit_result?: MedeoCommitResult;
+  collaborated?: boolean;
+  warnings?: MedeoToolWarning[];
 } | {
   ok: false;
   op: 'run-edit-script';
@@ -437,8 +699,11 @@ type MedeoToolResult = {
   op: 'commit-plan';
   doc_id: string;
   plan_id: string;
+  plan_kind: 'timeline' | 'entities';
   committed: boolean;
-  result: CommitPlanResult;
+  result: MedeoCommitResult;
+  collaborated?: boolean;
+  warnings?: MedeoToolWarning[];
 } | {
   ok: false;
   op: MedeoToolOp;
@@ -448,6 +713,7 @@ interface MedeoTool {
   name: typeof MEDEO_TOOL_NAME;
   description: typeof MEDEO_TOOL_DESCRIPTION;
   parameters: typeof MEDEO_TOOL_PARAMETERS;
+  getModelContext(input: MedeoModelContextInput): Promise<MedeoModelContext>;
   handle(input: unknown): Promise<MedeoToolResult>;
   close(): Promise<void>;
 }
@@ -455,12 +721,12 @@ type MedeoInitialDraft = VideoDraft;
 /**
  * Create the self-contained Medeo LLM tool.
  *
- * The package owns session construction, compact projection, sandbox execution,
+ * The package owns document construction, compact projection, sandbox execution,
  * plan caching, commit, document get-or-create, and shutdown. The host supplies
  * environment facts plus the authoritative legacy draft loader used only when
  * Mengine has no document yet.
  */
 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 MedeoInitialDraft, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RunEditScriptOptions, type SandboxCheckpoint, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
+export { type AssetGenerationFact, type AuthorableRelationKind, type ChangePlan, type CommitPlan, type CommitPlanOptions, type CommitPlanResult, type CompactProjectionOptions, type ConsoleShim, type CreateEntityInput, type CreateMedeoToolOptions, type DeleteEntityInput, type EditFacade, EditSandboxSession, type EditSandboxSessionOptions, type EditScriptResult, type EntityCommand, type EntityCommitResult, type EntityFacade, type EntityPlanState, type EntityStoreSnapshot, type GenerationFactsLoader, type GenerationSyncOutcome, type JsonObject, type JsonPrimitive, type JsonValue, type KnownEntityKind, type KnownRelationKind, type LinkGeneratedRelationInput, type LinkRelationInput, MEDEO_TOOL_DESCRIPTION, MEDEO_TOOL_NAME, MEDEO_TOOL_PARAMETERS, type MedeoCommitResult, type MedeoInitialDraft, type MedeoModelContext, type MedeoModelContextInput, type MedeoTool, type MedeoToolInput, type MedeoToolOp, type MedeoToolResult, type RelationFacade, type ResourceEntityKind, type RunEditScriptOptions, type SandboxCheckpoint, type SandboxEntity, type SandboxRelation, type TimelineClipDescriptor, type TimelineFacade, type TimelinePartDescriptor, type UnlinkRelationInput, type UpdateEntityInput, collectAffectedPartIds, commitPlan, createMedeoTool, renderCompactProjection, renderPreview, runEditScript };
 //# sourceMappingURL=index.d.mts.map