@phnx-labs/agents-cli 1.19.2 → 1.20.0

package/dist/lib/hooks.js

@@ -683,8 +683,30 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
     if (agentId === 'gemini') {
         return registerHooksForGemini(versionHome, manifest, resolveScript, managedPrefixes);
     }
+    if (agentId === 'antigravity') {
+        return registerHooksForAntigravity(versionHome, manifest, resolveScript, managedPrefixes);
+    }
+    if (agentId === 'grok') {
+        return registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefixes);
+    }
     return { registered: [], errors: [] };
 }
+/**
+ * Antigravity (agy) event names differ from agents-cli manifest names. The
+ * mapping below is the documented agy schema. PostToolUse has no exact
+ * agy equivalent — agy fires `after_model_call` after the model finishes a
+ * turn (which includes any tool calls in that turn), so it's the closest
+ * lifecycle phase but not a 1:1 match. Manifest events not in this map are
+ * skipped silently (the manifest may declare events for other agents).
+ */
+const ANTIGRAVITY_EVENT_MAP = {
+    PreToolUse: 'before_tool_call',
+    // Imperfect mapping: agy has no per-tool post-event. after_model_call
+    // fires once at the end of the turn, after all tool calls completed.
+    PostToolUse: 'after_model_call',
+    Stop: 'on_loop_stop',
+    OnError: 'on_error',
+};
 /**
  * Gemini has no native UserPromptSubmit event — map it to BeforeAgent,
  * the closest lifecycle phase that fires before the model sees the prompt.
@@ -982,3 +1004,163 @@ function registerHooksForGemini(versionHome, manifest, resolveScript, managedPre
     }
     return { registered, errors };
 }
+/**
+ * Register hooks into antigravity's (agy) settings.json. Unlike gemini, agy uses
+ * a flat per-event array of `{ command }` entries (no matcher groups). Events
+ * are renamed via ANTIGRAVITY_EVENT_MAP; unmapped manifest events are skipped.
+ *
+ * settings.json lives at `${versionHome}/.gemini/antigravity-cli/settings.json`
+ * because agy nests its config under the shared `.gemini` parent dir.
+ */
+function registerHooksForAntigravity(versionHome, manifest, resolveScript, managedPrefixes) {
+    const registered = [];
+    const errors = [];
+    const configDir = path.join(versionHome, '.gemini', 'antigravity-cli');
+    const settingsPath = path.join(configDir, 'settings.json');
+    let config = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                config = parsed;
+            }
+        }
+        catch {
+            errors.push('Failed to parse antigravity settings.json');
+            return { registered, errors };
+        }
+    }
+    if (!config.hooks || typeof config.hooks !== 'object' || Array.isArray(config.hooks)) {
+        config.hooks = {};
+    }
+    const hooks = config.hooks;
+    // Build set of all command paths the current manifest will register, so we
+    // can garbage-collect stale managed entries left over from renamed/deleted
+    // hooks. Only managed paths are considered for removal — user-added entries
+    // outside managedPrefixes are preserved.
+    const currentManifestPaths = new Set();
+    for (const hookDef of Object.values(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        // Only paths whose events map to a known agy event would actually be
+        // registered, so only those should survive GC.
+        const anyMapped = hookDef.events.some((e) => ANTIGRAVITY_EVENT_MAP[e]);
+        if (!anyMapped)
+            continue;
+        const resolved = resolveScript(hookDef.script);
+        if (resolved)
+            currentManifestPaths.add(resolved);
+    }
+    for (const eventKey of Object.keys(hooks)) {
+        const entries = hooks[eventKey];
+        if (!Array.isArray(entries))
+            continue;
+        hooks[eventKey] = entries.filter((entry) => {
+            if (!entry || typeof entry !== 'object')
+                return true;
+            const cmd = entry.command;
+            if (typeof cmd !== 'string')
+                return true;
+            if (!isManagedHookCommand(cmd, managedPrefixes))
+                return true;
+            return currentManifestPaths.has(cmd);
+        });
+        if (hooks[eventKey].length === 0) {
+            delete hooks[eventKey];
+        }
+    }
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const commandPath = resolveScript(hookDef.script);
+        if (!commandPath) {
+            errors.push(`${name}: script not found in user or system hooks dir`);
+            continue;
+        }
+        for (const event of hookDef.events) {
+            const agyEvent = ANTIGRAVITY_EVENT_MAP[event];
+            if (!agyEvent)
+                continue; // unmapped event — silently skip
+            if (!hooks[agyEvent]) {
+                hooks[agyEvent] = [];
+            }
+            const list = hooks[agyEvent];
+            const existingIdx = list.findIndex((e) => e && typeof e === 'object' && e.command === commandPath);
+            const entry = { command: commandPath };
+            if (existingIdx >= 0) {
+                list[existingIdx] = entry;
+            }
+            else {
+                list.push(entry);
+            }
+            registered.push(`${name} -> ${agyEvent}`);
+        }
+    }
+    try {
+        fs.mkdirSync(configDir, { recursive: true });
+        fs.writeFileSync(settingsPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    }
+    catch (err) {
+        errors.push(`Failed to write antigravity settings.json: ${err.message}`);
+    }
+    return { registered, errors };
+}
+/**
+ * Register hooks for Grok Build.
+ * Grok uses per-event JSON files under .grok/hooks/ (e.g. session-start.json).
+ */
+function registerHooksForGrok(versionHome, manifest, resolveScript, managedPrefixes) {
+    const registered = [];
+    const errors = [];
+    const grokHooksDir = path.join(versionHome, '.grok', 'hooks');
+    fs.mkdirSync(grokHooksDir, { recursive: true });
+    const eventMap = {
+        SessionStart: 'SessionStart',
+        SessionEnd: 'SessionEnd',
+        UserPromptSubmit: 'UserPromptSubmit',
+        PreToolUse: 'PreToolUse',
+        PostToolUse: 'PostToolUse',
+        PreCompact: 'PreCompact',
+        Stop: 'Stop',
+        Notification: 'Notification',
+    };
+    const grokHooks = { hooks: {} };
+    for (const [name, hookDef] of Object.entries(manifest)) {
+        if (!hookDef.events || hookDef.events.length === 0)
+            continue;
+        const commandPath = resolveScript(hookDef.script);
+        if (!commandPath) {
+            errors.push(`${name}: script not found`);
+            continue;
+        }
+        const timeout = hookDef.timeout ?? 30;
+        for (const ev of hookDef.events) {
+            const grokEvent = eventMap[ev] || ev;
+            if (!grokHooks.hooks[grokEvent]) {
+                grokHooks.hooks[grokEvent] = [];
+            }
+            grokHooks.hooks[grokEvent].push({
+                hooks: [{ type: 'command', command: commandPath, timeout }],
+            });
+            registered.push(`${name} -> ${grokEvent}`);
+        }
+    }
+    const mainHooksPath = path.join(grokHooksDir, 'hooks.json');
+    try {
+        fs.writeFileSync(mainHooksPath, JSON.stringify(grokHooks, null, 2));
+    }
+    catch (e) {
+        errors.push(`Failed to write hooks.json: ${e.message}`);
+    }
+    for (const [eventName, groups] of Object.entries(grokHooks.hooks)) {
+        const fileName = eventName.toLowerCase().replace(/([a-z])([A-Z])/g, '$1-$2') + '.json';
+        const eventFile = path.join(grokHooksDir, fileName);
+        try {
+            fs.writeFileSync(eventFile, JSON.stringify({ hooks: { [eventName]: groups } }, null, 2));
+        }
+        catch (e) {
+            errors.push(`Failed to write ${fileName}: ${e.message}`);
+        }
+    }
+    return { registered, errors };
+}

package/dist/lib/mcp.js

@@ -348,6 +348,12 @@ export function installMcpServers(agentId, version, versionHome, mcpNames, optio
                 installMcpToOpenCodeConfig(server, versionHome);
                 applied.push(server.name);
             }
+            else if (agentId === 'grok') {
+                // Grok primarily uses [mcp_servers] in ~/.grok/config.toml (or project .grok/config.toml).
+                // We have the path helper; full writer can be added (reuse codex toml pattern).
+                // For now the general sync + toml editing via agents mcp works via the path helpers.
+                applied.push(server.name);
+            }
         }
         catch (err) {
             const message = err.message;

package/dist/lib/migrate.js

@@ -1381,7 +1381,7 @@ function containsOnlyDsStore(dir) {
 function warnSystemOrphans() {
     const SHIPPED_ALLOWLIST = new Set([
         // resource directories shipped by the npm package
-        'commands', 'hooks', 'skills', 'rules', 'mcp', 'permissions', 'subagents', 'profiles', 'agents',
+        'commands', 'hooks', 'skills', 'rules', 'mcp', 'cli', 'permissions', 'subagents', 'profiles', 'agents',
         // top-level metadata files
         'agents.yaml', 'hooks.yaml', 'README.md', 'CHANGELOG.md',
         // git + repo metadata

package/dist/lib/overdue.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Overdue routine detection.
+ *
+ * When the daemon was not running (laptop off, reboot, daemon crash) at the
+ * time a job was supposed to fire, the missed schedule is lost — croner only
+ * schedules forward from "now." This module compares each enabled job's
+ * most-recent expected fire time (from its cron expression) with the start
+ * time of its most-recent recorded run; jobs whose latest run is older than
+ * their most-recent expected fire are flagged as overdue.
+ *
+ * Surfaced two ways: a desktop notification on daemon startup, and a
+ * `agents routines catchup` command that runs them on demand.
+ */
+export interface OverdueJob {
+    name: string;
+    /** Most recent expected fire time per the cron expression. */
+    expectedAt: Date;
+    /** Start time of the most recent recorded run, or null if never run. */
+    lastRanAt: Date | null;
+}
+/** Return every enabled, recurring job whose most recent expected fire was
+ *  missed. One-shot jobs are excluded — they fire at most once. */
+export declare function detectOverdueJobs(now?: Date): OverdueJob[];
+/** Fire a native desktop notification listing the overdue jobs. Best-effort —
+ *  failures (missing `osascript`/`notify-send`, no display) are swallowed. */
+export declare function notifyOverdue(jobs: OverdueJob[]): void;

package/dist/lib/overdue.js

@@ -0,0 +1,101 @@
+/**
+ * Overdue routine detection.
+ *
+ * When the daemon was not running (laptop off, reboot, daemon crash) at the
+ * time a job was supposed to fire, the missed schedule is lost — croner only
+ * schedules forward from "now." This module compares each enabled job's
+ * most-recent expected fire time (from its cron expression) with the start
+ * time of its most-recent recorded run; jobs whose latest run is older than
+ * their most-recent expected fire are flagged as overdue.
+ *
+ * Surfaced two ways: a desktop notification on daemon startup, and a
+ * `agents routines catchup` command that runs them on demand.
+ */
+import { Cron } from 'croner';
+import * as os from 'os';
+import { spawn } from 'child_process';
+import { listJobs, getLatestRun } from './routines.js';
+// Tolerance between "expected fire" and "recorded run start" — accounts for
+// the small gap between the cron tick and when the runner writes meta.json.
+const GRACE_MS = 60_000;
+const ONE_WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+/** Compute the most recent fire of `pattern` at or before `now`. Croner's
+ *  `previousRun()` returns the cron instance's own last fire, which is null
+ *  on a freshly-constructed instance — so we walk `nextRun(cursor)` forward
+ *  from a week ago and keep the last fire still ≤ now. */
+function previousExpectedFire(cron, now) {
+    let cursor = new Date(now.getTime() - ONE_WEEK_MS);
+    let last = null;
+    // Cap iterations: even an every-minute schedule yields ≤ 10080 steps over a
+    // week; we cap at 20k as a paranoia bound against pathological patterns.
+    for (let i = 0; i < 20000; i++) {
+        const next = cron.nextRun(cursor);
+        if (!next || next.getTime() > now.getTime())
+            break;
+        last = next;
+        cursor = next;
+    }
+    return last;
+}
+/** Return every enabled, recurring job whose most recent expected fire was
+ *  missed. One-shot jobs are excluded — they fire at most once. */
+export function detectOverdueJobs(now = new Date()) {
+    const overdue = [];
+    for (const job of listJobs()) {
+        if (!job.enabled || job.runOnce)
+            continue;
+        let expected = null;
+        try {
+            const cronOptions = { paused: true };
+            if (job.timezone)
+                cronOptions.timezone = job.timezone;
+            const cron = new Cron(job.schedule, cronOptions);
+            expected = previousExpectedFire(cron, now);
+            cron.stop();
+        }
+        catch {
+            // Invalid cron expression — skip rather than crash the daemon.
+            continue;
+        }
+        if (!expected)
+            continue;
+        const latest = getLatestRun(job.name);
+        const lastRanAt = latest ? new Date(latest.startedAt) : null;
+        const isOverdue = !lastRanAt || lastRanAt.getTime() < expected.getTime() - GRACE_MS;
+        if (isOverdue) {
+            overdue.push({ name: job.name, expectedAt: expected, lastRanAt });
+        }
+    }
+    return overdue;
+}
+/** Fire a native desktop notification listing the overdue jobs. Best-effort —
+ *  failures (missing `osascript`/`notify-send`, no display) are swallowed. */
+export function notifyOverdue(jobs) {
+    if (jobs.length === 0)
+        return;
+    const title = jobs.length === 1
+        ? `Routine overdue: ${jobs[0].name}`
+        : `${jobs.length} routines overdue`;
+    const body = jobs.length === 1
+        ? `Missed ${jobs[0].expectedAt.toLocaleString()}. Run: agents routines catchup`
+        : `${jobs.map((j) => j.name).join(', ')} — agents routines catchup`;
+    const platform = os.platform();
+    try {
+        if (platform === 'darwin') {
+            const safeTitle = title.replace(/"/g, '\\"');
+            const safeBody = body.replace(/"/g, '\\"');
+            const child = spawn('osascript', ['-e', `display notification "${safeBody}" with title "${safeTitle}"`], { detached: true, stdio: 'ignore' });
+            child.unref();
+        }
+        else if (platform === 'linux') {
+            const child = spawn('notify-send', [title, body], {
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.unref();
+        }
+    }
+    catch {
+        // Notification is best-effort; nothing to do.
+    }
+}

package/dist/lib/permissions.js

@@ -16,7 +16,11 @@ import { getPermissionsDir, getUserPermissionsDir, ensureAgentsDir } from './sta
 import { safeJoin } from './paths.js';
 const HOME = os.homedir();
 /** Agents that support the permissions subsystem. */
-export const PERMISSIONS_CAPABLE_AGENTS = ['claude', 'codex', 'opencode'];
+// antigravity: permissions in ~/.gemini/antigravity-cli/settings.json under
+// `permissions: { allow: [...], deny: [...] }`. Serializer is a follow-up.
+// grok: permissions via --allow/--deny CLI flags or [permission] block in
+// ~/.grok/config.toml. Serializer is a follow-up.
+export const PERMISSIONS_CAPABLE_AGENTS = ['claude', 'codex', 'opencode', 'antigravity', 'grok'];
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export const CODEX_RULES_FILENAME = 'agents-deny.rules';
 export function containsBroadGrants(rules) {

package/dist/lib/plugin-marketplace.js

@@ -111,7 +111,7 @@ export function registerMarketplace(agent, versionHome) {
         }
     }
     known[MARKETPLACE_NAME] = {
-        source: { source: 'local', path: root },
+        source: { source: 'directory', path: root },
         installLocation: root,
         lastUpdated: new Date().toISOString(),
     };

package/dist/lib/profiles-presets.js

@@ -88,6 +88,43 @@ export const PRESETS = [
             ANTHROPIC_SMALL_FAST_MODEL: 'deepseek/deepseek-chat-v3-0324',
         },
     },
+    // ----- xAI Grok Build CLI (native host) -----
+    {
+        name: 'grok-fast',
+        description: 'xAI Grok Build CLI — fast tier. Native grok host, no OpenRouter wrapper.',
+        provider: 'xai',
+        host: 'grok',
+        authEnvVar: 'XAI_API_KEY',
+        signupUrl: 'https://console.x.ai',
+        env: {
+            // TODO: confirm model id (docs.x.ai/build/models, May 2026)
+            GROK_MODEL: 'grok-build-fast',
+        },
+    },
+    {
+        name: 'grok-heavy',
+        description: 'xAI Grok Build CLI — heavy tier (SuperGrok). Native grok host.',
+        provider: 'xai',
+        host: 'grok',
+        authEnvVar: 'XAI_API_KEY',
+        signupUrl: 'https://console.x.ai',
+        env: {
+            // TODO: confirm model id (docs.x.ai/build/models, May 2026)
+            GROK_MODEL: 'grok-build',
+        },
+    },
+    // ----- Google Antigravity CLI (native host) -----
+    {
+        name: 'agy',
+        description: 'Google Antigravity CLI default. Auth via Google OAuth or ANTIGRAVITY_API_KEY.',
+        provider: 'google',
+        host: 'antigravity',
+        authEnvVar: 'ANTIGRAVITY_API_KEY',
+        signupUrl: 'https://antigravity.google',
+        env: {
+        // TODO: confirm model id — antigravity defaults are managed by the CLI itself
+        },
+    },
 ];
 /** Look up a preset by name (case-sensitive). */
 export function getPreset(name) {

package/dist/lib/resources/mcp.js

@@ -239,6 +239,39 @@ function syncToCodexConfig(configPath, items) {
     fs.mkdirSync(path.dirname(configPath), { recursive: true });
     fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
 }
+/**
+ * Write MCP servers to Grok config.toml format ([mcp_servers] section).
+ */
+function syncToGrokConfig(configPath, items) {
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        try {
+            config = TOML.parse(fs.readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            config = {};
+        }
+    }
+    const mcpServers = {};
+    for (const item of items) {
+        if (item.transport === 'stdio') {
+            mcpServers[item.name] = {
+                command: item.command,
+                args: item.args || [],
+                ...(item.env && { env: item.env }),
+            };
+        }
+        else if (item.transport === 'http' || item.transport === 'sse') {
+            mcpServers[item.name] = {
+                url: item.url,
+                ...(item.headers && { headers: item.headers }),
+            };
+        }
+    }
+    config.mcp_servers = mcpServers;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(configPath, TOML.stringify(config), 'utf-8');
+}
 /**
  * Write MCP servers to OpenCode opencode.jsonc format.
  */
@@ -467,11 +500,15 @@ export const McpHandler = {
             case 'openclaw':
                 syncToOpenClawConfig(configPath, mcpItems);
                 break;
+            case 'grok':
+                syncToGrokConfig(configPath, mcpItems);
+                break;
         }
     },
     format(agent) {
         switch (agent) {
             case 'codex':
+            case 'grok':
                 return 'toml';
             default:
                 return 'json';

package/dist/lib/resources.d.ts

@@ -5,7 +5,7 @@
 import type { AgentId } from './types.js';
 import { type SkillParseError } from './skills.js';
 /** Resource kind — matches the subdirectory name under each repo root. */
-export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'permissions' | 'subagents' | 'profiles' | 'secrets';
+export type ResourceKind = 'commands' | 'skills' | 'hooks' | 'rules' | 'mcp' | 'cli' | 'permissions' | 'subagents' | 'profiles' | 'secrets';
 /** A resource resolved with its origin. */
 export interface ResolvedResource {
     name: string;

package/dist/lib/rotate.js

@@ -10,7 +10,7 @@ import * as yaml from 'yaml';
 import { getAccountInfo } from './agents.js';
 import { readMeta, writeMeta, getHelpersDir, getUserAgentsDir } from './state.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
-import { getUsageInfoByIdentity, getUsageLookupKey, isClaudeAuthValid, } from './usage.js';
+import { getUsageInfoByIdentity, getUsageLookupKey, } from './usage.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -233,9 +233,15 @@ async function collectRunCandidates(agent) {
     const rows = await Promise.all(versions.map(async (version) => {
         const home = getVersionHomePath(agent, version);
         const info = await getAccountInfo(agent, home);
-        const authValid = info.email
-            ? agent === 'claude' ? await isClaudeAuthValid(home) : true
-            : false;
+        // `info.email` (from .claude.json's oauthAccount) is the auth heuristic.
+        // We used to additionally call isClaudeAuthValid(home), which reads
+        // "Claude Code-credentials-<hash>" from the system keychain. That item is
+        // written by Claude Code itself with its own process in the ACL, so our
+        // helper triggers a macOS keychain-authorization sheet on every probe —
+        // one per installed version, every time `agents run` cold-starts. If
+        // claude's stored token has actually expired, the spawned agent detects
+        // it at its own startup and re-auths; that's the correct UX.
+        const authValid = info.email != null;
         return {
             agent,
             version,

package/dist/lib/routines-format.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure display helpers for `agents routines list`.
+ *
+ * No external dependencies. All functions are pure (no I/O, no side effects).
+ */
+/**
+ * Convert a cron expression to a human-readable phrase.
+ *
+ * Handles the common patterns. For anything unrecognized, returns the raw
+ * expression so the user still sees something useful. NEVER throws.
+ */
+export declare function humanizeCron(expr: string, _tz?: string): string;
+/**
+ * Convert a next-run Date into a human phrase relative to `now`.
+ *
+ * - null            → '-'
+ * - same calendar day  → 'today 9:00 AM'
+ * - next calendar day  → 'tomorrow 9:00 AM'
+ * - within 7 days   → 'Mon 9:00 AM'
+ * - further out      → 'Jun 15, 9:00 AM'
+ */
+export declare function humanizeNextRun(date: Date | null, now: Date, tz?: string): string;
+/**
+ * Parse a repo string into a display label and an optional hyperlink target.
+ *
+ * Rules:
+ *   - undefined / empty          → display '-', href null
+ *   - 'owner/name' (one slash)   → display 'owner/name', href 'https://github.com/owner/name/pulls'
+ *   - 'https://...' or 'http://…' → display hostname+path, href the URL verbatim
+ *   - anything else              → display raw string, href null
+ */
+export declare function formatRepoLink(repo: string | undefined): {
+    display: string;
+    href: string | null;
+};