Skip to content

Open-source AI coworkers that each get a computer of their own: a browser, files and tools, with every action decided before it happens and recorded after. Bring any AG-UI agent.

11.8 KB
Raw Blame
import { z } from "zod";
import type { PluginServer, PluginSkill } from "@/lib/plugins/queries";
import { type SkillFormValues, skillFormSchema } from "./form";

/**
 * A skill a Bot proposes during a conversation, and the checks it goes through before anybody is
 * asked to approve it.
 *
 * WHY A SEPARATE SHAPE FROM THE FORM'S. `form.ts` describes what a person typed into four fields; a
 * model hands over the same four as arguments it may have got wrong in ways a form cannot — a slug
 * with a capital letter in it, a title the length of a paragraph, `tools` arriving as a string. So
 * the model-facing schema is permissive about types and the checking is done afterwards, against the
 * same `skillFormSchema` the form uses. That way a Bot writing a skill and a person writing one are
 * held to one rule, and there is no second parser to drift from the server's.
 *
 * Nothing here decides whether the skill may be saved. That is the server's, and it stays the
 * server's: a skill is an instruction rather than a capability, so the question is only ever whose
 * name the slug is under, which `POST /api/plugins/skills` answers with a sentence.
 */

/**
 * What the card answers its tool call with, and the one fact it reads back out.
 *
 * WHY THESE ARE HERE AND NOT ON THE CARD. A completed card has only the result string to go on — the
 * SDK hands back what the tool answered, not what happened — so whether to offer the "put it on a
 * Bot" link is decided by reading the sentence. Written on the card, the sentence and the reader of
 * the sentence were two literals a reword could silently separate, and the failure is a link that
 * quietly stops appearing. Paired here, and pinned by a test, they cannot drift.
 *
 * The sentences are addressed to the model, because that is who receives them. Each one says what to
 * do next, since a tool result that only reports state leaves the Bot to guess whether the turn is
 * finished.
 */
const SAVED_MARKER = "Saved.";

export const skillCardAnswer = {
  saved: (slug: string) =>
    `${SAVED_MARKER} /${slug} is now in the slash menu. It is on no Bot yet — putting it on one is done from the Skills page, so tell the person that is the remaining step.`,
  declined: () =>
    "The person did not save this skill. Ask what to change rather than saving it again unchanged.",
  /** A proposal the fields refuse, answered rather than shown as a question. See the card. */
  unwritable: (problems: readonly string[]) =>
    `Not saved, and the person was not asked, because the skill is not valid: ${problems.join(" ")} Fix those and propose it again.`,
};

/** Whether a completed card's recorded answer is one that wrote a skill. */
export function wasSaved(result: string): boolean {
  return result.startsWith(SAVED_MARKER);
}

/**
 * The skill whose grant turns a Bot into one you can write skills with.
 *
 * The app offers `save_skill` and the reads beside it only while the active Bot holds this slug, and
 * the shipped package is what puts the slug in the deployment and on a Bot. So the two have to agree:
 * rename it in one place and writing a skill in a conversation stops working with nothing on screen
 * to say why. `skill-creator-slug.test.ts` is the guard, which is why this lives in a module with no
 * React in it rather than beside the hooks that read it.
 *
 * Not an MCP ref, and deliberately not declared in `skills.yaml`'s `tools:`. A declaration there is
 * intersected with the Bot's MCP grants, so naming the app's own tools would name nothing.
 */
export const SKILL_CREATOR_SLUG = "skill-creator";

/**
 * The arguments the model is offered, described for the model rather than for us.
 *
 * Every `describe` here is read by the thing filling the field in, which is why they say what good
 * looks like instead of restating the type. The slug rule is spelled out because a model that has
 * seen `Find A Document` in a title will otherwise offer it as a command.
 */
export const proposedSkillSchema = z.object({
  slug: z
    .string()
    .describe(
      "The `/` command, in lower-case letters, numbers and hyphens: `check-a-claim`, not `Check A Claim`. 2 to 40 characters. This is the skill's identity — reusing one that already exists replaces that skill.",
    ),
  title: z
    .string()
    .describe(
      "What the skill is called in the menu, in a few words of sentence case: `Check a claim against a source`. Up to 120 characters.",
    ),
  summary: z
    .string()
    .optional()
    .describe(
      "One line under the title, saying what invoking it will do. Up to 200 characters. Omit only if the title already says everything.",
    ),
  instructions: z
    .string()
    .describe(
      "The instruction the Bot follows when somebody invokes this skill, written as directions to the Bot in the imperative. Say what to do, in what order, what to do when a step turns up nothing, and what the answer should contain. Explain why a step matters rather than only naming it. Do not describe the skill in the third person, and do not address the person invoking it.",
    ),
  tools: z
    .array(z.string())
    .optional()
    .describe(
      "The tools the skill needs, as `serverId/toolName` refs from list_skill_tools. This is a declaration, not a grant: naming a tool cannot make it callable, and a skill naming a tool its Bot does not hold simply loads nothing. Omit for a skill that is only prose.",
    ),
});

export type ProposedSkill = z.infer<typeof proposedSkillSchema>;

/** What checking a proposal answers with: the four fields to save, or the problems to fix. */
export type CheckedProposal =
  | { ok: true; values: SkillFormValues }
  | { ok: false; problems: string[] };

/**
 * Hold a proposal to the same rule the form is held to.
 *
 * Checked here rather than left to the server because the alternative is a person being shown a card
 * for a skill that cannot be saved, pressing Create, and reading a validation message as though they
 * had done something wrong. A problem the model can fix should reach the model, not the person.
 *
 * The problems name their field, because that is the only part a model needs in order to try again:
 * "slug: Lower-case letters, numbers and hyphens, 2 to 40 characters." is a repair instruction,
 * while "invalid input" is a guess.
 */
export function checkProposal(args: {
  slug?: unknown;
  title?: unknown;
  summary?: unknown;
  instructions?: unknown;
  tools?: unknown;
}): CheckedProposal {
  const parsed = skillFormSchema.safeParse({
    slug: typeof args.slug === "string" ? args.slug : "",
    title: typeof args.title === "string" ? args.title : "",
    // Optional on the server too, so an absent one is an empty one rather than a problem.
    summary: typeof args.summary === "string" ? args.summary : "",
    instructions:
      typeof args.instructions === "string" ? args.instructions : "",
    /*
     * Anything that is not a list of strings is dropped rather than refused. A model that answers
     * `tools: "google-drive/search_files"` meant the one tool, and a refusal here would send it back
     * to redo the whole proposal over a comma. Declaring nothing is always a valid skill.
     */
    tools: toolRefsIn(args.tools),
  });
  if (parsed.success) return { ok: true, values: parsed.data };
  return {
    ok: false,
    problems: parsed.error.issues.map((issue) => {
      const field = issue.path.join(".");
      return field ? `${field}: ${issue.message}` : issue.message;
    }),
  };
}

/** Tool refs out of whatever the model sent, keeping the strings and a lone string on its own. */
function toolRefsIn(value: unknown): string[] {
  if (typeof value === "string") return value.trim() ? [value.trim()] : [];
  if (!Array.isArray(value)) return [];
  return value
    .filter((ref): ref is string => typeof ref === "string")
    .map((ref) => ref.trim())
    .filter((ref) => ref.length > 0);
}

/**
 * Whose a skill is, in the words the answer uses.
 *
 * Ownership rather than permission, and the distinction is the point. Who may replace a slug is
 * decided by the server and nowhere else; what this says is the fact a model needs in order not to
 * try — the same fact the Skills page groups its two lists by. A model told "someone else's" and
 * told in its instructions that those cannot be replaced will pick another name, and if it tries
 * anyway the server's own sentence comes back on the card.
 */
export function ownershipOf(
  skill: Pick<PluginSkill, "ownerUserId">,
  meId: string | undefined,
): "yours" | "the deployment's" | "someone else's" {
  if (skill.ownerUserId === null) return "the deployment's";
  return skill.ownerUserId === meId ? "yours" : "someone else's";
}

/**
 * The skills that already exist here, as the answer to `list_skills`.
 *
 * One line each, because the reason to ask is to pick a name and to find the skill being improved,
 * and a paragraph per skill would push the useful part of a long list out of the run. The
 * instructions are deliberately not included: forty skills' instructions is most of a context
 * window, and a Bot improving one asks for that skill by slug.
 */
export function describeSkills(
  skills: readonly PluginSkill[],
  meId: string | undefined,
): string {
  if (skills.length === 0) {
    return "No skills exist here yet. Any slug is free.";
  }
  const lines = skills.map((skill) => {
    const parts = [
      `/${skill.slug} — ${skill.title} (${ownershipOf(skill, meId)})`,
    ];
    if (skill.summary) parts.push(skill.summary);
    if (skill.tools.length > 0) parts.push(`needs ${skill.tools.join(", ")}`);
    return `- ${parts.join(" · ")}`;
  });
  return [
    `${skills.length} skill${skills.length === 1 ? "" : "s"} exist here. A slug that is not yours cannot be replaced — pick another name.`,
    ...lines,
  ].join("\n");
}

/**
 * One skill's instructions in full, for improving it rather than listing it.
 *
 * Separate from {@link describeSkills} so the expensive field is fetched deliberately, one skill at
 * a time, by a Bot that has been asked to change that skill.
 */
export function describeSkill(skill: PluginSkill): string {
  return [
    `/${skill.slug} — ${skill.title}`,
    skill.summary ? `Summary: ${skill.summary}` : "Summary: (none)",
    skill.tools.length > 0
      ? `Declared tools: ${skill.tools.join(", ")}`
      : "Declared tools: (none)",
    "Instructions:",
    skill.instructions,
  ].join("\n");
}

/**
 * The tool refs a skill here could name, as the answer to `list_skill_tools`.
 *
 * Every connected server's tools, not the active Bot's grants, and that is deliberate rather than
 * loose. A declaration is not a grant: the offer a run gets is the intersection of what the skill
 * names with what the Bot holds, so a skill may — and should — name tools for a connector this
 * deployment has not granted to this Bot yet, which is what makes granting it later the only step.
 * Narrowing this list to the current Bot's grants would quietly produce skills that stop working the
 * moment they are put on a different Bot.
 */
export function describeToolRefs(servers: readonly PluginServer[]): string {
  const connected = servers.filter((server) => server.tools.length > 0);
  if (connected.length === 0) {
    return "No connector here offers any tools yet, so a skill written now can only be prose. That is ordinary — most skills are.";
  }
  const blocks = connected.map((server) => {
    const tools = server.tools.map(
      (tool) =>
        `  - ${tool.ref}${tool.effect === "write" ? " (writes)" : ""} — ${tool.description || tool.name}`,
    );
    return [`${server.title} (${server.id}):`, ...tools].join("\n");
  });
  return [
    "Refs are `serverId/toolName`.",
    // The server resolves these against its catalogue, so a research skill outlives a provider swap.
    "For public-web research, declare `@research/search` and `@research/fetch` instead of one provider's tools: they stand for search and page reading on whichever research connector the Bot holds.",
    ...blocks,
  ].join("\n");
}