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

package/dist/schedules/grant-rules.d.ts

@@ -0,0 +1,94 @@
+import { type DeviceLocalPolicySummary, type SandboxLimits, type SandboxTier } from "@capybara-hq/plugin-sdk";
+import { type OrgRole } from "../orgs/roles.js";
+import type { ResolvedTool } from "../tools/registry.js";
+import { TIER_GRANT_SPEC_HASH, TIER_OPEN_GRANT_KEY } from "./unattended.js";
+export { TIER_GRANT_SPEC_HASH, TIER_OPEN_GRANT_KEY };
+/**
+ * The one rule for what can be a scheduled task's grant (spec §7): the task form and
+ * `addGrants`, a trial run's kept approvals and the unattended policy's `missing_grants` all ask
+ * it. A plain module (no provider): the tool policy imports it.
+ */
+/** Who asks for a grant and where: the inputs of {@link grantRefusalOf}. */
+export interface GrantContext {
+    role: OrgRole;
+    forbiddenTools: readonly string[];
+}
+/**
+ * Why a tool can't be a task's grant, as a code the UI words: `forbidden` (the org's
+ * `forbiddenTools`), `not_grantable` (by design: a Platform call that changes the agent's
+ * skills, or any other per-call key such as `Platform:<operation>`), `not_available` (not one of the agent's tools now), `needs_role` (a
+ * `requiredRole` above the creator's), `fixed_ask` (always asks a person). A network grant
+ * (`network:<host>`, {@link networkGrantRefusal}) adds `needs_admin` (outside the org's network
+ * allowlist: only an org admin can add the host) and `device_refuses` (the task's device takes no
+ * network grants from the deployment: `remoteGrants` off); an invalid or wildcard host is
+ * `not_grantable`.
+ */
+export type GrantRefusalCode = "forbidden" | "not_grantable" | "not_available" | "needs_role" | "fixed_ask" | "needs_admin" | "device_refuses";
+/**
+ * Why `toolKey` cannot be one of a task's grants, or null when it can: the creator could approve
+ * it with scope `always` themselves (no `requiredRole` above their role, not a fixed ask), it is
+ * the tool's own key (a per-call key such as `Platform:<operation>` is decided per call and never
+ * a task grant), it changes none of the agent's skills (an unattended run never does) and
+ * the org forbids neither the key nor the tool. `tool`: the agent's tool `toolKey` belongs to,
+ * undefined when the agent does not have it now.
+ */
+export declare function grantRefusalOf(toolKey: string, tool: ResolvedTool | undefined, ctx: GrantContext): {
+    code: GrantRefusalCode;
+    message: string;
+} | null;
+/** {@link grantRefusalOf}'s message alone; null when the tool can be granted. */
+export declare function grantRefusal(toolKey: string, tool: ResolvedTool | undefined, ctx: GrantContext): string | null;
+/** The prefix of a network grant's key (network ask-to-allow spec §8.1). */
+export declare const NETWORK_GRANT_PREFIX = "network:";
+/** The `spec_hash` a network grant is stored with (no tool definition behind it; plan P-D7). */
+export declare const NETWORK_GRANT_SPEC_HASH = "network";
+/** Whether a grant key is a network grant (`network:<host>`). */
+export declare const isNetworkGrantKey: (key: string) => boolean;
+/** The host of a network grant key (`network:<host>`). */
+export declare const networkGrantHost: (key: string) => string;
+/** What {@link networkGrantRefusal} checks a host against. */
+export interface NetworkGrantContext {
+    /**
+     * The network of the org's sandbox ceiling now (`SandboxService.ceilingLimits`): the most a
+     * device's command may reach.
+     */
+    limits: Pick<SandboxLimits, "egress" | "allowHosts">;
+    /**
+     * The local policy summary of the task's device (its active machine); null or undefined when
+     * the task has no device that can be determined or its machine is not connected: the device
+     * rule is then skipped (the device still refuses at the command, and the run notes it).
+     */
+    deviceSummary?: DeviceLocalPolicySummary | null;
+}
+/**
+ * Why `host` cannot be one of a task's network grants (network ask-to-allow spec §8.1), or null
+ * when it can: `not_grantable` (not an exact, valid host name: no wildcard, no address),
+ * `needs_admin` (the org's effective egress does not admit it: only an org admin can add it),
+ * `device_refuses` (the task's device reports `remoteGrants: "off"`). The host is compared as given
+ * (callers lower-case it first).
+ */
+export declare function networkGrantRefusal(host: string, ctx: NetworkGrantContext): {
+    code: GrantRefusalCode;
+    message: string;
+} | null;
+/** The prefix of a sandbox tier grant's key (sandbox dev tiers spec §11.4): only `tier:open` exists. */
+export declare const TIER_GRANT_PREFIX = "tier:";
+/** Whether a grant key is a sandbox tier grant (`tier:<tier>`). */
+export declare const isTierGrantKey: (key: string) => boolean;
+/** Whether a grant key names no tool: a network grant or a sandbox tier grant. */
+export declare const isPolicyGrantKey: (key: string) => boolean;
+/**
+ * Why `key` cannot be a task's sandbox tier grant (sandbox dev tiers spec §11.4), or null when it
+ * can: only `tier:open` is one (`not_grantable` otherwise), and only while the org's ceiling
+ * (`ceiling`: its highest tier, cut to the platform's) is `open` (`needs_admin`: only an org admin
+ * can raise it, within the platform's), and only while the task's device can reach it
+ * (`deviceReachesOpen: false`, `device_refuses`: a local device whose program applies no tiers
+ * runs every command in `strict`).
+ */
+export declare function tierGrantRefusal(key: string, ctx: {
+    ceiling: SandboxTier;
+    deviceReachesOpen?: boolean;
+}): {
+    code: GrantRefusalCode;
+    message: string;
+} | null;

package/dist/schedules/grant-rules.js

@@ -0,0 +1,126 @@
+import { validateAllowHost, } from "@capybara-hq/plugin-sdk";
+import { orgAllows } from "../local-devices/network-grants.js";
+import { roleAtLeast } from "../orgs/roles.js";
+import { isFixedAsk } from "../tools/fixed-ask.js";
+import { changesAgentSkills, TIER_GRANT_SPEC_HASH, TIER_OPEN_GRANT_KEY } from "./unattended.js";
+export { TIER_GRANT_SPEC_HASH, TIER_OPEN_GRANT_KEY };
+/**
+ * Why `toolKey` cannot be one of a task's grants, or null when it can: the creator could approve
+ * it with scope `always` themselves (no `requiredRole` above their role, not a fixed ask), it is
+ * the tool's own key (a per-call key such as `Platform:<operation>` is decided per call and never
+ * a task grant), it changes none of the agent's skills (an unattended run never does) and
+ * the org forbids neither the key nor the tool. `tool`: the agent's tool `toolKey` belongs to,
+ * undefined when the agent does not have it now.
+ */
+export function grantRefusalOf(toolKey, tool, ctx) {
+    if (ctx.forbiddenTools.includes(toolKey) ||
+        (tool !== undefined && ctx.forbiddenTools.includes(tool.key))) {
+        return {
+            code: "forbidden",
+            message: `The organization does not allow ${toolKey} in scheduled runs`,
+        };
+    }
+    if (changesAgentSkills(toolKey)) {
+        return {
+            code: "not_grantable",
+            message: `${toolKey} cannot be approved for a scheduled task: an unattended run never changes the agent's skills`,
+        };
+    }
+    if (!tool) {
+        return { code: "not_available", message: `${toolKey} is not one of the agent's tools now` };
+    }
+    if (toolKey !== tool.key) {
+        return {
+            code: "not_grantable",
+            message: `${toolKey} is decided per call and cannot be approved in advance for a scheduled task`,
+        };
+    }
+    if (tool.requiredRole !== undefined && !roleAtLeast(ctx.role, tool.requiredRole)) {
+        return {
+            code: "needs_role",
+            message: `${toolKey} needs the ${tool.requiredRole} role to approve; you cannot approve it for the task`,
+        };
+    }
+    if (isFixedAsk(tool)) {
+        return {
+            code: "fixed_ask",
+            message: `${toolKey} always asks a person and cannot be approved in advance`,
+        };
+    }
+    return null;
+}
+/** {@link grantRefusalOf}'s message alone; null when the tool can be granted. */
+export function grantRefusal(toolKey, tool, ctx) {
+    return grantRefusalOf(toolKey, tool, ctx)?.message ?? null;
+}
+/** The prefix of a network grant's key (network ask-to-allow spec §8.1). */
+export const NETWORK_GRANT_PREFIX = "network:";
+/** The `spec_hash` a network grant is stored with (no tool definition behind it; plan P-D7). */
+export const NETWORK_GRANT_SPEC_HASH = "network";
+/** Whether a grant key is a network grant (`network:<host>`). */
+export const isNetworkGrantKey = (key) => key.startsWith(NETWORK_GRANT_PREFIX);
+/** The host of a network grant key (`network:<host>`). */
+export const networkGrantHost = (key) => key.slice(NETWORK_GRANT_PREFIX.length);
+/**
+ * Why `host` cannot be one of a task's network grants (network ask-to-allow spec §8.1), or null
+ * when it can: `not_grantable` (not an exact, valid host name: no wildcard, no address),
+ * `needs_admin` (the org's effective egress does not admit it: only an org admin can add it),
+ * `device_refuses` (the task's device reports `remoteGrants: "off"`). The host is compared as given
+ * (callers lower-case it first).
+ */
+export function networkGrantRefusal(host, ctx) {
+    if (host.startsWith("*.") || validateAllowHost(host).length > 0) {
+        return {
+            code: "not_grantable",
+            message: `${host} cannot be approved for a scheduled task: give one exact domain name (no wildcard, no IP address or local name)`,
+        };
+    }
+    if (!orgAllows(host, ctx.limits)) {
+        return {
+            code: "needs_admin",
+            message: `${host} is not in the organization's network allowlist; only an organization admin can add it`,
+        };
+    }
+    if (ctx.deviceSummary?.remoteGrants === "off") {
+        return {
+            code: "device_refuses",
+            message: `The task's device does not accept network grants from the deployment; its owner can allow ${host} locally: capybara-device policy add allowedDomains ${host}`,
+        };
+    }
+    return null;
+}
+/** The prefix of a sandbox tier grant's key (sandbox dev tiers spec §11.4): only `tier:open` exists. */
+export const TIER_GRANT_PREFIX = "tier:";
+/** Whether a grant key is a sandbox tier grant (`tier:<tier>`). */
+export const isTierGrantKey = (key) => key.startsWith(TIER_GRANT_PREFIX);
+/** Whether a grant key names no tool: a network grant or a sandbox tier grant. */
+export const isPolicyGrantKey = (key) => isNetworkGrantKey(key) || isTierGrantKey(key);
+/**
+ * Why `key` cannot be a task's sandbox tier grant (sandbox dev tiers spec §11.4), or null when it
+ * can: only `tier:open` is one (`not_grantable` otherwise), and only while the org's ceiling
+ * (`ceiling`: its highest tier, cut to the platform's) is `open` (`needs_admin`: only an org admin
+ * can raise it, within the platform's), and only while the task's device can reach it
+ * (`deviceReachesOpen: false`, `device_refuses`: a local device whose program applies no tiers
+ * runs every command in `strict`).
+ */
+export function tierGrantRefusal(key, ctx) {
+    if (key !== TIER_OPEN_GRANT_KEY) {
+        return {
+            code: "not_grantable",
+            message: `${key} cannot be approved for a scheduled task; the only sandbox level a task can allow is ${TIER_OPEN_GRANT_KEY}`,
+        };
+    }
+    if (ctx.ceiling !== "open") {
+        return {
+            code: "needs_admin",
+            message: `The organization's highest sandbox level is ${ctx.ceiling}, so a scheduled task cannot allow the open level; only an organization admin can raise it`,
+        };
+    }
+    if (ctx.deviceReachesOpen === false) {
+        return {
+            code: "device_refuses",
+            message: "The task's device runs a capybara-device program without sandbox levels, so its commands always run at the strict level; update the program on the device, then allow the open level",
+        };
+    }
+    return null;
+}

package/dist/schedules/job-ids.d.ts

@@ -0,0 +1,32 @@
+/** The scheduled tasks' jobs (a leaf module: no imports). */
+/**
+ * The once-a-minute `@LockedCron` that turns due tasks into task runs (spec §6); its name enqueued
+ * on the maintenance queue runs one scan (`ScheduledRuns.runNow`).
+ */
+export declare const SCHED_SCAN_JOB = "scheduled-task-scan";
+/** The one-off job that checks and starts one task run, on `cap-kernel-maintenance`. */
+export declare const SCHED_FIRE_JOB = "sched-fire";
+/** The data of a {@link SCHED_FIRE_JOB}. */
+export interface SchedFireJobData {
+    taskRunId: string;
+}
+/** The fire job's id: `sched-fire-<taskRunId>` (no `:`, task run ids are UUIDs). */
+export declare const schedFireJobId: (taskRunId: string) => string;
+/**
+ * The fire job of one task run. Removed when done, so the scanner's repair can enqueue it again
+ * after a lost job; the fire is idempotent on the task run's status, so retries are safe.
+ */
+export declare function schedFireJob(taskRunId: string): {
+    name: string;
+    data: SchedFireJobData;
+    opts: {
+        jobId: string;
+        attempts: number;
+        backoff: {
+            type: "exponential";
+            delay: number;
+        };
+        removeOnComplete: true;
+        removeOnFail: true;
+    };
+};

package/dist/schedules/job-ids.js

@@ -0,0 +1,27 @@
+/** The scheduled tasks' jobs (a leaf module: no imports). */
+/**
+ * The once-a-minute `@LockedCron` that turns due tasks into task runs (spec §6); its name enqueued
+ * on the maintenance queue runs one scan (`ScheduledRuns.runNow`).
+ */
+export const SCHED_SCAN_JOB = "scheduled-task-scan";
+/** The one-off job that checks and starts one task run, on `cap-kernel-maintenance`. */
+export const SCHED_FIRE_JOB = "sched-fire";
+/** The fire job's id: `sched-fire-<taskRunId>` (no `:`, task run ids are UUIDs). */
+export const schedFireJobId = (taskRunId) => `${SCHED_FIRE_JOB}-${taskRunId}`;
+/**
+ * The fire job of one task run. Removed when done, so the scanner's repair can enqueue it again
+ * after a lost job; the fire is idempotent on the task run's status, so retries are safe.
+ */
+export function schedFireJob(taskRunId) {
+    return {
+        name: SCHED_FIRE_JOB,
+        data: { taskRunId },
+        opts: {
+            jobId: schedFireJobId(taskRunId),
+            attempts: 3,
+            backoff: { type: "exponential", delay: 2_000 },
+            removeOnComplete: true,
+            removeOnFail: true,
+        },
+    };
+}

package/dist/schedules/pause.d.ts

@@ -0,0 +1,9 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { SchedulePauseReason } from "./types.js";
+/**
+ * Pauses an active live task for `reason` in the caller's transaction `t` (the fire job, the run
+ * tracker, the delivery path); `by` is the account that caused it, null for the kernel. A task
+ * already paused or ended keeps its state and reason. A plain function so the run tracker, which
+ * the runtime imports, needs no service of the schedules domain.
+ */
+export declare function pauseTaskIn(t: KernelSchemaDb, taskId: string, reason: SchedulePauseReason, by: string | null): Promise<void>;

package/dist/schedules/pause.js

@@ -0,0 +1,33 @@
+import { sql } from "kysely";
+import { audit } from "../identity/audit.js";
+/**
+ * Pauses an active live task for `reason` in the caller's transaction `t` (the fire job, the run
+ * tracker, the delivery path); `by` is the account that caused it, null for the kernel. A task
+ * already paused or ended keeps its state and reason. A plain function so the run tracker, which
+ * the runtime imports, needs no service of the schedules domain.
+ */
+export async function pauseTaskIn(t, taskId, reason, by) {
+    const row = await t
+        .updateTable("scheduled_tasks")
+        .set({
+        status: "paused",
+        pause_reason: reason,
+        paused_by: by,
+        next_run_at: null,
+        updated_at: sql `now()`,
+    })
+        .where("id", "=", taskId)
+        .where("status", "=", "active")
+        .where("deleted_at", "is", null)
+        .returning(["org_id", "account_id"])
+        .executeTakeFirst();
+    if (!row)
+        return;
+    await audit(t, {
+        actorAccountId: by,
+        orgId: row.org_id,
+        action: "schedule.paused",
+        target: taskId,
+        detail: { reason, creator: row.account_id },
+    });
+}

package/dist/schedules/run-tracker.d.ts

@@ -0,0 +1,81 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.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 type { TaskRun } from "./types.js";
+/** How a kernel run ended (`runs.status` once terminal). */
+export type RunOutcome = "completed" | "failed" | "aborted";
+/**
+ * How long a task run that was started (its message created or queued) may show no trace of its
+ * message before the overlap check releases it: the fire job writes `fired_at` before it creates
+ * the conversation or queues the item, in a transaction of its own.
+ */
+export declare const START_GRACE_MS: number;
+/**
+ * Follows a task run's kernel run to its end (scheduled tasks spec §6). {@link onRunFinished} runs
+ * in the transaction that writes a run's terminal state (`RunFinish.finishIn`, the one writer of
+ * terminal states), so a task run never misses its run's end: a run aborted by a person counts as
+ * completed; a failed one counts against the task (`consecutive_failures`, paused at the org's
+ * `pauseAfterFailures`), a completed one resets the count. Trial runs do not count.
+ * {@link inFlightIn} is the overlap check's view of the task's previous run: it settles a run whose
+ * end was missed and releases one whose queued message is gone.
+ */
+export declare class ScheduledTaskRunTracker {
+    private readonly kdb;
+    readonly txHost: TransactionHost;
+    private readonly config;
+    constructor(kdb: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">);
+    private get db();
+    /**
+     * The kernel run `runId` ended with `outcome`: the task run it was started for (the run its
+     * message triggered, `scheduled_task_runs.run_id`) takes the outcome. A sub-agent or wake run
+     * that inherited the marker is not the task run's own and changes nothing.
+     */
+    onRunFinished(runId: string, outcome: RunOutcome, error?: string): Promise<void>;
+    /**
+     * Whether `prev`, a run of the task still `pending` or `running`, is really in flight (the
+     * overlap check, inside the fire's transaction). Settled on the way: a running one whose kernel
+     * run already ended takes its outcome; a started one linked to its run now when the run exists;
+     * a started one whose message another run consumed (`consumed_seq`, no run of its own) ends
+     * `completed`; a started one with no queued item, no message and no run after {@link START_GRACE_MS} (its
+     * queued item was removed or the queue cleared without the queue's own hook) becomes `skipped`
+     * (`removed`). The marker alone decides what is the task's message, never a client message id.
+     */
+    inFlightIn(prev: TaskRun, now?: Date): Promise<boolean>;
+    /**
+     * A pending task run whose start was refused (the fire job could not create or queue its
+     * message, for a reason that is not a lasting skip): it fails and counts against the task like
+     * a failed run (`consecutive_failures`, paused at the org's `pauseAfterFailures`), a trial run
+     * excepted. In the caller's transaction, which holds the task row.
+     */
+    failStartIn(taskRunId: string, error: string): Promise<void>;
+    /** Writes the task run's end and the task's failure count (non-trial runs). */
+    private settle;
+}
+/**
+ * A kernel run was created for task run `taskRunId` (its message is the run's trigger, or it
+ * inherited the marker): a task run still `pending` takes the run (`running`), in the caller's
+ * transaction (`RunQueue.ensureRunIn`, which inserts the run). A task run already linked (a
+ * sub-agent or wake run inheriting the marker) is left alone.
+ */
+export declare function linkStartedRunIn(t: KernelSchemaDb, taskRunId: string, runId: string, conversationId: string): Promise<void>;
+/**
+ * A queued run row was taken back before it ran (`RunQueue.deleteQueued`: its job could not be
+ * enqueued): the task run it had taken waits for the next run of its message again.
+ */
+export declare function unlinkRunIn(t: KernelSchemaDb, taskRunId: string, runId: string): Promise<void>;
+/**
+ * A person removed, edited or sent the queued item that carried `schedule` (the item's stored
+ * marker, or null): its task run will never run as the task's, so it becomes `skipped`
+ * (`removed`) in the caller's transaction, and the next tick is not held by the overlap check.
+ */
+export declare function releaseQueuedTaskRunIn(t: KernelSchemaDb, schedule: unknown): Promise<void>;
+/**
+ * Locks a task's row (deleted or not) in the caller's transaction. Every path that locks a task
+ * run and the task takes the task row first: the fire job's claim, the run tracker, the scan's
+ * repair (a run finishing while the next tick's claim checks overlap must not deadlock).
+ */
+export declare function lockTaskRow(t: KernelSchemaDb, taskId: string): Promise<void>;
+/** The run tracker alone: the runtime (`RunFinish`) imports it without the schedules service. */
+export declare class ScheduledTaskTrackerModule {
+}