@guildai/cli 0.5.3 → 0.5.4

package/docs/getting-started.md

@@ -1,440 +0,0 @@
-# Building Agents with the Guild CLI
-
-## Prerequisites
-
-Before you begin, make sure you have:
-
-- **Node.js 18+** and **npm** — [nodejs.org](https://nodejs.org)
-- **A Guild account** — Guild.ai is in closed beta. Request an invitation at hello@guild.ai
-
-## Install the CLI
-
-```bash
-npm install -g @guildai/cli
-```
-
-Then authenticate with Guild:
-
-```bash
-guild auth login
-```
-
-This opens your browser to complete sign-in at [app.guild.ai](https://app.guild.ai). It also configures your local npm registry so the CLI can install Guild packages.
-
-Verify everything is working:
-
-```bash
-guild auth status
-# ✓ Authenticated
-```
-
-Then select your default workspace:
-
-```bash
-guild workspace select
-```
-
-If you have one workspace, it's selected automatically. If you have several, pick one from the list. This tells the CLI where to run agent tests and chat sessions.
-
-If you run into issues, see [Troubleshooting](#troubleshooting) below.
-
-### Set up coding assistant skills (optional)
-
-If you use Claude Code or another coding assistant, install Guild CLI skills into your project:
-
-```bash
-guild setup
-```
-
-This deposits SDK reference and CLI workflow docs into `.claude/skills/` so your coding assistant understands Guild agent development patterns.
-
-## Hello World
-
-Let's create a simple agent that greets users.
-
-### 1. Create the agent
-
-```bash
-mkdir hello-agent && cd hello-agent
-guild agent init --name hello-agent --template LLM
-```
-
-This creates the agent in the Guild backend, initializes a local git repo, and pulls starter files:
-
-```
-hello-agent/
-├── agent.ts          # Your agent code (edit this)
-├── package.json      # Dependencies (runtime packages are pre-configured)
-├── tsconfig.json     # TypeScript config
-├── guild.json        # Local config (managed by the CLI, don't edit)
-└── .gitignore
-```
-
-### 2. Edit the agent
-
-Open `agent.ts` and replace the contents:
-
-```typescript
-import { llmAgent, guildTools, userInterfaceTools } from '@guildai/agents-sdk';
-
-export default llmAgent({
-  description: 'A friendly greeting agent',
-  tools: { ...guildTools, ...userInterfaceTools },
-  systemPrompt: `You are a friendly assistant. Greet users warmly and answer their questions.`,
-  mode: 'multi-turn',
-});
-```
-
-### 3. Test it
-
-```bash
-guild agent test --ephemeral
-```
-
-This opens an interactive chat session. Type a message and press Enter:
-
-```
-You: Hello!
-Agent: Hello! Welcome — I'm happy to help. What can I do for you today?
-```
-
-Press `Ctrl+C` to exit.
-
-### 4. Save and publish
-
-```bash
-guild agent save -A --message "First version" --wait --publish
-```
-
-- `-A` stages and commits all changes before pushing
-- `--wait` blocks until validation passes
-- `--publish` makes the agent available in the Guild catalog
-
-Check status:
-
-```bash
-guild agent get
-guild agent versions
-```
-
-That's it — your first agent is live.
-
-## Installing Skills
-
-If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code), install Guild CLI skills into your project:
-
-```bash
-guild setup
-```
-
-This deposits SDK reference and CLI workflow docs into `.claude/skills/` so Claude Code understands Guild agent development patterns. Support for other coding assistants is coming soon.
-
-## Create an Agent
-
-If you skipped the Hello World, here's the quick version:
-
-```bash
-mkdir my-agent && cd my-agent
-guild agent init
-```
-
-The CLI will prompt for a name and template. Or skip the prompts:
-
-```bash
-guild agent init --name my-agent --template LLM
-```
-
-### Templates
-
-| Template             | Use when                                                             |
-| -------------------- | -------------------------------------------------------------------- |
-| `LLM`                | The LLM is the logic. You write a prompt and pick tools. Start here. |
-| `AUTO_MANAGED_STATE` | You write procedural TypeScript that calls tools inline.             |
-| `BLANK`              | You want full control over the agent lifecycle.                      |
-
-## Write Your Agent
-
-Edit `agent.ts`. The template gives you a working starting point — modify it to fit your use case.
-
-### LLM Agent
-
-Define a system prompt and the tools the LLM can use. No procedural code needed.
-
-```typescript
-import { llmAgent, guildTools, userInterfaceTools } from '@guildai/agents-sdk';
-import { gitHubTools } from '@guildai-services/guildai~github';
-
-export default llmAgent({
-  description: 'Answers questions about GitHub repositories',
-  tools: { ...gitHubTools, ...guildTools, ...userInterfaceTools },
-  systemPrompt: `You help users understand their GitHub repositories.
-Use the GitHub tools to look up real data when asked.`,
-  mode: 'multi-turn',
-});
-```
-
-`mode: "multi-turn"` keeps the conversation going after each response. Use `"one-shot"` (default) when the agent should respond once and finish.
-
-### Code-First Agent
-
-Write TypeScript that calls tools directly. The runtime manages state between tool calls via continuations. Requires the `"use agent"` directive at the top of the file.
-
-```typescript
-'use agent';
-
-import { agent, guildTools, userInterfaceTools, type Task } from '@guildai/agents-sdk';
-import { gitHubTools } from '@guildai-services/guildai~github';
-import { z } from 'zod';
-
-const tools = { ...gitHubTools, ...guildTools, ...userInterfaceTools };
-type Tools = typeof tools;
-
-const inputSchema = z.object({
-  type: z.literal('text'),
-  text: z.string().describe('Repository in owner/repo format'),
-});
-
-const outputSchema = z.object({
-  type: z.literal('text'),
-  text: z.string(),
-});
-
-async function run(input: z.infer<typeof inputSchema>, task: Task<Tools>) {
-  const prs = await task.tools.github_search_issues_and_pull_requests({
-    q: `is:pr is:open repo:${input.text}`,
-    per_page: 10,
-  });
-
-  if (!prs.items?.length) {
-    return { type: 'text' as const, text: 'No open PRs.' };
-  }
-
-  const summary = prs.items.map((pr) => `- #${pr.number}: ${pr.title}`).join('\n');
-
-  return { type: 'text' as const, text: summary };
-}
-
-export default agent({
-  description: 'Lists open PRs in a GitHub repo',
-  inputSchema,
-  outputSchema,
-  tools,
-  run,
-});
-```
-
-### Tools Overview
-
-Every agent has access to three categories of tools:
-
-- **Service tools** (e.g., `gitHubTools`, `slackTools`) — call third-party APIs. When a user first triggers a service tool, Guild prompts them to connect their account via OAuth.
-- **`guildTools`** — query the Guild platform (look up agents, workspaces, sessions, triggers).
-- **`userInterfaceTools`** — interact with the user during a session (ask questions, send progress updates).
-
-All tool calls go through `task.tools`:
-
-```typescript
-// Service tools
-const pr = await task.tools.github_pulls_get({ owner, repo, pull_number: 42 });
-await task.tools.slack_chat_post_message({ channel: 'C123', text: 'PR merged' });
-
-// User interface tools
-const answer = await task.tools.ui_prompt({ type: 'text', text: 'Which repo?' });
-```
-
-## Available Services
-
-Import service tools from their packages. These are provided by the runtime — don't add them to `package.json`.
-
-| Service      | Import                                                                      |
-| ------------ | --------------------------------------------------------------------------- |
-| GitHub       | `import { gitHubTools } from "@guildai-services/guildai~github"`            |
-| Slack        | `import { slackTools } from "@guildai-services/guildai~slack"`              |
-| Jira         | `import { jiraTools } from "@guildai-services/guildai~jira"`                |
-| Bitbucket    | `import { bitbucketTools } from "@guildai-services/guildai~bitbucket"`      |
-| Azure DevOps | `import { azureDevOpsTools } from "@guildai-services/guildai~azure-devops"` |
-
-## Available Models
-
-Guild agents can use the following LLM providers and models:
-
-| Provider  | Models                            |
-| --------- | --------------------------------- |
-| Anthropic | Claude Sonnet 4, Claude Haiku 3.5 |
-| OpenAI    | GPT-4o, GPT-4o mini               |
-| Google    | Gemini 2.0 Flash                  |
-
-Model selection is handled by the runtime. LLM agents use the platform's default model unless configured otherwise.
-
-## Development Loop
-
-The typical workflow is: pull → edit → test → save.
-
-### 1. Pull latest changes
-
-If others are working on the same agent, pull their changes first:
-
-```bash
-guild agent pull
-```
-
-This pulls git commits and also checks for unpublished changes made via the web editor. If someone edited the agent in the UI, pull downloads those files automatically.
-
-### 2. Test locally
-
-```bash
-guild agent test              # Interactive chat session
-guild agent chat "Hello"      # Send a single message
-```
-
-`guild agent test` opens an interactive session where you can chat with your agent. Changes to `agent.ts` take effect on the next save — you don't need to restart.
-
-### 3. Save your work
-
-Commit with git, then push via Guild:
-
-```bash
-git add . && git commit -m "Add Slack notifications"
-guild agent save
-```
-
-Or stage+commit+push in one step:
-
-```bash
-guild agent save -A --message "Add Slack notifications"
-```
-
-This pushes your commits and creates a new version in the Guild backend. Versions start as drafts.
-
-### 4. Publish
-
-```bash
-guild agent save -A --message "Ready to ship" --wait --publish
-```
-
-`--wait` blocks until validation passes. `--publish` makes the agent available in the catalog. You can also publish separately:
-
-```bash
-guild agent publish
-```
-
-### Check status
-
-```bash
-guild agent get                # Agent info and current version
-guild agent versions           # Version history
-guild agent code               # View source of latest version
-```
-
-## Key Rules
-
-- Agent code lives in `agent.ts` (typically at the project root, but can be in a subdirectory like `src/`).
-- Don't add `@guildai/agents-sdk`, `zod`, or `@guildai-services/*` to `package.json`. The runtime provides them. Only add third-party packages you actually use.
-- Always call tools through `task.tools.<name>(args)`. Never access services directly.
-- Use `git add` and `git commit` to manage your working tree. Use `guild agent save` to push and create versions. Don't use `git push` directly (a pre-push hook blocks it).
-- Don't edit `guild.json` — it's managed by the CLI.
-
-## Other Commands
-
-```bash
-guild agent clone owner/agent-name    # Clone an existing agent to work on locally
-guild agent init --fork owner/name    # Fork an agent as a starting point
-guild agent pull                      # Pull remote changes into local directory
-guild agent unpublish                 # Remove from catalog
-guild agent revalidate                # Re-run validation on latest version
-```
-
-## Diagnostics
-
-Run `guild doctor` to check your setup:
-
-```bash
-guild doctor
-```
-
-```
-Checking Guild CLI setup...
-
-  ✓ Authentication       Logged in
-  ✓ Server               Connected to https://app.guild.ai/api (125ms)
-  ✓ Global config        ~/.guild/config.json
-  ✓ Default workspace    my-workspace
-  - Local config         Not in an agent directory
-  ✓ Git                  Installed
-
-5 passed, 0 failed, 1 skipped
-```
-
-## Troubleshooting
-
-### "Connection refused" or "Cannot connect to server"
-
-1. Check your internet connection
-2. Run `guild doctor` to see which check is failing
-
-### "Workspace not found" or wrong workspace
-
-Your default workspace may not match the target server. Override with an environment variable:
-
-```bash
-GUILD_WORKSPACE_ID=<workspace-id> guild chat "hello"
-```
-
-Or set a new default:
-
-```bash
-guild workspace select
-```
-
-### "Not authenticated" from Guild CLI
-
-Run `guild auth login` to re-authenticate:
-
-```bash
-guild auth login
-guild auth status
-```
-
-### "No agent ID provided and not in an agent directory"
-
-You need to either run the command from inside an agent directory (one with a `guild.json` file), or pass the agent ID explicitly:
-
-```bash
-# Option 1: cd into the agent directory
-cd my-agent
-guild agent get
-
-# Option 2: pass the agent ID
-guild agent get <agent-id>
-```
-
-### "No changes to save"
-
-Working tree is clean and there are no unpushed commits. Make a code change, commit it, then run `guild agent save` again. If a previous save committed locally but failed to push (e.g., network error), just run `guild agent save` again — it detects the unpushed commits and resumes.
-
-### Validation failures
-
-After saving, if validation fails:
-
-```bash
-# Check the latest version for errors
-guild agent versions --limit 1
-
-# Fix the issue, commit, and save again
-git add . && git commit -m "Fix validation error"
-guild agent save --wait
-```
-
-### Agent test not responding
-
-If `guild agent test` hangs or produces no output:
-
-1. Check your agent code compiles: look for TypeScript errors in `agent.ts`
-2. Make sure you've saved at least once: `guild agent save -A --message "initial"`
-3. Try a single message instead: `guild agent chat "hello"`
-
-## Next Steps
-
-- Browse agents at [app.guild.ai/agents](https://app.guild.ai/agents)
-- Fork an existing agent: `guild agent init --fork owner/agent-name`
-- Clone one to study: `guild agent clone owner/agent-name`

package/docs/output-format.md

@@ -1,126 +0,0 @@
-# Output Format Design
-
-## Global Flags
-
-**`--json`** - Machine-readable JSON output
-
-- Explicit opt-in (not auto-detected from pipes)
-- Non-interactive mode
-- Pure JSON to stdout
-- Errors go to stderr as JSON
-
-**`--quiet` / `-q`** - Suppress progress messages
-
-- Keeps errors
-- Hides progress spinners and status updates
-- Works in both human and JSON modes
-
-## Output Streams
-
-**stdout** - Structured data
-
-- Command results
-- Lists, objects, values
-- Always parseable
-
-**stderr** - Messages
-
-- Progress updates
-- Status information
-- Errors
-- Suppressible with `--quiet`
-
-## Implementation
-
-The output system uses an `OutputWriter` interface:
-
-```typescript
-interface OutputWriter {
-  data(value: unknown): void;
-  success(message: string, details?: Record<string, unknown>): void;
-  error(message: string, details?: string): void;
-  progress(message: string): void;
-  spinner(message: string): Spinner;
-}
-```
-
-Two implementations:
-
-- `InteractiveOutputWriter` - Colors, symbols, formatted output
-- `JSONOutputWriter` - Pure JSON
-
-Commands use `createOutputWriter()` to get the right implementation based on flags.
-
-## Flag Checking
-
-```typescript
-// src/lib/output-mode.ts
-export function getOutputMode(): OutputMode {
-  if (process.argv.includes('--json')) return 'json';
-  return 'human';
-}
-
-export function isQuietMode(): boolean {
-  return process.argv.includes('--quiet') || process.argv.includes('-q');
-}
-```
-
-Just checks for `--json` flag. No pipe detection or environment inspection.
-
-## Command Patterns
-
-**Data commands** (list, get, etc.):
-
-- Output JSON by default
-- `--json` flag has no effect (already JSON)
-- Use for automation and scripting
-
-**Interactive commands** (chat, test REPL):
-
-- Human-friendly by default
-- `--mode=json` specifies JSON input/output format (for chat/agent commands)
-- `--once` controls interactivity (one-shot vs continuous)
-- Chat provides human-readable formatting by default
-
-## Examples
-
-```bash
-# Data command - JSON by default
-guild agent list
-# {"agents": [...], "pagination": {...}}
-
-# Interactive command - human-friendly
-guild chat
-# [colored output, prompts, spinners]
-
-# One-shot mode - human-readable (default)
-guild chat --once "hello"
-# Hello! How can I help you today?
-
-# One-shot mode - JSON output
-echo '{"prompt": "hello"}' | guild chat --once --mode=json
-# {"session_id": "...", "events": [...]}
-
-# Suppress progress messages
-guild agent create my-agent --quiet
-# Only shows result, no progress updates
-```
-
-## Design Decisions
-
-**No pipe auto-detection**: Explicit `--json` required. Prevents accidental format switching.
-
-**Separate streams**: Data to stdout, messages to stderr. Clean separation for piping.
-
-**JSON by default for data**: `agent list`, `workspace list`, etc. output JSON. The `guild chat` interface provides human-readable interaction.
-
-**Quiet mode independent**: Works with both human and JSON modes. Suppresses progress, keeps errors.
-
-## Hyperlinks
-
-Table cells for entity names and IDs are wrapped in [OSC8 terminal hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) that link to the corresponding dashboard pages. In supported terminals (iTerm2, VS Code Terminal, Windows Terminal), these cells are clickable.
-
-**Environment controls:**
-
-- `FORCE_HYPERLINK=1` — Force hyperlinks in non-TTY environments
-- `FORCE_HYPERLINK=0` — Disable hyperlinks entirely

package/docs/session-events.md

@@ -1,143 +0,0 @@
-# Session Events Architecture
-
-This document describes the shared session event type system introduced in PR #835 to support the new messaging architecture from PR #819.
-
-## Overview
-
-The CLI now uses a unified event-driven architecture for session communication, replacing the previous heuristic-based approach. All event type definitions are centralized in `src/lib/session-events.ts` to eliminate duplication and provide a single source of truth.
-
-## Event Type Categories
-
-### 1. Runtime System Events
-
-These events track the lifecycle of agent task execution:
-
-- **`runtime_start`** - Agent task has started
-- **`runtime_running`** - Agent task is actively running
-- **`runtime_waiting`** - Agent task is waiting (e.g., for user input)
-- **`runtime_error`** - Runtime error occurred during execution
-- **`runtime_done`** - Agent task completed successfully
-
-### 2. Agent Notification Events
-
-These events carry agent responses and updates:
-
-- **`agent_notification_message`** - Agent text responses
-  - Content: `{ type: 'text', data: string }`
-  - Rendered as markdown in CLI
-- **`agent_notification_progress`** - Agent progress updates
-  - Content: `{ type: 'text', data: string }`
-  - Displayed in spinner status line
-- **`agent_notification_error`** - Agent error notifications
-  - Content: `{ type: 'text', data: string }`
-  - Displayed as error messages in red
-
-### 3. Agent Console Events
-
-Debug and logging output from agents:
-
-- **`agent_console`** - Console output with levels
-  - Levels: `debug`, `info`, `warn`, `error`
-  - Content: `string`
-
-### 4. User Events
-
-- **`user_message`** - Messages sent by the user
-  - Content: `string`
-  - Includes `author_id` field
-
-### 5. Legacy Events (Backward Compatibility)
-
-- **`agent_message`** - Legacy format from pre-PR #819
-  - Message types: `MESSAGE`, `PROGRESS_LOG`, `DEBUG_LOG`, `DONE`
-  - Content: `string`
-  - Maintained for transition period
-
-## Usage in CLI Commands
-
-### Importing Types
-
-```typescript
-import { SessionEvent, Session, AgentMessageEvent } from '../lib/session-events.js';
-```
-
-### Event Processing Example
-
-```typescript
-// Handle different event types
-events.forEach((event: SessionEvent) => {
-  switch (event.type) {
-    case 'agent_notification_message':
-      // Display agent response
-      console.log(event.content.data);
-      break;
-    case 'runtime_done':
-      // Task completed
-      setIsComplete(true);
-      break;
-    case 'agent_message':
-      // Legacy format support
-      if (event.message_type === 'MESSAGE') {
-        console.log(event.content);
-      }
-      break;
-  }
-});
-```
-
-## Completion Detection
-
-The CLI uses different strategies for detecting when an agent task is complete:
-
-### For Assistant Agent
-
-- Waits for `agent_notification_message` events (MESSAGE type)
-- Assistant agent identifier: `"assistant"`
-- More flexible completion detection for assistant workflows
-
-### For Custom Agents
-
-- Waits for `runtime_done` events
-- Indicates the agent task has fully completed
-
-### Legacy Support
-
-- Still supports `agent_message` with `message_type: 'DONE'`
-- Maintained during transition period
-
-## Migration from Duplicated Types
-
-**Before PR #835:**
-
-```typescript
-// Duplicated in chat.tsx, agent/test.ts, agent/chat.ts
-interface AgentMessageEvent extends BaseEvent {
-  type: 'agent_message';
-  message_type: 'MESSAGE' | 'PROGRESS_LOG' | 'DEBUG_LOG' | 'DONE';
-  content: string;
-}
-```
-
-**After PR #835:**
-
-```typescript
-// Single definition in lib/session-events.ts
-import { AgentMessageEvent } from '../lib/session-events.js';
-```
-
-## Benefits
-
-- **Single Source of Truth**: All event types defined in one place
-- **Type Safety**: Compile-time checking for event handling
-- **Maintainability**: Changes to event structure only need to be made once
-- **Consistency**: All CLI commands use the same event definitions
-- **Future-Proof**: Easy to add new event types as the system evolves
-
-## Files Using Shared Types
-
-- `src/commands/chat.tsx` - Interactive chat command
-- `src/commands/agent/test.ts` - Agent testing command
-- `src/commands/agent/chat.ts` - Agent-specific chat command
-- `src/lib/session-events.ts` - Type definitions (source of truth)
-
-This architecture supports the transition from heuristic-based session management to proper event-driven communication, enabling more reliable and faster CLI operations.