@abot-ai/runtime 1.2.0 → 1.3.0

package/plugins/web/src/index.cjs

@@ -246,11 +246,24 @@ function failureFromError(error, options) {
   });
 }
 
-// plugins/web/source/errors.ts
-var WebPluginError = class extends Error {
+// src/shared/public-http/errors.ts
+var PublicHttpError = class extends Error {
   code;
   constructor(code, message) {
     super(message);
+    this.name = "PublicHttpError";
+    this.code = code;
+  }
+};
+function isPublicHttpError(error) {
+  return error instanceof PublicHttpError;
+}
+
+// plugins/web/source/errors.ts
+var WebPluginError = class extends PublicHttpError {
+  code;
+  constructor(code, message) {
+    super(code, message);
     this.name = "WebPluginError";
     this.code = code;
   }
@@ -258,6 +271,13 @@ var WebPluginError = class extends Error {
 function isWebPluginError(error) {
   return error instanceof WebPluginError;
 }
+function rethrowWebPluginError(error) {
+  if (error instanceof WebPluginError) throw error;
+  if (isPublicHttpError(error)) {
+    throw new WebPluginError(error.code, error.message);
+  }
+  throw error;
+}
 
 // plugins/web/source/concurrency.ts
 async function mapWithConcurrency(values, concurrency, operation) {
@@ -280,8 +300,19 @@ async function mapWithConcurrency(values, concurrency, operation) {
   return Object.freeze(results);
 }
 
+// src/shared/public-http/limits.ts
+var PUBLIC_HTTP_LIMITS = Object.freeze({
+  httpConcurrency: 6,
+  httpQueueLimit: 64,
+  redirects: 3,
+  responseBytes: 512 * 1024,
+  requestTimeoutMs: 1e4,
+  responseHeaderBytes: 32 * 1024
+});
+
 // plugins/web/source/limits.ts
 var WEB_LIMITS = Object.freeze({
+  ...PUBLIC_HTTP_LIMITS,
   queryMaxChars: 400,
   queryMaxWords: 50,
   searchQueries: 5,
@@ -292,14 +323,9 @@ var WEB_LIMITS = Object.freeze({
   targetReadableSources: 3,
   fetchUrls: 3,
   fetchConcurrency: 3,
-  httpConcurrency: 6,
-  httpQueueLimit: 64,
-  redirects: 3,
-  responseBytes: 512 * 1024,
   outputChars: 16e3,
   pageOutputChars: 12e3,
   sourceOutputChars: 3e3,
-  requestTimeoutMs: 1e4,
   searchTotalTimeoutMs: 3e4,
   outputBytes: 48 * 1024,
   upstreamUrlChars: 4096,
@@ -307,8 +333,7 @@ var WEB_LIMITS = Object.freeze({
   upstreamTitleChars: 180,
   upstreamSnippetChars: 800,
   retryAttempts: 2,
-  retryBaseMs: 750,
-  responseHeaderBytes: 32 * 1024
+  retryBaseMs: 750
 });
 
 // plugins/web/source/content.ts
@@ -832,7 +857,7 @@ function createWebFetchService(httpClient) {
   });
 }
 
-// plugins/web/source/network-policy.ts
+// src/shared/public-http/network-policy.ts
 var import_promises = require("node:dns/promises");
 var import_node_net = require("node:net");
 function ipv4Value(address) {
@@ -935,33 +960,33 @@ function parsePublicHttpUrl(rawUrl) {
   try {
     parsed = new URL(rawUrl);
   } catch {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_target_invalid",
       "A valid absolute URL is required."
     );
   }
   if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_target_invalid",
       "Only http and https URLs are supported."
     );
   }
   if (parsed.username || parsed.password) {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_target_invalid",
       "URLs containing credentials are not supported."
     );
   }
   const hostname = normalizeHostname(parsed.hostname);
   if (!hostname || isBlockedHostname(hostname)) {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_target_not_public",
       "Only public Internet targets are allowed."
     );
   }
   const family = (0, import_node_net.isIP)(hostname);
   if (family === 4 && !isPublicIpv4(hostname) || family === 6 && !isPublicIpv6(hostname)) {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_target_not_public",
       "Only public Internet targets are allowed."
     );
@@ -980,7 +1005,7 @@ var resolveHostAddresses = async (hostname) => {
   try {
     resolved = await (0, import_promises.lookup)(normalized, { all: true, verbatim: true });
   } catch {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_target_unresolvable",
       "The public target hostname could not be resolved."
     );
@@ -991,7 +1016,7 @@ var resolveHostAddresses = async (hostname) => {
     (entry) => Object.freeze({ address: entry.address, family: entry.family })
   );
   if (addresses.length === 0) {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_target_unresolvable",
       "The public target hostname could not be resolved."
     );
@@ -1002,7 +1027,7 @@ async function resolvePublicTarget(url, resolver = resolveHostAddresses) {
   const hostname = normalizeHostname(url.hostname);
   const addresses = await resolver(hostname);
   if (addresses.length === 0 || addresses.some((entry) => !isPublicAddress(entry))) {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_target_not_public",
       "Only public Internet targets are allowed."
     );
@@ -1010,6 +1035,15 @@ async function resolvePublicTarget(url, resolver = resolveHostAddresses) {
   return addresses[0];
 }
 
+// plugins/web/source/network-policy.ts
+function parsePublicHttpUrl2(rawUrl) {
+  try {
+    return parsePublicHttpUrl(rawUrl);
+  } catch (error) {
+    return rethrowWebPluginError(error);
+  }
+}
+
 // plugins/web/source/parameters.ts
 var SEARCH_REPAIR_HINT = "Do not retry this call unchanged. Provide query for one non-empty web query, or queries for up to five distinct non-empty web queries.";
 var FETCH_REPAIR_HINT = "Do not retry this call unchanged. Provide url for one absolute public http(s) URL, or urls for up to three such URLs.";
@@ -1069,7 +1103,7 @@ function parseFetchParams(params) {
     maxItems: WEB_LIMITS.fetchUrls,
     maxItemLength: WEB_LIMITS.upstreamUrlChars
   });
-  for (const url of urls) parsePublicHttpUrl(url);
+  for (const url of urls) parsePublicHttpUrl2(url);
   return urls;
 }
 function validate(parse, error, repairHint) {
@@ -1106,11 +1140,11 @@ var webFetchCallAdapter = Object.freeze({
   validateCall: ({ params }) => adapterValidation(validateFetchParams(params))
 });
 
-// plugins/web/source/deadline.ts
+// src/shared/public-http/deadline.ts
 function remainingTime(deadline) {
   const remaining = deadline - Date.now();
   if (remaining <= 0) {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_request_timed_out",
       "The upstream web request timed out."
     );
@@ -1120,7 +1154,10 @@ function remainingTime(deadline) {
 function withinDeadline(promise, deadline, abortSignal) {
   if (abortSignal?.aborted) {
     return Promise.reject(
-      new WebPluginError("web_request_aborted", "The web request was aborted.")
+      new PublicHttpError(
+        "web_request_aborted",
+        "The web request was aborted."
+      )
     );
   }
   return new Promise((resolve, reject) => {
@@ -1134,7 +1171,7 @@ function withinDeadline(promise, deadline, abortSignal) {
     };
     const onAbort = () => finish(
       () => reject(
-        new WebPluginError(
+        new PublicHttpError(
           "web_request_aborted",
           "The web request was aborted."
         )
@@ -1143,7 +1180,7 @@ function withinDeadline(promise, deadline, abortSignal) {
     const timeout = setTimeout(
       () => finish(
         () => reject(
-          new WebPluginError(
+          new PublicHttpError(
             "web_request_timed_out",
             "The upstream web request timed out."
           )
@@ -1160,7 +1197,7 @@ function withinDeadline(promise, deadline, abortSignal) {
   });
 }
 
-// plugins/web/source/aggregate-gate.ts
+// src/shared/public-http/aggregate-gate.ts
 function createAggregateGate(maxActive, maxQueued) {
   let active = 0;
   const queue = [];
@@ -1173,7 +1210,7 @@ function createAggregateGate(maxActive, maxQueued) {
       }
       if (waiter.abortSignal?.aborted) {
         waiter.reject(
-          new WebPluginError(
+          new PublicHttpError(
             "web_request_aborted",
             "The web request was aborted."
           )
@@ -1182,7 +1219,7 @@ function createAggregateGate(maxActive, maxQueued) {
       }
       if (waiter.deadline <= Date.now()) {
         waiter.reject(
-          new WebPluginError(
+          new PublicHttpError(
             "web_request_timed_out",
             "The upstream web request timed out."
           )
@@ -1202,7 +1239,7 @@ function createAggregateGate(maxActive, maxQueued) {
   const acquire = (deadline, abortSignal) => {
     if (abortSignal?.aborted) {
       return Promise.reject(
-        new WebPluginError(
+        new PublicHttpError(
           "web_request_aborted",
           "The web request was aborted."
         )
@@ -1220,7 +1257,7 @@ function createAggregateGate(maxActive, maxQueued) {
     }
     if (queue.length >= maxQueued) {
       return Promise.reject(
-        new WebPluginError(
+        new PublicHttpError(
           "web_request_capacity_exceeded",
           "The web client is at its bounded request capacity."
         )
@@ -1246,14 +1283,14 @@ function createAggregateGate(maxActive, maxQueued) {
         reject(error);
       };
       waiter.onAbort = () => fail(
-        new WebPluginError(
+        new PublicHttpError(
           "web_request_aborted",
           "The web request was aborted."
         )
       );
       waiter.timeout = setTimeout(
         () => fail(
-          new WebPluginError(
+          new PublicHttpError(
             "web_request_timed_out",
             "The upstream web request timed out."
           )
@@ -1275,7 +1312,7 @@ function createAggregateGate(maxActive, maxQueued) {
   });
 }
 
-// plugins/web/source/request-hop.ts
+// src/shared/public-http/request-hop.ts
 var import_node_http = require("node:http");
 var import_node_https = require("node:https");
 function buildPinnedLookup(address) {
@@ -1335,7 +1372,7 @@ function readBoundedBody(response, maxBytes) {
       if (settled) return;
       settled = true;
       reject(
-        new WebPluginError(
+        new PublicHttpError(
           "web_response_invalid",
           "The upstream response ended before completion."
         )
@@ -1345,7 +1382,7 @@ function readBoundedBody(response, maxBytes) {
 }
 var requestPinnedHop = async (params) => {
   if (params.abortSignal?.aborted) {
-    throw new WebPluginError(
+    throw new PublicHttpError(
       "web_request_aborted",
       "The web request was aborted."
     );
@@ -1362,7 +1399,7 @@ var requestPinnedHop = async (params) => {
       headers: params.headers,
       lookup: buildPinnedLookup(params.address),
       agent: false,
-      maxHeaderSize: WEB_LIMITS.responseHeaderBytes
+      maxHeaderSize: PUBLIC_HTTP_LIMITS.responseHeaderBytes
     };
     const requestFunction = params.url.protocol === "https:" ? import_node_https.request : import_node_http.request;
     const request = requestFunction(requestOptions, async (response) => {
@@ -1389,7 +1426,7 @@ var requestPinnedHop = async (params) => {
     const timeout = setTimeout(() => {
       timedOut = true;
       request.destroy(
-        new WebPluginError(
+        new PublicHttpError(
           "web_request_timed_out",
           "The upstream web request timed out."
         )
@@ -1397,7 +1434,7 @@ var requestPinnedHop = async (params) => {
     }, params.timeoutMs);
     timeout.unref?.();
     const onAbort = () => request.destroy(
-      new WebPluginError(
+      new PublicHttpError(
         "web_request_aborted",
         "The web request was aborted."
       )
@@ -1406,18 +1443,18 @@ var requestPinnedHop = async (params) => {
     request.once("error", (error) => {
       if (settled) return;
       settled = true;
-      if (isWebPluginError(error)) {
+      if (isPublicHttpError(error)) {
         reject(error);
       } else if (timedOut) {
         reject(
-          new WebPluginError(
+          new PublicHttpError(
             "web_request_timed_out",
             "The upstream web request timed out."
           )
         );
       } else {
         reject(
-          new WebPluginError(
+          new PublicHttpError(
             "web_response_invalid",
             "The upstream web request failed."
           )
@@ -1432,7 +1469,7 @@ var requestPinnedHop = async (params) => {
   });
 };
 
-// plugins/web/source/public-http.ts
+// src/shared/public-http/public-http.ts
 var REDIRECT_STATUSES = /* @__PURE__ */ new Set([301, 302, 303, 307, 308]);
 function canFollowHttpRedirect(request, status) {
   if (request.followRedirects === false) return false;
@@ -1443,9 +1480,9 @@ function redirectLocation(response) {
   return Array.isArray(raw) ? raw[0] : raw;
 }
 function validateBounds(request) {
-  const maxBytes = request.maxBytes ?? WEB_LIMITS.responseBytes;
-  const maxRedirects = request.maxRedirects ?? WEB_LIMITS.redirects;
-  const timeoutMs = request.timeoutMs ?? WEB_LIMITS.requestTimeoutMs;
+  const maxBytes = request.maxBytes ?? PUBLIC_HTTP_LIMITS.responseBytes;
+  const maxRedirects = request.maxRedirects ?? PUBLIC_HTTP_LIMITS.redirects;
+  const timeoutMs = request.timeoutMs ?? PUBLIC_HTTP_LIMITS.requestTimeoutMs;
   if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
     throw new RangeError("maxBytes must be a positive safe integer");
   }
@@ -1461,8 +1498,8 @@ function createPublicHttpClient(dependencies = {}) {
   const resolveHost = dependencies.resolveHost;
   const requestHop = dependencies.requestHop ?? requestPinnedHop;
   const gate = createAggregateGate(
-    WEB_LIMITS.httpConcurrency,
-    WEB_LIMITS.httpQueueLimit
+    PUBLIC_HTTP_LIMITS.httpConcurrency,
+    PUBLIC_HTTP_LIMITS.httpQueueLimit
   );
   return Object.freeze({
     async get(request) {
@@ -1502,13 +1539,13 @@ function createPublicHttpClient(dependencies = {}) {
         }
         const location = redirectLocation(response);
         if (!location) {
-          throw new WebPluginError(
+          throw new PublicHttpError(
             "web_redirect_invalid",
             "The upstream redirect did not provide a valid destination."
           );
         }
         if (redirectCount >= bounds.maxRedirects) {
-          throw new WebPluginError(
+          throw new PublicHttpError(
             "web_redirect_limit_exceeded",
             "The web request exceeded the redirect limit."
           );
@@ -1516,8 +1553,8 @@ function createPublicHttpClient(dependencies = {}) {
         try {
           current = parsePublicHttpUrl(new URL(location, current).toString());
         } catch (error) {
-          if (isWebPluginError(error)) throw error;
-          throw new WebPluginError(
+          if (isPublicHttpError(error)) throw error;
+          throw new PublicHttpError(
             "web_redirect_invalid",
             "The upstream redirect did not provide a valid destination."
           );
@@ -1527,6 +1564,20 @@ function createPublicHttpClient(dependencies = {}) {
   });
 }
 
+// plugins/web/source/public-http.ts
+function createPublicHttpClient2(dependencies = {}) {
+  const client = createPublicHttpClient(dependencies);
+  return Object.freeze({
+    async get(request) {
+      try {
+        return await client.get(request);
+      } catch (error) {
+        return rethrowWebPluginError(error);
+      }
+    }
+  });
+}
+
 // plugins/web/source/research.ts
 function uniqueHits(results) {
   const seen = /* @__PURE__ */ new Set();
@@ -2141,9 +2192,9 @@ function readSource(value) {
     value.allowedOrigins,
     "allowedOrigins",
     8
-  ).map((origin) => parsePublicHttpUrl(origin).origin);
+  ).map((origin) => parsePublicHttpUrl2(origin).origin);
   const entryUrls = readSourceStrings(value.entryUrls, "entryUrls", 8).map(
-    (url) => parsePublicHttpUrl(url).toString()
+    (url) => parsePublicHttpUrl2(url).toString()
   );
   for (const url of entryUrls) {
     if (url.length > 1024)
@@ -2220,6 +2271,15 @@ function readLightConfig(value) {
   });
 }
 
+// plugins/web/source/deadline.ts
+async function withinDeadline2(promise, deadline, abortSignal) {
+  try {
+    return await withinDeadline(promise, deadline, abortSignal);
+  } catch (error) {
+    return rethrowWebPluginError(error);
+  }
+}
+
 // plugins/web/source/light/crawl/origin-gate.ts
 function createOriginGate(maxActive, maxPerOrigin) {
   const activeOrigins = /* @__PURE__ */ new Map();
@@ -2321,7 +2381,7 @@ function createOriginGate(maxActive, maxPerOrigin) {
       const release = await acquire(origin, deadline, signal);
       const work = Promise.resolve().then(operation);
       void work.then(release, release);
-      return await withinDeadline(work, deadline, signal);
+      return await withinDeadline2(work, deadline, signal);
     }
   });
 }
@@ -2726,7 +2786,7 @@ function createRobotsPolicy(config, admittedOrigins) {
             document.sitemaps.filter((rawUrl) => {
               if (rawUrl.length > WEB_LIMITS.upstreamUrlChars) return false;
               try {
-                return admittedOrigins.has(parsePublicHttpUrl(rawUrl).origin);
+                return admittedOrigins.has(parsePublicHttpUrl2(rawUrl).origin);
               } catch {
                 return false;
               }
@@ -2864,7 +2924,7 @@ function parseLightUrl(raw) {
       "The Light source URL exceeds its length limit."
     );
   }
-  return parsePublicHttpUrl(raw);
+  return parsePublicHttpUrl2(raw);
 }
 function redirectTarget(response, current) {
   const raw = response.headers.location;
@@ -3260,7 +3320,7 @@ function boundedDiscoveryText(value, maxChars = 800) {
 function resolveDiscoveryUrl(value, base) {
   if (!value || value.length > 4096) return void 0;
   try {
-    const parsed = parsePublicHttpUrl(new URL(value.trim(), base).toString());
+    const parsed = parsePublicHttpUrl2(new URL(value.trim(), base).toString());
     parsed.hash = "";
     return parsed.toString();
   } catch {
@@ -3898,7 +3958,7 @@ async function readLightDocument(params) {
 // plugins/web/source/light/search-frontier.ts
 function admittedCandidateUrl(url, source) {
   try {
-    const parsed = parsePublicHttpUrl(url);
+    const parsed = parsePublicHttpUrl2(url);
     if (!source.allowedOrigins.includes(parsed.origin)) return void 0;
     parsed.hash = "";
     if (parsed.toString().length > 1024) return void 0;
@@ -4413,7 +4473,7 @@ function parseBraveHits(body, query) {
     if (!title || !rawUrl) continue;
     let parsed;
     try {
-      parsed = parsePublicHttpUrl(rawUrl);
+      parsed = parsePublicHttpUrl2(rawUrl);
     } catch {
       continue;
     }
@@ -4722,7 +4782,7 @@ function failure(error, operation) {
   });
 }
 function createWebPlugin(context, dependencies = {}) {
-  const httpClient = dependencies.httpClient ?? createPublicHttpClient();
+  const httpClient = dependencies.httpClient ?? createPublicHttpClient2();
   const fetchService = createWebFetchService(httpClient);
   const braveApiKey = context.secrets?.get("braveSearchApiKey")?.trim() ?? "";
   const retryBaseMs = readBoundedInteger(context.config?.retryBaseMs, {

package/runtime.config.schema.json

@@ -339,6 +339,13 @@
       "properties": {
         "enabled": { "type": "boolean", "default": false },
         "emitClientEvents": { "type": "boolean", "default": false },
+        "maxRecallCallsPerRequest": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "default": 5,
+          "description": "Maximum explicit memory recall calls offered per request."
+        },
         "embeddingProfileId": {
           "type": "string",
           "minLength": 1,

package/src/runtime/README.md

@@ -46,6 +46,12 @@ The production path is:
    kernel establishes one immutable normalized working directory on the root
    call from the accepted Execution Agent decision; an explicit `null`
    selection resolves to `.`.
+   When long-term memory is enabled, either root contract may instead select
+   `recall_memory`. The kernel invokes the Runtime memory service directly,
+   commits a root-bound passive receipt, and resumes the same root under the
+   existing activation ceiling. Recall neither creates a child nor consumes a
+   capability execution. The bounded projection belongs only to the current
+   root steering version and is reused during terminal response authoring.
 6. Only the canonical root commits the root response. The selected contract
    may use its own presentation step, but the request finalizer, persistence,
    terminal observation, and completion path are shared.
@@ -155,7 +161,7 @@ or model prose.
 
 ## Canonical State
 
-`orchestration/role-calls/` ledger v17 is the sole writer of the request-local call tree
+`orchestration/role-calls/` ledger v18 is the sole writer of the request-local call tree
 and role results. Each call frame records its caller, role, bounded objective,
 depth, status, result reference, and any canonical capability catalog-group
 scope. An authorized root, Planner, or Worker may also record one normalized
@@ -450,6 +456,104 @@ terminal-text behavior.
 
 ## Public Package Boundary
 
+### Scheduler lifecycle
+
+For installed clients, use `createLocalRuntimeApplication(config)` from
+`@abot-ai/runtime/runtime`. It automatically attaches to or creates one local
+environment owner. Web and Bridge use the same managed facade, so requests,
+session deletion and scheduling share admission across processes. Start with
+`await application.start()` and close with `await application.stop()`; closing
+an attached client leaves the owner running. See
+[local ownership and client lifecycle](local-host/README.md).
+
+`createRuntimeApplication` composes one local scheduler and its management
+capability. Call `await application.start()` to load persisted Jobs and begin
+the clock, and `await application.stop()` when shutting down. The local Web
+backend starts all configured environments without waiting for a browser visit.
+Scheduling can also start lazily when its built-in capability is first invoked.
+After shutdown, explicit application or compatibility-host startup can restart
+the same scheduler. Lazy management cannot revive a stopped scheduler. New
+subscribers belong to the restarted lifecycle; old run events cannot cross into
+it, and interrupted work is never retried.
+
+The compatibility `createDefaultRuntimeDependencies(config).host.start()` and
+standalone default host also start their composed scheduler automatically. The
+synchronous handle exposes optional `ready` for asynchronous startup and `stop`
+for both scheduler and Bridge; host requests and optional steering await
+readiness and reject after shutdown. Host adapter overrides that change execution
+or storage rebuild the scheduling graph. An event-only override rebinds future
+scheduled requests while preserving the existing scheduler, admission, session
+guard and subscriptions; running requests keep their captured sink. Starting the
+default host again restores its sink for future schedules. The default-adapters
+facade delegates these
+responsibilities to `runtime-environment`, `runtime-host-environment` and
+`runtime-host-lifecycle`; caller-supplied stores and registries remain injected.
+
+`application.services.scheduler` provides create/list/get/update/pause/resume/
+cancel/runNow and run history. Model calls bind the current conversation and
+model mechanically; the Web page selects an existing conversation and model.
+Each scheduled run enters the ordinary request handler with FULL permissions,
+its saved model, current canonical history, and one persisted trigger message.
+The trigger's immutable `schedule` reference identifies the Job and Run; its
+message content is the exact historical prompt. Provenance comes from an internal
+scheduler option bound to the exact request and session, never from public
+`run_request` fields. Supplied `schedule` fields do not mark ordinary requests as
+scheduled. Scheduled events can be observed
+through `application.subscribeScheduledEvents`. Consumers may supply
+`scheduledRequestOptions` for the existing approval and steering controllers.
+Scheduled terminal events are published once after the handler settles. Success
+requires the correlated assistant reply in canonical session storage; missing or
+failed persistence is published as failure instead of an earlier completion.
+
+Session admission defers scheduled work while ordinary requests are active;
+subsequent ordinary requests wait for a running scheduled reservation. Existing
+ordinary-request concurrency is unchanged when no scheduled reservation exists.
+The composed SessionStore facade serializes mutations and marks deletion intent
+synchronously. It uses the injected backing store but intentionally does not
+preserve that object's identity: all callers must use the composed facade for
+deletion and request persistence to share the lifetime guard.
+
+Session deletion keeps its tombstone even if backing deletion or cleanup fails.
+A later explicit delete retries only failed listeners from the original deletion;
+successful cleanup is not repeated and newly registered listeners are not
+retroactive. Concurrent deletes share the cleanup attempt until all listeners
+settle. Successful physical deletion retains its original result until cleanup
+succeeds, so an explicit retry can finish consumer attachment cleanup. Both
+delete APIs use the backing store's statistics operation; the boolean API projects
+its `deleted` result. The receipt is delivered once, including across API variants.
+Cleanup never revives the session or reruns scheduled work.
+
+See [scheduler ownership and time rules](scheduler/README.md) for persistence,
+offline behavior, cancellation, and local ownership locking. Stopping does not
+drain active model requests or retry interrupted work. This lifecycle does not
+start a separate model loop or alter the Supervisor/Worker/Execution Agent roles.
+
+The conversation-scoped `schedules.list` tool returns at most 100 Jobs per page,
+newest first, without their stored prompts. Pass `nextCursor` as `cursor` to
+continue until it is null; `omittedCount` describes the entries after that page.
+A stale cursor fails explicitly and requires listing from the beginning. This
+passive listing never schedules or executes work; `get` resolves an exact Job ID.
+`get` requests the latest 20 runs from storage before loading their payloads and
+returns that bounded history in chronological order, without pruning older runs.
+
+Creation is projected as six flat operations (`create_timer`, `create_once`,
+`create_interval`, `create_daily`, `create_weekly`, `create_monthly`). Each fixes
+the adapter's `action=create` and schedule kind mechanically and requires only
+its relevant timing fields. Calendar variants require an explicit IANA time zone.
+Missing required timing is rejected before dispatch; model and conversation
+binding remain owned by the active request. Recurrence changes use six matching
+`update_*` operations with complete required timing and fixed action/kind.
+The plain `update` operation edits metadata while retaining the recurrence;
+omitted time zone, model and mode retain their saved values. The scheduling tool
+has 19 operations under the shared 32-operation contract limit. Other management
+operations and the underlying scheduler service keep their existing contracts.
+
+`SchedulerService.listRuns` preserves complete chronological results when no
+query is supplied. Optional cursor/limit queries return bounded newest-first
+records with an exact Job-scoped run cursor. The Web requests one lookahead
+record before owner RPC serialization, returns 50 runs by default (maximum 100),
+and preserves access to older full records.
+
 Stable public subpath exports are:
 
 - `@abot-ai/runtime/runtime`