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

package/dist/schedules/store.js

@@ -0,0 +1,390 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+const NON_TERMINAL = ["pending", "running"];
+const date = (v) => (v instanceof Date ? v : new Date(v));
+const dateOrNull = (v) => (v === null ? null : date(v));
+const toTask = (r) => ({
+    id: r.id,
+    orgId: r.org_id,
+    accountId: r.account_id,
+    agentId: r.agent_id,
+    name: r.name,
+    prompt: r.prompt,
+    trigger: r.trigger,
+    mode: r.mode,
+    conversationId: r.conversation_id,
+    chat: r.chat,
+    model: r.model,
+    effort: r.effort,
+    deviceId: r.device_id,
+    status: r.status,
+    pauseReason: r.pause_reason,
+    pausedBy: r.paused_by,
+    nextRunAt: dateOrNull(r.next_run_at),
+    jitterSeconds: r.jitter_seconds,
+    expiresAt: dateOrNull(r.expires_at),
+    consecutiveFailures: r.consecutive_failures,
+    createdAt: date(r.created_at),
+    updatedAt: date(r.updated_at),
+});
+const toRun = (r) => ({
+    id: r.id,
+    taskId: r.task_id,
+    orgId: r.org_id,
+    scheduledFor: date(r.scheduled_for),
+    firedAt: dateOrNull(r.fired_at),
+    trial: r.trial,
+    manual: r.manual,
+    conversationId: r.conversation_id,
+    runId: r.run_id,
+    status: r.status,
+    skipReason: r.skip_reason,
+    error: r.error,
+    missingGrants: r.missing_grants,
+});
+const json = (v) => (v === null ? null : JSON.stringify(v));
+/** Maps a task patch to its columns; fields left undefined are not written. */
+function taskColumns(p) {
+    const c = {};
+    if (p.agentId !== undefined)
+        c.agent_id = p.agentId;
+    if (p.name !== undefined)
+        c.name = p.name;
+    if (p.prompt !== undefined)
+        c.prompt = p.prompt;
+    if (p.trigger !== undefined)
+        c.trigger = JSON.stringify(p.trigger);
+    if (p.mode !== undefined)
+        c.mode = p.mode;
+    if (p.conversationId !== undefined)
+        c.conversation_id = p.conversationId;
+    if (p.chat !== undefined)
+        c.chat = json(p.chat);
+    if (p.model !== undefined)
+        c.model = json(p.model);
+    if (p.effort !== undefined)
+        c.effort = p.effort;
+    if (p.deviceId !== undefined)
+        c.device_id = p.deviceId;
+    if (p.status !== undefined)
+        c.status = p.status;
+    if (p.pauseReason !== undefined)
+        c.pause_reason = p.pauseReason;
+    if (p.pausedBy !== undefined)
+        c.paused_by = p.pausedBy;
+    if (p.nextRunAt !== undefined)
+        c.next_run_at = p.nextRunAt;
+    if (p.jitterSeconds !== undefined)
+        c.jitter_seconds = p.jitterSeconds;
+    if (p.expiresAt !== undefined)
+        c.expires_at = p.expiresAt;
+    if (p.consecutiveFailures !== undefined)
+        c.consecutive_failures = p.consecutiveFailures;
+    return c;
+}
+/**
+ * Scheduled tasks, their runs and grants (spec §4): reads and writes rows only. Every method takes
+ * the database handle first so the caller decides the transaction (the scanner's `lockDue` and
+ * `insertRun` run in one, under the rows' locks).
+ */
+let ScheduledTaskStore = class ScheduledTaskStore {
+    async insertTask(t, task) {
+        const row = await t
+            .insertInto("scheduled_tasks")
+            .values({
+            id: task.id,
+            org_id: task.orgId,
+            account_id: task.accountId,
+            agent_id: task.agentId,
+            name: task.name,
+            prompt: task.prompt,
+            trigger: JSON.stringify(task.trigger),
+            mode: task.mode,
+            conversation_id: task.conversationId,
+            chat: json(task.chat),
+            model: json(task.model),
+            effort: task.effort,
+            device_id: task.deviceId,
+            status: task.status,
+            next_run_at: task.nextRunAt,
+            jitter_seconds: task.jitterSeconds,
+            expires_at: task.expiresAt,
+        })
+            .returningAll()
+            .executeTakeFirstOrThrow();
+        return toTask(row);
+    }
+    /** A live (not deleted) task of the org; null when missing, deleted or in another org. */
+    async getTask(t, orgId, id) {
+        const row = await t
+            .selectFrom("scheduled_tasks")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("id", "=", id)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return row ? toTask(row) : null;
+    }
+    /**
+     * {@link getTask} under `FOR UPDATE` (call it inside a transaction): a person's write holds the
+     * row, so the scanner's `lockDue` skips it until the write commits.
+     */
+    async lockTask(t, orgId, id) {
+        const row = await t
+            .selectFrom("scheduled_tasks")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("id", "=", id)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
+        return row ? toTask(row) : null;
+    }
+    /** Patches a live task; null when it is missing or deleted. */
+    async updateTask(t, id, patch) {
+        const row = await t
+            .updateTable("scheduled_tasks")
+            .set({ ...taskColumns(patch), updated_at: sql `now()` })
+            .where("id", "=", id)
+            .where("deleted_at", "is", null)
+            .returningAll()
+            .executeTakeFirst();
+        return row ? toTask(row) : null;
+    }
+    /** Deletes a task softly: hidden from every read and never due again. */
+    async softDelete(t, id) {
+        const r = await t
+            .updateTable("scheduled_tasks")
+            .set({ deleted_at: sql `now()`, updated_at: sql `now()`, next_run_at: null })
+            .where("id", "=", id)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        return Number(r.numUpdatedRows) > 0;
+    }
+    /** A creator's live tasks, newest first. */
+    async listForAccount(t, orgId, accountId) {
+        const rows = await t
+            .selectFrom("scheduled_tasks")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("account_id", "=", accountId)
+            .where("deleted_at", "is", null)
+            .orderBy("created_at", "desc")
+            .orderBy("id")
+            .execute();
+        return rows.map(toTask);
+    }
+    /** Every live task of the org, newest first. */
+    async listForOrg(t, orgId) {
+        const rows = await t
+            .selectFrom("scheduled_tasks")
+            .selectAll()
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .orderBy("created_at", "desc")
+            .orderBy("id")
+            .execute();
+        return rows.map(toTask);
+    }
+    /** Live tasks that count against the caps (`active` and `paused`), of the org or one creator. */
+    async countActive(t, orgId, accountId) {
+        let q = t
+            .selectFrom("scheduled_tasks")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .where("status", "in", ["active", "paused"]);
+        if (accountId !== undefined)
+            q = q.where("account_id", "=", accountId);
+        const row = await q.executeTakeFirstOrThrow();
+        return Number(row.n);
+    }
+    /**
+     * Locks up to `limit` due tasks (active, live, `next_run_at <= now`), oldest first, skipping
+     * rows another transaction holds (`FOR UPDATE SKIP LOCKED`). Call it inside a transaction: the
+     * locks last until it ends.
+     */
+    async lockDue(t, now, limit) {
+        const rows = await t
+            .selectFrom("scheduled_tasks")
+            .selectAll()
+            .where("status", "=", "active")
+            .where("deleted_at", "is", null)
+            .where("next_run_at", "<=", now)
+            .orderBy("next_run_at")
+            .orderBy("id")
+            .limit(limit)
+            .forUpdate()
+            .skipLocked()
+            .execute();
+        return rows.map(toTask);
+    }
+    /**
+     * Inserts a task run; null when a non-trial run for the same tick already exists (the
+     * exactly-once guard, `UNIQUE (task_id, scheduled_for) WHERE NOT trial`).
+     */
+    async insertRun(t, run) {
+        const row = await t
+            .insertInto("scheduled_task_runs")
+            .values({
+            id: run.id,
+            task_id: run.taskId,
+            org_id: run.orgId,
+            scheduled_for: run.scheduledFor,
+            trial: run.trial,
+            manual: run.manual ?? false,
+            status: run.status ?? "pending",
+            skip_reason: run.skipReason ?? null,
+            fired_at: run.firedAt ?? null,
+            conversation_id: run.conversationId ?? null,
+        })
+            .onConflict((oc) => oc.columns(["task_id", "scheduled_for"]).where("trial", "=", false).doNothing())
+            .returningAll()
+            .executeTakeFirst();
+        return row ? toRun(row) : null;
+    }
+    /** Patches a task run; null when it does not exist. */
+    async updateRun(t, id, patch) {
+        const c = {};
+        if (patch.scheduledFor !== undefined)
+            c.scheduled_for = patch.scheduledFor;
+        if (patch.firedAt !== undefined)
+            c.fired_at = patch.firedAt;
+        if (patch.conversationId !== undefined)
+            c.conversation_id = patch.conversationId;
+        if (patch.runId !== undefined)
+            c.run_id = patch.runId;
+        if (patch.status !== undefined)
+            c.status = patch.status;
+        if (patch.skipReason !== undefined)
+            c.skip_reason = patch.skipReason;
+        if (patch.error !== undefined)
+            c.error = patch.error;
+        if (patch.missingGrants !== undefined)
+            c.missing_grants = JSON.stringify(patch.missingGrants);
+        if (Object.keys(c).length === 0) {
+            const row = await t
+                .selectFrom("scheduled_task_runs")
+                .selectAll()
+                .where("id", "=", id)
+                .executeTakeFirst();
+            return row ? toRun(row) : null;
+        }
+        const row = await t
+            .updateTable("scheduled_task_runs")
+            .set(c)
+            .where("id", "=", id)
+            .returningAll()
+            .executeTakeFirst();
+        return row ? toRun(row) : null;
+    }
+    /**
+     * The task's latest run still `pending` or `running` (the overlap check), other than `exceptId`
+     * (the run being fired); null when none.
+     */
+    async latestNonTerminalRun(t, taskId, exceptId) {
+        let q = t
+            .selectFrom("scheduled_task_runs")
+            .selectAll()
+            .where("task_id", "=", taskId)
+            .where("status", "in", NON_TERMINAL);
+        if (exceptId !== undefined)
+            q = q.where("id", "!=", exceptId);
+        const row = await q
+            .orderBy("scheduled_for", "desc")
+            .orderBy("id", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        return row ? toRun(row) : null;
+    }
+    /**
+     * Runs of the org fired at or after `since` (the `maxRunsPerHour` count; trial runs included,
+     * skipped runs not: a run whose queued message a person removed was never run).
+     */
+    async countFiredSince(t, orgId, since) {
+        const row = await t
+            .selectFrom("scheduled_task_runs")
+            .select((eb) => eb.fn.countAll().as("n"))
+            .where("org_id", "=", orgId)
+            .where("fired_at", ">=", since)
+            .where("status", "!=", "skipped")
+            .executeTakeFirstOrThrow();
+        return Number(row.n);
+    }
+    /** A task's runs, latest tick first. */
+    async listRuns(t, taskId, limit) {
+        const rows = await t
+            .selectFrom("scheduled_task_runs")
+            .selectAll()
+            .where("task_id", "=", taskId)
+            .orderBy("scheduled_for", "desc")
+            .orderBy("id", "desc")
+            .limit(limit)
+            .execute();
+        return rows.map(toRun);
+    }
+    async listGrants(t, taskId) {
+        const rows = await t
+            .selectFrom("scheduled_task_grants")
+            .select(["tool_key", "spec_hash", "connector_id"])
+            .where("task_id", "=", taskId)
+            .orderBy("tool_key")
+            .execute();
+        return rows.map((r) => ({
+            toolKey: r.tool_key,
+            specHash: r.spec_hash,
+            connectorId: r.connector_id,
+        }));
+    }
+    /** Adds a grant, replacing the task's grant of the same tool key. */
+    async addGrant(t, taskId, grant) {
+        await t
+            .insertInto("scheduled_task_grants")
+            .values({
+            task_id: taskId,
+            tool_key: grant.toolKey,
+            spec_hash: grant.specHash,
+            connector_id: grant.connectorId,
+        })
+            .onConflict((oc) => oc.columns(["task_id", "tool_key"]).doUpdateSet({
+            spec_hash: grant.specHash,
+            connector_id: grant.connectorId,
+            created_at: sql `now()`,
+        }))
+            .execute();
+    }
+    async removeGrant(t, taskId, toolKey) {
+        const r = await t
+            .deleteFrom("scheduled_task_grants")
+            .where("task_id", "=", taskId)
+            .where("tool_key", "=", toolKey)
+            .executeTakeFirst();
+        return Number(r.numDeletedRows) > 0;
+    }
+};
+ScheduledTaskStore = __decorate([
+    Injectable()
+], ScheduledTaskStore);
+export { ScheduledTaskStore };
+/**
+ * Whether the task holds a grant for this tool as defined now: same key, same spec hash, same
+ * connector (null for plugin and builtin tools). A grant of an older definition does not count.
+ * A plain function too, for the tool policy (`createDecidePolicy`), which is not a provider.
+ */
+export async function findTaskGrant(t, taskId, toolKey, specHash, connectorId) {
+    const row = await t
+        .selectFrom("scheduled_task_grants")
+        .select("tool_key")
+        .where("task_id", "=", taskId)
+        .where("tool_key", "=", toolKey)
+        .where("spec_hash", "=", specHash)
+        .where(sql `connector_id IS NOT DISTINCT FROM ${connectorId}`)
+        .executeTakeFirst();
+    return row !== undefined;
+}

package/dist/schedules/store.module.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The scheduled task store alone, so the scanner (worker), the fire job, the HTTP API and the
+ * schedule tools can each import it without importing one another.
+ */
+export declare class ScheduledTaskStoreModule {
+}

package/dist/schedules/store.module.js

@@ -0,0 +1,21 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { ScheduledTaskStore } from "./store.js";
+/**
+ * The scheduled task store alone, so the scanner (worker), the fire job, the HTTP API and the
+ * schedule tools can each import it without importing one another.
+ */
+let ScheduledTaskStoreModule = class ScheduledTaskStoreModule {
+};
+ScheduledTaskStoreModule = __decorate([
+    Module({
+        providers: [ScheduledTaskStore],
+        exports: [ScheduledTaskStore],
+    })
+], ScheduledTaskStoreModule);
+export { ScheduledTaskStoreModule };

package/dist/schedules/types.d.ts

@@ -0,0 +1,108 @@
+import type { ModelRef } from "../agents/definition.js";
+/**
+ * Scheduled tasks (spec 2026-11-11-scheduled-tasks-design.md §4): the shapes the kernel reads and
+ * writes. The rows live in `capybara.scheduled_tasks`, `scheduled_task_runs` and
+ * `scheduled_task_grants` (migration 0113).
+ */
+/** When a task fires: a 5-field cron, or once at a local date-time, both in an IANA zone (§5). */
+export type ScheduleTrigger = {
+    kind: "cron";
+    expr: string;
+    timeZone: string;
+} | {
+    kind: "once";
+    at: string;
+    timeZone: string;
+};
+/** Where a run posts: a new conversation, one existing conversation, or an IM chat (§3). */
+export type ScheduleMode = "new" | "conversation" | "chat";
+/** The IM chat a `chat`-mode task posts into. */
+export interface ScheduleChat {
+    connectionId: string;
+    chatId: string;
+    chatType: "dm" | "group";
+}
+export type ScheduleStatus = "active" | "paused" | "ended";
+export type SchedulePauseReason = "creator" | "admin" | "failures" | "creator_inactive" | "agent_gone" | "target_gone" | "conversation_gone" | "org_disabled" | "expired"
+/** The stored trigger cannot be evaluated (the scanner stops selecting the task). */
+ | "invalid_schedule";
+export type TaskRunStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+export type TaskRunSkipReason = "missed" | "overlap" | "rate_limited" | "queue_paused" | "removed" | "device_offline" | "creator_inactive" | "agent_gone" | "target_gone" | "conversation_gone" | "org_disabled"
+/** A group chat on a channel without threads (a group run needs its own thread). */
+ | "unsupported_target"
+/** The task was deleted after the run was recorded. */
+ | "task_deleted"
+/** The task was paused after the scan recorded the tick (a "run now" still runs). */
+ | "task_paused";
+/** A task as the kernel reads it: the columns of `capybara.scheduled_tasks`, camel-cased. */
+export interface ScheduledTask {
+    id: string;
+    orgId: string;
+    /** The creator: every run acts as this account. */
+    accountId: string;
+    agentId: string;
+    name: string;
+    prompt: string;
+    trigger: ScheduleTrigger;
+    mode: ScheduleMode;
+    /** The target conversation (`conversation` mode only). */
+    conversationId: string | null;
+    /** The target chat (`chat` mode only). */
+    chat: ScheduleChat | null;
+    /** Null = the agent's default model. */
+    model: ModelRef | null;
+    /** Null = the agent's default effort. */
+    effort: string | null;
+    /** Null = the default pick for new conversations. */
+    deviceId: string | null;
+    status: ScheduleStatus;
+    pauseReason: SchedulePauseReason | null;
+    /** The account that paused the task (creator or admin); null when not paused by a person. */
+    pausedBy: string | null;
+    /** The next fire time, jitter included; null when the task is not active. */
+    nextRunAt: Date | null;
+    jitterSeconds: number;
+    expiresAt: Date | null;
+    consecutiveFailures: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** One tick of a task (or a trial run): the columns of `capybara.scheduled_task_runs`. */
+export interface TaskRun {
+    id: string;
+    taskId: string;
+    orgId: string;
+    /** The tick, before jitter (for a trial run: when it was requested). */
+    scheduledFor: Date;
+    firedAt: Date | null;
+    trial: boolean;
+    /** A person's "run now" (trial or not), outside the schedule. */
+    manual: boolean;
+    conversationId: string | null;
+    runId: string | null;
+    status: TaskRunStatus;
+    skipReason: TaskRunSkipReason | null;
+    error: string | null;
+    /** Tool keys refused for lack of a grant (§7). */
+    missingGrants: string[];
+}
+/**
+ * The marker a task's message carries (`conversation_queue.schedule`, then `user_message`): not
+ * model-visible as such; `taskName` and `localTime` feed the English header the model sees.
+ */
+export interface ScheduleMarker {
+    taskId: string;
+    taskRunId: string;
+    /** ISO timestamp of the tick. */
+    scheduledFor: string;
+    trial: boolean;
+    taskName: string;
+    /** The tick in the task's zone, as the header shows it. */
+    localTime: string;
+}
+/** A remembered "always allow" of a task (same meaning as `conversation_tool_grants`). */
+export interface ScheduledTaskGrant {
+    toolKey: string;
+    specHash: string;
+    connectorId: string | null;
+}

package/dist/schedules/types.js

@@ -0,0 +1 @@
+export {};

package/dist/schedules/unattended.d.ts

@@ -0,0 +1,117 @@
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import type { KernelConfigService } from "../infra/config/kernel-config.service.js";
+/**
+ * The scheduled task run a kernel run serves (scheduled tasks spec §4, §7), or null for an attended
+ * run: `runs.scheduled_task_run_id`, set on the run a task's message triggered and inherited by the
+ * runs descending from it without a person (sub-agent runs, wake runs). A run whose task run row is
+ * gone is treated as attended.
+ */
+export declare function unattendedTaskRunOf(db: KernelSchemaDb, runId: string): Promise<{
+    taskRunId: string;
+    taskId: string;
+    trial: boolean;
+} | null>;
+/**
+ * The `scheduled_task_run_id` a new run whose boundary (`runs.trigger_seq`) is event `seq` of
+ * `conversationId` gets (scheduled tasks spec §4), read in the caller's transaction:
+ * - a `user_message`: its schedule marker's task run; a sub-agent's task or `SendMessage` message
+ *   (`dispatch`): what its parent run has; a person's message: null;
+ * - a `background_task_finished`: what the run that launched the task has;
+ * - a `subagent_delivery`: what the child run that delivered it has (it inherited from its parent);
+ * - anything else, or no such event: null.
+ */
+export declare function scheduledTaskRunAt(t: KernelSchemaDb, conversationId: string, seq: number | string): Promise<string | null>;
+/** The tool result of an ask outside the task's grants in an unattended run, `fail` mode (§7). */
+export declare const UNATTENDED_ASK_ERROR: (tool: string) => string;
+/**
+ * The Platform operations that change an agent's skills: an unattended run never calls them
+ * without a person (spec §7), even where a private agent's owner would not be asked. Each is a
+ * fixed ask there, outside every grant.
+ */
+export declare const UNATTENDED_SKILL_OPERATIONS: ReadonlySet<string>;
+/** Whether a call's policy key (`Platform:<operation>`) is one of {@link UNATTENDED_SKILL_OPERATIONS}. */
+export declare function changesAgentSkills(policyKey: string): boolean;
+/**
+ * The result of a fixed ask (R3, `requiresUserInteraction`, a skill change unattended, a per-call
+ * policy that never remembers) in an unattended run, `fail` mode: no grant can ever cover it, so
+ * it is not a missing grant either.
+ */
+export declare const UNATTENDED_FIXED_ASK_ERROR: (tool: string) => string;
+/** The result of `AskUserQuestion` (or any other input request) in an unattended run, `fail` mode. */
+export declare const UNATTENDED_QUESTION_ERROR = "No one is present in this scheduled run; decide with the information you have, or state the open question in your final answer.";
+/** The result of a call that needs the creator's personal connection, unattended, `fail` mode. */
+export declare const UNATTENDED_CONNECTION_ERROR: (connector: string) => string;
+/** The note on a connector call whose elicitation was declined in an unattended run (`fail`). */
+export declare const UNATTENDED_ELICITATION_NOTE = "[The app asked for user input, but no one is present in this scheduled run, so the request was declined. Decide with the information you have, or state the open question in your final answer.]";
+/** The `missing_grants` entry of a personal connector the creator has not connected (§7). */
+export declare const connectionGrantKey: (connectorSlug: string) => string;
+/** The `missing_grants` entry of a refused network host (network ask-to-allow spec §8.1, §8.3). */
+export declare const networkGrantKey: (host: string) => string;
+/**
+ * What the tool policy knows of the scheduled task run a kernel run serves (`PolicyContext`): the
+ * task (its grants), the task run (its `missing_grants`), whether it is a trial run (attended), and
+ * the org's `unattendedAsk` and `forbiddenTools`, read live.
+ */
+export interface UnattendedRun {
+    taskId: string;
+    taskRunId: string;
+    trial: boolean;
+    unattendedAsk: "fail" | "wait";
+    forbiddenTools: string[];
+}
+/** An unattended run that is not a trial run: the §7 rules apply. */
+export declare const unattendedRules: (u: UnattendedRun | null | undefined) => u is UnattendedRun;
+/** In `fail` mode, an unattended run never waits for a person (§7). */
+export declare const unattendedFails: (u: UnattendedRun | null | undefined) => boolean;
+/**
+ * The scheduled task context of a run's tool calls (`PolicyContext.unattended`), or null when the
+ * run is attended: it serves no task run, or a person's message joined it ({@link personJoined}).
+ * A trial run is returned with `trial: true` (attended; its approvals become task grants).
+ */
+export declare function unattendedRunOf(db: KernelSchemaDb, config: Pick<KernelConfigService, "get">, orgId: string, runId: string): Promise<UnattendedRun | null>;
+/**
+ * The scheduled task whose grants a run's actions use (spec §7; network ask-to-allow spec §8.1),
+ * or null: the run serves a task run that is no trial run and no person joined
+ * ({@link personJoined}): the same rule as {@link unattendedRules} on {@link unattendedRunOf},
+ * without the org's settings. `accountId`: the task's creator; `orgId`: the task's org.
+ */
+export declare function taskGrantsRunOf(db: KernelSchemaDb, runId: string): Promise<{
+    taskId: string;
+    accountId: string;
+    orgId: string;
+} | null>;
+/**
+ * Appends a key to a task run's `missing_grants` (a tool key, or `connection:<slug>`), once: one
+ * atomic update, so parallel calls of a run and of its sub-agents never lose or repeat a key.
+ */
+export declare function appendMissingGrant(db: KernelSchemaDb, taskRunId: string, key: string): Promise<void>;
+/**
+ * The task grant that lets an unattended run use the open sandbox tier (sandbox dev tiers spec
+ * §11.4): without it a run of a scheduled task is capped at `dev` on a local device, and refused
+ * on an unsandboxed local device or a cloud device whose tier is open.
+ */
+export declare const TIER_OPEN_GRANT_KEY = "tier:open";
+/** The `spec_hash` the `tier:open` grant is stored with (no tool definition behind it). */
+export declare const TIER_GRANT_SPEC_HASH = "tier";
+/**
+ * The tier rule of an unattended run on `deviceId` (spec §11.4), or null when the run is attended
+ * (no task run, a trial run, or a person joined: the same rule as {@link taskGrantsRunOf}).
+ * `openGranted`: the task holds the `tier:open` grant and `deviceId` is a live device of the task's
+ * org owned by its creator (a creator approves for their own devices only, as with network
+ * grants). A deleted task grants nothing.
+ */
+export declare function unattendedTierOf(db: KernelSchemaDb, runId: string, deviceId: string): Promise<{
+    taskRunId: string;
+    taskId: string;
+    openGranted: boolean;
+} | null>;
+/**
+ * The tool error of a scheduled run on a device whose tier is open (cloud) without the task's
+ * `tier:open` grant (spec §11.4).
+ */
+export declare const UNATTENDED_OPEN_TIER_ERROR = "This device's sandbox level is open, which a scheduled run may use only when its task allows the open sandbox level; the task's owner can add tier:open to the task's approved tools, or lower the device's sandbox level.";
+/**
+ * The tool error of a scheduled run on a device that runs commands without a sandbox, without
+ * the task's `tier:open` grant (spec §11.4).
+ */
+export declare const UNATTENDED_UNSANDBOXED_ERROR = "This device runs commands without a sandbox, which a scheduled run may use only when its task allows the open sandbox level; the task's owner can add tier:open to the task's approved tools, or the device's owner can turn the sandbox back on with `capybara-device policy set isolation sandbox`.";