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

package/dist/sandbox/tiers.js

@@ -0,0 +1,104 @@
+import { isSandboxTier, minTier, tierAtMost } from "@capybara-hq/plugin-sdk";
+import { readPlatformTiers } from "./platform-tiers.js";
+/**
+ * The platform side of the policy, read live: the `sandbox.limits` network fields of the config
+ * and the effective platform tiers (in the caller's transaction when there is one).
+ */
+export async function readDeploymentSandboxPolicy(db, config) {
+    return { limits: config.get().sandbox.limits, tiers: await readPlatformTiers(db, config) };
+}
+/** The org's base list `L`: see {@link BaseSandboxEgress}. */
+export function baseSandboxEgress(deployment, org) {
+    if (deployment.egress === "none" || org?.mode === "none")
+        return { egress: "none", allowHosts: [] };
+    return { egress: "allowlist", allowHosts: [...(org?.allowHosts ?? deployment.allowHosts)] };
+}
+/**
+ * The network of `tier` over the base list (spec §4.2): `none` stays `none` in every tier; an
+ * allowlist is `L` in strict, `L ∪ D` in dev and open egress in open.
+ */
+export function networkForTier(base, devHosts, tier) {
+    if (base.egress === "none")
+        return { egress: "none", allowHosts: [] };
+    if (tier === "open")
+        return { egress: "open", allowHosts: [] };
+    if (tier === "dev") {
+        return { egress: "allowlist", allowHosts: [...new Set([...base.allowHosts, ...devHosts])] };
+    }
+    return { egress: "allowlist", allowHosts: [...base.allowHosts] };
+}
+/** The network of `tier` under `policy` (e.g. the ceiling's for a local device's exec args). */
+export function limitsForTier(policy, tier) {
+    return networkForTier(policy.base, policy.devHosts, tier);
+}
+/**
+ * The effective sandbox policy (spec §4.2). `deviceTier` is the device's own choice (null =
+ * follow the org's default). The org's ceiling is its `sandboxTier.max` (absent = the platform's)
+ * cut to the platform's; its default is `sandboxTier.default ?? sandbox.tiers.default`, cut to the
+ * ceiling. Stored values above the platform (the platform lowered its max later) are cut, never
+ * honoured.
+ */
+export function effectiveSandboxPolicy(deployment, org, deviceTier) {
+    const platformMax = deployment.tiers.max;
+    const orgMax = org.sandboxTier?.max ?? platformMax;
+    const ceiling = minTier(orgMax, platformMax);
+    const chosenDefault = org.sandboxTier?.default ?? deployment.tiers.default;
+    const defaultTier = minTier(chosenDefault, ceiling);
+    const chosen = deviceTier ?? chosenDefault;
+    const tier = minTier(chosen, ceiling);
+    // the platform caps when its max is the lowest ceiling (an org max at or above it cuts nothing)
+    const cappedBy = tier === chosen ? null : tierAtMost(platformMax, orgMax) ? "platform" : "org";
+    const base = baseSandboxEgress(deployment.limits, org.sandboxEgress);
+    const devHosts = [...deployment.limits.devHosts];
+    return {
+        tier,
+        ceiling,
+        defaultTier,
+        cappedBy,
+        ...networkForTier(base, devHosts, tier),
+        base,
+        devHosts,
+        allowUnsandboxed: deployment.tiers.allowUnsandboxed &&
+            (org.sandboxTier?.allowUnsandboxed ?? true) &&
+            ceiling === "open",
+    };
+}
+/** The {@link AppliedLimits} of `limits`. */
+export const appliedOf = (limits) => ({
+    tier: limits.tier,
+    egress: limits.egress,
+});
+/** Whether `a` and `b` are the same tier and egress mode (null, unknown, is never the same). */
+export const sameApplied = (a, b) => a != null && a.tier === b.tier && a.egress === b.egress;
+const EGRESS_MODES = ["none", "allowlist", "open"];
+function appliedFrom(v) {
+    if (typeof v !== "object" || v === null)
+        return null;
+    const o = v;
+    if (!isSandboxTier(o.tier) || typeof o.egress !== "string" || !EGRESS_MODES.includes(o.egress)) {
+        return null;
+    }
+    return { tier: o.tier, egress: o.egress };
+}
+/**
+ * `device_instances.instance_limits` read leniently: `applied` is what the instance runs with
+ * (null: unknown, e.g. an instance made before migration 0117, which differs from every effective
+ * value); `unapplied` is a newer value the provider could not apply without a file reset.
+ */
+export function readInstanceLimits(v) {
+    if (typeof v !== "object" || v === null)
+        return { applied: null, unapplied: null };
+    return {
+        applied: appliedFrom(v),
+        unapplied: appliedFrom(v.unapplied),
+    };
+}
+/** The JSON written to `device_instances.instance_limits`. */
+export function instanceLimitsJson(applied, unapplied) {
+    if (applied === null && unapplied === undefined)
+        return null;
+    return JSON.stringify({
+        ...(applied !== null && appliedOf(applied)),
+        ...(unapplied !== undefined && { unapplied: appliedOf(unapplied) }),
+    });
+}

package/dist/schedules/effective-settings.d.ts

@@ -0,0 +1,16 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { type ScheduledTasksSettings } from "../orgs/settings.service.js";
+/** The platform's bounds for the org settings (kernel config `schedules.*`). */
+export interface ScheduleBounds {
+    minIntervalFloorMinutes: number;
+    maxTasksPerMemberCap: number;
+    maxTasksPerOrgCap: number;
+    maxRunsPerHourCap: number;
+}
+/** The org's scheduled-task settings after clamping to the platform bounds. */
+export type EffectiveScheduleSettings = ScheduledTasksSettings;
+/** An org value outside the platform bounds is clamped: the interval up, the counts down. */
+export declare function effectiveScheduleSettings(org: ScheduledTasksSettings, bounds: ScheduleBounds): EffectiveScheduleSettings;
+/** Read the org's effective settings live (PG and the current kernel config). */
+export declare function readScheduleSettings(db: KernelSchemaDb, config: Pick<KernelConfigService, "get">, orgId: string): Promise<EffectiveScheduleSettings>;

package/dist/schedules/effective-settings.js

@@ -0,0 +1,17 @@
+import { readOrgSettings } from "../orgs/settings.service.js";
+/** An org value outside the platform bounds is clamped: the interval up, the counts down. */
+export function effectiveScheduleSettings(org, bounds) {
+    return {
+        ...org,
+        forbiddenTools: [...org.forbiddenTools],
+        minIntervalMinutes: Math.max(org.minIntervalMinutes, bounds.minIntervalFloorMinutes),
+        maxTasksPerMember: Math.min(org.maxTasksPerMember, bounds.maxTasksPerMemberCap),
+        maxTasksPerOrg: Math.min(org.maxTasksPerOrg, bounds.maxTasksPerOrgCap),
+        maxRunsPerHour: Math.min(org.maxRunsPerHour, bounds.maxRunsPerHourCap),
+    };
+}
+/** Read the org's effective settings live (PG and the current kernel config). */
+export async function readScheduleSettings(db, config, orgId) {
+    const org = await readOrgSettings(db, orgId);
+    return effectiveScheduleSettings(org.scheduledTasks, config.get().schedules);
+}

package/dist/schedules/errors.d.ts

@@ -0,0 +1,8 @@
+import { ApiError } from "../errors.js";
+/** The task is missing, deleted, in another org or not the caller's to see (never 403). */
+export declare const scheduleNotFound: () => ApiError;
+/** An org admin acting on another person's task in a way only its creator may (spec §10). */
+export declare const scheduleForbidden: () => ApiError;
+export declare const scheduleDisabled: () => ApiError;
+export declare const targetInvalid: (message: string) => ApiError;
+export declare const grantNotAllowed: (message: string) => ApiError;

package/dist/schedules/errors.js

@@ -0,0 +1,8 @@
+import { ApiError } from "../errors.js";
+/** The task is missing, deleted, in another org or not the caller's to see (never 403). */
+export const scheduleNotFound = () => new ApiError("schedule.not_found", "Scheduled task not found");
+/** An org admin acting on another person's task in a way only its creator may (spec §10). */
+export const scheduleForbidden = () => new ApiError("schedule.forbidden", "Only the task's creator can change its prompt, schedule, target or approved tools");
+export const scheduleDisabled = () => new ApiError("schedule.disabled", "Scheduled tasks are turned off in this organization");
+export const targetInvalid = (message) => new ApiError("schedule.target_invalid", message);
+export const grantNotAllowed = (message) => new ApiError("schedule.grant_not_allowed", message);

package/dist/schedules/fire.d.ts

@@ -0,0 +1,118 @@
+import { AgentLookup } from "../agents/agent-lookup.js";
+import { ChannelConnections } from "../channels/connections.service.js";
+import { ConversationAccess } from "../conversations/access.js";
+import { ConversationsService } from "../conversations/conversations.service.js";
+import { ConversationQueue } from "../conversations/queue.service.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { RunControl } from "../runtime/run-control.js";
+import { ScheduledTaskRunTracker } from "./run-tracker.js";
+import { ScheduledTaskStore } from "./store.js";
+/** A task run's message client id in a conversation's queue (never read back as "the task's"). */
+export declare const scheduledClientMessageId: (taskRunId: string) => string;
+/** The tick in the task's zone as the run's header shows it: `2026-11-11 09:00 (Asia/Shanghai)`. */
+export declare function localTimeOf(at: Date, timeZone: string): string;
+/**
+ * Checks and starts one task run (scheduled tasks spec §6), the body of the `sched-fire-<id>` job.
+ * Idempotent on the task run: only a `pending` one is fired. Two steps:
+ *
+ * 1. The claim, one transaction under the org row lock (which serializes the org's rate limit
+ *    count), then the task run and the task rows: the checks in order (task paused since the
+ *    scan, unless a person's "run now"; org disabled, creator
+ *    inactive or not a member, agent gone or not visible, conversation gone, connection inactive,
+ *    overlap, rate limit, device offline, queue paused), each a `skipped` run with its reason, the
+ *    lasting ones also pausing the task; then `fired_at` is written, after the rate limit count.
+ *    A run whose claim committed before (a retried job) goes straight to the start.
+ * 2. The start, idempotent: `new` creates the conversation with its first message keyed by the
+ *    task run id (`create_request_id`); `conversation` queues the prompt in the target
+ *    conversation's queue (never absorbed into a run in progress); `chat` finds the DM's live
+ *    thread or creates and binds a conversation (one transaction), then queues the prompt there;
+ *    a group chat gets a new conversation per run whose thread outbound binds at the run's first
+ *    post (`openGroup`). A start that finds the target gone takes `fired_at` back and skips the run.
+ *
+ * Every message carries the schedule marker and the task's zone; the kernel run its message
+ * triggers takes the task run (`linkStartedRunIn`), and the run tracker follows it to its end.
+ */
+export declare class ScheduledTaskFirer {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly config;
+    private readonly store;
+    private readonly tracker;
+    private readonly orgLock;
+    private readonly agents;
+    private readonly access;
+    private readonly conversations;
+    private readonly queue;
+    private readonly connections;
+    private readonly runs;
+    /** Reads a local device's connection lease (online or not). */
+    private readonly locks;
+    private readonly log;
+    constructor(kdb: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, store: ScheduledTaskStore, tracker: Pick<ScheduledTaskRunTracker, "inFlightIn" | "failStartIn">, orgLock: Pick<OrgLock, "tryLock">, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, conversations: Pick<ConversationsService, "createWithMessage" | "create">, queue: Pick<ConversationQueue, "add">, connections: Pick<ChannelConnections, "row" | "channel">, runs: Pick<RunControl, "ensureRun">, 
+    /** Reads a local device's connection lease (online or not). */
+    locks: Pick<LockService, "holderOf">, log: Pick<KernelLogger, "warn" | "info">);
+    private get db();
+    /** Fires task run `taskRunId` (see the class); a run not `pending` is left as it is. */
+    fire(taskRunId: string): Promise<void>;
+    /** Step 1 (see the class): a skip, the plan, or null when there is nothing to fire. */
+    private claim;
+    /** Step 2 (see the class). */
+    private start;
+    /**
+     * The DM's live conversation, or a new one bound to it (`findOrBindThread`), in one transaction:
+     * a conversation it creates is the task's (`conversations.scheduled_task_id`). Null when the
+     * live conversation's queue is paused (the run is skipped, `queue_paused`).
+     */
+    private bindChat;
+    /**
+     * A group run's conversation (spec §8): a new one per run, the task's
+     * (`conversations.scheduled_task_id`), whose delivery goes to the group with its thread still to
+     * bind (`channel_deliveries.pending_thread_account_id` = the creator): outbound binds it at the
+     * run's first post, thread key = that message's id, so replies in that thread continue the
+     * conversation. One transaction; a retried start reuses the conversation it made before.
+     */
+    private openGroup;
+    /** The start found the target gone: `fired_at` back to null, skipped with `reason`. */
+    private unstart;
+    /**
+     * The start was refused for another reason (a full queue, a model gone since the task was
+     * saved, …): the run failed, and counts toward the task's failures as a failed run does.
+     */
+    private failStart;
+    private setConversation;
+    /** Marks a pending run skipped (never fired) and pauses the task for a lasting reason. */
+    private skipIn;
+    /** Another run of the task is still in flight (stale ones are settled on the way). */
+    private overlaps;
+    /** The creator is an active account and still a member of the org. */
+    private creatorActive;
+    /** The target conversation, live, the creator's chat with the task's agent and accessible. */
+    private targetConversation;
+    private queuePaused;
+    /**
+     * The DM thread key of the creator in `chatId` (the key inbound uses, `dm:<externalId>`), from
+     * their external ids on the connection's identity source (`<plugin>:<tenant>`): the id whose
+     * thread row in this chat is the newest (archived rows count); when none has a row there, the
+     * smallest id (deterministic). Without an identity (no tenant yet), the key of their newest DM
+     * thread row in the chat. Undefined when neither exists.
+     */
+    private dmThreadKey;
+    /**
+     * The creator has written in the group (spec §8: a group thread row of theirs exists there,
+     * archived ones included), so a run may post there on their behalf.
+     */
+    private inGroup;
+    /** The device is gone, or a local device whose machine is not connected now. */
+    private deviceOffline;
+}
+/**
+ * The fire job and the scanner, worker only: imported by `MaintenanceModule` (which dispatches
+ * `sched-fire`) and `WorkerModule` (the scan's `@LockedCron`), never by another role.
+ */
+export declare class ScheduledTaskFireModule {
+}