@guildai/cli 0.9.0 → 0.9.1

package/dist/mcp/tools.js

@@ -1,10 +1,10 @@
 // Copyright 2026 Guild.ai
 // SPDX-License-Identifier: Apache-2.0
 import { z } from 'zod';
+import { pollForResponse as pollForSessionResponse } from '../lib/session-polling.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 120_000;
 // ---------------------------------------------------------------------------
 // Helpers
@@ -14,55 +14,6 @@ function debugLog(debug, message) {
         process.stderr.write(`[guild-mcp] ${message}\n`);
     }
 }
-/**
- * Poll session events until runtime_done or runtime_error.
- * Returns collected agent messages.
- */
-async function pollForResponse(apiClient, sessionId, debug) {
-    const startTime = Date.now();
-    const messages = [];
-    let lastEventId;
-    while (Date.now() - startTime < POLL_TIMEOUT_MS) {
-        try {
-            let url = `/sessions/${sessionId}/events`;
-            if (lastEventId) {
-                url += `?from_id=${lastEventId}`;
-            }
-            const response = await apiClient.get(url);
-            const events = response.events || [];
-            for (const event of events) {
-                debugLog(debug, `Event: ${event.event_type}`);
-                if (event.event_type === 'agent_notification_message') {
-                    const data = extractEventText(event);
-                    if (data) {
-                        messages.push(data);
-                    }
-                }
-                if (event.event_type === 'runtime_error') {
-                    const errorText = extractEventText(event);
-                    if (errorText) {
-                        return `Error: ${errorText}`;
-                    }
-                    return 'Error: Agent encountered an error';
-                }
-                if (event.event_type === 'runtime_done') {
-                    debugLog(debug, 'Runtime done');
-                    return messages.join('\n\n') || 'Agent completed without output.';
-                }
-            }
-            if (events.length > 0) {
-                lastEventId = events[events.length - 1].id;
-            }
-        }
-        catch (error) {
-            debugLog(debug, `Poll error: ${String(error)}`);
-        }
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
-    }
-    return messages.length > 0
-        ? messages.join('\n\n') + '\n\n(Timed out waiting for completion)'
-        : 'Timed out waiting for agent response.';
-}
 function extractEventText(event) {
     if (!event.content)
         return undefined;
@@ -74,6 +25,11 @@ function extractEventText(event) {
     }
     return undefined;
 }
+async function pollForMcpResponse(apiClient, sessionId, debug) {
+    debugLog(debug, `Polling response for session ${sessionId}`);
+    const result = await pollForSessionResponse(apiClient, sessionId, undefined, POLL_TIMEOUT_MS);
+    return result.response || 'Agent completed without output.';
+}
 function errText(action, error) {
     return `Failed to ${action}: ${error instanceof Error ? error.message : String(error)}`;
 }
@@ -504,7 +460,7 @@ export function registerTools(server, apiClient, defaultWorkspaceId, debug) {
             }
             const session = await apiClient.post(`/workspaces/${wsId}/sessions`, body);
             debugLog(debug, `Session created: ${session.id}`);
-            const response = await pollForResponse(apiClient, session.id, debug);
+            const response = await pollForMcpResponse(apiClient, session.id, debug);
             return {
                 content: [{ type: 'text', text: response }],
             };
@@ -526,7 +482,7 @@ export function registerTools(server, apiClient, defaultWorkspaceId, debug) {
                 event_type: 'user_message',
                 content: { type: 'text', data: message },
             });
-            const response = await pollForResponse(apiClient, session_id, debug);
+            const response = await pollForMcpResponse(apiClient, session_id, debug);
             return {
                 content: [{ type: 'text', text: response }],
             };

package/docs/skills/agent-dev.md

@@ -5,7 +5,17 @@ description: Local agent development using the Guild CLI. Activated when user me
 
 # Guild Agent Development
 
-Build agents for Guild using the CLI. **Always use the Guild CLI for agent operations - never use raw git commands.**
+Build agents for Guild using the CLI.
+
+The Guild CLI is self-documenting:
+
+- You may type `--help` after any command to learn more about how to use it
+- You can type `guild --help` to learn about common options available across all commands.
+- If you discover a discrepancy between these instructions and the Guild CLI's internal documentation, assume that the Guild CLI's version is correct.
+
+When using the CLI, prefer to explicitly provide arguments as defaults can sometimes be unintuitive
+
+**Always use the Guild CLI for agent operations - unless specified below, never use raw git commands.**
 
 ## MCP vs CLI
 
@@ -36,24 +46,34 @@ guild setup
 guild setup --claude-md
 ```
 
-### Creating Agents
+### Creating a New Agent
 
 ```bash
 # Create and initialize a new agent (interactive - prompts for name and template)
 guild agent init
 
-# Create with specific name and template
-guild agent init --name my-agent --template LLM
-guild agent init --name my-agent --template AUTO_MANAGED_STATE
-guild agent init --name my-agent --template BLANK
+# Create with specific name and template. You must specify an owner account.
+guild agent init --owner account-name --name my-agent --template LLM
+guild agent init --owner account-name --name my-agent --template AUTO_MANAGED_STATE
+guild agent init --owner account-name --name my-agent --template BLANK
 
 # Initialize with fork of existing agent
-guild agent init --fork owner/agent-name
+guild agent init --fork owner~agent-name
+```
+
+IMPORTANT! When creating a new agent, it's important to understand who will be the owner of the agent; typically this is likely to be an organization to which the user belongs, or the user's own private account. If unsure, ask for clarification!
 
+IMPORTANT! By default `guild agent init` will create an agent in the current working directory. Use the `--directory` option to specify an alternate location.
+
+### Modifying an Existing Agent
+
+```bash
 # Clone to work on existing agent
-guild agent clone owner/agent-name
+guild agent clone owner~agent-name
 ```
 
+IMPORTANT! By default `guild agent clone` will create an agent in the `<agent-name>` directory. Use the `--directory` option to specify an alternate location.
+
 ### Syncing and Saving
 
 Git owns the working tree, Guild owns the remote. Use normal git commands to stage and commit, then `guild agent save` to push and create a version.
@@ -76,8 +96,28 @@ guild agent save --message "Fix bug" --wait
 guild agent save -A --message "Release v1.0" --wait --publish
 ```
 
+### Building
+
+An agent is just an `npm` TypeScript project.
+
+```bash
+# Install the agent's dependencies
+npm install
+
+# Build the agent's code
+npm run build
+```
+
+IMPORTANT! You must be logged in to guild to `npm install` dependencies; run `guild auth login` if you get a "not authorized" error when running `npm install`.
+
+TIP. Once you've identified the integrations upon which your agent will depend, update `package.json` and run `npm install` _before_ attempting to write any code that uses the integration. You're much less likely to make a poor assumption about what tools exist or how you must use them.
+
+IMPORTANT! Always make sure that your agent builds correctly before testing.
+
 ### Testing
 
+An agent must be tested using the `guild` tool: this will upload the agent to the server runtime environment where the agent will operate.
+
 ```bash
 # Interactive test session
 guild agent test
@@ -99,6 +139,8 @@ EOF
 guild agent chat "Hello, can you help me?"
 ```
 
+IMPORTANT! Most integrations require that you provide credentials to connect them appropriately. Choose a workspace (e.g. with `guild workspace list`) that has appropriate credentials installed for each integration that your agent uses. If you cannot find one, instruct the user of your conundrum and ask for advice; specifically, tell them "I cannot test the agent without access to a workspace that has access to all of the integrations that this agent requires. I can't seem to find one. If I've overlooked a workspace with the correct credentials, please let me know which one to use. Otherwise, please configure a workspace appropriately and let me know its name when it is ready."
+
 ### Chatting with Agents
 
 ```bash
@@ -157,70 +199,13 @@ To chat with the agent you are developing locally, use `guild agent chat` from w
 
 The SDK core comes from `@guildai/agents-sdk`. Service tools are in separate `@guildai-services/*` packages.
 
-```typescript
-// Agent factories
-import { agent, llmAgent } from '@guildai/agents-sdk';
-
-// Types
-import type {
-  Task,
-  AgentResult,
-  TypedToolResult,
-  TypedToolError,
-} from '@guildai/agents-sdk';
+You can inspect this package locally after you `npm install` the agent's dependencies.
 
-// Result helpers (for self-managed state agents)
-import { ask, output, callTools } from '@guildai/agents-sdk';
+You can review [online documentation for the API](https://docs.guild.ai/guide/sdk-introduction): this includes guides and references.
 
-// Platform tools (from SDK)
-import { guildTools, userInterfaceTools } from '@guildai/agents-sdk';
+### Common Integrations
 
-// Service tools (from separate packages - NOT from SDK)
-import { azureDevOpsTools } from '@guildai-services/guildai~azure-devops';
-import { bitbucketTools } from '@guildai-services/guildai~bitbucket';
-import { confluenceTools } from '@guildai-services/guildai~confluence';
-import { cypressTools } from '@guildai-services/guildai~cypress';
-import { figmaTools } from '@guildai-services/guildai~figma';
-import { gitHubTools } from '@guildai-services/guildai~github';
-import { googleComputeTools } from '@guildai-services/guildai~google-compute';
-import { googleLoggingTools } from '@guildai-services/guildai~google-logging';
-import { jiraTools } from '@guildai-services/guildai~jira';
-import { linearTools } from '@guildai-services/guildai~linear';
-import { newrelicTools } from '@guildai-services/guildai~newrelic';
-import { pipedreamTools } from '@guildai-services/guildai~pipedream';
-import { slackTools } from '@guildai-services/guildai~slack';
-import { testrailTools } from '@guildai-services/guildai~testrail';
-import { zendeskTools } from '@guildai-services/guildai~zendesk';
-
-// Utilities
-import {
-  pick,
-  omit,
-  guildAgentTool,
-  progressLogNotifyEvent,
-} from '@guildai/agents-sdk';
-
-// Calling another agent as a tool (import from its /tool sub-package)
-import subagentTool from '@guildai/owner~agent-name/tool';
-
-// Coding agent (container-based code execution)
-import { ExperimentalCodingTools as codingTools } from '@guildai-services/guildai~experimental-coding';
-import {
-  CONTAINER_IMAGE,
-  codingAgentToolsFrom,
-} from '@guildai/guildai~sys-experimental-coding';
-import codingAgentTool from '@guildai/guildai~sys-experimental-coding/tool';
-
-// Advanced (for compiled agents with LLM tool loops)
-import { delegatedCallsOf, asToolResultContent } from '@guildai/agents-sdk';
-
-// Zod (provided by runtime, do NOT add to dependencies)
-import { z } from 'zod';
-```
-
-### Service Packages Table
-
-Service tools are in separate `@guildai-services/*` packages. The runtime resolves them automatically.
+An _integration_ provides the agent the tools it needs to interact with the world. An integration's API is made available via a separate `@guildai-services/*` package. To use an integration, you add it as a dependency in `package.json` and then `import` it in the agent's TypeScript code. Here are some examples:
 
 | Service        | Package                                    | Export               | Tool Name Prefix  |
 | -------------- | ------------------------------------------ | -------------------- | ----------------- |
@@ -242,9 +227,15 @@ Service tools are in separate `@guildai-services/*` packages. The runtime resolv
 | User Interface | `@guildai/agents-sdk`                      | `userInterfaceTools` | `ui_`             |
 | Zendesk        | `@guildai-services/guildai~zendesk`        | `zendeskTools`       | `zendesk_`        |
 
+You can use the CLI to search for a full list of integrations using `guild integration list`.
+
 ### Tool Access via `task.tools.*`
 
-All tool calls go through `task.tools.<toolName>(args)`. This is the primary API.
+To make use of an integration, you must:
+
+1. Import the integration's tools
+2. Include the relevant tools in the agent's tool set. This will automatically create functions you can call on the `task.tools` object.
+3. Invoke a tool using the `task.tools.<toolName>(args)`.
 
 ```typescript
 // GitHub
@@ -293,25 +284,41 @@ await task.tools.guild_credentials_request({ service: 'GITHUB' });
 
 Three patterns, ordered by simplicity:
 
+1. LLM agent - just a prompt and tools
+2. Coded agent - automatic state management
+3. Coded agent - explicit state management
+
+Considerations:
+
+- Maintenance. An LLM agent will be easiest for a human to understand and maintain. A coded agent requires expert knowledge, and one with explicit state management results in a state machine implementation that will be difficult even for an expert programmer to maintain.
+- Cost. An LLM agent requires inference to operate and so incurs a high per-invocation cost. If a task is sufficiently simple, a coded agent may be preferable and will certainly be cheaper to operate.
+- Latency. An LLM agent requires inference to operate and so can incur a non-trivial latency.
+- Control. An LLM agent is ultimately stochastic. If precise, fine-grained control is required, it may be easier to achieve with a coded agent than through natural language instructions.
+- Reasoning and decision making. An LLM agent allows for nuanced judgment calls; a coded agent requires strict rules.
+
+TIP. A coded agent can make use of the `task.llm.generateText` call to use an LLM as a subroutine: this may be a reasonable trade-off to make.
+
+A detailed description and example of each is provided below.
+
 ### 1. LLM Agent (`llmAgent()`) — Simplest
 
-For conversational/prompt-driven agents where the LLM IS the logic. No `run()` or `start()` needed.
+For conversational/prompt-driven agents where the LLM IS the logic.
 
 ```typescript
-import { guildTools, llmAgent, pick } from '@guildai/agents-sdk';
+import { llmAgent, pick } from '@guildai/agents-sdk';
 import { gitHubTools } from '@guildai-services/guildai~github';
 
 export default llmAgent({
   description: 'Helps users with GitHub questions',
   tools: {
     ...pick(gitHubTools, ['github_issues_list_for_repo', 'github_issues_get']),
-    ...guildTools, // ALWAYS spread fully — never pick() from guildTools
   },
   systemPrompt: `
     You are a helpful assistant that answers questions about GitHub repositories.
     Use the GitHub tools to look up information when asked.
   `,
-  mode: 'multi-turn', // "one-shot" (default) or "multi-turn"
+  mode: 'one-shot', // "one-shot" (default) or "multi-turn"
+  useWorkspaceAgents: false,
 });
 ```
 
@@ -320,7 +327,7 @@ export default llmAgent({
 By default, `llmAgent` accepts `{ type: "text", text: string }` and sends `text` as the first user message. Override this for structured inputs:
 
 ```typescript
-import { guildTools, llmAgent, pick } from '@guildai/agents-sdk';
+import { llmAgent, pick } from '@guildai/agents-sdk';
 import { gitHubTools } from '@guildai-services/guildai~github';
 import { z } from 'zod';
 
@@ -333,20 +340,47 @@ export default llmAgent({
   inputTemplate: 'Analyze repo {{repo}} on branch {{branch}}',
   tools: {
     ...pick(gitHubTools, ['github_repos_get', 'github_pulls_list']),
-    ...guildTools,
   },
   systemPrompt: 'You analyze GitHub repositories.',
+  mode: 'one-shot', // "one-shot" (default) or "multi-turn"
+  useWorkspaceAgents: false,
 });
 ```
 
 - `inputSchema` — Zod schema for the agent's input (replaces the default `{ type: "text", text: string }`)
 - `inputTemplate` — Mustache-style template that renders the input as the initial LLM user message (default: `"{{text}}"`)
 
-**`useWorkspaceAgents`** — When `true`, the agent dynamically discovers and can call other agents installed in the workspace (like Guild's built-in assistant does). Defaults to `true`, but most agents should set this to `false` unless they specifically need dynamic agent discovery. For deterministic orchestration, use `guildAgentTool()` to delegate to specific agents instead.
+**`mode`: `one-shot` versus `multi-turn`**
+
+An LLM agent whose `mode` is `one-shot` will run for a single turn and then return its output as a result. The "single turn" may include rounds of tool calls, thinking, etc. but once its computation is complete it will terminate and control will be restored to the agent that invoked it. This appropriate for most agents.
+
+TIP: use this agent whenever you need fully autonomous operation without user interaction.
+
+An LLM agent whose `mode` is `multi-turn` does not automatically return control to its caller and will instead proceed interactively -- i.e., prompting the user -- until a specific termination criteria is defined. You must specify this exact termination criteria and instruct the agent to call the `__submit__` tool once that criteria is achieved. This will end the interactive loop and restore control to the caller.
+
+WARNING: this is **rarely** the mode that an agent should operate in: it is **only** useful for agents that are guaranteed to be invoked interactively. USE WITH CAUTION!
+
+**`useWorkspaceAgents`**
+
+When `true`, the agent dynamically discovers and can call other agents installed in the workspace (like Guild's built-in assistant does). Defaults to `true`, but most agents should explicitly set this to `false` unless they specifically need dynamic agent discovery. For deterministic orchestration, use `guildAgentTool()` to delegate to specific agents instead.
+
+IMPORTANT! Understand whether or not your agent will operate in an interactive environment; i.e., one where a user will be able to directly chat with the agent. (An agent that is activated from a trigger -- i.e., a webhook or a timer -- is considered **non-interactive** since no user is present.) If the agent is non-interactive, **NEVER** make use of the `ui_prompt` tool: this tool attempts to solicit a response from an interactive user who will not be available.
 
-### 2. Automatic State Agent (`run()`) — Recommended for Code-First
+**Tools**
 
-Runtime manages state via continuations. Return the output object directly. Use `task.tools.*` for all tool calls. Requires `"use agent"` directive.
+- Provide an LLM agent with the minimum set of tools that it needs to accomplish its task.
+  - Many models have strict limits on the number of tools that are allowed.
+  - Unnecessary tools waste context space and risk confusion.
+- Use the `pick` utility to select multiple tools from an integration in a succinct way.
+- NEVER spread an entire toolset (e.g. `...gitHubTools`) in an LLM agent: this is bad form, and you always want to look good.
+
+### 2. Code Agent with Automatic State Management
+
+An agent that is implemented as a simple TypeScript `run` function. Ideal for most situations that require coding.
+
+- Implement a single `run()` function that accepts the input and returns the output: the function is implemented in a natural procedural style that is easy to understand and maintain.
+- Requires the `"use agent"` directive at top of the file: this triggers a compilation step that converts the TypeScript code into a resumable state machine that can be suspended at for long-running tasks.
+- Use `task.tools.*` for all integration tool calls.
 
 ```typescript
 'use agent';
@@ -377,7 +411,6 @@ type Output = z.infer<typeof outputSchema>;
 
 const tools = {
   ...pick(gitHubTools, ['github_search_issues_and_pull_requests']),
-  ...guildTools, // ALWAYS spread fully — never pick() from guildTools
   ...userInterfaceTools,
 };
 
@@ -411,16 +444,18 @@ export default agent({
 });
 ```
 
-**Key points:**
+### 3. Coded agent with Self-Managed State
 
-- `run()` returns the OUTPUT directly (not wrapped in `{ type: "output", output: ... }`)
-- The runtime handles continuations — you can `await` tool calls inline
-- `"use agent"` directive at top of file is optional (the Babel compiler recognizes it but strips it)
-- No `identifier` field needed
+For explicit state control.
 
-### 3. Self-Managed State Agent (`start()`/`onToolResults()`)
-
-For explicit state control. Uses `ask()`, `output()`, `callTools()` helpers and `task.save()`/`task.restore()`.
+- Implement the `start()` and `onToolResults()` functions: these return `AgentResult<Output, Tools>`
+  - `return ask(prompt)` — sends a `ui_prompt` tool call to get user input
+  - `return output(value)` — wraps your output as `{ type: "output", output: value }`
+  - `return callTools([...])` — requests the runtime to execute tool calls
+- `task.save(state)` / `task.restore()` persist state between invocations: you must explicitly specify the schema of the state.
+- May be necessary for more elaborate situations; notably, invoking multiple agents or tools in parallel.
+- Generally results in a much more complicated program that can be difficult to understand and maintain; avoid if possible.
+- No `"use agent"` directive since there is no compilation step.
 
 ```typescript
 import {
@@ -488,19 +523,11 @@ export default agent({
 });
 ```
 
-**Key points:**
-
-- `start()` and `onToolResults()` return `AgentResult<Output, Tools>`
-- `ask(prompt)` — sends a `ui_prompt` tool call to get user input
-- `output(value)` — wraps your output as `{ type: "output", output: value }`
-- `callTools([...])` — requests the runtime to execute tool calls
-- `task.save(state)` / `task.restore()` — persist state between invocations
-
 ---
 
 ## Agent-to-Agent Delegation
 
-Every published agent exposes a `/tool` sub-package that wraps it as a callable tool. Import it and add it to your tools object — the runtime handles dispatch.
+Every published agent exposes a `/tool` sub-package that allows it to be used just like any other callable tool. Import it and add it to your tools object — the runtime handles dispatch.
 
 ### Using a published agent as a tool (preferred)
 
@@ -580,7 +607,7 @@ export default agent({
 
 ### Using the Coding Agent
 
-The coding agent runs instructions inside an isolated container. Use it when your agent needs to read/write files, run shell commands, or work with a cloned repository.
+The coding agent runs instructions inside a dedicated (but isolated) virtual machine. The agent has full access to the computer: use it when your agent needs to read/write files, run shell commands, or work with a cloned repository.
 
 ```typescript
 import { ExperimentalCodingTools as codingTools } from '@guildai-services/guildai~experimental-coding';
@@ -672,6 +699,8 @@ Using `session_id` preserves the container's working directory, environment vari
 
 **GitHub tools for common container tasks:**
 
+The GitHub API provides primitives that must be composed in the coding container for common operations. If you need the agent to perform any of the following tasks, be sure to include the tools upon which the task depends. Use the table below as a reference.
+
 | Task                | Required Tools                                                                                                                                         |
 | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Clone a repository  | `github_repos_download_zipball_archive`                                                                                                                |
@@ -684,7 +713,9 @@ Using `session_id` preserves the container's working directory, environment vari
 
 ---
 
-## Advanced: Compiled Agent Patterns
+## Advanced Topics
+
+### Example: Using an LLM from within a coded agent
 
 For agents that need an LLM tool-calling loop with fine-grained control over which tool calls the LLM handles vs which get delegated to the runtime:
 
@@ -755,10 +786,9 @@ async function onToolResults(
 - `delegatedCallsOf<Tools>(content)` — extracts unexecuted tool calls from `generateText` results that need runtime delegation
 - `asToolResultContent(results)` — converts `TypedToolResult[]` into LLM message format for conversation history
 
-### Slack-Specific Patterns
+### Example: Slack-Specific Patterns
 
-When posting to Slack, convert markdown to Slack's mrkdwn format. Use an inline converter
-(`slackify-markdown` is CJS and breaks in the ESM agent runtime):
+When posting to Slack, convert markdown to Slack's mrkdwn format. Use an inline converter (`slackify-markdown` is CJS and breaks in the ESM agent runtime):
 
 ```typescript
 // Simple markdown-to-Slack-mrkdwn converter (inline — do NOT use slackify-markdown)
@@ -793,7 +823,7 @@ await task.tools.slack_chat_post_message({
 
 ### Discovering Available Tools
 
-**Do NOT guess tool names.** Use the Guild CLI to discover what tools exist for each integration:
+**NEVER attempt to guess a tool's name.** Use the Guild CLI to discover what tools exist for each integration:
 
 ```bash
 # List all available integrations
@@ -806,7 +836,10 @@ guild integration operation list guildai~github
 guild integration operation list guildai~github --json
 ```
 
-Tool names follow the pattern `{service_prefix}_{operation_name}` (e.g., `github_pulls_get`). Check the service packages table above for each service's prefix.
+Tool names follow the pattern `{service_prefix}_{operation_name}` (e.g., `github_pulls_get`).
+
+- Check the service packages table above for common service prefixes.
+- For an integration not listed above (e.g., `@guildai-services/some-owner~some-integration`), the service prefix will be the _integration name_ (e.g., `some-integration`) with any hyphens replaced by underscores (e.g., `some_integration`).
 
 Use `pick()` to select specific tools, or `omit()` to exclude specific tools:
 
@@ -814,41 +847,69 @@ Use `pick()` to select specific tools, or `omit()` to exclude specific tools:
 // Include only specific tools
 const tools = {
   ...pick(gitHubTools, ['github_repos_get', 'github_pulls_list']),
-  ...guildTools,
 };
 
 // Include all tools except specific ones
 const tools = {
   ...omit(gitHubTools, ['github_repos_delete', 'github_repos_update']),
-  ...guildTools,
 };
 ```
 
-### NEVER `pick()` from `guildTools`
+### Adding an integration for your agent
 
-**CRITICAL: Always spread `guildTools` fully. NEVER use `pick(guildTools, [...])`.**
+To add an integration for you agent, use `npm install`:
 
-The SDK's `Task` type conditionally provides `task.guild: GuildService` based on whether the **full** `guildTools` set is in the tools type. Using `pick()` creates a subset type that doesn't satisfy this constraint, causing:
+```bash
+# Add an integration
+npm install --save @guildai-services/some-owner~some-integration
 
-- `task.guild` becomes `undefined` instead of `GuildService`
-- Type errors in any function that expects `task.guild` to exist
-- Build failures during agent validation (which blocks publishing)
+# Add an agent as a tool
+npm install --save @guildai/some-owner~some-agent
+```
+
+The integration or agent should be added as a dependency (i.e., _not_ a `devDependency`)
+
+Once you've done that, import the agent into your agent as you would any other package:
 
 ```typescript
-// ❌ WRONG — task.guild will be undefined, TypeScript build fails
-const tools = {
-  ...pick(guildTools, ['guild_get_me', 'guild_create_agent']),
-  ...userInterfaceTools,
-};
+// An integration. This object will be a ToolSet from which you should select the tools you need.
+import { SomeIntegration } from '@guildai-services/some-owner~some-integration';
+
+// An agent... note that it's imported from the `/tool` sub-package as the default export
+import SomeAgent from '@guildai/some-onwer~some-agent/tool';
 
-// ✅ CORRECT — always spread fully
+// Include the relevant tools in your agent's tool object.
 const tools = {
-  ...guildTools,
-  ...userInterfaceTools,
+  // The integration tools.
+  ...pick(SomeIntegration, ['some_integration_tool_one', 'some_integration_tool_two']),
+
+  // The agent tool
+  someAgentTool: SomeAgent,
 };
 ```
 
-**`pick()` is fine for service tools** like `gitHubTools`, `slackTools`, etc. It's only `guildTools` that must be spread fully.
+**For a coded agent...**
+
+Once you've done the above, you can use the TypeScript LSP to determine the exact parameter and return type for each tool. OR... you can inspect the TypeScript types for the package directly in the `node_modules` subdirectory (this is often an expedient way to understand the type details).
+
+IMPORTANT! Always let TypeScript help you:
+
+- Let the TypeScript compiler infer the type of the `tools` object: DO NOT provide an explicit type annotation as it is likely incorrect!
+- NEVER cast to `any`: failure to resolve correct types likely means that something else is going wrong so keep investigating.
+- Adding a tool to the agent's `tools` creates the correct signature on the `task` object:
+
+```typescript
+// Assume `tools` is defined as above, and that `Input` and `Output` are the `z.infer'd` types
+type Tools = typeof tools;
+
+async function run(input: Input, task: Task<Tools>): Promise<Output> {
+  // These should *not* resolve to `any` type, but should instead be strongly typed if all your imports have been done correctly.
+  const { foo, bar } = await task.tools.some_integration_tool_one({
+    baz: 'bop',
+    bip: 12,
+  });
+}
+```
 
 ### DO NOT USE (Common Mistakes)
 
@@ -883,10 +944,6 @@ import { gitHubTools } from "@guildai-services/guildai~github/src/service"
 import { agent } from "@guildai/agents-sdk"
 // (no "use agent" at top)
 export default agent({ run: async (input, task) => { ... } })
-
-// ❌ WRONG: picking from guildTools breaks task.guild typing
-...pick(guildTools, ["guild_get_me", "guild_create_agent"])
-// Use ...guildTools instead (spread fully)
 ```
 
 ### CORRECT Patterns
@@ -995,8 +1052,9 @@ For simple `llmAgent()` agents that don't use `"use agent"`, you can skip the Ba
 
 **CRITICAL:**
 
-- Do NOT add `@guildai/agents-sdk`, `@guildai-services/*`, or `zod` to dependencies. The runtime provides them.
-- DO add third-party ESM-compatible packages your agent uses to `dependencies`. Note: CJS-only packages (e.g., `slackify-markdown`) will break in the ESM agent runtime — use inline alternatives instead.
+- DO NOT modify the `@guildai/agents-sdk` and `zod` dependencies provided in the agent's template.
+- You may add third-party ESM-compatible packages your agent uses to `dependencies`.
+- DO NOT include CJS packages: an agent that includes a CJS module will fail at runtime.
 - `devDependencies` is for build tools only (`esbuild` for bundling, `typescript` for compilation).
 
 ## Versioning
@@ -1028,6 +1086,12 @@ my-agent/
 
 ## CLI Commands
 
+Below is a quick reference of common CLI commands.
+
+- Use `guild help` to discover the full set of commands
+- Use `guild <command> [...<subcommand>] --help` with any command for full documentation on its usage
+- Prefer to explicitly provide all command arguments rather than relying on defaults
+
 ```bash
 guild setup                                        # Install coding assistant skills
 guild setup --claude-md                            # Also create CLAUDE.md template
@@ -1068,7 +1132,6 @@ guild workspace select                             # Set default workspace (writ
 
 ```bash
 GUILD_WORKSPACE_ID=<id> guild agent test           # Override workspace for this command
-GUILD_OWNER_ID=<id> guild agent init --name my-agent  # Override owner for agent creation
 ```
 
 ## Troubleshooting

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guildai/cli",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Guild.ai CLI - Build, test, and deploy AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -63,6 +63,7 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "dotenv": "^16.4.7",
+    "esbuild": "^0.28.0",
     "execa": "^9.6.1",
     "ink": "^5.0.1",
     "ink-text-input": "^6.0.0",