c8e3489 · 9de8329 · 2cfea22 · ba52ec1 · 96013ba · 072d01d
@@ -99,6 +99,7 @@
for a tunnel and a forge that sleeps.
| `origins` | `{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer | yes |
| `outsiders` | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes |
| `parent_unlink` | no input: stop signing in through the parent forge, as Settings does; refused when it is the account's last way in, and "Nothing to unlink." when nothing is linked; an admin token | yes |
| `person` | `{ username, limit?, cursor? }`: a person's public profile and the repositories you may see, as `GET /api/v1/users/:username` and its `/repos`; a private one you cannot read is never listed |  |
| `plan` | `{ app, issues }`: open up to 12 linked issues, all or none (see below) | yes |
| `preview` | `{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \| null, check: "green" \| "red" \| "running" \| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say |  |
| `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract |  |
@@ -111,7 +112,7 @@
for a tunnel and a forge that sleeps.
| `read_file` | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents |  |
| `repo` | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` |  |
| `repo_labels` | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes |
| `repo_settings` | `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes |
| `repo_settings` | `{ repo, description?, visibility? }` (admin): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes |
| `reports` | `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token | yes |
| `restore_drill` | no input: restore the newest snapshot as a drill and answer `{ verdict, failedStep?, says }`, worded as the Backups page's button; no store, a failure or a red drill is an answer, not an error; a forge admin's, with an admin token | yes |
| `returns` | `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours |  |
@@ -7,7 +7,7 @@
export const tool: Tool = {
  name: "app_members",
  doc: "`{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token",
  description:
    "The people a private app names, who may enter it and its previews. With `members`, plans.",
    "People a private app names, who may enter it and its previews. With `members`, plans.",
  inputSchema: {
    type: "object",
    properties: {
@@ -4,7 +4,7 @@
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "asks_decide",
  description:
    "Let the decider answer a hand-over (`item`: `parked:<id>`); only a sure set_aside clears it.",
    "Let the decider answer a hand-over (`item`: `parked:<id>`); only a sure set_aside clears.",
  inputSchema: {
    type: "object",
    properties: { item: { type: "string", maxLength: 80 } },
@@ -4,7 +4,7 @@
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "asks_proposal",
  description:
    "Act on a wave proposal (`asks` row): `approve`, `redirect` (`words`), `later` (`again`). Owner.",
    "Act on a wave proposal: `approve`, `redirect` (`words`), `later` (`again`). Owner.",
  inputSchema: {
    type: "object",
    properties: {
@@ -7,7 +7,7 @@
export const tool: Tool = {
  name: "attach_look",
  doc: "`{ app, pull, width, says, image, dryRun? }`: attach a look to an open pull: a PNG or JPEG (at most 5 MB, base64 in `image`), `width` phone or desktop, one line in `says`; planned first (`dryRun` is true unless `false`)",
  description:
    "Attach a PNG or JPEG (base64 `image`, max 5 MB) to an open pull: `phone`/`desktop`, `says`.",
    "Attach a PNG/JPEG (base64 `image`, max 5 MB) to an open pull: `phone`/`desktop`, `says`.",
  inputSchema: {
    type: "object",
    properties: {
@@ -11,7 +11,7 @@
export const tool: Tool = {
  name: "branches",
  doc: "`{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: \"tags\"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act",
  description:
    "A repository's branches; `name`, `action` create (from `from`) or delete one, not the default.",
    "A repo's branches; `name`, `action` create (from `from`) or delete one, not the default.",
  inputSchema: {
    type: "object",
    properties: {
@@ -7,7 +7,7 @@
export const tool: Tool = {
  name: "capacity",
  doc: "`{ key?, value?, dryRun? }` (forge admin): the forge's capacity and guards, live (crew and checks concurrency, check shards, cell egress, the new-account guard, the sign-in edge, queue depth, child forges; only the first six are settable by `key`); with `key` and `value` (`\"\"` restores the default), planned first (`dryRun` is true unless `false`); applying needs an admin-scope token",
  description:
    "The forge's capacity and guards, live. With `key` and `value` (\"\" restores default), plans.",
    "Forge capacity and guards, live. With `key` and `value` (\"\" restores default), plans.",
  inputSchema: {
    type: "object",
    properties: {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "claim_link",
  doc: "`{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's",
  description:
    "A new claim link for an unclaimed child forge, only with `reveal: true`; the old one stops.",
    "A new claim link for an unclaimed child forge, only with `reveal: true`; the old stops.",
  inputSchema: {
    type: "object",
    properties: {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "contribute",
  doc: "for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose",
  description:
    "For an arriving agent: what this forge is, its bottleneck, help-wanted issues, how to propose.",
    "For a new agent: what this forge is, its bottleneck, help-wanted issues, how to propose.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  run: (ctx) => good(welcome(ctx.app)),
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "family",
  doc: "the forge that sent this one and, for a site admin, those it sent, with state and version",
  description:
    "The forge that sent this one and, for a site admin, those it sent, with state and version.",
    "The forge that sent this one and, for a site admin, those it sent, with state, version.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  async run(ctx, user) {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "feed",
  doc: "`{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed`; `quietRuns` counts agent runs of the last 24 h that pushed, opened or said nothing, which the timeline leaves out",
  description:
    "Your ranked home timeline across visible apps; `cursor` pages; saved filter (`feed_chips`) applies.",
    "Your ranked home timeline; `cursor` pages; saved filter (`feed_chips`) applies.",
  inputSchema: {
    type: "object",
    properties: {
@@ -6,7 +6,7 @@
export const tool: Tool = {
  name: "feed_chips",
  doc: "`{ kind?, value?, hidden? }`: the feed chips you switched off, which `feed` and `asks` leave out; with `kind` (`kind` or `person`), `value` and `hidden` it switches one off or on",
  description:
    "Feed chips you switched off in `feed` and `asks`. With `kind`, `value` and `hidden`, sets one.",
    "Feed chips you switched off. With `kind`, `value` and `hidden`, sets one.",
  inputSchema: {
    type: "object",
    properties: {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "forge_proposals",
  doc: "`{ repo }`: what this forge proposed to its parent, newest first; `reachable` is false if the parent did not answer",
  description:
    "What this forge proposed to its parent, newest first; `reachable` false if it is silent.",
    "What this forge proposed to its parent; `reachable` false if it is silent.",
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG },
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "forges",
  doc: "an admin's list of the forges sent from here: name, address, whom for, apps, claimed or not, last activity",
  description:
    "The forges sent from here (admin): name, address, apps, claimed, spendTodayUsd, ceilingUsd.",
    "Forges sent from here (admin): name, address, apps, claimed, spendTodayUsd, ceilingUsd.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  async run(ctx, user) {
@@ -6,7 +6,7 @@
export const tool: Tool = {
  name: "hold",
  doc: "`{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false`",
  description:
    "Hold a pull (`why`) or release it (`release: true`): held, nothing reviews or lands it. Writers.",
    "Hold a pull (`why`) or release it (`release: true`); held, none reviews or lands it. Writers.",
  inputSchema: {
    type: "object",
    properties: {
@@ -79,6 +79,7 @@
export { tool as origin_apps } from "./origin_apps.ts";
export { tool as origins } from "./origins.ts";
export { tool as outsiders } from "./outsiders.ts";
export { tool as parent_unlink } from "./parent_unlink.ts";
export { tool as person } from "./person.ts";
export { tool as plan } from "./plan.ts";
export { tool as preview } from "./preview.ts";
export { tool as probe } from "./probe.ts";
@@ -8,7 +8,7 @@
export const tool: Tool = {
  name: "migrate",
  doc: "`{ url, name?, crew? }` brings a public repository in by URL (history only; nothing reaches back) and answers `{ job, state, url }`; `{ job }` alone reads that job. Same validation, scope (`rw`) and private-address refusal as `POST /api/v1/migrate`",
  description:
    "Bring a repository in by public `url` (`name`, `crew`), history and all. With `job`, its state.",
    "Bring a repo in by public `url` (`name`, `crew`), history and all. With `job`, its state.",
  inputSchema: {
    type: "object",
    properties: {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "milestones",
  doc: "`{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues)",
  description:
    "How far each thing asked for is. With `app`: top-level limbs, done/total, building, recent merges.",
    "How far each ask is. With `app`: top-level limbs, done/total, building, recent merges.",
  inputSchema: {
    type: "object",
    properties: {
@@ -7,7 +7,7 @@
export const tool: Tool = {
  name: "mint_invite",
  doc: "`{ days? }`: mint a single-use invite link that expires in `days` (1–30, default 7) and is shown once; a person admin's, with an admin token",
  description:
    "Mint a single-use invite link, shown once, expiring in `days` (1–30, default 7). Person admins.",
    "Mint a one-use invite link, shown once, expires in `days` (1–30, default 7). Person admins.",
  inputSchema: {
    type: "object",
    properties: {
@@ -6,7 +6,7 @@
import { good, bad, type Tool, mayBoards } from "../shared.ts";
export const tool: Tool = {
  name: "model_grant",
  description:
    "Give a person a capped monthly model grant (`usdPerMonth`, 0 takes it back). Person admins.",
    "Give a person a monthly model grant (`usdPerMonth`, 0 takes it back). Person admins.",
  inputSchema: {
    type: "object",
    properties: {
@@ -12,7 +12,7 @@
export const tool: Tool = {
  name: "new_app",
  doc: "`{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken)",
  description:
    "Make an app from a sentence: a repository, production, and with `description` a first issue.",
    "Make an app from a sentence: a repo, production, and with `description` a first issue.",
  inputSchema: {
    type: "object",
    properties: {
@@ -15,7 +15,7 @@
export const tool: Tool = {
  name: "now",
  doc: "what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`)",
  description:
    "What the crew is doing across your apps: who, on what, since when, cost; what awaits review.",
    "What the crew does across your apps: who, on what, since when, cost; what awaits review.",
  inputSchema: { type: "object", properties: {} },
  writes: false,
  run(ctx, user) {
@@ -7,7 +7,7 @@
export const tool: Tool = {
  name: "outsiders",
  doc: "`{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent",
  description:
    "Whether people who cannot write an app may direct its crew (off by default). No `on` reads it.",
    "Whether non-writers may direct an app's crew (off by default). No `on` reads it.",
  inputSchema: {
    type: "object",
    properties: {
@@ -0,0 +1,41 @@
import { pageLimit } from "../../../core/issues.ts";
import { listReposByOwner } from "../../../core/repos.ts";
import { getUserByName, hiddenFrom } from "../../../core/users.ts";
import { paged, publicProfile } from "../../respond.ts";
import { good, bad, type Tool } from "../shared.ts";
export const tool: Tool = {
  name: "person",
  doc: "`{ username, limit?, cursor? }`: a person's public profile and the repositories you may see, as `GET /api/v1/users/:username` and its `/repos`; a private one you cannot read is never listed",
  description: "A person's profile and repos you may see.",
  inputSchema: {
    type: "object",
    properties: {
      username: { type: "string" },
      limit: { type: "integer" },
      cursor: { type: "string" },
    },
    required: ["username"],
  },
  writes: false,
  run(ctx, user, args) {
    const { username, limit, cursor } = args;
    if (typeof username !== "string" || username === "" || username.length > 100)
      return bad("invalid", "`username` is 1 to 100 characters");
    if (limit !== undefined && (typeof limit !== "number" || !Number.isFinite(limit)))
      return bad("invalid", "`limit` is a number");
    if (cursor !== undefined && typeof cursor !== "string")
      return bad("invalid", "`cursor` is the one a previous answer gave");
    const person = getUserByName(ctx.app.db, username);
    if (!person || hiddenFrom(person, user)) return bad("not_found", "no such person");
    const size = pageLimit(limit as number | undefined);
    const items = listReposByOwner(ctx.app.db, person.username, user, {
      limit: size,
      ...(cursor ? { cursor } : {}),
    });
    return good({
      ...publicProfile(person),
      repos: paged(items, size, (r) => r.id),
    });
  },
};
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "proposal_tokens",
  doc: "`{ repo, verb, child?, origin?, childRepo?, id? }`: give a child forge a propose-only credential: `mint` one (`child`, `origin`), `list` them, or `revoke` one by `id`; writers only",
  description:
    "A child's propose-only credential: `mint` (`child`, `origin`), `list`, `revoke` (`id`). Writers.",
    "A child's propose-only token: `mint` (`child`, `origin`), `list`, `revoke` (`id`). Writers.",
  inputSchema: {
    type: "object",
    properties: {
@@ -13,7 +13,7 @@
export const tool: Tool = {
  name: "pull",
  doc: "`{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `next: { who, why }` (open only; who acts next: builder, reviewer, queue or person), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment",
  description:
      
        sentinelcrew
        18d ago
        outdated
      
      Low: this trim removes checkStale from the description, but the tool still returns it (line 50). An agent reading tools/list loses the one hint that the check may be against an old base. If the budget allows, trim elsewhere and keep the field name, for example "A pull: title, state, head, base; open: mergeable, conflicts, checkStale, check."
    
    "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `proposal`, `checkStale`, `check`.",
    "A pull: title, state, head, base; open: `mergeable`, `conflicts`, `checkStale`, `check`.",
  inputSchema: {
    type: "object",
    properties: {
@@ -3,9 +3,9 @@
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"
export const tool: Tool = {
  name: "repo_settings",
  doc: "`{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid`",
  doc: "`{ repo, description?, visibility? }` (admin): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid`",
  description:
    "Change a repository's description or visibility, as PATCH /api/v1/repos/:owner/:name (admin token).",
    "Change a repo's description or visibility: PATCH /api/v1/repos/:owner/:name (admin).",
  inputSchema: {
    type: "object",
    properties: {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "returns",
  doc: "`{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours",
  description:
    "What crew tokens bought over `days` (1–90, default 7): dollars, runs, landed, cost/change.",
    "What crew tokens bought in `days` (1–90, default 7): dollars, runs, landed, cost/change.",
  inputSchema: {
    type: "object",
    properties: {
@@ -7,7 +7,7 @@
export const tool: Tool = {
  name: "say",
  doc: "speak on an issue or a pull; a working builder hears it as its next step",
  description:
    "Say something on an issue or pull. A working builder hears it next; otherwise the next run does.",
    "Say something on an issue or pull. A working builder hears it next, else the next run.",
  inputSchema: {
    type: "object",
    properties: {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "seal",
  doc: "`{ repo, number, sealed }`: seal a security report (and the pull that fixes it) so only writers and the crew see it, or unseal it for every reader; a writer's, recorded",
  description:
    "Seal or unseal an issue or pull: a sealed one is seen only by the app's writers and crew.",
    "Seal or unseal an issue or pull: a sealed one is seen only by writers and crew.",
  inputSchema: {
    type: "object",
    properties: {
@@ -6,7 +6,7 @@
export const tool: Tool = {
  name: "sever",
  doc: "`{ repo }`: cut a spawned forge's link to the forge its code came from; its `forge` repository's owner only; deletes nothing",
  description:
    "Cut a spawned forge's link to its parent (its `forge` repository's owner only). Deletes nothing.",
    "Unlink a spawned forge from its parent (owner of its `forge` repo only). Deletes nothing.",
      
        sentinelcrew
        18d ago
        outdated
      
      Low: the trim dropped "Deletes nothing.", and that is the line an agent needs before calling an irreversible-sounding tool. doc still says it, but tools/list no longer does. If bytes free up later, put it back before trimming any other description.
    
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG },
@@ -7,7 +7,7 @@
export const tool: Tool = {
  name: "share",
  doc: "`{ item, to? }`: share a feed item (`item` is its id); with no `to` it goes to the app's crew and owners, else to up to 10 named usernames' followers; a daily budget each; answers `{ sent }`",
  description:
    "Share a feed item: no `to` tells the app's crew and owners, else followers; daily budget.",
    "Share a feed item: no `to` tells the app's crew and owners, else followers; budgeted.",
  inputSchema: {
    type: "object",
    properties: {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "spawn",
  doc: "`{ name, apps?, crew?, dryRun? }`: a child forge, planned first (`dryRun` is true unless `false`); an admin's, and an `ro` token may plan but not make",
  description:
    "Spawn a child forge with the named apps and the crew's briefs. Plans first.",
    "Spawn a child forge with named apps and the crew's briefs. Plans first.",
  inputSchema: {
    type: "object",
    properties: {
@@ -4,7 +4,7 @@
import { good, bad, type Tool, REPO_ARG, repoArg, isAnswer } from "../shared.ts"
export const tool: Tool = {
  name: "spend",
  description:
    "Report what your session spent outside the forge's runs: who, model, tokens or dollars, issue.",
    "Report what your session spent outside forge runs: who, model, tokens or dollars, issue.",
  inputSchema: {
    type: "object",
    properties: {
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "stop",
  doc: "stop one run by its id from `now`",
  description:
    "Stop one of the crew's runs, by its id from `now`. Its pushes stay; nothing is re-queued.",
    "Stop a crew run by its id from `now`. Its pushes stay; nothing is re-queued.",
  inputSchema: {
    type: "object",
    properties: { repo: REPO_ARG, run: { type: "string" } },
@@ -5,7 +5,7 @@
export const tool: Tool = {
  name: "usage",
  doc: "`{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's",
  description:
    "What the crew's runs on an app spent over `days` (1–90, default 7), by agent and issue. Writers.",
    "What crew runs on an app spent in `days` (1–90, default 7), by agent, issue. Writers.",
  inputSchema: {
    type: "object",
    properties: {
@@ -8,7 +8,7 @@
export const tool: Tool = {
  name: "variant",
  doc: "`{ repo, number, answer, reason? }`: like or dislike one pull among its variants (`answer` like or dislike); a later vote replaces the earlier; a dislike closes the pull with `reason`",
  description:
    "Like or dislike a pull among its variants; a later vote replaces it; dislike closes it (`reason`).",
    "Like or dislike a pull among its variants; a later vote replaces; dislike closes it.",
  inputSchema: {
    type: "object",
    properties: {
@@ -0,0 +1,116 @@
/**
 * The `person` tool answers what /api/v1/users/:username and its /repos answer
 * the same caller: a stranger sees public repositories only, a team member the
 * private one they were given, and an unknown name is not found.
 */
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createApp, type App } from "../src/app.ts";
import { createRepo } from "../src/actions/repos.ts";
import { addTeamMember, createOrg, createTeam } from "../src/core/orgs.ts";
import { createToken } from "../src/core/tokens.ts";
import { createUser } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
describe("MCP person", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let aliceRo: string;
  let bobRo: string;
  let carolRo: string;
  let id = 1;
  const tool = async (token: string, args: unknown) => {
    const res = await fetch(`${servers.url}/mcp`, {
      method: "POST",
      headers: {
        "content-type": "application/json",
        accept: "application/json, text/event-stream",
        authorization: `Bearer ${token}`,
      },
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: id++,
        method: "tools/call",
        params: { name: "person", arguments: args },
      }),
    });
    const body: any = await res.json();
    const text: string = body.result.content[0].text;
    return body.result.isError === true ? { error: text } : { value: JSON.parse(text) };
  };
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-person-"));
    app = createApp({ dataDir, port: 0 });
    servers = await serve(app);
    const mk = async (username: string, first = false) => {
      const u = await createUser(app.db, {
        origin: "seed",
        trusted: true,
        username,
        email: `${username}@forge.local`,
        password: "a-good-passphrase",
        adminIfFirst: first,
      });
      if (!u.ok) throw new Error(u.error);
      return u.value;
    };
    const alice = await mk("alice", true);
    const bob = await mk("bob");
    const carol = await mk("carol");
    aliceRo = createToken(app.db, alice.id, "ro", "ro").token;
    bobRo = createToken(app.db, bob.id, "ro", "ro").token;
    carolRo = createToken(app.db, carol.id, "ro", "ro").token;
    const dave = await mk("dave");
    app.db.query("UPDATE user SET suspended_at = ? WHERE id = ?").run(new Date().toISOString(), dave.id);
    const org = createOrg(app.db, "guild", alice.id);
    if (!org.ok) throw new Error(org.error);
    const team = createTeam(app.db, org.value.id, "makers", "read");
    if (!team.ok) throw new Error(team.error);
    addTeamMember(app.db, team.value, bob.id);
    for (const [name, visibility] of [["open", "public"], ["hidden", "private"]] as const) {
      const made = await createRepo(app, alice, { name, visibility, owner: "guild" });
      if (!made.ok) throw new Error(String(made.error));
    }
  }, 30_000);
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("a stranger sees the profile and only public repositories", async () => {
    const r = await tool(carolRo, { username: "guild" });
    expect(r.value.username).toBe("guild");
    expect(r.value.repos.items.map((x: any) => x.name)).toEqual(["open"]);
  });
  test("a member also sees the private repository they were given", async () => {
    const r = await tool(bobRo, { username: "guild" });
    expect(r.value.repos.items.map((x: any) => x.name).sort()).toEqual(["hidden", "open"]);
  });
  test("limit pages with a cursor", async () => {
    const first = await tool(bobRo, { username: "guild", limit: 1 });
    expect(first.value.repos.items.length).toBe(1);
    const next = await tool(bobRo, { username: "guild", limit: 1, cursor: first.value.repos.next_cursor });
    expect(next.value.repos.items.length).toBe(1);
      
        sentinelcrew
        23d ago
        outdated
      
      Add the hidden-account case beside this test (suspend a user, then check the call as a non-admin and as alice the admin), so the hiddenFrom check at mcp.ts:2374 is covered.
    
    expect(next.value.repos.items[0].name).not.toBe(first.value.repos.items[0].name);
  });
  test("a suspended person is not found to a non-admin, and still found by an admin", async () => {
    expect((await tool(carolRo, { username: "dave" })).error).toContain("no such person");
    expect((await tool(aliceRo, { username: "dave" })).value.username).toBe("dave");
  });
  test("an unknown name is not found, and bad arguments are refused", async () => {
    expect((await tool(carolRo, { username: "nobody" })).error).toContain("no such person");
    expect((await tool(carolRo, {})).error).toBeDefined();
    expect((await tool(carolRo, { username: 5 })).error).toBeDefined();
  });
});
@@ -251,6 +251,7 @@
describe("the forge over MCP", () => {
      "app_members",
      "egress_grants",
      "explore",
      "person",
      "search",
      "feed",
      "feed_chips",
		@@ -99,6 +99,7 @@ for a tunnel and a forge that sleeps.
99	99	\| `origins` \| `{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer \| yes \|
100	100	\| `outsiders` \| `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent \| yes \|
101	101	\| `parent_unlink` \| no input: stop signing in through the parent forge, as Settings does; refused when it is the account's last way in, and "Nothing to unlink." when nothing is linked; an admin token \| yes \|
	102	\| `person` \| `{ username, limit?, cursor? }`: a person's public profile and the repositories you may see, as `GET /api/v1/users/:username` and its `/repos`; a private one you cannot read is never listed \| \|
102	103	\| `plan` \| `{ app, issues }`: open up to 12 linked issues, all or none (see below) \| yes \|
103	104	\| `preview` \| `{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \\| null, check: "green" \\| "red" \\| "running" \\| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say \| \|
104	105	\| `probe` \| knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract \| \|
		@@ -111,7 +112,7 @@ for a tunnel and a forge that sleeps.
111	112	\| `read_file` \| a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents \| \|
112	113	\| `repo` \| `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` \| \|
113	114	\| `repo_labels` \| `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin \| yes \|
114		\| `repo_settings` \| `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` \| yes \|
	115	\| `repo_settings` \| `{ repo, description?, visibility? }` (admin): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` \| yes \|
115	116	\| `reports` \| `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token \| yes \|
116	117	\| `restore_drill` \| no input: restore the newest snapshot as a drill and answer `{ verdict, failedStep?, says }`, worded as the Backups page's button; no store, a failure or a red drill is an answer, not an error; a forge admin's, with an admin token \| yes \|
117	118	\| `returns` \| `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours \| \|
		@@ -7,7 +7,7 @@ export const tool: Tool = {
7	7	name: "app_members",
8	8	doc: "`{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token",
9	9	description:
10		"The people a private app names, who may enter it and its previews. With `members`, plans.",
	10	"People a private app names, who may enter it and its previews. With `members`, plans.",
11	11	inputSchema: {
12	12	type: "object",
13	13	properties: {
		@@ -4,7 +4,7 @@ import { good, bad, type Tool } from "../shared.ts";
4	4	export const tool: Tool = {
5	5	name: "asks_decide",
6	6	description:
7		"Let the decider answer a hand-over (`item`: `parked:<id>`); only a sure set_aside clears it.",
	7	"Let the decider answer a hand-over (`item`: `parked:<id>`); only a sure set_aside clears.",
8	8	inputSchema: {
9	9	type: "object",
10	10	properties: { item: { type: "string", maxLength: 80 } },
		@@ -4,7 +4,7 @@ import { good, bad, type Tool } from "../shared.ts";
4	4	export const tool: Tool = {
5	5	name: "asks_proposal",
6	6	description:
7		"Act on a wave proposal (`asks` row): `approve`, `redirect` (`words`), `later` (`again`). Owner.",
	7	"Act on a wave proposal: `approve`, `redirect` (`words`), `later` (`again`). Owner.",
8	8	inputSchema: {
9	9	type: "object",
10	10	properties: {
		@@ -7,7 +7,7 @@ export const tool: Tool = {
7	7	name: "attach_look",
8	8	doc: "`{ app, pull, width, says, image, dryRun? }`: attach a look to an open pull: a PNG or JPEG (at most 5 MB, base64 in `image`), `width` phone or desktop, one line in `says`; planned first (`dryRun` is true unless `false`)",
9	9	description:
10		"Attach a PNG or JPEG (base64 `image`, max 5 MB) to an open pull: `phone`/`desktop`, `says`.",
	10	"Attach a PNG/JPEG (base64 `image`, max 5 MB) to an open pull: `phone`/`desktop`, `says`.",
11	11	inputSchema: {
12	12	type: "object",
13	13	properties: {
		@@ -11,7 +11,7 @@ export const tool: Tool = {
11	11	name: "branches",
12	12	doc: "`{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: \"tags\"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act",
13	13	description:
14		"A repository's branches; `name`, `action` create (from `from`) or delete one, not the default.",
	14	"A repo's branches; `name`, `action` create (from `from`) or delete one, not the default.",
15	15	inputSchema: {
16	16	type: "object",
17	17	properties: {
		@@ -7,7 +7,7 @@ export const tool: Tool = {
7	7	name: "capacity",
8	8	doc: "`{ key?, value?, dryRun? }` (forge admin): the forge's capacity and guards, live (crew and checks concurrency, check shards, cell egress, the new-account guard, the sign-in edge, queue depth, child forges; only the first six are settable by `key`); with `key` and `value` (`\"\"` restores the default), planned first (`dryRun` is true unless `false`); applying needs an admin-scope token",
9	9	description:
10		"The forge's capacity and guards, live. With `key` and `value` (\"\" restores default), plans.",
	10	"Forge capacity and guards, live. With `key` and `value` (\"\" restores default), plans.",
11	11	inputSchema: {
12	12	type: "object",
13	13	properties: {
		@@ -5,7 +5,7 @@ export const tool: Tool = {
5	5	name: "claim_link",
6	6	doc: "`{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's",
7	7	description:
8		"A new claim link for an unclaimed child forge, only with `reveal: true`; the old one stops.",
	8	"A new claim link for an unclaimed child forge, only with `reveal: true`; the old stops.",
9	9	inputSchema: {
10	10	type: "object",
11	11	properties: {
		@@ -5,7 +5,7 @@ export const tool: Tool = {
5	5	name: "contribute",
6	6	doc: "for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose",
7	7	description:
8		"For an arriving agent: what this forge is, its bottleneck, help-wanted issues, how to propose.",
	8	"For a new agent: what this forge is, its bottleneck, help-wanted issues, how to propose.",
9	9	inputSchema: { type: "object", properties: {} },
10	10	writes: false,
11	11	run: (ctx) => good(welcome(ctx.app)),
		@@ -5,7 +5,7 @@ export const tool: Tool = {
5	5	name: "family",
6	6	doc: "the forge that sent this one and, for a site admin, those it sent, with state and version",
7	7	description:
8		"The forge that sent this one and, for a site admin, those it sent, with state and version.",
	8	"The forge that sent this one and, for a site admin, those it sent, with state, version.",
9	9	inputSchema: { type: "object", properties: {} },
10	10	writes: false,
11	11	async run(ctx, user) {