@abot-ai/runtime 1.2.0 → 1.3.0

package/dist/src/runtime/adapters/registered-tool-normal-invocations/payload/lifecycle.js

@@ -1,5 +1,5 @@
 import { materializeCall } from "../execution/call-binding.js";
-import { buildToolIntentEventMetadata } from "../shared/event-metadata.js";
+import { buildToolExecutorEventMetadata, buildToolIntentEventMetadata, } from "../shared/event-metadata.js";
 import { rejectNormalInvocation } from "../shared/rejection.js";
 import { validatePublicInput } from "./input-preparation.js";
 export function emitNormalInvocationPayloadLifecycle(params) {
@@ -35,8 +35,12 @@ export function prepareNormalInvocationPayloadLifecycle(params) {
     const event = materializePayloadLifecycleEvent(params.input, base);
     return Object.freeze({
         status: "prepared",
-        emit: () => {
-            params.onEvent?.(event.name, event.payload);
+        emit: (executionId, executorIdentity) => {
+            params.onEvent?.(event.name, {
+                ...event.payload,
+                ...buildToolExecutorEventMetadata(executorIdentity),
+                ...(executionId ? { executionId } : {}),
+            });
             return Object.freeze({ status: "emitted" });
         },
     });

package/dist/src/runtime/adapters/registered-tool-normal-invocations/shared/contracts.d.ts

@@ -1,3 +1,4 @@
+import type { ToolEventExecutorIdentity } from "./event-metadata.js";
 import type { RegisteredToolNormalInvocation, ToolActionSummary, ToolExecutionResult, ToolExecutionSharedState, ToolNormalInvocationEffect, ToolNormalInvocationOperation } from "../../../../capabilities/tool-types.js";
 import type { ToolApprovalController, ToolPermissionMode, ToolRegistry } from "../../../ports.js";
 import type { RegisteredToolPayloadContextPlan, RegisteredToolStagedPayloadPlan } from "../../registered-tool-payload-plan.js";
@@ -37,7 +38,14 @@ export type RegisteredToolPreparedNormalInvocation = Readonly<{
     actionFingerprint: string;
     /** Exact validated non-payload controls accepted for this invocation. */
     acceptedControls: Readonly<Record<string, unknown>>;
-    execute(): Promise<RegisteredToolNormalInvocationResult>;
+    /** Client-only terminal event when admission is rejected before execution. */
+    emitRejection(input: Readonly<{
+        executionId: string;
+        executorIdentity: ToolEventExecutorIdentity;
+        errorCode: string;
+    }>): void;
+    /** Canonical execution identity for client lifecycle events only. */
+    execute(executionId?: string, executorIdentity?: ToolEventExecutorIdentity): Promise<RegisteredToolNormalInvocationResult>;
 }>;
 export type RegisteredToolNormalInvocationPreparation = RegisteredToolPreparedNormalInvocation | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolNormalInvocationPayloadLifecyclePhase = "started" | "completed" | "failed";
@@ -46,13 +54,20 @@ export type RegisteredToolNormalInvocationPayloadLifecycleResult = Readonly<{
 }> | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolPreparedNormalInvocationPayloadLifecycle = Readonly<{
     status: "prepared";
-    emit(): Readonly<{
+    /** Canonical execution identity for client lifecycle events only. */
+    emit(executionId?: string, executorIdentity?: ToolEventExecutorIdentity): Readonly<{
         status: "emitted";
     }>;
 }>;
 export type RegisteredToolNormalInvocationPayloadLifecyclePreparation = RegisteredToolPreparedNormalInvocationPayloadLifecycle | RegisteredToolNormalInvocationRejection;
 export type RegisteredToolNormalInvocationExecutor = Readonly<{
     operations: readonly RegisteredToolNormalInvocationProjection[];
+    /** Prepares client-only rejection reporting for a registered source handle. */
+    prepareRejectionEvent(input: Readonly<{
+        handle: RegisteredToolNormalInvocationHandle;
+        controls: Readonly<Record<string, unknown>>;
+        intent?: string;
+    }>): RegisteredToolPreparedNormalInvocation["emitRejection"] | undefined;
     /**
      * Emits the existing client payload lifecycle without exposing the bound
      * tool name or payload parameter to the profile that owns model context.

package/dist/src/runtime/adapters/registered-tool-normal-invocations/shared/event-metadata.d.ts

@@ -1,2 +1,11 @@
 import type { ToolCall, ToolDefinition } from "../../../../capabilities/tool-types.js";
 export declare function buildToolIntentEventMetadata(call: ToolCall, intent: string | undefined, definition?: ToolDefinition): Record<string, unknown> | undefined;
+/** Canonical caller identity used only to attribute client lifecycle events. */
+export type ToolEventExecutorIdentity = Readonly<{
+    callId: string;
+    roleId: string;
+}>;
+export declare function buildToolExecutorEventMetadata(identity: ToolEventExecutorIdentity | undefined): {
+    roleCallId: string;
+    executorRole: string;
+} | undefined;

package/dist/src/runtime/adapters/registered-tool-normal-invocations/shared/event-metadata.js

@@ -8,3 +8,11 @@ export function buildToolIntentEventMetadata(call, intent, definition) {
         intent,
     };
 }
+export function buildToolExecutorEventMetadata(identity) {
+    if (!identity)
+        return undefined;
+    return {
+        roleCallId: identity.callId,
+        executorRole: identity.roleId,
+    };
+}

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

@@ -166,6 +166,11 @@ async function prepareRegisteredToolWorkerCapability(params, input, payloadObser
             selectedTargetReferences,
             rejectedExecution: canonicalRejection,
             payloadObservability,
+            emitRejection: params.executor.prepareRejectionEvent({
+                handle: params.projection.handle,
+                controls: effectiveControls,
+                intent: input.intent,
+            }),
             ...(preparedPayload.body === undefined
                 ? {}
                 : { payload: preparedPayload.body }),
@@ -183,6 +188,11 @@ async function prepareRegisteredToolWorkerCapability(params, input, payloadObser
                 tracePreparedExecutionStarted(params, input, operationId, executionId);
                 const rejectedExecution = executionFreshnessRejection(input.executionFreshness);
                 if (rejectedExecution) {
+                    normalPreparation.emitRejection({
+                        executionId,
+                        executorIdentity: input.call,
+                        errorCode: rejectedExecution.sourceIssueCode,
+                    });
                     return completeRuntimeRejection({
                         params,
                         input,
@@ -192,7 +202,7 @@ async function prepareRegisteredToolWorkerCapability(params, input, payloadObser
                         rejectedExecution,
                     });
                 }
-                const externalResult = await normalPreparation.execute();
+                const externalResult = await normalPreparation.execute(executionId, input.call);
                 const observed = observeExternalResult(externalResult, params.projection.operation.effect, input.call.parentCallId === null);
                 const observedResult = attachTargetReferences(observed.result, selectedTargetReferences);
                 traceRegisteredToolWorkerCapabilityExecutionCompleted(params.diagnostic, operationId, input.call, executionId, observedResult, externalResult.status, {
@@ -235,6 +245,11 @@ function preparedRuntimeRejection(input) {
             try {
                 input.payloadObservability.release(executionId);
                 tracePreparedExecutionStarted(input.params, input.input, input.operationId, executionId);
+                input.emitRejection?.({
+                    executionId,
+                    executorIdentity: input.input.call,
+                    errorCode: input.rejectedExecution.sourceIssueCode,
+                });
                 return completeRuntimeRejection({ ...input, executionId });
             }
             catch (error) {

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

@@ -11,8 +11,8 @@ export function createDeferredPayloadObservability(params) {
             const prepared = params.executor.preparePayloadLifecycle(input);
             if (prepared.status === "rejected")
                 return prepared;
-            deferred.push(() => {
-                prepared.emit();
+            deferred.push((executionId) => {
+                prepared.emit(executionId, params.call);
             });
             return Object.freeze({ status: "emitted" });
         },

package/dist/src/runtime/adapters/scheduled-request-outcome.d.ts

@@ -0,0 +1,11 @@
+import type { SessionStore } from "../ports.js";
+import type { SchedulerRun, SchedulerRunOutcome } from "../scheduler/contracts.js";
+export type ScheduledRequestEvent = Record<string, unknown>;
+export type ScheduledRequestSettlement = Readonly<{
+    outcome: SchedulerRunOutcome;
+    event: ScheduledRequestEvent;
+}>;
+export declare function isScheduledTerminalEvent(event: ScheduledRequestEvent): boolean;
+export declare function failedScheduledRequestOutcome(error: unknown): ScheduledRequestSettlement;
+/** A captured completion is provisional until canonical assistant persistence is proven. */
+export declare function resolveScheduledRequestOutcome(terminal: ScheduledRequestEvent | undefined, sessions: SessionStore, run: SchedulerRun): Promise<ScheduledRequestSettlement>;

package/dist/src/runtime/adapters/scheduled-request-outcome.js

@@ -0,0 +1,41 @@
+export function isScheduledTerminalEvent(event) {
+    return event.type === "completed" || event.type === "failed";
+}
+export function failedScheduledRequestOutcome(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        outcome: { status: "failed", error: message },
+        event: { type: "failed", error: message },
+    };
+}
+/** A captured completion is provisional until canonical assistant persistence is proven. */
+export async function resolveScheduledRequestOutcome(terminal, sessions, run) {
+    if (!terminal)
+        return failedScheduledRequestOutcome("scheduled_request_missing_terminal");
+    if (terminal.type === "failed") {
+        const failure = failedScheduledRequestOutcome(terminal.error ?? "scheduled_request_failed");
+        return { ...failure, event: { ...terminal, ...failure.event } };
+    }
+    try {
+        const session = await sessions.getSessionById(run.sessionId);
+        const result = session?.messages.find((message) => isScheduledAssistantReply(message, run.requestId));
+        if (!result)
+            return failedScheduledRequestOutcome("scheduled_result_not_persisted");
+        return {
+            outcome: {
+                status: "succeeded",
+                resultText: String(terminal.output ?? ""),
+                resultMessageId: result.id,
+            },
+            event: terminal,
+        };
+    }
+    catch (error) {
+        return failedScheduledRequestOutcome(error);
+    }
+}
+function isScheduledAssistantReply(message, requestId) {
+    if (message.role !== "assistant")
+        return false;
+    return message.requestId === requestId;
+}

package/dist/src/runtime/adapters/scheduler-runtime.d.ts

@@ -0,0 +1,19 @@
+import type { RuntimeConfig, SessionStore } from "../ports.js";
+import type { RuntimeRequestHandler, RuntimeRequestOptions } from "../composition.js";
+import type { SchedulerRun } from "../scheduler/contracts.js";
+import type { SessionRequestAdmission } from "../request/session-admission.js";
+import { type ScheduledRequestEvent } from "./scheduled-request-outcome.js";
+export declare function createRuntimeScheduler(options: {
+    config: RuntimeConfig;
+    sessions: SessionStore;
+    admission: SessionRequestAdmission;
+    isDeleted(sessionId: string): boolean;
+    handle: RuntimeRequestHandler["handle"];
+    requestOptions?: (run: SchedulerRun) => RuntimeRequestOptions;
+}): {
+    scheduler: import("../scheduler/contracts.js").SchedulerService;
+    start: () => Promise<void>;
+    ensureStarted(): Promise<void>;
+    stop(): Promise<void>;
+    subscribe(listener: (event: ScheduledRequestEvent) => void): () => void;
+};

package/dist/src/runtime/adapters/scheduler-runtime.js

@@ -0,0 +1,138 @@
+import { join } from "node:path";
+import { createFileSchedulerStore } from "../scheduler/file-store.js";
+import { createSchedulerService } from "../scheduler/scheduler-service.js";
+import { withScheduledExecution } from "../request/scheduled-execution.js";
+import { resolveModelSelection } from "../model/model-selection.js";
+import { failedScheduledRequestOutcome, isScheduledTerminalEvent, resolveScheduledRequestOutcome, } from "./scheduled-request-outcome.js";
+export function createRuntimeScheduler(options) {
+    const listeners = new Set();
+    let startup;
+    let stopped = false;
+    let generation = 0;
+    function canPublishRunEvents(runGeneration) {
+        if (stopped)
+            return false;
+        return runGeneration === generation;
+    }
+    function publish(event, sessionId, runGeneration) {
+        if (!canPublishRunEvents(runGeneration))
+            return;
+        const isDeletedSession = options.isDeleted(sessionId);
+        const isTerminalEvent = isScheduledTerminalEvent(event);
+        if (isDeletedSession && !isTerminalEvent)
+            return;
+        const outbound = isDeletedSession
+            ? { ...event, sessionDeleted: true }
+            : event;
+        for (const listener of [...listeners]) {
+            if (!canPublishRunEvents(runGeneration))
+                return;
+            try {
+                listener(outbound);
+            }
+            catch {
+                /* A view cannot alter execution settlement. */
+            }
+        }
+    }
+    async function execute(job, run) {
+        const runGeneration = generation;
+        const publishForRun = (event) => {
+            publish({
+                ...event,
+                requestId: run.requestId,
+                sessionId: job.sessionId,
+                environment: job.environmentId,
+            }, job.sessionId, runGeneration);
+        };
+        const finish = (settlement) => {
+            publishForRun(settlement.event);
+            return settlement.outcome;
+        };
+        if (options.isDeleted(job.sessionId))
+            return finish(failedScheduledRequestOutcome("session_deleted"));
+        const selection = resolveModelSelection({
+            agentMode: job.agentMode,
+            modelPreference: { profileId: job.modelProfileId, scope: "all" },
+            modelPolicy: options.config.models,
+        });
+        if (selection.execution.primaryProfileId !== job.modelProfileId) {
+            return finish(failedScheduledRequestOutcome("scheduled_model_unavailable"));
+        }
+        let terminal;
+        let acceptingEvents = true;
+        const ws = {
+            send(data) {
+                if (!acceptingEvents)
+                    return;
+                const event = JSON.parse(data);
+                if (event.requestId !== run.requestId)
+                    return;
+                if (isScheduledTerminalEvent(event)) {
+                    terminal = event;
+                    return;
+                }
+                publishForRun(event);
+            },
+        };
+        const message = {
+            type: "run_request",
+            requestId: run.requestId,
+            sessionId: job.sessionId,
+            text: run.prompt,
+            agentMode: job.agentMode,
+            modelPreference: { profileId: job.modelProfileId, scope: "all" },
+            toolPermissionMode: "full_access",
+        };
+        try {
+            await options.handle(ws, message, withScheduledExecution(options.requestOptions?.(run), run));
+        }
+        catch (error) {
+            terminal = failedScheduledRequestOutcome(error).event;
+        }
+        finally {
+            acceptingEvents = false;
+        }
+        return finish(await resolveScheduledRequestOutcome(terminal, options.sessions, run));
+    }
+    const scheduler = createSchedulerService({
+        environmentId: options.config.runtimeId,
+        store: createFileSchedulerStore(join(options.config.paths.runtimeDir, "scheduler")),
+        executor: {
+            tryReserve: (sessionId) => options.admission.tryReserve(sessionId),
+            sessionExists: async (sessionId) => {
+                if (options.isDeleted(sessionId))
+                    return false;
+                return (await options.sessions.getSessionById(sessionId)) !== null;
+            },
+            start: execute,
+        },
+    });
+    function start() {
+        stopped = false;
+        startup ??= scheduler.start();
+        return startup;
+    }
+    return {
+        scheduler,
+        start,
+        ensureStarted() {
+            if (stopped)
+                return Promise.reject(new Error("scheduler_stopped"));
+            return start();
+        },
+        stop() {
+            stopped = true;
+            generation += 1;
+            startup = undefined;
+            listeners.clear();
+            return scheduler.stop();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

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

@@ -0,0 +1,55 @@
+export declare const scheduleCreateOperations: readonly [Readonly<{
+    operationId: string;
+    summary: string;
+    input: import("../../../capabilities/tool-types.js").ToolNormalInvocationInput;
+    selectionControlIds?: readonly string[];
+    fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
+    payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+    approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+}>, Readonly<{
+    operationId: string;
+    summary: string;
+    input: import("../../../capabilities/tool-types.js").ToolNormalInvocationInput;
+    selectionControlIds?: readonly string[];
+    fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
+    payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+    approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+}>, Readonly<{
+    operationId: string;
+    summary: string;
+    input: import("../../../capabilities/tool-types.js").ToolNormalInvocationInput;
+    selectionControlIds?: readonly string[];
+    fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
+    payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+    approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+}>, Readonly<{
+    operationId: string;
+    summary: string;
+    input: import("../../../capabilities/tool-types.js").ToolNormalInvocationInput;
+    selectionControlIds?: readonly string[];
+    fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
+    payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+    approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+}>, Readonly<{
+    operationId: string;
+    summary: string;
+    input: import("../../../capabilities/tool-types.js").ToolNormalInvocationInput;
+    selectionControlIds?: readonly string[];
+    fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
+    payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+    approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+}>, Readonly<{
+    operationId: string;
+    summary: string;
+    input: import("../../../capabilities/tool-types.js").ToolNormalInvocationInput;
+    selectionControlIds?: readonly string[];
+    fixedParams?: Readonly<Record<string, import("../../../capabilities/tool-types.js").ToolNormalInvocationFixedValue>>;
+    payload?: import("../../../capabilities/tool-types.js").ToolNormalInvocationPayload;
+    effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+    approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+}>];

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

@@ -0,0 +1,30 @@
+import { scheduleDetailProperties, scheduleTimingProperties, } from "./tool-input-properties.js";
+function createScheduleOperation(kind, timingSummary, timingFields, requiredTiming = timingFields) {
+    return {
+        operationId: `create_${kind}`,
+        summary: `Schedule a future request in this conversation using the current model. Write prompt as the complete instruction the assistant must execute when this Job runs. For reminders, explicitly ask it to remind the user to act; preserve the exact action and target. For delegated work, retain the work itself. Put timing in the schedule fields and ask for missing timing details before creating. ${timingSummary}`,
+        effect: "mutating",
+        approval: "request_policy",
+        fixedParams: { action: "create", scheduleKind: kind },
+        input: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                ...scheduleDetailProperties,
+                timeZone: scheduleTimingProperties.timeZone,
+                ...Object.fromEntries(timingFields.map((field) => [field, scheduleTimingProperties[field]])),
+            },
+            required: ["title", "prompt", ...requiredTiming],
+        },
+    };
+}
+export const scheduleCreateOperations = [
+    createScheduleOperation("timer", "Run once after delayMs milliseconds.", [
+        "delayMs",
+    ]),
+    createScheduleOperation("once", "Run once at an exact ISO instant in at, including its UTC offset.", ["at"]),
+    createScheduleOperation("interval", "Repeat everyMs milliseconds with optional exact first-run anchorAt ISO instant.", ["everyMs", "anchorAt"], ["everyMs"]),
+    createScheduleOperation("daily", "Run daily at exact HH:mm in at and an explicit IANA timeZone.", ["at"], ["at", "timeZone"]),
+    createScheduleOperation("weekly", "Run on weekdays (Sunday=0) at exact HH:mm in at and an explicit IANA timeZone.", ["at", "weekdays"], ["at", "weekdays", "timeZone"]),
+    createScheduleOperation("monthly", "Run on dayOfMonth at exact HH:mm in at and an explicit IANA timeZone.", ["at", "dayOfMonth"], ["at", "dayOfMonth", "timeZone"]),
+];

package/dist/src/runtime/capabilities/scheduling/create-time-zone.d.ts

@@ -0,0 +1 @@
+export declare function requireCreateCalendarTimeZone(params: Record<string, unknown>): void;

package/dist/src/runtime/capabilities/scheduling/create-time-zone.js

@@ -0,0 +1,11 @@
+export function requireCreateCalendarTimeZone(params) {
+    const isCalendarSchedule = ["daily", "weekly", "monthly"].includes(String(params.scheduleKind));
+    if (!isCalendarSchedule)
+        return;
+    if (typeof params.timeZone !== "string") {
+        throw new Error("schedule_time_zone_required");
+    }
+    if (!params.timeZone.trim()) {
+        throw new Error("schedule_time_zone_required");
+    }
+}

package/dist/src/runtime/capabilities/scheduling/job-list-page.d.ts

@@ -0,0 +1,25 @@
+import type { SchedulerJob } from "../../scheduler/contracts.js";
+/** A bounded, passive projection; cursors bind to exact Jobs in this session. */
+export declare function createSchedulerJobPage(jobs: readonly SchedulerJob[], params: {
+    cursor?: unknown;
+    limit?: unknown;
+}): {
+    jobs: {
+        id: string;
+        environmentId: string;
+        sessionId: string;
+        title: string;
+        modelProfileId: string;
+        agentMode: import("../../../shared/types.js").AgentMode;
+        toolPermissionMode: "full_access";
+        timeZone: string;
+        schedule: import("../../scheduler/contracts.js").SchedulerSchedule;
+        state: import("../../scheduler/contracts.js").SchedulerJobState;
+        createdAt: string;
+        updatedAt: string;
+        nextRunAt: string | null;
+        revision: number;
+    }[];
+    omittedCount: number;
+    nextCursor: string | null;
+};

package/dist/src/runtime/capabilities/scheduling/job-list-page.js

@@ -0,0 +1,40 @@
+/** A bounded, passive projection; cursors bind to exact Jobs in this session. */
+export function createSchedulerJobPage(jobs, params) {
+    const limit = params.limit === undefined ? 100 : params.limit;
+    if (!isSupportedPageLimit(limit))
+        throw new Error("schedule_page_limit_invalid");
+    const ordered = [...jobs].sort(compareNewestJobs);
+    const offset = cursorOffset(ordered, params.cursor);
+    const page = ordered.slice(offset, offset + limit);
+    const omittedCount = Math.max(0, ordered.length - offset - page.length);
+    return {
+        jobs: page.map(({ prompt: _prompt, ...job }) => job),
+        omittedCount,
+        nextCursor: omittedCount > 0 ? page.at(-1).id : null,
+    };
+}
+function isSupportedPageLimit(value) {
+    if (!Number.isSafeInteger(value))
+        return false;
+    if (Number(value) < 1)
+        return false;
+    return Number(value) <= 100;
+}
+function cursorOffset(jobs, cursor) {
+    if (cursor === undefined)
+        return 0;
+    if (typeof cursor !== "string")
+        throw new Error("schedule_cursor_invalid");
+    if (!cursor)
+        throw new Error("schedule_cursor_invalid");
+    const index = jobs.findIndex((job) => job.id === cursor);
+    if (index < 0)
+        throw new Error("schedule_cursor_not_found");
+    return index + 1;
+}
+function compareNewestJobs(left, right) {
+    const created = right.createdAt.localeCompare(left.createdAt);
+    if (created !== 0)
+        return created;
+    return right.id.localeCompare(left.id);
+}

package/dist/src/runtime/capabilities/scheduling/model-validation.d.ts

@@ -0,0 +1,2 @@
+import type { RuntimeConfig } from "../../ports.js";
+export declare function requireAvailableScheduleModel(config: RuntimeConfig, modelProfileId: unknown): void;

package/dist/src/runtime/capabilities/scheduling/model-validation.js

@@ -0,0 +1,15 @@
+import { resolveModelSelection } from "../../model/model-selection.js";
+export function requireAvailableScheduleModel(config, modelProfileId) {
+    if (typeof modelProfileId !== "string") {
+        throw new Error("scheduler_model_required");
+    }
+    const selection = resolveModelSelection({
+        agentMode: "reasoning",
+        modelPreference: { profileId: modelProfileId },
+        modelPolicy: config.models,
+    });
+    const isSelectedScheduleModel = selection.execution.primaryProfileId === modelProfileId;
+    if (!isSelectedScheduleModel) {
+        throw new Error("scheduler_model_unavailable");
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { ToolNormalInvocationContract } from "../../../capabilities/tool-types.js";
+export declare const schedulingToolContract: ToolNormalInvocationContract;

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

@@ -0,0 +1,35 @@
+import { scheduleCreateOperations } from "./create-operations.js";
+import { scheduleUpdateOperations } from "./update-operations.js";
+import { scheduleTextField as text } from "./tool-input-properties.js";
+const identity = { jobId: text(200) };
+function operation(operationId, summary, properties, required, effect) {
+    return {
+        operationId,
+        summary,
+        effect,
+        approval: "request_policy",
+        fixedParams: { action: operationId },
+        input: {
+            type: "object",
+            additionalProperties: false,
+            properties,
+            required,
+        },
+    };
+}
+export const schedulingToolContract = {
+    version: 1,
+    operations: [
+        ...scheduleCreateOperations,
+        operation("list", "List this conversation's schedules newest first, without executing them or exposing their task prompts. Each page has up to 100 Jobs; pass its nextCursor to retrieve the next page until null. A stale cursor requires a fresh list without cursor.", {
+            cursor: text(200),
+            limit: { type: "integer", minimum: 1, maximum: 100 },
+        }, [], "read_only"),
+        operation("get", "Read this conversation's Job and recent run history by exact Job ID.", identity, ["jobId"], "read_only"),
+        ...scheduleUpdateOperations,
+        operation("pause", "Pause future starts of this Job, including its pending occurrence. An already-started run continues.", identity, ["jobId"], "mutating"),
+        operation("resume", "Resume this paused Job from its next future occurrence, without backfill.", identity, ["jobId"], "mutating"),
+        operation("cancel", "Cancel this Job and its pending occurrence. An already-started run continues.", identity, ["jobId"], "mutating"),
+        operation("run_now", "Request one immediate run of this Job; wait if this conversation is busy. Does not change its ordinary recurrence.", identity, ["jobId"], "mutating"),
+    ],
+};

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

@@ -0,0 +1,43 @@
+import type { ToolNormalInvocationPropertyInput } from "../../../capabilities/tool-types.js";
+export declare const scheduleTextField: (maxLength: number) => ToolNormalInvocationPropertyInput;
+export declare const scheduleTimingProperties: {
+    scheduleKind: {
+        type: "string";
+        enum: string[];
+    };
+    at: ToolNormalInvocationPropertyInput;
+    delayMs: {
+        type: "integer";
+        minimum: number;
+        maximum: number;
+    };
+    everyMs: {
+        type: "integer";
+        minimum: number;
+        maximum: number;
+    };
+    anchorAt: ToolNormalInvocationPropertyInput;
+    weekdays: {
+        type: "array";
+        items: {
+            type: "integer";
+            minimum: number;
+            maximum: number;
+        };
+        minItems: number;
+        maxItems: number;
+    };
+    dayOfMonth: {
+        type: "integer";
+        minimum: number;
+        maximum: number;
+    };
+    timeZone: ToolNormalInvocationPropertyInput;
+};
+export declare const scheduleDetailProperties: {
+    title: ToolNormalInvocationPropertyInput;
+    prompt: {
+        type: "string";
+        minLength: number;
+    };
+};