@axiom-lattice/core 3.1.2 → 4.0.0

package/dist/index.d.mts

@@ -8,7 +8,7 @@ import { BaseLanguageModelInput, LanguageModelLike } from '@langchain/core/langu
 import { CallbackManagerForLLMRun } from '@langchain/core/callbacks/manager';
 import { ChatResult } from '@langchain/core/outputs';
 import * as _axiom_lattice_protocols from '@axiom-lattice/protocols';
-import { LLMConfig, SemanticMetricsServerConfig, MetricMeta, MetricQueryResult, DataSource, SemanticMetricsQueryRequest, SemanticMetricsQueryResponse, TableQueryRequest, TableQueryResponse, ExecuteSqlQueryRequest, ExecuteSqlQueryResponse, MetricsServerType, MetricsServerConfig, ToolConfig, ToolExecutor, AgentConfig, MiddlewareType, GraphBuildOptions, MessageChunk, MessageChunkType, QueueLatticeProtocol, QueueConfig, QueueClient, QueueResult, ScheduleLatticeProtocol, ScheduleConfig, ScheduleClient, ScheduleStorage, TaskHandler, ScheduleOnceOptions, ScheduleCronOptions, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, ThreadStore, AssistantStore, SkillStore, CollectionStore, WorkspaceStore, ProjectStore, DatabaseConfigStore, MetricsServerConfigStore, McpServerConfigStore, UserStore, TenantStore, UserTenantLinkStore, WorkflowTrackingStore, EvalStore, ChannelInstallationStore, BindingRegistry, MenuRegistry, A2AApiKeyStore, TaskStore, SharedResourceStore, ConnectionStore, TaskWorkItemStore, VectorStoreProvider, Thread, CreateThreadRequest, Assistant, CreateAssistantRequest, Skill, CreateSkillRequest, SkillStoreContext, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, User, CreateUserRequest, UpdateUserRequest, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationRequest, UpdateChannelInstallationRequest, Binding, CreateBindingInput, A2AApiKeyRecord, CreateA2AApiKeyInput, A2AApiKeyEntry, CreateTaskRequest, TaskItem, TaskListFilter, UpdateTaskRequest, Collection, CreateCollectionRequest, UpdateCollectionRequest, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, STTModelLatticeProtocol, STTConfig, STTClient, TranscriptionResult, LoggerLatticeProtocol, LoggerConfig, LoggerClient, LoggerContext, SkillConfig, SkillClient, McpTool, ResourceResolver, ResourceAddress, ShareVisibility, CreateShareRequest, ChannelAdapter, InterruptPolicy, PluginMeta, Plugin, PluginMetaOutput, InternalStateField, InternalInput, InternalNode, InternalAgentNode, InternalMapNode, InternalDSL, ConnectionEntry } from '@axiom-lattice/protocols';
+import { LLMConfig, SemanticMetricsServerConfig, MetricMeta, MetricQueryResult, DataSource, SemanticMetricsQueryRequest, SemanticMetricsQueryResponse, TableQueryRequest, TableQueryResponse, ExecuteSqlQueryRequest, ExecuteSqlQueryResponse, MetricsServerType, MetricsServerConfig, ToolConfig, ToolExecutor, AgentConfig, MiddlewareType, GraphBuildOptions, MessageChunk, MessageChunkType, QueueLatticeProtocol, QueueConfig, QueueClient, QueueResult, ScheduleLatticeProtocol, ScheduleConfig, ScheduleClient, ScheduleStorage, TaskHandler, ScheduleOnceOptions, ScheduleCronOptions, ScheduledTaskDefinition, ScheduledTaskStatus, ScheduleExecutionType, ThreadStore, AssistantStore, SkillStore, CollectionStore, WorkspaceStore, ProjectStore, DatabaseConfigStore, MetricsServerConfigStore, McpServerConfigStore, UserStore, TenantStore, UserTenantLinkStore, WorkflowTrackingStore, EvalStore, ChannelInstallationStore, BindingRegistry, MenuRegistry, A2AApiKeyStore, TaskStore, SharedResourceStore, ConnectionStore, TaskWorkItemStore, VectorStoreProvider, Thread, CreateThreadRequest, Assistant, CreateAssistantRequest, Skill, CreateSkillRequest, SkillStoreContext, DatabaseConfigEntry, CreateDatabaseConfigRequest, UpdateDatabaseConfigRequest, User, CreateUserRequest, UpdateUserRequest, Tenant, CreateTenantRequest, UpdateTenantRequest, UserTenantLink, CreateUserTenantLinkRequest, UpdateUserTenantLinkRequest, ChannelInstallation, ChannelInstallationType, CreateChannelInstallationRequest, UpdateChannelInstallationRequest, Binding, CreateBindingInput, A2AApiKeyRecord, CreateA2AApiKeyInput, A2AApiKeyEntry, CreateTaskRequest, TaskItem, TaskListFilter, UpdateTaskRequest, Collection, CreateCollectionRequest, UpdateCollectionRequest, MenuItem, CreateMenuItemInput, UpdateMenuItemInput, STTModelLatticeProtocol, STTConfig, STTClient, TranscriptionResult, LoggerLatticeProtocol, LoggerConfig, LoggerClient, LoggerContext, SkillConfig, SkillClient, McpTool, ResourceResolver, ResourceAddress, ShareVisibility, CreateShareRequest, ChannelAdapter, InterruptPolicy, TaskBeliefState, PluginMeta, Plugin, PluginMetaOutput, InternalStateField, InternalInput, InternalNode, InternalAgentNode, InternalMapNode, InternalDSL, ConnectionEntry } from '@axiom-lattice/protocols';
 export { _axiom_lattice_protocols as Protocols };
 export { AgentConfig, AgentType, GraphBuildOptions, MemoryType } from '@axiom-lattice/protocols';
 import * as langchain from 'langchain';
@@ -3110,6 +3110,19 @@ declare class FileSystemSkillStore implements SkillStore {
      * @returns The resource content as string
      */
     loadSkillResource(_tenantId: string, skillName: string, resourcePath: string): Promise<string | null>;
+    /**
+     * Write a resource file into a skill's resources directory
+     * @param tenantId The tenant identifier (accepted for protocol compliance)
+     * @param skillName The skill name
+     * @param resourcePath Path to the resource relative to resources/ directory
+     * @param content Resource content
+     */
+    writeSkillResource(_tenantId: string, skillName: string, resourcePath: string, content: string): Promise<void>;
+    /** Load a skill resource as bytes. */
+    loadSkillResourceRaw(_tenantId: string, skillName: string, resourcePath: string): Promise<Buffer | null>;
+    /** Write skill resource bytes without text encoding. */
+    writeSkillResourceRaw(_tenantId: string, skillName: string, resourcePath: string, data: Buffer): Promise<void>;
+    private resolveResourcePath;
 }
 
 /**
@@ -3213,6 +3226,25 @@ declare class SandboxSkillStore implements SkillStore {
       * Get sub-skills of a parent skill within a tenant
       */
     getSubSkills(tenantId: string, parentSkillName: string, context?: SkillStoreContext): Promise<Skill[]>;
+    /**
+     * List all resources in a skill's resources directory (within sandbox).
+     * Returns paths relative to the resources/ directory.
+     */
+    listSkillResources(tenantId: string, id: string, context?: SkillStoreContext): Promise<string[]>;
+    /**
+     * Load a specific resource from a skill's resources directory (within sandbox).
+     */
+    loadSkillResource(tenantId: string, id: string, resourcePath: string, context?: SkillStoreContext): Promise<string | null>;
+    /**
+     * Write a resource file into a skill's resources directory (within sandbox).
+     * Creates parent directories as needed.
+     */
+    writeSkillResource(tenantId: string, id: string, resourcePath: string, content: string, context?: SkillStoreContext): Promise<void>;
+    /** Load a resource as bytes through the sandbox file API. */
+    loadSkillResourceRaw(tenantId: string, id: string, resourcePath: string, context?: SkillStoreContext): Promise<Buffer | null>;
+    /** Write resource bytes through the sandbox file API. */
+    writeSkillResourceRaw(tenantId: string, id: string, resourcePath: string, data: Buffer, context?: SkillStoreContext): Promise<void>;
+    private validateResourcePath;
 }
 
 /**
@@ -3508,9 +3540,11 @@ declare class InMemoryBindingStore implements BindingRegistry {
     clear(): void;
 }
 
+/** In-memory A2A API key persistence for development and tests. */
 declare class InMemoryA2AApiKeyStore implements A2AApiKeyStore {
     private keys;
     findByKey(key: string): Promise<A2AApiKeyRecord | null>;
+    findById(id: string): Promise<A2AApiKeyRecord | null>;
     list(params: {
         tenantId?: string;
         limit?: number;
@@ -3560,8 +3594,14 @@ declare class InMemoryThreadMessageQueueStore implements IMessageQueueStore {
  */
 declare class InMemoryTaskStore implements TaskStore {
     private tasks;
+    private cloneTask;
+    private nextUpdatedAt;
+    private canAdvanceUpdatedAt;
+    private recognizedUpdates;
+    private applyUpdates;
     /**
      * Create a new task
+     * @throws Error when the tenant already contains the requested task ID.
      */
     create(params: CreateTaskRequest & {
         tenantId: string;
@@ -3580,6 +3620,22 @@ declare class InMemoryTaskStore implements TaskStore {
      * Update an existing task
      */
     update(tenantId: string, id: string, updates: UpdateTaskRequest): Promise<TaskItem | null>;
+    /** Atomically update a task only when its current status is expected. */
+    updateIfStatusIn(tenantId: string, id: string, updates: UpdateTaskRequest, expectedStatuses: TaskItem["status"][]): Promise<TaskItem | null>;
+    /**
+     * Atomically update a task unless its current status is blocked.
+     *
+     * @param tenantId Tenant identifier.
+     * @param id Task identifier.
+     * @param updates Partial task data to update.
+     * @param blockedStatuses Current statuses that prevent the update.
+     * @returns The updated task, or `null` when missing or blocked.
+     */
+    updateIfStatusNotIn(tenantId: string, id: string, updates: UpdateTaskRequest, blockedStatuses: TaskItem["status"][]): Promise<TaskItem | null>;
+    /** Atomically update a task only when status and updatedAt match a read snapshot. */
+    updateIfStatusAndUpdatedAt(tenantId: string, id: string, updates: UpdateTaskRequest, expectedStatuses: TaskItem["status"][], expectedUpdatedAt: Date | string): Promise<TaskItem | null>;
+    /** Atomically update a child only when both child and parent snapshots match. */
+    updateIfStatusUpdatedAtAndParentUpdatedAt(tenantId: string, id: string, updates: UpdateTaskRequest, expectedStatuses: TaskItem["status"][], expectedUpdatedAt: Date | string, parentId: string, expectedParentUpdatedAt: Date | string): Promise<TaskItem | null>;
     /**
      * Delete a task by ID
      */
@@ -7476,6 +7532,289 @@ declare class AgentInstanceManager {
 }
 declare const agentInstanceManager: AgentInstanceManager;
 
+/**
+ * A single structured belief report attached to a task completion.
+ *
+ * Mirrors the `manage_task.beliefImpact` tool field: the reporting task claims
+ * that, after execution, the named Belief Key is true with `after` percent
+ * probability, supported by `basis` evidence.
+ */
+interface BeliefImpactInput {
+    key: string;
+    after: number;
+    basis: string;
+}
+
+/** A recoverable work-item failure that occurred after a task transition committed. */
+interface LifecycleWarning {
+    code: string;
+    taskId: string;
+    evidenceId?: string;
+    eventKey?: string;
+    parentTaskId?: string;
+}
+/** The structured outcome returned by every task lifecycle operation. */
+type LifecycleResult = {
+    success: true;
+    task: TaskItem;
+    evidenceId?: string;
+    eventKey?: string;
+    warnings?: LifecycleWarning[];
+} | {
+    success: false;
+    code: string;
+    error: string;
+    hint?: string;
+    evidenceId?: string;
+    eventKey?: string;
+    warnings?: LifecycleWarning[];
+};
+/** Stores and clock used by {@link TaskLifecycleService}. */
+interface TaskLifecycleServiceDeps {
+    taskStore: TaskStore;
+    workItemStore: TaskWorkItemStore;
+    now?: () => Date;
+}
+/** Input shared by direct completion and completion repair. */
+interface AgentTaskCompletionInput {
+    tenantId: string;
+    taskId: string;
+    result: string;
+    beliefImpact: BeliefImpactInput[];
+    actor: string;
+    threadId?: string;
+    sourceId?: string;
+}
+/** Input for submitting agent completion evidence to HITL review. */
+interface SubmitTaskReviewInput extends AgentTaskCompletionInput {
+    reviewMode: "disabled" | "hitl";
+    /** Atomically enables review as part of the in-progress-to-interrupted transition. */
+    configureRequireReview?: boolean;
+}
+/** Input for approving completion evidence after an HITL resume. */
+interface ApproveInterruptedTaskInput {
+    tenantId: string;
+    taskId: string;
+    evidenceId: string;
+    actor: string;
+    threadId?: string;
+}
+/** Input for rejecting completion evidence after an HITL resume. */
+interface RejectInterruptedTaskInput extends ApproveInterruptedTaskInput {
+    note: string;
+}
+/** Input for a description update that audits semantic Belief State changes. */
+interface ReconcileTaskDescriptionInput {
+    tenantId: string;
+    taskId: string;
+    description: string;
+    actor: string;
+    threadId?: string;
+}
+/** Input for resuming an interruption that is not waiting for human review. */
+interface ResumeInterruptionInput {
+    /** Tenant containing the task. */
+    tenantId: string;
+    /** Interrupted task identifier. */
+    taskId: string;
+    /** Actor making the resume request. */
+    actor: string;
+    /** Optional thread to retain in the interruption audit context. */
+    threadId?: string;
+}
+/** Input for atomically starting or retrying an agent task. */
+interface StartTaskInput {
+    tenantId: string;
+    taskId: string;
+    actor: string;
+    threadId?: string;
+}
+/** Input for atomically failing an active agent task. */
+interface FailTaskInput {
+    tenantId: string;
+    taskId: string;
+    failureReason: string;
+    actor: string;
+    threadId?: string;
+}
+/** Input for atomically cancelling a nonterminal agent task. */
+interface CancelTaskInput {
+    tenantId: string;
+    taskId: string;
+    actor: string;
+    threadId?: string;
+    summary?: string;
+}
+/** Agent-owned interruption kinds persisted by the lifecycle service. */
+type AgentInterruptionType = "missing_input" | "external_dependency" | "user_decision";
+/** Input for atomically interrupting an in-progress agent task. */
+interface InterruptTaskInput {
+    tenantId: string;
+    taskId: string;
+    type: AgentInterruptionType;
+    summary: string;
+    actor: string;
+    threadId?: string;
+}
+/** Canonical identity and Belief State snapshot bound to completion evidence. */
+interface BeliefOwnerSnapshot {
+    owner: "self" | "parent";
+    childParentId?: string;
+    beliefState: TaskBeliefState;
+    self?: {
+        id: string;
+        ownerType: "user" | "agent";
+        ownerId: string;
+        workspaceId?: string;
+        projectId?: string;
+    };
+    parent?: {
+        id: string;
+        ownerType: "user" | "agent";
+        ownerId: string;
+        workspaceId?: string;
+        projectId?: string;
+    };
+    parentUpdatedAt?: string;
+}
+/**
+ * Owns atomic agent-task completion, review, repair, and belief reconciliation.
+ *
+ * Evidence is persisted before status CAS operations. All events written after
+ * CAS have deterministic keys, allowing callers to repair partial persistence.
+ *
+ * @example
+ * ```ts
+ * const service = new TaskLifecycleService({ taskStore, workItemStore });
+ * await service.completeAgentTask({ tenantId, taskId, result, beliefImpact, actor });
+ * ```
+ */
+declare class TaskLifecycleService {
+    private readonly deps;
+    private readonly now;
+    /**
+     * Creates a lifecycle service with injected stores and an optional test clock.
+     *
+     * @param deps Task and work-item stores plus an optional deterministic clock.
+     * @remarks Store operations are translated to structured lifecycle failures by public methods.
+     */
+    constructor(deps: TaskLifecycleServiceDeps);
+    /**
+     * Returns the deterministic task-scoped completion evidence key.
+     *
+     * @param taskId Task receiving the evidence.
+     * @param result Candidate result Markdown.
+     * @param beliefImpact Structured belief evidence.
+     * @param beliefOwner Optional canonical owner snapshot to bind into the key.
+     * @returns A task-scoped key containing the canonical SHA-256 digest.
+     * @remarks Review attempts append `:attempt:N` to this canonical base key.
+     */
+    completionEventKey(taskId: string, result: string, beliefImpact: BeliefImpactInput[], beliefOwner?: BeliefOwnerSnapshot): string;
+    /**
+     * Resumes an interruption unless it is explicitly owned by the review workflow.
+     *
+     * @param input Resume request and actor identity.
+     * @returns Structured task transition result.
+     * @remarks Review interruptions must be approved or rejected through their evidence-bound methods.
+     */
+    resumeInterruption(input: ResumeInterruptionInput): Promise<LifecycleResult>;
+    /** Atomically fails an active agent task and records an idempotent status event. */
+    failTask(input: FailTaskInput): Promise<LifecycleResult>;
+    /** Atomically starts a pending agent task and records an idempotent status event. */
+    startTask(input: StartTaskInput): Promise<LifecycleResult>;
+    /** Atomically retries a failed agent task and records an idempotent status event. */
+    retryTask(input: StartTaskInput): Promise<LifecycleResult>;
+    /** Atomically cancels a nonterminal agent task and records an idempotent status event. */
+    cancelTask(input: CancelTaskInput): Promise<LifecycleResult>;
+    /** Atomically records a governed blocking interruption for an in-progress agent task. */
+    interruptTask(input: InterruptTaskInput): Promise<LifecycleResult>;
+    /**
+     * Atomically completes an in-progress agent task and writes repairable events.
+     * @param input Completion result, belief impacts, actor, and optional thread.
+     * @returns Structured completion result or failure.
+     * @remarks Evidence is written before the status CAS; retries are idempotent by canonical event key.
+     */
+    completeAgentTask(input: AgentTaskCompletionInput): Promise<LifecycleResult>;
+    /**
+     * Persists candidate evidence and atomically enters `interrupted(review_required)`.
+     * @param input Review submission and candidate evidence.
+     * @returns Structured interruption result or failure.
+     * @remarks Existing context is preserved and review attempts after rejection receive a fresh key.
+     */
+    submitReview(input: SubmitTaskReviewInput): Promise<LifecycleResult>;
+    /**
+     * Approves current completion evidence after revalidation and atomically completes the task.
+     * @param input Evidence-bound approval request.
+     * @returns Structured completion result or failure.
+     * @remarks Approval is valid only for the current interruption evidence and is status-CAS protected.
+     */
+    approveInterrupted(input: ApproveInterruptedTaskInput): Promise<LifecycleResult>;
+    /**
+     * Rejects current completion evidence and atomically resumes the task in progress.
+     * @param input Evidence-bound rejection request and reviewer note.
+     * @returns Structured resume result with repair warnings when post-CAS events fail.
+     * @remarks Rejection records a decision before any later identical submission can be approved.
+     */
+    rejectInterrupted(input: RejectInterruptedTaskInput): Promise<LifecycleResult>;
+    /**
+     * Repairs review decision and feedback events after rejection resumed the task.
+     *
+     * @param input Rejected evidence and deterministic feedback data.
+     * @returns Structured repair result with any remaining warnings.
+     * @remarks This path is valid only while the task remains in progress; it never changes task status.
+     */
+    repairReview(input: RejectInterruptedTaskInput): Promise<LifecycleResult>;
+    /**
+     * Repairs missing completion status, decision, or parent events for an identical terminal replay.
+     * @param input Canonical completion evidence to replay.
+     * @returns Structured repair result or failure.
+     * @remarks Repair never creates terminal events for non-completed tasks or incompatible evidence.
+     */
+    repairCompletion(input: AgentTaskCompletionInput): Promise<LifecycleResult>;
+    /**
+     * Updates a description while preserving its goal contract and auditing semantic belief changes.
+     * @param input Description, actor, and optional thread.
+     * @returns Structured update result or failure.
+     * @remarks Duplicate Objective or Acceptance Criteria headings are rejected rather than collapsed.
+     */
+    updateTaskDescriptionWithReconciliation(input: ReconcileTaskDescriptionInput): Promise<LifecycleResult>;
+    private prepareCompletion;
+    private beliefOwnerSnapshot;
+    private reconcileCompletedCas;
+    private reconcileSubmittedCas;
+    private reconcileReviewDecisionCas;
+    private loadParent;
+    private updatePreparedSnapshot;
+    private hasStaleAgentParent;
+    private validatePrepared;
+    private loadReviewEvidence;
+    private resumeEarlyStaleApproval;
+    private findEvidenceById;
+    private listAllWorkItems;
+    private isValidEvidence;
+    private reviewAttemptEventKey;
+    private writeCompletionEvents;
+    private writeReviewDecision;
+    private writeTransitionMarker;
+    private resumeEventKey;
+    private writeResumeEvent;
+    private transitionAgentTask;
+    private statusEventKey;
+    private writeStatusEvent;
+    private clearAuditMarker;
+    private writeReviewActivity;
+    private createEvent;
+    private success;
+}
+/**
+ * Creates the lifecycle service from injected stores or the default Store Lattice.
+ *
+ * @param deps Optional stores and clock; omitted dependencies resolve the current
+ * `default:task` and `default:taskWorkItem` registrations.
+ * @returns A task lifecycle service ready for adapter use.
+ */
+declare function createTaskLifecycleService(deps?: TaskLifecycleServiceDeps): TaskLifecycleService;
+
 declare const AGENT_TASK_EVENT = "agent:execute";
 
 /**
@@ -7766,7 +8105,11 @@ interface SchedulerMiddlewareOptions {
 }
 declare function createSchedulerMiddleware(options?: SchedulerMiddlewareOptions): AgentMiddleware;
 
-declare function createTaskMiddleware(): AgentMiddleware;
+/** Configuration consumed by the task middleware adapter. */
+interface TaskMiddlewareConfig {
+    reviewMode?: "disabled" | "hitl";
+}
+declare function createTaskMiddleware(options?: TaskMiddlewareConfig): AgentMiddleware;
 
 type ResolveAgentFn = (ref?: string, responseFormat?: Record<string, unknown>, stepType?: string) => Promise<AgentClient>;
 /**
@@ -7972,6 +8315,18 @@ interface ExportableEntity {
     _exportId: string;
     data: Record<string, unknown>;
 }
+/**
+ * A file bundled with an exported entity (e.g., skill SKILL.md, resources).
+ * Stored in the archive under `files/{entityType}/{entityId}/{path}`.
+ */
+interface ExportableFile {
+    /** The raw entity id this file belongs to (e.g., skill name). */
+    entityId: string;
+    /** Relative path within the entity's file tree, e.g. "SKILL.md" or "resources/scripts/x.py". */
+    path: string;
+    /** File content. */
+    content: Buffer;
+}
 /** Top-level export JSON format written to file. */
 interface ExportBundle {
     version: 1;
@@ -8023,6 +8378,12 @@ interface Resolution {
     action: ResolutionAction;
     newId?: string;
 }
+/** Resolution passed internally to registrations for conflict-free inserts. */
+interface ImportApplyResolution {
+    _exportId: string;
+    action: ResolutionAction | 'insert';
+    newId?: string;
+}
 /** Result of importing a single entity. */
 type ImportEntityStatus = 'created' | 'updated' | 'skipped' | 'failed';
 interface ImportEntityResult {
@@ -8044,6 +8405,15 @@ interface ExportJob {
     bundle: ExportBundle;
     createdAt: Date;
 }
+/**
+ * Runtime context for export/import operations.
+ * Sandbox-backed entity types (skills) need workspace/project to resolve the
+ * correct volume; DB-backed types ignore it.
+ */
+interface ExportContext {
+    workspaceId?: string;
+    projectId?: string;
+}
 /**
  * Definition for a single exportable entity type.
  * Plugins and built-in types register through this interface.
@@ -8055,22 +8425,36 @@ interface ExportableEntityDefinition {
     dependsOn: string[];
     cascadeParents: string[];
     /** List all entities of this type for the given tenant. */
-    listForExport(tenantId: string): Promise<ExportableEntity[]>;
+    listForExport(tenantId: string, context?: ExportContext): Promise<ExportableEntity[]>;
+    /**
+     * Optionally collect file content to bundle with this entity type.
+     * Used for file-backed entities (e.g., skills with SKILL.md + resources/).
+     * Returns files keyed by raw entity id → relative path → content.
+     */
+    listFilesForExport?(tenantId: string, entities: ExportableEntity[], context?: ExportContext): Promise<ExportableFile[]>;
     /**
      * Map of field name → referenced entityType. During export, raw IDs in these fields
      * are replaced with @type/exportId references. During import, IdRemapper reverses this.
      */
     referenceFields?: Record<string, string>;
+    /**
+     * Return entity IDs required by the selected entities, grouped by registered
+     * entity type. Export follows these references transitively and rejects
+     * missing entities or explicit selections that omit a required ID.
+     */
+    getReferencedEntityIds?(tenantId: string, entities: ExportableEntity[], context?: ExportContext): Promise<Record<string, string[]>>;
     /** Check for conflicts when importing into the target tenant. */
-    previewImport(tenantId: string, entities: ExportableEntity[]): Promise<ImportPreviewResult>;
+    previewImport(tenantId: string, entities: ExportableEntity[], context?: ExportContext): Promise<ImportPreviewResult>;
     /**
      * Apply a single entity import.
      * @param tenantId - Target tenant
      * @param entity - The entity data with references already remapped by the service
      * @param resolution - How to handle this entity (skip/overwrite/rename)
+     * @param files - Extracted file content for this entity (from archive `files/`), keyed by relative path
+     * @param context - Runtime context (workspace/project) for sandbox resolution
      * @returns The new ID created, or undefined if skipped
      */
-    applyImport(tenantId: string, entity: ExportableEntity, resolution: Resolution): Promise<{
+    applyImport(tenantId: string, entity: ExportableEntity, resolution: ImportApplyResolution, files?: Map<string, Buffer>, context?: ExportContext): Promise<{
         newId?: string;
     }>;
 }
@@ -8218,4 +8602,4 @@ declare class IdRemapper {
     remapSkillIds(graphDefinition: Record<string, unknown>, skillRemap: Record<string, string>): Record<string, unknown>;
 }
 
-export { AGENT_TASK_EVENT, type AddMessageParams, Agent, type AgentClient, type AgentExecutor, AgentInstanceManager, type AgentLattice, AgentLatticeManager, type AgentLifecycleEventName, AgentManager, type AgentStreamExecutor, type AgentThreadInterface, BUILTIN_PLUGINS, BUILTIN_SKILLS, type BackendFactory, type BackendProtocol, type BufferStats, type CacheEntry, type CalibrationProbe, type CaseRunResult, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, CollectionLatticeManager, type ColumnInfo, CompositeBackend, type ConflictItem, type ConnectAllChannelsOptions, ConnectionRegistry, ConsoleLoggerClient, type CreateSandboxProviderConfig, type CronFields, CustomMetricsClient, type CustomMiddlewareFactory, CustomMiddlewareRegistry, DEFAULT_CALIBRATION_PROBES, type DatabaseConfig, type DatabaseType, DaytonaInstance, DaytonaProvider, type DaytonaProviderConfig, DefaultScheduleClient, type DeleteResult, DependencyResolver, E2BInstance, E2BProvider, type E2BProviderConfig, EMPTY_CONTENT_WARNING, type EditResult, type EmbeddingsInfo, type EmbeddingsLatticeInterface, EmbeddingsLatticeManager, type EnsureMicrosandboxInput, type EvalRunService, type ExportBundle, type ExportJob, type ExportableEntity, type ExportableEntityDefinition, ExportableEntityRegistry, type ExportableTypeInfo, type FileData, type FileInfo, FileSystemSkillStore, type FileSystemSkillStoreOptions, FilesystemBackend, type FsEntry, type GrepMatch, type IMessageQueueStore, type IMetricsServerClient, type ISqlDatabase, IdRemapper, type ImportApplyResult, type ImportEntityResult, type ImportEntityStatus, type ImportPreviewResult, InMemoryA2AApiKeyStore, InMemoryAssistantStore, InMemoryBindingStore, InMemoryChannelInstallationStore, InMemoryChunkBuffer, InMemoryCollectionStore, InMemoryDatabaseConfigStore, InMemoryMailboxStore, InMemoryMenuStore, InMemoryTaskListStore, InMemoryTaskStore, InMemoryTenantStore, InMemoryThreadMessageQueueStore, InMemoryThreadStore, InMemoryUserStore, InMemoryUserTenantLinkStore, type InsertionItem, type JudgeVerdict, LINE_NUMBER_WIDTH, type LangGraphStateChecker, type LatticeAgentStepConfig, LatticeEval, type LatticeEvalBatchReport, type LatticeEvalCase, type LatticeEvalCaseType, type LatticeEvalCaseWithTemplate, type LatticeEvalConfig, type LatticeEvalLogEvent, type LatticeEvalLogLevel, LatticeEvalProject, type LatticeEvalProjectType, type LatticeEvalResult, type LatticeEvalRubric, LatticeEvalSuite, type LatticeEvalSuiteType, type LatticeEvalTemplate, LocalSandboxInstance, LocalSandboxProvider, type LocalSandboxProviderConfig, type LoggerLattice, LoggerLatticeManager, MAX_LINE_LENGTH, type MailboxMessage, type MailboxStore, type McpLatticeInterface, McpLatticeManager, type McpServerInfo, MemoryBackend, MemoryLatticeManager, MemoryQueueClient, MemoryScheduleStorage, type MessageCompletedEvent, type MessageFailedEvent, type MessageStartedEvent, MessageType, MetricsServerManager, MicrosandboxRemoteInstance, MicrosandboxRemoteProvider, type MicrosandboxRemoteProviderClient, type MicrosandboxRemoteProviderConfig, MicrosandboxServiceClient, type MicrosandboxServiceClientConfig, type MicrosandboxShellExecInput, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, MysqlDatabase, type OutputType, type PendingMessage, PersonalAssistantConfig, PinoLoggerClient, PluginRegistry, PostgresDatabase, type PreviewError, PrometheusClient, type QueryResult, type QueueLattice, QueueLatticeManager, QueueMode, type QueuePendingEvent, RemoteSandboxInstance, RemoteSandboxProvider, type RemoteSandboxProviderConfig, type Resolution, type ResolutionAction, type ResolveAgentFn, type ResolvedConfig, type RunSandboxConfig, type RuntimeModelConfig, type STTModelInfo, STTModelLattice, type STTModelLatticeInterface, STTModelLatticeManager, type SandboxFileInfo, type SandboxFileService, SandboxFilesystem, type SandboxInstance, type SandboxIsolationLevel, SandboxLatticeManager, type SandboxManagerProtocol, type SandboxProvider, type SandboxProviderFactory, type SandboxProviderType, type SandboxShellService, SandboxSkillStore, type SandboxSkillStoreOptions, type SandboxVolumeDefinition, type ScheduleLattice, ScheduleLatticeManager, type SchedulerMiddlewareOptions, SemanticMetricsClient, type SharePayload, SimpleMemoryVectorStore, type SkillLattice, SkillLatticeManager, type SkillMeta, type SkillResource, SqlDatabaseManager, type StateAndStore, StateBackend, StoreBackend, type StoreLattice, StoreLatticeManager, type StoreType, type StoreTypeMap, TOOL_RESULT_TOKEN_LIMIT, TRUNCATION_GUIDANCE, type TableInfo, type TableSchema, type TaskEvent, type TaskListStore, type TaskSpec, TaskStatus, type TaskUpdatable, TeamAgentGraphBuilder, type TeamConfig, type TeamMiddlewareOptions, type TeamTask, type TeammateSpec, type TeammateToolsOptions, type ThreadBuffer, type ThreadBufferConfig, type ThreadBusyEvent, type ThreadIdleEvent, type ThreadInfo, type ThreadQueueConfig, type ThreadState, ThreadStatus, type ThreadStatusChangedEvent, TokenCache, type ToolDefinition, type ToolLattice, ToolLatticeManager, type UnknownToolHandlerConfig, type VectorStoreLatticeInterface, VectorStoreLatticeManager, type VectorStoreProviderLattice, VectorStoreProviderManager, VolumeFilesystem, type VolumeFsClient, type WorkflowValidationError, type WriteResult, abortWorkflowRun, agentInstanceManager, agentLatticeManager, buildGrepResultsDict, buildInput, buildNamedVolumeName, buildSandboxMetadataEnv, buildSkillFile, buildStateAnnotation, buildTableName, checkEmptyContent, clearEncryptionKeyCache, clearEvalRunService, collectionLatticeManager, compileInternal, compileWorkflow, computeSandboxName, configureStores, connectAllChannels, createAgentNode, createAgentTeam, createExecuteSqlQueryTool, createFileData, createInfoSqlTool, createListMetricsDataSourcesTool, createListMetricsServersTool, createListTablesSqlTool, createMapNode, createModelSelectorMiddleware, createNodeHandler, createQueryCheckerSqlTool, createQueryMetricDefinitionTool, createQueryMetricsListTool, createQuerySemanticMetricDataTool, createQuerySqlTool, createQueryTableDefinitionTool, createQueryTablesListTool, createResourceAddress, createSandboxProvider, createSchedulerMiddleware, createSharePayload, createTaskMiddleware, createTeamMiddleware, createTeammateTools, createUnknownToolHandlerMiddleware, createWidgetMiddleware, decrypt, describeCronExpression, documentLearningPlugin, documentParserPlugin, embeddingsLatticeManager, encrypt, ensureBuiltinAgentsForTenant, evaluateLatticeCaseWithLogs, eventBus, eventBus as eventBusDefault, extractFetcherError, extractOutput, fileDataToString, formatContentWithLineNumbers, formatGrepMatches, formatGrepResults, formatReadResponse, generateToken, getAgentClient, getAgentConfig, getAllAgentConfigs, getAllBuiltInSkillMetas, getAllToolDefinitions, getBindingRegistry, getBuiltInSkillContent, getBuiltInSkillMeta, getBuiltInSkillNames, getCheckpointSaver, getChunkBuffer, getCollectionEntryCount, getEmbeddingsClient, getEmbeddingsLattice, getEncryptionKey, getEvalRunService, getLoggerLattice, getMenuRegistry, getModelLattice, getNextCronTime, getOrCreateCollectionVectorStore, getQueueLattice, getSTTClient, getSTTClientWithTenant, getSTTModelLattice, getSandBoxManager, getScheduleLattice, getStoreLattice, getToolClient, getToolDefinition, getToolLattice, getVectorStoreClient, getVectorStoreLattice, getVectorStoreProvider, getWorkflowSignal, globSearchFiles, grepMatchesFromFiles, grepSearchFiles, hasChunkBuffer, invokeWithRetry, isBuiltInSkill, isUsingDefaultKey, isValidCronExpression, isValidSandboxName, isValidSkillName, listCollectionEntries, listSandboxProviderTypes, loggerLatticeManager, mcpManager, metricsServerManager, modelLatticeManager, normalizeSandboxName, parallelLimit, parseCronExpression, parseJudgeVerdict, parseSkillFrontmatter, parseYaml, performStringReplacement, queueLatticeManager, registerAgentLattice, registerAgentLatticeWithTenant, registerAgentLattices, registerBuiltinSkill, registerCheckpointSaver, registerChunkBuffer, registerEmbeddingsLattice, registerExistingTool, registerLoggerLattice, registerModelLattice, registerQueueLattice, registerSTTModelLattice, registerSandboxProviderType, registerScheduleLattice, registerStoreLattice, registerTeammateAgent, registerToolLattice, registerVectorStoreLattice, registerVectorStoreProvider, registerWorkflowRun, removeCollectionVectorStore, renderTemplate, resolveJudgeModelKey, resolvePath, sandboxLatticeManager, sanitizeToolCallId, scheduleLatticeManager, serializePluginMeta, setBindingRegistry, setEvalRunService, setMenuRegistry, skillLatticeManager, sqlDatabaseManager, storeLatticeManager, sttModelLatticeManager, toJsonSchema, toSafeStateExpr, toolLatticeManager, truncateIfTooLong, unregisterTeammateAgent, unregisterWorkflowRun, updateFileData, validateAgentInput, validateDSL, validateEncryptionKey, validatePath, validateSkillName, validateToolInput, vectorStoreLatticeManager, vectorStoreProviderManager };
+export { AGENT_TASK_EVENT, type AddMessageParams, Agent, type AgentClient, type AgentExecutor, AgentInstanceManager, type AgentLattice, AgentLatticeManager, type AgentLifecycleEventName, AgentManager, type AgentStreamExecutor, type AgentTaskCompletionInput, type AgentThreadInterface, type ApproveInterruptedTaskInput, BUILTIN_PLUGINS, BUILTIN_SKILLS, type BackendFactory, type BackendProtocol, type BufferStats, type CacheEntry, type CalibrationProbe, type CaseRunResult, type Chunk, ChunkBuffer, ChunkBufferLatticeManager, CollectionLatticeManager, type ColumnInfo, CompositeBackend, type ConflictItem, type ConnectAllChannelsOptions, ConnectionRegistry, ConsoleLoggerClient, type CreateSandboxProviderConfig, type CronFields, CustomMetricsClient, type CustomMiddlewareFactory, CustomMiddlewareRegistry, DEFAULT_CALIBRATION_PROBES, type DatabaseConfig, type DatabaseType, DaytonaInstance, DaytonaProvider, type DaytonaProviderConfig, DefaultScheduleClient, type DeleteResult, DependencyResolver, E2BInstance, E2BProvider, type E2BProviderConfig, EMPTY_CONTENT_WARNING, type EditResult, type EmbeddingsInfo, type EmbeddingsLatticeInterface, EmbeddingsLatticeManager, type EnsureMicrosandboxInput, type EvalRunService, type ExportBundle, type ExportContext, type ExportJob, type ExportableEntity, type ExportableEntityDefinition, ExportableEntityRegistry, type ExportableFile, type ExportableTypeInfo, type FileData, type FileInfo, FileSystemSkillStore, type FileSystemSkillStoreOptions, FilesystemBackend, type FsEntry, type GrepMatch, type IMessageQueueStore, type IMetricsServerClient, type ISqlDatabase, IdRemapper, type ImportApplyResolution, type ImportApplyResult, type ImportEntityResult, type ImportEntityStatus, type ImportPreviewResult, InMemoryA2AApiKeyStore, InMemoryAssistantStore, InMemoryBindingStore, InMemoryChannelInstallationStore, InMemoryChunkBuffer, InMemoryCollectionStore, InMemoryDatabaseConfigStore, InMemoryMailboxStore, InMemoryMenuStore, InMemoryTaskListStore, InMemoryTaskStore, InMemoryTenantStore, InMemoryThreadMessageQueueStore, InMemoryThreadStore, InMemoryUserStore, InMemoryUserTenantLinkStore, type InsertionItem, type JudgeVerdict, LINE_NUMBER_WIDTH, type LangGraphStateChecker, type LatticeAgentStepConfig, LatticeEval, type LatticeEvalBatchReport, type LatticeEvalCase, type LatticeEvalCaseType, type LatticeEvalCaseWithTemplate, type LatticeEvalConfig, type LatticeEvalLogEvent, type LatticeEvalLogLevel, LatticeEvalProject, type LatticeEvalProjectType, type LatticeEvalResult, type LatticeEvalRubric, LatticeEvalSuite, type LatticeEvalSuiteType, type LatticeEvalTemplate, type LifecycleResult, type LifecycleWarning, LocalSandboxInstance, LocalSandboxProvider, type LocalSandboxProviderConfig, type LoggerLattice, LoggerLatticeManager, MAX_LINE_LENGTH, type MailboxMessage, type MailboxStore, type McpLatticeInterface, McpLatticeManager, type McpServerInfo, MemoryBackend, MemoryLatticeManager, MemoryQueueClient, MemoryScheduleStorage, type MessageCompletedEvent, type MessageFailedEvent, type MessageStartedEvent, MessageType, MetricsServerManager, MicrosandboxRemoteInstance, MicrosandboxRemoteProvider, type MicrosandboxRemoteProviderClient, type MicrosandboxRemoteProviderConfig, MicrosandboxServiceClient, type MicrosandboxServiceClientConfig, type MicrosandboxShellExecInput, type ModelConfig, type ModelLatticeInterface, ModelLatticeManager, MysqlDatabase, type OutputType, type PendingMessage, PersonalAssistantConfig, PinoLoggerClient, PluginRegistry, PostgresDatabase, type PreviewError, PrometheusClient, type QueryResult, type QueueLattice, QueueLatticeManager, QueueMode, type QueuePendingEvent, type ReconcileTaskDescriptionInput, type RejectInterruptedTaskInput, RemoteSandboxInstance, RemoteSandboxProvider, type RemoteSandboxProviderConfig, type Resolution, type ResolutionAction, type ResolveAgentFn, type ResolvedConfig, type RunSandboxConfig, type RuntimeModelConfig, type STTModelInfo, STTModelLattice, type STTModelLatticeInterface, STTModelLatticeManager, type SandboxFileInfo, type SandboxFileService, SandboxFilesystem, type SandboxInstance, type SandboxIsolationLevel, SandboxLatticeManager, type SandboxManagerProtocol, type SandboxProvider, type SandboxProviderFactory, type SandboxProviderType, type SandboxShellService, SandboxSkillStore, type SandboxSkillStoreOptions, type SandboxVolumeDefinition, type ScheduleLattice, ScheduleLatticeManager, type SchedulerMiddlewareOptions, SemanticMetricsClient, type SharePayload, SimpleMemoryVectorStore, type SkillLattice, SkillLatticeManager, type SkillMeta, type SkillResource, SqlDatabaseManager, type StateAndStore, StateBackend, StoreBackend, type StoreLattice, StoreLatticeManager, type StoreType, type StoreTypeMap, type SubmitTaskReviewInput, TOOL_RESULT_TOKEN_LIMIT, TRUNCATION_GUIDANCE, type TableInfo, type TableSchema, type TaskEvent, TaskLifecycleService, type TaskLifecycleServiceDeps, type TaskListStore, type TaskSpec, TaskStatus, type TaskUpdatable, TeamAgentGraphBuilder, type TeamConfig, type TeamMiddlewareOptions, type TeamTask, type TeammateSpec, type TeammateToolsOptions, type ThreadBuffer, type ThreadBufferConfig, type ThreadBusyEvent, type ThreadIdleEvent, type ThreadInfo, type ThreadQueueConfig, type ThreadState, ThreadStatus, type ThreadStatusChangedEvent, TokenCache, type ToolDefinition, type ToolLattice, ToolLatticeManager, type UnknownToolHandlerConfig, type VectorStoreLatticeInterface, VectorStoreLatticeManager, type VectorStoreProviderLattice, VectorStoreProviderManager, VolumeFilesystem, type VolumeFsClient, type WorkflowValidationError, type WriteResult, abortWorkflowRun, agentInstanceManager, agentLatticeManager, buildGrepResultsDict, buildInput, buildNamedVolumeName, buildSandboxMetadataEnv, buildSkillFile, buildStateAnnotation, buildTableName, checkEmptyContent, clearEncryptionKeyCache, clearEvalRunService, collectionLatticeManager, compileInternal, compileWorkflow, computeSandboxName, configureStores, connectAllChannels, createAgentNode, createAgentTeam, createExecuteSqlQueryTool, createFileData, createInfoSqlTool, createListMetricsDataSourcesTool, createListMetricsServersTool, createListTablesSqlTool, createMapNode, createModelSelectorMiddleware, createNodeHandler, createQueryCheckerSqlTool, createQueryMetricDefinitionTool, createQueryMetricsListTool, createQuerySemanticMetricDataTool, createQuerySqlTool, createQueryTableDefinitionTool, createQueryTablesListTool, createResourceAddress, createSandboxProvider, createSchedulerMiddleware, createSharePayload, createTaskLifecycleService, createTaskMiddleware, createTeamMiddleware, createTeammateTools, createUnknownToolHandlerMiddleware, createWidgetMiddleware, decrypt, describeCronExpression, documentLearningPlugin, documentParserPlugin, embeddingsLatticeManager, encrypt, ensureBuiltinAgentsForTenant, evaluateLatticeCaseWithLogs, eventBus, eventBus as eventBusDefault, extractFetcherError, extractOutput, fileDataToString, formatContentWithLineNumbers, formatGrepMatches, formatGrepResults, formatReadResponse, generateToken, getAgentClient, getAgentConfig, getAllAgentConfigs, getAllBuiltInSkillMetas, getAllToolDefinitions, getBindingRegistry, getBuiltInSkillContent, getBuiltInSkillMeta, getBuiltInSkillNames, getCheckpointSaver, getChunkBuffer, getCollectionEntryCount, getEmbeddingsClient, getEmbeddingsLattice, getEncryptionKey, getEvalRunService, getLoggerLattice, getMenuRegistry, getModelLattice, getNextCronTime, getOrCreateCollectionVectorStore, getQueueLattice, getSTTClient, getSTTClientWithTenant, getSTTModelLattice, getSandBoxManager, getScheduleLattice, getStoreLattice, getToolClient, getToolDefinition, getToolLattice, getVectorStoreClient, getVectorStoreLattice, getVectorStoreProvider, getWorkflowSignal, globSearchFiles, grepMatchesFromFiles, grepSearchFiles, hasChunkBuffer, invokeWithRetry, isBuiltInSkill, isUsingDefaultKey, isValidCronExpression, isValidSandboxName, isValidSkillName, listCollectionEntries, listSandboxProviderTypes, loggerLatticeManager, mcpManager, metricsServerManager, modelLatticeManager, normalizeSandboxName, parallelLimit, parseCronExpression, parseJudgeVerdict, parseSkillFrontmatter, parseYaml, performStringReplacement, queueLatticeManager, registerAgentLattice, registerAgentLatticeWithTenant, registerAgentLattices, registerBuiltinSkill, registerCheckpointSaver, registerChunkBuffer, registerEmbeddingsLattice, registerExistingTool, registerLoggerLattice, registerModelLattice, registerQueueLattice, registerSTTModelLattice, registerSandboxProviderType, registerScheduleLattice, registerStoreLattice, registerTeammateAgent, registerToolLattice, registerVectorStoreLattice, registerVectorStoreProvider, registerWorkflowRun, removeCollectionVectorStore, renderTemplate, resolveJudgeModelKey, resolvePath, sandboxLatticeManager, sanitizeToolCallId, scheduleLatticeManager, serializePluginMeta, setBindingRegistry, setEvalRunService, setMenuRegistry, skillLatticeManager, sqlDatabaseManager, storeLatticeManager, sttModelLatticeManager, toJsonSchema, toSafeStateExpr, toolLatticeManager, truncateIfTooLong, unregisterTeammateAgent, unregisterWorkflowRun, updateFileData, validateAgentInput, validateDSL, validateEncryptionKey, validatePath, validateSkillName, validateToolInput, vectorStoreLatticeManager, vectorStoreProviderManager };