Make a coworker by talking to one, and grant it nothing

Making a coworker means answering a form, and the field that decides
everything is the one a form is worst at. `role_description` is not a
label: with no endpoint it becomes the standing instruction handed to a
model on every turn in every channel that coworker is in. People write a
sentence, get a coworker that answers vaguely, and never go back.

The three questions that make one useful are the ones nobody answers
unprompted — what it must never conclude, what it says when the evidence
is thin, and whether something here already does the job. A form cannot
ask a follow-up. A conversation can.

So the deployment ships a `bot-creator` skill whose instruction is how to
run that interview, and a Bot holding it is offered four tools:
`list_bots`, `read_bot`, `list_bot_skills` and `save_bot`. The grant is
the gate rather than a flag — four more tools on every run costs the
per-run narrowing more than it buys, and a Bot for looking up
transactions has no business making coworkers.

The tools ride the signed-in session from the browser, so `POST
/api/agents` answers who may and writes `bot.created` with the actor on
it, unchanged. A server-side tool would have to carry an actor into runs
that have none — a routine, a Slack thread, a schedule — and the first
way that goes wrong is a coworker created under a name nobody chose.

The card is the whole tool; there is no handler behind it. It shows the
entire role description, unclipped, because that text will run on
somebody's behalf and a clamp would hide half of what they are agreeing
to. It grants skills and nothing else: no address, no connector, no tool,
no boundary, no visibility. A card that could grant capability would make
asking a Bot the fastest route around the screens that decide it.

Two changes to the create path come with it, because without them the
interview would have to end by asking somebody for a URL. `store.create`
accepts a system prompt and writes a `built_in` coworker when there is
neither an endpoint nor a Bot in the box, and the route passes the role
description when no endpoint was given. Every other path is untouched:
give an address and it is a remote Bot, as before, and `update` cannot
take a prompt at all — changing an existing Bot's type is a different act.

Two defects found by using it, both about state rather than logic. The
first conversation answered "No skills exist here yet" to a deployment
holding nine, because the handler read a query that had not loaded; an
empty list and an unloaded list were sharing a code path, and the Bot
repeated the tidier one as fact. The answers now fetch when asked, from a
module a test calls against a cold client. And the link on a completed
card lived in component state, so it would have drawn once and stopped
for anybody who reloaded — a card is re-rendered from the transcript with
the arguments and the answer and nothing else. The coworker's id travels
in the answer now, read back by a function paired with the sentence.

Verification: 2164 pass, 23 skip, 0 fail across 179 files; format, lint
and typecheck clean. The card test follows this repository's DOM harness
— register in `beforeAll`, unregister in `afterAll`, queries off
`render()` — because a file that registers at module scope and queries
the global `screen` passes alone and fails every case in a full run.

Author: jerelvelarde

app/src/components/agents/proposed-bot.tsx

@@ -0,0 +1,298 @@
+import { Link } from "@tanstack/react-router";
+import { useEffect, useRef, useState } from "react";
+import { Badge, GalleryFrame } from "@/components/gallery/frame";
+import { Button } from "@/components/ui/button";
+import type { AgentFormValues } from "@/lib/agents/form";
+import {
+  botCardAnswer,
+  checkProposal,
+  createdBotIdIn,
+  type ProposedBot,
+  wasCreated,
+} from "@/lib/agents/proposal";
+
+/**
+ * The coworker a Bot has written, put in front of the person before it exists.
+ *
+ * WHY THERE IS A CARD AT ALL. A coworker is not a document: the role description below becomes a
+ * standing instruction handed to a model on every turn in every channel it is in, and it was written
+ * by something that was told about the job second-hand. So the same rule the template consent screen
+ * follows applies here — the whole of that text is shown, unabridged and unclipped, before anything
+ * is created, because a person cannot agree to instructions they were not shown.
+ *
+ * The whole tool is this card. There is no handler behind it: the run suspends here, and nothing is
+ * written until a button is pressed.
+ *
+ * WHAT IT DELIBERATELY CANNOT DO. No address, no connector, no tool, no boundary and no visibility
+ * change. The coworker arrives private, holding whatever skills were agreed and nothing else, and
+ * everything it might reach is granted afterwards on its profile by somebody who may. A card that
+ * could grant capability would make "ask the Bot for it" the fastest route around the screens that
+ * exist to decide it.
+ */
+
+/** What creating actually did, since creating and granting are two calls and one can fail alone. */
+export type CreatedBot = {
+  agentId: string;
+  name: string;
+  granted: string[];
+  failed: string[];
+};
+
+export type ProposedBotCardProps = {
+  /** Partial while the model is still streaming the arguments. */
+  args: Partial<ProposedBot>;
+  /**
+   * A coworker already here whose name this one reuses, when there is one.
+   *
+   * Drives the wording and nothing else. Names do not have to be unique, so this is not a refusal —
+   * it is the fact somebody needs in order to notice they are about to end up with two Renewal Desks
+   * on one roster and no way to tell them apart in a channel list.
+   */
+  clashes?: { title: string; ownership: string };
+  /** Answering resumes the Bot. Absent while streaming, and once this card has been answered. */
+  respond?: (result: unknown) => Promise<void>;
+  /** The recorded answer, once there is one. Completed cards show it instead of controls. */
+  result?: string;
+  create: (values: AgentFormValues, skills: string[]) => Promise<CreatedBot>;
+};
+
+export function ProposedBotCard({
+  args,
+  clashes,
+  respond,
+  result,
+  create,
+}: ProposedBotCardProps) {
+  const [sending, setSending] = useState<"create" | "decline" | null>(null);
+  /**
+   * A refusal from the server, kept on the card rather than answered with.
+   *
+   * The run stays suspended, because both things worth doing next need it to be — pressing again
+   * after whatever the refusal named has been dealt with, or declining. Answering the tool with the
+   * error would end the turn and leave the person retyping their request.
+   */
+  const [refusal, setRefusal] = useState<string | null>(null);
+
+  if (result !== undefined) {
+    /*
+     * The coworker read back out of the answer rather than out of state. This card is re-rendered
+     * from the transcript on every reload, when whatever this component remembered is gone; the id
+     * is the server's, so unlike a skill's slug it is not in the arguments either. See
+     * `createdBotIdIn`.
+     */
+    const madeId = wasCreated(result) ? createdBotIdIn(result) : null;
+    return (
+      <GalleryFrame
+        action={<Badge tone="neutral">Done</Badge>}
+        title={titleFor(args.name, clashes)}
+      >
+        <p className="text-sm">{result}</p>
+        {madeId ? <TalkToIt agentId={madeId} name={args.name} /> : null}
+      </GalleryFrame>
+    );
+  }
+
+  if (!respond) {
+    return (
+      <GalleryFrame title={titleFor(args.name, clashes)}>
+        <p className="text-muted-foreground text-sm">Writing the coworker…</p>
+      </GalleryFrame>
+    );
+  }
+
+  const checked = checkProposal(args);
+  if (!checked.ok) {
+    return <Unwritable problems={checked.problems} respond={respond} />;
+  }
+  const { values, skills } = checked;
+
+  const make = async () => {
+    setSending("create");
+    setRefusal(null);
+    let outcome: CreatedBot;
+    try {
+      outcome = await create(values, skills);
+    } catch (cause) {
+      // Left on the card with the buttons still live. See `refusal` above.
+      setSending(null);
+      setRefusal(
+        cause instanceof Error
+          ? cause.message
+          : "The coworker was not created.",
+      );
+      return;
+    }
+    /*
+     * Pressing again is not offered from here on: the coworker exists, and a second press would make
+     * a second one. The answer carries its id, which is what the completed card links to.
+     */
+    await answer(respond, botCardAnswer.created(outcome));
+  };
+
+  const decline = async () => {
+    setSending("decline");
+    await answer(respond, botCardAnswer.declined());
+  };
+
+  return (
+    <GalleryFrame
+      action={<Badge tone="caution">Waiting on you</Badge>}
+      caption={
+        clashes
+          ? `There is already a ${clashes.title} here, which is ${clashes.ownership}. Names do not have to be unique, but two with the same name are hard to tell apart in a channel list.`
+          : "Nothing is created until you press the button."
+      }
+      title={titleFor(values.name, clashes)}
+    >
+      <dl className="grid grid-cols-[minmax(0,7rem)_1fr] gap-x-4 gap-y-1.5 text-sm">
+        <dt className="truncate text-muted-foreground">Name</dt>
+        <dd className="min-w-0 break-words font-medium">{values.name}</dd>
+        <dt className="truncate text-muted-foreground">Job</dt>
+        <dd className="min-w-0 break-words">{values.title}</dd>
+        <dt className="truncate text-muted-foreground">Skills</dt>
+        <dd className="min-w-0 break-words">
+          {skills.length > 0 ? (
+            <span className="font-mono text-xs">
+              {skills.map((slug) => `/${slug}`).join(", ")}
+            </span>
+          ) : (
+            <span className="text-muted-foreground">None</span>
+          )}
+        </dd>
+      </dl>
+
+      <p className="mt-3 text-muted-foreground text-xs">
+        Its standing instructions. This text is given to a model on every turn.
+      </p>
+      {/*
+       * Scrolled rather than clamped, and the distinction is the whole point of the card. A clamp
+       * hides the second half of an instruction that will run on somebody's behalf from the one
+       * person being asked to agree to it; a scroller keeps every character reachable.
+       */}
+      <p className="mt-1 max-h-56 overflow-y-auto whitespace-pre-wrap rounded-md border border-border bg-muted/40 px-3 py-2 text-sm">
+        {values.roleDescription}
+      </p>
+
+      <p className="mt-2 text-muted-foreground text-xs">
+        It arrives private, with no address, no connector and no tool. Anything
+        it needs to reach is granted on its profile afterwards.
+      </p>
+
+      {refusal ? (
+        <p className="mt-3 text-destructive text-sm" role="alert">
+          {refusal}
+        </p>
+      ) : null}
+
+      <div className="mt-4 flex gap-2">
+        <Button
+          disabled={Boolean(sending)}
+          onClick={() => void make()}
+          size="sm"
+        >
+          {sending === "create" ? "Creating…" : "Create it"}
+        </Button>
+        <Button
+          disabled={Boolean(sending)}
+          onClick={() => void decline()}
+          size="sm"
+          variant="outline"
+        >
+          {sending === "decline" ? "…" : "Don't create"}
+        </Button>
+      </div>
+    </GalleryFrame>
+  );
+}
+
+function titleFor(
+  name: string | undefined,
+  clashes: { title: string } | undefined,
+): string {
+  const called = name?.trim() ? name.trim() : "a new coworker";
+  return clashes ? `Create ${called}, again` : `Create ${called}`;
+}
+
+/**
+ * Where the next step happens.
+ *
+ * The profile rather than a channel, because it is the screen that answers both remaining questions
+ * — what this coworker may reach, and whether anybody else can see it — and it carries the control
+ * that opens a conversation.
+ */
+function TalkToIt({
+  agentId,
+  name,
+}: {
+  agentId: string;
+  name: string | undefined;
+}) {
+  return (
+    <Link
+      className="mt-2 inline-block text-sm underline underline-offset-4"
+      search={{ agent: agentId }}
+      to="/agents"
+    >
+      Open {name?.trim() || "the coworker"}
+    </Link>
+  );
+}
+
+/**
+ * A proposal that cannot be created as written.
+ *
+ * Answered rather than shown as a question, because there is nothing for the person to decide: the
+ * fields are wrong in a way the model can fix, and the problems name their field so it can. The card
+ * still appears, so the transcript has no silent gap where a coworker was nearly made.
+ */
+function Unwritable({
+  problems,
+  respond,
+}: {
+  problems: string[];
+  respond: (result: unknown) => Promise<void>;
+}) {
+  /**
+   * Answered once, guarded by a ref rather than by the dependency list.
+   *
+   * `problems` is rebuilt from the arguments on every render and the grant queries behind this card
+   * poll, so a value-equal array arrives as a new identity every few seconds. Left to the deps, this
+   * would answer the same tool call again on each of them.
+   */
+  const answered = useRef(false);
+  useEffect(() => {
+    if (answered.current) return;
+    answered.current = true;
+    void answer(respond, botCardAnswer.unwritable(problems));
+  }, [problems, respond]);
+
+  return (
+    <GalleryFrame
+      action={<Badge tone="neutral">Not created</Badge>}
+      title="Create a coworker"
+    >
+      <p className="text-sm">
+        The coworker could not be created as written, so nothing was asked of
+        you. It is being redrafted.
+      </p>
+    </GalleryFrame>
+  );
+}
+
+/**
+ * Answering, with a failure to answer swallowed deliberately.
+ *
+ * The only way `respond` rejects is a run that has already ended — a reload, a stop, a card answered
+ * in another tab — and in every one of those the write has already happened or already not happened.
+ * Throwing here would surface a React error over a decision the person has finished making.
+ */
+async function answer(
+  respond: (result: unknown) => Promise<void>,
+  text: string,
+): Promise<void> {
+  try {
+    await respond(text);
+  } catch {
+    // The run this card belonged to is gone. Nothing further to do.
+  }
+}

app/src/lib/agents/answers.ts

@@ -0,0 +1,49 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { pluginsPageQueryOptions } from "@/lib/plugins/queries";
+import { describeBot, describeBots, describeGrantableSkills } from "./proposal";
+import { agentListQueryOptions } from "./queries";
+
+/**
+ * What the three reading tools answer with, fetched at the moment they are asked.
+ *
+ * THE BUG THIS SHAPE EXISTS TO PREVENT, which the very first conversation with this feature
+ * produced. The obvious wiring is a `useQuery` in the component and handlers closing over
+ * `data ?? []`. A run starts the moment somebody sends a message, and the model called
+ * `list_bot_skills` before that query had come back — so the handler read an empty array and
+ * answered "No skills exist here yet", which the Bot then told the person as a fact about their
+ * deployment. Nine skills existed.
+ *
+ * An empty list and an unloaded list are different answers and must not share a code path.
+ * `ensureQueryData` returns what is cached when there is something cached and fetches when there is
+ * not, so a tool called in the first second of a run waits for the truth rather than inventing a
+ * tidier one — and a run that never calls these pays for neither.
+ *
+ * They live here rather than inline in the hooks so that a test can call them cold, against a query
+ * client nothing has rendered, which is precisely the state the bug needed.
+ */
+
+export async function answerListBots(client: QueryClient): Promise<string> {
+  return describeBots(await client.ensureQueryData(agentListQueryOptions()));
+}
+
+export async function answerReadBot(
+  client: QueryClient,
+  name: string,
+): Promise<string> {
+  const wanted = name.trim().toLowerCase();
+  const known = await client.ensureQueryData(agentListQueryOptions());
+  const agent = known.find(
+    (candidate) => candidate.name.toLowerCase() === wanted,
+  );
+  if (!agent) {
+    return `There is no coworker called ${name} that this person can see. Call list_bots for the ones there are.`;
+  }
+  return describeBot(agent);
+}
+
+export async function answerListBotSkills(
+  client: QueryClient,
+): Promise<string> {
+  const page = await client.ensureQueryData(pluginsPageQueryOptions());
+  return describeGrantableSkills(page.skills);
+}