@abot-ai/runtime 1.7.0 → 1.8.1

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

@@ -24,6 +24,10 @@ export async function readBoundedRegularFile(absolutePath, options) {
         throw new RangeError("maxBytes must be a non-negative safe integer");
     }
     throwIfAborted(options.signal);
+    if (process.platform === "win32") {
+        const { readWindowsBoundedRegularFile } = await import("./files-windows/read.js");
+        return readWindowsBoundedRegularFile(absolutePath, options);
+    }
     if (typeof constants.O_NOFOLLOW !== "number") {
         return Object.freeze({ ok: false, reason: "safe_open_unsupported" });
     }

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

@@ -4,6 +4,7 @@ export * from "./parameters.js";
 export * from "./paths.js";
 export * from "./plugin.js";
 export * from "./results.js";
+export * from "./mutation-result.js";
 export * from "./context-text-result.js";
 export * from "../capabilities/tool-media.js";
 export * from "./tool-availability-brief.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 "./mutation-result.js";
 export * from "./context-text-result.js";
 export * from "../capabilities/tool-media.js";
 export * from "./tool-availability-brief.js";

package/dist/src/plugin-sdk/mutation-result.d.ts

@@ -0,0 +1,7 @@
+import type { ToolImplementationOutput } from "../plugin-contract/entrypoint.js";
+import { type SuccessResultInput, type ToolResultBudget } from "./results.js";
+/**
+ * Reports a mutation already confirmed by the owning plugin. This helper
+ * preserves its receipt; it does not execute or independently verify a change.
+ */
+export declare function mutationSuccessResult(input: SuccessResultInput, resultBudget?: ToolResultBudget): ToolImplementationOutput;

package/dist/src/plugin-sdk/mutation-result.js

@@ -0,0 +1,11 @@
+import { successResult, } from "./results.js";
+/**
+ * Reports a mutation already confirmed by the owning plugin. This helper
+ * preserves its receipt; it does not execute or independently verify a change.
+ */
+export function mutationSuccessResult(input, resultBudget) {
+    return successResult({
+        ...input,
+        data: { ...input.data, mutationEvidence: true },
+    }, resultBudget);
+}

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

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { removeEmptyLockTree, removeObservedOwner } from "./cleanup.js";
 import { fileSystemErrorCode, INCOMPLETE_LOCK_GRACE_MS, LOCK_ACQUIRE_TIMEOUT_MS, LOCK_RETRY_DELAY_MS, ownerFileName, } from "./contracts.js";
 import { installLockDirectory } from "./install.js";
+import { isWindowsLockReadDenial } from "./path-observation.js";
 import { readLockSnapshot } from "./snapshot.js";
 import { removeObservedOwnerSynchronously } from "./synchronous-release.js";
 export async function acquireFileLock(lockPath, options) {
@@ -18,7 +19,7 @@ export async function acquireFileLock(lockPath, options) {
         catch (error) {
             if (!isLockContention(error))
                 throw error;
-            const removed = await removeAbandonedLock(lockPath, processIsAlive);
+            const removed = await removeAbandonedLock(lockPath, processIsAlive, deadline, retryDelayMs);
             if (removed)
                 continue;
             if (Date.now() >= deadline) {
@@ -45,8 +46,8 @@ function createRelease(lockPath, token, releaseMode) {
 function requiresSynchronousRelease(mode) {
     return mode === "synchronous";
 }
-async function removeAbandonedLock(lockPath, processIsAlive) {
-    const snapshot = await readLockSnapshot(lockPath);
+async function removeAbandonedLock(lockPath, processIsAlive, deadline, retryDelayMs) {
+    const snapshot = await readContendedSnapshot(lockPath, deadline, retryDelayMs);
     if (!snapshot)
         return true;
     if (snapshot.kind === "legacy_file" || !snapshot.reclaimable)
@@ -64,6 +65,22 @@ async function removeAbandonedLock(lockPath, processIsAlive) {
     }
     return removeEmptyLockTree(lockPath, snapshot.hasLeaseDirectory);
 }
+async function readContendedSnapshot(lockPath, deadline, retryDelayMs) {
+    for (;;) {
+        try {
+            return await readLockSnapshot(lockPath);
+        }
+        catch (error) {
+            if (!isWindowsLockReadDenial(error))
+                throw error;
+            if (Date.now() >= deadline)
+                throw error;
+            // Windows can deny a pending deletion while stat still sees the directory.
+            // Wait within the acquisition budget; an unreadable owner is never reclaimed.
+            await delay(Math.min(retryDelayMs, Math.max(deadline - Date.now(), 0)));
+        }
+    }
+}
 async function hasLiveObservedOwner(snapshot, processIsAlive) {
     if (snapshot.ownerPid === undefined)
         return false;

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

@@ -3,10 +3,12 @@ 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";
+import { observeLockReadFailure } from "./path-observation.js";
 export async function readOwnerRecord(lockPath, entryName, expectedToken, directoryModifiedAtMs) {
     let handle;
     try {
-        handle = await open(join(lockPath, LEASE_DIRECTORY_NAME, entryName), constants.O_RDONLY | constants.O_NOFOLLOW);
+        const ownerPath = join(lockPath, LEASE_DIRECTORY_NAME, entryName);
+        handle = await open(ownerPath, constants.O_RDONLY | constants.O_NOFOLLOW).catch(async (error) => { throw await observeLockReadFailure(ownerPath, error); });
         const before = await handle.stat({ bigint: true });
         const modifiedAtMs = Math.max(directoryModifiedAtMs, Number(before.mtimeMs));
         const hasReadableRecord = before.isFile() &&

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

@@ -0,0 +1,3 @@
+/** Only confirmed disappearance can normalize a Windows pending-delete denial. */
+export declare function observeLockReadFailure(path: string, error: unknown): Promise<unknown>;
+export declare function isWindowsLockReadDenial(error: unknown): boolean;

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

@@ -0,0 +1,20 @@
+import { lstat } from "node:fs/promises";
+import { fileSystemErrorCode } from "./contracts.js";
+/** Only confirmed disappearance can normalize a Windows pending-delete denial. */
+export async function observeLockReadFailure(path, error) {
+    if (!isWindowsLockReadDenial(error))
+        return error;
+    try {
+        await lstat(path);
+    }
+    catch (observedError) {
+        if (fileSystemErrorCode(observedError) === "ENOENT")
+            return observedError;
+    }
+    return error;
+}
+export function isWindowsLockReadDenial(error) {
+    if (process.platform !== "win32")
+        return false;
+    return fileSystemErrorCode(error) === "EPERM";
+}

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

@@ -2,6 +2,7 @@ import { lstat, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { directorySnapshot, fileSystemErrorCode, LEASE_DIRECTORY_NAME, OWNER_FILE_PATTERN, } from "./contracts.js";
 import { readOwnerRecord } from "./owner-record.js";
+import { observeLockReadFailure } from "./path-observation.js";
 export async function readLockSnapshot(lockPath) {
     const lockInfo = await readLockInfo(lockPath);
     if (!lockInfo)
@@ -13,7 +14,8 @@ export async function readLockSnapshot(lockPath) {
     try {
         lockEntries = await readdir(lockPath, { withFileTypes: true });
     }
-    catch (error) {
+    catch (readError) {
+        const error = await observeLockReadFailure(lockPath, readError);
         const code = fileSystemErrorCode(error);
         if (code === "ENOENT")
             return undefined;
@@ -45,7 +47,8 @@ async function readLockInfo(lockPath) {
     try {
         return await lstat(lockPath);
     }
-    catch (error) {
+    catch (readError) {
+        const error = await observeLockReadFailure(lockPath, readError);
         if (fileSystemErrorCode(error) === "ENOENT")
             return undefined;
         throw error;
@@ -62,7 +65,8 @@ async function readLeaseSnapshot(lockPath, lockModifiedAtMs) {
         }
         leaseEntries = await readdir(leasePath, { withFileTypes: true });
     }
-    catch (error) {
+    catch (readError) {
+        const error = await observeLockReadFailure(leasePath, readError);
         if (fileSystemErrorCode(error) === "ENOENT") {
             return invalidLeaseSnapshot(lockModifiedAtMs);
         }

package/dist/src/runtime/adapters/passive-learning-runtime.d.ts

@@ -1,7 +1,7 @@
 import type { RuntimeConfig, ModelGatewayClient, SessionStore } from "../ports.js";
 import type { LongTermMemoryService } from "../long-term-memory/contracts.js";
 import type { SessionRequestAdmission } from "../request/session-admission.js";
-/** The environment owns learning; the paired desktop owns native collection. */
+/** The environment owns learning; the collection adapter owns the selected desktop source. */
 export declare function createRuntimePassiveLearning(params: {
     config: RuntimeConfig;
     models: ModelGatewayClient;

package/dist/src/runtime/adapters/passive-learning-runtime.js

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
-import { connectHostObservations } from "../../computer-access/companion/observation-client.js";
+import { connectRuntimeObservations } from "./runtime-observation-connection.js";
 import { createPassiveLearningService } from "../passive-learning/service.js";
 import { createRuntimePassiveLearningModel } from "../passive-learning/model.js";
 import { createCoWorkerResourceDependencies } from "./co-worker-resources.js";
-/** The environment owns learning; the paired desktop owns native collection. */
+/** The environment owns learning; the collection adapter owns the selected desktop source. */
 export function createRuntimePassiveLearning(params) {
     const { config, models, memory } = params;
     const ownerId = createHash("sha256")
@@ -19,7 +19,7 @@ export function createRuntimePassiveLearning(params) {
             config, models, memory, context, ownerId, directory: join(config.paths.runtimeDir, "passive-learning"),
             sessions: params.sessions, deliveryAdmission: params.deliveryAdmission,
         }),
-        connect: (input) => connectHostObservations({
+        connect: (input) => connectRuntimeObservations({
             ...input,
             ownerId,
             rootDir: config.paths.rootDir,

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-rejection.d.ts

@@ -1,8 +1,8 @@
 import type { CapabilityAdapterResult } from "../../orchestration/capability-adapters/index.js";
 import type { WorkerCapabilityAdapterResult, WorkerCapabilityExecutionFreshness } from "../../orchestration/worker-capabilities/index.js";
 import type { PayloadLifecycleEmitter } from "./payload-observability.js";
-export declare const STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION: "steering_superseded_before_external_execution";
-export declare const STEERING_SUPERSEDED_SUMMARY = "steering_superseded_before_external_execution: No external execution occurred because a newer active-request update superseded this capability invocation.";
+import { STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY } from "../../orchestration/worker-capabilities/execution/execution-freshness.js";
+export { STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY, };
 export type PayloadLifecycleContext = Readonly<Omit<Parameters<PayloadLifecycleEmitter["emitPayloadLifecycle"]>[0], "phase" | "errorCode">>;
 export declare function rejectPayloadLifecycle(params: {
     executor: PayloadLifecycleEmitter;

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/payload-rejection.js

@@ -1,7 +1,7 @@
 import { boundedSummary, requireCapabilityAdapterResult, } from "./result-observer.js";
 import { createRegisteredToolWorkerFailureOutcomeFingerprint } from "./failure-outcome-fingerprint.js";
-export const STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION = "steering_superseded_before_external_execution";
-export const STEERING_SUPERSEDED_SUMMARY = "steering_superseded_before_external_execution: No external execution occurred because a newer active-request update superseded this capability invocation.";
+import { STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY, } from "../../orchestration/worker-capabilities/execution/execution-freshness.js";
+export { STEERING_SUPERSEDED_BEFORE_EXTERNAL_EXECUTION, STEERING_SUPERSEDED_SUMMARY, };
 export function rejectPayloadLifecycle(params) {
     const failed = params.executor.emitPayloadLifecycle({
         ...params.lifecycle,

package/dist/src/runtime/adapters/registered-tool-worker-capabilities/prepared-execution.js

@@ -1,9 +1,23 @@
 import { traceRegisteredToolWorkerCapabilityExecutionStarted, traceRegisteredToolWorkerCapabilityExecutionCompleted, traceRegisteredToolWorkerCapabilityExecutionFailed, } from "../registered-tool-worker-capability-diagnostics.js";
 import { executionFreshnessRejection } from "./payload-lifecycle.js";
+import { payloadRejection } from "./payload-rejection.js";
 import { RegisteredToolWorkerCapabilityExecutionError } from "./errors.js";
 import { observeExternalResult, attachTargetReferences, } from "./result-observer.js";
 export function createPreparedWorkerInvocation(params, input, normalPreparation, selectedTargetReferences, payloadObservability) {
     const operationId = params.projection.operation.operationId;
+    const rejectBeforeExecution = (executionId, code, message) => {
+        payloadObservability.release(executionId);
+        const rejectedExecution = payloadRejection(code, message);
+        normalPreparation.emitRejection({
+            executionId,
+            executorIdentity: input.call,
+            errorCode: code,
+        });
+        return attachTargetReferences({
+            ...rejectedExecution.result,
+            exactResult: rejectedExecution.exactResult,
+        }, selectedTargetReferences);
+    };
     return Object.freeze({
         actionFingerprint: normalPreparation.actionFingerprint,
         acceptedControls: normalPreparation.acceptedControls,
@@ -18,22 +32,14 @@ export function createPreparedWorkerInvocation(params, input, normalPreparation,
             : {}),
         applyApprovalDecision: normalPreparation.applyApprovalDecision,
         onAdmitted: payloadObservability.release,
+        rejectBeforeExecution,
         execute: async (executionId) => {
             try {
                 payloadObservability.release(executionId);
                 traceRegisteredToolWorkerCapabilityExecutionStarted(params.diagnostic, operationId, input.call, executionId, input.intent.length, Object.keys(input.controls).length);
                 const rejectedExecution = executionFreshnessRejection(input.executionFreshness);
-                if (rejectedExecution) {
-                    normalPreparation.emitRejection({
-                        executionId,
-                        executorIdentity: input.call,
-                        errorCode: rejectedExecution.sourceIssueCode,
-                    });
-                    return attachTargetReferences({
-                        ...rejectedExecution.result,
-                        exactResult: rejectedExecution.exactResult,
-                    }, selectedTargetReferences);
-                }
+                if (rejectedExecution)
+                    return rejectBeforeExecution(executionId, rejectedExecution.sourceIssueCode, rejectedExecution.result.summary);
                 const externalResult = await normalPreparation.execute(executionId, input.call, selectedTargetReferences);
                 const observed = observeExternalResult(externalResult, params.projection.operation.effect, input.call.parentCallId === null, selectedTargetReferences);
                 const observedResult = observed.result;

package/dist/src/runtime/adapters/runtime-observation-connection.d.ts

@@ -0,0 +1,5 @@
+import type { HostObservationSubscription } from "../../shared/passive-observation.js";
+/** Installation consent gates every collection route before transport or helper startup. */
+export declare function connectRuntimeObservations(options: HostObservationSubscription): Promise<Readonly<{
+    close(): void;
+}>>;

package/dist/src/runtime/adapters/runtime-observation-connection.js

@@ -0,0 +1,13 @@
+import { connectHostObservations } from "../../computer-access/companion/observation-client.js";
+import { connectNativeObservations } from "../../computer-access/native-observation-connection.js";
+import { requireCollectionConsent } from "../../computer-access/collection-consent.js";
+import { readRuntimeCollectionSource } from "../../computer-access/observation-source.js";
+/** Installation consent gates every collection route before transport or helper startup. */
+export async function connectRuntimeObservations(options) {
+    options.abortSignal.throwIfAborted();
+    await requireCollectionConsent(options.rootDir);
+    options.abortSignal.throwIfAborted();
+    if (readRuntimeCollectionSource().mode === "native")
+        return connectNativeObservations(options);
+    return connectHostObservations(options);
+}

package/dist/src/runtime/capabilities/tool-availability.js

@@ -3,6 +3,12 @@ export function projectAvailableTools(registrations) {
         return undefined;
     const entries = registrations.flatMap((registration) => registration.contract.operations.map((operation) => Object.freeze({
         toolName: registration.toolName,
+        ...(registration.definition.pluginName !== undefined
+            ? { pluginName: registration.definition.pluginName }
+            : {}),
+        ...(registration.definition.pluginDescription !== undefined
+            ? { pluginDescription: registration.definition.pluginDescription }
+            : {}),
         operationId: operation.operationId,
         summary: operation.summary,
         catalogGroups: Object.freeze([

package/dist/src/runtime/context/capability-brief.d.ts

@@ -1,10 +1,10 @@
 import type { ChatMessage, ModelTokenEstimationConfig } from "../../model-gateway/types.js";
 import type { ToolAvailabilityEntry } from "../../capabilities/tool-types.js";
-import { type ToolAvailabilityOverviewGroup, type ToolAvailabilityOverviewLevel } from "../../plugin-sdk/tool-availability-overview.js";
+import { type ToolAvailabilityOverviewGroup } from "../../plugin-sdk/tool-availability-overview.js";
 import type { projectRequestContext } from "./request-context.js";
 export declare const CAPABILITY_BRIEF_KIND = "runtime_capability_brief_v1";
 export declare const CAPABILITY_BRIEF_MAX_TOKENS = 512;
-export type CapabilityBriefLevel = ToolAvailabilityOverviewLevel | "descriptions" | "none";
+export type CapabilityBriefLevel = "groups" | "descriptions" | "none";
 export type CapabilityBriefProjection = Readonly<{
     level: CapabilityBriefLevel;
     message?: ChatMessage;

package/dist/src/runtime/context/capability-brief.js

@@ -1,6 +1,6 @@
 import { buildToolAvailabilityOverview, } from "../../plugin-sdk/tool-availability-overview.js";
 import { resolveCapabilityBriefHeadroom } from "./capability-brief-budget.js";
-import { buildCapabilityDescriptions } from "./capability-descriptions.js";
+import { buildPluginDiscoveryCatalogText } from "./capability-descriptions.js";
 import { estimateMessageTokens } from "./token-estimator.js";
 export const CAPABILITY_BRIEF_KIND = "runtime_capability_brief_v1";
 export const CAPABILITY_BRIEF_MAX_TOKENS = 512;
@@ -22,12 +22,12 @@ export function projectCapabilityBriefAtHeadroom(params) {
         return omittedBrief(compactBudgetTokens, "empty_catalog");
     }
     const levels = hasCompleteCapabilityBriefEntries(params.entries, params.groups)
-        ? ["descriptions", "detailed", "titles", "groups"]
+        ? ["descriptions", "groups"]
         : ["groups"];
     for (const level of levels) {
         const budgetTokens = level === "descriptions" ? headroom : compactBudgetTokens;
         const body = level === "descriptions"
-            ? buildCapabilityDescriptions(params.entries ?? [])
+            ? buildPluginDiscoveryCatalogText(params.groups.map(({ groupId }) => groupId), params.entries)
             : buildToolAvailabilityOverview(params.entries ?? [], params.groups, level);
         const message = Object.freeze({
             role: "system",

package/dist/src/runtime/context/capability-descriptions.d.ts

@@ -1,3 +1,4 @@
 import type { ToolAvailabilityEntry } from "../../capabilities/tool-types.js";
-/** Complete request-registry facts; neither a selected subset nor tool schemas. */
-export declare function buildCapabilityDescriptions(entries: readonly ToolAvailabilityEntry[]): string;
+export declare const PLUGIN_DISCOVERY_CATALOG_HEADER = "Tool groups:";
+/** Passive discovery: selectable groups first, with plugin descriptions once. */
+export declare function buildPluginDiscoveryCatalogText(catalogGroupIds: readonly string[], entries?: readonly ToolAvailabilityEntry[]): string;

package/dist/src/runtime/context/capability-descriptions.js

@@ -1,23 +1,60 @@
-/** Complete request-registry facts; neither a selected subset nor tool schemas. */
-export function buildCapabilityDescriptions(entries) {
-    const ordered = [...entries].sort(compareCapabilityDescriptions);
-    return JSON.stringify(ordered.map(({ toolName, operationId, summary, catalogGroups }) => ({
-        toolName,
-        operationId,
-        summary,
-        catalogGroups: [...new Set(catalogGroups)].sort(compareAscii),
-    })));
+export const PLUGIN_DISCOVERY_CATALOG_HEADER = "Tool groups:";
+/** Passive discovery: selectable groups first, with plugin descriptions once. */
+export function buildPluginDiscoveryCatalogText(catalogGroupIds, entries = []) {
+    const offeredGroups = new Set(catalogGroupIds);
+    const toolsByGroup = new Map();
+    const descriptions = new Map();
+    for (const entry of entries) {
+        const groupIds = entry.catalogGroups.filter((id) => offeredGroups.has(id));
+        if (groupIds.length === 0)
+            continue;
+        // The empty owner denotes a native tool, never a fabricated plugin.
+        const owner = entry.pluginName ?? "";
+        for (const id of groupIds) {
+            const owners = toolsByGroup.get(id) ?? new Map();
+            const toolNames = owners.get(owner) ?? new Set();
+            toolNames.add(entry.toolName);
+            owners.set(owner, toolNames);
+            toolsByGroup.set(id, owners);
+        }
+        if (!entry.pluginName)
+            continue;
+        const description = descriptions.get(entry.pluginName)
+            || formatPluginDiscoveryDescription(entry.pluginDescription);
+        if (description)
+            descriptions.set(entry.pluginName, description);
+    }
+    const hasOfferedToolBindings = toolsByGroup.size > 0;
+    if (!hasOfferedToolBindings) {
+        return catalogGroupIds.length > 0
+            ? `${PLUGIN_DISCOVERY_CATALOG_HEADER} ${catalogGroupIds.join(", ")}`
+            : PLUGIN_DISCOVERY_CATALOG_HEADER;
+    }
+    const groupEntries = [...offeredGroups].sort().map((id) => {
+        const owners = toolsByGroup.get(id);
+        if (!owners)
+            return id;
+        const bindings = [...owners.keys()].sort().map((owner) => {
+            const names = [...owners.get(owner)].sort().map(formatPluginDiscoveryToolName).join(", ");
+            return owner ? `${owner} [${names}]` : names;
+        });
+        return `${id}: ${bindings.join(", ")}`;
+    });
+    const catalog = `${PLUGIN_DISCOVERY_CATALOG_HEADER} ${groupEntries.join(" | ")}`;
+    const pluginDescriptions = [...descriptions.keys()].sort().map((name) => `${name}: ${descriptions.get(name)}`);
+    return pluginDescriptions.length > 0
+        ? `${catalog}\nPlugin descriptions: ${pluginDescriptions.join(" | ")}`
+        : catalog;
 }
-function compareCapabilityDescriptions(left, right) {
-    const byOperation = compareAscii(left.operationId, right.operationId);
-    if (byOperation !== 0)
-        return byOperation;
-    return compareAscii(left.toolName, right.toolName);
+function formatPluginDiscoveryToolName(name) {
+    return name.replace(/[%\\[\],;:|\s\u0000-\u001f\u007f]/gu, (character) => encodeURIComponent(character));
 }
-function compareAscii(left, right) {
-    if (left < right)
-        return -1;
-    if (left > right)
-        return 1;
-    return 0;
+function formatPluginDiscoveryDescription(description) {
+    if (description === undefined)
+        return undefined;
+    const normalized = description.replaceAll("|", "/").replace(/\s+/gu, " ").trim();
+    const characters = Array.from(normalized);
+    if (characters.length <= 160)
+        return normalized;
+    return `${characters.slice(0, 160).join("")}....`;
 }

package/dist/src/runtime/local-host/windows-private-access.js

@@ -2,7 +2,9 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execute = promisify(execFile);
 // Paths travel through an environment value, never through shell interpolation.
+// PowerShell 7 callers can pass incompatible modules to Windows PowerShell 5.1.
 const privateAccessScript = `
+$env:PSModulePath = "$PSHOME\\Modules"
 $ErrorActionPreference = 'Stop'
 $target = $env:ABOT_LOCAL_HOST_PRIVATE_PATH
 $current = [System.Security.Principal.WindowsIdentity]::GetCurrent().User

package/dist/src/runtime/long-term-memory/conversation-authoring/context.d.ts

@@ -1,7 +1,7 @@
 import type { ChatMessage } from "../../../model-gateway/types.js";
 import type { RequestExecutionScope } from "../../request/execution-scope.js";
 import type { RequestSteeringSnapshot } from "../../request/request-steering.js";
-import type { LearningKnowledgeEntry } from "../maturation/contracts.js";
+import type { LearningKnowledgeEntry, LearningKnowledgeContext } from "../maturation/contracts.js";
 import type { ConversationMemoryEvidence } from "../maturation/evidence-contracts.js";
 export type ConversationMemoryAuthoringContext = Readonly<{
     evidence: ConversationMemoryEvidence;
@@ -12,3 +12,8 @@ export type ConversationMemoryAuthoringContext = Readonly<{
 export declare function canAuthorConversationMemory(request: Pick<RequestExecutionScope, "longTermMemory">, context: ConversationMemoryAuthoringContext | undefined): boolean;
 /** Request-local authoring reference; never part of ordinary recall or routing. */
 export declare function prepareConversationMemoryAuthoring(request: Pick<RequestExecutionScope, "longTermMemory" | "requestId" | "sessionId" | "prompt" | "abortSignal">, steering: RequestSteeringSnapshot): Promise<ConversationMemoryAuthoringContext | undefined>;
+export declare function prepareConversationMemoryKnowledge(request: Pick<RequestExecutionScope, "longTermMemory" | "requestId" | "sessionId" | "prompt" | "abortSignal">, steering: RequestSteeringSnapshot): Promise<LearningKnowledgeContext | undefined>;
+/** Shared deterministic binding for decision and response authoring. No retrieval. */
+export declare function buildConversationMemoryAuthoringContext(request: Pick<RequestExecutionScope, "requestId" | "sessionId" | "prompt">, steering: RequestSteeringSnapshot, context: Pick<LearningKnowledgeContext, "entries" | "omitted" | "referenceTime">): ConversationMemoryAuthoringContext;
+/** The same contract projection must precede ledger cloning and durable approval capture. */
+export declare function projectConversationMemoryKnowledge(context: LearningKnowledgeContext): LearningKnowledgeContext;

package/dist/src/runtime/long-term-memory/conversation-authoring/context.js

@@ -10,6 +10,10 @@ export function canAuthorConversationMemory(request, context) {
 }
 /** Request-local authoring reference; never part of ordinary recall or routing. */
 export async function prepareConversationMemoryAuthoring(request, steering) {
+    const context = await prepareConversationMemoryKnowledge(request, steering);
+    return context ? buildConversationMemoryAuthoringContext(request, steering, context) : undefined;
+}
+export async function prepareConversationMemoryKnowledge(request, steering) {
     const learning = request.longTermMemory?.learning;
     if (!request.longTermMemory?.enabled || !learning)
         return undefined;
@@ -19,31 +23,7 @@ export async function prepareConversationMemoryAuthoring(request, steering) {
             abortSignal: request.abortSignal,
             debugRequestId: request.requestId,
         });
-        const evidence = Object.freeze({
-            sourceSessionId: request.sessionId,
-            sourceRequestId: request.requestId,
-            observedAt: context.referenceTime,
-            evidenceDigest: createHash("sha256").update(JSON.stringify([
-                request.prompt, ...steering.updates.map(({ text }) => text),
-            ])).digest("hex"),
-        });
-        const entries = structuredClone(context.entries);
-        const targets = new Map(entries.map((entry, index) => [`k${index + 1}`, Object.freeze(entry)]));
-        return Object.freeze({
-            evidence, targets,
-            userMessages: Object.freeze([request.prompt, ...steering.updates.map(({ text }) => text)]),
-            message: Object.freeze({ role: "system", content: JSON.stringify({
-                    kind: "conversation_memory_authoring_reference_v1",
-                    authority: "passive_memory_reference",
-                    purpose: "assess_lasting_user_knowledge_and_resolve_optional_update_targets",
-                    applicability: "memoryCandidates_only",
-                    presenceEffect: "not_user_intent_fresh_evidence_or_action_authority",
-                    targetPolicy: "null_creates_candidate_only_use_supplied_mutable_refs_for_updates",
-                    omitted: context.omitted,
-                    omissionMeaning: "unlisted_knowledge_is_unknown_and_cannot_be_targeted",
-                    entries: [...targets].map(([ref, { id: _id, version: _version, ...entry }]) => ({ ref, ...entry })),
-                }) }),
-        });
+        return context;
     }
     catch (error) {
         request.abortSignal.throwIfAborted();
@@ -53,3 +33,49 @@ export async function prepareConversationMemoryAuthoring(request, steering) {
         return undefined;
     }
 }
+/** Shared deterministic binding for decision and response authoring. No retrieval. */
+export function buildConversationMemoryAuthoringContext(request, steering, context) {
+    const evidence = Object.freeze({
+        sourceSessionId: request.sessionId,
+        sourceRequestId: request.requestId,
+        observedAt: context.referenceTime,
+        evidenceDigest: createHash("sha256").update(JSON.stringify([
+            request.prompt, ...steering.updates.map(({ text }) => text),
+        ])).digest("hex"),
+    });
+    // Project only contract fields, including when entries come from a saved checkpoint.
+    const entries = context.entries.map(projectConversationMemoryKnowledgeEntry);
+    const targets = new Map(entries.map((entry, index) => [`k${index + 1}`, Object.freeze(entry)]));
+    return Object.freeze({
+        evidence, targets,
+        userMessages: Object.freeze([request.prompt, ...steering.updates.map(({ text }) => text)]),
+        message: Object.freeze({ role: "system", content: JSON.stringify({
+                kind: "conversation_memory_authoring_reference_v1",
+                authority: "passive_memory_reference",
+                purpose: "assess_lasting_user_knowledge_and_resolve_optional_update_targets",
+                applicability: "memoryCandidates_only",
+                presenceEffect: "not_user_intent_fresh_evidence_or_action_authority",
+                targetPolicy: "null_creates_candidate_only_use_supplied_mutable_refs_for_updates",
+                omitted: context.omitted,
+                omissionMeaning: "unlisted_knowledge_is_unknown_and_cannot_be_targeted",
+                entries: [...targets].map(([ref, { id: _id, version: _version, ...entry }]) => ({ ref, ...entry })),
+            }) }),
+    });
+}
+/** The same contract projection must precede ledger cloning and durable approval capture. */
+export function projectConversationMemoryKnowledge(context) {
+    return {
+        kind: context.kind, authority: context.authority, presenceEffect: context.presenceEffect,
+        repositoryRevision: context.repositoryRevision, knowledgeRevision: context.knowledgeRevision,
+        referenceTime: context.referenceTime, omitted: context.omitted,
+        entries: context.entries.map(projectConversationMemoryKnowledgeEntry),
+    };
+}
+function projectConversationMemoryKnowledgeEntry(entry) {
+    return {
+        kind: entry.kind, id: entry.id, version: entry.version,
+        content: entry.content, tags: [...entry.tags], mutable: entry.mutable,
+        score: entry.score, reason: entry.reason, certainty: entry.certainty,
+        lastReinforcedAt: entry.lastReinforcedAt, reconsiderAt: entry.reconsiderAt,
+    };
+}

package/dist/src/runtime/long-term-memory/initial-context.d.ts

@@ -0,0 +1,17 @@
+import type { RequestExecutionScope } from "../request/execution-scope.js";
+import type { ChatMessage } from "../../model-gateway/types.js";
+import { type RequestSteeringSnapshot } from "../request/request-steering.js";
+import type { RoleInitialMemory } from "../orchestration/role-calls/memory-recall-contract.js";
+/** Prepared once as part of the existing request ledger initialization. */
+export declare function prepareInitialMemory(request: RequestExecutionScope, restored?: RoleInitialMemory): Promise<RoleInitialMemory | undefined>;
+export declare function projectExecutionAgentMemory(request: RequestExecutionScope, initial: RoleInitialMemory | undefined, steering: RequestSteeringSnapshot): Readonly<{
+    memoryMessage: ChatMessage | undefined;
+    authoringContext: Readonly<{
+        evidence: import("./maturation/evidence-contracts.js").ConversationMemoryEvidence;
+        targets: ReadonlyMap<string, import("./maturation/contracts.js").LearningKnowledgeEntry>;
+        userMessages: readonly string[];
+        message: ChatMessage;
+    }> | undefined;
+    authoringEnabled: boolean;
+}>;
+export type ExecutionMemoryProjection = ReturnType<typeof projectExecutionAgentMemory>;