@guildai/cli 0.6.2 → 0.7.0

package/dist/commands/setup.js

@@ -11,7 +11,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const packageRoot = path.resolve(__dirname, '..', '..');
 const docsDir = path.join(packageRoot, 'docs');
-const SKILL_FILES = [
+const CLAUDE_SKILL_FILES = [
     {
         src: path.join(docsDir, 'skills', 'agent-dev.md'),
         dest: path.join('.claude', 'skills', 'agent-dev', 'skill.md'),
@@ -22,6 +22,18 @@ const SKILL_FILES = [
         dest: path.join('.claude', 'skills', 'guild-cli-workflow', 'skill.md'),
         label: '.claude/skills/guild-cli-workflow/skill.md',
     },
+    {
+        src: path.join(docsDir, 'skills', 'integrations.md'),
+        dest: path.join('.claude', 'skills', 'integrations', 'skill.md'),
+        label: '.claude/skills/integrations/skill.md',
+    },
+];
+const CODEX_SKILL_FILES = [
+    {
+        src: path.join(docsDir, 'skills', 'codex-agent-dev.md'),
+        dest: path.join('.agents', 'skills', 'guild-agent-dev', 'SKILL.md'),
+        label: '.agents/skills/guild-agent-dev/SKILL.md',
+    },
 ];
 const CLAUDE_MD_TEMPLATE = `# CLAUDE.md
 
@@ -38,6 +50,22 @@ guild agent save --message "Initial version" --wait --publish
 
 See \`.claude/skills/agent-dev/skill.md\` for SDK reference, patterns, and anti-hallucination guide.
 `;
+const AGENTS_MD_TEMPLATE = `# AGENTS.md
+
+## Guild Agent Development
+
+This project uses Guild for agent development. Codex instructions are installed in \`.agents/skills/guild-agent-dev/SKILL.md\`.
+
+### Quick Start
+
+\`\`\`bash
+guild agent init --name my-agent --template LLM
+guild agent test --ephemeral
+guild agent save -A --message "Initial version"
+\`\`\`
+
+Use \`guild doctor\` to check authentication, server connectivity, workspace selection, and git setup.
+`;
 async function fileExists(filePath) {
     try {
         await fs.access(filePath);
@@ -82,21 +110,29 @@ async function setupMcp(options) {
 }
 async function setup(options) {
     const output = createOutputWriter();
-    // Verify source docs exist
-    const docsExist = await fileExists(path.join(docsDir, 'skills', 'agent-dev.md'));
-    if (!docsExist) {
-        output.error('Could not find Guild CLI docs. Reinstall the CLI: npm install -g @guildai/cli');
+    if (options.agentsMd && !options.codex) {
+        output.error('--agents-md requires --codex', 'Create Codex setup files with:\n  guild setup --codex --agents-md');
+        process.exit(1);
+    }
+    if (options.claudeMd && options.codex) {
+        output.error('--claude-md cannot be used with --codex', 'Create Claude setup with:\n  guild setup --claude-md\n\nCreate Codex setup with:\n  guild setup --codex --agents-md');
         process.exit(1);
     }
+    const skillFiles = options.codex ? CODEX_SKILL_FILES : CLAUDE_SKILL_FILES;
+    // Verify source docs exist
+    for (const file of skillFiles) {
+        if (!(await fileExists(file.src))) {
+            output.error('Could not find Guild CLI docs. Reinstall the CLI: npm install -g @guildai/cli');
+            process.exit(1);
+        }
+    }
     output.progress('Setting up Guild CLI skills...');
     output.progress('');
-    // Ensure .claude/skills/ directory exists
-    const skillsDir = path.join(process.cwd(), '.claude', 'skills');
-    await fs.mkdir(skillsDir, { recursive: true });
     let filesCreated = 0;
     let filesSkipped = 0;
+    let codexProjectFilesChanged = false;
     // Copy skill files
-    for (const file of SKILL_FILES) {
+    for (const file of skillFiles) {
         const destPath = path.join(process.cwd(), file.dest);
         const exists = await fileExists(destPath);
         if (exists && !options.force) {
@@ -113,6 +149,9 @@ async function setup(options) {
                 output.success(`Created ${file.label}`);
             }
             filesCreated++;
+            if (options.codex) {
+                codexProjectFilesChanged = true;
+            }
         }
     }
     // Handle --mcp flag
@@ -139,6 +178,21 @@ async function setup(options) {
             filesCreated++;
         }
     }
+    // Handle AGENTS.md template for Codex setup
+    if (options.agentsMd) {
+        const agentsMdPath = path.join(process.cwd(), 'AGENTS.md');
+        const exists = await fileExists(agentsMdPath);
+        if (exists) {
+            output.progress('AGENTS.md already exists (not overwriting)');
+            filesSkipped++;
+        }
+        else {
+            await fs.writeFile(agentsMdPath, AGENTS_MD_TEMPLATE, 'utf-8');
+            output.success('Created AGENTS.md');
+            filesCreated++;
+            codexProjectFilesChanged = true;
+        }
+    }
     // Summary
     output.progress('');
     if (filesCreated > 0 && filesSkipped === 0) {
@@ -155,13 +209,18 @@ async function setup(options) {
     else {
         output.success('Guild CLI skills installed.');
     }
+    if (codexProjectFilesChanged) {
+        output.progress('Restart Codex to pick up the new project instructions.');
+    }
 }
 export function createSetupCommand() {
     const cmd = new Command('setup');
     cmd
-        .description('Set up Guild CLI skills for coding assistants (Claude Code, etc.)')
-        .option('--force', 'Overwrite existing skill files', false)
+        .description('Set up Guild CLI skills for coding assistants (Claude Code, Codex, etc.)')
+        .option('--force', 'Overwrite existing skill files and Guild MCP config', false)
+        .option('--codex', 'Install Codex skill files instead of Claude Code skills', false)
         .option('--claude-md', 'Also create a CLAUDE.md template in the project root', false)
+        .option('--agents-md', 'With --codex, also create an AGENTS.md template in the project root', false)
         .option('--no-mcp', 'Skip MCP server configuration')
         .action(async (options) => {
         await setup(options);

package/dist/index.js

@@ -59,6 +59,7 @@ import { createSessionEventsCommand } from './commands/session/events.js';
 import { createSessionTasksCommand } from './commands/session/tasks.js';
 import { createSessionCreateCommand } from './commands/session/create.js';
 import { createSessionSendCommand } from './commands/session/send.js';
+import { createSessionInterruptCommand } from './commands/session/interrupt.js';
 import { createJobGetCommand } from './commands/job/get.js';
 import { createJobStepGetCommand } from './commands/job/step-get.js';
 import { createConfigListCommand } from './commands/config/list.js';
@@ -276,6 +277,7 @@ sessionCmd.addCommand(createSessionEventsCommand());
 sessionCmd.addCommand(createSessionTasksCommand());
 sessionCmd.addCommand(createSessionCreateCommand());
 sessionCmd.addCommand(createSessionSendCommand());
+sessionCmd.addCommand(createSessionInterruptCommand());
 // Job command group
 const jobCmd = program.command('job').description('Job management');
 jobCmd.addCommand(createJobGetCommand());

package/dist/lib/event-filter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Event type filtering for the CLI `--events` flag.
+ *
+ * Mirrors the web UI's "Filter by type" modal, which groups event types into
+ * two categories: user-facing events (on by default) and system/debug events
+ * (off by default).
+ *
+ * The canonical event type list is generated from the backend EventType enum
+ * (see generated-types.ts). The user/system grouping is a UI concern defined
+ * here and in www/src/components/EventTypeFilters/types.ts.
+ */
+import type { EventType } from './generated-types.js';
+/**
+ * User-facing event types — shown by default (mirrors web UI defaults).
+ */
+export declare const USER_EVENT_TYPES: readonly EventType[];
+/**
+ * System / debug event types — hidden by default (mirrors web UI defaults).
+ */
+export declare const SYSTEM_EVENT_TYPES: readonly EventType[];
+/**
+ * Default active filter: all user-facing types, no system types.
+ */
+export declare const DEFAULT_EVENT_TYPES: Set<string>;
+/**
+ * Parse the value of the `--events` flag into a Set of event type names.
+ *
+ * Whatever you pass replaces the defaults entirely:
+ *  - `none`   → empty set (no event types shown)
+ *  - `user`   → all USER_EVENT_TYPES (same as default)
+ *  - `system` → only SYSTEM_EVENT_TYPES
+ *  - `all`    → both USER_EVENT_TYPES + SYSTEM_EVENT_TYPES
+ *
+ * Comma-separated for fine-grained control:
+ *  - `agent_console,llm_start` → only those two types
+ *  - `user,system` → same as `all`
+ */
+export declare function parseEventFilter(raw: string): Set<string>;
+/**
+ * Check whether an event should be shown given the active filter.
+ *
+ * Returns `true` when the event type is in the filter set.
+ *
+ * Note: certain event types (e.g. `agent_notification_progress`,
+ * `agent_notification_message`) drive core UI state (spinner, chat history)
+ * and are always processed regardless of the filter; only their *display* is
+ * gated here for new/optional event types.
+ */
+export declare function shouldShowEvent(type: string, filter: Set<string>): boolean;
+//# sourceMappingURL=event-filter.d.ts.map

package/dist/lib/event-filter.js

@@ -0,0 +1,91 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * User-facing event types — shown by default (mirrors web UI defaults).
+ */
+export const USER_EVENT_TYPES = [
+    'user_message',
+    'agent_notification_message',
+    'agent_notification_progress',
+    'agent_notification_error',
+    'credentials_request',
+    'agent_install_request',
+    'trigger_message',
+    'system_error',
+];
+/**
+ * System / debug event types — hidden by default (mirrors web UI defaults).
+ */
+export const SYSTEM_EVENT_TYPES = [
+    'agent_console',
+    'runtime_start',
+    'runtime_running',
+    'runtime_waiting',
+    'runtime_error',
+    'runtime_done',
+    'llm_start',
+    'llm_done',
+];
+/**
+ * Default active filter: all user-facing types, no system types.
+ */
+export const DEFAULT_EVENT_TYPES = new Set(USER_EVENT_TYPES);
+/**
+ * Parse the value of the `--events` flag into a Set of event type names.
+ *
+ * Whatever you pass replaces the defaults entirely:
+ *  - `none`   → empty set (no event types shown)
+ *  - `user`   → all USER_EVENT_TYPES (same as default)
+ *  - `system` → only SYSTEM_EVENT_TYPES
+ *  - `all`    → both USER_EVENT_TYPES + SYSTEM_EVENT_TYPES
+ *
+ * Comma-separated for fine-grained control:
+ *  - `agent_console,llm_start` → only those two types
+ *  - `user,system` → same as `all`
+ */
+export function parseEventFilter(raw) {
+    const tokens = raw
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+    // `none` returns an empty set — no event types shown
+    if (tokens.length === 1 && tokens[0] === 'none') {
+        return new Set();
+    }
+    const result = new Set();
+    for (const token of tokens) {
+        switch (token) {
+            case 'all':
+                for (const t of USER_EVENT_TYPES)
+                    result.add(t);
+                for (const t of SYSTEM_EVENT_TYPES)
+                    result.add(t);
+                break;
+            case 'user':
+                for (const t of USER_EVENT_TYPES)
+                    result.add(t);
+                break;
+            case 'system':
+                for (const t of SYSTEM_EVENT_TYPES)
+                    result.add(t);
+                break;
+            default:
+                result.add(token);
+        }
+    }
+    return result;
+}
+/**
+ * Check whether an event should be shown given the active filter.
+ *
+ * Returns `true` when the event type is in the filter set.
+ *
+ * Note: certain event types (e.g. `agent_notification_progress`,
+ * `agent_notification_message`) drive core UI state (spinner, chat history)
+ * and are always processed regardless of the filter; only their *display* is
+ * gated here for new/optional event types.
+ */
+export function shouldShowEvent(type, filter) {
+    return filter.has(type);
+}
+//# sourceMappingURL=event-filter.js.map

package/dist/lib/generated-types.d.ts

@@ -2,4 +2,6 @@ export declare const WEBHOOK_SERVICES: readonly ["AZURE_DEVOPS", "BITBUCKET", "C
 export type WebhookService = (typeof WEBHOOK_SERVICES)[number];
 export declare const TIME_TRIGGER_FREQUENCIES: readonly ["HOURLY", "DAILY", "WEEKLY", "MONTHLY", "CRON"];
 export type TimeTriggerFrequency = (typeof TIME_TRIGGER_FREQUENCIES)[number];
+export declare const EVENT_TYPES: readonly ["user_message", "agent_console", "runtime_start", "runtime_running", "runtime_waiting", "runtime_error", "runtime_done", "credentials_request", "agent_install_request", "agent_notification_message", "agent_notification_progress", "agent_notification_error", "system_error", "trigger_message", "interrupted", "llm_start", "llm_done"];
+export type EventType = (typeof EVENT_TYPES)[number];
 //# sourceMappingURL=generated-types.d.ts.map

package/dist/lib/generated-types.js

@@ -32,4 +32,24 @@ export const TIME_TRIGGER_FREQUENCIES = [
     'MONTHLY',
     'CRON',
 ];
+// Source: python/guildcore/routes/serializers.py -> EventType
+export const EVENT_TYPES = [
+    'user_message',
+    'agent_console',
+    'runtime_start',
+    'runtime_running',
+    'runtime_waiting',
+    'runtime_error',
+    'runtime_done',
+    'credentials_request',
+    'agent_install_request',
+    'agent_notification_message',
+    'agent_notification_progress',
+    'agent_notification_error',
+    'system_error',
+    'trigger_message',
+    'interrupted',
+    'llm_start',
+    'llm_done',
+];
 //# sourceMappingURL=generated-types.js.map

package/dist/lib/session-events.d.ts

@@ -117,6 +117,31 @@ export interface AgentConsoleEvent extends BaseEvent {
     level: 'debug' | 'info' | 'warn' | 'error';
     content: string;
 }
+export interface TriggerMessageEvent extends BaseEvent {
+    type: 'trigger_message';
+    content: {
+        type: 'text';
+        data: string;
+    };
+}
+export interface SystemErrorEvent extends BaseEvent {
+    type: 'system_error';
+    content: {
+        type: 'text';
+        data: string;
+    };
+    details?: Record<string, unknown>;
+}
+export interface LlmStartEvent extends BaseEvent {
+    type: 'llm_start';
+    provider: string;
+    payload: Record<string, unknown>;
+}
+export interface LlmDoneEvent extends BaseEvent {
+    type: 'llm_done';
+    status_code: number;
+    body: string;
+}
 /** Agent info as returned in install request */
 export interface RequestedAgent {
     id: string;
@@ -149,7 +174,7 @@ export interface InterruptedEvent extends BaseEvent {
     interrupted_at: string;
     interrupted_by_id: string;
 }
-export type SessionEvent = UserMessageEvent | RuntimeStartEvent | RuntimeRunningEvent | RuntimeWaitingEvent | RuntimeErrorEvent | RuntimeDoneEvent | AgentNotificationMessageEvent | AgentNotificationProgressEvent | AgentNotificationErrorEvent | AgentConsoleEvent | AgentInstallRequestEvent | CredentialsRequestEvent | InterruptedEvent;
+export type SessionEvent = UserMessageEvent | RuntimeStartEvent | RuntimeRunningEvent | RuntimeWaitingEvent | RuntimeErrorEvent | RuntimeDoneEvent | AgentNotificationMessageEvent | AgentNotificationProgressEvent | AgentNotificationErrorEvent | AgentConsoleEvent | TriggerMessageEvent | SystemErrorEvent | LlmStartEvent | LlmDoneEvent | AgentInstallRequestEvent | CredentialsRequestEvent | InterruptedEvent;
 export interface Session {
     id: string;
     workspace_id?: string;

package/docs/CLI_WORKFLOW.md

@@ -57,11 +57,17 @@ guild agent save --message "Description" --wait --publish
 ### Project Setup
 
 ```bash
-# Install Guild CLI skills for coding assistants (Claude Code, etc.)
+# Install Guild CLI skills for coding assistants (Claude Code, Codex, etc.)
 guild setup
 
 # Also create a CLAUDE.md template
 guild setup --claude-md
+
+# Install Codex skill files
+guild setup --codex
+
+# Also create an AGENTS.md template for Codex
+guild setup --codex --agents-md
 ```
 
 ### Creating Agents

package/docs/DESIGN.md

@@ -188,7 +188,7 @@ Environments are Docker containers managed by GuildCore. The CLI provides a simp
 
 ## Integration with Developer Tools
 
-The CLI integrates with AI coding assistants like Claude Code, Cursor, and others. Run `guild setup` to install Guild skills into your project.
+The CLI integrates with AI coding assistants like Claude Code, Cursor, and others. Run `guild setup` to install Claude Code skills into your project, or `guild setup --codex` to install Codex skills.
 
 The CLI also exposes a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server via `guild mcp`. This gives coding assistants direct access to Guild's API — searching agents, managing workspaces, reading contexts, and starting sessions — without leaving the editor. `guild setup` configures it by default; use `--no-mcp` to skip.
 

package/docs/skills/codex-agent-dev.md

@@ -0,0 +1,155 @@
+---
+name: guild-agent-dev
+description: Use when working on Guild agents with Codex: creating agents, editing agent code, testing with the Guild CLI, saving versions, publishing, debugging sessions, or answering questions about Guild agent development.
+---
+
+# Guild Agent Development
+
+Use the Guild CLI for local agent development. Prefer commands that are scriptable and safe for a coding agent to run.
+
+## First Checks
+
+Before changing an agent, establish the local context:
+
+```bash
+guild --version
+guild auth status
+guild workspace current
+```
+
+If authentication or workspace selection is missing, tell the user the exact command to run:
+
+```bash
+guild auth login
+guild workspace select
+```
+
+## Core Rules
+
+- Use `guild agent init`, `guild agent clone`, `guild agent pull`, `guild agent test`, `guild agent chat`, and `guild agent save` for agent lifecycle work.
+- Do not edit `guild.json`; it is managed by the CLI.
+- Prefer `guild agent save -A --message "..."` instead of raw `git add`, `git commit`, or `git push`.
+- Do not use `git push` directly for agent repositories; use `guild agent save`.
+- Keep edits scoped to the agent files requested by the user.
+- Surface command output that matters, especially validation errors, session links, workspace IDs, and next commands.
+
+## Common Workflows
+
+Create a new agent:
+
+```bash
+mkdir my-agent && cd my-agent
+guild agent init --name my-agent --template LLM
+```
+
+Clone an existing agent:
+
+```bash
+guild agent clone owner/agent-name
+cd agent-name
+```
+
+Sync before editing when collaborating:
+
+```bash
+guild agent pull
+```
+
+Test unsaved local changes:
+
+```bash
+guild agent test --ephemeral
+```
+
+For non-interactive Codex test loops, prefer JSON input:
+
+```bash
+printf '{"type":"text","text":"hello"}\n' | guild agent test --ephemeral --mode json
+```
+
+Send a single message to the agent in the current directory:
+
+```bash
+guild agent chat --ephemeral "Hello"
+```
+
+Save a draft version:
+
+```bash
+guild agent save -A --message "Describe the change"
+```
+
+Save, validate, and publish:
+
+```bash
+guild agent save -A --message "Ready" --wait --publish
+```
+
+## Debugging
+
+If a test fails or stalls:
+
+```bash
+guild doctor
+guild agent versions
+guild session events <session-id>
+guild session tasks <session-id>
+```
+
+Use `--debug` when command output is too sparse:
+
+```bash
+guild --debug agent test --ephemeral
+```
+
+## Agent Code Patterns
+
+LLM agents use a prompt and tools:
+
+```typescript
+import { llmAgent, guildTools } from '@guildai/agents-sdk';
+
+export default llmAgent({
+  description: 'Helps users with Guild workspaces',
+  tools: { ...guildTools },
+  systemPrompt: `You are a helpful Guild workspace assistant.`,
+  mode: 'multi-turn',
+});
+```
+
+Code-first agents call tools through `task.tools`:
+
+```typescript
+'use agent';
+
+import { agent, guildTools, type Task } from '@guildai/agents-sdk';
+import { z } from 'zod';
+
+const tools = { ...guildTools };
+type Tools = typeof tools;
+
+const inputSchema = z.object({
+  type: z.literal('text'),
+  text: z.string(),
+});
+
+const outputSchema = z.object({
+  type: z.literal('text'),
+  text: z.string(),
+});
+
+async function run(input: z.infer<typeof inputSchema>, task: Task<Tools>) {
+  await task.tools.guild_debug_log({ message: input.text });
+  return { type: 'text' as const, text: input.text };
+}
+
+export default agent({
+  description: 'Echoes user text',
+  inputSchema,
+  outputSchema,
+  tools,
+  run,
+});
+```
+
+All tool calls go through `task.tools.<toolName>(args)`.