@guildai/cli 0.6.2 → 0.7.1

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

@@ -54,7 +54,7 @@ export declare function getAgentName(agent: AgentRef | null | undefined): string
  * Check if a task's agent matches a target agent identifier.
  *
  * Target format: "@scope/owner~name" (e.g. "@guildai/guildai~agent-builder") or simple name ("assistant")
- * AgentRef format: { name: "agent-builder", full_name: "guildai/agent-builder", ... }
+ * AgentRef format: { name: "agent-builder", full_name: "guildai~agent-builder", ... }
  */
 export declare function matchesAgent(taskAgent: AgentRef | null | undefined, targetAgent: string): boolean;
 /** Get display name for a task - agent name or tool name */
@@ -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/dist/lib/session-events.js

@@ -41,7 +41,7 @@ export function getAgentName(agent) {
  * Check if a task's agent matches a target agent identifier.
  *
  * Target format: "@scope/owner~name" (e.g. "@guildai/guildai~agent-builder") or simple name ("assistant")
- * AgentRef format: { name: "agent-builder", full_name: "guildai/agent-builder", ... }
+ * AgentRef format: { name: "agent-builder", full_name: "guildai~agent-builder", ... }
  */
 export function matchesAgent(taskAgent, targetAgent) {
     if (!taskAgent)
@@ -49,9 +49,11 @@ export function matchesAgent(taskAgent, targetAgent) {
     // Direct name match for simple identifiers like "assistant"
     if (taskAgent.name === targetAgent)
         return true;
-    // Normalize "@scope/owner~name" -> "owner/name" for full_name comparison
+    // Normalize target to match full_name format:
+    // 1. Strip npm scope prefix: "@scope/owner~name" -> "owner~name"
+    // 2. Convert slash separator to tilde: "owner/name" -> "owner~name"
     if (taskAgent.full_name) {
-        const normalized = targetAgent.replace(/^@[^/]+\//, '').replace('~', '/');
+        const normalized = targetAgent.replace(/^@[^/]+\//, '').replace('/', '~');
         if (taskAgent.full_name === normalized)
             return true;
     }

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

@@ -16,4 +16,12 @@ export interface PollResult {
  * 3. runtime_error from agent tasks — fail fast
  */
 export declare function pollForResponse(client: GuildAPIClient, sessionId: string, afterEventId: string | undefined, maxWaitTime?: number): Promise<PollResult>;
+/**
+ * Poll for agent response while streaming matching events to stdout as JSONL.
+ *
+ * Same completion logic as pollForResponse(), but writes each event that
+ * passes the filter to stdout so callers get intermediate output (console.log,
+ * progress, etc.) in JSON/JSONL automation modes.
+ */
+export declare function pollForResponseWithEvents(client: GuildAPIClient, sessionId: string, eventFilter: Set<string>, afterEventId: string | undefined, maxWaitTime?: number): Promise<PollResult>;
 //# sourceMappingURL=session-polling.d.ts.map

package/dist/lib/session-polling.js

@@ -1,6 +1,7 @@
 // Copyright 2026 Guild.ai
 // SPDX-License-Identifier: Apache-2.0
 import { debug, isDebugMode } from './errors.js';
+import { shouldShowEvent } from './event-filter.js';
 import { fetchEvents } from './session-events-fetch.js';
 /**
  * Poll for agent response using from_id cursor.
@@ -50,4 +51,52 @@ export async function pollForResponse(client, sessionId, afterEventId, maxWaitTi
     }
     return { response: null, lastEventId: fromId };
 }
+/**
+ * Poll for agent response while streaming matching events to stdout as JSONL.
+ *
+ * Same completion logic as pollForResponse(), but writes each event that
+ * passes the filter to stdout so callers get intermediate output (console.log,
+ * progress, etc.) in JSON/JSONL automation modes.
+ */
+export async function pollForResponseWithEvents(client, sessionId, eventFilter, afterEventId, maxWaitTime = 60000) {
+    const startTime = Date.now();
+    let fromId = afterEventId;
+    while (Date.now() - startTime < maxWaitTime) {
+        const events = await fetchEvents(client, sessionId, { fromId });
+        let lastAgentRuntimeDone = null;
+        for (const event of events) {
+            debug(`pollForResponseWithEvents event: ${event.type}`);
+            // Stream matching events to stdout as JSONL
+            if (shouldShowEvent(event.type, eventFilter)) {
+                process.stdout.write(JSON.stringify(event) + '\n');
+            }
+            if (event.type === 'agent_notification_message') {
+                return { response: event.content.data, lastEventId: event.id };
+            }
+            if (event.type === 'runtime_done' &&
+                event.content !== undefined &&
+                event.task &&
+                'agent' in event.task) {
+                lastAgentRuntimeDone = JSON.stringify(event.content);
+            }
+            if (event.type === 'runtime_error' && event.task && 'agent' in event.task) {
+                return {
+                    response: JSON.stringify({ error: event.content }),
+                    lastEventId: event.id,
+                };
+            }
+            if (event.type === 'agent_console' && isDebugMode()) {
+                process.stderr.write(`[console.${event.level}] ${event.content}\n`);
+            }
+        }
+        if (events.length > 0) {
+            fromId = events[events.length - 1].id;
+        }
+        if (lastAgentRuntimeDone !== null) {
+            return { response: lastAgentRuntimeDone, lastEventId: fromId };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+    return { response: null, lastEventId: fromId };
+}
 //# sourceMappingURL=session-polling.js.map

package/dist/lib/spinners.js

@@ -751,7 +751,10 @@ export function getSpinnerThemes() {
  * @deprecated Use createSpinner() instead
  */
 export function getActiveTheme() {
-    return getSpinnerThemes().get('classic');
+    const theme = getSpinnerThemes().get('classic');
+    if (!theme)
+        throw new Error('Missing classic spinner theme');
+    return theme;
 }
 /**
  * @deprecated Use createSpinner() instead

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)`.