@abot-ai/runtime 1.2.0 → 1.3.0

package/dist/src/sessions/session-service.js

@@ -200,6 +200,7 @@ export class SessionService {
                 taskType: options.taskType,
                 requestId: options.requestId,
                 cronJobId: options.cronJobId,
+                ...(options.schedule ? { schedule: options.schedule } : {}),
                 cronTitle: options.cronTitle,
                 triggerType: options.triggerType,
                 attachments: options.attachments,

package/dist/src/sessions/types.d.ts

@@ -86,6 +86,7 @@ export type SessionListResult = {
     nextCursor: string | null;
 };
 export type SessionSnapshotMessage = {
+    schedule?: import("./schedule-metadata.js").ScheduleMessageReference;
     id: string | number;
     sessionId: string;
     role: SessionMessageRole;
@@ -137,6 +138,7 @@ export type SessionMessageDeleteResult = {
     deletedRequestEvents?: number;
 };
 export type SessionMessage = {
+    schedule?: import("./schedule-metadata.js").ScheduleMessageReference;
     id: string;
     role: SessionMessageRole;
     content: string;

package/dist/src/shared/http-server-shutdown.d.ts

@@ -0,0 +1,4 @@
+import type { Server } from "node:http";
+import type { WebSocketServer } from "ws";
+/** Stops only this server's connections; active work is not drained on shutdown. */
+export declare function closeHttpServerImmediately(server: Server, webSockets?: WebSocketServer): Promise<void>;

package/dist/src/shared/http-server-shutdown.js

@@ -0,0 +1,17 @@
+/** Stops only this server's connections; active work is not drained on shutdown. */
+export function closeHttpServerImmediately(server, webSockets) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+        // Stop accepting first: a connection cannot arrive between the sweep and close.
+        server.closeAllConnections();
+        webSockets?.close();
+        for (const client of webSockets?.clients ?? [])
+            client.terminate();
+    });
+}

package/dist/src/shared/public-http/aggregate-gate.d.ts

@@ -0,0 +1,3 @@
+export declare function createAggregateGate(maxActive: number, maxQueued: number): Readonly<{
+    run<T>(operation: () => Promise<T>, deadline: number, abortSignal?: AbortSignal): Promise<T>;
+}>;

package/dist/src/shared/public-http/aggregate-gate.js

@@ -0,0 +1,87 @@
+import { remainingTime, withinDeadline } from "./deadline.js";
+import { PublicHttpError } from "./errors.js";
+export function createAggregateGate(maxActive, maxQueued) {
+    let active = 0;
+    const queue = [];
+    const startQueued = () => {
+        while (active < maxActive && queue.length > 0) {
+            const waiter = queue.shift();
+            clearTimeout(waiter.timeout);
+            if (waiter.onAbort) {
+                waiter.abortSignal?.removeEventListener("abort", waiter.onAbort);
+            }
+            if (waiter.abortSignal?.aborted) {
+                waiter.reject(new PublicHttpError("web_request_aborted", "The web request was aborted."));
+                continue;
+            }
+            if (waiter.deadline <= Date.now()) {
+                waiter.reject(new PublicHttpError("web_request_timed_out", "The upstream web request timed out."));
+                continue;
+            }
+            active += 1;
+            let released = false;
+            waiter.resolve(() => {
+                if (released)
+                    return;
+                released = true;
+                active -= 1;
+                startQueued();
+            });
+        }
+    };
+    const acquire = (deadline, abortSignal) => {
+        if (abortSignal?.aborted) {
+            return Promise.reject(new PublicHttpError("web_request_aborted", "The web request was aborted."));
+        }
+        if (active < maxActive) {
+            active += 1;
+            let released = false;
+            return Promise.resolve(() => {
+                if (released)
+                    return;
+                released = true;
+                active -= 1;
+                startQueued();
+            });
+        }
+        if (queue.length >= maxQueued) {
+            return Promise.reject(new PublicHttpError("web_request_capacity_exceeded", "The web client is at its bounded request capacity."));
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve,
+                reject,
+                deadline,
+                ...(abortSignal ? { abortSignal } : {}),
+            };
+            const remove = () => {
+                const index = queue.indexOf(waiter);
+                if (index >= 0)
+                    queue.splice(index, 1);
+            };
+            const fail = (error) => {
+                remove();
+                clearTimeout(waiter.timeout);
+                if (waiter.onAbort) {
+                    abortSignal?.removeEventListener("abort", waiter.onAbort);
+                }
+                reject(error);
+            };
+            waiter.onAbort = () => fail(new PublicHttpError("web_request_aborted", "The web request was aborted."));
+            waiter.timeout = setTimeout(() => fail(new PublicHttpError("web_request_timed_out", "The upstream web request timed out.")), remainingTime(deadline));
+            waiter.timeout.unref?.();
+            abortSignal?.addEventListener("abort", waiter.onAbort, { once: true });
+            queue.push(waiter);
+        });
+    };
+    return Object.freeze({
+        async run(operation, deadline, abortSignal) {
+            const release = await acquire(deadline, abortSignal);
+            const rawWork = Promise.resolve().then(operation);
+            // A deadline rejects the visible operation promptly, but the capacity slot
+            // remains held until non-cancellable DNS or transport work actually settles.
+            void rawWork.then(release, release);
+            return await withinDeadline(rawWork, deadline, abortSignal);
+        },
+    });
+}

package/dist/src/shared/public-http/deadline.d.ts

@@ -0,0 +1,2 @@
+export declare function remainingTime(deadline: number): number;
+export declare function withinDeadline<T>(promise: Promise<T>, deadline: number, abortSignal?: AbortSignal): Promise<T>;

package/dist/src/shared/public-http/deadline.js

@@ -0,0 +1,29 @@
+import { PublicHttpError } from "./errors.js";
+export function remainingTime(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+        throw new PublicHttpError("web_request_timed_out", "The upstream web request timed out.");
+    }
+    return remaining;
+}
+export function withinDeadline(promise, deadline, abortSignal) {
+    if (abortSignal?.aborted) {
+        return Promise.reject(new PublicHttpError("web_request_aborted", "The web request was aborted."));
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (operation) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            abortSignal?.removeEventListener("abort", onAbort);
+            operation();
+        };
+        const onAbort = () => finish(() => reject(new PublicHttpError("web_request_aborted", "The web request was aborted.")));
+        const timeout = setTimeout(() => finish(() => reject(new PublicHttpError("web_request_timed_out", "The upstream web request timed out."))), remainingTime(deadline));
+        timeout.unref?.();
+        abortSignal?.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => finish(() => resolve(value)), (error) => finish(() => reject(error)));
+    });
+}

package/dist/src/shared/public-http/errors.d.ts

@@ -0,0 +1,6 @@
+export type PublicHttpErrorCode = "web_request_aborted" | "web_request_timed_out" | "web_request_capacity_exceeded" | "web_target_invalid" | "web_target_not_public" | "web_target_unresolvable" | "web_redirect_invalid" | "web_redirect_limit_exceeded" | "web_response_invalid";
+export declare class PublicHttpError<Code extends string = PublicHttpErrorCode> extends Error {
+    readonly code: Code;
+    constructor(code: Code, message: string);
+}
+export declare function isPublicHttpError(error: unknown): error is PublicHttpError;

package/dist/src/shared/public-http/errors.js

@@ -0,0 +1,11 @@
+export class PublicHttpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PublicHttpError";
+        this.code = code;
+    }
+}
+export function isPublicHttpError(error) {
+    return error instanceof PublicHttpError;
+}

package/dist/src/shared/public-http/limits.d.ts

@@ -0,0 +1,8 @@
+export declare const PUBLIC_HTTP_LIMITS: Readonly<{
+    readonly httpConcurrency: 6;
+    readonly httpQueueLimit: 64;
+    readonly redirects: 3;
+    readonly responseBytes: number;
+    readonly requestTimeoutMs: 10000;
+    readonly responseHeaderBytes: number;
+}>;

package/dist/src/shared/public-http/limits.js

@@ -0,0 +1,8 @@
+export const PUBLIC_HTTP_LIMITS = Object.freeze({
+    httpConcurrency: 6,
+    httpQueueLimit: 64,
+    redirects: 3,
+    responseBytes: 512 * 1024,
+    requestTimeoutMs: 10_000,
+    responseHeaderBytes: 32 * 1024,
+});

package/dist/src/shared/public-http/network-policy.d.ts

@@ -0,0 +1,11 @@
+export type PublicAddress = Readonly<{
+    address: string;
+    family: 4 | 6;
+}>;
+export type HostResolver = (hostname: string) => Promise<readonly PublicAddress[]>;
+export declare function isPublicIpv4(address: string): boolean;
+export declare function isPublicIpv6(address: string): boolean;
+export declare function isPublicAddress(address: PublicAddress): boolean;
+export declare function parsePublicHttpUrl(rawUrl: string): URL;
+export declare const resolveHostAddresses: HostResolver;
+export declare function resolvePublicTarget(url: URL, resolver?: HostResolver): Promise<PublicAddress>;

package/dist/src/shared/public-http/network-policy.js

@@ -0,0 +1,178 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { PublicHttpError } from "./errors.js";
+function ipv4Value(address) {
+    if (isIP(address) !== 4)
+        return undefined;
+    const octets = address.split(".").map(Number);
+    return (((octets[0] << 24) >>> 0) +
+        (octets[1] << 16) +
+        (octets[2] << 8) +
+        octets[3]);
+}
+function ipv4InCidr(value, base, bits) {
+    const shift = 32 - bits;
+    return value >>> shift === base >>> shift;
+}
+export function isPublicIpv4(address) {
+    const value = ipv4Value(address);
+    if (value === undefined)
+        return false;
+    const blocked = [
+        ["0.0.0.0", 8],
+        ["10.0.0.0", 8],
+        ["100.64.0.0", 10],
+        ["127.0.0.0", 8],
+        ["169.254.0.0", 16],
+        ["172.16.0.0", 12],
+        ["192.0.0.0", 24],
+        ["192.0.2.0", 24],
+        ["192.88.99.0", 24],
+        ["192.168.0.0", 16],
+        ["198.18.0.0", 15],
+        ["198.51.100.0", 24],
+        ["203.0.113.0", 24],
+        ["224.0.0.0", 4],
+        ["240.0.0.0", 4],
+    ];
+    return !blocked.some(([base, bits]) => ipv4InCidr(value, ipv4Value(base), bits));
+}
+function parseIpv6(address) {
+    const normalized = address.toLowerCase().replace(/^\[|\]$/gu, "");
+    if (normalized.includes("%") || isIP(normalized) !== 6)
+        return undefined;
+    let candidate = normalized;
+    const ipv4Tail = candidate.match(/(?:^|:)(\d+\.\d+\.\d+\.\d+)$/u)?.[1];
+    if (ipv4Tail) {
+        const value = ipv4Value(ipv4Tail);
+        if (value === undefined)
+            return undefined;
+        candidate = candidate.slice(0, -ipv4Tail.length);
+        candidate += `${((value >>> 16) & 0xffff).toString(16)}:${(value & 0xffff).toString(16)}`;
+    }
+    const doubleColon = candidate.indexOf("::");
+    if (doubleColon !== candidate.lastIndexOf("::"))
+        return undefined;
+    const head = (doubleColon >= 0 ? candidate.slice(0, doubleColon) : candidate)
+        .split(":")
+        .filter(Boolean);
+    const tail = (doubleColon >= 0 ? candidate.slice(doubleColon + 2) : "")
+        .split(":")
+        .filter(Boolean);
+    const missing = 8 - head.length - tail.length;
+    if ((doubleColon < 0 && missing !== 0) || (doubleColon >= 0 && missing < 1)) {
+        return undefined;
+    }
+    const groups = [...head, ...Array(missing).fill("0"), ...tail];
+    if (groups.length !== 8 ||
+        groups.some((group) => !/^[0-9a-f]{1,4}$/u.test(group))) {
+        return undefined;
+    }
+    return groups.reduce((value, group) => (value << 16n) | BigInt(Number.parseInt(group, 16)), 0n);
+}
+function ipv6InCidr(value, baseAddress, bits) {
+    const base = parseIpv6(baseAddress);
+    const shift = BigInt(128 - bits);
+    return value >> shift === base >> shift;
+}
+export function isPublicIpv6(address) {
+    const value = parseIpv6(address);
+    if (value === undefined)
+        return false;
+    if (ipv6InCidr(value, "::ffff:0:0", 96)) {
+        const mapped = Number(value & 0xffffffffn) >>> 0;
+        const dotted = [24, 16, 8, 0]
+            .map((shift) => (mapped >>> shift) & 0xff)
+            .join(".");
+        return isPublicIpv4(dotted);
+    }
+    if (ipv6InCidr(value, "64:ff9b::", 96) ||
+        ipv6InCidr(value, "64:ff9b:1::", 48)) {
+        return false;
+    }
+    if (!ipv6InCidr(value, "2000::", 3))
+        return false;
+    const blocked = [
+        ["2001::", 23],
+        ["2001:db8::", 32],
+        ["2002::", 16],
+        ["3fff::", 20],
+    ];
+    return !blocked.some(([base, bits]) => ipv6InCidr(value, base, bits));
+}
+export function isPublicAddress(address) {
+    return address.family === 4
+        ? isPublicIpv4(address.address)
+        : isPublicIpv6(address.address);
+}
+function normalizeHostname(hostname) {
+    return hostname
+        .toLowerCase()
+        .replace(/^\[|\]$/gu, "")
+        .replace(/\.$/u, "");
+}
+function isBlockedHostname(hostname) {
+    return (hostname === "localhost" ||
+        hostname.endsWith(".localhost") ||
+        hostname.endsWith(".local") ||
+        hostname.endsWith(".internal") ||
+        hostname.endsWith(".home") ||
+        hostname.endsWith(".lan"));
+}
+export function parsePublicHttpUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new PublicHttpError("web_target_invalid", "A valid absolute URL is required.");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new PublicHttpError("web_target_invalid", "Only http and https URLs are supported.");
+    }
+    if (parsed.username || parsed.password) {
+        throw new PublicHttpError("web_target_invalid", "URLs containing credentials are not supported.");
+    }
+    const hostname = normalizeHostname(parsed.hostname);
+    if (!hostname || isBlockedHostname(hostname)) {
+        throw new PublicHttpError("web_target_not_public", "Only public Internet targets are allowed.");
+    }
+    const family = isIP(hostname);
+    if ((family === 4 && !isPublicIpv4(hostname)) ||
+        (family === 6 && !isPublicIpv6(hostname))) {
+        throw new PublicHttpError("web_target_not_public", "Only public Internet targets are allowed.");
+    }
+    return parsed;
+}
+export const resolveHostAddresses = async (hostname) => {
+    const normalized = normalizeHostname(hostname);
+    const literalFamily = isIP(normalized);
+    if (literalFamily === 4 || literalFamily === 6) {
+        return Object.freeze([
+            Object.freeze({ address: normalized, family: literalFamily }),
+        ]);
+    }
+    let resolved;
+    try {
+        resolved = await lookup(normalized, { all: true, verbatim: true });
+    }
+    catch {
+        throw new PublicHttpError("web_target_unresolvable", "The public target hostname could not be resolved.");
+    }
+    const addresses = resolved
+        .filter((entry) => entry.family === 4 || entry.family === 6)
+        .map((entry) => Object.freeze({ address: entry.address, family: entry.family }));
+    if (addresses.length === 0) {
+        throw new PublicHttpError("web_target_unresolvable", "The public target hostname could not be resolved.");
+    }
+    return Object.freeze(addresses);
+};
+export 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 PublicHttpError("web_target_not_public", "Only public Internet targets are allowed.");
+    }
+    return addresses[0];
+}

package/dist/src/shared/public-http/public-http.d.ts

@@ -0,0 +1,24 @@
+import { type HostResolver } from "./network-policy.js";
+import { requestPinnedHop, type HopRequester, type HopResponse } from "./request-hop.js";
+export { requestPinnedHop };
+export type { HopRequester };
+export type PublicHttpResponse = HopResponse & Readonly<{
+    requestedUrl: string;
+    finalUrl: string;
+}>;
+export type PublicHttpRequest = Readonly<{
+    url: string;
+    headers?: Readonly<Record<string, string>>;
+    maxBytes?: number;
+    maxRedirects?: number;
+    followRedirects?: boolean;
+    timeoutMs?: number;
+    abortSignal?: AbortSignal;
+}>;
+export type PublicHttpClient = Readonly<{
+    get(request: PublicHttpRequest): Promise<PublicHttpResponse>;
+}>;
+export declare function createPublicHttpClient(dependencies?: Readonly<{
+    resolveHost?: HostResolver;
+    requestHop?: HopRequester;
+}>): PublicHttpClient;

package/dist/src/shared/public-http/public-http.js

@@ -0,0 +1,85 @@
+import { createAggregateGate } from "./aggregate-gate.js";
+import { remainingTime } from "./deadline.js";
+import { PublicHttpError, isPublicHttpError } from "./errors.js";
+import { PUBLIC_HTTP_LIMITS } from "./limits.js";
+import { parsePublicHttpUrl, resolvePublicTarget, } from "./network-policy.js";
+import { requestPinnedHop, } from "./request-hop.js";
+export { requestPinnedHop };
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function canFollowHttpRedirect(request, status) {
+    if (request.followRedirects === false)
+        return false;
+    return REDIRECT_STATUSES.has(status);
+}
+function redirectLocation(response) {
+    const raw = response.headers.location;
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+function validateBounds(request) {
+    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");
+    }
+    if (!Number.isSafeInteger(maxRedirects) || maxRedirects < 0) {
+        throw new RangeError("maxRedirects must be a non-negative safe integer");
+    }
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1) {
+        throw new RangeError("timeoutMs must be a positive safe integer");
+    }
+    return Object.freeze({ maxBytes, maxRedirects, timeoutMs });
+}
+export function createPublicHttpClient(dependencies = {}) {
+    const resolveHost = dependencies.resolveHost;
+    const requestHop = dependencies.requestHop ?? requestPinnedHop;
+    const gate = createAggregateGate(PUBLIC_HTTP_LIMITS.httpConcurrency, PUBLIC_HTTP_LIMITS.httpQueueLimit);
+    return Object.freeze({
+        async get(request) {
+            const requested = parsePublicHttpUrl(request.url);
+            const bounds = validateBounds(request);
+            const deadline = Date.now() + bounds.timeoutMs;
+            let current = requested;
+            for (let redirectCount = 0;; redirectCount += 1) {
+                const address = await gate.run(() => resolvePublicTarget(current, resolveHost), deadline, request.abortSignal);
+                const response = await gate.run(() => requestHop({
+                    url: current,
+                    address,
+                    headers: Object.freeze({
+                        Accept: "text/html,application/xhtml+xml,text/plain,application/json;q=0.9,application/xml;q=0.8,text/xml;q=0.8",
+                        "Accept-Encoding": "identity",
+                        "User-Agent": "abot-runtime-web/1.0",
+                        ...(request.headers ?? {}),
+                    }),
+                    maxBytes: bounds.maxBytes,
+                    timeoutMs: remainingTime(deadline),
+                    ...(request.abortSignal
+                        ? { abortSignal: request.abortSignal }
+                        : {}),
+                }), deadline, request.abortSignal);
+                if (!canFollowHttpRedirect(request, response.status)) {
+                    return Object.freeze({
+                        requestedUrl: requested.toString(),
+                        finalUrl: current.toString(),
+                        ...response,
+                    });
+                }
+                const location = redirectLocation(response);
+                if (!location) {
+                    throw new PublicHttpError("web_redirect_invalid", "The upstream redirect did not provide a valid destination.");
+                }
+                if (redirectCount >= bounds.maxRedirects) {
+                    throw new PublicHttpError("web_redirect_limit_exceeded", "The web request exceeded the redirect limit.");
+                }
+                try {
+                    current = parsePublicHttpUrl(new URL(location, current).toString());
+                }
+                catch (error) {
+                    if (isPublicHttpError(error))
+                        throw error;
+                    throw new PublicHttpError("web_redirect_invalid", "The upstream redirect did not provide a valid destination.");
+                }
+            }
+        },
+    });
+}

package/dist/src/shared/public-http/request-hop.d.ts

@@ -0,0 +1,18 @@
+import { type IncomingHttpHeaders } from "node:http";
+import type { PublicAddress } from "./network-policy.js";
+export type HopResponse = Readonly<{
+    status: number;
+    headers: IncomingHttpHeaders;
+    body: Uint8Array;
+    bytesRead: number;
+    partialContent: boolean;
+}>;
+export type HopRequester = (params: {
+    url: URL;
+    address: PublicAddress;
+    headers: Readonly<Record<string, string>>;
+    maxBytes: number;
+    timeoutMs: number;
+    abortSignal?: AbortSignal;
+}) => Promise<HopResponse>;
+export declare const requestPinnedHop: HopRequester;