codeply-cli 0.5.5 → 0.6.0

package/lib/tools.mjs

@@ -13,9 +13,10 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import crypto from 'crypto';
-import { exec } from 'child_process';
+import { exec, execSync, spawn } from 'child_process';
 import { createRequire } from 'module';
 import { searchLibrary, listCategories, designLibraryConfigured, CATEGORY_LABELS } from './design-library/query.mjs';
+import { design_direction, design_lint } from './design-tools.mjs';
 
 const require = createRequire(import.meta.url);
 const editEngine = require('./edit-engine.js');
@@ -24,6 +25,11 @@ const diagnostics = require('./diagnostics.js');
 const { commandPatterns } = require('./arity.js');
 const mcpLib = require('./mcp.js');
 const reachLib = require('./reach.js');
+const lifeLib = require('./life.js');
+const brainLib = require('./brain.js');
+const screenLib = require('./screen.js');
+const computerLib = require('./computer.js');
+const botMailLib = require('./bot-mail.js');
 const applyLimit = require('./apply-limit.js');
 const config = require('./config.js');
 const skills = require('./skills.js');
@@ -288,6 +294,12 @@ function isPlanPath(p, cwd) {
   return !outside && /^\.codeply\/plans\/[^/]+\.md$/i.test(rel);
 }
 
+// Design mode works in the design's own folder (its cwd) and writes there without
+// asking: a design is a sandbox. Anything outside it is blocked in executeTool.
+function isDesignWrite(p, ctx) {
+  return ctx.mode === 'Design' && !!p && !resolvePath(String(p), ctx.cwd).outside;
+}
+
 // ─── Tools ──────────────────────────────────────────────────────────────────
 
 async function list_dir(args, ctx) {
@@ -385,7 +397,7 @@ async function write_file(args, ctx) {
   const beforeLines = existed ? before.split('\n').length : 0;
   const afterLines = after.split('\n').length;
 
-  const verdict = ctx.mode === 'Plan' && isPlanPath(target, ctx.cwd) ? 'allow' : await ctx.approve({
+  const verdict = (ctx.mode === 'Plan' && isPlanPath(target, ctx.cwd)) || isDesignWrite(target, ctx) ? 'allow' : await ctx.approve({
     tool: 'write_file',
     path: rel,
     title: existed ? `Overwrite ${rel}` : `Create ${rel}`,
@@ -475,7 +487,7 @@ async function edit_file(args, ctx) {
   const removed = args.search.split('\n').length * occurrences;
   const added = args.replace.split('\n').length * occurrences;
 
-  const verdict = ctx.mode === 'Plan' && isPlanPath(target, ctx.cwd) ? 'allow' : await ctx.approve({
+  const verdict = (ctx.mode === 'Plan' && isPlanPath(target, ctx.cwd)) || isDesignWrite(target, ctx) ? 'allow' : await ctx.approve({
     tool: 'edit_file',
     path: rel,
     title: `Edit ${rel}`,
@@ -638,7 +650,7 @@ async function fetch_image(args, ctx) {
   // `path` rides alongside `detail` (the original url) so a host that wants to
   // offer a real picker doesn't have to scrape the human-readable `title` text
   // to know where the image is headed.
-  const verdict = await ctx.approve({
+  const verdict = isDesignWrite(target, ctx) ? 'allow' : await ctx.approve({
     tool: 'fetch_image',
     title: `Download image to ${rel}`,
     detail: url,
@@ -732,7 +744,7 @@ function readVerdict(v) {
 function applyEmailEdits(draft, edits) {
   if (!edits) return draft;
   const out = { ...draft };
-  for (const k of ['to', 'subject', 'body']) {
+  for (const k of ['to', 'cc', 'subject', 'body']) {
     if (typeof edits[k] === 'string') out[k] = k === 'body' ? edits[k].slice(0, 100000) : edits[k].trim().slice(0, 1000);
   }
   return out;
@@ -746,11 +758,11 @@ const GMAIL_NOT_CONNECTED = 'Gmail is not connected. Ask the user to connect it
 function draftsDir() { return path.join(os.homedir(), '.codeply', 'drafts'); }
 const DRAFT_ID = /^d[a-z0-9]{6,30}$/;
 
-function saveLocalDraft({ to, subject, body }) {
+function saveLocalDraft({ to, cc, subject, body }) {
   const dir = draftsDir();
   fs.mkdirSync(dir, { recursive: true });
   const id = `d${Date.now().toString(36)}${crypto.randomBytes(3).toString('hex')}`;
-  const draft = { id, to: to || '', subject: subject || '', body: body || '', createdAt: new Date().toISOString() };
+  const draft = { id, to: to || '', cc: cc || '', subject: subject || '', body: body || '', createdAt: new Date().toISOString() };
   fs.writeFileSync(path.join(dir, `${id}.json`), JSON.stringify(draft, null, 2));
   return draft;
 }
@@ -786,7 +798,7 @@ async function storeDraft(draft, token) {
         const r = await oauth.gmailCreateDraft(token, draft);
         return { ok: true, output: `Draft saved in Gmail's Drafts folder${draft.to ? ` (to ${draft.to})` : ''}, Gmail draft id ${r.id}. Nothing was sent.`, meta: { label: `draft: ${draft.subject || '(no subject)'}` } };
       } catch (e) {
-        if (!e.scopeMissing) return { ok: false, output: `Gmail draft failed: ${e.message}` };
+        if (!e.scopeMissing) return { ok: false, output: googleFailure('Gmail draft', 'email', e) };
         why = 'Gmail was connected before drafts were allowed, so it was saved in Codeply\'s drafts instead. Reconnect Gmail in Connect Apps to allow drafts in Gmail.';
       }
     }
@@ -803,6 +815,7 @@ async function storeDraft(draft, token) {
 
 async function gmail_send(args, ctx) {
   let to = (args.to || '').trim();
+  let cc = (args.cc || '').trim();
   let subject = (args.subject || '').trim();
   let body = args.body || '';
   const draftId = String(args.draft || '').trim();
@@ -810,7 +823,7 @@ async function gmail_send(args, ctx) {
   if (draftId) {
     saved = readLocalDraft(draftId);
     if (!saved) return { ok: false, output: `No saved draft with id "${draftId}". drafts_list shows the saved drafts.` };
-    to = to || saved.to; subject = subject || saved.subject; body = body || saved.body;
+    to = to || saved.to; cc = cc || saved.cc || ''; subject = subject || saved.subject; body = body || saved.body;
   }
   if (!to) return { ok: false, output: 'gmail_send needs a <to> address.' };
   if (!subject) return { ok: false, output: 'gmail_send needs a <subject>.' };
@@ -821,15 +834,15 @@ async function gmail_send(args, ctx) {
 
   const verdict = readVerdict(await ctx.approve({
     tool: 'gmail_send',
-    title: `Send email to ${to}`,
-    detail: `Subject: ${subject}\n\n${body}`,
+    title: `Send email to ${to}${cc ? ` (cc ${cc})` : ''}`,
+    detail: `${cc ? `Cc: ${cc}\n` : ''}Subject: ${subject}\n\n${body}`,
     danger: false,
     // The card shows these as editable fields; edits come back with the verdict.
-    draft: { to, subject, body },
+    draft: { to, cc, subject, body },
   }));
   if (verdict.action === 'reject') return { ok: false, output: `User declined to send the email to ${to}.`, meta: { rejected: true } };
-  const email = applyEmailEdits({ to, subject, body }, verdict.edits);
-  const edited = !!verdict.edits && (email.to !== to || email.subject !== subject || email.body !== body);
+  const email = applyEmailEdits({ to, cc, subject, body }, verdict.edits);
+  const edited = !!verdict.edits && (email.to !== to || email.cc !== cc || email.subject !== subject || email.body !== body);
   if (verdict.action === 'draft') {
     const r = await storeDraft(email, token);
     return { ...r, output: `The user chose to save it as a draft instead of sending. ${r.output}` };
@@ -839,15 +852,17 @@ async function gmail_send(args, ctx) {
   try {
     const result = await oauth.gmailSend(token, email);
     if (saved) { try { fs.unlinkSync(path.join(draftsDir(), `${saved.id}.json`)); } catch {} }
-    const note = edited ? ` The user edited it before sending; what went out: to ${email.to}, subject "${email.subject}".` : '';
-    return { ok: true, output: `Email sent to ${email.to} (message id ${result.id}).${note}`, meta: { label: `to ${email.to}: ${email.subject}` } };
+    const note = edited ? ` The user edited it before sending; what went out: to ${email.to}${email.cc ? `, cc ${email.cc}` : ''}, subject "${email.subject}".` : '';
+    // Whoever this answers is no longer waiting on the user (the life context).
+    try { lifeLib.noteSent([email.to, email.cc].filter(Boolean).join(',')); } catch {}
+    return { ok: true, output: `Email sent to ${email.to}${email.cc ? `, cc ${email.cc}` : ''} (message id ${result.id}).${note}`, meta: { label: `to ${email.to}: ${email.subject}` } };
   } catch (e) {
-    return { ok: false, output: `Gmail send failed: ${e.message}` };
+    return { ok: false, output: googleFailure('Gmail send', 'email', e) };
   }
 }
 
 async function gmail_draft(args, ctx) {
-  const draft = { to: (args.to || '').trim(), subject: (args.subject || '').trim(), body: args.body || '' };
+  const draft = { to: (args.to || '').trim(), cc: (args.cc || '').trim(), subject: (args.subject || '').trim(), body: args.body || '' };
   if (!draft.subject && !draft.body.trim()) return { ok: false, output: 'gmail_draft needs at least a <subject> or a <body>.' };
 
   let token = null;
@@ -856,7 +871,7 @@ async function gmail_draft(args, ctx) {
   const verdict = readVerdict(await ctx.approve({
     tool: 'gmail_draft',
     title: `Save a draft${draft.to ? ` to ${draft.to}` : ''}${token ? ' in Gmail' : ''}`,
-    detail: `Subject: ${draft.subject}\n\n${draft.body}`,
+    detail: `${draft.cc ? `Cc: ${draft.cc}\n` : ''}Subject: ${draft.subject}\n\n${draft.body}`,
     danger: false,
     draft,
     draftOnly: true,
@@ -924,7 +939,23 @@ function eventLine(ev) {
     const e = new Date(ev.end && ev.end.dateTime);
     when = Number.isNaN(s.getTime()) ? '(no time)' : `${showLocal(s)} to ${Number.isNaN(e.getTime()) ? '?' : (ymd(e) === ymd(s) ? `${pad2(e.getHours())}:${pad2(e.getMinutes())}` : showLocal(e))}`;
   }
-  return `- ${title}: ${when}${ev.location ? `, at ${ev.location}` : ''}`;
+  const guests = (ev.attendees || []).filter((a) => a && a.email && !a.self).map((a) => a.email);
+  return `- ${ev.id ? `[${ev.id}] ` : ''}${title}: ${when}${ev.location ? `, at ${ev.location}` : ''}${guests.length ? ` (with ${guests.slice(0, 6).join(', ')})` : ''}`;
+}
+
+/**
+ * What a failed Google call tells the model. Switched off on Codeply's side
+ * (an API not enabled in the Cloud project behind the app): the user can't fix
+ * that, so the bot just says it can't reach it right now, with no links, error
+ * codes or setup steps. Anything the user can fix (sign in again, allow
+ * access) is passed on in plain words.
+ */
+function googleFailure(what, thing, e, extra = '') {
+  if (e && e.serviceSide) {
+    console.warn(`[google] ${what}: ${e.message}`); // for whoever runs Codeply: enable the API in that Cloud project
+    return `${what} is not available in Codeply right now. This is a setup problem on Codeply's side, not something the user can fix. Tell the user in one short, friendly sentence that you can't reach their ${thing} right now. Do not give links, error codes, project numbers or setup steps. Then still help with what they asked, another way.`;
+  }
+  return `${what} failed: ${e.message}${extra} Tell the user briefly, in plain words, what went wrong and what they can do about it; no raw error codes or links.`;
 }
 
 async function calendar_list(args) {
@@ -947,7 +978,7 @@ async function calendar_list(args) {
     if (!items.length) return { ok: true, output: `No events from ${range} (local time).`, meta: { label: 'no events' } };
     return { ok: true, output: `${items.length} event(s) from ${range} (local time):\n${items.map(eventLine).join('\n')}`, meta: { label: `${items.length} event(s)`, count: items.length } };
   } catch (e) {
-    return { ok: false, output: `Calendar list failed: ${e.message} Tell the user this exact error.` };
+    return { ok: false, output: googleFailure('Calendar list', 'calendar', e) };
   }
 }
 
@@ -961,6 +992,8 @@ async function calendar_add(args, ctx) {
   const event = { summary: title };
   if (args.description) event.description = String(args.description);
   if (args.location) event.location = String(args.location).trim();
+  const guests = String(args.attendees || args.guests || '').split(/[\s,;]+/).map((x) => x.trim()).filter((x) => /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(x)).slice(0, 30);
+  if (guests.length) event.attendees = guests.map((email) => ({ email }));
   let when;
   if (start.allDay && (!end || end.allDay)) {
     // All-day: Google's end date is exclusive, so a one-day event ends the next day.
@@ -987,14 +1020,66 @@ async function calendar_add(args, ctx) {
   try { t = await googleTokenFor('Google Calendar'); } catch (e) { return { ok: false, output: `Calendar add failed: ${e.message}` }; }
   if (t.error) return { ok: false, output: t.error };
 
-  const detail = [`When: ${when} (local time)`, event.location ? `Where: ${event.location}` : '', mins.length ? `Reminders: ${mins.map((m) => `${m} min before`).join(', ')}` : '', event.description ? `\n${event.description}` : ''].filter(Boolean).join('\n');
+  const detail = [`When: ${when} (local time)`, event.location ? `Where: ${event.location}` : '', guests.length ? `Guests (they get an invite): ${guests.join(', ')}` : '', mins.length ? `Reminders: ${mins.map((m) => `${m} min before`).join(', ')}` : '', event.description ? `\n${event.description}` : ''].filter(Boolean).join('\n');
   const verdict = readVerdict(await ctx.approve({ tool: 'calendar_add', title: `Add "${title}" to your calendar`, detail, danger: false }));
   if (verdict.action === 'reject') return { ok: false, output: `User declined to add "${title}" to the calendar.`, meta: { rejected: true } };
   try {
     const r = await oauth.calendarInsertEvent(t.token, event);
-    return { ok: true, output: `Added "${title}" to the calendar: ${when} (local time)${event.location ? `, at ${event.location}` : ''}.${r.htmlLink ? ` Link: ${r.htmlLink}` : ''}`, meta: { label: `${title}: ${when}` } };
+    return { ok: true, output: `Added "${title}" to the calendar: ${when} (local time)${event.location ? `, at ${event.location}` : ''}${guests.length ? `; invites sent to ${guests.join(', ')}` : ''}. Event id ${r.id}.${r.htmlLink ? ` Link: ${r.htmlLink}` : ''}`, meta: { label: `${title}: ${when}` } };
+  } catch (e) {
+    return { ok: false, output: googleFailure('Calendar add', 'calendar', e) };
+  }
+}
+
+/** Move, rename or cancel one event (its id from calendar_list). Asks first; guests are told. */
+async function calendar_update(args, ctx) {
+  const id = String(args.id || '').trim().replace(/^\[|\]$/g, '');
+  if (!id) return { ok: false, output: 'calendar_update needs the event <id> from calendar_list.' };
+  const cancel = /^(yes|true|1|cancel)$/i.test(String(args.cancel || '').trim());
+  const patch = {};
+  if (args.title) patch.summary = String(args.title).trim();
+  if (args.location) patch.location = String(args.location).trim();
+  if (args.description) patch.description = String(args.description);
+  let when = '';
+  if (args.start) {
+    const start = parseWhen(args.start);
+    if (!start || start.allDay) return { ok: false, output: `calendar_update needs a <start> with a time (got "${args.start}"), like 2026-10-03T14:00.` };
+    const end = args.end ? parseWhen(args.end) : null;
+    const minutes = Number(args.minutes) || 60;
+    const e = end && !end.allDay ? end.date : new Date(start.date.getTime() + minutes * 60000);
+    if (e <= start.date) return { ok: false, output: 'calendar_update: <end> must be after <start>.' };
+    let tz = ''; try { tz = Intl.DateTimeFormat().resolvedOptions().timeZone || ''; } catch {}
+    patch.start = { dateTime: localIso(start.date), ...(tz ? { timeZone: tz } : {}) };
+    patch.end = { dateTime: localIso(e), ...(tz ? { timeZone: tz } : {}) };
+    when = `${showLocal(start.date)} to ${pad2(e.getHours())}:${pad2(e.getMinutes())}`;
+  }
+  if (!cancel && !Object.keys(patch).length) return { ok: false, output: 'calendar_update: say what changes (<start>, <title>, <location>), or <cancel>yes</cancel>.' };
+  let t;
+  try { t = await googleTokenFor('Google Calendar'); } catch (e) { return { ok: false, output: `Calendar update failed: ${e.message}` }; }
+  if (t.error) return { ok: false, output: t.error };
+  const title = cancel ? `Cancel the event ${id} on your calendar` : `Change the event on your calendar${patch.summary ? ` to "${patch.summary}"` : ''}${when ? `: ${when}` : ''}`;
+  const verdict = readVerdict(await ctx.approve({ tool: 'calendar_update', title, detail: cancel ? 'The event is removed; any guests are told.' : [when ? `When: ${when} (local time)` : '', patch.location ? `Where: ${patch.location}` : '', 'Guests are told about the change.'].filter(Boolean).join('\n'), danger: false }));
+  if (verdict.action === 'reject') return { ok: false, output: 'User declined the calendar change.', meta: { rejected: true } };
+  try {
+    if (cancel) { await oauth.calendarDeleteEvent(t.token, id); return { ok: true, output: `Cancelled event ${id}.`, meta: { label: `cancelled ${id}` } }; }
+    const r = await oauth.calendarPatchEvent(t.token, id, patch);
+    return { ok: true, output: `Updated "${r.summary || patch.summary || id}"${when ? `: now ${when} (local time)` : ''}.`, meta: { label: `${r.summary || id}${when ? `: ${when}` : ''}` } };
+  } catch (e) {
+    return { ok: false, output: googleFailure('Calendar update', 'calendar', e) };
+  }
+}
+
+async function gmail_read(args) {
+  const id = String(args.id || '').trim().replace(/^\[|\]$/g, '');
+  if (!id) return { ok: false, output: 'gmail_read needs the <id> of an email, from gmail_search.' };
+  try {
+    const token = await getValidGmailToken();
+    if (!token) return { ok: false, output: GMAIL_NOT_CONNECTED };
+    const m = await oauth.gmailGetMessage(token, id);
+    const body = String(m.body || '').replace(/\r/g, '').replace(/\n{3,}/g, '\n\n').trim();
+    return { ok: true, output: truncate(`From: ${m.from}\nTo: ${m.to}${m.cc ? `\nCc: ${m.cc}` : ''}\nDate: ${m.date}\nSubject: ${m.subject}\nThread: ${m.threadId}\n\n${body || '(empty)'}`), meta: { label: m.subject || id } };
   } catch (e) {
-    return { ok: false, output: `Calendar add failed: ${e.message} Tell the user this exact error.` };
+    return { ok: false, output: googleFailure('Gmail read', 'email', e) };
   }
 }
 
@@ -1016,10 +1101,10 @@ async function gmail_search(args, ctx) {
       results = await oauth.gmailSearch(token, query);
     }
     if (!results.length) return { ok: true, output: query ? `No messages matched "${query}".` : 'The mailbox is empty.', meta: { label } };
-    const lines = results.map((m) => `- ${m.subject || '(no subject)'} - from ${m.from} - ${m.date}\n  ${m.snippet}`);
-    return { ok: true, output: `${results.length} message(s)${query ? ` matching "${query}"` : ', newest first'}:\n\n${lines.join('\n')}`, meta: { label, count: results.length } };
+    const lines = results.map((m) => `- [${m.id}] ${m.subject || '(no subject)'} - from ${m.from} - ${m.date}\n  ${m.snippet}`);
+    return { ok: true, output: `${results.length} message(s)${query ? ` matching "${query}"` : ', newest first'}:\n\n${lines.join('\n')}\n\n(These are previews. gmail_read with the [id] reads a whole email.)`, meta: { label, count: results.length } };
   } catch (e) {
-    return { ok: false, output: `Gmail search failed: ${e.message} Do not retry with other queries; tell the user this exact error.` };
+    return { ok: false, output: googleFailure('Gmail search', 'email', e, ' Do not retry with other queries.') };
   }
 }
 
@@ -1057,10 +1142,16 @@ async function slack_post_message(args, ctx) {
     // Channel lookup always uses the bot token - channels:read is a bot-only
     // scope in this app's setup regardless of which token ends up posting.
     const channelId = await resolveSlackChannel(slack.accessToken, channelInput);
-    // Posting defaults to the user token when connected - messages read as
-    // coming from the actual person, not the "Codeply Craft APP" bot. Falls
-    // back to the bot token for anyone who connected before user-token
-    // support existed, or who only approved the bot scopes.
+    // A bot posts as itself (the app's bot token, with the bot's name), never
+    // as the user. The plain agent posts with the user token when connected -
+    // messages read as coming from the actual person, not the "Codeply Craft
+    // APP" bot - and falls back to the bot token for anyone who connected
+    // before user-token support existed, or who only approved the bot scopes.
+    const bot = ctx.botId ? require('./bots.js').getBot(ctx.botId) : null;
+    if (bot) {
+      const r = await oauth.slackPostMessage(slack.accessToken, { channel: channelId, text }, { asName: `${bot.name} (assistant)` });
+      return { ok: true, output: `Posted to ${channelInput} as ${bot.name}${r.named ? '' : ' (with the Codeply app\'s name: reconnect Slack in Connect Apps so bots can post under their own names)'}.`, meta: { label: `#${channelInput.replace(/^#/, '')} as ${bot.name}` } };
+    }
     const useUserToken = !!slack.userAccessToken;
     const postToken = useUserToken ? slack.userAccessToken : slack.accessToken;
     await oauth.slackPostMessage(postToken, { channel: channelId, text }, { isUserToken: useUserToken });
@@ -1539,6 +1630,20 @@ async function run(args, ctx) {
   });
   if (verdict === 'reject') return { ok: false, output: `User declined to run: ${displayCommand}`, meta: { rejected: true } };
 
+  if (/^(1|true|yes)$/i.test(String(args.background || '').trim())) {
+    if (READ_ONLY_MODES.has(ctx.mode)) return { ok: false, output: `Background commands are not available in ${ctx.mode} mode.` };
+    const j = startJob(displayCommand, execCommand, ctx.cwd);
+    // A few seconds so an instant failure or a "listening on :3000" line comes back now.
+    await new Promise((r) => { const t = setTimeout(r, 4000); j.child.once('close', () => { clearTimeout(t); r(); }); });
+    const state = j.endedAt ? `exited with code ${j.code}` : 'still running in the background';
+    const tail = j.out.trim() ? truncate(j.out.trimEnd(), 3000, { keep: 'ends', spill: false }) : '(no output yet)';
+    return {
+      ok: true,
+      output: `$ ${displayCommand}\n[background job ${j.id}: ${state}]\n${tail}\n\nRead its output later with <codeply:job><id>${j.id}</id></codeply:job>, stop it with <stop>true</stop> in the same block. Do not start it again.`,
+      meta: { label: displayCommand, background: true, jobId: j.id, output: j.out.slice(-JOB_SHOWN), ...(j.endedAt ? { exitCode: j.code } : {}) },
+    };
+  }
+
   return new Promise((resolve) => {
     exec(execCommand, { cwd: ctx.cwd, timeout: RUN_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, windowsHide: true },
       (err, stdout, stderr) => {
@@ -1559,12 +1664,84 @@ async function run(args, ctx) {
         resolve({
           ok: true, // a non-zero exit is a real result the model must see, not a tool failure
           output: truncate(`$ ${displayCommand}\n[exit ${code}]\n${body}`, MAX_TOOL_OUTPUT, { keep: 'ends' }) + (hint ? `\n[hint] ${hint}` : ''),
-          meta: { label: displayCommand, exitCode: effectiveCode, ...(effectiveCode !== code ? { maskedFailure: true } : {}) },
+          // What the user sees when they open the row: the end of the real output.
+          meta: { label: displayCommand, exitCode: effectiveCode, output: body.slice(-JOB_SHOWN), ...(effectiveCode !== code ? { maskedFailure: true } : {}) },
         });
       });
   });
 }
 
+// ─── Background commands: dev servers, watchers, long builds ─────────────────
+// run with <background>true</background> starts the command and answers at once;
+// job reads its output later or stops it. Jobs live as long as the app does,
+// and the host (Craft) lists them under the composer through backgroundJobs.
+const jobs = new Map(); // id -> { id, command, cwd, child, out, startedAt, endedAt, code }
+const jobListeners = new Set();
+const JOB_KEEP = 64 * 1024; // output kept per job
+const JOB_SHOWN = 4000; // output shown on a chat row
+let jobSeq = 0;
+
+const jobCard = (j) => ({ id: j.id, command: j.command, cwd: j.cwd, startedAt: j.startedAt, endedAt: j.endedAt, code: j.code, running: !j.endedAt });
+function jobChanged(j) { for (const fn of jobListeners) { try { fn(jobCard(j)); } catch {} } }
+
+function startJob(command, execCommand, cwd) {
+  const win = process.platform === 'win32';
+  // detached on POSIX so the whole process group can be stopped; Windows uses taskkill /T.
+  const child = spawn(execCommand, { cwd, shell: true, windowsHide: true, detached: !win });
+  const j = { id: String(++jobSeq), command, cwd, child, out: '', startedAt: Date.now(), endedAt: 0, code: null };
+  const add = (d) => { j.out += d.toString(); if (j.out.length > JOB_KEEP) j.out = j.out.slice(-JOB_KEEP); };
+  child.stdout.on('data', add);
+  child.stderr.on('data', add);
+  child.on('error', (e) => add(`\n[error] ${e.message}\n`));
+  child.on('close', (code) => { j.code = code == null ? 1 : code; j.endedAt = Date.now(); jobChanged(j); });
+  jobs.set(j.id, j);
+  jobChanged(j);
+  return j;
+}
+
+function killJob(j, { sync = false } = {}) {
+  if (j.endedAt) return;
+  try {
+    if (process.platform === 'win32') {
+      const cmd = `taskkill /pid ${j.child.pid} /T /F`;
+      if (sync) execSync(cmd, { windowsHide: true, stdio: 'ignore' }); else exec(cmd, { windowsHide: true }, () => {});
+    } else process.kill(-j.child.pid, 'SIGTERM');
+  } catch { try { j.child.kill(); } catch {} }
+}
+
+function jobLine(j) {
+  const secs = Math.round(((j.endedAt || Date.now()) - j.startedAt) / 1000);
+  return `[job ${j.id}] ${j.endedAt ? `exited with code ${j.code} after ${secs}s` : `running for ${secs}s`}: ${j.command}`;
+}
+
+async function job(args) {
+  const id = String(args.id || '').trim().replace(/^#/, '');
+  if (!id) {
+    if (!jobs.size) return { ok: true, output: 'No background jobs.', meta: { label: 'no background jobs' } };
+    return { ok: true, output: [...jobs.values()].map(jobLine).join('\n'), meta: { label: `${jobs.size} background job${jobs.size === 1 ? '' : 's'}` } };
+  }
+  const j = jobs.get(id);
+  if (!j) return { ok: false, output: `No background job ${id}. Jobs: ${[...jobs.keys()].join(', ') || 'none'}.` };
+  if (/^(1|true|yes)$/i.test(String(args.stop || '').trim())) {
+    const wasRunning = !j.endedAt;
+    killJob(j);
+    if (wasRunning) await new Promise((r) => { const t = setTimeout(r, 2000); j.child.once('close', () => { clearTimeout(t); r(); }); });
+    return { ok: true, output: wasRunning ? `Stopped job ${id}: ${j.command}` : `Job ${id} had already ${jobLine(j).split(': ')[0].replace(/^\[job \d+\] /, '')}.`, meta: { label: `stopped: ${j.command}` } };
+  }
+  const out = j.out.trimEnd() || '(no output yet)';
+  return { ok: true, output: `${jobLine(j)}\n${truncate(out, MAX_TOOL_OUTPUT, { keep: 'ends' })}`, meta: { label: j.command, output: out.slice(-JOB_SHOWN), ...(j.endedAt ? { exitCode: j.code } : {}) } };
+}
+
+export const backgroundJobs = {
+  list: () => [...jobs.values()].map(jobCard),
+  output: (id) => (jobs.get(String(id)) || {}).out || '',
+  stop: (id) => { const j = jobs.get(String(id)); if (j) killJob(j); return !!j; },
+  /** Forget finished jobs (the list under the composer clears them). */
+  clear: () => { for (const [id, j] of jobs) if (j.endedAt) jobs.delete(id); },
+  stopAll: () => { for (const j of jobs.values()) killJob(j, { sync: true }); },
+  onChange: (fn) => { jobListeners.add(fn); return () => jobListeners.delete(fn); },
+};
+
 /**
  * Load one skill's full instructions on demand. Read-only, no approval - the
  * whole point of the skill index living in the system prompt (see
@@ -2115,7 +2292,7 @@ async function apply_patch(args, ctx) {
     .filter((l) => l.startsWith(sign) && !l.startsWith(sign.repeat(3) + ' '))
     .map((l) => l.slice(1)).join('\n').slice(0, 4000);
 
-  const verdict = await ctx.approve({
+  const verdict = ctx.mode === 'Design' && !danger ? 'allow' : await ctx.approve({
     tool: 'apply_patch',
     title: plan.changes.length === 1 ? `Patch ${label(plan.changes[0])}` : `Apply patch (${plan.changes.length} files)`,
     detail,
@@ -2237,8 +2414,86 @@ async function ask_bot(args, ctx) {
 }
 
 // ─── Reaching the user's phone (lib/reach.js; the host registers the handler) ─
-const reach_me = (args, ctx) => reachLib.reachMe(args, ctx);
-const watch_email = (args, ctx) => reachLib.watchEmail(args, ctx);
+// A reminder at a time also lands on the user's Google Calendar (when connected),
+// so the day's plan shows it without a second ask. No guests, so no approval.
+async function reach_me(args, ctx) {
+  const r = await reachLib.reachMe(args, ctx);
+  const at = r.ok ? reachLib.parseWhen(args.at) : null;
+  if (!at) return r;
+  try {
+    const t = await googleTokenFor('Google Calendar');
+    if (t.error) return r;
+    let tz = '';
+    try { tz = Intl.DateTimeFormat().resolvedOptions().timeZone || ''; } catch {}
+    const title = String(args.message || '').trim().replace(/\s+/g, ' ').slice(0, 80);
+    const end = new Date(at.getTime() + 30 * 60 * 1000);
+    await oauth.calendarInsertEvent(t.token, {
+      summary: title,
+      description: 'Set as a phone reminder in Codeply.',
+      start: { dateTime: localIso(at), ...(tz ? { timeZone: tz } : {}) },
+      end: { dateTime: localIso(end), ...(tz ? { timeZone: tz } : {}) },
+      reminders: { useDefault: false, overrides: [{ method: 'popup', minutes: 10 }] },
+    });
+    return { ...r, output: `${r.output} It is also on the user's Google Calendar at ${showLocal(at)} with a 10 minute reminder, so do not add it again.`, meta: { ...(r.meta || {}), label: `${(r.meta && r.meta.label) || 'Reminder'} (also on your calendar)` } };
+  } catch { return r; }
+}
+const watch_email =(args, ctx) => reachLib.watchEmail(args, ctx);
+
+// ─── The user's life context (lib/life.js; the host attaches the store) ──────
+// A bot reads only the sources its Life settings allow; the plain agent reads the non-sensitive ones.
+function life_context(args, ctx) {
+  const bot = ctx.botId ? require('./bots.js').getBot(ctx.botId) : null;
+  return lifeLib.contextTool(args, { bot });
+}
+
+// ─── The shared brain (lib/brain.js): one memory for every app and bot ────────
+const remember = (args, ctx) => brainLib.rememberTool(args, ctx);
+const recall = (args, ctx) => brainLib.recallTool(args, ctx);
+
+// Pass a job to the agent whose domain it is, and carry on (no waiting, unlike
+// ask_bot). The host provides ctx.handOff, which knows who asked for this run.
+async function hand_off(args, ctx) {
+  if (typeof ctx.handOff !== 'function') return { ok: false, output: 'hand_off is not available here. Do the work yourself, or ask a teammate with ask_bot.' };
+  if (!String(args.intent || '').trim()) return { ok: false, output: 'hand_off needs <intent>: what the other agent should get done.' };
+  return ctx.handOff({ to: String(args.to || '').trim(), intent: String(args.intent || '').trim(), facts: args.facts, decision: args.decision });
+}
+
+// ─── The user's screen (lib/screen.js; only a desktop host can look) ──────────
+// A picture of the screen and its text, for "this", "her message", "what's on my right".
+const look_at_screen = (args, ctx) => screenLib.lookTool(ctx, args);
+const use_computer = (args, ctx) => computerLib.tool(args, ctx);
+
+// ─── A bot's own email (lib/bot-mail.js; the host sends through Codeply's server) ─
+// The same editable card as gmail_send: what is left on it is what goes out.
+async function bot_email_send(args, ctx) {
+  const bot = ctx.botId ? require('./bots.js').getBot(ctx.botId) : null;
+  if (!bot) return { ok: false, output: 'Only a bot with its own address can email as itself. Use gmail_send to send from the user\'s Gmail.' };
+  const from = botMailLib.addressOf(bot.id);
+  if (!from) return { ok: false, output: `${bot.name} has no email address yet. The user can give it one in Crew: Edit bot, Email.` };
+  const thread = args.reply_to ? await botMailLib.threadOf(args.reply_to) : null;
+  if (args.reply_to && !thread) return { ok: false, output: `No received email with id "${args.reply_to}". Leave reply_to empty to start a new email.` };
+  const to = String(args.to || (thread && thread.to) || '').trim();
+  const subject = String(args.subject || (thread && thread.subject) || '').trim();
+  const body = String(args.body || '');
+  if (!to) return { ok: false, output: 'bot_email_send needs a <to> address.' };
+  if (!body.trim()) return { ok: false, output: 'bot_email_send needs a <body>.' };
+  const verdict = readVerdict(await ctx.approve({
+    tool: 'bot_email_send',
+    title: `Email ${to} as ${bot.name} (${from})`,
+    detail: `Subject: ${subject || '(no subject)'}\n\n${body}`,
+    danger: false,
+    draft: { to, subject, body },
+    draftOnly: false,
+  }));
+  if (verdict.action === 'reject') return { ok: false, output: `User declined to send the email to ${to}.`, meta: { rejected: true } };
+  if (verdict.action === 'draft') return { ok: false, output: 'The user wants to keep it as a draft. It was not sent; tell them it is on the card above.', meta: { rejected: true } };
+  const email = applyEmailEdits({ to, subject, body }, verdict.edits);
+  if (!email.to) return { ok: false, output: 'The email has no recipient after the user\'s edits, so it was not sent.' };
+  const r = await botMailLib.send({ botId: bot.id, to: email.to, subject: email.subject, text: email.body, replyTo: thread ? thread.id : '' });
+  if (!r || !r.ok) return { ok: false, output: `Not sent: ${(r && (r.error || r.output)) || 'the server did not answer'}` };
+  const left = r.used && r.limits ? ` The crew has ${Math.max(0, r.limits.day - r.used.day)} emails left today and ${Math.max(0, r.limits.month - r.used.month)} this month.` : '';
+  return { ok: true, output: `Sent from ${from} to ${email.to}, subject "${email.subject}".${left}`, meta: { label: `to ${email.to}: ${email.subject}` } };
+}
 
 // ─── Publishing (Supabase + Vercel + GitHub, see lib/publish.js) ────────────
 const publishTools = publishLib.makePublishTools({
@@ -2295,17 +2550,18 @@ export const TOOLS = {
   ask_bot,
   ask_user,
   mcp,
-  web_fetch, web_search, image_search, apply_patch, plan_exit, plan_enter, lsp, reach_me, watch_email,
-  list_dir, read_file, write_file, edit_file, search, run, use_skill, list_skills, fetch_image, browser_check,
-  gmail_send, gmail_search, gmail_draft, drafts_list, calendar_list, calendar_add, slack_post_message, vercel_deploy, supabase_create_project, supabase_delete_project, github_create_repo,
+  web_fetch, web_search, image_search, apply_patch, plan_exit, plan_enter, lsp, reach_me, watch_email, life_context, remember, recall, hand_off, bot_email_send, look_at_screen, use_computer,
+  list_dir, read_file, write_file, edit_file, search, run, job, use_skill, list_skills, fetch_image, browser_check,
+  gmail_send, gmail_search, gmail_read, gmail_draft, drafts_list, calendar_list, calendar_add, calendar_update, slack_post_message, vercel_deploy, supabase_create_project, supabase_delete_project, github_create_repo,
   design_reference_search, view_images, supabase_api, supabase_sql, vercel_api, add_model,
+  design_direction, design_lint,
 };
 
 // Tools that can change something. supabase_api/supabase_sql/vercel_api only
 // actually prompt for non-read requests (see above); read-only tools
 // (browser_check, gmail_search, design_reference_search, view_images, ...)
 // never prompt.
-export const TOOL_NEEDS_APPROVAL = new Set(['add_model', 'supabase_setup', 'supabase_schema', 'publish_deploy', 'publish_github', 'write_file', 'edit_file', 'apply_patch', 'run', 'fetch_image', 'gmail_send', 'gmail_draft', 'calendar_add', 'slack_post_message', 'vercel_deploy', 'supabase_create_project', 'supabase_delete_project', 'github_create_repo', 'supabase_api', 'supabase_sql', 'vercel_api']);
+export const TOOL_NEEDS_APPROVAL = new Set(['use_computer', 'add_model', 'supabase_setup', 'supabase_schema', 'publish_deploy', 'publish_github', 'write_file', 'edit_file', 'apply_patch', 'run', 'fetch_image', 'gmail_send', 'gmail_draft', 'bot_email_send', 'calendar_add', 'calendar_update', 'slack_post_message', 'vercel_deploy', 'supabase_create_project', 'supabase_delete_project', 'github_create_repo', 'supabase_api', 'supabase_sql', 'vercel_api']);
 
 /** Human-facing verb + colour hint for the transcript. */
 export const TOOL_DISPLAY = {
@@ -2318,6 +2574,13 @@ export const TOOL_DISPLAY = {
   image_search: { verb: 'images', icon: '▸' },
   reach_me: { verb: 'phone', icon: '☎' },
   watch_email: { verb: 'watch', icon: '✉' },
+  life_context: { verb: 'context', icon: '◷' },
+  remember: { verb: 'remember', icon: '✦' },
+  recall: { verb: 'recall', icon: '✦' },
+  hand_off: { verb: 'handed', icon: '⇢' },
+  look_at_screen: { verb: 'screen', icon: '◉' },
+  use_computer: { verb: 'computer', icon: '◉' },
+  bot_email_send: { verb: 'email', icon: '✉' },
   apply_patch:{ verb: 'patch',  icon: '✎' },
   plan_exit:  { verb: 'plan',   icon: '☐' },
   plan_enter: { verb: 'plan',   icon: '☐' },
@@ -2328,6 +2591,7 @@ export const TOOL_DISPLAY = {
   edit_file:  { verb: 'edit',   icon: '✎' },
   search:     { verb: 'search', icon: '▸' },
   run:        { verb: 'run',    icon: '$' },
+  job:        { verb: 'job',    icon: '$' },
   use_skill:  { verb: 'skill',  icon: '★' },
   list_skills:{ verb: 'skills', icon: '★' },
   fetch_image:{ verb: 'fetch',  icon: '⇩' },
@@ -2338,6 +2602,8 @@ export const TOOL_DISPLAY = {
   drafts_list:{ verb: 'drafts', icon: '✉' },
   calendar_list:{ verb: 'calendar', icon: '▦' },
   calendar_add:{ verb: 'calendar', icon: '▦' },
+  calendar_update:{ verb: 'calendar', icon: '▦' },
+  gmail_read:{ verb: 'read', icon: '✉' },
   add_model:{ verb: 'model', icon: '◆' },
   slack_post_message:{ verb: 'post', icon: '#' },
   vercel_deploy:{ verb: 'deploy', icon: '▲' },
@@ -2345,6 +2611,8 @@ export const TOOL_DISPLAY = {
   supabase_delete_project:{ verb: 'delete', icon: '◆' },
   github_create_repo:{ verb: 'push', icon: '⎇' },
   design_reference_search:{ verb: 'reference', icon: '◫' },
+  design_direction:{ verb: 'direction', icon: '◐' },
+  design_lint:{ verb: 'check', icon: '◎' },
   view_images:{ verb: 'view', icon: '◉' },
   supabase_api:{ verb: 'supabase', icon: '◆' },
   supabase_sql:{ verb: 'sql', icon: '◆' },
@@ -2361,17 +2629,35 @@ export const TOOL_DISPLAY = {
 // agent.mjs; this covers every other tool that changes something outside the
 // conversation, so read-only can't be escaped through a side door.
 const MUTATING_TOOLS = new Set([
-  'write_file', 'edit_file', 'apply_patch', 'fetch_image', 'gmail_send', 'gmail_draft', 'calendar_add', 'slack_post_message', 'add_model',
+  'write_file', 'edit_file', 'apply_patch', 'fetch_image', 'gmail_send', 'gmail_draft', 'calendar_add', 'calendar_update', 'slack_post_message', 'add_model', 'use_computer',
   'vercel_deploy', 'supabase_create_project', 'supabase_delete_project', 'github_create_repo',
   'supabase_setup', 'supabase_schema', 'publish_deploy', 'publish_github',
 ]);
 
+// Everything that isn't designing: commands, deploys, databases, messages, other projects.
+export const DESIGN_BLOCKED = new Set([
+  'run', 'job', 'use_computer', 'lsp', 'mcp', 'ask_bot', 'hand_off', 'plan_enter', 'plan_exit', 'reach_me', 'watch_email', 'add_model', 'browser_check', 'bot_email_send',
+  'gmail_send', 'gmail_draft', 'gmail_search', 'gmail_read', 'drafts_list', 'calendar_list', 'calendar_add', 'calendar_update', 'slack_post_message',
+  'vercel_deploy', 'vercel_api', 'supabase_create_project', 'supabase_delete_project', 'supabase_api', 'supabase_sql',
+  'github_create_repo', 'publish_check', 'publish_connect', 'supabase_setup', 'supabase_schema', 'publish_deploy', 'publish_github',
+]);
+
 export async function executeTool(name, args, ctx) {
   const fn = TOOLS[name];
   if (!fn) {
     return { ok: false, output: `Unknown tool "${name}". Available: ${Object.keys(TOOLS).join(', ')}.` };
   }
 
+  // Design mode only designs: no commands, deploys or messages, and files stay in the design's folder.
+  if (ctx.mode === 'Design') {
+    if (DESIGN_BLOCKED.has(name)) {
+      return { ok: false, output: `Blocked - Design mode only makes designs, so ${name} is not available. When the design is ready, the user can press "Build it in Craft" to make it work.` };
+    }
+    if ((name === 'write_file' || name === 'edit_file' || name === 'fetch_image') && args.path && resolvePath(String(args.path), ctx.cwd).outside) {
+      return { ok: false, output: 'Blocked - in Design mode every file stays inside this design\'s folder. Write it under the design instead (e.g. assets/).' };
+    }
+  }
+
   const planFileWrite = ctx.mode === 'Plan' && (name === 'write_file' || name === 'edit_file') && isPlanPath(args.path, ctx.cwd);
   if (READ_ONLY_MODES.has(ctx.mode) && MUTATING_TOOLS.has(name) && !planFileWrite) {
     return { ok: false, output: `Blocked - ${ctx.mode} mode is read-only, so ${name} is not available. Describe what you would do instead, or tell the user to switch to Build mode.` };