@guildai/cli 0.7.0 → 0.8.0

package/dist/lib/agent-helpers.js

@@ -1,23 +1,52 @@
 // Copyright 2026 Guild.ai
 // SPDX-License-Identifier: Apache-2.0
+import { createHash } from 'crypto';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { loadLocalConfig } from './guild-config.js';
 import { runGit } from './git.js';
 import { resolveOwnerId } from './owner-helpers.js';
+import { pollUntilComplete } from './polling.js';
+// ---------------------------------------------------------------------------
+// Build error types
+// ---------------------------------------------------------------------------
+/** Thrown when the ephemeral version build times out or polling fails. */
+export class BuildTimeoutError extends Error {
+    constructor(message = 'The agent version build timed out or failed to report status.') {
+        super(message);
+        this.name = 'BuildTimeoutError';
+    }
+}
+/** Thrown when the ephemeral version build fails validation. */
+export class BuildFailedError extends Error {
+    failedSteps;
+    constructor(failedSteps) {
+        const stepSummary = failedSteps.length > 0
+            ? failedSteps
+                .map((s) => `Step "${s.name}" failed:${s.content ? `\n${s.content}` : ''}`)
+                .join('\n')
+            : 'No failed steps found. Check validation logs for details.';
+        super(`Build failed\n\n${stepSummary}\n\nFix the issues and retry.`);
+        this.name = 'BuildFailedError';
+        this.failedSteps = failedSteps;
+    }
+}
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * Resolve an agent identifier to a fully-qualified form.
  *
- * If the identifier already contains `/` or is a UUID, return it verbatim.
- * Otherwise, resolve the default owner and prepend `owner.name/`.
+ * If the identifier already contains `~` or is a UUID, return it verbatim.
+ * Otherwise, resolve the default owner and prepend `owner.name~`.
  */
 export async function resolveAgentRef(client, identifier) {
-    if (identifier.includes('/') || UUID_RE.test(identifier)) {
+    if (identifier.includes('~') || UUID_RE.test(identifier)) {
         return identifier;
     }
+    if (identifier.includes('/')) {
+        return identifier.replace('/', '~');
+    }
     const owner = await resolveOwnerId({ client, interactive: false });
-    return `${owner.name}/${identifier}`;
+    return `${owner.name}~${identifier}`;
 }
 /**
  * Get agent ID from argument or guild.json in current directory
@@ -72,10 +101,7 @@ const REQUIRED_AGENT_FILES = ['agent.ts', 'package.json'];
 export async function readAgentFiles(cwd) {
     const { stdout } = await runGit(['ls-files', '--cached', '--others', '--exclude-standard'], { cwd });
     const gitFiles = stdout.split('\n').filter((f) => f.trim().length > 0);
-    const relevantFiles = gitFiles.filter((f) => {
-        const ext = path.extname(f);
-        return ['.ts', '.json', '.md'].includes(ext);
-    });
+    const relevantFiles = gitFiles.filter((f) => !f.startsWith('.guild/'));
     const files = [];
     for (const filePath of relevantFiles) {
         const fullPath = path.join(cwd, filePath);
@@ -89,4 +115,192 @@ export async function readAgentFiles(cwd) {
     }
     return files;
 }
+const CACHE_DIR = path.join('.guild', 'cache');
+const CACHE_FILE = 'last-ephemeral.json';
+/**
+ * Compute a deterministic hash of agent files.
+ * Sorts by path to ensure consistent ordering.
+ */
+export function hashAgentFiles(files) {
+    const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+    const hash = createHash('sha256');
+    for (const file of sorted) {
+        hash.update(file.path);
+        hash.update('\0');
+        hash.update(file.content);
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+async function readEphemeralCache(cwd) {
+    try {
+        const cachePath = path.join(cwd, CACHE_DIR, CACHE_FILE);
+        const raw = await fs.readFile(cachePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.hash === 'string' && typeof parsed.version_id === 'string') {
+            return { hash: parsed.hash, version_id: parsed.version_id };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeEphemeralCache(cwd, cache) {
+    const dir = path.join(cwd, CACHE_DIR);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, CACHE_FILE), JSON.stringify(cache, null, 2) + '\n');
+}
+/**
+ * Get or create an ephemeral version, skipping the build if files haven't
+ * changed since the last successful ephemeral build.
+ *
+ * Returns the version (cached or newly created), a cache hit flag, and the
+ * computed hash (used by buildEphemeralVersion to write the cache on success).
+ */
+export async function getOrCreateEphemeral(client, agentId, files, cwd, summary, options) {
+    const hash = hashAgentFiles(files);
+    if (options?.noCache) {
+        const version = (await client.post(`/agents/${agentId}/versions`, {
+            files,
+            summary,
+            version_type: 'EPHEMERAL',
+        }));
+        return { version, cached: false, hash };
+    }
+    const cache = await readEphemeralCache(cwd);
+    if (cache && cache.hash === hash) {
+        // Verify the cached version still exists on the server
+        try {
+            const version = (await client.get(`/versions/${cache.version_id}`));
+            if (version.validation_status === 'PASSED') {
+                return { version, cached: true, hash };
+            }
+        }
+        catch {
+            // Version gone or inaccessible — fall through to create new one
+        }
+    }
+    const version = (await client.post(`/agents/${agentId}/versions`, {
+        files,
+        summary,
+        version_type: 'EPHEMERAL',
+    }));
+    return { version, cached: false, hash };
+}
+/**
+ * Build an ephemeral version end-to-end: get-or-create, poll for validation,
+ * cache on success, and report build failures.
+ *
+ * Consolidates the build/poll/cache pattern used by both `guild agent test`
+ * and `guild agent chat`.
+ */
+export async function buildEphemeralVersion(client, agentId, files, cwd, summary, options) {
+    const { version: initial, cached, hash, } = await getOrCreateEphemeral(client, agentId, files, cwd, summary, options);
+    if (cached) {
+        return { version: initial, cached: true };
+    }
+    // Poll for validation to complete
+    const pollResult = await pollUntilComplete({
+        resourceId: initial.id,
+        endpoint: `/versions/${initial.id}`,
+        isComplete: (r) => r.validation_status !== 'PENDING' && r.validation_status !== 'RUNNING',
+        message: 'Building...',
+        successMessage: 'Build finished',
+        timeoutMessage: 'Build timed out',
+        maxAttempts: 120,
+        delayMs: 1000,
+    });
+    if (!pollResult.success || !pollResult.response) {
+        throw new BuildTimeoutError();
+    }
+    const version = pollResult.response;
+    // Cache the successful build so we can skip it next time
+    if (version.validation_status === 'PASSED') {
+        await writeEphemeralCache(cwd, { hash, version_id: version.id });
+    }
+    if (version.validation_status === 'FAILED') {
+        let failedSteps = [];
+        try {
+            const stepsResponse = await client.get(`/versions/${version.id}/validation/steps`);
+            failedSteps = stepsResponse.steps
+                .filter((step) => step.status === 'FAILED')
+                .map((step) => ({ name: step.name, content: step.content ?? undefined }));
+        }
+        catch {
+            // Could not fetch validation details — throw with empty steps
+        }
+        throw new BuildFailedError(failedSteps);
+    }
+    return { version, cached: false };
+}
+// ---------------------------------------------------------------------------
+// Bundle version
+// ---------------------------------------------------------------------------
+/** Thrown when the specified bundle file cannot be found on disk. */
+export class BundleNotFoundError extends Error {
+    constructor(filePath) {
+        super(`Bundle file not found: ${filePath}`);
+        this.name = 'BundleNotFoundError';
+    }
+}
+/**
+ * Upload a pre-built bundle as an ephemeral version.
+ *
+ * The bundle file must be gzip+base64 encoded (the output of
+ * `esbuild ... | gzip | base64`). Source files are included for
+ * dashboard viewing, but the server skips its own build step because
+ * the ready-to-run artifact is already provided.
+ */
+export async function buildBundledVersion(client, agentId, bundlePath, cwd, summary) {
+    try {
+        await fs.access(bundlePath);
+    }
+    catch {
+        throw new BundleNotFoundError(bundlePath);
+    }
+    const bundle = (await fs.readFile(bundlePath, 'utf-8')).trim();
+    let files = [];
+    try {
+        files = await readAgentFiles(cwd);
+    }
+    catch {
+        // No git or missing required files — proceed with bundle-only upload
+    }
+    const initial = (await client.post(`/agents/${agentId}/versions`, {
+        version_type: 'EPHEMERAL',
+        bundle,
+        encoding: 'gzip;base64',
+        files,
+        summary,
+    }));
+    const pollResult = await pollUntilComplete({
+        resourceId: initial.id,
+        endpoint: `/versions/${initial.id}`,
+        isComplete: (r) => r.validation_status !== 'PENDING' && r.validation_status !== 'RUNNING',
+        message: 'Validating bundle...',
+        successMessage: 'Bundle validated',
+        timeoutMessage: 'Bundle validation timed out',
+        maxAttempts: 120,
+        delayMs: 1000,
+    });
+    if (!pollResult.success || !pollResult.response) {
+        throw new BuildTimeoutError('Bundle validation timed out.');
+    }
+    const version = pollResult.response;
+    if (version.validation_status === 'FAILED') {
+        let failedSteps = [];
+        try {
+            const stepsResponse = await client.get(`/versions/${version.id}/validation/steps`);
+            failedSteps = stepsResponse.steps
+                .filter((step) => step.status === 'FAILED')
+                .map((step) => ({ name: step.name, content: step.content ?? undefined }));
+        }
+        catch {
+            // Could not fetch validation details — throw with empty steps
+        }
+        throw new BuildFailedError(failedSteps);
+    }
+    return { version };
+}
 //# sourceMappingURL=agent-helpers.js.map

package/dist/lib/alternate-screen.js

@@ -50,6 +50,8 @@ export function suppressScrollbackClear() {
                 chunk = chunk.replace(CLEAR_TERMINAL, CLEAR_SUBSEQUENT);
             }
         }
+        if (!originalWrite)
+            return false;
         return originalWrite.apply(this, [chunk, ...args]);
     };
     process.stdout.write = patched;

package/dist/lib/api-client.js

@@ -3,7 +3,7 @@
 import axios from 'axios';
 import { getAuthToken, clearAuthToken } from './auth.js';
 import { retry, debug, GuildCLIError, ErrorCodes } from './errors.js';
-import { getGuildcoreUrl } from './config.js';
+import { getUserAgent, getGuildcoreUrl } from './config.js';
 import { getIapHeaders } from './iap.js';
 /**
  * HTTP client for Guild API
@@ -24,6 +24,7 @@ export class GuildAPIClient {
             headers: {
                 'Content-Type': 'application/json',
                 Accept: 'application/json',
+                'User-Agent': getUserAgent(),
             },
         });
         debug(`API Client initialized: ${this.baseUrl}, retry: ${this.enableRetry}, max retries: ${this.maxRetries}`);

package/dist/lib/api-types.d.ts

@@ -361,6 +361,43 @@ export interface CredentialsPolicy {
     updated_at: string;
 }
 export type CredentialsPolicyListResponse = PaginatedResponse<CredentialsPolicy>;
+export type TaskStatus = 'CREATED' | 'DISPATCHED' | 'STARTED' | 'RUNNING' | 'WAITING' | 'ERROR' | 'DONE' | 'INTERRUPTED';
+export interface TokenUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+    total_tokens: number;
+    llm_call_count: number;
+}
+interface TaskBase {
+    id: string;
+    entity_type: string;
+    status: TaskStatus;
+    token_usage: TokenUsage | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface TaskAgent extends TaskBase {
+    entity_type: 'EntTaskAgent';
+    agent: {
+        name: string;
+        full_name?: string;
+    } | null;
+    version: {
+        id: string;
+        version_number?: string;
+    } | null;
+}
+export interface TaskTool extends TaskBase {
+    entity_type: 'EntTaskTool';
+    tool_name: string;
+    tool_call_id: string;
+    request_bytes: number;
+    response_bytes: number;
+    http_status_code: number;
+}
+export type Task = TaskAgent | TaskTool;
 /**
  * Session entity from API responses.
  * Used by: session list

package/dist/lib/config.d.ts

@@ -1,3 +1,6 @@
+export declare function getCliVersion(): string;
+export declare function isDevBuild(): boolean;
+export declare function getUserAgent(): string;
 /**
  * IAP (Identity-Aware Proxy) configuration for internal *.guildai.dev hosts.
  * Users must run `gcloud auth login` with an authorized Google account to access.

package/dist/lib/config.js

@@ -1,5 +1,38 @@
 // Copyright 2026 Guild.ai
 // SPDX-License-Identifier: Apache-2.0
+import { readFileSync } from 'fs';
+import path from 'path';
+const FALLBACK_VERSION = 'unknown';
+let cachedVersion;
+export function getCliVersion() {
+    if (!cachedVersion) {
+        try {
+            const pkg = JSON.parse(readFileSync(path.join(__dirname, '../package.json'), 'utf-8'));
+            cachedVersion = pkg.version ?? FALLBACK_VERSION;
+        }
+        catch {
+            cachedVersion = FALLBACK_VERSION;
+        }
+    }
+    return cachedVersion;
+}
+export function isDevBuild() {
+    try {
+        return !__dirname.includes('node_modules');
+    }
+    catch {
+        return false;
+    }
+}
+export function getUserAgent() {
+    try {
+        const base = `GuildCLI/${getCliVersion()}`;
+        return isDevBuild() ? `${base}/dev` : base;
+    }
+    catch {
+        return 'GuildCLI';
+    }
+}
 /**
  * IAP configuration for shared.guildai.dev
  */

package/dist/lib/output.d.ts

@@ -1,5 +1,5 @@
 import { type Spinner } from './progress.js';
-import type { Agent, AgentVersion, Credentials, CredentialsPolicy, Context, Integration, IntegrationVersion, JobStep, Pagination, Session, Workspace, WorkspaceAgent, Trigger } from './api-types.js';
+import type { Agent, AgentVersion, Credentials, CredentialsPolicy, Context, Integration, IntegrationVersion, JobStep, Pagination, Session, Task, Workspace, WorkspaceAgent, Trigger } from './api-types.js';
 /**
  * Format an agent list as a human-readable table.
  * Shared by agent list and agent search commands.
@@ -40,6 +40,11 @@ export declare function formatWorkspaceTable(workspaces: Workspace[], pagination
  * Used by session list command.
  */
 export declare function formatSessionTable(sessions: Session[], pagination: Pagination): void;
+/**
+ * Format a task list as a human-readable table.
+ * Used by session tasks command.
+ */
+export declare function formatTaskTable(tasks: Task[], pagination: Pagination): void;
 /**
  * Format a trigger list as a human-readable table.
  * Used by trigger list command.

package/dist/lib/output.js

@@ -359,6 +359,56 @@ export function formatSessionTable(sessions, pagination) {
         console.log(chalk.dim(`\nShowing ${showing} of ${pagination.total_count} sessions`));
     }
 }
+/**
+ * Format a task list as a human-readable table.
+ * Used by session tasks command.
+ */
+export function formatTaskTable(tasks, pagination) {
+    if (tasks.length === 0) {
+        console.log(chalk.dim('No tasks found'));
+        return;
+    }
+    const table = new Table({
+        columns: [
+            { name: 'id', title: 'ID', alignment: 'left' },
+            { name: 'name', title: 'NAME', alignment: 'left' },
+            { name: 'status', title: 'STATUS', alignment: 'left' },
+            { name: 'tokens', title: 'TOKENS', alignment: 'left' },
+            { name: 'created', title: 'CREATED', alignment: 'left' },
+        ],
+    });
+    tasks.forEach((task) => {
+        const name = task.entity_type === 'EntTaskAgent'
+            ? task.agent?.full_name || task.agent?.name || '-'
+            : task.tool_name;
+        const statusColor = task.status === 'DONE'
+            ? chalk.green
+            : task.status === 'ERROR'
+                ? chalk.red
+                : task.status === 'RUNNING' ||
+                    task.status === 'STARTED' ||
+                    task.status === 'WAITING'
+                    ? chalk.yellow
+                    : chalk.dim;
+        table.addRow({
+            id: truncate(task.id, 13),
+            name,
+            status: statusColor(task.status),
+            tokens: task.token_usage ? task.token_usage.total_tokens.toLocaleString() : '-',
+            created: task.created_at ? formatRelativeTime(task.created_at) : '',
+        });
+    });
+    table.printTable();
+    const showing = Math.min(pagination.limit, tasks.length);
+    if (pagination.has_more) {
+        const nextOffset = pagination.offset + pagination.limit;
+        console.log(`\nShowing ${showing} of ${pagination.total_count} tasks. ` +
+            chalk.dim(`Use --offset ${nextOffset} to see more.`));
+    }
+    else if (pagination.total_count > showing) {
+        console.log(chalk.dim(`\nShowing ${showing} of ${pagination.total_count} tasks`));
+    }
+}
 /**
  * Format a trigger list as a human-readable table.
  * Used by trigger list command.

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 */

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guildai/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Guild.ai CLI - Build, test, and deploy AI agents",
   "type": "module",
   "main": "dist/index.js",