@useatlas/create 0.0.6 → 0.0.7

package/templates/docker/src/lib/tools/actions/handler.ts

@@ -15,6 +15,7 @@ import type {
   ActionToolResult,
   ActionApprovalMode,
   ActionStatus,
+  RollbackInfo,
 } from "@atlas/api/lib/action-types";
 import type { AtlasRole } from "@atlas/api/lib/auth/types";
 import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
@@ -25,6 +26,29 @@ import { logActionAudit } from "./audit";
 
 const log = createLogger("action-handler");
 
+// ---------------------------------------------------------------------------
+// Timeout helper
+// ---------------------------------------------------------------------------
+
+export class ActionTimeoutError extends Error {
+  constructor(public readonly timeoutMs: number) {
+    super(`Action timed out after ${timeoutMs}ms`);
+    this.name = "ActionTimeoutError";
+  }
+}
+
+function executeWithTimeout<T>(
+  fn: () => Promise<T>,
+  timeoutMs: number | undefined,
+): Promise<T> {
+  if (timeoutMs == null) return fn();
+  let timer: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new ActionTimeoutError(timeoutMs)), timeoutMs);
+  });
+  return Promise.race([fn(), timeoutPromise]).finally(() => clearTimeout(timer!));
+}
+
 // ---------------------------------------------------------------------------
 // In-memory fallback store (when DATABASE_URL is not set)
 // ---------------------------------------------------------------------------
@@ -46,15 +70,29 @@ export function getActionExecutor(actionId: string): ActionExecutor | undefined
   return executorRegistry.get(actionId);
 }
 
+// ---------------------------------------------------------------------------
+// Rollback method registry
+// ---------------------------------------------------------------------------
+
+type RollbackMethodHandler = (params: Record<string, unknown>) => Promise<unknown>;
+const rollbackMethodRegistry = new Map<string, RollbackMethodHandler>();
+
+export function registerRollbackMethod(method: string, handler: RollbackMethodHandler): void {
+  rollbackMethodRegistry.set(method, handler);
+}
+
+export function getRollbackMethod(method: string): RollbackMethodHandler | undefined {
+  return rollbackMethodRegistry.get(method);
+}
+
 // ---------------------------------------------------------------------------
 // Config resolution
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the effective approval mode for an action type.
+ * Resolve the effective action config for an action type (approval, timeout, requiredRole).
  * Priority: per-action override > config defaults > action's defaultApproval > "manual".
  */
-// Note: timeout and maxPerConversation are resolved here but not yet enforced — reserved for future implementation
 export function getActionConfig(
   actionType: string,
   defaultApproval?: ActionApprovalMode,
@@ -86,6 +124,9 @@ export function getActionConfig(
         log.warn({ actionType, value: perAction.requiredRole }, "Per-action requiredRole is not a valid Atlas role — ignoring override");
       }
     }
+    if (typeof perAction.timeout === "number" && perAction.timeout > 0) {
+      timeout = perAction.timeout;
+    }
   }
 
   return { approval, requiredRole, timeout, maxPerConversation };
@@ -149,11 +190,14 @@ const COLUMN_MAP: Record<string, string> = {
   approved_by: "approved_by",
   result: "result",
   error: "error",
+  rollback_info: "rollback_info",
 };
 
+const JSON_COLUMNS: ReadonlySet<string> = new Set(["result", "rollback_info"]);
+
 async function updateActionStatus(
   id: string,
-  updates: Partial<Pick<ActionLogEntry, "status" | "resolved_at" | "executed_at" | "approved_by" | "result" | "error">>,
+  updates: Partial<Pick<ActionLogEntry, "status" | "resolved_at" | "executed_at" | "approved_by" | "result" | "error" | "rollback_info">>,
 ): Promise<void> {
   // Update memory store first
   const existing = memoryStore.get(id);
@@ -170,7 +214,7 @@ async function updateActionStatus(
       const colName = COLUMN_MAP[key];
       if (!colName) throw new Error(`Unknown action_log column key: ${key}`);
       setClauses.push(`${colName} = $${paramIdx}`);
-      params.push(colName === "result" ? JSON.stringify(value) : value);
+      params.push(JSON_COLUMNS.has(colName) ? JSON.stringify(value) : value);
       paramIdx++;
     }
   }
@@ -248,15 +292,20 @@ export async function handleAction(
     // Execute immediately
     const startMs = Date.now();
     try {
-      const result = await executeFn(request.payload);
+      const result = await executeWithTimeout(
+        () => executeFn(request.payload),
+        actionConfig.timeout,
+      );
       const latencyMs = Date.now() - startMs;
 
+      const rbInfo = extractRollbackInfo(result);
       await updateActionStatus(request.id, {
         status: "auto_approved",
         resolved_at: new Date().toISOString(),
         executed_at: new Date().toISOString(),
         approved_by: "system:auto",
         result,
+        ...(rbInfo && { rollback_info: rbInfo }),
       });
       logActionAudit({
         actionId: request.id,
@@ -269,6 +318,24 @@ export async function handleAction(
       return { status: "auto_approved", actionId: request.id, result };
     } catch (err) {
       const latencyMs = Date.now() - startMs;
+
+      if (err instanceof ActionTimeoutError) {
+        await updateActionStatus(request.id, {
+          status: "timed_out",
+          resolved_at: new Date().toISOString(),
+          error: err.message,
+        });
+        logActionAudit({
+          actionId: request.id,
+          actionType: request.actionType,
+          status: "timed_out",
+          latencyMs,
+          timeoutMs: err.timeoutMs,
+          userId,
+        });
+        return { status: "timed_out", actionId: request.id, error: err.message };
+      }
+
       const errorMsg = err instanceof Error ? err.message : String(err);
 
       await updateActionStatus(request.id, {
@@ -285,7 +352,7 @@ export async function handleAction(
         error: errorMsg,
       });
 
-      return { status: "error", actionId: request.id, error: errorMsg };
+      return { status: "failed", actionId: request.id, error: errorMsg };
     }
   }
 
@@ -297,6 +364,78 @@ export async function handleAction(
 // Approval / denial (CAS via PostgreSQL WHERE status = 'pending' RETURNING *; in-memory path uses non-atomic check-then-update)
 // ---------------------------------------------------------------------------
 
+/**
+ * Execute an approved action with timeout handling.
+ * Returns the final entry state (executed, timed_out, or failed).
+ */
+async function executeApprovedAction(
+  actionId: string,
+  entry: ActionLogEntry,
+  executeFn: ActionExecutor,
+  approverId: string,
+): Promise<ActionLogEntry> {
+  const { timeout } = getActionConfig(entry.action_type);
+  const startMs = Date.now();
+  try {
+    const result = await executeWithTimeout(
+      () => executeFn(entry.payload),
+      timeout,
+    );
+    const latencyMs = Date.now() - startMs;
+    const rbInfo = extractRollbackInfo(result);
+
+    await updateActionStatus(actionId, {
+      status: "executed",
+      executed_at: new Date().toISOString(),
+      result,
+      ...(rbInfo && { rollback_info: rbInfo }),
+    });
+    logActionAudit({
+      actionId,
+      actionType: entry.action_type,
+      status: "executed",
+      latencyMs,
+      approverId,
+    });
+
+    const updated = memoryStore.get(actionId);
+    return updated ?? { ...entry, status: "executed" as ActionStatus, executed_at: new Date().toISOString(), result, ...(rbInfo && { rollback_info: rbInfo }) };
+  } catch (err) {
+    const latencyMs = Date.now() - startMs;
+
+    if (err instanceof ActionTimeoutError) {
+      await updateActionStatus(actionId, {
+        status: "timed_out",
+        error: err.message,
+      });
+      logActionAudit({
+        actionId,
+        actionType: entry.action_type,
+        status: "timed_out",
+        latencyMs,
+        timeoutMs: err.timeoutMs,
+        approverId,
+      });
+      return memoryStore.get(actionId) ?? { ...entry, status: "timed_out" as ActionStatus, error: err.message };
+    }
+
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    await updateActionStatus(actionId, {
+      status: "failed",
+      error: errorMsg,
+    });
+    logActionAudit({
+      actionId,
+      actionType: entry.action_type,
+      status: "failed",
+      latencyMs,
+      approverId,
+      error: errorMsg,
+    });
+    return memoryStore.get(actionId) ?? { ...entry, status: "failed" as ActionStatus, error: errorMsg };
+  }
+}
+
 /**
  * Approve a pending action. Returns the updated entry, or null if CAS failed
  * (action already resolved — 409 scenario).
@@ -329,51 +468,8 @@ export async function approveAction(
       approverId,
     });
 
-    // Execute the action
     if (resolveFn) {
-      const startMs = Date.now();
-      try {
-        const result = await resolveFn(entry.payload);
-        const latencyMs = Date.now() - startMs;
-
-        const execRows = await internalQuery(
-          `UPDATE action_log SET status = 'executed', executed_at = now(), result = $1 WHERE id = $2 RETURNING *`,
-          [JSON.stringify(result), actionId],
-        ) as unknown as ActionLogEntry[];
-        const updated = execRows[0] ?? { ...entry, status: "executed" as ActionStatus, executed_at: new Date().toISOString(), result };
-        memoryStore.set(actionId, updated);
-
-        logActionAudit({
-          actionId,
-          actionType: entry.action_type,
-          status: "executed",
-          latencyMs,
-          approverId,
-        });
-
-        return updated;
-      } catch (err) {
-        const latencyMs = Date.now() - startMs;
-        const errorMsg = err instanceof Error ? err.message : String(err);
-
-        const failRows = await internalQuery(
-          `UPDATE action_log SET status = 'failed', error = $1 WHERE id = $2 RETURNING *`,
-          [errorMsg, actionId],
-        ) as unknown as ActionLogEntry[];
-        const failed = failRows[0] ?? { ...entry, status: "failed" as ActionStatus, error: errorMsg };
-        memoryStore.set(actionId, failed);
-
-        logActionAudit({
-          actionId,
-          actionType: entry.action_type,
-          status: "failed",
-          latencyMs,
-          approverId,
-          error: errorMsg,
-        });
-
-        return failed;
-      }
+      return executeApprovedAction(actionId, entry, resolveFn, approverId);
     }
 
     log.warn({ actionId, actionType: entry.action_type }, "Action approved but no executor available — will not execute");
@@ -390,6 +486,7 @@ export async function approveAction(
     resolved_at: new Date().toISOString(),
     approved_by: approverId,
   };
+  memoryStore.set(actionId, approved);
 
   logActionAudit({
     actionId,
@@ -399,52 +496,10 @@ export async function approveAction(
   });
 
   if (resolveFn) {
-    const startMs = Date.now();
-    try {
-      const result = await resolveFn(entry.payload);
-      const latencyMs = Date.now() - startMs;
-      const executed: ActionLogEntry = {
-        ...approved,
-        status: "executed",
-        executed_at: new Date().toISOString(),
-        result,
-      };
-      memoryStore.set(actionId, executed);
-
-      logActionAudit({
-        actionId,
-        actionType: entry.action_type,
-        status: "executed",
-        latencyMs,
-        approverId,
-      });
-
-      return executed;
-    } catch (err) {
-      const latencyMs = Date.now() - startMs;
-      const errorMsg = err instanceof Error ? err.message : String(err);
-      const failed: ActionLogEntry = {
-        ...approved,
-        status: "failed",
-        error: errorMsg,
-      };
-      memoryStore.set(actionId, failed);
-
-      logActionAudit({
-        actionId,
-        actionType: entry.action_type,
-        status: "failed",
-        latencyMs,
-        approverId,
-        error: errorMsg,
-      });
-
-      return failed;
-    }
+    return executeApprovedAction(actionId, approved, resolveFn, approverId);
   }
 
   log.warn({ actionId, actionType: entry.action_type }, "Action approved but no executor available — will not execute");
-  memoryStore.set(actionId, approved);
   return approved;
 }
 
@@ -581,6 +636,133 @@ export async function listPendingActions(opts?: ListActionsOptions): Promise<Act
     .slice(0, limit);
 }
 
+// ---------------------------------------------------------------------------
+// Rollback info extraction
+// ---------------------------------------------------------------------------
+
+/** Statuses from which an action can be rolled back. */
+const ROLLBACKABLE_STATUSES: ReadonlySet<ActionStatus> = new Set(["executed", "auto_approved"]);
+
+/** Extract RollbackInfo from an action execution result, if present. */
+export function extractRollbackInfo(result: unknown): RollbackInfo | null {
+  if (!result || typeof result !== "object") return null;
+  const r = result as Record<string, unknown>;
+  const info = r.rollbackInfo;
+  if (!info || typeof info !== "object") return null;
+  const ri = info as Record<string, unknown>;
+  if (typeof ri.method !== "string") return null;
+  if (!ri.params || typeof ri.params !== "object" || Array.isArray(ri.params)) return null;
+  return { method: ri.method, params: ri.params as Record<string, unknown> };
+}
+
+// ---------------------------------------------------------------------------
+// Rollback
+// ---------------------------------------------------------------------------
+
+/** Best-effort dispatch of a rollback handler. Updates the entry with any error. */
+async function dispatchRollback(
+  actionId: string,
+  entry: ActionLogEntry,
+  rollbackInfo: RollbackInfo,
+  userId: string,
+): Promise<void> {
+  const handler = getRollbackMethod(rollbackInfo.method);
+  if (handler) {
+    try {
+      await handler(rollbackInfo.params);
+      log.info({ actionId, method: rollbackInfo.method }, "Rollback method executed successfully");
+    } catch (err) {
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      log.error({ actionId, method: rollbackInfo.method, err: errorMsg }, "Rollback method failed");
+      await updateActionStatus(actionId, { error: errorMsg });
+      logActionAudit({
+        actionId,
+        actionType: entry.action_type,
+        status: "rolled_back",
+        userId,
+        error: errorMsg,
+      });
+    }
+  } else {
+    const noHandlerMsg = `No rollback handler registered for method: ${rollbackInfo.method}`;
+    log.warn({ actionId, method: rollbackInfo.method }, "No rollback handler registered for method — status updated but rollback not dispatched");
+    await updateActionStatus(actionId, { error: noHandlerMsg });
+  }
+}
+
+/**
+ * Roll back an executed action using its stored rollback_info.
+ *
+ * Rollback is best-effort: the status transitions to "rolled_back" via CAS,
+ * then the rollback method handler is dispatched. If dispatch fails, the error
+ * is logged and stored but the status remains "rolled_back".
+ *
+ * Returns the updated entry, or null if CAS failed (action not in rollbackable state).
+ */
+export async function rollbackAction(
+  actionId: string,
+  userId: string,
+): Promise<ActionLogEntry | null> {
+  const action = await getAction(actionId);
+  if (!action) return null;
+
+  if (!ROLLBACKABLE_STATUSES.has(action.status)) {
+    return null;
+  }
+
+  if (!action.rollback_info) {
+    return null;
+  }
+
+  const rollbackInfo = action.rollback_info;
+
+  // CAS: transition to rolled_back
+  if (hasInternalDB()) {
+    const rows = await internalQuery(
+      `UPDATE action_log
+       SET status = 'rolled_back', resolved_at = now()
+       WHERE id = $1 AND status IN ('executed', 'auto_approved')
+       RETURNING *`,
+      [actionId],
+    ) as unknown as ActionLogEntry[];
+    if (rows.length === 0) return null;
+
+    const entry = rows[0];
+    memoryStore.set(actionId, entry);
+
+    logActionAudit({
+      actionId,
+      actionType: entry.action_type,
+      status: "rolled_back",
+      userId,
+    });
+
+    await dispatchRollback(actionId, entry, rollbackInfo, userId);
+    return memoryStore.get(actionId) ?? entry;
+  }
+
+  // Memory-only fallback
+  const entry = memoryStore.get(actionId);
+  if (!entry || !ROLLBACKABLE_STATUSES.has(entry.status)) return null;
+
+  const rolledBack: ActionLogEntry = {
+    ...entry,
+    status: "rolled_back",
+    resolved_at: new Date().toISOString(),
+  };
+  memoryStore.set(actionId, rolledBack);
+
+  logActionAudit({
+    actionId,
+    actionType: entry.action_type,
+    status: "rolled_back",
+    userId,
+  });
+
+  await dispatchRollback(actionId, rolledBack, rollbackInfo, userId);
+  return memoryStore.get(actionId) ?? rolledBack;
+}
+
 // ---------------------------------------------------------------------------
 // Test helpers
 // ---------------------------------------------------------------------------
@@ -588,4 +770,5 @@ export async function listPendingActions(opts?: ListActionsOptions): Promise<Act
 export function _resetActionStore(): void {
   memoryStore.clear();
   executorRegistry.clear();
+  rollbackMethodRegistry.clear();
 }

package/templates/docker/src/lib/tools/actions/jira.ts

@@ -109,12 +109,12 @@ export async function executeJiraCreate(
       ).map(([field, msg]) => `${field}: ${msg}`);
       detail = [...messages, ...fieldErrors].join("; ") || `HTTP ${response.status}`;
     } catch {
-      // JSON parsing failed — try to get raw text for diagnostics
+      // intentionally ignored: JSON parse failed, fall through to text() attempt
       let rawText = "";
       try {
         rawText = await response.text();
       } catch {
-        // ignore — body may already be consumed
+        // intentionally ignored: body may already be consumed
       }
       detail = rawText
         ? `HTTP ${response.status}: ${rawText.slice(0, 200)}`

package/templates/docker/src/lib/tools/backends/detect.ts

@@ -0,0 +1,16 @@
+/**
+ * Runtime detection helpers for sandbox backend selection.
+ *
+ * Shared between explore.ts and python.ts to avoid duplicating
+ * environment variable checks.
+ */
+
+/** Returns true when running on Vercel or ATLAS_RUNTIME=vercel. */
+export function useVercelSandbox(): boolean {
+  return process.env.ATLAS_RUNTIME === "vercel" || !!process.env.VERCEL;
+}
+
+/** Returns true when ATLAS_SANDBOX_URL is set (sidecar backend available). */
+export function useSidecar(): boolean {
+  return !!process.env.ATLAS_SANDBOX_URL;
+}

package/templates/docker/src/lib/tools/backends/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared sandbox backend utilities.
+ *
+ * Barrel export for types, utilities, nsjail detection, and runtime detection
+ * used by both explore and python sandbox backends.
+ */
+
+export * from "./types";
+export * from "./shared";
+export * from "./nsjail";
+export * from "./detect";