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

package/dist/schedules/scheduled-tasks.service.d.ts

@@ -0,0 +1,351 @@
+import type { Queue } from "bullmq";
+import { AgentLookup } from "../agents/agent-lookup.js";
+import type { ModelRef } from "../agents/definition.js";
+import { ConversationAccess } from "../conversations/access.js";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+import { ExtensionRegistry } from "../extensions/registry.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 { DevicePolicyService } from "../local-devices/device-policy.service.js";
+import type { KernelLogger } from "../log.js";
+import { OrgLock } from "../orgs/org-lock.js";
+import { ProviderRegistry } from "../runtime/providers.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { ToolRegistry } from "../tools/registry.js";
+import { type GrantContext, type GrantRefusalCode, grantRefusal, grantRefusalOf, networkGrantRefusal } from "./grant-rules.js";
+import { ScheduledTaskStore } from "./store.js";
+import type { ScheduleChat, ScheduledTask, ScheduledTaskGrant, ScheduleMode, SchedulePauseReason, TaskRun } from "./types.js";
+export { type GrantContext, type GrantRefusalCode, grantRefusal, grantRefusalOf, networkGrantRefusal, };
+/** When a task fires, before the zone is fixed (spec §5). */
+export type TriggerInput = {
+    kind: "cron";
+    expr: string;
+} | {
+    kind: "once";
+    at: string;
+};
+/** A scheduled task that needs its creator's attention (spec §8): the inbox item's payload. */
+export interface ScheduleAttention {
+    taskId: string;
+    name: string;
+    /**
+     * `missing_grants`: the latest run was refused tools or connections the task lacks; `failed`:
+     * the latest settled run of an active task failed (its start included); else the pause reason.
+     */
+    reason: SchedulePauseReason | "missing_grants" | "failed";
+    /** The person who paused the task (`reason: "admin"` names the admin); else null. */
+    pausedBy: {
+        id: string;
+        name: string;
+    } | null;
+    /**
+     * `missing_grants` only: tool keys the latest run was refused and the task has no grant for now,
+     * `connection:<slug>` (connect that connector), or `network:<host>` (a domain the run was
+     * refused: the task has no grant for it, or the org's network allowlist no longer admits it).
+     */
+    missing: string[];
+    /** The subset of `missing` the creator cannot pre-approve (the tool needs a higher role). */
+    needsRole: string[];
+    /**
+     * The `network:<host>` keys of `missing` outside the org's network allowlist: only an org admin
+     * can add the host (network ask-to-allow spec §8.3); the creator cannot pre-approve them.
+     */
+    needsAdmin: string[];
+    /**
+     * `missing` holds `network:` keys and the task's device reports it takes no network grants from
+     * the deployment (`remoteGrants` off): a task grant would not reach it; its owner allows the
+     * domains locally (`capybara-device policy add allowedDomains <host>`).
+     */
+    deviceRefuses: boolean;
+    /** `failed` only: the run's error; else null. */
+    error: string | null;
+    /** When the pause happened, or when the refused or failed run was due. */
+    at: Date;
+}
+/**
+ * A tool the creator pre-approves for the task; the service resolves its current `spec_hash`. Or a
+ * domain (`toolKey: "network:<host>"`, network ask-to-allow spec §8.1): one exact host the task's
+ * unattended runs may reach on the task's device, checked by `networkGrantRefusal`.
+ */
+export interface GrantInput {
+    toolKey: string;
+    /** The connector the tool comes from; when given it must be the tool's own. */
+    connectorId?: string;
+}
+export interface CreateTaskInput {
+    agentId: string;
+    name: string;
+    prompt: string;
+    trigger: TriggerInput;
+    /** Absent: the creator's effective zone (account, browser, org, UTC). */
+    timeZone?: string;
+    mode: ScheduleMode;
+    /** `conversation` mode only. */
+    conversationId?: string;
+    /** `chat` mode only. */
+    chat?: ScheduleChat;
+    /**
+     * `new` mode only (a conversation or chat task runs with that conversation's selection and
+     * device): the model, which must resolve for the org, and an effort it declares.
+     */
+    model?: ModelRef;
+    effort?: string;
+    deviceId?: string;
+    /**
+     * When the task ends; it must lie in the future. Absent or null: for a cron task, now + the
+     * org's `defaultExpiryDays` when set; otherwise never.
+     */
+    expiresAt?: Date | null;
+    grants?: GrantInput[];
+}
+/**
+ * Fields to change; `null` clears an optional one (`expiresAt: null` is the org's default expiry
+ * for a cron task, as on create). Grants change through their own methods.
+ */
+export interface UpdateTaskInput {
+    agentId?: string;
+    name?: string;
+    prompt?: string;
+    trigger?: TriggerInput;
+    timeZone?: string;
+    mode?: ScheduleMode;
+    conversationId?: string | null;
+    chat?: ScheduleChat | null;
+    model?: ModelRef | null;
+    effort?: string | null;
+    deviceId?: string | null;
+    expiresAt?: Date | null;
+}
+/**
+ * Where a grant write comes from: `fromSession` only for a person in a signed-in web session (not a
+ * personal access token, the Platform tool or the schedule tools). Network domains are approved
+ * only there (network ask-to-allow spec §8.1): an agent must never pre-approve a domain for itself.
+ */
+export interface GrantWriteSource {
+    fromSession?: boolean;
+}
+/** Who acts on a task: the service reads their live role itself and decides by that one. */
+export interface ScheduleActor {
+    accountId: string;
+}
+/** One of the agent's tools as the task form offers it (`GET …/schedules/grantable-tools`). */
+export interface GrantableTool {
+    key: string;
+    /** The tool's display title, when it declares one. */
+    title: string | null;
+    source: "builtin" | "plugin" | "connector";
+    connectorId: string | null;
+    grantable: boolean;
+    /** Why not, when not grantable. */
+    reason: GrantRefusalCode | null;
+}
+/**
+ * A grant as the task page shows it: `stale` when the tool's definition changed or the tool left
+ * (spec §7); null when the agent's tools cannot be read now.
+ */
+export interface ScheduledTaskGrantView extends ScheduledTaskGrant {
+    stale: boolean | null;
+}
+/** The latest settled (completed, failed or skipped) non-trial run of a task. */
+export interface TaskLastRun {
+    status: "completed" | "failed" | "skipped";
+    skipReason: TaskRun["skipReason"];
+    /** When it fired; its tick for a skipped one. */
+    at: Date;
+}
+/** A task in a list, with its latest settled run. */
+export type ScheduledTaskListItem = ScheduledTask & {
+    lastRun: TaskLastRun | null;
+};
+/**
+ * A chat the creator can point a `chat` task at (spec §8): their DM with a connection's bot
+ * (a thread row of theirs, archived included), or a group they have talked in when the channel
+ * has threads.
+ */
+export interface ChatTarget {
+    connectionId: string;
+    connectionName: string;
+    plugin: string;
+    /** The connection's agent: a chat task's agent. */
+    agentId: string;
+    chatId: string;
+    chatType: "dm" | "group";
+    /** A name for people: the connection's name (and the group's chat id). */
+    label: string;
+}
+/**
+ * Scheduled tasks for people (spec §5, §7–§10): create, edit, pause, resume, delete, their runs
+ * and grants. Every write runs in one transaction under the org row lock (`OrgLock`), which also
+ * serializes the per-member and per-org caps, re-reads the actor's role there, and holds the task
+ * row (`FOR UPDATE`) so the scanner skips it until the write commits.
+ *
+ * Roles: `schedules.use` (member) creates and edits one's own tasks; `schedules.manage` (admin)
+ * lists, pauses, resumes and deletes any task of the org, never edits another person's (the task
+ * runs as its creator). A task the caller may not see is `schedule.not_found`.
+ */
+export declare class ScheduledTasksService {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly config;
+    private readonly store;
+    private readonly orgLock;
+    private readonly agents;
+    private readonly access;
+    private readonly tools;
+    private readonly extensions;
+    /** A task's model must resolve for the org and declare its effort (as a message's switch). */
+    private readonly providers;
+    private readonly log;
+    /** "Run now" enqueues the fire job (consumed by the worker role). */
+    private readonly maintenance;
+    /** Network grants: the org's effective egress (network ask-to-allow spec §8.1). */
+    private readonly sandbox;
+    /** Network grants: the task's device's local policy summary (`remoteGrants`). */
+    private readonly devicePolicy;
+    constructor(db: KernelDb, txHost: TransactionHost, config: Pick<KernelConfigService, "get">, store: ScheduledTaskStore, orgLock: Pick<OrgLock, "lockAndAuthorize">, agents: Pick<AgentLookup, "get">, access: Pick<ConversationAccess, "isAccessible">, tools: Pick<ToolRegistry, "forAgent">, extensions: Pick<ExtensionRegistry, "list">, 
+    /** A task's model must resolve for the org and declare its effort (as a message's switch). */
+    providers: Pick<ProviderRegistry, "resolve">, log: Pick<KernelLogger, "warn">, 
+    /** "Run now" enqueues the fire job (consumed by the worker role). */
+    maintenance: Pick<Queue, "add">, 
+    /** Network grants: the org's effective egress (network ask-to-allow spec §8.1). */
+    sandbox: Pick<SandboxService, "ceilingLimits" | "devicePolicy">, 
+    /** Network grants: the task's device's local policy summary (`remoteGrants`). */
+    devicePolicy: Pick<DevicePolicyService, "summary">);
+    create(orgId: string, accountId: string, input: CreateTaskInput, browserTimeZone?: string, source?: GrantWriteSource): Promise<ScheduledTask>;
+    /** Creator only: an org admin gets `schedule.forbidden`, anyone else `schedule.not_found`. */
+    update(orgId: string, accountId: string, id: string, patch: UpdateTaskInput): Promise<ScheduledTask>;
+    /** The creator, or an org admin (`schedules.manage`); a task not active is returned as is. */
+    pause(orgId: string, actor: ScheduleActor, id: string): Promise<ScheduledTask>;
+    /**
+     * The creator (`schedules.use`), or an org admin. The next run is computed from now (missed ticks
+     * are not caught up) and the failure count starts over. An ended task cannot be resumed.
+     */
+    resume(orgId: string, actor: ScheduleActor, id: string): Promise<ScheduledTask>;
+    /** The creator, or an org admin. */
+    remove(orgId: string, actor: ScheduleActor, id: string): Promise<void>;
+    /** The creator, or an org admin. */
+    get(orgId: string, actor: ScheduleActor, id: string): Promise<ScheduledTask>;
+    /** The actor's own tasks; `all` (org admins only, else `forbidden`): every task of the org. */
+    list(orgId: string, actor: ScheduleActor, opts?: {
+        all?: boolean;
+        conversationId?: string;
+    }): Promise<ScheduledTaskListItem[]>;
+    /**
+     * The tasks of `tasks` that post into the conversation: a `conversation` task naming it, or a
+     * `chat` task whose chat the conversation is a thread of (spec §10 side panel).
+     */
+    private postingInto;
+    /** Each task with its latest settled non-trial run, in one query. */
+    private withLastRuns;
+    /**
+     * The chats the caller can point a `chat` task at (spec §8): per active connection of the org,
+     * their DM threads (archived included) and, on a channel with threads, the groups they have a
+     * thread in. Members up (`schedules.use`, the route's).
+     */
+    chatTargets(orgId: string, accountId: string): Promise<ChatTarget[]>;
+    /**
+     * The agent's tools (connector tools included) as a task's grant picker offers them, each
+     * grantable or why not by {@link grantRefusalOf}, the rule {@link addGrants} applies.
+     * `agent.not_found` when the caller can't use the agent.
+     */
+    grantableTools(orgId: string, accountId: string, agentId: string): Promise<GrantableTool[]>;
+    /** The task's runs, latest first (default 50, at most 200); visible as {@link get}. */
+    runs(orgId: string, actor: ScheduleActor, id: string, limit?: number): Promise<TaskRun[]>;
+    /** The task's grants; visible as {@link get}. */
+    grants(orgId: string, actor: ScheduleActor, id: string): Promise<ScheduledTaskGrantView[]>;
+    /**
+     * Creator only; each grant is checked as at create (spec §7); network domains only from a web
+     * session (`source.fromSession`).
+     */
+    addGrants(orgId: string, accountId: string, id: string, grants: GrantInput[], source?: GrantWriteSource): Promise<ScheduledTaskGrant[]>;
+    /** Creator only; removing a grant the task does not have is a no-op. */
+    removeGrant(orgId: string, accountId: string, id: string, toolKey: string): Promise<void>;
+    /**
+     * The creator's scheduled tasks that need attention (spec §8), derived live: a paused task whose
+     * reason is not `creator` (resuming clears it), an active task whose latest settled non-trial
+     * run failed (the next good run clears it), and a task whose latest settled non-trial run was
+     * refused tools, connections or domains (a tool granted since drops out, a domain too while the
+     * org's network allowlist admits it; the next clean run clears the rest). Newest first.
+     */
+    attentionFor(orgId: string, accountId: string): Promise<ScheduleAttention[]>;
+    private roleOrNull;
+    /**
+     * The agent's tools by key (their `requiredRole` and definition hash) as the creator sees them;
+     * empty when the agent is gone or hidden (the task is paused for that anyway); null when they
+     * cannot be read now (logged: the caller then cannot tell what is stale or needs a role).
+     */
+    private agentToolFacts;
+    /**
+     * Pauses an active live task for `reason` in the caller's transaction `t` (the fire job, 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.
+     */
+    pauseFor(t: KernelSchemaDb, taskId: string, reason: SchedulePauseReason, by: string | null): Promise<void>;
+    /**
+     * "Run now" (spec §6), creator only: a task run for the request time, outside the schedule (no
+     * unique-key conflict with a tick, and `next_run_at` does not move), fired at once through the
+     * fire job after the commit. `trial`: an attended trial run whose approvals become the task's
+     * grants (§7). Counted in the rate limit like any run. An ended task cannot run; a paused one
+     * can (only its creator gets here: the run is `manual`, which the fire's paused check lets by).
+     */
+    runNow(orgId: string, accountId: string, id: string, opts: {
+        trial: boolean;
+    }): Promise<TaskRun>;
+    /** The live role of a member of the org; not a member → `schedule.not_found`. */
+    private liveRole;
+    /** The actor's own task, row-locked; another's: `schedule.forbidden` for an admin, else 404. */
+    private lockOwn;
+    /**
+     * A task the actor may pause, resume or delete, row-locked under the org lock: their own (with
+     * `creatorAction`), or any as an org admin (`schedules.manage`); otherwise `schedule.not_found`.
+     */
+    private lockManaged;
+    /**
+     * Where runs go (spec §3, §8), checked against the creator:
+     * - the mode and its fields agree (`conversation`: a conversation and no chat; `chat`: a chat
+     *   and no conversation; `new`: neither);
+     * - `conversation`: the creator's live chat conversation with this agent, still accessible;
+     * - `chat`: the connection is active and bound to this agent; a DM needs a thread row (archived
+     *   allowed) of the creator in that chat; a group needs the creator's thread row in the group
+     *   and a channel with threads.
+     */
+    private checkTarget;
+    /** The channel's declared features; undefined when its extension is not loaded here. */
+    private channelFeatures;
+    /**
+     * A task's model, effort and device (spec §4): `new` mode only, since a conversation or chat
+     * task runs with that conversation's selection and device (a task must not switch a person's
+     * conversation for their later turns), so another mode refuses them (`validation_failed`).
+     * The model must resolve for the org (`agent.model_unavailable`, as a message's switch) and
+     * declare the effort (`validation_failed`); the device must be one of the creator's
+     * (`checkDevice`, when `deviceChanged`).
+     */
+    private checkPick;
+    /** The device is one of the creator's live personal devices in the org. */
+    private checkDevice;
+    /**
+     * The grants as stored: each tool resolved among the agent's tools now (its `spec_hash` and
+     * source connector), refused by {@link grantRefusal}; each `network:<host>` key (lower-cased)
+     * refused by {@link networkGrantRefusal} against the org's effective egress and the summary of
+     * `deviceId`, the task's device (null: none can be determined, the device rule is skipped),
+     * stored with `spec_hash` `network` and no connector (plan P-D7), and only when
+     * `source.fromSession` (a person on the task page; never a token, the Platform tool or the
+     * schedule tools). Duplicates keep the last.
+     */
+    private resolveGrants;
+    /**
+     * What a network grant is checked against (network ask-to-allow spec §8.1): the network of the
+     * org's sandbox ceiling now (sandbox dev tiers spec §4.2) and the local policy summary of the
+     * task's device (null without a device or a connected machine).
+     */
+    private networkGrantContext;
+    /**
+     * The device a task's runs use, as far as the task tells: a `new` task's own device, a
+     * `conversation` task's conversation's device (in the org); null when none is chosen, and for a
+     * chat task: its IM conversation's device is not known until it runs, so the device rule of a
+     * network grant is skipped there (the device still refuses grants at the command when its owner
+     * turned them off, and the run notes it).
+     */
+    private taskDeviceOf;
+}