@profoundlogic/coderflow-cli 0.12.144 → 0.13.0

package/README.md

@@ -51,6 +51,15 @@ coder discard --yes
 ## Attaching to Containers
 
 ```bash
+# Discover interactive containers and running containers retained by completed tasks
+coder containers
+
+# Include stopped, unknown-state, and active-task containers
+coder containers --all
+
+# Emit machine-readable output without a human-oriented preamble
+coder containers --json
+
 # Connect to last container
 coder attach
 
@@ -59,8 +68,28 @@ coder attach --shell
 
 # Connect to specific container
 coder attach <container-id>
+
+# Connect to a completed task's retained container without finding its container ID
+coder attach <task-id>
+
+# Show task state and retained-container state separately
+coder status <task-id>
+
+# Emit task and container status as JSON
+coder status <task-id> --json
 ```
 
+The default container list preserves existing interactive-container entries and
+adds running retained-task containers. Retained entries show both task status
+and container status plus an attach command using the public task ID.
+Task-backed entries require both container-shell access and normal task
+visibility; containers for private (`shared: false`) tasks are shown only to
+owners who retain `tasks:view` or an administrator with `tasks:view_any`.
+The `tasks:view_any` permission is independently sufficient for private-task
+visibility.
+When supplying a container ID directly, use the full ID or an unambiguous
+prefix of at least 12 hexadecimal characters.
+
 ## Configuration and Profiles
 
 Manage connection settings:

package/coder.js

@@ -116,7 +116,7 @@ async function main() {
         break;
 
       case 'status':
-        await getStatus(args[1]);
+        await getStatus(args[1], args.slice(2));
         break;
 
       case 'results':

package/lib/commands/attach.js

@@ -1,11 +1,61 @@
 /**
- * Command: coder attach [container-id] - Attach to a running container
+ * Command: coder attach [container-or-task-id] - Attach to a running container
  */
 
 import { request } from '../http-client.js';
 import { getLastContainerId, saveLastContainerId } from '../config.js';
 import { connectTerminal } from '../terminal-client.js';
 
+export function looksLikeTaskId(value) {
+  return /^\d{10,}-[a-z0-9]+$/i.test(value || '');
+}
+
+export function formatAttachLookupError(error) {
+  return error?.serverMessage
+    || error?.responseBody?.message
+    || error?.message
+    || 'Unknown error';
+}
+
+/**
+ * Resolve either a task ID or a container ID to attachable container details.
+ */
+export async function resolveAttachTarget(target, requestFn = request) {
+  if (!looksLikeTaskId(target)) {
+    return {
+      containerInfo: await requestFn(`/containers/${encodeURIComponent(target)}`, { exitOnError: false }),
+      taskId: null
+    };
+  }
+
+  const task = await requestFn(`/tasks/${encodeURIComponent(target)}`, { exitOnError: false });
+  if (!task.containerId) {
+    throw new Error(`Task ${target} does not have a retained container`);
+  }
+  if (task.containerState === 'not_found') {
+    throw new Error(`Task ${target}'s retained container no longer exists`);
+  }
+
+  let containerInfo;
+  try {
+    containerInfo = await requestFn(`/containers/${encodeURIComponent(task.containerId)}`, { exitOnError: false });
+  } catch (error) {
+    if (error.statusCode === 404) {
+      throw new Error(`Task ${target}'s retained container no longer exists`, { cause: error });
+    }
+    throw error;
+  }
+  return {
+    containerInfo: {
+      ...containerInfo,
+      isTaskContainer: true,
+      taskId: containerInfo.taskId || target,
+      taskStatus: containerInfo.taskStatus || task.status
+    },
+    taskId: target
+  };
+}
+
 export async function attachToContainer(args = []) {
   let containerId = null;
   let startShell = false;
@@ -38,7 +88,7 @@ export async function attachToContainer(args = []) {
     if (!containerId) {
       console.error('Error: No container ID specified and no previous container found.');
       console.error('\nUsage:');
-      console.error('  coder attach <container-id>    # Attach to specific container');
+      console.error('  coder attach <container-or-task-id>  # Attach to specific container or task');
       console.error('  coder attach                   # Attach to last container');
       console.error('\nTo see available containers, run:');
       console.error('  coder containers');
@@ -46,15 +96,20 @@ export async function attachToContainer(args = []) {
     }
     console.log(`Attaching to last container: ${containerId}`);
   } else {
-    console.log(`Attaching to container: ${containerId}`);
+    const targetType = looksLikeTaskId(containerId) ? 'task' : 'container';
+    console.log(`Attaching to ${targetType}: ${containerId}`);
   }
 
   // Fetch container info from server to verify it exists and get details
   let containerInfo;
   try {
-    containerInfo = await request(`/containers/${containerId}`);
+    const resolved = await resolveAttachTarget(containerId);
+    containerInfo = resolved.containerInfo;
+    if (resolved.taskId) {
+      console.log(`Resolved task to container: ${containerInfo.containerId}`);
+    }
   } catch (error) {
-    console.error(`\n✗ Failed to find container: ${error.message}`);
+    console.error(`\n✗ Failed to find container: ${formatAttachLookupError(error)}`);
     console.error('\nTo see available containers, run:');
     console.error('  coder containers');
     process.exit(1);
@@ -69,6 +124,7 @@ export async function attachToContainer(args = []) {
   console.log(`  Status:         ${containerInfo.status}`);
   if (containerInfo.isTaskContainer) {
     console.log(`  Type:           Task container (${containerInfo.taskId})`);
+    console.log(`  Task Status:    ${containerInfo.taskStatus || 'unknown'}`);
   }
 
   if (containerInfo.status !== 'running') {

package/lib/commands/containers.js

@@ -38,6 +38,24 @@ function parseCleanArgs(args) {
   return options;
 }
 
+function parseListArgs(args) {
+  const options = { json: false, all: false };
+
+  for (const arg of args) {
+    if (arg === '--json') {
+      options.json = true;
+    } else if (arg === '--all' || arg === '-a') {
+      options.all = true;
+    } else {
+      console.error(`Error: Unknown option: ${arg}`);
+      console.error('Usage: coder containers [--all] [--json]');
+      process.exit(1);
+    }
+  }
+
+  return options;
+}
+
 async function confirm(message) {
   const rl = createInterface({
     input: process.stdin,
@@ -84,18 +102,38 @@ function filterContainers(containers, options) {
   });
 }
 
-async function fetchContainers() {
-  const data = await request('/containers');
+async function fetchContainers({ includeTaskContainers = false } = {}, requestFn = request) {
+  const path = includeTaskContainers ? '/containers?include=tasks' : '/containers';
+  const data = await requestFn(path);
   return data.containers || [];
 }
 
-async function listContainers() {
-  console.log('Fetching Coder containers...\n');
+export async function listContainers(args = [], requestFn = request) {
+  const options = parseListArgs(args);
+  if (!options.json) {
+    console.log('Fetching Coder containers...\n');
+  }
 
-  const containers = await fetchContainers();
+  const fetchedContainers = await fetchContainers({ includeTaskContainers: true }, requestFn);
+  // Interactive containers preserve the legacy list behavior. The default task
+  // view focuses on the newly discoverable/attachable case from this guide:
+  // retained containers that are still running. --all exposes the rest.
+  const containers = options.all
+    ? fetchedContainers
+    : fetchedContainers.filter(container => (
+      !container.isTaskContainer || (container.retained && container.status === 'running')
+    ));
+
+  if (options.json) {
+    console.log(JSON.stringify({ count: containers.length, containers }, null, 2));
+    return;
+  }
 
   if (containers.length === 0) {
     console.log('No Coder containers found.');
+    if (!options.all) {
+      console.log('Use "coder containers --all" to include stopped, unknown-state, and active-task containers.');
+    }
     return;
   }
 
@@ -105,6 +143,17 @@ async function listContainers() {
     const statusIcon = container.status === 'running' ? '▶' : '■';
     console.log(`  ${statusIcon} ${container.name} (${container.containerId})`);
     console.log(`    Status:  ${container.status}`);
+    if (container.isTaskContainer) {
+      console.log(`    Type:    ${container.retained ? 'Retained task container' : 'Task container'}`);
+      console.log(`    Task:    ${container.taskId}`);
+      console.log(`    Task status: ${container.taskStatus || 'unknown'}`);
+      if (container.taskName) {
+        console.log(`    Task name:   ${container.taskName}`);
+      }
+      if (container.status === 'running') {
+        console.log(`    Attach:  coder attach ${container.taskId}`);
+      }
+    }
     if (container.environment) {
       console.log(`    Env:     ${container.environment}`);
     }
@@ -115,18 +164,20 @@ async function listContainers() {
   }
 }
 
-async function deleteContainer(container) {
-  await request(`/containers/${container.name}`, {
+async function deleteContainer(container, requestFn = request) {
+  await requestFn(`/containers/${container.name}`, {
     method: 'DELETE'
   });
 }
 
-async function cleanContainers(args) {
+export async function cleanContainers(args, requestFn = request) {
   const options = parseCleanArgs(args);
 
   console.log('Fetching Coder containers...\n');
 
-  const allContainers = await fetchContainers();
+  // Task containers have their own lifecycle and must never be candidates for
+  // the interactive-container cleanup command.
+  const allContainers = await fetchContainers({}, requestFn);
 
   if (allContainers.length === 0) {
     console.log('No Coder containers found. Nothing to clean.');
@@ -181,7 +232,7 @@ async function cleanContainers(args) {
 
   for (const container of containersToDelete) {
     try {
-      await deleteContainer(container);
+      await deleteContainer(container, requestFn);
       deletedCount += 1;
     } catch (error) {
       console.error(`✗ Failed to delete ${container.name}: ${error.message}`);
@@ -196,17 +247,19 @@ async function cleanContainers(args) {
   }
 }
 
-export async function handleContainers(args = []) {
+export async function handleContainers(args = [], requestFn = request) {
   const subcommand = args[0];
 
   if (subcommand === 'clean') {
-    await cleanContainers(args.slice(1));
-  } else if (!subcommand) {
-    await listContainers();
+    await cleanContainers(args.slice(1), requestFn);
+  } else if (!subcommand || subcommand.startsWith('-')) {
+    await listContainers(args, requestFn);
   } else {
     console.error(`Error: Unknown subcommand: ${subcommand}`);
-    console.error('Usage: coder containers [clean]');
-    console.error('  coder containers              # List all containers');
+    console.error('Usage: coder containers [--all] [--json|clean]');
+    console.error('  coder containers              # List interactive and task containers');
+    console.error('  coder containers --all        # Include stopped, unknown, and active-task containers');
+    console.error('  coder containers --json       # List containers as JSON');
     console.error('  coder containers clean        # Clean containers');
     process.exit(1);
   }

package/lib/commands/login.js

@@ -235,6 +235,14 @@ async function ssoLogin() {
         console.error(`Error: Lost connection to server: ${error.message}`);
         process.exit(1);
       }
+      if (error.code === 'INVALID_SSO_APPROVAL_RESPONSE') {
+        process.removeListener('SIGINT', cleanup);
+        process.stdout.write('\r' + ' '.repeat(60) + '\r');
+        console.error('');
+        console.error(`Error: ${error.message}.`);
+        console.error('Please update the CLI/server or contact your administrator.');
+        process.exit(1);
+      }
       // For other errors, continue polling
     }
 

package/lib/commands/status.js

@@ -4,16 +4,31 @@
 
 import { request } from '../http-client.js';
 
-export async function getStatus(taskId) {
+export async function getStatus(taskId, args = [], requestFn = request) {
   if (!taskId) {
     console.error('Error: Task ID required');
     console.error('Usage: coder status <task-id>');
     process.exit(1);
   }
 
-  console.log(`Fetching status for task ${taskId}...`);
+  const json = args.includes('--json');
+  const unknownOption = args.find(arg => arg !== '--json');
+  if (unknownOption) {
+    console.error(`Error: Unknown option: ${unknownOption}`);
+    console.error('Usage: coder status <task-id> [--json]');
+    process.exit(1);
+  }
 
-  const data = await request(`/tasks/${taskId}`);
+  if (!json) {
+    console.log(`Fetching status for task ${taskId}...`);
+  }
+
+  const data = await requestFn(`/tasks/${taskId}`);
+
+  if (json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
 
   console.log(`\nTask Status:`);
   console.log(`  Task ID:      ${data.taskId}`);
@@ -28,6 +43,20 @@ export async function getStatus(taskId) {
     console.log(`  Exit Code:    ${data.exitCode}`);
   }
 
+  if (data.containerId) {
+    const containerState = data.containerState || 'unknown';
+    const containerStateLabel = containerState === 'not_found'
+      ? 'not found'
+      : (containerState === 'exited' || containerState === 'dead' ? 'stopped' : containerState);
+    console.log(`  Container ID: ${data.containerId.substring(0, 12)}`);
+    console.log(`  Container:    ${containerStateLabel}`);
+    if (containerState === 'running') {
+      console.log(`  Attach:       coder attach ${taskId}`);
+    }
+  } else {
+    console.log('  Container:    not available');
+  }
+
   // Custom task detail fields (per-environment definitions; values on the task)
   const customFields = data.customFields || {};
   if (Object.keys(customFields).length > 0) {

package/lib/config.js

@@ -165,6 +165,10 @@ export async function getCredentialsPathForDisplay() {
  * Save API key to config file or active profile
  */
 export async function saveApiKey(apiKey) {
+  if (typeof apiKey !== 'string' || apiKey.trim().length === 0) {
+    throw new Error('Cannot save an empty API key');
+  }
+
   // Check if there's an active profile (including CLI override)
   const activeProfileName = cliProfileOverride || await getActiveProfileName();
 

package/lib/help.js

@@ -38,12 +38,12 @@ Examples:
 `,
 
   attach: `
-Usage: coder attach [container-id] [options]
+Usage: coder attach [container-or-task-id] [options]
 
 Connect to a running container.
 
 Arguments:
-  container-id          Container ID to attach to (optional - uses last container if omitted)
+  container-or-task-id  Container or task ID to attach to (optional - uses last container if omitted)
 
 Options:
   --agent=<agent>       Agent to use (claude, codex, gemini, bob, grok, kimi)
@@ -52,6 +52,7 @@ Options:
 Examples:
   coder attach                          # Reconnect to last container
   coder attach 188b8e72d656             # Connect to specific container
+  coder attach 1784748839353-e7hk4lh2c  # Connect to a task's retained container
   coder attach --shell                  # Connect with bash shell
   coder attach --agent=codex            # Connect with specific agent
 `,
@@ -139,13 +140,16 @@ Examples:
 `,
 
   status: `
-Usage: coder status <task-id>
+Usage: coder status <task-id> [--json]
 
-Check the status of a task.
+Check task status and retained-container availability.
 
 Arguments:
   task-id               Task ID to check (required)
 
+Options:
+  --json                Print machine-readable JSON only
+
 Examples:
   coder status 1759542727986-3uoyf48lr
 `,
@@ -275,11 +279,16 @@ Examples:
   containers: `
 Usage: coder containers [command] [options]
 
-List or clean containers.
+List or clean containers. The default list includes interactive containers and
+running task containers retained after completion.
 
 Commands:
-  (none)                List all containers
-  clean                 Clean up containers
+  (none)                List interactive and task containers
+  clean                 Clean up interactive containers
+
+Options (for list):
+  --all, -a             Include stopped, unknown-state, and active-task containers
+  --json                Print machine-readable JSON only
 
 Options (for clean):
   --stopped             Clean stopped containers
@@ -289,6 +298,8 @@ Options (for clean):
 
 Examples:
   coder containers
+  coder containers --all
+  coder containers --json
   coder containers clean --stopped --yes
   coder containers clean --older-than=7d --dry-run
 `
@@ -315,7 +326,7 @@ Usage: coder <command> [options]
 Commands:
   coder apply [task-id]                              Apply patches from completed task to local repos
   coder discard [--env=<environment>] [--yes]        Discard applied changes from repos
-  coder attach [container-id] [options]              Connect to a running container
+  coder attach [container-or-task-id] [options]      Connect to a running container
 
 Setup:
   coder login [--sso]                                Authenticate with server
@@ -355,7 +366,7 @@ Applying Changes:
   coder discard [--env=<environment>] [--yes]        Discard applied changes from repos
 
 Connecting to Containers:
-  coder attach [container-id] [--agent=<agent>] [--shell]   Connect to a running container
+  coder attach [container-or-task-id] [--agent=<agent>] [--shell]   Connect to a running container
 
 Setup & Configuration:
   coder login [--sso]                                Authenticate with server

package/lib/http-client.js

@@ -4,6 +4,48 @@
 
 import { getServerUrl, getApiKey } from './config.js';
 
+/**
+ * Build a consistent error object from an HTTP error response.
+ */
+export function buildHttpError(status, data) {
+  let message;
+  let detailedError = null;
+
+  if (typeof data === 'string') {
+    message = data.trim() || `HTTP ${status}`;
+    detailedError = data.trim();
+  } else {
+    // A 400 response commonly uses `error` as a generic label ("Bad Request")
+    // and `message` for the actionable reason. Surface the useful reason first.
+    message = (status === 400 && data?.message)
+      || data?.error
+      || data?.message
+      || `HTTP ${status}`;
+
+    if (data?.error && data?.message) {
+      detailedError = `${data.error}: ${data.message}`;
+    } else if (data?.message) {
+      detailedError = data.message;
+    } else if (data?.error) {
+      detailedError = data.error;
+    }
+  }
+
+  const error = new Error(message);
+  error.detailedError = detailedError;
+  error.statusCode = status;
+  if (data && typeof data === 'object') {
+    error.responseBody = data;
+    error.serverMessage = typeof data.message === 'string' ? data.message : null;
+    for (const field of ['errorCode', 'requiredPermission', 'containerId', 'taskId', 'details']) {
+      if (Object.prototype.hasOwnProperty.call(data, field)) {
+        error[field] = data[field];
+      }
+    }
+  }
+  return error;
+}
+
 /**
  * Format a helpful error message based on error type
  */
@@ -106,10 +148,9 @@ function formatErrorMessage(error, url, response, serverUrl) {
 export async function request(path, options = {}) {
   const serverUrl = await getServerUrl();
   const url = `${serverUrl}${path}`;
+  const { parse = 'json', exitOnError = true, ...fetchOptions } = options;
 
   try {
-    const { parse = 'json', ...fetchOptions } = options;
-
     // Get API key and add to headers if available
     const apiKey = await getApiKey();
     const headers = {
@@ -140,30 +181,9 @@ export async function request(path, options = {}) {
     }
 
     if (!response.ok) {
-      let message;
-      let detailedError = null;
-
-      if (typeof data === 'string') {
-        message = data.trim() || `HTTP ${response.status}`;
-        // Try to parse error details from string response
-        detailedError = data.trim();
-      } else {
-        message = data?.error || data?.message || `HTTP ${response.status}`;
-        // Capture additional error details if available
-        if (data?.error && data?.message) {
-          detailedError = `${data.error}: ${data.message}`;
-        } else if (data?.message) {
-          detailedError = data.message;
-        } else if (data?.error) {
-          detailedError = data.error;
-        }
-      }
-
-      const error = new Error(message);
-      error.detailedError = detailedError;
-      error.statusCode = response.status;
+      const error = buildHttpError(response.status, data);
 
-      if (formatErrorMessage(error, url, response, serverUrl)) {
+      if (exitOnError && formatErrorMessage(error, url, response, serverUrl)) {
         process.exit(1);
       }
       throw error;
@@ -172,7 +192,7 @@ export async function request(path, options = {}) {
     return data;
   } catch (error) {
     // Handle network/connection errors
-    if (formatErrorMessage(error, url, null, serverUrl)) {
+    if (!error.statusCode && exitOnError && formatErrorMessage(error, url, null, serverUrl)) {
       process.exit(1);
     }
     throw error;

package/lib/oidc.js

@@ -111,11 +111,18 @@ export async function pollDeviceFlow(deviceCode) {
   }
 
   const data = await response.json();
+  const apiKey = data.api_key || data.apiKey;
+
+  if (data.status === 'approved' || apiKey) {
+    if (!apiKey) {
+      const error = new Error('SSO approval response did not include an API key');
+      error.code = 'INVALID_SSO_APPROVAL_RESPONSE';
+      throw error;
+    }
 
-  if (data.status === 'approved' || data.apiKey) {
     return {
       status: 'approved',
-      apiKey: data.apiKey,
+      apiKey,
       user: data.user
     };
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profoundlogic/coderflow-cli",
-  "version": "0.12.144",
+  "version": "0.13.0",
   "description": "AI Coder CLI - Command-line interface for managing AI coding tasks",
   "main": "coder.js",
   "type": "module",
@@ -12,7 +12,7 @@
     "test:all": "node --test tests/**/*.test.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "files": [
     "coder.js",
@@ -28,8 +28,8 @@
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderflow.ai",
   "dependencies": {
-    "ws": "^8.18.0",
-    "@inquirer/prompts": "^7.2.1",
-    "open": "^10.1.0"
+    "ws": "^8.21.1",
+    "@inquirer/prompts": "^8.5.2",
+    "open": "^11.0.0"
   }
 }