@capybara-hq/kernel 0.1.0-rc.23 → 0.1.0-rc.25

package/dist/sandbox/jobs.d.ts

@@ -1,5 +1,6 @@
 import type { Job, Queue } from "bullmq";
 import { LockService } from "../infra/lock/lock.service.js";
+import type { OutboxService } from "../infra/outbox/outbox.service.js";
 import type { KernelLogger } from "../log.js";
 import { SandboxService } from "./sandbox.service.js";
 /** The idle suspension sweep (every minute, once per tick across replicas). */
@@ -7,10 +8,25 @@ export declare const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
 /** The inactivity destruction sweep (hourly, once per tick across replicas). */
 export declare const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
 /**
- * One-off job: destroy a batch of devices now, instance and file system (device
- * deletion, offboarding; data `{ deviceIds }`).
+ * One-off job: destroy devices now, instance and file system (data `{ deviceIds }`). Owed through
+ * the outbox by the transaction that soft-deletes the device (a device's deletion, offboarding),
+ * one device per job under {@link deviceDestroyJobId} ({@link oweDeviceDestroy}).
  */
 export declare const SANDBOX_DESTROY_FOR_JOB = "sandbox-destroy-for";
+/** The data of a {@link SANDBOX_DESTROY_FOR_JOB} job. */
+export interface SandboxDestroyForData {
+    deviceIds: string[];
+}
+/**
+ * The deterministic id of a deleted device's destroy job (no `:`): a device is deleted once, so
+ * its destruction is owed once.
+ */
+export declare const deviceDestroyJobId: (deviceId: string) => string;
+/**
+ * Owes the destruction of a device in the caller's transaction, the one that soft-deleted it
+ * (transactional outbox spec §8.1; throws outside a transaction).
+ */
+export declare function oweDeviceDestroy(outbox: Pick<OutboxService, "add">, deviceId: string, orgId: string): Promise<boolean>;
 /**
  * One-off job: start a device over with empty files (`resetFileSystem`; data
  * `{ deviceId }`, job id {@link resetFilesJobId}).
@@ -22,18 +38,12 @@ export declare const SANDBOX_RESET_FILES_JOB = "sandbox-reset-files";
  */
 export declare const resetFilesJobId: (deviceId: string) => string;
 /**
- * The producer of the sandbox maintenance jobs: {@link SANDBOX_DESTROY_FOR_JOB} (BullMQ's own job
- * ids, as before: every enqueue is a new job, also after a batch failed all its attempts) and
- * {@link SANDBOX_RESET_FILES_JOB}; `MaintenanceProcessor` consumes them.
+ * The producer of {@link SANDBOX_RESET_FILES_JOB} (destroys are owed through the outbox,
+ * {@link oweDeviceDestroy}); `MaintenanceProcessor` consumes both.
  */
 export declare class SandboxJobs {
     private readonly queue;
     constructor(queue: Pick<Queue, "add">);
-    /**
-     * Enqueues the destruction of these devices: a failed batch is retried whole (destroying
-     * one already destroyed does nothing).
-     */
-    destroy(deviceIds: string[]): Promise<void>;
     /**
      * Enqueues the reset of a device's files (see {@link resetFilesJobId}): retried on failure
      * (the exclusive lease not obtained in time, the provider failing); a job that failed all its

package/dist/sandbox/jobs.js

@@ -19,10 +19,29 @@ export const SANDBOX_SUSPEND_JOB = "sandbox-suspend-idle";
 /** The inactivity destruction sweep (hourly, once per tick across replicas). */
 export const SANDBOX_DESTROY_JOB = "sandbox-destroy-inactive";
 /**
- * One-off job: destroy a batch of devices now, instance and file system (device
- * deletion, offboarding; data `{ deviceIds }`).
+ * One-off job: destroy devices now, instance and file system (data `{ deviceIds }`). Owed through
+ * the outbox by the transaction that soft-deletes the device (a device's deletion, offboarding),
+ * one device per job under {@link deviceDestroyJobId} ({@link oweDeviceDestroy}).
  */
 export const SANDBOX_DESTROY_FOR_JOB = "sandbox-destroy-for";
+/**
+ * The deterministic id of a deleted device's destroy job (no `:`): a device is deleted once, so
+ * its destruction is owed once.
+ */
+export const deviceDestroyJobId = (deviceId) => `device-destroy-${deviceId}`;
+/**
+ * Owes the destruction of a device in the caller's transaction, the one that soft-deleted it
+ * (transactional outbox spec §8.1; throws outside a transaction).
+ */
+export function oweDeviceDestroy(outbox, deviceId, orgId) {
+    return outbox.add({
+        queue: MAINTENANCE_QUEUE_NAME,
+        name: SANDBOX_DESTROY_FOR_JOB,
+        jobId: deviceDestroyJobId(deviceId),
+        data: { deviceIds: [deviceId] },
+        orgId,
+    });
+}
 /**
  * One-off job: start a device over with empty files (`resetFileSystem`; data
  * `{ deviceId }`, job id {@link resetFilesJobId}).
@@ -34,27 +53,14 @@ export const SANDBOX_RESET_FILES_JOB = "sandbox-reset-files";
  */
 export const resetFilesJobId = (deviceId) => `${SANDBOX_RESET_FILES_JOB}-${deviceId}`;
 /**
- * The producer of the sandbox maintenance jobs: {@link SANDBOX_DESTROY_FOR_JOB} (BullMQ's own job
- * ids, as before: every enqueue is a new job, also after a batch failed all its attempts) and
- * {@link SANDBOX_RESET_FILES_JOB}; `MaintenanceProcessor` consumes them.
+ * The producer of {@link SANDBOX_RESET_FILES_JOB} (destroys are owed through the outbox,
+ * {@link oweDeviceDestroy}); `MaintenanceProcessor` consumes both.
  */
 let SandboxJobs = class SandboxJobs {
     queue;
     constructor(queue) {
         this.queue = queue;
     }
-    /**
-     * Enqueues the destruction of these devices: a failed batch is retried whole (destroying
-     * one already destroyed does nothing).
-     */
-    async destroy(deviceIds) {
-        await this.queue.add(SANDBOX_DESTROY_FOR_JOB, { deviceIds }, {
-            attempts: 5,
-            backoff: { type: "exponential", delay: 30_000 },
-            removeOnComplete: true,
-            removeOnFail: 100,
-        });
-    }
     /**
      * Enqueues the reset of a device's files (see {@link resetFilesJobId}): retried on failure
      * (the exclusive lease not obtained in time, the provider failing); a job that failed all its

package/dist/sandbox/sandbox.service.d.ts

@@ -2,7 +2,7 @@ import { type ExecResult, type SandboxActor, type SandboxHandle, type SandboxLim
 import type { Redis } from "ioredis";
 import { type Selectable } from "kysely";
 import { BackgroundTaskStore } from "../background/store.js";
-import { type KernelConfig } from "../config/schema.js";
+import type { KernelConfig } from "../config/schema.js";
 import type { DeviceInstancesTable } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
@@ -106,6 +106,19 @@ export declare const deviceNotFound: () => ApiError;
  * owner's: `capybara-device logout`, then `login` into the device, recreates it (ruling R24).
  */
 export declare const deviceFilesLost: (local?: boolean) => ApiError;
+/**
+ * A cloud sandbox provider refused to make (or move) an instance with open egress, the open tier
+ * (409; sandbox dev tiers spec §5.3): above all a provider set to refuse it (sandbox-docker /
+ * sandbox-e2b `openEgress: "off"`). Details `[{ tier }]`. The provider's own error goes only to
+ * the log: it may name the provider's settings.
+ */
+export declare const sandboxTierRefused: (tier: SandboxTier) => ApiError;
+/**
+ * A cloud sandbox provider failed to make a device's file system or instance for another reason
+ * (502): often its deployment config (image, runtime, network), sometimes a passing fault. The
+ * provider's own error goes only to the log.
+ */
+export declare const sandboxCreateFailed: () => ApiError;
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -117,11 +130,11 @@ export declare const isInstance: (row: Pick<Row, "handle" | "created_at">, gone:
  *   run time limit (Ruling M20);
  * - `sandbox.tiers.max` is open but the current provider plugin sets `openEgress: "off"`: every
  *   creation of an open-tier instance is refused.
- * With both time limits at their defaults (900 < 7200, a known trade-off) it is only info; warn
- * when an operator changed one and they still disagree.
+ * No run duration limit (`runtime.maxRunSeconds` 0, the default) cuts no command, so there is
+ * nothing to tell.
  */
 export declare function sandboxConfigWarnings(cfg: Pick<KernelConfig, "runtime" | "sandbox" | "extensionConfig">, providerPlugin?: string): {
-    level: "info" | "warn";
+    level: "warn";
     message: string;
 }[];
 /** No sandbox provider (503). */

package/dist/sandbox/sandbox.service.js

@@ -13,7 +13,6 @@ import { Inject, Injectable } from "@nestjs/common";
 import { sql, } from "kysely";
 import { SESSION_MODE_SCRIPT } from "../background/launch.js";
 import { BackgroundTaskStore } from "../background/store.js";
-import { DEFAULT_MAX_COMMAND_SECONDS, DEFAULT_MAX_RUN_SECONDS, } from "../config/schema.js";
 import { ApiError } from "../errors.js";
 import { readSandboxLimitOverride } from "../identity/settings.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
@@ -23,8 +22,9 @@ import { effectiveSandboxLimits, readOrgSettings } from "../orgs/settings.servic
 import { appendMissingGrant, TIER_OPEN_GRANT_KEY, UNATTENDED_OPEN_TIER_ERROR, unattendedTierOf, } from "../schedules/unattended.js";
 import { canonicalJson } from "../tools/canonical-json.js";
 import { SandboxLeases, SandboxLockLostError, sandboxBusy, } from "./leases.js";
-import { LOCAL_PROVIDER, providerForDevice, SandboxProviders, } from "./providers.js";
+import { isInternalProvider, LOCAL_PROVIDER, providerForDevice, SandboxProviders, } from "./providers.js";
 import { appliedOf, effectiveSandboxPolicy, instanceLimitsJson, limitsForTier, readDeploymentSandboxPolicy, readInstanceLimits, sameApplied, } from "./tiers.js";
+import { SandboxProviderUnreachableError } from "./unreachable.js";
 // Moved to leases.ts (phase C); re-exported for existing importers
 export { SANDBOX_LOCK_PREFIX, SANDBOX_LOCK_TTL_MS, SandboxLockLostError, sandboxBusy, } from "./leases.js";
 /** Margin (ms) of a holder record's TTL beyond the longest command: by then the in-sandbox limit has ended its commands. */
@@ -58,6 +58,46 @@ export const deviceNotFound = () => new ApiError("device.not_found", "This devic
 export const deviceFilesLost = (local = false) => local
     ? new ApiError("device.files_lost", "The local device's directory is gone from its machine; run capybara-device logout, then capybara-device login into this device, on that machine to recreate it.", [{ source: "local" }])
     : new ApiError("device.files_lost", "The device's files are gone; reset its files from the devices page to start with an empty workspace.");
+/**
+ * A cloud sandbox provider refused to make (or move) an instance with open egress, the open tier
+ * (409; sandbox dev tiers spec §5.3): above all a provider set to refuse it (sandbox-docker /
+ * sandbox-e2b `openEgress: "off"`). Details `[{ tier }]`. The provider's own error goes only to
+ * the log: it may name the provider's settings.
+ */
+export const sandboxTierRefused = (tier) => new ApiError("sandbox.tier_refused", `The cloud sandbox can't run this device at the ${tier} tier: the sandbox provider refused to create it there. An org admin can lower the tier on the device page or in the org's sandbox settings, or a super admin can allow it in the sandbox extension's settings.`, [{ tier }]);
+/**
+ * A cloud sandbox provider failed to make a device's file system or instance for another reason
+ * (502): often its deployment config (image, runtime, network), sometimes a passing fault. The
+ * provider's own error goes only to the log.
+ */
+export const sandboxCreateFailed = () => new ApiError("sandbox.create_failed", "The cloud sandbox provider could not create this device's sandbox. Retry; if it keeps failing, a super admin should check the sandbox extension's settings.");
+/**
+ * What a failed `createFileSystem` / `create` / `update` of a cloud provider becomes: an abort,
+ * a gone error, an unreachable provider and a kernel error stay as they are (their callers and the
+ * tools handle them); any other error is logged (warn, redacted) and replaced by
+ * {@link sandboxTierRefused} when `limits` ask for open egress (the only egress a provider's
+ * config refuses), else (a create) by {@link sandboxCreateFailed}; a failed `update` below open
+ * stays as it is. A kernel-internal provider (`@local`) keeps its own errors.
+ */
+function providerRefusal(log, err, facts, limits, signal) {
+    if (signal.aborted ||
+        isInternalProvider(facts.provider) ||
+        isSandboxGoneError(err) ||
+        isFileSystemGoneError(err) ||
+        err instanceof SandboxProviderUnreachableError ||
+        err instanceof ApiError) {
+        return err;
+    }
+    if (limits.egress === "open") {
+        // spec §5.3: a provider set to refuse open egress (`openEgress: "off"`) fails here
+        log.warn("the sandbox provider refused an instance in the open tier; check its openEgress setting or lower sandbox.tiers.max", { ...facts, tier: limits.tier, err });
+        return sandboxTierRefused(limits.tier);
+    }
+    if (facts.op === "update")
+        return err;
+    log.warn("the sandbox provider failed to create a device's sandbox", { ...facts, err });
+    return sandboxCreateFailed();
+}
 /**
  * The row still records the instance `gone` (same handle and same `created_at`). Handles compare
  * canonically: a jsonb round trip reorders a multi-key handle's keys (final review m9).
@@ -87,8 +127,8 @@ function tagged(impl, tag, actor, before) {
  *   run time limit (Ruling M20);
  * - `sandbox.tiers.max` is open but the current provider plugin sets `openEgress: "off"`: every
  *   creation of an open-tier instance is refused.
- * With both time limits at their defaults (900 < 7200, a known trade-off) it is only info; warn
- * when an operator changed one and they still disagree.
+ * No run duration limit (`runtime.maxRunSeconds` 0, the default) cuts no command, so there is
+ * nothing to tell.
  */
 export function sandboxConfigWarnings(cfg, providerPlugin) {
     const out = [];
@@ -104,10 +144,9 @@ export function sandboxConfigWarnings(cfg, providerPlugin) {
     }
     const run = cfg.runtime.maxRunSeconds;
     const cmd = cfg.sandbox.limits.maxCommandSeconds;
-    if (run < cmd) {
-        const defaults = run === DEFAULT_MAX_RUN_SECONDS && cmd === DEFAULT_MAX_COMMAND_SECONDS;
+    if (run > 0 && run < cmd) {
         out.push({
-            level: defaults ? "info" : "warn",
+            level: "warn",
             message: `runtime.maxRunSeconds (${run}) is less than sandbox.limits.maxCommandSeconds (${cmd}): sandbox commands are limited to the time left in the run, so commands longer than about ${run} seconds cannot finish; raise runtime.maxRunSeconds to at least ${cmd} if agents need long commands`,
         });
     }
@@ -1380,7 +1419,12 @@ let SandboxService = class SandboxService {
             ? row.fs_handle
             : null;
         if (fs === null) {
-            fs = await p.impl.createFileSystem({ name, limits, signal });
+            try {
+                fs = await p.impl.createFileSystem({ name, limits, signal });
+            }
+            catch (err) {
+                throw providerRefusal(this.log, err, { deviceId: id, provider: p.plugin, op: "createFileSystem" }, limits, signal);
+            }
             // A lost lease fails this write and leaves the file system alone: createFileSystem returns
             // the existing one for a name, so the new holder may already use it, files and all.
             await this.fenced(held, id, fence, {
@@ -1403,11 +1447,7 @@ let SandboxService = class SandboxService {
         }
         catch (err) {
             if (!isFileSystemGoneError(err)) {
-                if (limits.egress === "open" && !signal.aborted) {
-                    // spec §5.3: a provider set to refuse open egress (`openEgress: "off"`) fails here
-                    this.log.warn("the sandbox provider did not create an instance in the open tier; check its openEgress setting or lower sandbox.tiers.max", { deviceId: id, provider: p.plugin, err });
-                }
-                throw err;
+                throw providerRefusal(this.log, err, { deviceId: id, provider: p.plugin, op: "create" }, limits, signal);
             }
             this.log.warn("device file system is gone at the provider; its files are lost", {
                 deviceId: id,
@@ -1479,7 +1519,8 @@ let SandboxService = class SandboxService {
                     // the instance may run with half-applied limits and cannot be recreated here: stop it,
                     // so the next use resumes it and applies them again
                     await this.quarantine(held, id, handle, p, fence);
-                    throw err;
+                    // a provider bound to its file system that refuses the new tier (E2B, `openEgress: "off"`)
+                    throw providerRefusal(this.log, err, { deviceId: id, provider: p.plugin, op: "update" }, want, signal);
                 }
                 else {
                     // a new instance gets the limits at create: recreate rather than trust a failed update

package/dist/schedules/calendar.d.ts

@@ -0,0 +1,134 @@
+import type { ScheduledTask, ScheduleMode, SchedulePauseReason, ScheduleStatus, ScheduleTrigger, TaskRun, TaskRunSkipReason, TaskRunStatus } from "./types.js";
+/** Planned occurrences reach this far ahead of now (spec §5.2, "about six weeks"). */
+export declare const CALENDAR_HORIZON_DAYS = 42;
+/** The longest range one request may ask for: a 6-week month grid plus a DST hour (§5.1). */
+export declare const CALENDAR_RANGE_DAYS = 43;
+/** The longest range with `taskId` (the panel's one-day list, §5.4). */
+export declare const CALENDAR_TASK_RANGE_DAYS = 2;
+/** A task-day with more items than this is collapsed into one summary (§5.4). */
+export declare const CALENDAR_COLLAPSE_OVER = 6;
+/**
+ * Ticks taken per request after the first local day, across all tasks (§5.5). One tick costs
+ * about 150-340 µs (cron's `getNextDateFrom`, measured 2026-11-12 with a ticker built once per
+ * task), so 3,000 keeps a worst-case request near one second.
+ */
+export declare const CALENDAR_TICK_BUDGET = 3000;
+/** Entries (`items` + `collapsed`) per request after the first local day (§5.5). */
+export declare const CALENDAR_ITEM_CAP = 3000;
+/** Run rows read per request after the first local day (§5.5). */
+export declare const CALENDAR_RUN_ROW_CAP = 20000;
+/**
+ * The first requested local day is always returned whole, outside the limits above; only these
+ * safety caps stop it (then nothing is returned, `truncated`, `horizon` = `from`).
+ */
+export declare const CALENDAR_FIRST_DAY_TICK_CAP = 10000;
+export declare const CALENDAR_FIRST_DAY_RUN_CAP = 20000;
+/** The limits of one assembly; tests lower them. */
+export interface CalendarLimits {
+    horizonDays: number;
+    collapseOver: number;
+    /**
+     * Ticks taken (planned ticks in the range, the due tick included), after the first day. Not
+     * counted: each stream's one lookahead evaluation past its `until` and the doubling search of
+     * `scanStep` for a task already due, at most about 2 × tasks evaluations more.
+     */
+    tickBudget: number;
+    itemCap: number;
+    runRowCap: number;
+    firstDayTickCap: number;
+    firstDayRunCap: number;
+}
+export declare const CALENDAR_LIMITS: CalendarLimits;
+/** How many run rows the service reads: enough to tell where either run cap cuts. */
+export declare const calendarRunReadLimit: (limits: CalendarLimits) => number;
+/** A task an entry of the answer names. */
+export interface CalendarTask {
+    id: string;
+    name: string;
+    agentId: string;
+    accountId: string;
+    status: ScheduleStatus;
+    pauseReason: SchedulePauseReason | null;
+    trigger: ScheduleTrigger;
+    mode: ScheduleMode;
+    jitterSeconds: number;
+    nextRunAt: string | null;
+}
+export type CalendarItem = {
+    kind: "run";
+    taskId: string;
+    /** The task run's id. */
+    id: string;
+    scheduledFor: string;
+    firedAt: string | null;
+    status: TaskRunStatus;
+    skipReason: TaskRunSkipReason | null;
+    trial: boolean;
+    manual: boolean;
+    /** Null for another member's run (admin `all`, spec §15 Q3), as `error` and `missingGrants`. */
+    conversationId: string | null;
+    error: string | null;
+    missingGrants: number | null;
+} | {
+    kind: "occurrence";
+    taskId: string;
+    /** The tick, before jitter. */
+    scheduledFor: string;
+    /** When it fires: the tick plus the task's jitter. */
+    at: string;
+};
+/** A task's items of one local day, summarized (§5.4). */
+export interface CalendarCollapsed {
+    taskId: string;
+    /** YYYY-MM-DD in the request's `timeZone`. */
+    day: string;
+    count: number;
+    upcoming: number;
+    running: number;
+    completed: number;
+    failed: number;
+    skipped: number;
+    /** The earliest and latest `scheduledFor` of the day's items. */
+    first: string;
+    last: string;
+}
+export interface CalendarAnswer {
+    tasks: CalendarTask[];
+    items: CalendarItem[];
+    collapsed: CalendarCollapsed[];
+    /** Nothing is returned after it: 42 days ahead, or the cut. */
+    horizon: string;
+    /** A limit cut the range at a whole local day. */
+    truncated: boolean;
+}
+export interface CalendarInput {
+    /** The live tasks the viewer may see in this request. */
+    tasks: readonly ScheduledTask[];
+    /**
+     * Their runs with `scheduledFor` in `[from, to)`, trial included, ordered by `scheduledFor`, at
+     * most {@link calendarRunReadLimit} (rows past it are not read; the range is cut before them).
+     */
+    runs: readonly TaskRun[];
+    /** The viewer: another creator's runs lose `conversationId`, `error` and `missingGrants`. */
+    viewerAccountId: string;
+    from: Date;
+    to: Date;
+    /** The viewer's zone: local days for the collapse and the cut. */
+    timeZone: string;
+    now: Date;
+    /** False when the org turned scheduled tasks off: nothing would fire, so nothing is planned. */
+    plan: boolean;
+    /** The org's catch-up window, as the scanner reads it. */
+    catchUpWindowMinutes: number;
+    /** False for a `taskId` read: every item, never collapsed. */
+    collapse: boolean;
+}
+/** The calendar answer from the rows (spec §5.2–§5.5). */
+export declare function assembleCalendar(input: CalendarInput, limits?: CalendarLimits): CalendarAnswer;
+/** YYYY-MM-DD of the instant (epoch ms) in `timeZone`. */
+export declare function dayKey(ms: number, timeZone: string): string;
+/**
+ * The first instant (epoch ms) of the local day of `ms` in `timeZone`: midnight, or the end of a
+ * DST gap that swallows it. A day is at most 25 hours long, so 27 hours back is an earlier day.
+ */
+export declare function startOfLocalDay(ms: number, timeZone: string): number;