Let a Bot at its own endpoint hand work to another Bot (#718)

* Let a Bot at its own endpoint hand work to another Bot

The grant route already accepted a remote grantee, and remote Bots call
back for message_bot through the same coordination tools and handoff
desk as built-in Bots. But botsReachableFrom kept only built-in
grantees, so a remote Bot was never offered message_bot and a call it
made anyway was refused as not granted. agentRunsHere did the same for
the handoff panel, which hid the switches.

botsReachableFrom now counts a grant whatever the grantee's type, and
agentRunsHere becomes agentCanHandOn, true for any Bot that exists.

* Clean up queued hops by the suite's actor in the handoff integration tests

The handoff suites deleted work items by a key prefix, but a hop's key is
hop:<hash>:<hash>, so nothing was deleted and every hop a suite sent stayed
queued. The end-to-end suite's sweep claims any queued hop, so it delivered
other suites' hops and its own assertions failed whenever it ran after
them. Each suite now deletes the hops its own actor queued.

Author: davidmckayv

CHANGELOG.md

@@ -8,6 +8,14 @@ Newest first. `Unreleased` is what is on `main` and not yet tagged.
 
 ## Unreleased
 
+### A coworker at its own endpoint can hand work to another Bot
+
+A grant letting a remote Bot (a coworker at its own endpoint) hand work to another Bot was accepted and stored, but the grant read kept only built-in Bots, so the remote Bot was never
+offered `message_bot` and a call it made anyway was refused as not granted. The read now counts a
+grant whatever the Bot's type, so a remote Bot hands work on through the same signed callback, grant
+check, caps and audit rows as a built-in one, to a built-in Bot or to another remote Bot. The
+coworker's handoff panel now offers it the same switches.
+
 ### A channel cursor with a malformed time reads as the first page, not a 500
 
 `GET /api/channels` only checked that a cursor's time was a string before casting it with

app/src/components/agents/handoff-panel.tsx

@@ -106,9 +106,9 @@ export function HandoffPanel({ agentId }: { agentId: string }) {
             <ItemTitle>This coworker cannot hand work on</ItemTitle>
             {/* Unclamped for the same reason as above: three lines, and the third is the useful one. */}
             <ItemDescription className="line-clamp-none">
-              Handing work on is a tool that runs inside this deployment's own
-              loop, and this coworker runs as its own agent — so there is
-              nothing to grant it. It can still be asked by Bots that can.
+              This deployment has nowhere to record which Bots it may hand work
+              to, so there is nothing to grant it. It can still be asked by Bots
+              that can.
             </ItemDescription>
           </ItemContent>
         </Item>

server/src/agents/profile-store.ts

@@ -261,9 +261,8 @@ export type AgentRun = {
  * do-not-fabricate instruction. Copy it and you get a coworker with the name, the title, the avatar,
  * and none of that.
  *
- * The type is carried too, not only the configuration. A copy written as `remote_ag_ui` also cannot
- * be granted handoff for the rest of its life: `agentRunsHere` and `botsReachableFrom` both key on
- * `agents.type == "built_in"`, so the original may hand work on and its copy silently may not.
+ * The type is carried too, not only the configuration, so a copy runs the same way its original
+ * does.
  *
  * `null` means there is nothing to run this copy on, which the caller turns into
  * {@link ManagedAgentUnavailableError}. That can now only happen for a source that had neither an

server/src/agents/routes.ts

@@ -264,12 +264,11 @@ export function createAgentRoutes(
     /** The Bots this one may address today, read per call so a revoked grant stops showing. */
     reachableFrom: (agentId: string) => Promise<readonly string[]>;
     /**
-     * Whether this Bot can be a grantee at all — the handing-on tool executes inside this
-     * deployment's own run loop, so only a Bot that runs in it can be offered one. Exposed so the
-     * screen can say that once, instead of letting every switch fail with the same refusal.
-     * Optional so a caller without a plugin store answers "no" rather than crashing the read.
+     * Whether this Bot can be a grantee at all: any Bot that exists, built in or at its own
+     * endpoint, since both reach the same handoff desk. Optional so a caller without a plugin store
+     * answers "no" rather than crashing the read.
      */
-    runsHere?: (agentId: string) => Promise<boolean | undefined>;
+    canHandOn?: (agentId: string) => Promise<boolean | undefined>;
   },
   /**
    * Whether a coworker can run on this deployment's own Bot, i.e. be created with no endpoint.
@@ -720,8 +719,8 @@ export function createAgentRoutes(
           reachable: handoff ? await handoff.reachableFrom(agentId) : [],
           // Whether this Bot can hold such a grant at all; the write path refuses one that cannot,
           // and the screen should say so before a person flips switches that can only bounce.
-          grantable: handoff?.runsHere
-            ? ((await handoff.runsHere(agentId)) ?? false)
+          grantable: handoff?.canHandOn
+            ? ((await handoff.canHandOn(agentId)) ?? false)
             : false,
         },
       });

server/src/app.ts

@@ -1308,7 +1308,7 @@ export function createApp(
               reachableFrom: (agentId) =>
                 pluginStore.botsReachableFrom(agentId),
               // The same answer the write path checks, read up front so the screen can say it once.
-              runsHere: (agentId) => pluginStore.agentRunsHere(agentId),
+              canHandOn: (agentId) => pluginStore.agentCanHandOn(agentId),
             }
           : undefined,
         // Whether "built-in" is a kind of coworker this deployment can actually make: the create

server/src/plugins/store.ts

@@ -4230,22 +4230,21 @@ export function createPluginStore(options: PluginStoreOptions) {
      * "may this person put their skill on that Bot", and a whole profile is more than that needs.
      */
     /**
-     * Whether this Bot's run happens in this process, rather than at an endpoint somewhere.
+     * Whether this Bot can be granted handing work on, or `undefined` if there is no such Bot.
      *
-     * Undefined for a Bot nobody has heard of. Asked because a tool this deployment executes can
-     * only be offered to a run it builds: a Bot at an endpoint runs its own loop and is handed
-     * descriptions of what it may call back for, and handing work to another Bot is not one of them.
+     * Any Bot that exists can: a built-in Bot runs `message_bot` in this process, and a Bot at its
+     * own endpoint calls back for it through the signed tool callback, which reaches the same desk.
      */
-    async agentRunsHere(agentId: string): Promise<boolean | undefined> {
+    async agentCanHandOn(agentId: string): Promise<boolean | undefined> {
       const [row] = await database
-        .select({ type: agents.type })
+        .select({ id: agents.id })
         .from(agents)
         .innerJoin(agentProfiles, eq(agentProfiles.agentId, agents.id))
         // A deleted Bot is not one anybody may be given, and answering about it at all would say it
         // had existed.
         .where(and(eq(agents.id, agentId), isNull(agentProfiles.deletedAt)))
         .limit(1);
-      return row ? row.type === "built_in" : undefined;
+      return row ? true : undefined;
     },
 
     /**
@@ -4418,29 +4417,23 @@ export function createPluginStore(options: PluginStoreOptions) {
      * is a single indexed read, which is the right price for that.
      */
     /**
-     * The Bots this one may hand work to, and can actually reach.
+     * The Bots this one may hand work to.
      *
-     * FILTERED AT READ TIME, not only when the grant is made. Refusing a new grant to a Bot that
-     * runs at its own endpoint stops one being created; it does nothing about the ones already
-     * there, or about a Bot that was built in when it was granted and was pointed at an endpoint
-     * afterwards. Those rows read as configured and are inert, which is the shape of thing an
-     * administrator debugs for an afternoon: the grant is right there in the table and no hop ever
-     * happens.
+     * Whatever the grantee's type. A Bot at its own endpoint is offered `message_bot` as a tool it
+     * calls back for, and the call reaches the same handoff desk, grant check and caps as a built-in
+     * Bot's (see `createCoordinationTools`). This used to keep only built-in grantees, from before
+     * remote Bots could call back for coordination, which left every remote Bot's grant reading as
+     * configured while no hop ever happened.
      *
-     * The asking side is the one that matters here — a Bot at an endpoint runs its own loop and is
-     * never offered this tool — so it is the grantee, `agent_id`, that is checked.
+     * The join keeps a grant held by a Bot that no longer exists from counting.
      */
     async botsReachableFrom(agentId: string): Promise<string[]> {
       const rows = await database
         .select({ ref: pluginGrants.ref })
         .from(pluginGrants)
         .innerJoin(agents, eq(agents.id, pluginGrants.agentId))
         .where(
-          and(
-            eq(pluginGrants.kind, "bot"),
-            eq(pluginGrants.agentId, agentId),
-            eq(agents.type, "built_in"),
-          ),
+          and(eq(pluginGrants.kind, "bot"), eq(pluginGrants.agentId, agentId)),
         );
       return rows.map((row) => row.ref);
     },

server/tests/agent-handoff-endtoend.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomUUID } from "node:crypto";
-import { and, eq, like } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import { createHandoffDesk } from "../src/agents/handoff";
 import {
   createHandoffRunner,
@@ -67,7 +67,11 @@ const desk = createHandoffDesk({
 });
 
 async function clean() {
-  await database.delete(workItems).where(like(workItems.key, `${RUN}%`));
+  // By the suite's own actor, which every hop's payload carries. A hop's key is `hop:<hash>:<hash>`,
+  // so a key prefix matches nothing, and a hop left queued is claimed by the next suite's sweep.
+  await database
+    .delete(workItems)
+    .where(sql`${workItems.payload}->>'actorId' = ${ACTOR}`);
   for (const id of [ASKER, TARGET]) {
     await database.delete(pluginGrants).where(eq(pluginGrants.agentId, id));
     await database.delete(agentProfiles).where(eq(agentProfiles.agentId, id));

server/tests/agent-handoff.integration.test.ts

@@ -1,6 +1,6 @@
 import { afterAll, beforeEach, describe, expect, test } from "bun:test";
 import { randomUUID } from "node:crypto";
-import { and, eq, like } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import { createHandoffDesk, HANDOFF_KIND } from "../src/agents/handoff";
 import { createAgentProfileStore } from "../src/agents/profile-store";
 import { createAuditStore } from "../src/audit";
@@ -53,7 +53,11 @@ const desk = createHandoffDesk({
 });
 
 async function clean() {
-  await database.delete(workItems).where(like(workItems.key, `run-${suite}%`));
+  // By the suite's own actor, which every hop's payload carries. A hop's key is `hop:<hash>:<hash>`,
+  // so a key prefix matches nothing, and a hop left queued is claimed by the next suite's sweep.
+  await database
+    .delete(workItems)
+    .where(sql`${workItems.payload}->>'actorId' = ${ACTOR}`);
   for (const id of [ASKER, TARGET]) {
     await database.delete(pluginGrants).where(eq(pluginGrants.agentId, id));
     await database.delete(agentProfiles).where(eq(agentProfiles.agentId, id));

server/tests/agent-routes.test.ts

@@ -698,7 +698,7 @@ describe("which Bots a Bot may hand work to", () => {
       enabled: true,
       canGrant: true,
       reachable: ["knowledge"],
-      // No runsHere reader was wired, and a Bot nothing can vouch for is not offered grants.
+      // No canHandOn reader was wired, and a Bot nothing can vouch for is not offered grants.
       grantable: false,
     });
   });

server/tests/plugin-routes.test.ts

@@ -377,10 +377,10 @@ describe("refreshing a server that cannot be resolved", () => {
  */
 function grantsApp(
   role: "admin" | "user" = "admin",
-  runsHere: (agentId: string) => boolean | undefined = (agentId) => {
+  canHandOn: (agentId: string) => boolean | undefined = (agentId) => {
     // Undefined is "no such Bot", which is what the store answers for one nobody registered.
     if (agentId === "never-registered") return undefined;
-    return agentId !== "at-an-endpoint";
+    return true;
   },
 ) {
   /**
@@ -416,7 +416,7 @@ function grantsApp(
     },
     skillOwner: async () => null,
     agentOwner: async () => null,
-    agentRunsHere: async (agentId: string) => runsHere(agentId),
+    agentCanHandOn: async (agentId: string) => canHandOn(agentId),
     agentIsRegistered: async (agentId: string) =>
       agentId !== "never-registered",
   });