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

package/dist/tools/builtins/schedules.d.ts

@@ -0,0 +1,107 @@
+import type { KernelSchemaDb } from "../../db/kernel-schema.js";
+import { ApiError } from "../../errors.js";
+import type { 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 { ScheduledTasksService, UpdateTaskInput } from "../../schedules/scheduled-tasks.service.js";
+import { ScheduledTaskStore } from "../../schedules/store.js";
+import type { ScheduleChat, ScheduledTask, ScheduleTrigger } from "../../schedules/types.js";
+import type { BuiltinTool } from "../registry.js";
+/**
+ * The schedule builtins (scheduled tasks spec §11): `ScheduleCreate`, `ScheduleUpdate`,
+ * `ScheduleList` and `ScheduleDelete` manage the scheduled tasks of the run's trigger account
+ * through the same service as the HTTP routes (`ScheduledTasksService`), so the org's limits and
+ * the grant rules apply unchanged.
+ *
+ * - `ScheduleCreate` / `ScheduleUpdate` are fixed asks (R3, `R3_FIXED_ASK_TOOL_KEYS`) with a
+ *   per-call policy that never remembers: every call asks, no grant (conversation, always or task)
+ *   covers it, and an unattended run in `fail` mode is refused. The approval card's summary is
+ *   rendered here, by the kernel, from the input and the stored task: name, schedule in words with
+ *   its zone, where runs go and the approved tools (an update shows what changes).
+ * - The approved tools of a task are exactly the `approvedTools` of the approved input: create
+ *   grants that list, and an update that passes it replaces the task's grants with it (the card
+ *   lists the full new set), so nothing beyond what the person saw is ever granted.
+ * - `ScheduleList` (allow) lists the person's own tasks; `ScheduleDelete` (allow; deleting only
+ *   narrows) deletes only the person's own task, even when they are an org admin.
+ * - `mode: "here"`: a `chat` task for this conversation's IM direct chat when the conversation is
+ *   delivered to one (`channel_deliveries`) and is the live DM thread of the person
+ *   (`channel_threads`), else a `conversation` task for this conversation. The zone is the run's
+ *   (`run_context`, else the org's, else UTC).
+ */
+/** The task service as the tools use it (bound at start; null when not loaded here). */
+export type ScheduleService = Pick<ScheduledTasksService, "create" | "update" | "list" | "remove" | "addGrants" | "removeGrant">;
+/**
+ * Where the schedule tools find the task service: a registration port. `SchedulesModule` imports
+ * `ToolsModule` (its grants resolve the agent's tools through `ToolRegistry`, which lists these
+ * builtins), so the service cannot be injected into the builtins; `SchedulesModule` binds it here
+ * from `onModuleInit` instead, as the domain operations register into `PlatformOperations`. Null
+ * until bound (an application without `SchedulesModule`).
+ */
+export declare class ScheduleToolsPort {
+    private service;
+    bind(service: ScheduleService): void;
+    get(): ScheduleService | null;
+}
+export interface ScheduleToolsDeps {
+    /** The kernel-schema handle of the current context. */
+    db: () => KernelSchemaDb;
+    config: Pick<KernelConfigService, "get">;
+    store: Pick<ScheduledTaskStore, "getTask" | "listGrants">;
+    /** The task service, or null when this application does not load it. */
+    service: () => ScheduleService | null;
+    /** `ScheduleUpdate`'s write (its field change and grant changes commit together). */
+    updates: Pick<ScheduleUpdates, "apply">;
+    /** The conversation's zone: its latest `run_context`, else the org's, else UTC. */
+    timeZoneOf: (orgId: string, conversationId: string) => Promise<string>;
+    /** The clock (epoch ms), for the next run shown on cards and lists. */
+    now: () => number;
+}
+export declare const SCHEDULES_UNAVAILABLE_TEXT = "Scheduled tasks are not available on this server; ask the user to manage the task on the scheduled tasks page instead.";
+export declare const SCHEDULES_OFF_TEXT = "Scheduled tasks are turned off in this organization; ask an org admin to turn them on.";
+/** The card recomputed at run time differs from the one the person approved. */
+export declare const cardChangedText: (tool: string) => string;
+export declare const NOT_A_MEMBER_TEXT = "The user is no longer a member of this organization, so their scheduled tasks cannot be managed here; ask them to check their membership.";
+/** No task with that id is the person's own (missing, deleted, or another member's). */
+export declare const notYoursText: (id: string) => string;
+/** The service's refusal as an actionable English tool error. */
+export declare function scheduleErrorText(e: ApiError, ctx: {
+    id?: string;
+    zone?: string;
+}): string;
+type Words = {
+    zh: string;
+    en: string;
+};
+/** A trigger in words, its zone included; an unusual cron reads as the expression itself. */
+export declare function scheduleWords(t: ScheduleTrigger): Words;
+/** Where a task's runs go, resolved for a card or a result. */
+export type Target = {
+    mode: "new";
+} | {
+    mode: "conversation";
+    conversationId: string;
+} | {
+    mode: "chat";
+    chat: ScheduleChat;
+    connectionName: string;
+};
+/**
+ * `mode: "here"` (spec §8): the conversation's IM direct chat when the conversation is delivered
+ * to a chat and is the person's live DM thread there, else this conversation.
+ */
+export declare function hereTarget(db: KernelSchemaDb, orgId: string, accountId: string, conversationId: string): Promise<Target>;
+/**
+ * `ScheduleUpdate`'s write in one transaction: the field change, then (with `approvedTools`) the
+ * task's grants replaced by exactly that list. Each service call is `@Transactional` and joins
+ * this one, so a refused grant rolls the field change back too.
+ */
+export declare class ScheduleUpdates {
+    readonly txHost: TransactionHost;
+    private readonly db;
+    private readonly store;
+    constructor(txHost: TransactionHost, db: KernelDb, store: ScheduledTaskStore);
+    apply(svc: Pick<ScheduleService, "update" | "addGrants" | "removeGrant">, orgId: string, accountId: string, task: ScheduledTask, patch: UpdateTaskInput, approvedTools: readonly string[] | undefined): Promise<ScheduledTask>;
+}
+/** The four schedule builtins. */
+export declare function scheduleTools(deps: ScheduleToolsDeps): BuiltinTool[];
+export {};