@guildai/cli 0.8.1 → 0.9.1

package/dist/lib/stdin.d.ts

@@ -8,6 +8,10 @@ export declare function isInteractive(): boolean;
  * accidentally pipe input without --mode get clear guidance instead of a hang.
  */
 export declare function ensureInteractiveStdin(command: string): void;
+/**
+ * Read raw text from stdin with a timeout.
+ */
+export declare function readStdinAsText(): Promise<string>;
 /**
  * Read JSON from stdin with a timeout.
  */

package/dist/lib/stdin.js

@@ -24,6 +24,29 @@ export function ensureInteractiveStdin(command) {
         process.exit(1);
     }
 }
+/**
+ * Read raw text from stdin with a timeout.
+ */
+export function readStdinAsText() {
+    return new Promise((resolve, reject) => {
+        let input = '';
+        const timeout = setTimeout(() => {
+            reject(new Error('Timeout waiting for stdin'));
+        }, 5000);
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            input += chunk;
+        });
+        process.stdin.on('end', () => {
+            clearTimeout(timeout);
+            resolve(input);
+        });
+        process.stdin.on('error', (error) => {
+            clearTimeout(timeout);
+            reject(error);
+        });
+    });
+}
 /**
  * Read JSON from stdin with a timeout.
  */

package/dist/lib/validate-input-schema.d.ts

@@ -0,0 +1,19 @@
+interface ValidationSuccess {
+    valid: true;
+}
+interface ValidationFailure {
+    valid: false;
+    errors: Array<{
+        message: string;
+        path?: string[];
+    }>;
+}
+interface ValidationSkipped {
+    valid: true;
+    skipped: true;
+    reason: string;
+}
+export type ValidationResult = ValidationSuccess | ValidationFailure | ValidationSkipped;
+export declare function validateInputSchema(agentDir: string, inputs: unknown[]): Promise<ValidationResult>;
+export {};
+//# sourceMappingURL=validate-input-schema.d.ts.map

package/dist/lib/validate-input-schema.js

@@ -0,0 +1,208 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { debug } from './errors.js';
+const execFileAsync = promisify(execFile);
+function resolveSourceEntryPoint(agentDir, packageJson) {
+    const exports = packageJson.exports;
+    if (exports?.['.']) {
+        const distPath = exports['.'];
+        const sourcePath = distPath
+            .replace(/^\.\/dist\//, '')
+            .replace(/\.compiled\.js$/, '.ts')
+            .replace(/\.js$/, '.ts');
+        return path.join(agentDir, sourcePath);
+    }
+    return path.join(agentDir, 'agent.ts');
+}
+async function fileExists(filePath) {
+    return fs
+        .access(filePath)
+        .then(() => true)
+        .catch(() => false);
+}
+/**
+ * Extract a single `const <name> = z.<call>(...)` declaration from source,
+ * starting at the given regex match. Uses balanced parenthesis matching
+ * with string literal awareness.
+ */
+function extractZodDeclaration(source, match) {
+    const startIndex = match.index;
+    const afterEquals = match.index + match[0].length;
+    let depth = 0;
+    let foundOpen = false;
+    let endIndex = afterEquals;
+    let inString = null;
+    for (let charIndex = afterEquals; charIndex < source.length; charIndex++) {
+        const char = source[charIndex];
+        if (inString) {
+            if (char === '\\') {
+                charIndex++;
+            }
+            else if (char === inString) {
+                inString = null;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'" || char === '`') {
+            inString = char;
+        }
+        else if (char === '(') {
+            depth++;
+            foundOpen = true;
+        }
+        else if (char === ')') {
+            depth--;
+            if (foundOpen && depth === 0) {
+                endIndex = charIndex + 1;
+                if (source[endIndex] === ';')
+                    endIndex++;
+                break;
+            }
+        }
+    }
+    if (!foundOpen)
+        return null;
+    return source.substring(startIndex, endIndex);
+}
+/**
+ * Extract inputSchema and any Zod schema dependencies from agent source.
+ * Finds all `const <name> = z.<call>(...)` declarations that appear before
+ * inputSchema (which may be referenced inside it), plus inputSchema itself.
+ * Returns them in source order so dependencies are defined before use.
+ */
+function extractInputSchema(source) {
+    const inputPattern = /const\s+inputSchema\s*=\s*/;
+    const inputMatch = inputPattern.exec(source);
+    if (!inputMatch)
+        return null;
+    const inputBlock = extractZodDeclaration(source, inputMatch);
+    if (!inputBlock)
+        return null;
+    const blocks = [];
+    const zodDeclPattern = /const\s+\w+\s*=\s*z\s*\.\s*/g;
+    let declMatch;
+    while ((declMatch = zodDeclPattern.exec(source)) !== null) {
+        if (declMatch.index >= inputMatch.index)
+            break;
+        const block = extractZodDeclaration(source, declMatch);
+        if (block)
+            blocks.push(block);
+    }
+    blocks.push(inputBlock);
+    return blocks.join('\n');
+}
+export async function validateInputSchema(agentDir, inputs) {
+    const nodeModulesPath = path.join(agentDir, 'node_modules');
+    if (!(await fileExists(nodeModulesPath))) {
+        return {
+            valid: true,
+            skipped: true,
+            reason: 'run npm install for pre-build input validation',
+        };
+    }
+    const pkgJsonPath = path.join(agentDir, 'package.json');
+    if (!(await fileExists(pkgJsonPath))) {
+        return {
+            valid: true,
+            skipped: true,
+            reason: 'no package.json found',
+        };
+    }
+    const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf-8'));
+    let entryPoint = resolveSourceEntryPoint(agentDir, pkgJson);
+    if (!(await fileExists(entryPoint))) {
+        const fallback = path.join(agentDir, 'agent.ts');
+        if (await fileExists(fallback)) {
+            entryPoint = fallback;
+        }
+        else {
+            return {
+                valid: true,
+                skipped: true,
+                reason: `could not find agent source file (tried ${path.basename(entryPoint)})`,
+            };
+        }
+    }
+    const agentSource = await fs.readFile(entryPoint, 'utf-8');
+    const schemaBlock = extractInputSchema(agentSource);
+    if (!schemaBlock) {
+        return {
+            valid: true,
+            skipped: true,
+            reason: 'could not find inputSchema definition in agent source',
+        };
+    }
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'guild-validate-'));
+    try {
+        const extractorSource = [
+            `import { z } from "zod";`,
+            schemaBlock,
+            `const inputs = JSON.parse(process.argv[2]);`,
+            `const errors = [];`,
+            `for (let i = 0; i < inputs.length; i++) {`,
+            `  try {`,
+            `    inputSchema.parse(inputs[i]);`,
+            `  } catch (e) {`,
+            `    const issues = e.issues || [{ message: e.message }];`,
+            `    errors.push({ index: i, issues: issues.map(iss => ({ message: iss.message, path: iss.path })) });`,
+            `  }`,
+            `}`,
+            `if (errors.length > 0) {`,
+            `  console.log(JSON.stringify({ valid: false, errors }));`,
+            `} else {`,
+            `  console.log(JSON.stringify({ valid: true }));`,
+            `}`,
+        ].join('\n');
+        const extractorPath = path.join(tmpDir, 'validate.mjs');
+        await fs.writeFile(extractorPath, extractorSource);
+        const { build } = await import('esbuild');
+        const bundlePath = path.join(tmpDir, 'validate-bundle.mjs');
+        await build({
+            entryPoints: [extractorPath],
+            bundle: true,
+            format: 'esm',
+            target: 'esnext',
+            platform: 'node',
+            outfile: bundlePath,
+            logLevel: 'silent',
+            nodePaths: [path.join(agentDir, 'node_modules')],
+        });
+        const inputArg = JSON.stringify(inputs);
+        const { stdout } = await execFileAsync('node', [bundlePath, inputArg], {
+            cwd: agentDir,
+            timeout: 10000,
+        });
+        const result = JSON.parse(stdout.trim());
+        if (result.valid) {
+            return { valid: true };
+        }
+        const flatErrors = [];
+        for (const entry of result.errors) {
+            for (const issue of entry.issues) {
+                const prefix = inputs.length > 1 ? `Line ${entry.index + 1}: ` : '';
+                flatErrors.push({
+                    message: `${prefix}${issue.message}`,
+                    path: issue.path,
+                });
+            }
+        }
+        return { valid: false, errors: flatErrors };
+    }
+    catch (error) {
+        debug('Local input validation failed: %s', error);
+        return {
+            valid: true,
+            skipped: true,
+            reason: 'local validation encountered an error (server-side validation will still run)',
+        };
+    }
+    finally {
+        await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => { });
+    }
+}
+//# sourceMappingURL=validate-input-schema.js.map

package/dist/lib/version-helpers.js

@@ -2,12 +2,41 @@
 // SPDX-License-Identifier: Apache-2.0
 import { GuildAPIClient } from './api-client.js';
 import { pollUntilComplete } from './polling.js';
+/**
+ * Format a list of validation steps into a compact single-line status string
+ * suitable for spinner text, e.g. `✓ build  ⟳ test  ○ deploy`.
+ * Returns null when the steps array is empty so callers can fall back to the
+ * default attempt-counter text.
+ */
+function formatStepProgress(steps) {
+    if (steps.length === 0)
+        return null;
+    const tokens = steps.map((step) => {
+        let prefix;
+        switch (step.status) {
+            case 'SUCCEEDED':
+                prefix = '✓';
+                break;
+            case 'RUNNING':
+                prefix = '⟳';
+                break;
+            case 'FAILED':
+                prefix = '✗';
+                break;
+            default:
+                prefix = '○';
+        }
+        return `${prefix} ${step.name}`;
+    });
+    return tokens.join('  ');
+}
 /**
  * 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 client = new GuildAPIClient();
     const pollResult = await pollUntilComplete({
         resourceId: versionId,
         endpoint: `/versions/${versionId}`,
@@ -18,6 +47,10 @@ export async function waitForValidation(versionId, output) {
         timeoutMessage: 'Validation timed out',
         maxAttempts: 120,
         delayMs: 1000,
+        onPoll: async () => {
+            const r = await client.get(`/versions/${versionId}/validation/steps`);
+            return formatStepProgress(r.steps);
+        },
     });
     if (!pollResult.success || !pollResult.response) {
         output.error('Validation did not complete in time', 'Check status manually:\n  guild agent versions');
@@ -64,6 +97,7 @@ async function fetchValidationFailureDetails(versionId) {
  * Returns the updated version on success.
  */
 export async function waitForPublish(versionId, output) {
+    const client = new GuildAPIClient();
     const pollResult = await pollUntilComplete({
         resourceId: versionId,
         endpoint: `/versions/${versionId}`,
@@ -73,6 +107,10 @@ export async function waitForPublish(versionId, output) {
         timeoutMessage: 'Publish timed out',
         maxAttempts: 60,
         delayMs: 1000,
+        onPoll: async () => {
+            const r = await client.get(`/versions/${versionId}/publish/steps`);
+            return formatStepProgress(r.steps);
+        },
     });
     if (!pollResult.success || pollResult.response?.status !== 'PUBLISHED') {
         output.error('Publish did not complete in time', 'Check status manually:\n  guild agent versions');

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

@@ -0,0 +1,20 @@
+/**
+ * Workspace resolution helper for workspace subcommands.
+ *
+ * Resolves a workspace identifier (UUID or human-readable name) to a UUID.
+ * Used by `guild workspace agent add`, `list`, and `remove`.
+ */
+import { GuildAPIClient } from './api-client.js';
+/**
+ * Resolve a workspace ID or name to a workspace UUID.
+ *
+ * UUID inputs pass through unchanged. Name inputs are resolved by searching
+ * the user's workspaces via `GET /me/workspaces?filter=all&search=...` first,
+ * with a `fetchAll` fallback for IDs and names not matched by the search.
+ *
+ * Throws an `Error` with message `Workspace "<idOrName>" not found` if
+ * nothing resolves — callers should catch this and call `output.error` +
+ * `process.exit(1)`.
+ */
+export declare function resolveWorkspaceId(client: GuildAPIClient, idOrName: string): Promise<string>;
+//# sourceMappingURL=workspace-helpers.d.ts.map

package/dist/lib/workspace-helpers.js

@@ -0,0 +1,49 @@
+// Copyright 2026 Guild.ai
+// SPDX-License-Identifier: Apache-2.0
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Match a workspace against a search argument (case-insensitive name, full_name, or exact ID).
+ */
+function matchesWorkspaceArg(w, arg) {
+    return (w.id === arg ||
+        w.name === arg ||
+        w.name.toLowerCase() === arg.toLowerCase() ||
+        w.full_name === arg ||
+        w.full_name?.toLowerCase() === arg.toLowerCase());
+}
+/**
+ * Resolve a workspace ID or name to a workspace UUID.
+ *
+ * UUID inputs pass through unchanged. Name inputs are resolved by searching
+ * the user's workspaces via `GET /me/workspaces?filter=all&search=...` first,
+ * with a `fetchAll` fallback for IDs and names not matched by the search.
+ *
+ * Throws an `Error` with message `Workspace "<idOrName>" not found` if
+ * nothing resolves — callers should catch this and call `output.error` +
+ * `process.exit(1)`.
+ */
+export async function resolveWorkspaceId(client, idOrName) {
+    // Short-circuit UUID inputs — pass through unchanged
+    if (UUID_RE.test(idOrName)) {
+        return idOrName;
+    }
+    // Use server-side search first. Extract just the name part for full_name
+    // inputs (e.g. "owner/workspace-name") since the backend searches by name.
+    const searchTerm = idOrName.includes('/')
+        ? (idOrName.split('/').pop() ?? idOrName)
+        : idOrName;
+    const searchResults = await client.get(`/me/workspaces?filter=all&search=${encodeURIComponent(searchTerm)}&limit=100`);
+    const directMatch = searchResults.items.find((w) => matchesWorkspaceArg(w, idOrName));
+    if (directMatch) {
+        return directMatch.id;
+    }
+    // Fall back to fetching all workspaces (handles IDs and names not returned
+    // by search, e.g. when the backend's ILIKE search doesn't match full_name).
+    const allWorkspaces = await client.fetchAll('/me/workspaces?filter=all');
+    const fallbackMatch = allWorkspaces.find((w) => matchesWorkspaceArg(w, idOrName));
+    if (fallbackMatch) {
+        return fallbackMatch.id;
+    }
+    throw new Error(`Workspace "${idOrName}" not found`);
+}
+//# sourceMappingURL=workspace-helpers.js.map

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/CLI_WORKFLOW.md

@@ -1,5 +1,5 @@
 ---
-name: Guild CLI Workflow
+name: guild-cli-workflow
 description: Agent development using the Guild CLI. Activated when user mentions guild agent commands, saving/publishing agents, clone/pull workflow, or agent testing. Covers CLI commands and common workflows.
 ---