@guildai/cli 0.6.1 → 0.7.0

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/dist/lib/session-polling.js

@@ -46,7 +46,7 @@ export async function pollForResponse(client, sessionId, afterEventId, maxWaitTi
         if (lastAgentRuntimeDone !== null) {
             return { response: lastAgentRuntimeDone, lastEventId: fromId };
         }
-        await new Promise((resolve) => setTimeout(resolve, 500));
+        await new Promise((resolve) => setTimeout(resolve, 2000));
     }
     return { response: null, lastEventId: fromId };
 }

package/dist/lib/version-helpers.d.ts

@@ -0,0 +1,15 @@
+import type { OutputWriter } from './output.js';
+import type { AgentVersion } from './api-types.js';
+/**
+ * Poll until a version's validation completes, then check the result.
+ * Exits the process on timeout or validation failure.
+ * Returns the updated version on success.
+ */
+export declare function waitForValidation(versionId: string, output: OutputWriter): Promise<AgentVersion>;
+/**
+ * Poll until a version's publish completes (PUBLISHING → PUBLISHED).
+ * Exits the process on timeout or failure.
+ * Returns the updated version on success.
+ */
+export declare function waitForPublish(versionId: string, output: OutputWriter): Promise<AgentVersion>;
+//# sourceMappingURL=version-helpers.d.ts.map

package/dist/lib/version-helpers.js

@@ -0,0 +1,83 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import { GuildAPIClient } from './api-client.js';
+import { pollUntilComplete } from './polling.js';
+/**
+ * Poll until a version's validation completes, then check the result.
+ * Exits the process on timeout or validation failure.
+ * Returns the updated version on success.
+ */
+export async function waitForValidation(versionId, output) {
+    const pollResult = await pollUntilComplete({
+        resourceId: versionId,
+        endpoint: `/versions/${versionId}`,
+        isComplete: (response) => response.validation_status !== 'PENDING' &&
+            response.validation_status !== 'RUNNING',
+        message: 'Waiting for validation to complete...',
+        successMessage: 'Validation complete',
+        timeoutMessage: 'Validation timed out',
+        maxAttempts: 120,
+        delayMs: 1000,
+    });
+    if (!pollResult.success || !pollResult.response) {
+        output.error('Validation did not complete in time', 'Check status manually:\n  guild agent versions');
+        process.exit(1);
+    }
+    const version = pollResult.response;
+    if (version.validation_status === 'FAILED') {
+        const details = await fetchValidationFailureDetails(version.id);
+        output.error('Validation failed', details);
+        process.exit(1);
+    }
+    return version;
+}
+/**
+ * Fetch validation step details for a failed version.
+ */
+async function fetchValidationFailureDetails(versionId) {
+    const client = new GuildAPIClient();
+    let failureDetails = '';
+    try {
+        const stepsResponse = await client.get(`/versions/${versionId}/validation/steps`);
+        const failedSteps = stepsResponse.steps.filter((step) => step.status === 'FAILED');
+        if (failedSteps.length > 0) {
+            failureDetails = failedSteps
+                .map((step) => step.content
+                ? `Step "${step.name}" failed: ${step.content}`
+                : `Step "${step.name}" failed`)
+                .join('\n');
+        }
+        else {
+            failureDetails = 'No failed steps found. Check validation logs for details.';
+        }
+    }
+    catch {
+        failureDetails = 'Could not fetch validation details.';
+    }
+    failureDetails +=
+        '\n\nFix the issues, then save a new version:\n  guild agent save --message "Fix validation errors"';
+    return failureDetails;
+}
+/**
+ * Poll until a version's publish completes (PUBLISHING → PUBLISHED).
+ * Exits the process on timeout or failure.
+ * Returns the updated version on success.
+ */
+export async function waitForPublish(versionId, output) {
+    const pollResult = await pollUntilComplete({
+        resourceId: versionId,
+        endpoint: `/versions/${versionId}`,
+        isComplete: (response) => response.status === 'PUBLISHED' || response.status === 'FAILED',
+        message: 'Waiting for publish to complete...',
+        successMessage: 'Published',
+        timeoutMessage: 'Publish timed out',
+        maxAttempts: 60,
+        delayMs: 1000,
+    });
+    if (!pollResult.success || pollResult.response?.status !== 'PUBLISHED') {
+        output.error('Publish did not complete in time', 'Check status manually:\n  guild agent versions');
+        process.exit(1);
+    }
+    return pollResult.response;
+}
+//# sourceMappingURL=version-helpers.js.map

package/dist/mcp/tools.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const POLL_INTERVAL_MS = 500;
+const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 120_000;
 // ---------------------------------------------------------------------------
 // Helpers

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