@capybara-hq/kernel 0.1.0-rc.26 → 0.1.0-rc.28

package/dist/tools/approvals.service.js

@@ -13,7 +13,7 @@ import { connectorToolKey, parseToolKey, validateAllowHost, } from "@capybara-hq
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { EventLog } from "../conversations/event-log.js";
-import { NETWORK_ASK_MAX_HOSTS, NETWORK_HOST_MAX_CHARS, } from "../conversations/events.js";
+import { GIT_ASK_MAX_REFS, GIT_REF_MAX_CHARS, NETWORK_ASK_MAX_HOSTS, NETWORK_HOST_MAX_CHARS, } from "../conversations/events.js";
 import { conversationSourceOf } from "../conversations/source.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
@@ -32,9 +32,10 @@ import { RunResume } from "../runtime/run-jobs.js";
 import { rootConversationOf } from "../runtime/subagents/child.js";
 import { deviceNotFound, SandboxService } from "../sandbox/sandbox.service.js";
 import { readScheduleSettings } from "../schedules/effective-settings.js";
-import { grantRefusalOf, NETWORK_GRANT_PREFIX, NETWORK_GRANT_SPEC_HASH, networkGrantRefusal, } from "../schedules/grant-rules.js";
+import { GIT_GRANT_SPEC_HASH, gitGrantRefusal, gitPushGrantKey, grantRefusalOf, NETWORK_GRANT_PREFIX, NETWORK_GRANT_SPEC_HASH, networkGrantRefusal, normalizeGitRepo, } from "../schedules/grant-rules.js";
 import { ScheduledTaskStore } from "../schedules/store.js";
 import { unattendedTaskRunOf } from "../schedules/unattended.js";
+import { gitPushPolicyName, personalAuth } from "./connector-account-policies.js";
 import { pluginDisplayNames } from "./display-names.js";
 import { normalizeStoredDefinitionIn } from "./legacy-data.js";
 import { ToolRegistry } from "./registry.js";
@@ -46,17 +47,26 @@ export const APPROVALS_LIST_MAX = 100;
  * the device owner answered (spec §6.7).
  */
 export const NETWORK_ASK_CANCELLED_NOTE = "[network] The run was stopped before the user answered; access stays blocked.";
-/** The record without a network ask's kept command result (what routes and cards may show). */
+/** The model-visible note after a git ask's kept result when its run is stopped before the answer. */
+export const GIT_ASK_CANCELLED_NOTE = "[git] The run was stopped before the user answered; the push was not made.";
+/** The record without an ask's kept command result (what routes and cards may show). */
 export function publicRecord(r) {
-    if (r.detail === null)
-        return { ...r, detail: null };
-    const { result: _result, ...detail } = r.detail;
-    return { ...r, detail };
+    const strip = (d) => {
+        if (d === null)
+            return null;
+        const { result: _result, ...rest } = d;
+        return rest;
+    };
+    return { ...r, detail: strip(r.detail), git: strip(r.git) };
 }
 /** The tool key a network ask is recorded under (the command ran in `Bash`). */
 export const NETWORK_ASK_TOOL_KEY = "Bash";
 /** The spec hash of a network ask (no tool definition is approved). */
 const NETWORK_ASK_SPEC_HASH = "network";
+/** The tool key a git ask is recorded under (the push ran in a `Bash` command). */
+export const GIT_ASK_TOOL_KEY = "Bash";
+/** The spec hash of a git ask (no tool definition is approved). */
+const GIT_ASK_SPEC_HASH = "git";
 const notFound = () => new ApiError("approval.not_found", "Approval not found");
 /**
  * A decision refused before it wrote anything (the ask closed, expired or is not the account's to
@@ -84,6 +94,7 @@ function toRecord(r) {
         attempt: r.attempt,
         kind: r.kind,
         detail: r.kind === "network" ? (r.detail ?? null) : null,
+        git: r.kind === "git" ? (r.detail ?? null) : null,
         toolKey: r.tool_key,
         specHash: r.spec_hash,
         connectorId: r.connector_id,
@@ -329,6 +340,109 @@ let ApprovalsService = class ApprovalsService {
         ]);
         return { record: rec, toSeq: Math.max(...written.map((e) => e.seq)) };
     }
+    /**
+     * A git push ask (sandbox git credentials spec §7): a pending approval of kind `git` for the
+     * actor whose credential the push used, expiring like a tool approval, and its
+     * `approval_requested` (tool key `Bash`, the display-only `git` field), in one transaction. The
+     * scopes are `once` (a run grant) and, for a personal connector (the push used the actor's own
+     * connection), `always` (the actor's standing allow for the repository); an org connector's push
+     * acts as the org, so no member allow applies to it. Takes the attempt after the call's other
+     * approvals; one per call: a second request returns the first.
+     */
+    async requestGit(input) {
+        const d = input.detail;
+        const repo = normalizeGitRepo(d.repo);
+        if (repo === null || repo !== d.repo) {
+            throw new Error(`a git ask names a normalized <owner>/<repo> (got ${d.repo})`);
+        }
+        if (d.host.length === 0 || d.host.length > NETWORK_HOST_MAX_CHARS) {
+            throw new Error("a git ask's host is 1 to 255 characters");
+        }
+        if (d.refs.length > GIT_ASK_MAX_REFS ||
+            d.refs.some((r) => r.length === 0 || r.length > GIT_REF_MAX_CHARS)) {
+            throw new Error(`a git ask lists at most ${GIT_ASK_MAX_REFS} refs of 1 to 255 characters`);
+        }
+        const { record, toSeq } = await this.requestGitIn(input);
+        if (toSeq !== null)
+            await this.eventLog.notify(record.conversationId, toSeq);
+        return record;
+    }
+    async requestGitIn(input) {
+        const hours = this.config.get().tools.approvalTimeoutHours;
+        const t = this.db.db;
+        // the conversation row first (as `requestIn`): it also serializes two asks of one call
+        await t
+            .selectFrom("conversations")
+            .select("id")
+            .where("id", "=", input.conversationId)
+            .forUpdate()
+            .execute();
+        // only a member of the org is asked, and only about a live connector of the org
+        const member = await this.roleOf(input.orgId, input.requestedFor);
+        const connector = await t
+            .selectFrom("connectors")
+            .select("auth")
+            .where("id", "=", input.connectorId)
+            .where("org_id", "=", input.orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (member === null || connector === undefined) {
+            throw new Error(`a git ask is for a member of the org about one of its connectors (connector ${input.connectorId})`);
+        }
+        const existing = await this.gitForCall(input.runId, input.callId);
+        if (existing !== null)
+            return { record: existing, toSeq: null };
+        const last = await t
+            .selectFrom("approvals")
+            .select(sql `max(attempt)`.as("attempt"))
+            .where("run_id", "=", input.runId)
+            .where("call_id", "=", input.callId)
+            .executeTakeFirst();
+        const scopes = personalAuth(connector.auth) ? ["once", "always"] : ["once"];
+        const row = await t
+            .insertInto("approvals")
+            .values({
+            id: randomUUID(),
+            org_id: input.orgId,
+            conversation_id: input.conversationId,
+            run_id: input.runId,
+            call_id: input.callId,
+            attempt: Number(last?.attempt ?? 0) + 1,
+            kind: "git",
+            detail: JSON.stringify(input.detail),
+            tool_key: GIT_ASK_TOOL_KEY,
+            spec_hash: GIT_ASK_SPEC_HASH,
+            connector_id: input.connectorId,
+            input: JSON.stringify({}),
+            requested_for: input.requestedFor,
+            approver_role: null,
+            scopes,
+            scope: null,
+            decided_by: null,
+            expires_at: sql `now() + ${hours}::integer * interval '1 hour'`,
+        })
+            .returningAll()
+            .executeTakeFirstOrThrow();
+        const rec = toRecord(row);
+        const written = await this.eventLog.appendIn(rec.conversationId, [
+            {
+                type: "approval_requested",
+                runId: rec.runId,
+                idemKey: `approval_requested:${rec.id}`,
+                payload: {
+                    step: input.step,
+                    callId: rec.callId,
+                    approvalId: rec.id,
+                    toolKey: rec.toolKey,
+                    expiresAt: rec.expiresAt,
+                    git: { host: input.detail.host, repo: input.detail.repo, refs: input.detail.refs },
+                    requestedFor: rec.requestedFor,
+                    approverRole: null,
+                },
+            },
+        ]);
+        return { record: rec, toSeq: Math.max(...written.map((e) => e.seq)) };
+    }
     /** 当前用户能处理的审批（新的在前，最多 {@link APPROVALS_LIST_MAX} 条）；`status` 缺省为全部。 */
     async list(orgId, accountId, status) {
         const role = await this.roleOf(orgId, accountId);
@@ -401,6 +515,9 @@ let ApprovalsService = class ApprovalsService {
                 { path: "hosts", message: "Only a network ask takes hosts" },
             ]);
         }
+        if (kind.kind === "git") {
+            return this.decideGit(orgId, id, accountId, body, actorTokenId, via);
+        }
         const { record, toSeq } = await this.decideIn(orgId, id, accountId, body, actorTokenId);
         await this.announceDecided(record, toSeq);
         return record;
@@ -496,6 +613,52 @@ let ApprovalsService = class ApprovalsService {
         await this.announceDecided(decided.record, decided.toSeq);
         return decided.record;
     }
+    /**
+     * A git push ask's decision (sandbox git credentials spec §7): only the asked actor
+     * (`requested_for`) decides, in a signed-in session (a personal access token is refused, as for
+     * network asks); `once` is a run grant (the row itself), `always` also writes the actor's
+     * standing allow for the repository on that host (`connector_tool_account_policies`,
+     * `git_push:<host>/<owner>/<repo>`) in the decision's transaction. The run resumes after the
+     * commit.
+     */
+    async decideGit(orgId, id, accountId, body, actorTokenId, via) {
+        const row = await this.db
+            .selectFrom("approvals")
+            .selectAll()
+            .where("id", "=", id)
+            .where("org_id", "=", orgId)
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        const ask = toRecord(row);
+        if (ask.requestedFor !== accountId) {
+            // named only to the people the ask is shown to (the run's starter); any other member
+            // learns nothing about it, as `get` (approval.not_found)
+            const trigger = await this.db
+                .selectFrom("runs")
+                .select("trigger_account_id")
+                .where("id", "=", ask.runId)
+                .executeTakeFirst();
+            if (accountId !== trigger?.trigger_account_id)
+                throw notFound();
+            const name = ask.requestedFor === null ? null : await this.displayNameOf(ask.requestedFor);
+            throw new ApiError("approval.not_yours", `Only ${name ?? "the person whose connection the push used"} can allow this push.`);
+        }
+        if (actorTokenId !== undefined) {
+            throw new ApiError("auth.session_required", "Git pushes are decided in a signed-in session, not with a personal access token.");
+        }
+        let git = { outcome: null, via };
+        if (body.decision === "approve") {
+            const scope = body.scope ?? "once";
+            if (scope === "session" || !ask.scopes.includes(scope)) {
+                throw new ApiError("approval.scope_not_allowed", `Scope "${scope}" is not allowed for this approval; allowed: ${ask.scopes.join(", ")}`);
+            }
+            git = { outcome: scope, via };
+        }
+        const decided = await this.decideIn(orgId, id, accountId, body, actorTokenId, undefined, git);
+        await this.announceDecided(decided.record, decided.toSeq);
+        return decided.record;
+    }
     /**
      * 「这台设备一直允许」 (transactional outbox spec §7): the intent of the device change (naming the
      * ask) is recorded, the `policy` op sent (no transaction open), then {@link settleNetworkOp}
@@ -788,14 +951,14 @@ let ApprovalsService = class ApprovalsService {
     }
     // its own transaction (as the legacy one was): `approval.decided` is emitted only after the
     // decision committed, even when a caller has a transaction open
-    decideIn(orgId, id, accountId, body, actorTokenId, network) {
-        return this.decideTx(orgId, id, accountId, body, actorTokenId, network);
+    decideIn(orgId, id, accountId, body, actorTokenId, network, git) {
+        return this.decideTx(orgId, id, accountId, body, actorTokenId, network, git);
     }
     /**
      * A decision in the caller's transaction: lock order conversation → approval → run (the resume).
      * Refuses (`approval.already_decided`, `approval.not_found`, …) before any write.
      */
-    async decideTx(orgId, id, accountId, body, actorTokenId, network) {
+    async decideTx(orgId, id, accountId, body, actorTokenId, network, git) {
         const t = this.db.db;
         // lock order: the conversation, the approval, then the run (as a stop of the waiting run)
         if (!(await this.lockConversationOf(id, orgId)))
@@ -830,19 +993,23 @@ let ApprovalsService = class ApprovalsService {
         if (locked.expired) {
             throw new ApiError("approval.already_decided", "Approval has expired");
         }
-        // a network ask is decided only with what took effect (decideNetwork, the op's resolver)
-        if ((before.kind === "network") !== (network !== undefined)) {
+        // a network ask is decided only through decideNetwork (its policy op went first), a git ask
+        // only through decideGit
+        if ((before.kind === "network") !== (network !== undefined) ||
+            (before.kind === "git") !== (git !== undefined)) {
             throw new Error(`approval ${id} is of kind ${before.kind}`);
         }
         const approved = body.decision === "approve";
         const reason = approved ? undefined : body.reason?.trim() || undefined;
         const scope = !approved
             ? null
-            : network === undefined
-                ? (body.scope ?? "once")
-                : network.outcome === "always" || network.outcome === "refused"
-                    ? "always"
-                    : "once";
+            : git !== undefined
+                ? (git.outcome ?? "once")
+                : network === undefined
+                    ? (body.scope ?? "once")
+                    : network.outcome === "always" || network.outcome === "refused"
+                        ? "always"
+                        : "once";
         // 按角色升级的批准只对这一次有效：授权记在发起人名下会让其以后绕过角色要求
         if (scope !== null && scope !== "once" && before.requestedFor === null) {
             throw new ApiError("validation_failed", 'Only scope "once" is allowed for role-escalated approvals', [{ path: "scope", message: 'Only "once" is allowed for role-escalated approvals' }]);
@@ -871,6 +1038,10 @@ let ApprovalsService = class ApprovalsService {
                     ...(network.fallback !== undefined && { fallback: network.fallback }),
                 }),
             }),
+            ...(git?.outcome != null &&
+                before.git !== null && {
+                detail: JSON.stringify({ ...before.git, outcome: git.outcome }),
+            }),
         })
             .where("id", "=", id)
             .returningAll()
@@ -881,6 +1052,13 @@ let ApprovalsService = class ApprovalsService {
         if (network !== undefined) {
             // a network ask grants nothing of the tool kind: its run grant is the row itself
         }
+        else if (git !== undefined) {
+            // a git ask's run grant is the row itself; `always` is the actor's standing allow for the
+            // repository on the connector (a row the connector's deletion removes with it)
+            if (git.outcome === "always" && before.git !== null && connectorId !== null) {
+                await this.allowRepoIn(orgId, connectorId, accountId, before.git.host, before.git.repo);
+            }
+        }
         else if (scope === "session") {
             // a sub-agent's grant is the root conversation's (agent map spec §7): the root and every
             // agent of its tree, at any depth, are not asked again for the same call
@@ -917,9 +1095,13 @@ let ApprovalsService = class ApprovalsService {
             }))
                 .execute();
         }
-        if (approved && scope !== null && network === undefined) {
+        if (approved && scope !== null && network === undefined && git === undefined) {
             await this.keepTrialGrant(before, accountId);
         }
+        // 「这次允许」 of a push in a trial run: the task's grant for that repository; a standing
+        // allow needs none (the member's policy already allows it)
+        if (git?.outcome === "once")
+            await this.keepTrialGitGrant(before, accountId);
         // 「这次允许」 in a trial run (also an 「一直允许」 the device could not take): the task's
         // grants; one the device took needs none (network ask-to-allow spec §8.1)
         if (network?.outcome === "once" || network?.outcome === "once_fallback") {
@@ -973,6 +1155,14 @@ let ApprovalsService = class ApprovalsService {
             action: "approval.decided",
             target: id,
             detail: {
+                ...(git !== undefined &&
+                    before.git !== null && {
+                    kind: "git",
+                    host: before.git.host,
+                    repo: before.git.repo,
+                    connectorId,
+                    via: git.via,
+                }),
                 toolKey: before.toolKey,
                 conversationId: before.conversationId,
                 runId: before.runId,
@@ -1088,6 +1278,60 @@ let ApprovalsService = class ApprovalsService {
             });
         }
     }
+    /**
+     * The actor's standing allow for pushes to `repo` through the connector (sandbox git
+     * credentials spec §7, 「一直允许」): a `connector_tool_account_policies` row named
+     * `git_push:<host>/<owner>/<repo>` with policy `allow`, in the decision's transaction.
+     */
+    async allowRepoIn(orgId, connectorId, accountId, host, repo) {
+        await this.db.db
+            .insertInto("connector_tool_account_policies")
+            .values({
+            org_id: orgId,
+            connector_id: connectorId,
+            account_id: accountId,
+            tool_name: gitPushPolicyName(host, repo),
+            policy: "allow",
+        })
+            .onConflict((oc) => oc
+            .columns(["connector_id", "account_id", "tool_name"])
+            .doUpdateSet({ policy: "allow", updated_at: sql `now()` }))
+            .execute();
+    }
+    /**
+     * A trial run of a scheduled task (sandbox git credentials spec §7): a push its creator allowed
+     * for this run (「这次允许」) becomes the task's `git:push:<owner>/<repo>` grant, when
+     * `gitGrantRefusal` allows it (the org does not forbid it). Never for an ask another account
+     * decided or one asked of someone else. In the decision's transaction.
+     */
+    async keepTrialGitGrant(a, decidedBy) {
+        if (a.git === null)
+            return;
+        if (a.requestedFor === null || a.requestedFor !== decidedBy)
+            return;
+        const t = this.db.db;
+        const served = await unattendedTaskRunOf(t, a.runId);
+        if (served === null || !served.trial)
+            return;
+        const task = await t
+            .selectFrom("scheduled_tasks")
+            .select("account_id")
+            .where("id", "=", served.taskId)
+            .where("org_id", "=", a.orgId)
+            .where("deleted_at", "is", null)
+            .executeTakeFirst();
+        if (task?.account_id !== decidedBy)
+            return;
+        const key = gitPushGrantKey(a.git.repo);
+        const { forbiddenTools } = await readScheduleSettings(t, this.config, a.orgId);
+        if (gitGrantRefusal(key, { forbiddenTools }) !== null)
+            return;
+        await this.schedules.addGrant(t, served.taskId, {
+            toolKey: key,
+            specHash: GIT_GRANT_SPEC_HASH,
+            connectorId: null,
+        });
+    }
     /**
      * 详情，不做处理人校验（内核内部用：渠道出站投递组装 IM 审批卡片）；不存在返回 null。
      * 不得直接回给请求方——HTTP 接口用 {@link get}。
@@ -1129,6 +1373,19 @@ let ApprovalsService = class ApprovalsService {
             .executeTakeFirst();
         return row ? toRecord(row) : null;
     }
+    /** The git push ask of a tool call (at most one per call); null when it has none. */
+    async gitForCall(runId, callId) {
+        const row = await this.db
+            .selectFrom("approvals")
+            .selectAll()
+            .where("run_id", "=", runId)
+            .where("call_id", "=", callId)
+            .where("kind", "=", "git")
+            .orderBy("attempt", "desc")
+            .limit(1)
+            .executeTakeFirst();
+        return row ? toRecord(row) : null;
+    }
     /**
      * 超时（等待机制的超时任务调用）：仍 pending 且已到期 → 置 expired、写 `approval_decided{expired}`（处理人为 null）。
      * 与人工决定都锁同一行，恰好一个生效。返回 `expired`（本次生效）/ `not_due`（尚未到期）/
@@ -1254,7 +1511,8 @@ let ApprovalsService = class ApprovalsService {
     /**
      * In the caller's transaction (`mandatory`; it wrote `authorAccountId`'s message in
      * `conversationId` and holds that conversation's row lock): the message skips the pending
-     * network asks it closes (network ask-to-allow spec §6.7), as it skips questions: the asks of
+     * network and git asks it closes (network ask-to-allow spec §6.7; a git push ask follows the
+     * same flow, sandbox git credentials spec §7), as it skips questions: the asks of
      * active runs `authorAccountId` started, in the conversation and in its sub-agents'
      * conversations at any depth (their asks are shown in the root). Each becomes `skipped` with
      * `approval_decided{skipped}` by the author; access stays blocked. Returns the skipped records and
@@ -1272,7 +1530,7 @@ let ApprovalsService = class ApprovalsService {
             .selectFrom("approvals")
             .select("conversation_id")
             .where("conversation_id", "in", tree)
-            .where("kind", "=", "network")
+            .where("kind", "in", ["network", "git"])
             .where("status", "=", "pending"));
         if (convs.length === 0)
             return { records: [], seqs: new Map() };
@@ -1281,7 +1539,7 @@ let ApprovalsService = class ApprovalsService {
             .innerJoin("runs as r", "r.id", "a.run_id")
             .selectAll("a")
             .where("a.conversation_id", "in", convs)
-            .where("a.kind", "=", "network")
+            .where("a.kind", "in", ["network", "git"])
             .where("a.status", "=", "pending")
             .where(sql `a.expires_at > now()`)
             .where("r.status", "in", ["running", "waiting"])
@@ -1522,6 +1780,9 @@ __decorate([
 __decorate([
     Transactional()
 ], ApprovalsService.prototype, "requestNetworkIn", null);
+__decorate([
+    Transactional()
+], ApprovalsService.prototype, "requestGitIn", null);
 __decorate([
     WithLock({ key: "network-ask-#{1}", ttl: 60_000, waitTimeout: 45_000 })
 ], ApprovalsService.prototype, "decideNetwork", null);
@@ -1552,6 +1813,12 @@ __decorate([
 __decorate([
     Transactional({ propagation: "mandatory" })
 ], ApprovalsService.prototype, "keepTrialNetworkGrant", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ApprovalsService.prototype, "allowRepoIn", null);
+__decorate([
+    Transactional({ propagation: "mandatory" })
+], ApprovalsService.prototype, "keepTrialGitGrant", null);
 __decorate([
     Transactional()
 ], ApprovalsService.prototype, "expireIn", null);

package/dist/tools/builtin-names.d.ts

@@ -31,6 +31,7 @@ export declare const BUILTIN: {
     readonly ScheduleCreate: "ScheduleCreate";
     readonly ScheduleUpdate: "ScheduleUpdate";
     readonly ScheduleList: "ScheduleList";
+    readonly ScheduleTargets: "ScheduleTargets";
     readonly ScheduleDelete: "ScheduleDelete";
 };
 export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
@@ -55,7 +56,8 @@ export declare const BASH_COMPANION_TOOLS: readonly BuiltinName[];
 export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
 /**
  * The builtins that manage the person's scheduled tasks (scheduled tasks spec §11): create and
- * update are fixed asks ({@link R3_FIXED_ASK_TOOL_KEYS}), list and delete only read or narrow.
+ * update are fixed asks ({@link R3_FIXED_ASK_TOOL_KEYS}), list, targets and delete only read or
+ * narrow.
  */
 export declare const SCHEDULE_TOOL_NAMES: readonly BuiltinName[];
 /**
@@ -108,7 +110,7 @@ export declare const R3_FIXED_ASK_TOOL_KEYS: ReadonlySet<string>;
  * person manages tasks from the conversation they see, never from a child). `Agent` is removed
  * only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
  */
-export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver", "ScheduleCreate", "ScheduleUpdate", "ScheduleList", "ScheduleDelete"];
+export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver", "ScheduleCreate", "ScheduleUpdate", "ScheduleList", "ScheduleTargets", "ScheduleDelete"];
 /**
  * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
  * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,

package/dist/tools/builtin-names.js

@@ -31,6 +31,7 @@ export const BUILTIN = {
     ScheduleCreate: "ScheduleCreate",
     ScheduleUpdate: "ScheduleUpdate",
     ScheduleList: "ScheduleList",
+    ScheduleTargets: "ScheduleTargets",
     ScheduleDelete: "ScheduleDelete",
 };
 /**
@@ -74,12 +75,14 @@ export const SANDBOX_ASK_TOOL_NAMES = new Set([
 ]);
 /**
  * The builtins that manage the person's scheduled tasks (scheduled tasks spec §11): create and
- * update are fixed asks ({@link R3_FIXED_ASK_TOOL_KEYS}), list and delete only read or narrow.
+ * update are fixed asks ({@link R3_FIXED_ASK_TOOL_KEYS}), list, targets and delete only read or
+ * narrow.
  */
 export const SCHEDULE_TOOL_NAMES = [
     BUILTIN.ScheduleCreate,
     BUILTIN.ScheduleUpdate,
     BUILTIN.ScheduleList,
+    BUILTIN.ScheduleTargets,
     BUILTIN.ScheduleDelete,
 ];
 /**
@@ -160,6 +163,7 @@ export const CHILD_REMOVED_TOOLS = [
     BUILTIN.ScheduleCreate,
     BUILTIN.ScheduleUpdate,
     BUILTIN.ScheduleList,
+    BUILTIN.ScheduleTargets,
     BUILTIN.ScheduleDelete,
 ];
 /**
@@ -198,6 +202,7 @@ export const BUILTIN_TOOL_KINDS = {
     [BUILTIN.ScheduleCreate]: "tool",
     [BUILTIN.ScheduleUpdate]: "tool",
     [BUILTIN.ScheduleList]: "tool",
+    [BUILTIN.ScheduleTargets]: "tool",
     [BUILTIN.ScheduleDelete]: "tool",
 };
 /**

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

@@ -9,9 +9,9 @@ import type { ScheduleChat, ScheduledTask, ScheduleTrigger } from "../../schedul
 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.
+ * `ScheduleList`, `ScheduleTargets` 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)
@@ -21,15 +21,17 @@ import type { BuiltinTool } from "../registry.js";
  * - 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.
+ * - `ScheduleList` (allow) lists the person's own tasks; `ScheduleTargets` (allow) lists the IM
+ *   chats they can deliver to (the service's `chatTargets`, the same data as the route);
+ *   `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).
+ *   (`channel_threads`), else a `conversation` task for this conversation. `mode: "chat"` posts into
+ *   the IM chat named by `chat`. 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">;
+export type ScheduleService = Pick<ScheduledTasksService, "create" | "update" | "list" | "remove" | "addGrants" | "removeGrant" | "chatTargets">;
 /**
  * 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
@@ -102,6 +104,6 @@ export declare class ScheduleUpdates {
     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. */
+/** The five schedule builtins. */
 export declare function scheduleTools(deps: ScheduleToolsDeps): BuiltinTool[];
 export {};