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

package/dist/schedules/schedules.controller.d.ts

@@ -0,0 +1,68 @@
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { type ChatTarget, type GrantableTool, type ScheduledTaskGrantView, type ScheduledTaskListItem, ScheduledTasksService } from "./scheduled-tasks.service.js";
+import { type ScheduleChatTargetsQuery, type ScheduleCreateBody, type ScheduleGrantableQuery, type ScheduleGrantParams, type ScheduleGrantsBody, type ScheduleListQuery, type ScheduleParams, type ScheduleRunBody, type ScheduleRunsQuery, type ScheduleUpdateBody } from "./schedules.schemas.js";
+import type { ScheduledTask, ScheduledTaskGrant, TaskRun } from "./types.js";
+/**
+ * Scheduled tasks (`/api/v1/orgs/:orgId/schedules`, spec 2026-11-11-scheduled-tasks §10); human
+ * users only (a service token gets 403).
+ * - `GET /` → `{ items }`: the caller's own tasks, each with its `lastRun`; `?all=true` every task
+ *   of the org (org admins, `schedules.manage`, enforced by the service: 403 `forbidden`
+ *   otherwise); `?conversationId=` only those posting into that conversation;
+ * - `GET /chat-targets` → `{ items }`: the chats the caller can point a `chat` task at;
+ * - `GET /grantable-tools?agentId=` → `{ items }`: the agent's tools, each grantable or why not;
+ * - `POST /` → 201 `{ task }` (`timeZone` is the browser zone, a fallback only);
+ *   `GET /:id`, `PATCH /:id`, `POST /:id/pause`, `POST /:id/resume` → `{ task }`;
+ * - `DELETE /:id` → 204; `POST /:id/run { trial? }` → 202 `{ run }`;
+ * - `GET /:id/runs?limit` → `{ items }`; `GET /:id/grants` → `{ items }` (each with `stale`);
+ *   `POST /:id/grants { grants }` → `{ items }`; `DELETE /:id/grants/:toolKey` → 204.
+ *
+ * Roles: create, edit, resume, run and the grants need `schedules.use` (member and up; a guest
+ * gets 403). Pause and delete are `org.read` (any member, a guest included) so a creator demoted
+ * to guest can still stop and remove their own tasks; the service decides by the live role and
+ * ownership (the creator, or an org admin), and a task the caller may not see is 404
+ * `schedule.not_found`.
+ */
+export declare class SchedulesController {
+    private readonly tasks;
+    constructor(tasks: ScheduledTasksService);
+    list(principal: Principal, org: OrgContext, q: z.infer<typeof ScheduleListQuery>): Promise<{
+        items: ScheduledTaskListItem[];
+    }>;
+    chatTargets(principal: Principal, org: OrgContext, _q: z.infer<typeof ScheduleChatTargetsQuery>): Promise<{
+        items: ChatTarget[];
+    }>;
+    grantableTools(principal: Principal, org: OrgContext, q: z.infer<typeof ScheduleGrantableQuery>): Promise<{
+        items: GrantableTool[];
+    }>;
+    create(principal: Principal, org: OrgContext, body: z.infer<typeof ScheduleCreateBody>): Promise<{
+        task: ScheduledTask;
+    }>;
+    get(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>): Promise<{
+        task: ScheduledTask;
+    }>;
+    update(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>, body: z.infer<typeof ScheduleUpdateBody>): Promise<{
+        task: ScheduledTask;
+    }>;
+    remove(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>): Promise<void>;
+    pause(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>): Promise<{
+        task: ScheduledTask;
+    }>;
+    resume(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>): Promise<{
+        task: ScheduledTask;
+    }>;
+    run(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>, body: z.infer<typeof ScheduleRunBody>): Promise<{
+        run: TaskRun;
+    }>;
+    runs(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>, q: z.infer<typeof ScheduleRunsQuery>): Promise<{
+        items: TaskRun[];
+    }>;
+    grants(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>): Promise<{
+        items: ScheduledTaskGrantView[];
+    }>;
+    addGrants(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleParams>, body: z.infer<typeof ScheduleGrantsBody>): Promise<{
+        items: ScheduledTaskGrant[];
+    }>;
+    removeGrant(principal: Principal, org: OrgContext, params: z.infer<typeof ScheduleGrantParams>): Promise<void>;
+}

package/dist/schedules/schedules.controller.js

@@ -0,0 +1,242 @@
+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;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Delete, Get, HttpCode, Inject, Patch, Post } from "@nestjs/common";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { ZBody, ZParam, ZQuery } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { ScheduledTasksService, } from "./scheduled-tasks.service.js";
+import { createInputOf, grantsOf, ScheduleChatTargetsQueryDto, ScheduleCreateBodyDto, ScheduleGrantableQueryDto, ScheduleGrantParamsDto, ScheduleGrantsBodyDto, ScheduleListQueryDto, ScheduleParamsDto, ScheduleRunBodyDto, ScheduleRunsQueryDto, ScheduleUpdateBodyDto, updateInputOf, } from "./schedules.schemas.js";
+/**
+ * Scheduled tasks (`/api/v1/orgs/:orgId/schedules`, spec 2026-11-11-scheduled-tasks §10); human
+ * users only (a service token gets 403).
+ * - `GET /` → `{ items }`: the caller's own tasks, each with its `lastRun`; `?all=true` every task
+ *   of the org (org admins, `schedules.manage`, enforced by the service: 403 `forbidden`
+ *   otherwise); `?conversationId=` only those posting into that conversation;
+ * - `GET /chat-targets` → `{ items }`: the chats the caller can point a `chat` task at;
+ * - `GET /grantable-tools?agentId=` → `{ items }`: the agent's tools, each grantable or why not;
+ * - `POST /` → 201 `{ task }` (`timeZone` is the browser zone, a fallback only);
+ *   `GET /:id`, `PATCH /:id`, `POST /:id/pause`, `POST /:id/resume` → `{ task }`;
+ * - `DELETE /:id` → 204; `POST /:id/run { trial? }` → 202 `{ run }`;
+ * - `GET /:id/runs?limit` → `{ items }`; `GET /:id/grants` → `{ items }` (each with `stale`);
+ *   `POST /:id/grants { grants }` → `{ items }`; `DELETE /:id/grants/:toolKey` → 204.
+ *
+ * Roles: create, edit, resume, run and the grants need `schedules.use` (member and up; a guest
+ * gets 403). Pause and delete are `org.read` (any member, a guest included) so a creator demoted
+ * to guest can still stop and remove their own tasks; the service decides by the live role and
+ * ownership (the creator, or an org admin), and a task the caller may not see is 404
+ * `schedule.not_found`.
+ */
+let SchedulesController = class SchedulesController {
+    tasks;
+    constructor(tasks) {
+        this.tasks = tasks;
+    }
+    // org.read: a creator demoted to guest still lists their own tasks (to pause or delete them);
+    // `all` is the service's admin check
+    async list(principal, org, q) {
+        const p = requireUser(principal);
+        const items = await this.tasks.list(org.orgId, { accountId: p.account.id }, {
+            all: q.all === "true",
+            ...(q.conversationId !== undefined && { conversationId: q.conversationId }),
+        });
+        return { items };
+    }
+    async chatTargets(principal, org, _q) {
+        const p = requireUser(principal);
+        return { items: await this.tasks.chatTargets(org.orgId, p.account.id) };
+    }
+    async grantableTools(principal, org, q) {
+        const p = requireUser(principal);
+        return { items: await this.tasks.grantableTools(org.orgId, p.account.id, q.agentId) };
+    }
+    async create(principal, org, body) {
+        const p = requireUser(principal);
+        const { input, browserTimeZone } = createInputOf(body);
+        // network domains only from a person's web session (never a personal access token)
+        return {
+            task: await this.tasks.create(org.orgId, p.account.id, input, browserTimeZone, {
+                fromSession: p.via === "session",
+            }),
+        };
+    }
+    async get(principal, org, params) {
+        const p = requireUser(principal);
+        return {
+            task: await this.tasks.get(org.orgId, { accountId: p.account.id }, params.id),
+        };
+    }
+    async update(principal, org, params, body) {
+        const p = requireUser(principal);
+        return {
+            task: await this.tasks.update(org.orgId, p.account.id, params.id, updateInputOf(body)),
+        };
+    }
+    async remove(principal, org, params) {
+        const p = requireUser(principal);
+        await this.tasks.remove(org.orgId, { accountId: p.account.id }, params.id);
+    }
+    async pause(principal, org, params) {
+        const p = requireUser(principal);
+        return {
+            task: await this.tasks.pause(org.orgId, { accountId: p.account.id }, params.id),
+        };
+    }
+    async resume(principal, org, params) {
+        const p = requireUser(principal);
+        return {
+            task: await this.tasks.resume(org.orgId, { accountId: p.account.id }, params.id),
+        };
+    }
+    async run(principal, org, params, body) {
+        const p = requireUser(principal);
+        return {
+            run: await this.tasks.runNow(org.orgId, p.account.id, params.id, {
+                trial: body.trial === true,
+            }),
+        };
+    }
+    async runs(principal, org, params, q) {
+        const p = requireUser(principal);
+        return {
+            items: await this.tasks.runs(org.orgId, { accountId: p.account.id }, params.id, q.limit),
+        };
+    }
+    async grants(principal, org, params) {
+        const p = requireUser(principal);
+        return {
+            items: await this.tasks.grants(org.orgId, { accountId: p.account.id }, params.id),
+        };
+    }
+    async addGrants(principal, org, params, body) {
+        const p = requireUser(principal);
+        return {
+            items: await this.tasks.addGrants(org.orgId, p.account.id, params.id, grantsOf(body.grants), {
+                fromSession: p.via === "session",
+            }),
+        };
+    }
+    async removeGrant(principal, org, params) {
+        const p = requireUser(principal);
+        await this.tasks.removeGrant(org.orgId, p.account.id, params.id, params.toolKey);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("org.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZQuery(ScheduleListQueryDto))
+], SchedulesController.prototype, "list", null);
+__decorate([
+    Get("chat-targets"),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZQuery(ScheduleChatTargetsQueryDto))
+], SchedulesController.prototype, "chatTargets", null);
+__decorate([
+    Get("grantable-tools"),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZQuery(ScheduleGrantableQueryDto))
+], SchedulesController.prototype, "grantableTools", null);
+__decorate([
+    Post(),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZBody(ScheduleCreateBodyDto))
+], SchedulesController.prototype, "create", null);
+__decorate([
+    Get(":id"),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto))
+], SchedulesController.prototype, "get", null);
+__decorate([
+    Patch(":id"),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto)),
+    __param(3, ZBody(ScheduleUpdateBodyDto))
+], SchedulesController.prototype, "update", null);
+__decorate([
+    Delete(":id"),
+    HttpCode(204),
+    OrgAction("org.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto))
+], SchedulesController.prototype, "remove", null);
+__decorate([
+    Post(":id/pause"),
+    HttpCode(200),
+    OrgAction("org.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto))
+], SchedulesController.prototype, "pause", null);
+__decorate([
+    Post(":id/resume"),
+    HttpCode(200),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto))
+], SchedulesController.prototype, "resume", null);
+__decorate([
+    Post(":id/run"),
+    HttpCode(202),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto)),
+    __param(3, ZBody(ScheduleRunBodyDto))
+], SchedulesController.prototype, "run", null);
+__decorate([
+    Get(":id/runs"),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto)),
+    __param(3, ZQuery(ScheduleRunsQueryDto))
+], SchedulesController.prototype, "runs", null);
+__decorate([
+    Get(":id/grants"),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto))
+], SchedulesController.prototype, "grants", null);
+__decorate([
+    Post(":id/grants"),
+    HttpCode(200),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleParamsDto)),
+    __param(3, ZBody(ScheduleGrantsBodyDto))
+], SchedulesController.prototype, "addGrants", null);
+__decorate([
+    Delete(":id/grants/:toolKey"),
+    HttpCode(204),
+    OrgAction("schedules.use"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(ScheduleGrantParamsDto))
+], SchedulesController.prototype, "removeGrant", null);
+SchedulesController = __decorate([
+    Controller("api/v1/orgs/:orgId/schedules"),
+    __param(0, Inject(ScheduledTasksService))
+], SchedulesController);
+export { SchedulesController };

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

@@ -0,0 +1,16 @@
+import { type OnModuleInit } from "@nestjs/common";
+import { ScheduleToolsPort } from "../tools/builtins/schedules.js";
+import { ScheduledTasksService } from "./scheduled-tasks.service.js";
+/**
+ * Scheduled tasks for people (spec 2026-11-11): the service the HTTP API, the Platform operations
+ * and the schedule tools share. ToolsModule: grants resolve the agent's tools (`ToolRegistry`);
+ * ExtensionRegistryModule: a group chat target needs its channel's `features.threads`. At start
+ * it binds the service into the schedule tools' port (`ScheduleToolsPort`): the tools cannot
+ * inject it, since this module imports theirs.
+ */
+export declare class SchedulesModule implements OnModuleInit {
+    private readonly port;
+    private readonly service;
+    constructor(port: ScheduleToolsPort, service: ScheduledTasksService);
+    onModuleInit(): void;
+}

package/dist/schedules/schedules.module.js

@@ -0,0 +1,65 @@
+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;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Module } from "@nestjs/common";
+import { AgentLookupModule } from "../agents/agent-lookup.js";
+import { ConversationAccessModule } from "../conversations/access.js";
+import { ExtensionRegistryModule } from "../extensions/registry.js";
+import { QueueModule } from "../infra/queue/queue.module.js";
+import { LocalDevicesModule } from "../local-devices/local-devices.module.js";
+import { OrgLockModule } from "../orgs/org-lock.js";
+import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
+import { ProvidersModule } from "../runtime/providers.js";
+import { SandboxModule } from "../sandbox/sandbox.module.js";
+import { ScheduleToolsPort } from "../tools/builtins/schedules.js";
+import { ToolsModule } from "../tools/tools.module.js";
+import { ScheduledTasksService } from "./scheduled-tasks.service.js";
+import { ScheduledTaskStoreModule } from "./store.module.js";
+/**
+ * Scheduled tasks for people (spec 2026-11-11): the service the HTTP API, the Platform operations
+ * and the schedule tools share. ToolsModule: grants resolve the agent's tools (`ToolRegistry`);
+ * ExtensionRegistryModule: a group chat target needs its channel's `features.threads`. At start
+ * it binds the service into the schedule tools' port (`ScheduleToolsPort`): the tools cannot
+ * inject it, since this module imports theirs.
+ */
+let SchedulesModule = class SchedulesModule {
+    port;
+    service;
+    constructor(port, service) {
+        this.port = port;
+        this.service = service;
+    }
+    onModuleInit() {
+        this.port.bind(this.service);
+    }
+};
+SchedulesModule = __decorate([
+    Module({
+        imports: [
+            ScheduledTaskStoreModule,
+            OrgLockModule,
+            AgentLookupModule,
+            ConversationAccessModule,
+            ExtensionRegistryModule,
+            ToolsModule,
+            // a new-conversation task's model must resolve for the org
+            ProvidersModule,
+            // network grants: the org's effective egress and the task device's policy summary
+            SandboxModule,
+            LocalDevicesModule,
+            // "run now" enqueues the fire job
+            QueueModule.registerQueue(MAINTENANCE_QUEUE_NAME),
+        ],
+        providers: [ScheduledTasksService],
+        exports: [ScheduledTasksService, ScheduledTaskStoreModule],
+    }),
+    __param(0, Inject(ScheduleToolsPort)),
+    __param(1, Inject(ScheduledTasksService))
+], SchedulesModule);
+export { SchedulesModule };