@abot-ai/runtime 1.2.0 → 1.3.0

package/dist/src/runtime/capabilities/scheduling/tool-input-properties.js

@@ -0,0 +1,27 @@
+export const scheduleTextField = (maxLength) => ({
+    type: "string",
+    minLength: 1,
+    maxLength,
+});
+export const scheduleTimingProperties = {
+    scheduleKind: {
+        type: "string",
+        enum: ["timer", "once", "interval", "daily", "weekly", "monthly"],
+    },
+    at: scheduleTextField(64),
+    delayMs: { type: "integer", minimum: 1_000, maximum: 31_536_000_000 },
+    everyMs: { type: "integer", minimum: 1_000, maximum: 31_536_000_000 },
+    anchorAt: scheduleTextField(64),
+    weekdays: {
+        type: "array",
+        items: { type: "integer", minimum: 0, maximum: 6 },
+        minItems: 1,
+        maxItems: 7,
+    },
+    dayOfMonth: { type: "integer", minimum: 1, maximum: 31 },
+    timeZone: scheduleTextField(100),
+};
+export const scheduleDetailProperties = {
+    title: scheduleTextField(200),
+    prompt: { type: "string", minLength: 1 },
+};

package/dist/src/runtime/capabilities/scheduling/tool-module.d.ts

@@ -0,0 +1,4 @@
+import type { ToolModuleDeclaration } from "../../../capabilities/tool-types.js";
+import type { RuntimeConfig } from "../../ports.js";
+import type { SchedulerService } from "../../scheduler/contracts.js";
+export declare function createSchedulingToolModule(service: SchedulerService, config: RuntimeConfig, ready: () => Promise<void>): ToolModuleDeclaration;

package/dist/src/runtime/capabilities/scheduling/tool-module.js

@@ -0,0 +1,158 @@
+import { resolveModelSelection } from "../../model/model-selection.js";
+import { requireCreateCalendarTimeZone } from "./create-time-zone.js";
+import { requireAvailableScheduleModel } from "./model-validation.js";
+import { schedulingToolContract } from "./tool-contract.js";
+import { createSchedulerJobPage } from "./job-list-page.js";
+function requireText(value, field) {
+    if (typeof value !== "string")
+        throw new Error(`schedule_${field}_required`);
+    if (!value.trim())
+        throw new Error(`schedule_${field}_required`);
+    return value.trim();
+}
+function scheduleInput(params) {
+    const kind = params.scheduleKind;
+    if (kind === "timer")
+        return { kind, delayMs: Number(params.delayMs) };
+    if (kind === "once")
+        return { kind, at: requireText(params.at, "exact_time") };
+    if (kind === "interval")
+        return {
+            kind,
+            everyMs: Number(params.everyMs),
+            ...(params.anchorAt
+                ? { anchorAt: requireText(params.anchorAt, "anchor_time") }
+                : {}),
+        };
+    if (kind === "daily")
+        return { kind, at: requireText(params.at, "exact_time") };
+    if (kind === "weekly")
+        return {
+            kind,
+            at: requireText(params.at, "exact_time"),
+            weekdays: Array.isArray(params.weekdays)
+                ? params.weekdays.map(Number)
+                : [],
+        };
+    if (kind === "monthly")
+        return {
+            kind,
+            at: requireText(params.at, "exact_time"),
+            dayOfMonth: Number(params.dayOfMonth),
+        };
+    throw new Error("schedule_kind_required");
+}
+function updateInput(params, config) {
+    if (params.modelProfileId !== undefined) {
+        requireAvailableScheduleModel(config, params.modelProfileId);
+    }
+    return {
+        ...(params.title !== undefined
+            ? { title: requireText(params.title, "title") }
+            : {}),
+        ...(params.prompt !== undefined
+            ? { prompt: requireText(params.prompt, "prompt") }
+            : {}),
+        ...(params.modelProfileId !== undefined
+            ? { modelProfileId: requireText(params.modelProfileId, "model") }
+            : {}),
+        ...(params.agentMode !== undefined
+            ? { agentMode: params.agentMode }
+            : {}),
+        ...(params.timeZone !== undefined
+            ? { timeZone: requireText(params.timeZone, "time_zone") }
+            : {}),
+        ...(params.scheduleKind !== undefined
+            ? { schedule: scheduleInput(params) }
+            : {}),
+    };
+}
+export function createSchedulingToolModule(service, config, ready) {
+    async function execute(params, context) {
+        await ready();
+        context?.abortSignal?.throwIfAborted();
+        const sessionId = requireText(context?.sharedState?.currentSessionId, "session");
+        const action = requireText(params.action, "action");
+        if (action === "list") {
+            const jobs = await service.list({ sessionId });
+            return createSchedulerJobPage(jobs, params);
+        }
+        if (action === "create") {
+            requireCreateCalendarTimeZone(params);
+            const request = context?.sharedState?.requestContext;
+            const selection = resolveModelSelection({
+                agentMode: request?.agentMode,
+                modelPreference: request?.modelPreference,
+                modelPolicy: config.models,
+            });
+            return service.create({
+                sessionId,
+                title: requireText(params.title, "title"),
+                prompt: requireText(params.prompt, "prompt"),
+                modelProfileId: requireText(selection.execution.primaryProfileId, "model"),
+                agentMode: selection.agentMode,
+                timeZone: params.timeZone
+                    ? requireText(params.timeZone, "time_zone")
+                    : Intl.DateTimeFormat().resolvedOptions().timeZone,
+                schedule: scheduleInput(params),
+            });
+        }
+        const id = requireText(params.jobId, "job_id");
+        const job = await service.get(id);
+        if (!job)
+            throw new Error("schedule_job_not_found");
+        if (job.sessionId !== sessionId)
+            throw new Error("schedule_job_not_found");
+        if (action === "get")
+            return {
+                job,
+                runs: [...(await service.listRuns(id, { limit: 20 }))].reverse(),
+            };
+        if (action === "update")
+            return service.update(id, updateInput(params, config));
+        if (action === "pause")
+            return service.pause(id);
+        if (action === "resume")
+            return service.resume(id);
+        if (action === "cancel")
+            return service.cancel(id);
+        if (action === "run_now")
+            return service.runNow(id);
+        throw new Error("schedule_action_unknown");
+    }
+    return {
+        definition: {
+            name: "schedules",
+            description: "Core local schedules for the current conversation: create, inspect, edit, pause, resume, cancel and run now. Scheduled requests run with FULL permissions using their saved model.",
+            routingCapability: "semantic_mutation",
+            catalogGroups: ["scheduling"],
+            developmentRoles: ["auxiliary"],
+            controlsRefinement: "mechanical_when_complete",
+        },
+        normalInvocation: schedulingToolContract,
+        async implementation(params, context) {
+            try {
+                const result = await execute(params, context);
+                const isScheduleMutation = params.action !== "list" && params.action !== "get";
+                return {
+                    ok: true,
+                    output: JSON.stringify(result),
+                    producedNewInformation: true,
+                    data: {
+                        mutationEvidence: isScheduleMutation,
+                        currentStateEvidence: true,
+                    },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    ok: false,
+                    output: message,
+                    error: message,
+                    producedNewInformation: false,
+                };
+            }
+        },
+    };
+}

package/dist/src/runtime/capabilities/scheduling/update-operations.d.ts

@@ -0,0 +1,2 @@
+import type { ToolNormalInvocationOperation } from "../../../capabilities/tool-types.js";
+export declare const scheduleUpdateOperations: readonly ToolNormalInvocationOperation[];

package/dist/src/runtime/capabilities/scheduling/update-operations.js

@@ -0,0 +1,49 @@
+import { scheduleDetailProperties, scheduleTextField, scheduleTimingProperties, } from "./tool-input-properties.js";
+const editableJobProperties = {
+    jobId: scheduleTextField(200),
+    ...scheduleDetailProperties,
+    modelProfileId: scheduleTextField(200),
+    agentMode: { type: "string", enum: ["fast", "reasoning", "deep"] },
+    timeZone: scheduleTimingProperties.timeZone,
+};
+function updateScheduleOperation(kind, timingSummary, timingFields, requiredTiming = timingFields) {
+    return {
+        operationId: `update_${kind}`,
+        summary: `Replace this conversation's Job recurrence. Ask for missing timing details before updating. Omit timeZone, modelProfileId and agentMode to retain saved settings. ${timingSummary}`,
+        effect: "mutating",
+        approval: "request_policy",
+        fixedParams: { action: "update", scheduleKind: kind },
+        input: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                ...editableJobProperties,
+                ...Object.fromEntries(timingFields.map((field) => [field, scheduleTimingProperties[field]])),
+            },
+            required: ["jobId", ...requiredTiming],
+        },
+    };
+}
+export const scheduleUpdateOperations = [
+    {
+        operationId: "update",
+        summary: "Edit a Job's title, prompt, model, mode or time zone in this conversation while retaining its recurrence. Choose a kind-specific update operation to replace timing. modelProfileId must identify an available configured model; omitted settings keep their saved values.",
+        effect: "mutating",
+        approval: "request_policy",
+        fixedParams: { action: "update" },
+        input: {
+            type: "object",
+            additionalProperties: false,
+            properties: editableJobProperties,
+            required: ["jobId"],
+        },
+    },
+    updateScheduleOperation("timer", "Run once after delayMs milliseconds.", [
+        "delayMs",
+    ]),
+    updateScheduleOperation("once", "Run once at an exact ISO instant in at, including its UTC offset.", ["at"]),
+    updateScheduleOperation("interval", "Repeat everyMs milliseconds with optional exact first-run anchorAt ISO instant.", ["everyMs", "anchorAt"], ["everyMs"]),
+    updateScheduleOperation("daily", "Run daily at exact HH:mm in at.", ["at"]),
+    updateScheduleOperation("weekly", "Run on weekdays (Sunday=0) at exact HH:mm in at.", ["at", "weekdays"]),
+    updateScheduleOperation("monthly", "Run on dayOfMonth at exact HH:mm in at.", ["at", "dayOfMonth"]),
+];

package/dist/src/runtime/composition.d.ts

@@ -2,8 +2,11 @@ import type WebSocket from "ws";
 import type { EventSinkFactory, ModelGatewayClient, RuntimeConfig, RuntimeHost, SessionStore, ToolRegistry } from "./ports.js";
 import type { RuntimeAttachmentStore } from "./attachments/store.js";
 import type { RequestHandlerOptions, RunRequestMessage } from "./request/contracts.js";
-import { type SessionMemoryCompactor } from "./context/session-memory/index.js";
+import type { SessionMemoryCompactor } from "./context/session-memory/index.js";
 import type { LongTermMemoryService } from "./long-term-memory/contracts.js";
+import type { SchedulerRun, SchedulerService } from "./scheduler/contracts.js";
+import { SessionRequestAdmission } from "./request/session-admission.js";
+import type { RequestSteeringAppendResult } from "./request/request-steering.js";
 export type RuntimeEnvironmentServices = Readonly<{
     config: RuntimeConfig;
     sessions: SessionStore;
@@ -13,15 +16,26 @@ export type RuntimeEnvironmentServices = Readonly<{
     events: EventSinkFactory;
     sessionMemoryCompactor: SessionMemoryCompactor;
     longTermMemory: LongTermMemoryService;
+    scheduler?: SchedulerService;
+    startScheduler?: () => Promise<void>;
+    stopScheduler?: () => Promise<void>;
+    requestAdmission?: SessionRequestAdmission;
 }>;
 export type RuntimeRequestOptions = Pick<RequestHandlerOptions, "toolApprovalController" | "requestSteering">;
 export type RuntimeRequestHandler = Readonly<{
+    steer?: (requestId: string, input: Readonly<{
+        steerId: string;
+        text: string;
+    }>) => Promise<RequestSteeringAppendResult>;
     handle: (ws: WebSocket, message: RunRequestMessage, options?: RuntimeRequestOptions) => Promise<void>;
 }>;
 export type RuntimeApplication = Readonly<{
     services: RuntimeEnvironmentServices;
     host: RuntimeHost;
     requests: RuntimeRequestHandler;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    subscribeScheduledEvents: (listener: (event: Record<string, unknown>) => void) => () => void;
 }>;
 export type RuntimeDependencies = {
     config: RuntimeConfig;
@@ -33,9 +47,15 @@ export type RuntimeDependencies = {
     events: EventSinkFactory;
     sessionMemoryCompactor: SessionMemoryCompactor;
     longTermMemory: LongTermMemoryService;
+    scheduler?: SchedulerService;
+    startScheduler?: () => Promise<void>;
+    stopScheduler?: () => Promise<void>;
+    requestAdmission?: SessionRequestAdmission;
+};
+export type RuntimeDependencyOverrides = Partial<Omit<RuntimeDependencies, "config" | "scheduler" | "startScheduler" | "stopScheduler" | "requestAdmission">>;
+export type RuntimeApplicationOverrides = RuntimeDependencyOverrides & {
+    scheduledRequestOptions?: (run: SchedulerRun) => RuntimeRequestOptions;
 };
-export type RuntimeDependencyOverrides = Partial<Omit<RuntimeDependencies, "config">>;
-export type RuntimeApplicationOverrides = RuntimeDependencyOverrides;
 export declare function createRuntimeApplication(config?: RuntimeConfig, overrides?: RuntimeApplicationOverrides): RuntimeApplication;
 export declare function createRuntimeRequestHandler(services: RuntimeEnvironmentServices): RuntimeRequestHandler;
 export declare function createDefaultRuntimeDependencies(config?: RuntimeConfig, overrides?: RuntimeDependencyOverrides): RuntimeDependencies;

package/dist/src/runtime/composition.js

@@ -1,21 +1,9 @@
-import { createBoundRuntimeRequestHandler, createDefaultAttachmentStore, createDefaultEventSinkFactory, createDefaultModelGatewayClient, createDefaultLongTermMemoryService, createDefaultRuntimeHost, createDefaultSessionStore, createDefaultToolRegistry, } from "./default-adapters.js";
+import { createBoundRuntimeRequestHandler, createDefaultRuntimeHost, } from "./default-adapters.js";
+import { createRuntimeEnvironment } from "./runtime-environment.js";
 import { loadRuntimeConfig } from "./config.js";
-import { createModelSessionMemoryCompactor, } from "./context/session-memory/index.js";
 export function createRuntimeApplication(config = loadRuntimeConfig(), overrides = {}) {
-    const tools = overrides.tools ?? createDefaultToolRegistry(config);
-    const models = overrides.models ?? createDefaultModelGatewayClient(config);
-    const services = Object.freeze({
-        config,
-        sessions: overrides.sessions ?? createDefaultSessionStore(config),
-        attachments: overrides.attachments ?? createDefaultAttachmentStore(config),
-        tools,
-        models,
-        events: overrides.events ?? createDefaultEventSinkFactory(config),
-        sessionMemoryCompactor: overrides.sessionMemoryCompactor ?? createModelSessionMemoryCompactor(),
-        longTermMemory: overrides.longTermMemory ??
-            createDefaultLongTermMemoryService(config, models),
-    });
-    const requests = createRuntimeRequestHandler(services);
+    const environment = createRuntimeEnvironment(config, overrides);
+    const { services, requests } = environment;
     const host = overrides.host ??
         createDefaultRuntimeHost(config, {
             runtimeId: config.runtimeId,
@@ -25,7 +13,14 @@ export function createRuntimeApplication(config = loadRuntimeConfig(), overrides
             requestHandler: requests,
             requestHandlerFactory: createRuntimeRequestHandler,
         });
-    return Object.freeze({ services, host, requests });
+    return Object.freeze({
+        services,
+        host,
+        requests,
+        start: environment.start,
+        stop: environment.stop,
+        subscribeScheduledEvents: environment.subscribeScheduledEvents,
+    });
 }
 export function createRuntimeRequestHandler(services) {
     return createBoundRuntimeRequestHandler(services);

package/dist/src/runtime/config/environment-paths.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeEnvironmentProfileSelection } from "./environment.js";
+import type { RuntimeConfigFile, RuntimeConfigOptions } from "./types.js";
+/** Resolves inherited bases once so every environment-owned adapter shares the namespace. */
+export declare function resolveEnvironmentRuntimeDirectory(params: {
+    rootDir: string;
+    env: RuntimeConfigOptions["env"];
+    config: RuntimeConfigFile;
+    configPath: string;
+    selection: RuntimeEnvironmentProfileSelection;
+}): string;

package/dist/src/runtime/config/environment-paths.js

@@ -0,0 +1,31 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { requireLegacyRuntimeStorageAssignment } from "./environment-storage.js";
+import { DEFAULT_RUNTIME_STATE_DIR } from "./layout.js";
+import { readFirstString, readNestedConfigString, resolveRuntimePath, } from "./utils.js";
+/** Resolves inherited bases once so every environment-owned adapter shares the namespace. */
+export function resolveEnvironmentRuntimeDirectory(params) {
+    const override = readFirstString(params.env ?? {}, ["LLM_RUNTIME_DIR"]);
+    const profileDirectory = readNestedConfigString(params.selection.profilePaths, "runtimeDir");
+    const baseDirectory = readNestedConfigString(params.selection.basePaths, "runtimeDir");
+    const directory = resolveRuntimePath(params.rootDir, override ?? profileDirectory ?? baseDirectory ?? DEFAULT_RUNTIME_STATE_DIR);
+    if (!params.selection.profileId)
+        return directory;
+    if (usesExplicitEnvironmentDirectory(override, profileDirectory))
+        return directory;
+    requireLegacyRuntimeStorageAssignment({
+        rootDir: params.rootDir,
+        baseDir: directory,
+        config: params.config,
+        configPath: params.configPath,
+        environmentOverride: override !== undefined,
+    });
+    // Hash only the stable ID: safe for arbitrary IDs and case-insensitive filesystems.
+    const namespace = createHash("sha256")
+        .update(params.selection.profileId)
+        .digest("hex");
+    return join(directory, "environments", namespace);
+}
+function usesExplicitEnvironmentDirectory(override, profileDirectory) {
+    return override === undefined && profileDirectory !== undefined;
+}

package/dist/src/runtime/config/environment-storage.d.ts

@@ -0,0 +1,9 @@
+import type { RuntimeConfigFile } from "./types.js";
+/** Old shared state has no complete environment attribution; never move or hide it. */
+export declare function requireLegacyRuntimeStorageAssignment(params: {
+    rootDir: string;
+    baseDir: string;
+    config: RuntimeConfigFile;
+    configPath: string;
+    environmentOverride: boolean;
+}): void;

package/dist/src/runtime/config/environment-storage.js

@@ -0,0 +1,65 @@
+import { lstatSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isRecord, readNestedConfigString } from "./utils.js";
+import { RuntimeConfigValidationError } from "./validation/runtime-config-validation-contract.js";
+const LEGACY_RUNTIME_DIRECTORIES = [
+    "scheduler",
+    "sessions",
+    "attachments",
+    "long-term-memory",
+    "plugins",
+    "memory",
+    "logs",
+    "local-host",
+];
+/** Old shared state has no complete environment attribution; never move or hide it. */
+export function requireLegacyRuntimeStorageAssignment(params) {
+    const populated = LEGACY_RUNTIME_DIRECTORIES.filter((directory) => hasStoredEntries(join(params.baseDir, directory)));
+    if (populated.length === 0)
+        return;
+    if (hasExplicitLegacyOwner(params))
+        return;
+    throw new RuntimeConfigValidationError(params.configPath, [
+        `runtime_environment_storage_assignment_required: Existing runtime state at ${params.baseDir} (${populated.join(", ")}) needs an explicit environment owner. Set exactly one environment.profiles.<id>.paths.runtimeDir to this directory, preserving any explicit session, attachment and trace paths. Remove a shared LLM_RUNTIME_DIR override before assigning ownership. No data was moved and no new environment directory was created.`,
+    ]);
+}
+function hasStoredEntries(path) {
+    try {
+        const entry = lstatSync(path);
+        if (!entry.isDirectory())
+            return true;
+        return readdirSync(path).length > 0;
+    }
+    catch (error) {
+        if (isMissingPath(error))
+            return false;
+        throw error;
+    }
+}
+function isMissingPath(error) {
+    return isRecord(error) && error.code === "ENOENT";
+}
+function hasExplicitLegacyOwner(params) {
+    if (params.environmentOverride)
+        return false;
+    if (!isRecord(params.config.environment))
+        return false;
+    const profiles = params.config.environment.profiles;
+    if (!isRecord(profiles))
+        return false;
+    const owners = Object.values(profiles).filter((profile) => {
+        if (!isRecord(profile))
+            return false;
+        const path = readNestedConfigString(profile.paths, "runtimeDir");
+        if (!path)
+            return false;
+        return sameRuntimeDirectory(resolve(params.rootDir, path), params.baseDir);
+    });
+    return owners.length === 1;
+}
+function sameRuntimeDirectory(left, right) {
+    if (process.platform === "win32") {
+        return resolve(left).toLowerCase() === resolve(right).toLowerCase();
+    }
+    return resolve(left) === resolve(right);
+}

package/dist/src/runtime/config/fields.js

@@ -1,3 +1,4 @@
+import { DEFAULT_MEMORY_RECALL_CALL_LIMIT } from "../long-term-memory/recall-policy.js";
 import { DEFAULT_MODEL_GATEWAY_URL } from "../../shared/constants.js";
 import { DEFAULT_RUNTIME_AGENT_BRIDGE_URL, DEFAULT_RUNTIME_LOGGING_ENABLED, DEFAULT_RUNTIME_LOG_ROTATION_CONFIG, } from "./constants.js";
 import { DEFAULT_AGENT_WORK_DIR, DEFAULT_RUNTIME_COMPILED_DIR, DEFAULT_RUNTIME_ATTACHMENTS_DIR, DEFAULT_RUNTIME_SESSIONS_DIR, DEFAULT_RUNTIME_SHARED_DIR, DEFAULT_RUNTIME_STATE_DIR, DEFAULT_RUNTIME_TRACE_FILE, DEFAULT_WORKSPACE_SOURCE_DIR, } from "./layout.js";
@@ -263,6 +264,12 @@ export const RUNTIME_CONFIG_SCHEMA_FIELDS = [
         defaultValue: "false",
         description: "Whether bounded memory lifecycle events are visible to clients.",
     },
+    {
+        path: "longTermMemory.maxRecallCallsPerRequest",
+        type: "positive-number",
+        defaultValue: String(DEFAULT_MEMORY_RECALL_CALL_LIMIT),
+        description: "Maximum explicit memory recall calls offered per request; must be a positive safe integer.",
+    },
     {
         path: "longTermMemory.embeddingProfileId",
         type: "non-empty-string",

package/dist/src/runtime/config/long-term-memory.js

@@ -1,7 +1,9 @@
+import { DEFAULT_MEMORY_RECALL_CALL_LIMIT, isMemoryRecallCallLimit, } from "../long-term-memory/recall-policy.js";
 import { isRecord } from "./utils.js";
 export const DEFAULT_LONG_TERM_MEMORY_CONFIG = Object.freeze({
     enabled: false,
     emitClientEvents: false,
+    maxRecallCallsPerRequest: DEFAULT_MEMORY_RECALL_CALL_LIMIT,
 });
 export function buildLongTermMemoryConfig(config) {
     if (!isRecord(config.longTermMemory)) {
@@ -11,6 +13,9 @@ export function buildLongTermMemoryConfig(config) {
     return Object.freeze({
         enabled: config.longTermMemory.enabled === true,
         emitClientEvents: config.longTermMemory.emitClientEvents === true,
+        maxRecallCallsPerRequest: isMemoryRecallCallLimit(config.longTermMemory.maxRecallCallsPerRequest)
+            ? config.longTermMemory.maxRecallCallsPerRequest
+            : DEFAULT_MEMORY_RECALL_CALL_LIMIT,
         ...(embeddingProfileId ? { embeddingProfileId } : {}),
     });
 }
@@ -26,6 +31,7 @@ export function validateLongTermMemoryConfig(params) {
     validateOptionalBoolean(params.issues, params.value, "enabled");
     validateOptionalBoolean(params.issues, params.value, "emitClientEvents");
     validateOptionalProfileId(params.issues, params.value);
+    validateOptionalMemoryRecallLimit(params.issues, params.value);
     validateEnabledProfileBinding(params);
 }
 function rejectUnsupportedKeys(issues, config) {
@@ -33,6 +39,7 @@ function rejectUnsupportedKeys(issues, config) {
         "enabled",
         "emitClientEvents",
         "embeddingProfileId",
+        "maxRecallCallsPerRequest",
     ]);
     for (const key of Object.keys(config)) {
         if (!supported.has(key)) {
@@ -40,6 +47,14 @@ function rejectUnsupportedKeys(issues, config) {
         }
     }
 }
+function validateOptionalMemoryRecallLimit(issues, config) {
+    const value = config.maxRecallCallsPerRequest;
+    if (value === undefined)
+        return;
+    if (isMemoryRecallCallLimit(value))
+        return;
+    issues.push("longTermMemory.maxRecallCallsPerRequest must be a positive safe integer");
+}
 function validateOptionalBoolean(issues, config, key) {
     if (config[key] !== undefined && typeof config[key] !== "boolean") {
         issues.push(`longTermMemory.${key} must be a boolean`);

package/dist/src/runtime/config/schema.js

@@ -1,3 +1,4 @@
+import { DEFAULT_MEMORY_RECALL_CALL_LIMIT } from "../long-term-memory/recall-policy.js";
 import { PATH_CONFIG_FIELDS, STRING_CONFIG_FIELDS, TIMEOUT_CONFIG_FIELDS, } from "./fields.js";
 import { DEFAULT_RUNTIME_LOGGING_ENABLED, DEFAULT_RUNTIME_LOG_ROTATION_CONFIG, } from "./constants.js";
 import { DEFAULT_REQUEST_EXECUTION_POLICY_ID, REQUEST_EXECUTION_POLICY_IDS, } from "./model-execution-policy.js";
@@ -167,6 +168,13 @@ function longTermMemorySchema() {
         properties: {
             enabled: { type: "boolean", default: false },
             emitClientEvents: { type: "boolean", default: false },
+            maxRecallCallsPerRequest: {
+                type: "integer",
+                minimum: 1,
+                maximum: Number.MAX_SAFE_INTEGER,
+                default: DEFAULT_MEMORY_RECALL_CALL_LIMIT,
+                description: "Maximum explicit memory recall calls offered per request.",
+            },
             embeddingProfileId: {
                 type: "string",
                 minLength: 1,

package/dist/src/runtime/config.js

@@ -6,11 +6,12 @@ import { buildLongTermMemoryConfig } from "./config/long-term-memory.js";
 import { DEFAULT_RUNTIME_AGENT_BRIDGE_URL, DEFAULT_RUNTIME_CONFIG_FILE, } from "./config/constants.js";
 import { validateEffectiveRuntimeModelConfig } from "./config/effective-model-config-validation.js";
 import { resolveRuntimeEnvironmentProfileSelection } from "./config/environment.js";
+import { resolveEnvironmentRuntimeDirectory } from "./config/environment-paths.js";
 import { RUNTIME_CONFIG_SCHEMA_FIELDS } from "./config/fields.js";
 import { loadRuntimeConfigFileWithMeta } from "./config/loader.js";
 import { resolveRequestRunnerConfigReference } from "./config/request-runner-config.js";
 import { loadRequestRunnerConfig } from "./config/runner/loader.js";
-import { DEFAULT_RUNTIME_COMPILED_DIR, DEFAULT_RUNTIME_SHARED_DIR, DEFAULT_AGENT_WORK_DIR, DEFAULT_RUNTIME_STATE_DIR, DEFAULT_WORKSPACE_SOURCE_DIR, RUNTIME_ATTACHMENTS_DIR_NAME, RUNTIME_LOGS_DIR_NAME, RUNTIME_SESSIONS_DIR_NAME, } from "./config/layout.js";
+import { DEFAULT_RUNTIME_COMPILED_DIR, DEFAULT_RUNTIME_SHARED_DIR, DEFAULT_AGENT_WORK_DIR, DEFAULT_WORKSPACE_SOURCE_DIR, RUNTIME_ATTACHMENTS_DIR_NAME, RUNTIME_LOGS_DIR_NAME, RUNTIME_SESSIONS_DIR_NAME, } from "./config/layout.js";
 import { createRuntimeConfigJsonSchema, RUNTIME_CONFIG_JSON_SCHEMA, } from "./config/schema.js";
 import { readConfigPositiveInt, readConfigString, readFirstString, readNestedConfigString, readPositiveInt, resolveRuntimePath, } from "./config/utils.js";
 import { RuntimeConfigValidationError } from "./config/validation.js";
@@ -54,10 +55,13 @@ export function loadRuntimeConfig(options = {}) {
         profileId: options.profileId,
     });
     const basePaths = profileSelection.basePaths ?? fileConfig.paths;
-    const runtimeDir = resolveRuntimePath(rootDir, readFirstString(env, ["LLM_RUNTIME_DIR"]) ??
-        readNestedConfigString(profileSelection.profilePaths, "runtimeDir") ??
-        readNestedConfigString(basePaths, "runtimeDir") ??
-        DEFAULT_RUNTIME_STATE_DIR);
+    const runtimeDir = resolveEnvironmentRuntimeDirectory({
+        rootDir,
+        env,
+        config: fileConfig,
+        configPath: loadedConfig.path,
+        selection: profileSelection,
+    });
     const agentWorkDir = resolveRuntimePath(rootDir, readFirstString(env, ["LLM_RUNTIME_AGENT_WORK_DIR"]) ??
         readNestedConfigString(profileSelection.profilePaths, "agentWorkDir") ??
         readNestedConfigString(basePaths, "agentWorkDir") ??

package/dist/src/runtime/context/scheduled-execution-context.d.ts

@@ -0,0 +1,10 @@
+import type { ChatMessage } from "../../model-gateway/types.js";
+import type { RequestExecutionSeed } from "../request/contracts.js";
+export declare const SCHEDULED_EXECUTION_CONTEXT_KIND: "runtime_scheduled_execution_v1";
+type ScheduledExecutionPhase = "decision" | "response";
+export declare function projectScheduledExecutionContext(request: Pick<RequestExecutionSeed, "requestId" | "scheduledExecution">, instructions: string, phase: ScheduledExecutionPhase): Readonly<{
+    instructions: string;
+    referenceMessages: readonly ChatMessage[];
+}>;
+export declare function isScheduledExecutionContextMessage(message: ChatMessage): boolean;
+export {};

package/dist/src/runtime/context/scheduled-execution-context.js

@@ -0,0 +1,52 @@
+export const SCHEDULED_EXECUTION_CONTEXT_KIND = "runtime_scheduled_execution_v1";
+const SCHEDULED_EXECUTION_CONTEXT_POLICY = [
+    "runtime_scheduled_execution_v1 is trusted request-local state from the runtime scheduler, bound to this request and Job run. The current user message contains the saved task to execute now.",
+    "This Job run has already been triggered; do not reinterpret its saved task as a new request to create or configure this schedule.",
+    "Preserve who performs the requested action: a reminder asks you to notify the user; a task delegated to you asks you to perform the assigned work. Execution origin does not change the saved task or its actor.",
+    "This state does not add user intent, grant additional authorization, or establish completion. It is not a user fact or a memory candidate.",
+].join("\n");
+const SCHEDULED_EXECUTION_PHASE_POLICY = Object.freeze({
+    decision: "Choose the action needed for this current run under the saved task and existing authority; the origin does not select a capability or require an external action for a reminder notification.",
+    response: "Present the requested outcome of this current run, preserving the task's actor. Do not claim you were asked to perform an action that the saved task asks the user to perform.",
+});
+export function projectScheduledExecutionContext(request, instructions, phase) {
+    const reference = request.scheduledExecution;
+    if (!hasScheduledExecutionOrigin(reference)) {
+        return Object.freeze({
+            instructions,
+            referenceMessages: Object.freeze([]),
+        });
+    }
+    const capsule = Object.freeze({
+        kind: SCHEDULED_EXECUTION_CONTEXT_KIND,
+        authority: "runtime_scheduler",
+        purpose: "execute_saved_task_for_current_run",
+        requestId: request.requestId,
+        jobId: reference.jobId,
+        runId: reference.runId,
+        scheduledAt: reference.scheduledAt,
+        triggerType: reference.triggerType,
+        presenceEffect: "execution_origin_only_not_new_intent_authorization_or_completion",
+    });
+    return Object.freeze({
+        instructions: [
+            instructions,
+            SCHEDULED_EXECUTION_CONTEXT_POLICY,
+            SCHEDULED_EXECUTION_PHASE_POLICY[phase],
+        ].join("\n\n"),
+        referenceMessages: Object.freeze([
+            Object.freeze({
+                role: "system",
+                content: JSON.stringify(capsule),
+            }),
+        ]),
+    });
+}
+function hasScheduledExecutionOrigin(reference) {
+    return reference !== undefined;
+}
+export function isScheduledExecutionContextMessage(message) {
+    if (message.role !== "system")
+        return false;
+    return message.content.startsWith(`{"kind":${JSON.stringify(SCHEDULED_EXECUTION_CONTEXT_KIND)},`);
+}