@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/plugin-contract/manifest.d.ts

@@ -12,6 +12,7 @@ export type AgentPluginOperationManifest = Readonly<{
     payload?: ToolNormalInvocationPayload;
 }>;
 export type AgentPluginCapabilityManifest = Readonly<{
+    requiredPermissionMode?: import("../capabilities/tool-permission-mode.js").ToolRequiredPermissionMode;
     description: string;
     routingCapability: ToolRoutingCapability;
     controlsRefinement?: "mechanical_when_complete";

package/dist/src/plugin-sdk/computer-access.d.ts

@@ -0,0 +1,13 @@
+/** Shared computer access. Import this subpath only when your plugin uses the host. */
+export { executeHostOperation, readHostStatus, } from "../computer-access/companion/broker-client.js";
+export { HOST_OPERATIONS, type HostIdentity, type HostOperation, type HostStatus, isHostIdentifier, isHostIdentity, isHostOperation, } from "../computer-access/companion/protocol.js";
+export { computerFields, computerInputError, computerRecord, computerText, readNativeComputerAction, readPhysicalRectangle, } from "../computer-access/computer/action-input.js";
+export { createCompanionComputerBackend } from "../computer-access/computer/companion-backend.js";
+export { withDesktopQueue } from "../computer-access/computer/desktop-action-queue.js";
+export { createNativeComputerBackend } from "../computer-access/computer/native-backend.js";
+export { type NativeComputerAction, type NativeComputerBackend, type NativeComputerObservation, type NativeComputerResult, type PhysicalPoint, type PhysicalRectangle, } from "../computer-access/computer/native-protocol.js";
+export { COMPUTER_CAPABILITY, readNativeComputerResult, } from "../computer-access/computer/native-validation.js";
+export { SystemOperationError, type SystemTarget, type SystemTargetId, } from "../computer-access/contracts.js";
+export { createSystemHandlers } from "../computer-access/handlers.js";
+export { type SystemTargetObservation, observeSystemTargets, } from "../computer-access/target-observation.js";
+export type { ComputerAccessConnection, CompanionTarget, } from "../computer-access/client.js";

package/dist/src/plugin-sdk/computer-access.js

@@ -0,0 +1,11 @@
+/** Shared computer access. Import this subpath only when your plugin uses the host. */
+export { executeHostOperation, readHostStatus, } from "../computer-access/companion/broker-client.js";
+export { HOST_OPERATIONS, isHostIdentifier, isHostIdentity, isHostOperation, } from "../computer-access/companion/protocol.js";
+export { computerFields, computerInputError, computerRecord, computerText, readNativeComputerAction, readPhysicalRectangle, } from "../computer-access/computer/action-input.js";
+export { createCompanionComputerBackend } from "../computer-access/computer/companion-backend.js";
+export { withDesktopQueue } from "../computer-access/computer/desktop-action-queue.js";
+export { createNativeComputerBackend } from "../computer-access/computer/native-backend.js";
+export { COMPUTER_CAPABILITY, readNativeComputerResult, } from "../computer-access/computer/native-validation.js";
+export { SystemOperationError, } from "../computer-access/contracts.js";
+export { createSystemHandlers } from "../computer-access/handlers.js";
+export { observeSystemTargets, } from "../computer-access/target-observation.js";

package/dist/src/plugin-sdk/index.d.ts

@@ -4,6 +4,8 @@ export * from "./parameters.js";
 export * from "./paths.js";
 export * from "./plugin.js";
 export * from "./results.js";
+export * from "../capabilities/tool-media.js";
 export * from "./tool-availability-brief.js";
 export * from "./tool-availability-overview.js";
 export * from "../plugin-contract/index.js";
+export type { ToolRequestWork, ToolRequestState, ToolRequestPreparationContext, } from "../capabilities/tool-request-resources.js";

package/dist/src/plugin-sdk/index.js

@@ -4,6 +4,7 @@ export * from "./parameters.js";
 export * from "./paths.js";
 export * from "./plugin.js";
 export * from "./results.js";
+export * from "../capabilities/tool-media.js";
 export * from "./tool-availability-brief.js";
 export * from "./tool-availability-overview.js";
 export * from "../plugin-contract/index.js";

package/dist/src/plugin-sdk/results.d.ts

@@ -1,5 +1,5 @@
 import type { ToolImplementationOutput } from "../plugin-contract/entrypoint.js";
-type ResultCommon = Pick<ToolImplementationOutput, "actions" | "data" | "exitCode" | "progress" | "stderr" | "stdout">;
+type ResultCommon = Pick<ToolImplementationOutput, "actions" | "data" | "exitCode" | "progress" | "stderr" | "stdout" | "media">;
 export declare const PLUGIN_RESULT_SERIALIZED_MAX_BYTES: number;
 export declare function enforcePluginResultByteBudget(result: ToolImplementationOutput): ToolImplementationOutput;
 export type SuccessResultInput = ResultCommon & Readonly<{

package/dist/src/plugin-sdk/results.js

@@ -30,6 +30,7 @@ export function enforcePluginResultByteBudget(result) {
 export function successResult(input) {
     return enforcePluginResultByteBudget({
         ok: true,
+        ...(input.media !== undefined ? { media: input.media } : {}),
         output: input.output,
         producedNewInformation: input.producedNewInformation ?? true,
         ...(input.progress !== undefined ? { progress: input.progress } : {}),
@@ -43,6 +44,7 @@ export function successResult(input) {
 export function failureResult(input) {
     return enforcePluginResultByteBudget({
         ok: false,
+        ...(input.media !== undefined ? { media: input.media } : {}),
         output: input.output ?? input.message,
         producedNewInformation: false,
         ...(input.progress !== undefined ? { progress: input.progress } : {}),

package/dist/src/runtime/adapters/co-worker-resources.d.ts

@@ -0,0 +1,13 @@
+import type { RuntimeConfig, ModelGatewayClient, SessionStore } from "../ports.js";
+import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
+import type { LearningBackgroundContext, LearningBackgroundDependencies } from "../passive-learning/background-dependencies.js";
+/** The environment shares one budget; foreground chat keeps its original clients. */
+export declare function createCoWorkerResourceDependencies(options: {
+    config: RuntimeConfig;
+    models: ModelGatewayClient;
+    memory: LongTermMemoryService;
+    directory: string;
+    ownerId: string;
+    context: LearningBackgroundContext;
+    sessions?: SessionStore;
+}): LearningBackgroundDependencies;

package/dist/src/runtime/adapters/co-worker-resources.js

@@ -0,0 +1,74 @@
+import { createRuntimePassiveLearningModel } from "../passive-learning/model.js";
+import { CoWorkerResourceBudget } from "../passive-learning/resources/budget.js";
+import { DEFAULT_CO_WORKER_RESOURCE_LIMITS } from "../passive-learning/resources/contracts.js";
+import { createCoWorkerResourceGateway } from "../passive-learning/resources/gateway.js";
+import { createRuntimeProactiveModel } from "../passive-learning/proactive/model.js";
+import { CoWorkerProactiveAgent } from "../passive-learning/proactive/agent.js";
+import { isWithinAnalysisWindow } from "../passive-learning/analysis-schedule.js";
+import { ScheduledLearningReassessment } from "../passive-learning/scheduled-reassessment.js";
+/** The environment shares one budget; foreground chat keeps its original clients. */
+export function createCoWorkerResourceDependencies(options) {
+    const { context } = options;
+    const budget = new CoWorkerResourceBudget({ directory: options.directory, limits: () => {
+            const preferences = context.preferences();
+            return { ...(preferences.resourceLimits ?? DEFAULT_CO_WORKER_RESOURCE_LIMITS), maxConcurrentCalls: preferences.maxConcurrentBatches ?? 1 };
+        } });
+    const original = createRuntimePassiveLearningModel(options);
+    const processingGateway = createCoWorkerResourceGateway({
+        gateway: options.models, budget, activity: "processing", assertActivityAllowed: context.assertProcessingAllowed,
+        supportsParallel: () => original.supportsParallelBatches?.(context.preferences().modelProfileId ?? "") ?? false,
+    });
+    async function assertMemoryAvailable(signal) {
+        signal.throwIfAborted();
+        context.assertProcessingAllowed();
+        const status = await options.memory.status();
+        signal.throwIfAborted();
+        context.assertProcessingAllowed();
+        if (!status.enabled || !status.available)
+            throw new Error("learning_memory_unavailable");
+    }
+    const gateway = {
+        ...processingGateway,
+        async invoke(input) { await assertMemoryAvailable(input.abortSignal); return processingGateway.invoke(input); },
+        async invokeRaw(input) { await assertMemoryAvailable(input.abortSignal); return processingGateway.invokeRaw(input); },
+        ...(processingGateway.embed ? { embed: async (input) => {
+                await assertMemoryAvailable(input.abortSignal);
+                return processingGateway.embed(input);
+            } } : {}),
+    };
+    const beforeEmbedding = async ({ signal, characters }) => {
+        await assertMemoryAvailable(signal);
+        return budget.reserve({ kind: "embedding", activity: "processing", signal, embeddingCharacters: characters,
+            supportsParallel: false, assertActivityAllowed: context.assertProcessingAllowed });
+    };
+    const learning = options.memory.learning;
+    const memory = {
+        ...options.memory,
+        ...(learning ? { learning: {
+                ...learning,
+                prepare: (input) => learning.prepare({ ...input, beforeEmbedding }),
+                apply: (input) => learning.apply({ ...input, beforeEmbedding }),
+            } } : {}),
+    };
+    const proactiveGateway = createCoWorkerResourceGateway({
+        gateway: options.models, budget, activity: "proactive",
+        assertActivityAllowed: () => {
+            if (!context.isStarted() || context.isInteractiveBusy() || !context.preferences().proactiveEnabled)
+                throw new Error("proactive_disabled");
+            if (!isWithinAnalysisWindow(Date.now(), context.preferences().proactiveWindow))
+                throw new Error("proactive_outside_window");
+        },
+        supportsParallel: () => original.supportsParallelBatches?.(context.preferences().proactiveModelProfileId ?? context.preferences().modelProfileId ?? "") ?? false,
+    });
+    const proactive = learning && options.sessions ? new CoWorkerProactiveAgent({ directory: options.directory,
+        context, memory: learning, sessions: options.sessions, budget,
+        model: createRuntimeProactiveModel({ config: options.config, models: proactiveGateway }) }) : undefined;
+    const model = createRuntimePassiveLearningModel({ ...options, models: gateway });
+    const reassessment = memory.learning ? new ScheduledLearningReassessment({ directory: options.directory,
+        environmentId: options.ownerId, context, memory: memory.learning, model,
+        resourceUsage: () => budget.status(), changed: () => { proactive?.knowledgeChanged(); context.changed(); } }) : undefined;
+    return { model, memory,
+        ...(proactive ? { proactive } : {}),
+        ...(reassessment ? { reassessment } : {}),
+        resourceUsage: () => budget.status() };
+}

package/dist/src/runtime/adapters/config-file-transaction.d.ts

@@ -0,0 +1,46 @@
+/** Configuration activation can hold this lock throughout shutdown and restart.
+ * Cooperating writers wait for release; dead owners remain reclaimable.
+ */
+export declare const CONFIG_FILE_LOCK_OPTIONS: Readonly<{
+    waitMs: number;
+}>;
+type JsonConfig = Record<string, unknown>;
+export type ConfigFileReadOptions = Readonly<{
+    allowMalformedJson?: boolean;
+}>;
+export type InvalidConfigJson = Readonly<{
+    raw: string;
+    message: string;
+}>;
+export type ConfigFileSnapshot = Readonly<{
+    config: JsonConfig;
+    invalidJson?: InvalidConfigJson;
+    exists: boolean;
+    revision: string;
+}>;
+export type ConfigFileExpectation = Readonly<{
+    expectedConfig?: JsonConfig;
+    expectedRevision?: string;
+}>;
+export type ConfigFileCommit = Readonly<{
+    revision: string;
+    backupPath?: string;
+}>;
+export type ConfigFileTransaction = Readonly<{
+    path: string;
+    snapshot: ConfigFileSnapshot;
+    write(config: JsonConfig, expectation?: ConfigFileExpectation): Promise<ConfigFileCommit>;
+}>;
+export declare class ConfigFileConflictError extends Error {
+    readonly code = "config_changed";
+    constructor();
+}
+/** Existing targets and missing children of symlinked directories share one lock. */
+export declare function canonicalConfigFilePath(path: string): Promise<string>;
+export declare function readConfigFileSnapshot(path: string, options?: ConfigFileReadOptions): Promise<ConfigFileSnapshot>;
+/** All cooperating config writers hold this lock from read through commit.
+ * Revision checks also reject completed external edits; advisory locks cannot
+ * exclude an external editor that writes between the final check and rename.
+ */
+export declare function withConfigFileTransaction<T>(path: string, operation: (transaction: ConfigFileTransaction) => Promise<T>, options?: ConfigFileReadOptions): Promise<T>;
+export {};

package/dist/src/runtime/adapters/config-file-transaction.js

@@ -0,0 +1,165 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, realpath, rename, rm, stat, writeFile, } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { isRecord } from "../config/utils.js";
+import { withFileLock } from "./long-term-memory/file-lock.js";
+/** Configuration activation can hold this lock throughout shutdown and restart.
+ * Cooperating writers wait for release; dead owners remain reclaimable.
+ */
+export const CONFIG_FILE_LOCK_OPTIONS = Object.freeze({
+    waitMs: Number.POSITIVE_INFINITY,
+});
+export class ConfigFileConflictError extends Error {
+    code = "config_changed";
+    constructor() {
+        super("Configuration changed since it was loaded. Refresh Configuration before saving again.");
+    }
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+/** Existing targets and missing children of symlinked directories share one lock. */
+export async function canonicalConfigFilePath(path) {
+    const absolute = resolve(path);
+    try {
+        return await realpath(absolute);
+    }
+    catch (error) {
+        if (!isMissingFile(error))
+            throw error;
+        const parent = dirname(absolute);
+        if (parent === absolute)
+            throw error;
+        return join(await canonicalConfigFilePath(parent), basename(absolute));
+    }
+}
+function configRevision(path, raw) {
+    const hash = createHash("sha256").update(path).update("\0");
+    if (raw === undefined)
+        return hash.update("missing").digest("hex");
+    return hash.update("present:").update(raw).digest("hex");
+}
+function parseSnapshotConfig(raw, options) {
+    if (raw === undefined)
+        return { config: {} };
+    const text = raw.toString("utf8");
+    try {
+        const config = JSON.parse(text);
+        if (!isRecord(config))
+            throw new Error("Configuration must contain a JSON object.");
+        return { config };
+    }
+    catch (error) {
+        if (!options.allowMalformedJson)
+            throw error;
+        return {
+            config: {},
+            invalidJson: {
+                raw: text,
+                message: "This file is not a valid JSON object. Correct its Raw JSON and save the file to repair it.",
+            },
+        };
+    }
+}
+async function requireRegularConfigFile(path) {
+    if ((await stat(path)).isFile())
+        return;
+    throw new Error("Configuration path must be a regular file.");
+}
+async function readSnapshot(path, options = {}) {
+    let raw;
+    try {
+        // Inspect before opening: special entries such as FIFOs can block a read.
+        await requireRegularConfigFile(path);
+        raw = await readFile(path);
+    }
+    catch (error) {
+        if (!isMissingFile(error))
+            throw error;
+    }
+    return {
+        ...parseSnapshotConfig(raw, options),
+        exists: raw !== undefined,
+        revision: configRevision(path, raw),
+        raw,
+    };
+}
+export async function readConfigFileSnapshot(path, options = {}) {
+    const { raw: _raw, ...snapshot } = await readSnapshot(await canonicalConfigFilePath(path), options);
+    return snapshot;
+}
+function requireExpectedSnapshot(snapshot, expectation) {
+    if (snapshot.invalidJson && expectation.expectedRevision === undefined)
+        throw new ConfigFileConflictError();
+    if (expectation.expectedRevision !== undefined &&
+        expectation.expectedRevision !== snapshot.revision)
+        throw new ConfigFileConflictError();
+    if (expectation.expectedConfig !== undefined &&
+        !isDeepStrictEqual(expectation.expectedConfig, snapshot.config))
+        throw new ConfigFileConflictError();
+}
+async function requireUnchangedFile(path, revision, options) {
+    if ((await readSnapshot(path, options)).revision !== revision)
+        throw new ConfigFileConflictError();
+}
+/** All cooperating config writers hold this lock from read through commit.
+ * Revision checks also reject completed external edits; advisory locks cannot
+ * exclude an external editor that writes between the final check and rename.
+ */
+export async function withConfigFileTransaction(path, operation, options = {}) {
+    const canonicalPath = await canonicalConfigFilePath(path);
+    await mkdir(dirname(canonicalPath), { recursive: true });
+    return withFileLock(`${canonicalPath}.config.lock`, async () => {
+        let current = await readSnapshot(canonicalPath, options);
+        return operation({
+            path: canonicalPath,
+            get snapshot() {
+                return current;
+            },
+            async write(config, expectation = {}) {
+                requireExpectedSnapshot(current, expectation);
+                await requireUnchangedFile(canonicalPath, current.revision, options);
+                const token = randomUUID();
+                const temporaryPath = `${canonicalPath}.${token}.tmp`;
+                const backupPath = current.exists
+                    ? `${canonicalPath}.${new Date().toISOString().replace(/[:.]/gu, "-")}.${token}.bak`
+                    : undefined;
+                const mode = current.exists
+                    ? (await stat(canonicalPath)).mode & 0o777
+                    : 0o600;
+                const raw = Buffer.from(`${JSON.stringify(config, null, 2)}\n`, "utf8");
+                try {
+                    if (backupPath)
+                        await writeFile(backupPath, current.raw, {
+                            encoding: "utf8",
+                            mode,
+                            flag: "wx",
+                        });
+                    await writeFile(temporaryPath, raw, {
+                        encoding: "utf8",
+                        mode,
+                        flag: "wx",
+                    });
+                    await chmod(temporaryPath, mode);
+                    await requireUnchangedFile(canonicalPath, current.revision, options);
+                    await rename(temporaryPath, canonicalPath);
+                }
+                catch (error) {
+                    await rm(temporaryPath, { force: true }).catch(() => undefined);
+                    throw error;
+                }
+                current = {
+                    config,
+                    exists: true,
+                    revision: configRevision(canonicalPath, raw),
+                    raw,
+                };
+                return {
+                    revision: current.revision,
+                    ...(backupPath ? { backupPath } : {}),
+                };
+            },
+        });
+    }, CONFIG_FILE_LOCK_OPTIONS);
+}

package/dist/src/runtime/adapters/configured-skill-provider.js

@@ -1,5 +1,5 @@
 import { createSkillsContextProvider, } from "../context/skills-context.js";
-import { loadBundledRuntimePlugins, loadConfiguredRuntimePlugins, } from "../plugins/loader.js";
+import { loadRuntimeCapabilityPlugins } from "../plugins/runtime-capability-plugins.js";
 function unique(values) {
     return [...new Set(values.filter((value) => value.trim().length > 0))];
 }
@@ -46,14 +46,14 @@ export function createRuntimePluginSkillProvider(options) {
 /** Loads the config-selected plugin catalog and projects only its skills. */
 export function createConfiguredSkillProvider(options) {
     return createProviderFromPlugins({
-        plugins: loadConfiguredRuntimePlugins(options.config),
+        plugins: loadRuntimeCapabilityPlugins(options.config),
         listToolDefinitions: options.listToolDefinitions,
     });
 }
 /** Uses the same bundled plugin manifests as the unconfigured tool registry. */
 export function createBundledPluginSkillProvider(options = {}) {
     return createProviderFromPlugins({
-        plugins: loadBundledRuntimePlugins(),
+        plugins: loadRuntimeCapabilityPlugins(),
         listToolDefinitions: options.listToolDefinitions,
     });
 }

package/dist/src/runtime/adapters/default-session-adapters.d.ts

@@ -1,3 +1,3 @@
 import type { ConversationContextProvider, SessionStore } from "../ports.js";
-export declare const defaultRuntimeSessionStore: Pick<SessionStore, "appendMessage" | "appendContextEntry" | "appendRequestEvent" | "compareAndSwapSessionMemoryCheckpoint" | "getAllSessions" | "getOrCreateSession" | "startRequestStream" | "upsertArtifactPaths" | "updateSessionRuntimeMode" | "updateSessionTitle">;
+export declare const defaultRuntimeSessionStore: Pick<SessionStore, "appendMessage" | "requestLifecycle" | "appendContextEntry" | "appendRequestEvent" | "compareAndSwapSessionMemoryCheckpoint" | "getAllSessions" | "getOrCreateSession" | "startRequestStream" | "upsertArtifactPaths" | "updateSessionRuntimeMode" | "updateSessionTitle">;
 export declare const defaultRuntimeConversationContextProvider: Pick<ConversationContextProvider, "buildContextBuckets">;

package/dist/src/runtime/adapters/file-session-store.js

@@ -2,6 +2,8 @@ import { SessionService } from "../../sessions/session-service.js";
 export function createFileSessionStore(options = {}) {
     const service = new SessionService(options);
     return {
+        requestLifecycle: service.requestLifecycle,
+        createAssistantConversation: service.createAssistantConversation.bind(service),
         getOrCreateSession: service.getOrCreateSession.bind(service),
         getAllSessions: service.getAllSessions.bind(service),
         listSessions: service.listSessions.bind(service),

package/dist/src/runtime/adapters/in-memory-session-store.js

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+import { assertSessionProjectUnchanged, copySessionProject, } from "../../sessions/project-binding.js";
 import { assertValidSessionArtifactPathInputs, upsertSessionArtifactPaths, } from "../../sessions/artifact-paths.js";
 import { clientVisibleMessages, compactRequestEvents, filterMessagesAfter, getRequestFinalState, getSessionRequest, isSameMessageId, normalizeAfterSeq, normalizeCursor, normalizeLimit, normalizeSessionTitle, toClientReplayEvent, toEpochMs, toSessionListItem, toSnapshotMessage, toSnapshotRequest, } from "../../sessions/record/projection.js";
 import { assertValidRequestId, assertValidSessionId, createContextEntryId, defaultCreateMessageId, pruneSupersededContextEntries, } from "../../sessions/record/rules.js";
@@ -40,15 +42,19 @@ class InMemorySessionStore {
             this.sessions.set(session.id, cloneSession(session));
         }
     }
-    async getOrCreateSession(sessionId) {
+    async getOrCreateSession(sessionId, options = {}) {
         assertValidSessionId(sessionId);
         const existing = this.sessions.get(sessionId);
         if (existing) {
+            assertSessionProjectUnchanged(existing, options.project);
             return cloneSession(existing);
         }
         const timestamp = toIso(this.now);
         const session = {
             id: sessionId,
+            ...(options.project
+                ? { project: copySessionProject(options.project) }
+                : {}),
             title: sessionId,
             createdAt: timestamp,
             updatedAt: timestamp,
@@ -87,6 +93,7 @@ class InMemorySessionStore {
         }
         return {
             sessionId,
+            ...(session.project ? { project: session.project } : {}),
             title: session.title,
             messages: filterMessagesAfter(clientVisibleMessages(session.messages), options.afterMessageId).map((message) => toSnapshotMessage(sessionId, message, session.requests ?? [])),
             requests: options.includeRequests === false
@@ -106,6 +113,7 @@ class InMemorySessionStore {
             return {
                 requestId,
                 sessionId: request.sessionId,
+                ...(request.generation ? { generation: request.generation } : {}),
                 events: request.events
                     .filter((event) => event.seqNo > normalizedAfterSeq)
                     .map(toClientReplayEvent),
@@ -262,6 +270,8 @@ class InMemorySessionStore {
             const request = {
                 requestId,
                 sessionId,
+                // Only an explicit new stream establishes a request lifetime.
+                generation: randomUUID(),
                 status: "streaming",
                 createdAt: timestamp,
                 updatedAt: timestamp,

package/dist/src/runtime/adapters/long-term-memory/file-lock/acquisition.js

@@ -12,7 +12,7 @@ export async function acquireFileLock(lockPath, options) {
     for (;;) {
         const token = randomUUID();
         try {
-            await installLockDirectory(lockPath, token);
+            await installLockDirectory(lockPath, token, options.ownerIdentity);
             return createRelease(lockPath, token, options.releaseMode);
         }
         catch (error) {
@@ -51,9 +51,8 @@ async function removeAbandonedLock(lockPath, processIsAlive) {
         return true;
     if (snapshot.kind === "legacy_file" || !snapshot.reclaimable)
         return false;
-    if (snapshot.ownerPid !== undefined && processIsAlive(snapshot.ownerPid)) {
+    if (await hasLiveObservedOwner(snapshot, processIsAlive))
         return false;
-    }
     if (snapshot.record && snapshot.ownerFileName) {
         return removeObservedOwner(lockPath, snapshot.ownerFileName);
     }
@@ -65,6 +64,11 @@ async function removeAbandonedLock(lockPath, processIsAlive) {
     }
     return removeEmptyLockTree(lockPath, snapshot.hasLeaseDirectory);
 }
+async function hasLiveObservedOwner(snapshot, processIsAlive) {
+    if (snapshot.ownerPid === undefined)
+        return false;
+    return processIsAlive(snapshot.ownerPid, snapshot.record?.ownerIdentity);
+}
 function defaultProcessIsAlive(pid) {
     try {
         process.kill(pid, 0);

package/dist/src/runtime/adapters/long-term-memory/file-lock/contracts.d.ts

@@ -7,7 +7,9 @@ export declare const OWNER_FILE_PATTERN: RegExp;
 export type FileLockOptions = Readonly<{
     waitMs?: number;
     retryDelayMs?: number;
-    processIsAlive?: (pid: number) => boolean;
+    /** Optional process incarnation; interpreted only by the caller's liveness probe. */
+    ownerIdentity?: string;
+    processIsAlive?: (pid: number, ownerIdentity?: string) => boolean | Promise<boolean>;
     /** Long-lived host leases must finish physical cleanup before process.exit. */
     releaseMode?: "asynchronous" | "synchronous";
 }>;
@@ -15,6 +17,7 @@ export type LockRecord = Readonly<{
     pid: number;
     token: string;
     createdAt: string;
+    ownerIdentity?: string;
 }>;
 export type DirectoryLockSnapshot = Readonly<{
     kind: "directory";

package/dist/src/runtime/adapters/long-term-memory/file-lock/install.d.ts

@@ -1 +1 @@
-export declare function installLockDirectory(lockPath: string, token: string): Promise<void>;
+export declare function installLockDirectory(lockPath: string, token: string, ownerIdentity?: string): Promise<void>;

package/dist/src/runtime/adapters/long-term-memory/file-lock/install.js

@@ -2,7 +2,10 @@ import { mkdir, open, rename } from "node:fs/promises";
 import { join } from "node:path";
 import { removeDirectoryIfEmpty, removeStagingLock } from "./cleanup.js";
 import { LEASE_DIRECTORY_NAME, ownerFileName } from "./contracts.js";
-export async function installLockDirectory(lockPath, token) {
+import { hasValidOptionalLockOwnerIdentity } from "./owner-identity.js";
+export async function installLockDirectory(lockPath, token, ownerIdentity) {
+    if (!hasValidOptionalLockOwnerIdentity(ownerIdentity))
+        throw new Error("file_lock_owner_identity_invalid");
     const stagingPath = `${lockPath}.${process.pid}.${token}.pending`;
     const stagingOwnerPath = join(stagingPath, ownerFileName(token));
     let handle;
@@ -15,6 +18,7 @@ export async function installLockDirectory(lockPath, token) {
             pid: process.pid,
             token,
             createdAt: new Date().toISOString(),
+            ...(ownerIdentity === undefined ? {} : { ownerIdentity }),
         }), "utf8");
         await handle.sync();
         await handle.close();

package/dist/src/runtime/adapters/long-term-memory/file-lock/owner-identity.d.ts

@@ -0,0 +1,3 @@
+/** Opaque caller-owned incarnation metadata; the lock does not interpret it. */
+export declare function isLockOwnerIdentity(value: unknown): value is string;
+export declare function hasValidOptionalLockOwnerIdentity(value: unknown): value is string | undefined;

package/dist/src/runtime/adapters/long-term-memory/file-lock/owner-identity.js

@@ -0,0 +1,15 @@
+/** Opaque caller-owned incarnation metadata; the lock does not interpret it. */
+export function isLockOwnerIdentity(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value.length === 0)
+        return false;
+    if (Buffer.byteLength(value, "utf8") > 256)
+        return false;
+    return !/[\x00-\x1f\x7f]/u.test(value);
+}
+export function hasValidOptionalLockOwnerIdentity(value) {
+    if (value === undefined)
+        return true;
+    return isLockOwnerIdentity(value);
+}

package/dist/src/runtime/adapters/long-term-memory/file-lock/owner-record.js

@@ -2,6 +2,7 @@ import { constants } from "node:fs";
 import { open } from "node:fs/promises";
 import { join } from "node:path";
 import { directorySnapshot, fileSystemErrorCode, LEASE_DIRECTORY_NAME, MAX_LOCK_RECORD_BYTES, } from "./contracts.js";
+import { isLockOwnerIdentity } from "./owner-identity.js";
 export async function readOwnerRecord(lockPath, entryName, expectedToken, directoryModifiedAtMs) {
     let handle;
     try {
@@ -109,6 +110,7 @@ function parseLockRecord(raw, expectedToken) {
             pid: ownerPid,
             token: expectedToken,
             createdAt: candidate.createdAt,
+            ...(isLockOwnerIdentity(candidate.ownerIdentity) ? { ownerIdentity: candidate.ownerIdentity } : {}),
         }),
     });
 }

package/dist/src/runtime/adapters/long-term-memory/file-repository.js

@@ -3,6 +3,7 @@ import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { advanceMemorySnapshot, createEmptyMemorySnapshot, parseMemorySnapshot, } from "../../long-term-memory/repository-state.js";
 import { withFileLock } from "./file-lock.js";
+import { preserveMemoryMigrationBackup } from "./migration-backup.js";
 const STORE_FILE_NAME = "memory.json";
 const LOCK_FILE_NAME = "memory.lock";
 const PRIVATE_STORE_FILE_MODE = 0o600;
@@ -16,6 +17,7 @@ export function createFileLongTermMemoryRepository(directory) {
             return withFileLock(lockPath, async () => {
                 const current = await readSnapshot(storePath);
                 const next = advanceMemorySnapshot(current, mutate(current));
+                await preserveMemoryMigrationBackup(storePath, current, next);
                 await writeSnapshot(storePath, next);
                 return next;
             });

package/dist/src/runtime/adapters/long-term-memory/migration-backup.d.ts

@@ -0,0 +1,3 @@
+import type { LongTermMemoryRepositorySnapshot } from "../../long-term-memory/contracts.js";
+/** Preserve one private rollback snapshot before each incompatible replacement. */
+export declare function preserveMemoryMigrationBackup(storePath: string, current: LongTermMemoryRepositorySnapshot, next: LongTermMemoryRepositorySnapshot): Promise<void>;