agentbox-app 0.1.13 → 0.1.16

package/mcp/core/teammates.mjs

@@ -0,0 +1,222 @@
+// The store tools a teammate uses on its runs: talk in the team chat, pass work
+// to a teammate, keep what it learns about the person, and set itself up.
+//
+// Which teammate the session is comes from the app, not the model: the run it
+// was started for (`ZERO_ITEM`) carries `teammate:<id>`, so no argument names
+// who is speaking and no session can speak as another teammate.
+import { readWorkItem } from '../../main/store/work-items.mjs';
+import { listProjects, legacyRoot } from '../../main/store/project.mjs';
+import {
+  teamDir, readTeammates, readChat, writeTeammate, writeChat, newMemoryId,
+  readPlaybooks, writePlaybook, newPlaybookId, newLessonId, newDutyId,
+} from '../../main/store/teammates-files.mjs';
+import { teammateIdOf, hopOf, mentionsIn, isWorks, letterFor, cleanDuty, dutyStart, YOU } from '../../shared/teammates.mjs';
+import { periodKey } from '../../shared/repeats.mjs';
+import { resolveProduct, resolveAccount } from './account.mjs';
+
+// A title or a choice is drawn as plain words, so markdown in one shows as stars.
+const plain = (s) => String(s ?? '').replace(/\*\*|__|`/g, '').replace(/\s+/g, ' ').trim();
+
+const NOT_A_TEAMMATE = 'this session is not a teammate\'s run, so it has no team chat to write to';
+
+function projectOf(itemId, product) {
+  if (product) return resolveProduct(product);
+  for (const p of listProjects()) {
+    try { if (readWorkItem(p.dir, itemId)) return p; } catch { /* a product with no ledger */ }
+  }
+  throw new Error(`no thread ${itemId} in any product`);
+}
+
+// `outsider` lets a thread that is no teammate's run in: it speaks for the
+// person (`me` is null), which is what they asked it to do.
+export function teammateContext({ env = process.env, now = Date.now(), outsider = false } = {}) {
+  const itemId = String(env.ZERO_ITEM ?? '').trim();
+  if (!itemId) throw new Error(NOT_A_TEAMMATE);
+  const project = projectOf(itemId, String(env.ZERO_PRODUCT ?? '').trim() || null);
+  const item = readWorkItem(project.dir, itemId, now);
+  if (!item) throw new Error(`no thread ${itemId} in ${project.name}`);
+  const tid = teammateIdOf(item);
+  if (!tid && !outsider) throw new Error(NOT_A_TEAMMATE);
+  const accountId = String(env.STORE_ACCOUNT_ID ?? '').trim() || resolveAccount().accountId;
+  const dir = teamDir(legacyRoot(), accountId);
+  const team = readTeammates(dir, now);
+  if (!tid) return { dir, me: null, team, item, project, hop: 0, via: { via: item.id, viaProduct: project.id } };
+  const me = team.find((t) => t.id === tid);
+  if (!me) throw new Error(`the teammate behind ${itemId} is no longer on the team`);
+  return { dir, me, team, item, project, hop: hopOf(item), via: {} };
+}
+
+function idsFor(names, team, me) {
+  const list = (Array.isArray(names) ? names : [names]).map((n) => String(n ?? '').trim().replace(/^@/, '')).filter(Boolean);
+  const out = [];
+  for (const n of list) {
+    const lower = n.toLowerCase();
+    const t = team.find((x) => x.id === n || x.name.toLowerCase() === lower);
+    if (!t) throw new Error(`no teammate called ${n}. The team: ${team.map((x) => x.name).join(', ')}`);
+    if (t.id !== me?.id) out.push(t.id);
+  }
+  return out;
+}
+
+export function teamPost({ text, to = [], options } = {}, ctx = {}) {
+  const { dir, me, team, hop, via } = teammateContext({ ...ctx, outsider: true });
+  const words = String(text ?? '').trim();
+  if (!words) throw new Error('nothing to post');
+  const ids = new Set([...idsFor(to, team, me), ...mentionsIn(words, team).filter((x) => x !== me?.id)]);
+  const opts = me && Array.isArray(options) ? options.map(plain).filter(Boolean).slice(0, 4) : null;
+  const m = writeChat(dir, { kind: 'msg', from: me?.id ?? YOU, to: [...ids], text: words.slice(0, 4000), hop, ...via, ...(opts?.length ? { options: opts } : {}) }, ctx.now);
+  return { posted: m.id, to: [...ids].map((x) => team.find((t) => t.id === x)?.name), note: ids.size ? 'The teammates named will wake to read it.' : 'Posted. Nobody was named, so nobody is woken by it.' };
+}
+
+export function teamPass({ to, title, details, project: named } = {}, ctx = {}) {
+  const { dir, me, team, hop, via, project } = teammateContext({ ...ctx, outsider: true });
+  // The work is done where it is named, or for a thread handing it on, in that
+  // thread's project; otherwise in the receiver's own.
+  const where = named ? resolveProduct(named).id : me ? null : project.id;
+  const [target] = idsFor(to, team, me);
+  if (!target) throw new Error('pass work to another teammate, not to yourself');
+  const what = plain(title);
+  if (!what) throw new Error('give the work a short title');
+  const m = writeChat(dir, { kind: 'pass', from: me?.id ?? YOU, to: target, title: what.slice(0, 200), details: String(details ?? '').slice(0, 6000), hop, ...via, ...(where ? { product: where } : {}) }, ctx.now);
+  return { passed: m.id, to: team.find((t) => t.id === target)?.name };
+}
+
+export function teamRemember({ text } = {}, ctx = {}) {
+  const { dir, me, item } = teammateContext(ctx);
+  const words = String(text ?? '').trim();
+  if (!words) throw new Error('nothing to remember');
+  if (me.memory.some((m) => m.text.toLowerCase() === words.toLowerCase())) return { remembered: false, note: 'already kept' };
+  const now = ctx.now ?? Date.now();
+  const mem = { id: newMemoryId(), text: words.slice(0, 300), from: `run ${item.id}`, at: now };
+  writeTeammate(dir, me.id, { remember: mem }, now);
+  writeChat(dir, { kind: 'act', from: me.id, verb: 'learned', text: mem.text, ref: mem.id }, now);
+  return { remembered: true, id: mem.id };
+}
+
+const EVERY = ['day', 'weekday', 'week', 'never'];
+
+// Or answered in the setup thread itself, which reaches the run as its answer.
+function answeredInThread(item) {
+  const said = typeof item?.answer === 'string' ? item.answer.trim() : '';
+  return !!said && said !== '(withdrawn)' && item.wrote?.answer?.source === 'founder';
+}
+
+function answeredSince(dir, id) {
+  const { messages } = readChat(dir);
+  const asked = messages.filter((m) => m.kind === 'msg' && m.from === YOU && m.setup && (m.to ?? []).includes(id)).at(-1);
+  return messages.some((m) => m.kind === 'msg' && m.from === YOU && !m.setup && (m.to ?? []).includes(id) && m.ts > (asked?.ts ?? 0));
+}
+
+// What a change to these says in the chat, so you can see it saved.
+const SAID = {
+  name: 'its name', role: 'its role', job: 'its job', goal: 'its goal', counted: 'how it counts its goal',
+  asksFirst: 'what needs your yes first', works: 'when it works', duties: 'what it does on its own',
+};
+
+// Duties keep their id, and what they have served, when one with the same
+// words is set again.
+function dutiesFrom(list, me, now) {
+  if (!Array.isArray(list)) throw new Error('duties is a list of { what, every, at, on } or { what, after: "ship", most }');
+  const out = [];
+  const served = {};
+  for (const raw of list) {
+    const what = String(raw?.what ?? '').trim();
+    if (!what) throw new Error('each duty needs what it does');
+    const had = (me.duties ?? []).find((d) => d.what.toLowerCase() === what.toLowerCase());
+    const d = cleanDuty({ ...raw, what, id: had?.id ?? newDutyId(), at: raw?.after === 'ship' ? undefined : (Array.isArray(raw?.at) ? raw.at : raw?.at ? [raw.at] : []) });
+    if (!d) throw new Error(`"${what}" cannot run as written: every is day, weekday or week, at is a list of HH:MM times in 24 hours, on is 0 (Sunday) to 6 for weekly, or after is "ship" with most runs a week`);
+    out.push(d);
+    if (!had) served[d.id] = dutyStart(d, now);
+  }
+  return { duties: out, served };
+}
+
+export function teamSetup({ name, role, job, goal, counted, asksFirst, every, at, on, duties, runsOn, ready } = {}, ctx = {}) {
+  const { dir, me, team, item } = teammateContext(ctx);
+  const now = ctx.now ?? Date.now();
+  if (typeof asksFirst === 'string' && /\?\s*$/.test(asksFirst)) {
+    throw new Error('asksFirst is what needs the person\'s yes before you do it, said as a statement ("Anything that goes out in public"). Ask a question with team_post instead.');
+  }
+  const patch = {};
+  if (typeof name === 'string' && name.trim()) {
+    const clean = name.trim().replace(/\s+/g, ' ').slice(0, 40);
+    if (team.some((t) => t.id !== me.id && t.name.toLowerCase() === clean.toLowerCase())) throw new Error(`${clean} is taken; pick another name`);
+    patch.name = clean;
+    patch.letter = letterFor(clean, team.filter((t) => t.id !== me.id));
+  }
+  for (const [k, v] of Object.entries({ role, job, goal, counted, asksFirst })) if (typeof v === 'string' && v.trim()) patch[k] = v.trim();
+  if (every !== undefined) {
+    if (!EVERY.includes(every)) throw new Error(`every is one of ${EVERY.join(', ')}`);
+    if (every === 'never') patch.works = null;
+    else {
+      const works = { every, at: at ?? '09:00', ...(every === 'week' ? { on: Number.isInteger(on) ? on : 1 } : {}) };
+      if (!isWorks(works)) throw new Error('at is HH:MM in 24 hours, and on is 0 (Sunday) to 6 for a weekly round');
+      patch.works = works;
+      patch.served = periodKey(works, now) ?? '';
+    }
+  }
+  if (duties !== undefined) {
+    const made = dutiesFrom(duties, me, now);
+    patch.duties = made.duties;
+    patch.works = null;
+    if (Object.keys(made.served).length) patch.dutyServed = made.served;
+  }
+  if (runsOn !== undefined) {
+    if (runsOn !== 'claude' && runsOn !== 'codex') throw new Error('runsOn is claude or codex');
+    patch.engine = runsOn;
+  }
+  // A new teammate asks before it starts, so ready waits for the person's
+  // own words to it after the ask that made it.
+  if (ready === true && me.status === 'draft' && !answeredSince(dir, me.id) && !answeredInThread(item)) {
+    throw new Error('ask you first: post your questions with team_post, each with options, and finish; you can go ready once the person has answered');
+  }
+  if (ready === true) patch.status = 'active';
+  writeTeammate(dir, me.id, patch, now);
+  if (ready === true && me.status === 'draft') writeChat(dir, { kind: 'act', from: me.id, verb: 'started' }, now);
+  const changed = Object.keys(SAID).filter((k) => k in patch && JSON.stringify(patch[k]) !== JSON.stringify(me[k] ?? null));
+  if (me.status === 'active' && changed.length) {
+    const parts = changed.map((k) => SAID[k]);
+    writeChat(dir, { kind: 'act', from: me.id, verb: 'updated', text: `Updated ${parts.length > 1 ? `${parts.slice(0, -1).join(', ')} and ${parts.at(-1)}` : parts[0]}` }, now);
+  }
+  const after = readTeammates(dir, now).find((t) => t.id === me.id);
+  return { teammate: { name: after.name, role: after.role, job: after.job, goal: after.goal, counted: after.counted, asksFirst: after.asksFirst, works: after.works, duties: after.duties, runsOn: after.engine ?? 'your default', status: after.status } };
+}
+
+// A lesson about how the person likes a kind of work done, kept in the
+// playbook of that title so every teammate doing that work reads it. With no
+// lesson it starts reading a playbook another teammate wrote.
+export function teamPlaybook({ playbook, lesson } = {}, ctx = {}) {
+  const { dir, me, item, project } = teammateContext(ctx);
+  const now = ctx.now ?? Date.now();
+  const title = plain(playbook).slice(0, 120);
+  if (!title) throw new Error('name the playbook, like "How you write posts"');
+  const books = readPlaybooks(dir);
+  let book = books.find((b) => b.title.toLowerCase() === title.toLowerCase());
+  if (lesson === undefined) {
+    if (!book) throw new Error(`no playbook called ${title}. The team has: ${books.map((b) => b.title).join(', ') || 'none yet'}. Add a lesson to start one.`);
+    if (!book.readers.includes(me.id)) writePlaybook(dir, { kind: 'reader', book: book.id, teammate: me.id }, now);
+    return { playbook: book.id, reading: true, lessons: book.lessons.map((l) => l.text) };
+  }
+  const text = String(lesson ?? '').trim().slice(0, 400);
+  if (!text) throw new Error('the lesson is empty');
+  if (!book) {
+    book = { id: newPlaybookId(), title, lessons: [], readers: [] };
+    writePlaybook(dir, { kind: 'book', id: book.id, title }, now);
+  }
+  if (book.lessons.some((l) => l.text.toLowerCase() === text.toLowerCase())) return { playbook: book.id, kept: false, note: 'already in it' };
+  const id = newLessonId();
+  writePlaybook(dir, { kind: 'lesson', id, book: book.id, text, by: me.id, from: { product: project.id, id: item.id, title: plain(item.label || item.title) } }, now);
+  writeChat(dir, { kind: 'act', from: me.id, verb: 'lesson', ref: book.id, text }, now);
+  return { playbook: book.id, kept: true, id };
+}
+
+export function teamRoster(ctx = {}) {
+  const { dir, me, team } = teammateContext({ ...ctx, outsider: true });
+  const { messages } = readChat(dir);
+  const nameOf = (id) => (id === YOU ? 'the person' : team.find((t) => t.id === id)?.name ?? 'a teammate');
+  return {
+    you: me?.name ?? null,
+    team: team.map((t) => ({ name: t.name, role: t.role, job: t.job, paused: t.paused, status: t.status })),
+    recent: messages.filter((m) => m.kind === 'msg' || m.kind === 'pass').slice(-20).map((m) => ({ from: nameOf(m.from), to: m.kind === 'pass' ? [nameOf(m.to)] : (m.to ?? []).map(nameOf), text: m.kind === 'pass' ? `passed: ${m.title}` : m.text, at: new Date(m.ts).toISOString() })),
+  };
+}

package/mcp/core/work.mjs

@@ -96,10 +96,63 @@ export function createItem(product, fields = {}, { source = 'agent', from = [] }
   const p = resolveProduct(product);
   const sources = [...from, fields.parent].filter(Boolean).map((id) => { try { return locate(id).item; } catch { return null; } });
   const kept = fields.visibility ? {} : privacyFrom(sources);
+  // A row filed under a thread runs as that thread does, or it falls to the default engine.
+  const parent = fields.parent ? sources.at(-1) : null;
+  for (const f of ['engine', 'model', 'effort']) if (fields[f] == null && parent?.[f]) kept[f] = parent[f];
   const item = createWorkItem(p.dir, saidPlainly({ ...fields, ...kept }, source), { source });
   return { ...item, product: p.id, productName: p.name };
 }
 
+/*
+ * ONE JOB IS ONE THREAD, AND A RUN THAT FILES A SECOND ONE IS TOLD SO
+ * (w-31b2eb82ba).
+ *
+ * "I want you to fix all of those in one thread, feels unecessary to create
+ * multiple threads and a bit confusing. I feel like my inbox has been getting
+ * super cluttered with agents separating into multiple threads when I don't
+ * want them to."
+ *
+ * A QA campaign had found four things and had ONE question in it — do you want
+ * these fixed — and filed four threads, which is four things to read, rank and
+ * either start or close that did not exist until it filed them. The brief is
+ * rewritten (briefs/worker.md, "One job is one thread") and the brief alone is
+ * not enough: all four went in from one session in 53 seconds at the end of a
+ * long run, and nothing anywhere counted them or pushed back.
+ *
+ * So the filing tool answers with the count. It does NOT refuse, because a
+ * refusal at this moment loses a finding an agent has already measured, and
+ * the judgement it is asking for is one only the agent can make. It is said
+ * where the session reads it while it can still fold the thread back.
+ *
+ * The group is the parent, because that is the question being asked: how many
+ * live threads now hang off the one conversation. A finished sibling is not
+ * counted; nobody is waiting on it. A thread filed under NOTHING is grouped by
+ * the run instead and says so in harder words, because a thread with no parent
+ * is not a proposal waiting in Later: it is a row in their inbox
+ * (`isProposal`, renderer/src/list-rules.ts).
+ */
+function alsoOnThisThread(beside, parent) {
+  const n = beside.length + 1;
+  const where = parent ? `under ${parent}` : 'under no thread at all';
+  const fold = parent
+    ? `fold it into ${parent}`
+    : 'put it in the thread you are already on, under what is left to do';
+  return `${n} live threads are now filed ${where}, counting this one (${beside.join(', ')}). `
+    + 'ONE JOB IS ONE THREAD: if they would answer all of these in one breath, they are one thread, so '
+    + `${fold} and close this one with a note saying where the work went. Keep it separate only if two `
+    + 'agents could genuinely run these at the same time, and then say in your answer why there is more '
+    + 'than one.';
+}
+
+/** The live threads already filed under the same parent, this one aside. */
+function besideIt(product, item) {
+  let items = [];
+  try { items = readWorkItems(resolveProduct(product).dir, Date.now()); } catch { return []; }
+  return items
+    .filter((i) => i.id !== item.id && i.parent === item.parent && i.status !== 'done')
+    .map((i) => i.id);
+}
+
 /*
  * A TASK AN AGENT FILES IS SEEN BY NO MORE PEOPLE THAN THE TASKS IT CAME FROM
  * (w-e053ed3581). The agent asked into a private chat holds a task seen only
@@ -121,9 +174,21 @@ export function privacyFrom(items) {
   return people.length ? { visibility: 'people', visibleTo: people } : { visibility: 'private' };
 }
 
+// A teammate's run is known by these labels, and labels are written whole, so
+// a run that closes with ["clean"] would stop being its teammate's run.
+const RUN_LABELS = ['teammate:', 'hop:', 'from:'];
+function keepRunLabels(had, patch) {
+  if (!Array.isArray(patch.labels)) return patch;
+  const before = had?.labels ?? [];
+  if (!before.some((l) => String(l).startsWith('teammate:'))) return patch;
+  const kept = before.filter((l) => l === 'founder' || RUN_LABELS.some((p) => String(l).startsWith(p)));
+  const missing = kept.filter((l) => !patch.labels.includes(l));
+  return missing.length ? { ...patch, labels: [...patch.labels, ...missing] } : patch;
+}
+
 export function updateItem(id, patch, { product = null, epoch = null, source = 'agent' } = {}) {
-  const { project } = locate(id, { product });
-  const item = updateWorkItem(project.dir, id, saidPlainly(patch, source), { epoch, source });
+  const { project, item: had } = locate(id, { product });
+  const item = updateWorkItem(project.dir, id, saidPlainly(keepRunLabels(had, patch), source), { epoch, source });
   return { ...item, product: project.id, productName: project.name };
 }
 
@@ -158,7 +223,7 @@ const plainly = (s) => String(s ?? '')
 
 export function herRow(item) {
   const labels = item?.labels ?? [];
-  return labels.includes('founder') && !labels.some((l) => String(l).startsWith('repeat:'));
+  return labels.includes('founder') && !labels.some((l) => String(l).startsWith('repeat:') || String(l).startsWith('teammate:'));
 }
 
 export function saidToClose(item, words) {
@@ -244,6 +309,9 @@ export function createClaimRegistry({ heartbeatMs = HEARTBEAT_MS, holder } = {})
   // epoch: the founder replies to finished rows constantly, and the session she
   // is replying to has to be able to answer her.
   const held = new Map(); // workItemId -> { dir, epoch, pending, live }
+  // The threads this run has filed under no parent at all, so that the second
+  // loose one is counted even though the store cannot group them.
+  const loose = [];
   let timer = null;
   const liveCount = () => [...held.values()].filter((h) => h.live).length;
 
@@ -458,8 +526,12 @@ export function createClaimRegistry({ heartbeatMs = HEARTBEAT_MS, holder } = {})
 
     // Filing from this session: what it files is kept as private as every row
     // it has held, finished ones too, since it may still be answering on them.
+    // And it is counted: `alsoOnThisThread` above says why.
     file(product, fields) {
-      return createItem(product, fields, { from: [...held.keys()] });
+      const item = createItem(product, fields, { from: [...held.keys()] });
+      const beside = item.parent ? besideIt(product, item) : [...loose];
+      if (!item.parent) loose.push(item.id);
+      return beside.length ? { ...item, alsoFiled: alsoOnThisThread(beside, item.parent) } : item;
     },
 
     holding: () => [...held.entries()].filter(([, h]) => h.live).map(([id]) => id),

package/mcp/stdio.mjs

@@ -20,6 +20,7 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import path from 'node:path';
 import { buildTools } from './tools.mjs';
 import { NAME, Name, nameSlug } from '../shared/product-name.mjs';
 
@@ -27,8 +28,13 @@ const LOG = `[${nameSlug}-store]`;
 
 console.log = (...args) => console.error(LOG, ...args);
 
-async function main() {
-  const { account, tools, claims } = buildTools();
+/**
+ * One store server over `input` and `output`: this process's own stdio, or one
+ * cloud run's connection when many share a process (main/cloud/run.mjs), each
+ * holding its own claims (`holder`). Returns a close that gives them back.
+ */
+export async function serveStore({ input = process.stdin, output = process.stdout, holder, ownItem } = {}) {
+  const { account, tools, claims } = buildTools({ holder, ...(ownItem !== undefined ? { ownItem } : {}) });
 
   const server = new McpServer(
     { name: nameSlug, version: '1.0.0' },
@@ -45,23 +51,30 @@ async function main() {
     server.registerTool(tool.name, { description: tool.description, inputSchema: tool.schema }, tool.run);
   }
 
-  // Give held work items back promptly on a clean exit instead of making the
-  // next worker wait out a full lease. Best effort by design: the lease is the
-  // guarantee, and this is only the courtesy that makes the common case fast.
-  const goodbye = () => {
+  // Give held work items back promptly when the session ends instead of making
+  // the next worker wait out a full lease. Best effort by design: the lease is
+  // the guarantee, and this is only the courtesy that makes the common case fast.
+  const giveBack = () => {
     for (const id of claims.holding()) {
       try { claims.release(id); } catch { /* the lease will handle it */ }
     }
-    process.exit(0);
   };
-  process.on('SIGINT', goodbye);
-  process.on('SIGTERM', goodbye);
 
-  await server.connect(new StdioServerTransport());
+  await server.connect(new StdioServerTransport(input, output));
   console.error(`${LOG} serving account ${account.accountId} from ${account.root} (${tools.length} tools) for ${NAME}`);
+  return { close: async () => { giveBack(); await server.close().catch(() => {}); } };
+}
+
+async function main() {
+  const { close } = await serveStore();
+  const goodbye = () => { close().finally(() => process.exit(0)); };
+  process.on('SIGINT', goodbye);
+  process.on('SIGTERM', goodbye);
 }
 
-main().catch((err) => {
+// Started as a program (mcp/agentbox-mcp.sh), not imported by a cloud run's relay.
+const startedAsProgram = path.basename(process.argv[1] || '') === 'stdio.mjs';
+if (startedAsProgram) main().catch((err) => {
   // A startup failure is almost always configuration (no account, wrong
   // STORE_HOME), so it must be readable on stderr rather than a stack trace
   // the client swallows.

package/mcp/tools.mjs

@@ -17,6 +17,10 @@ import { listProducts, getProduct, createProduct, updateProduct } from './core/p
 import { listDocuments, readDocument, writeDocument } from './core/documents.mjs';
 import { listSkills, fetchSkill, fetchReference } from './core/skills.mjs';
 import { listWorkItems, updateItem, createClaimRegistry } from './core/work.mjs';
+import { readStandingInstruction, setStandingInstruction } from './core/repeats.mjs';
+import { teamPost, teamPass, teamRemember, teamSetup, teamRoster, teamPlaybook } from './core/teammates.mjs';
+import { readTeammates, teamDir } from '../main/store/teammates-files.mjs';
+import { legacyRoot } from '../main/store/project.mjs';
 import { listProductChats, readProductChat } from './core/chat.mjs';
 import { lookAtPage } from './core/page.mjs';
 import { WORK_ITEM_STATUSES } from '../shared/work-items.mjs';
@@ -33,6 +37,8 @@ import { Name, possessive } from '../shared/product-name.mjs';
 const CAPABILITIES = [
   'products', 'documents (read and write, any path in the product)',
   'personas and transcripts (they are documents)', 'skills', 'work items', 'past chats (read only)',
+  'the standing instruction behind a repeating task, on a thread that is one of its runs',
+  'the team chat and passing work to a teammate, from any thread; remembering and setting up, on a thread that is a teammate\'s run',
   'looking at a page running on this machine (look_at_page, local addresses only)',
 ];
 const MISSING = [
@@ -50,9 +56,12 @@ const guard = (fn) => async (args) => {
   try { return await fn(args ?? {}); } catch (err) { return { ...text(`error: ${err?.message ?? err}`), isError: true }; }
 };
 
-export function buildTools({ holder } = {}) {
+// `ownItem` is the row this server's session was started for, if any.
+export function buildTools({ holder, ownItem = process.env.ZERO_ITEM || null } = {}) {
   const account = resolveAccount();
   const claims = createClaimRegistry({ holder: holder ?? `mcp-${process.pid}` });
+  const hasTeam = teammatesExist(String(process.env.STORE_ACCOUNT_ID ?? '').trim() || account.accountId);
+  const capabilities = hasTeam ? CAPABILITIES : CAPABILITIES.filter((c) => !c.includes('teammate'));
 
   const tools = [
     /* ------------------------------- products ------------------------------ */
@@ -138,7 +147,7 @@ export function buildTools({ holder } = {}) {
       name: 'fetch_skill',
       description: 'One skill in full, with a short header explaining which of its tools exist here and which are your own job. These were written for the agent inside the app, so the method applies exactly and some tool names do not.',
       schema: { name: z.string() },
-      run: ({ name }) => json(fetchSkill(name, { capabilities: CAPABILITIES, missing: MISSING })),
+      run: ({ name }) => json(fetchSkill(name, { capabilities, missing: MISSING })),
     },
     {
       name: 'fetch_reference',
@@ -162,7 +171,7 @@ export function buildTools({ holder } = {}) {
     },
     {
       name: 'create_work_item',
-      description: 'Record something that needs doing, on a product. kind and labels are free text and yours to choose; a question for the founder is a work item with kind "question". Anything you discover but cannot finish now belongs here rather than in a message, because the queue outlives this session and the message does not.',
+      description: 'Record something that needs doing, on a product. kind and labels are free text and yours to choose; a question for the person you work for is a work item with kind "question". ONE JOB IS ONE THREAD: ask how many answers you need rather than how many things you found, because every extra thread is one more thing they must read, rank and either start or close. Twenty findings they would answer in one breath are one thread, and one PR is one thread. Something you discovered but cannot finish usually belongs in the thread you are already on, under what is left to do, and work that can run in parallel goes to subagents inside this thread, not to new threads. When it really is its own job, file it under the thread it came from with parent.',
       schema: {
         product: z.string(),
         title: z.string(),
@@ -170,14 +179,14 @@ export function buildTools({ holder } = {}) {
         kind: z.string().optional(),
         labels: z.array(z.string()).optional(),
         priority: z.number().int().optional().describe('higher goes first; defaults to 0'),
-        parent: z.string().optional().describe('another work item id, for a subtask'),
+        parent: z.string().optional().describe('another work item id: the thread this one came out of. It decides where the filing lands. With a parent it is a proposal, waiting in Later and drawn on that thread with one press, so they answer it where the conversation already is; with none it is a row of its own in their inbox, addressed to them, whatever it says.'),
         runAt: z.number().int().optional().describe('epoch ms before which nothing happens with this item: it cannot be claimed and will not start. Use it when the work genuinely belongs to a later moment. A missed moment is not lost; the item simply becomes available once it passes.'),
       },
       run: ({ product, ...fields }) => json(claims.file(product, fields)),
     },
     {
       name: 'claim_work_item',
-      description: 'Take exclusive ownership of a work item before starting it. Pass an id for a specific one, or a filter to pull the next available item (highest priority, then oldest) from any product. Returns claimed false with the current holder if someone else has it, which is an ordinary outcome: ask for the next one instead. The claim is kept alive automatically for as long as this session runs and is released if it dies, so there is nothing to renew and nothing to clean up. If an earlier session on this row lost its claim mid-write, that write comes back with the claim, in `pending`: it never reached the row or the founder, so read it and carry what is still true into your own note or result.',
+      description: 'Take exclusive ownership of a work item before starting it. Pass an id for a specific one, or a filter to pull the next available item (highest priority, then oldest) from any product. With neither, a session started for a work item claims that item. Returns claimed false with the current holder if someone else has it, which is an ordinary outcome: ask for the next one instead. The claim is kept alive automatically for as long as this session runs and is released if it dies, so there is nothing to renew and nothing to clean up. If an earlier session on this row lost its claim mid-write, that write comes back with the claim, in `pending`: it never reached the row or the founder, so read it and carry what is still true into your own note or result.',
       schema: {
         product: z.string().optional(),
         id: z.string().optional(),
@@ -187,7 +196,11 @@ export function buildTools({ holder } = {}) {
           product: z.string().optional(),
         }).optional(),
       },
-      run: async ({ product, id, filter }) => json(await claims.claim({ product, id, filter: filter ?? (id ? null : {}) })),
+      // A bare call from a session started for a row means that row, not the oldest open one anywhere.
+      run: async ({ product, id, filter }) => {
+        if (!id && !filter && ownItem) return json(await claims.claim({ id: ownItem }));
+        return json(await claims.claim({ product, id, filter: filter ?? (id ? null : {}) }));
+      },
     },
     {
       name: 'update_work_item',
@@ -203,7 +216,7 @@ export function buildTools({ holder } = {}) {
         closeBecause: z.string().optional().describe('only with status done on a row the founder wrote: their own words, quoted exactly from the row, asking you to close it'),
         deferBecause: z.string().optional().describe('only with runAt on a row the founder wrote: their own words, quoted exactly from the row, asking for it to be put off or to be reminded later. Without them the row stays in their inbox'),
         problem: z.string().optional().describe(`the summary's CONTEXT: a few plain sentences, ${CONTEXT_WORDS} words at most, that bring the thread back to someone who has forgotten it: what was asked, what was found, the facts needed to decide`),
-        progress: z.string().optional().describe(`the summary's DONE list: the steps taken so far, one per line, oldest first and newest last, ${DONE_STEPS} lines at most of ${DONE_STEP_WORDS} words each. Send the whole list each time; it replaces the last one`),
+        progress: z.string().optional().describe(`the summary's DONE list: the steps taken so far, one per line, oldest first and newest last, ${DONE_STEPS} lines at most of ${DONE_STEP_WORDS} words each. Send the whole list each time; it replaces the last one. Every line is a step that FINISHED: one you are about to take goes on after it happens, never before`),
         solution: z.string().optional().describe(`no longer shown; leave it out (older threads may still carry one, ${SUMMARY_WORDS} words at most)`),
         blockedBy: z.array(z.string()).optional().describe('ids of threads this one waits on'),
         blocks: z.array(z.string()).optional().describe('ids of threads that wait on this one'),
@@ -217,6 +230,95 @@ export function buildTools({ holder } = {}) {
       run: ({ id }) => json(claims.release(id)),
     },
 
+    /* --------------------------- repeating tasks --------------------------- */
+    // The rule itself, for the session standing on one of its runs. A run that
+    // edits its own body edits a copy, and a memory note is kept per task
+    // folder while every run gets a new one, so neither reaches tomorrow.
+    {
+      name: 'read_repeating_task',
+      description: 'The standing instruction behind this run, if this thread is one run of a repeating task: the words every run after this one is briefed with, plus the schedule and when it next runs. Read it before changing it; set_repeating_task replaces the whole instruction.',
+      schema: {},
+      run: () => json(readStandingInstruction()),
+    },
+    {
+      name: 'set_repeating_task',
+      description: 'Change the standing instruction behind this run, so the next run and every one after it is briefed with the new words. This is what to use when the person tells you, on a run, how the task should go from now on ("if there is nothing new, don\'t bother me") — they should not have to go and edit it themselves, and a memory note will not do it, because every run gets a new task folder. Send the WHOLE instruction, not the part you are adding: read_repeating_task first, then send it back with their change in it. Only the words are yours: the hour, the day and which coding agent runs it stay on their own screen, and it only works on a thread that is a run of a repeating task.',
+      schema: {
+        instruction: z.string().describe('the whole standing instruction, as the person would have typed it'),
+      },
+      run: ({ instruction }) => json(setStandingInstruction({ instruction })),
+    },
+
+    /* ------------------------------- teammates ------------------------------ */
+    // On a teammate's run, the teammate speaks; on any other thread, the person
+    // does, because they asked. Which comes from the run, never an argument.
+    {
+      name: 'team_post',
+      description: 'Say something in the team chat: as the teammate this run belongs to, or, on any other thread, for the person when they ask you to tell a teammate something. The person and every teammate read it, so say "you" to the person, never "the person". Naming a teammate in `to` or with @Name in the text wakes them to read it, so name someone only when they need to act. Keep it short and plain. Add up to four short `options` when asking the person something they can answer in a tap.',
+      schema: {
+        text: z.string().describe('what to say, one to three sentences'),
+        to: z.array(z.string()).optional().describe('names of teammates who need to act on it'),
+        options: z.array(z.string()).optional().describe('short answers the person can tap, when asking them a question'),
+      },
+      run: ({ text: words, to, options }) => json(teamPost({ text: words, to, options })),
+    },
+    {
+      name: 'team_pass',
+      description: 'Hand a piece of work to a teammate whose job it is. They get it as a run of their own, with your title and details as its brief, and it shows in the team chat. On a thread that is not a teammate\'s run, use it when the person asks you to give something to one of their teammates (call team_roster first to see who is on the team). Put everything they need in the details: steps, files, links, what done looks like.',
+      schema: {
+        to: z.string().describe('the teammate\'s name'),
+        title: z.string().describe('the work, in a short line'),
+        details: z.string().describe('everything they need to do it'),
+        project: z.string().optional().describe('the project the work is in, when it is not the teammate\'s own (from another thread it defaults to that thread\'s)'),
+      },
+      run: ({ to, title, details, project }) => json(teamPass({ to, title, details, project })),
+    },
+    {
+      name: 'team_remember',
+      description: 'Keep a standing preference the person stated ("from now on", "always", "never", "I prefer"), so every later run of yours is briefed with it. A few words in their terms. The person sees it in the team chat and can undo it.',
+      schema: { text: z.string().describe('the preference, in a few words') },
+      run: ({ text: words }) => json(teamRemember({ text: words })),
+    },
+    {
+      name: 'team_playbook',
+      description: 'Keep a lesson about how the person likes a kind of work done ("open videos on the product, never a logo") in the playbook of that title ("How you like videos made"), made if new, with the thread you are on as where it came from. Every teammate that reads the playbook is briefed with it. Leave out lesson to start reading a playbook another teammate wrote.',
+      schema: {
+        playbook: z.string().describe('its title, like "How you write posts"'),
+        lesson: z.string().optional().describe('the lesson, one sentence in their terms'),
+      },
+      run: ({ playbook, lesson }) => json(teamPlaybook({ playbook, lesson })),
+    },
+    {
+      name: 'team_setup',
+      description: 'Set or change who you are as a teammate: your name (your role, like Marketing lead), role, job (as long as it needs, in plain words to yourself), goal, how the goal is counted, what needs the person\'s yes first (a statement, never a question), what you do on your own (duties: a list, each { what, every: day|weekday|week, at: ["09:00", "15:00"], on: 0-6 for weekly } or { what, after: "ship", most: runs a week }, with tell: when to bring the person in; the list you send replaces the old one), and which coding agent runs you when the person said (runsOn: claude or codex). A new teammate calls it to set itself up, and with ready true when it is set.',
+      schema: {
+        name: z.string().optional(),
+        role: z.string().optional(),
+        job: z.string().optional(),
+        goal: z.string().optional(),
+        counted: z.string().optional(),
+        asksFirst: z.string().optional(),
+        duties: z.array(z.object({
+          what: z.string(),
+          every: z.enum(['day', 'weekday', 'week']).optional(),
+          at: z.union([z.string(), z.array(z.string())]).optional(),
+          on: z.number().int().optional(),
+          after: z.enum(['ship']).optional(),
+          most: z.number().int().optional(),
+          tell: z.string().optional(),
+        })).optional(),
+        runsOn: z.enum(['claude', 'codex']).optional(),
+        ready: z.boolean().optional(),
+      },
+      run: (args) => json(teamSetup(args)),
+    },
+    {
+      name: 'team_roster',
+      description: 'The person\'s teammates (agents with standing jobs) with their role and job, and the last twenty things said in the team chat. Works on any thread.',
+      schema: {},
+      run: () => json(teamRoster()),
+    },
+
     /* -------------------------------- chats -------------------------------- */
     {
       name: 'list_chats',
@@ -256,9 +358,15 @@ export function buildTools({ holder } = {}) {
     },
   ];
 
+  // Teammates are an alpha feature: their tools are offered once there is a
+  // teammate to talk to, which is never while the feature is off.
   return {
     account,
     claims,
-    tools: tools.map((t) => ({ ...t, run: guard(t.run) })),
+    tools: tools.filter((t) => hasTeam || !t.name.startsWith('team_')).map((t) => ({ ...t, run: guard(t.run) })),
   };
 }
+
+function teammatesExist(accountId) {
+  try { return readTeammates(teamDir(legacyRoot(), accountId)).length > 0; } catch { return false; }
+}