codeply-cli 0.4.0 → 0.5.0

package/lib/native-tools.mjs

@@ -33,7 +33,7 @@ export const TOOL_DOCS = {
   fetch_image: { d: 'Download an image into the project.', req: ['url', 'path'], p: { url: 'Image URL.', path: 'Where to save it, e.g. assets/hero.jpg.' } },
   browser_check: { d: 'Open a page in a real browser and get errors plus a screenshot.', req: ['url'], p: { url: 'file:///absolute/path or http://localhost:port.', wait: 'Extra milliseconds to wait before capturing.', viewport: 'desktop (default), tablet, mobile, or WIDTHxHEIGHT.' } },
   gmail_send: { d: 'Send a real email now (no drafts). Only when the user asked for it.', req: ['to', 'subject', 'body'], p: { to: 'Recipient address.', subject: 'Subject line.', body: 'Plain-text body.' } },
-  gmail_search: { d: 'Search the connected Gmail account.', req: ['query'], p: { query: 'Gmail search syntax.' } },
+  gmail_search: { d: 'Search the connected Gmail account. Leave query empty to list the newest mail.', req: [], p: { query: 'Gmail search syntax, e.g. "is:unread" or "from:x@y.com". Empty = newest mail.' } },
   slack_post_message: { d: 'Post a real Slack message now. Only when the user asked for it.', req: ['channel', 'text'], p: { channel: 'Channel name or id.', text: 'Message text.' } },
   vercel_deploy: { d: 'Deploy a folder to the connected Vercel account (live, real).', req: [], p: { path: 'Folder to deploy. Default ".".' } },
   supabase_create_project: { d: 'Create a new Supabase project (billable, real).', req: ['name'], p: { name: 'Project name.' } },
@@ -50,6 +50,7 @@ export const TOOL_DOCS = {
   lsp: { d: 'Code navigation for TypeScript/JavaScript: find the real definition or every reference of a symbol, hover for its type, outline a file, or search symbols.', req: ['operation'], p: { operation: 'definition, references, implementation, hover, documentSymbol or workspaceSymbol.', path: 'File the symbol is in (not needed for workspaceSymbol).', line: '1-based line of the symbol.', character: '1-based column of the symbol (or give symbol instead).', symbol: 'The name on that line, e.g. fetchUser.', query: 'For workspaceSymbol: the name to look for.' } },
   plan_exit: { d: 'Plan mode only. Call after the plan file is written: asks the user whether to switch to Build mode and start implementing.', req: [], p: { path: 'The plan file, e.g. .codeply/plans/add-login.md. Default: the newest plan file.' } },
   plan_enter: { d: 'Build mode only. Ask the user to switch to Plan mode first, for a large or ambiguous task. Use sparingly.', req: [], p: { reason: 'Why planning first would help, one sentence.' } },
+  ask_bot: { d: 'Hand one task to a teammate bot from the TEAM or BOTS list and wait for its result. Only one bot runs at a time.', req: ['bot', 'task'], p: { bot: 'The bot\'s name.', task: 'The one task, with all the context it needs (it sees nothing else).' } },
   mcp: { d: 'Call a tool on a connected MCP server.', req: ['server', 'tool'], p: { server: 'Server name from MCP SERVERS.', tool: 'Tool name on that server.', args: 'JSON object of the tool\'s arguments.' } },
 };
 

package/lib/oauth-connectors.js

@@ -55,8 +55,19 @@ async function refreshGmailToken(clientId, clientSecret, refreshToken) {
       refresh_token: refreshToken, grant_type: 'refresh_token',
     }),
   });
-  const body = await res.json();
-  if (!res.ok) throw new Error(body.error_description || body.error || `Gmail token refresh failed (HTTP ${res.status})`);
+  const body = await readJson(res);
+  if (!res.ok) {
+    // invalid_grant (Google's description is just "Bad Request") means the
+    // refresh token is dead: revoked, or expired because the OAuth app is
+    // still in Testing mode, where Google drops refresh tokens after 7 days.
+    // Only a fresh sign-in fixes it, so say that instead of "Bad Request".
+    if (body.error === 'invalid_grant') {
+      const e = new Error('The Gmail sign-in has expired or was revoked, so Craft disconnected it. Reconnect Gmail in Connect Apps (account menu → Connect Apps), then try again.');
+      e.code = 'invalid_grant';
+      throw e;
+    }
+    throw new Error(`Gmail token refresh failed (HTTP ${res.status}, ${body.error || 'error'}): ${body.error_description || 'no details from Google'}`);
+  }
   return body; // { access_token, expires_in, ... } - no new refresh_token on refresh
 }
 
@@ -64,11 +75,38 @@ async function getGmailProfile(accessToken) {
   const res = await fetch('https://www.googleapis.com/gmail/v1/users/me/profile', {
     headers: { Authorization: `Bearer ${accessToken}` },
   });
-  const body = await res.json();
-  if (!res.ok) throw new Error(body.error?.message || `Gmail profile lookup failed (HTTP ${res.status})`);
+  const body = await readJson(res);
+  if (!res.ok) throw gmailError(body, res.status, 'Gmail profile lookup');
   return body.emailAddress;
 }
 
+/**
+ * Google's bare error.message is often just "Bad Request", which tells the
+ * agent (and the user) nothing. Pull the status, the machine reason and the
+ * per-error message so the real cause shows, with a plain-words hint for the
+ * ones that need the user to act.
+ */
+function gmailError(data, status, what) {
+  const err = (data && data.error) || {};
+  const first = Array.isArray(err.errors) && err.errors[0] ? err.errors[0] : {};
+  const reason = first.reason || err.status || '';
+  const detail = [err.message, first.message].filter((m, i, a) => m && a.indexOf(m) === i).join(': ');
+  let hint = '';
+  if (status === 401) hint = ' The Gmail sign-in expired or was revoked. Reconnect Gmail in Connect Apps.';
+  else if (status === 403 && /scope|insufficient/i.test(detail + reason)) hint = ' Gmail was connected without read access. Reconnect Gmail in Connect Apps and allow all requested permissions.';
+  else if (status === 403 && /accessNotConfigured|SERVICE_DISABLED|has not been used/i.test(detail + reason)) hint = ' The Gmail API is not enabled on the Google Cloud project behind this app.';
+  else if (/failedPrecondition|FAILED_PRECONDITION/i.test(reason)) hint = ' Google says this account has no usable Gmail mailbox for this app (Gmail turned off, or the account is not a test user of the app). Reconnect Gmail in Connect Apps with the right account.';
+  else if (status === 400) hint = ' Reconnecting Gmail in Connect Apps usually fixes this.';
+  const e = new Error(`${what} failed (HTTP ${status}${reason ? `, ${reason}` : ''}): ${detail || 'no details from Google'}.${hint}`);
+  e.status = status;
+  return e;
+}
+
+async function readJson(res) {
+  const text = await res.text();
+  try { return JSON.parse(text); } catch { return { error: { message: text.slice(0, 200) } }; }
+}
+
 function base64UrlEncode(str) {
   return Buffer.from(str, 'utf8').toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
@@ -80,18 +118,22 @@ async function gmailSend(accessToken, { to, subject, body }) {
     headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
     body: JSON.stringify({ raw }),
   });
-  const data = await res.json();
-  if (!res.ok) throw new Error(data.error?.message || `Gmail send failed (HTTP ${res.status})`);
+  const data = await readJson(res);
+  if (!res.ok) throw gmailError(data, res.status, 'Gmail send');
   return data; // { id, threadId, ... }
 }
 
 async function gmailSearch(accessToken, query, maxResults = 10) {
-  const params = new URLSearchParams({ q: query, maxResults: String(maxResults) });
+  // "*" and "" mean "everything" to a person but are not Gmail syntax; an
+  // empty q simply lists the newest mail, which is what they meant.
+  const q = String(query || '').trim();
+  const params = new URLSearchParams({ maxResults: String(maxResults) });
+  if (q && q !== '*' && q !== '""' && q !== "''") params.set('q', q);
   const res = await fetch(`https://www.googleapis.com/gmail/v1/users/me/messages?${params}`, {
     headers: { Authorization: `Bearer ${accessToken}` },
   });
-  const list = await res.json();
-  if (!res.ok) throw new Error(list.error?.message || `Gmail search failed (HTTP ${res.status})`);
+  const list = await readJson(res);
+  if (!res.ok) throw gmailError(list, res.status, 'Gmail search');
   if (!list.messages?.length) return [];
   // The list endpoint only returns bare ids - each result needs its own
   // fetch for subject/from/snippet, capped by maxResults so a broad query

package/lib/tools.mjs

@@ -695,12 +695,20 @@ async function fetch_image(args, ctx) {
  * "expired 4 minutes ago" and "expires in 4 minutes" both need the same
  * refresh anyway and there's no benefit to waiting for the failure first.
  */
-async function getValidGmailToken() {
+async function getValidGmailToken({ force = false } = {}) {
   const gmail = config.getIntegration('gmail');
   if (!gmail.accessToken) return null;
-  if (gmail.expiresAt && Date.now() < gmail.expiresAt - 60000) return gmail.accessToken;
+  if (!force && gmail.expiresAt && Date.now() < gmail.expiresAt - 60000) return gmail.accessToken;
   if (!gmail.refreshToken) return gmail.accessToken; // nothing to refresh with - let the call itself fail if it's actually expired
-  const refreshed = await oauth.refreshGmailToken(gmail.clientId, gmail.clientSecret, gmail.refreshToken);
+  let refreshed;
+  try {
+    refreshed = await oauth.refreshGmailToken(gmail.clientId, gmail.clientSecret, gmail.refreshToken);
+  } catch (e) {
+    // A dead refresh token never comes back: drop it so Connect Apps shows
+    // Gmail as disconnected instead of "connected" but failing every call.
+    if (e.code === 'invalid_grant') config.disconnectIntegration('gmail');
+    throw e;
+  }
   config.saveIntegration('gmail', { accessToken: refreshed.access_token, expiresAt: Date.now() + (refreshed.expires_in || 3600) * 1000 });
   return refreshed.access_token;
 }
@@ -712,7 +720,8 @@ async function gmail_send(args, ctx) {
   if (!to) return { ok: false, output: 'gmail_send needs a <to> address.' };
   if (!subject) return { ok: false, output: 'gmail_send needs a <subject>.' };
 
-  const token = await getValidGmailToken();
+  let token;
+  try { token = await getValidGmailToken(); } catch (e) { return { ok: false, output: `Gmail send failed: ${e.message}` }; }
   if (!token) return { ok: false, output: 'Gmail is not connected. Ask the user to connect it from Connect Apps (account menu → Connect Apps) first.' };
 
   const verdict = await ctx.approve({
@@ -733,18 +742,26 @@ async function gmail_send(args, ctx) {
 
 async function gmail_search(args, ctx) {
   const query = (args.query || '').trim();
-  if (!query) return { ok: false, output: 'gmail_search needs a <query> (Gmail search syntax, e.g. "from:x@y.com is:unread").' };
-
-  const token = await getValidGmailToken();
-  if (!token) return { ok: false, output: 'Gmail is not connected. Ask the user to connect it from Connect Apps (account menu → Connect Apps) first.' };
+  // An empty query is fine: it lists the newest mail ("check my emails").
+  const label = query || 'newest mail';
 
   try {
-    const results = await oauth.gmailSearch(token, query);
-    if (!results.length) return { ok: true, output: `No messages matched "${query}".`, meta: { label: query } };
+    let token = await getValidGmailToken();
+    if (!token) return { ok: false, output: 'Gmail is not connected. Ask the user to connect it from Connect Apps (account menu → Connect Apps) first.' };
+    let results;
+    try {
+      results = await oauth.gmailSearch(token, query);
+    } catch (e) {
+      // A token Google already dropped looks valid by our clock; refresh once and retry.
+      if (e.status !== 401) throw e;
+      token = await getValidGmailToken({ force: true });
+      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) matching "${query}":\n\n${lines.join('\n')}`, meta: { label: query, count: results.length } };
+    return { ok: true, output: `${results.length} message(s)${query ? ` matching "${query}"` : ', newest first'}:\n\n${lines.join('\n')}`, meta: { label, count: results.length } };
   } catch (e) {
-    return { ok: false, output: `Gmail search failed: ${e.message}` };
+    return { ok: false, output: `Gmail search failed: ${e.message} Do not retry with other queries; tell the user this exact error.` };
   }
 }
 
@@ -1924,8 +1941,18 @@ async function plan_enter(args, ctx) {
   return { ok: true, output: 'The user wants to keep building. Carry on in Build mode.', meta: { label: 'plan' } };
 }
 
+// Hand one task to another bot (lib/bots.js). The host provides ctx.askBot,
+// which runs that bot to completion, one agent at a time, and returns its result.
+async function ask_bot(args, ctx) {
+  if (typeof ctx.askBot !== 'function') {
+    return { ok: false, output: 'ask_bot is not available here (no bots, or this run cannot delegate any further). Do the work yourself.' };
+  }
+  return ctx.askBot({ name: String(args.bot || '').trim(), task: String(args.task || '').trim(), signal: ctx.signal });
+}
+
 export const TOOLS = {
   todo,
+  ask_bot,
   ask_user,
   mcp,
   web_fetch, web_search, apply_patch, plan_exit, plan_enter, lsp,
@@ -1944,6 +1971,7 @@ export const TOOL_NEEDS_APPROVAL = new Set(['write_file', 'edit_file', 'apply_pa
 export const TOOL_DISPLAY = {
   todo:       { verb: 'plan',   icon: '☐' },
   ask_user:   { verb: 'ask',    icon: '?' },
+  ask_bot:    { verb: 'asked',  icon: '◉' },
   mcp:        { verb: 'mcp',    icon: '⧉' },
   web_fetch:  { verb: 'fetch',  icon: '⇩' },
   web_search: { verb: 'web',    icon: '▸' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeply-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Codeply from the terminal: an interactive AI coding agent, a local server (codeply serve), and a GitHub agent that runs in your own Actions runner.",
   "main": "bin/codeply.js",
   "bin": {