@awak-app/simy-cli 0.2.3 → 0.4.0

package/src/agent.js

@@ -1,6 +1,7 @@
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { dirname, resolve } from "node:path";
+import { createReadStream } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 
 import {
   applyLocalHumanDecision,
@@ -33,7 +34,9 @@ import { isRequestOriginAllowed, resolveWebOrigin } from "./web-origin.js";
 import {
   cleanupExpiredRuns,
   cleanupRunAttachments,
+  prepareRunAttachments,
   stageRunAttachments,
+  stagePreparedRunAttachments,
   referenceLocalAttachmentPaths,
 } from "./local-attachments.js";
 import { discoverWorkspace } from "./workspace-context.js";
@@ -63,6 +66,7 @@ import {
   mergeRepositoryInventory,
   readRepositoryInventory,
   scanGitRepositories,
+  verifyRepositoryIdentity,
   writeRepositoryInventory,
 } from "./repository-inventory.js";
 import {
@@ -80,6 +84,37 @@ import {
   classifyExecutionRequirement,
   EXECUTION_GUARDRAIL_POLICY_VERSION,
 } from "./execution-guardrail.js";
+import {
+  createLocalTask,
+  createLocalTaskId,
+  createLocalTaskRequestFingerprint,
+  hashLocalTaskIdempotencyKey,
+  localTaskArtifact,
+  localTaskSnapshot,
+  LocalTaskRegistry,
+  localTasksRoot,
+  persistLocalTask,
+  prepareLocalTaskWorkspace,
+  restoreLocalTasks,
+  startLocalTask,
+  stopLocalTask,
+} from "./local-task.js";
+import {
+  createDurableLocalTaskApi,
+  createDurableLocalTaskWorker,
+} from "./durable-local-task-worker.js";
+import { createLocalTaskAttachmentStore } from "./local-task-attachment-store.js";
+import {
+  LOCAL_TASK_FILE_CAPABILITY_REGISTRY,
+  LOCAL_TASK_FILE_CAPABILITY_VERSION,
+  LocalTaskFileCapabilityError,
+  localTaskFileErrorPayload,
+} from "./local-task-file-capabilities.js";
+import {
+  LocalTaskScenarioPackError,
+  normalizeLocalTaskScenarioPack,
+  validateLocalTaskScenarioInputs,
+} from "./local-task-scenario-packs.js";
 
 const DEVICE_HEARTBEAT_INTERVAL_MS = 20_000;
 
@@ -95,10 +130,25 @@ export async function startAgent({
   const apiOrigin = resolveWebOrigin(webOrigin);
   const registry = new LocalRunRegistry();
   const directRegistry = new DirectTaskRegistry();
+  const localTaskRegistry = new LocalTaskRegistry();
+  const taskStorageRoot = localTasksRoot(
+    dependencies.localTasksRoot || (sessionRoot ? join(sessionRoot, "tasks") : undefined),
+  );
+  const localTaskAttachmentStore =
+    dependencies.localTaskAttachmentStore ||
+    createLocalTaskAttachmentStore({
+      root:
+        dependencies.localTaskAttachmentRoot ||
+        join(dirname(taskStorageRoot), "attachment-staging"),
+    });
+  await localTaskAttachmentStore.cleanupExpired?.();
   const authNonce = randomBytes(16).toString("base64url");
   let session = await readSession(apiOrigin, sessionRoot);
   if (session && sessionRequiresWebAuthorization(session, apiOrigin)) session = null;
   await cleanupExpiredRuns();
+  for (const task of await restoreLocalTasks({ root: taskStorageRoot })) {
+    localTaskRegistry.create(task);
+  }
   const workspace = dependencies.discoverWorkspace
     ? await dependencies.discoverWorkspace()
     : await discoverWorkspace(dependencies.cwd ?? process.cwd());
@@ -117,10 +167,36 @@ export async function startAgent({
       : [],
   );
   const installMode = updateManager?.snapshot?.()?.install_mode ?? null;
-  const availableCapabilities = withCliContract(
-    await readCapabilities(dependencies),
-    installMode,
-  );
+  const inspectedCapabilities = await readCapabilities(dependencies);
+  const contractSourceCapabilities =
+    inspectedCapabilities?.features?.local_task_control_plane === true
+      ? {
+          ...inspectedCapabilities,
+          features: {
+            ...inspectedCapabilities.features,
+            local_task_control_plane: daemon,
+            pipeline_local_task_artifacts:
+              daemon &&
+              inspectedCapabilities.features.pipeline_local_task_artifacts === true,
+            durable_local_task_attachments: daemon,
+            durable_local_task_steps:
+              daemon &&
+              inspectedCapabilities.features.durable_local_task_steps === true,
+            bounded_local_task_subtasks:
+              daemon &&
+              inspectedCapabilities.features.bounded_local_task_subtasks === true,
+          },
+        }
+      : inspectedCapabilities;
+  let availableCapabilities;
+  const refreshAvailableCapabilities = () => {
+    availableCapabilities = withCliContract(contractSourceCapabilities, installMode, {
+      authenticated:
+        isSessionValid(session, Date.now(), apiOrigin) && Boolean(session?.device_id),
+    });
+    return availableCapabilities;
+  };
+  refreshAvailableCapabilities();
   const heartbeatDevice = dependencies.heartbeatDevice || heartbeatLocalDevice;
   const runOptions = dependencies.runOptions || {};
   const repositoryScanRoot = resolve(
@@ -134,6 +210,7 @@ export async function startAgent({
   let port = requestedPort;
   let heartbeatTimer = null;
   let heartbeatInFlight = null;
+  let durableLocalTaskWorker = null;
 
   const restoreRemoteRuns = async () => {
     if (!isSessionValid(session, Date.now(), apiOrigin) || !session?.device_id) return;
@@ -165,15 +242,21 @@ export async function startAgent({
   const heartbeat = () => {
     if (!isSessionValid(session, Date.now(), apiOrigin)) return Promise.resolve(false);
     if (heartbeatInFlight) return heartbeatInFlight;
-    heartbeatInFlight = heartbeatDevice({
-      apiOrigin,
-      apiBaseUrl: session.api_base_url,
-      token: session.token,
-      port,
-      capabilities: availableCapabilities,
-      repoInventory: repositoryInventory,
-    })
-      .then(() => true)
+    heartbeatInFlight = Promise.resolve()
+      .then(() =>
+        heartbeatDevice({
+          apiOrigin,
+          apiBaseUrl: session.api_base_url,
+          token: session.token,
+          port,
+          capabilities: refreshAvailableCapabilities(),
+          repoInventory: repositoryInventory,
+        }),
+      )
+      .then(async () => {
+        if (durableLocalTaskWorker) await durableLocalTaskWorker.poll();
+        return true;
+      })
       .finally(() => {
         heartbeatInFlight = null;
       });
@@ -234,12 +317,51 @@ export async function startAgent({
   };
 
   const ensureRepositoryIndexed = async (repository) => {
+    const verifyIdentity =
+      dependencies.verifyRepositoryIdentity || verifyRepositoryIdentity;
     const indexed = findRepository(repositoryInventory, repository);
-    if (indexed || !isRepositoryScanAuthorized()) return indexed;
+    const verified = indexed
+      ? await verifyIdentity(indexed, repository)
+      : null;
+    if (verified || !isRepositoryScanAuthorized()) return verified;
     await refreshAuthorizedRepositoryInventory();
-    return findRepository(repositoryInventory, repository);
+    const refreshed = findRepository(repositoryInventory, repository);
+    return refreshed
+      ? await verifyIdentity(refreshed, repository)
+      : null;
   };
 
+  if (
+    daemon &&
+    availableCapabilities?.features?.local_task_control_plane === true
+  ) {
+    const durableApi =
+      dependencies.durableLocalTaskApi ||
+      createDurableLocalTaskApi({
+        getConnection: () => ({
+          apiOrigin,
+          apiBaseUrl: session?.api_base_url,
+          token: session?.token,
+        }),
+        fetchImpl: dependencies.fetch || globalThis.fetch,
+      });
+    const createWorker =
+      dependencies.createDurableLocalTaskWorker ||
+      createDurableLocalTaskWorker;
+    durableLocalTaskWorker = createWorker({
+      api: durableApi,
+      registry: localTaskRegistry,
+      storageRoot: taskStorageRoot,
+      workspaceRoot: dependencies.localTaskWorkspaceRoot,
+      resolveRepository: ensureRepositoryIndexed,
+      runLocalTask: dependencies.runLocalTask || startLocalTask,
+      attachmentStore: localTaskAttachmentStore,
+      getDeviceId: () => session?.device_id || null,
+      beginWork: () => acquireUpdateWork(updateManager),
+      onError: (error) => reportDurableLocalTaskError(error, quiet),
+    });
+  }
+
   const selectRepository = async (run, repository) => {
     if (run) ensureAcceptingNewWork(updateManager);
     const selected = repository?.local_path
@@ -279,10 +401,14 @@ export async function startAgent({
 
       const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
       const agenticLoopPath = canonicalAgenticLoopPath(url.pathname);
+      const startsLocalExecution =
+        url.pathname === "/v1/local-tasks/start" ||
+        url.pathname === "/v1/direct-execution/start";
       if (
         req.method === "POST" &&
-        agenticLoopPath.startsWith("/v1/agentic-loop") &&
-        agenticLoopPath !== "/v1/agentic-loop/preflight"
+        ((agenticLoopPath.startsWith("/v1/agentic-loop") &&
+          agenticLoopPath !== "/v1/agentic-loop/preflight") ||
+          startsLocalExecution)
       ) {
         const releaseUpdateWork = acquireUpdateWork(updateManager);
         if (!releaseUpdateWork) {
@@ -306,7 +432,65 @@ export async function startAgent({
         return;
       }
       if (req.method === "GET" && url.pathname === "/v1/capabilities") {
-        json(res, 200, availableCapabilities);
+        json(res, 200, refreshAvailableCapabilities());
+        return;
+      }
+      if (
+        req.method === "POST" &&
+        url.pathname === "/v1/local-tasks/attachments/stage"
+      ) {
+        if (!req.headers.origin) {
+          json(res, 403, {
+            error: "Open SIMY Web to attach files to a Local Task.",
+            code: "local_task_attachment_web_origin_required",
+            recovery: "reattach_file",
+          });
+          return;
+        }
+        if (!isSessionValid(session, Date.now(), apiOrigin) || !session?.device_id) {
+          json(res, 401, {
+            error: "Reconnect SIMY CLI before attaching files.",
+            code: "local_task_attachment_device_unavailable",
+            recovery: "reattach_file",
+          });
+          return;
+        }
+        try {
+          const files = await readAttachmentStage(req);
+          const prepared = await prepareRunAttachments({ attachments: files });
+          const staged = await localTaskAttachmentStore.stage({
+            deviceId: session.device_id,
+            idempotencyKey: req.headers["idempotency-key"],
+            files: prepared,
+          });
+          res.setHeader("Cache-Control", "no-store");
+          json(res, staged.replayed ? 200 : 201, {
+            ok: true,
+            replayed: staged.replayed,
+            attachment_refs: staged.refs,
+          });
+        } catch (error) {
+          if (error instanceof LocalTaskFileCapabilityError) {
+            json(
+              res,
+              error.code === "local_task_attachment_idempotency_conflict"
+                ? 409
+                : error.code === "local_task_attachment_request_too_large"
+                  ? 413
+                : 400,
+              localTaskFileErrorPayload(error),
+            );
+            return;
+          }
+          json(res, 500, {
+            error:
+              "SIMY CLI could not safely prepare these files. Keep SIMY CLI running and attach them again.",
+            code: "local_task_attachment_stage_failed",
+            recovery: "reattach_file",
+            recovery_action:
+              LOCAL_TASK_FILE_CAPABILITY_REGISTRY.recovery_actions.reattach_file,
+          });
+        }
         return;
       }
       if (req.method === "POST" && agenticLoopPath === "/v1/agentic-loop/preflight") {
@@ -373,6 +557,16 @@ export async function startAgent({
           device_id: typeof body.device_id === "string" ? body.device_id : null,
           api_origin: apiOrigin,
           api_base_url: apiBaseUrl,
+          account_id: typeof body.account_id === "string"
+            ? body.account_id
+            : typeof body.auth_user_id === "string"
+            ? body.auth_user_id
+            : null,
+          organization_id: typeof body.organization_id === "string"
+            ? body.organization_id
+            : typeof body.org_id === "string"
+            ? body.org_id
+            : null,
           expires_at: typeof body.expires_at === "string" ? body.expires_at : expiresAtFromNow(),
         };
         await writeSession(apiOrigin, session, sessionRoot);
@@ -388,6 +582,363 @@ export async function startAgent({
         void synchronizeAuthorizedSession();
         return;
       }
+      const localTaskArtifactMatch = url.pathname.match(
+        /^\/v1\/local-tasks\/([^/]+)\/artifacts\/([^/]+)$/,
+      );
+      if (req.method === "GET" && localTaskArtifactMatch) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const task = localTaskRegistry.get(decodeURIComponent(localTaskArtifactMatch[1]));
+        const artifact = await localTaskArtifact(
+          task,
+          decodeURIComponent(localTaskArtifactMatch[2]),
+        );
+        if (!task || !artifact) {
+          json(res, 404, { error: "Local Task artifact not found" });
+          return;
+        }
+        res.writeHead(200, {
+          "Content-Type": artifact.mime_type,
+          "Content-Length": String(artifact.size_bytes),
+          "Content-Disposition": `attachment; filename*=UTF-8''${encodeURIComponent(artifact.name)}`,
+          "X-Content-Type-Options": "nosniff",
+        });
+        createReadStream(artifact.local_path)
+          .on("error", () => {
+            if (!res.headersSent) json(res, 500, { error: "Local Task artifact is unavailable" });
+            else res.destroy();
+          })
+          .pipe(res);
+        return;
+      }
+      const localTaskStreamMatch = url.pathname.match(/^\/v1\/local-tasks\/([^/]+)\/stream$/);
+      if (req.method === "GET" && localTaskStreamMatch) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        streamLocalTask(res, localTaskRegistry.get(decodeURIComponent(localTaskStreamMatch[1])));
+        return;
+      }
+      const localTaskControlMatch = url.pathname.match(/^\/v1\/local-tasks\/([^/]+)\/control$/);
+      if (req.method === "POST" && localTaskControlMatch) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const task = localTaskRegistry.get(decodeURIComponent(localTaskControlMatch[1]));
+        if (!task) {
+          json(res, 404, { error: "Local Task not found" });
+          return;
+        }
+        const body = await readJson(req);
+        if (body.action !== "stop") {
+          json(res, 400, { error: "Local Task control action must be stop" });
+          return;
+        }
+        await stopLocalTask(task);
+        json(res, 200, { ok: true, task: localTaskSnapshot(task) });
+        return;
+      }
+      const localTaskMatch = url.pathname.match(/^\/v1\/local-tasks\/([^/]+)$/);
+      if (req.method === "GET" && url.pathname === "/v1/local-tasks/reconcile") {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        let task;
+        try {
+          task = localTaskRegistry.getByIdempotencyKey(req.headers["idempotency-key"]);
+        } catch (error) {
+          json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+          return;
+        }
+        if (!task) {
+          res.setHeader("Cache-Control", "no-store");
+          json(res, 404, { error: "Local Task request not found" });
+          return;
+        }
+        res.setHeader("Cache-Control", "no-store");
+        res.setHeader("Location", `/v1/local-tasks/${task.id}`);
+        json(res, 200, { ok: true, replayed: true, task: localTaskSnapshot(task) });
+        return;
+      }
+      if (req.method === "GET" && localTaskMatch) {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const task = localTaskRegistry.get(decodeURIComponent(localTaskMatch[1]));
+        if (!task) {
+          json(res, 404, { error: "Local Task not found" });
+          return;
+        }
+        json(res, 200, { task: localTaskSnapshot(task) });
+        return;
+      }
+      if (req.method === "POST" && url.pathname === "/v1/local-tasks/start") {
+        if (!isSessionValid(session, Date.now(), apiOrigin)) {
+          json(res, 401, { error: "simy session expired; run simy again" });
+          return;
+        }
+        const { body, attachments } = await readCodingLoopStart(req);
+        const instruction = String(body.instruction || "").trim();
+        if (!instruction) {
+          json(res, 400, { error: "instruction is required" });
+          return;
+        }
+        const authorizationInstruction = String(
+          body.authorization_instruction || instruction,
+        ).trim();
+        if (!authorizationInstruction) {
+          json(res, 400, { error: "authorization_instruction is required" });
+          return;
+        }
+        if (body.backend !== "codex" && body.backend !== "claude") {
+          json(res, 400, { error: "backend must be codex or claude" });
+          return;
+        }
+        const idempotencyKey = String(
+          req.headers["idempotency-key"] || body.client_request_id || "",
+        ).trim();
+        const guardrail = classifyExecutionRequirement(authorizationInstruction);
+        if (
+          guardrail.decision !== "direct_executor" ||
+          body.guardrail?.policy_version !== EXECUTION_GUARDRAIL_POLICY_VERSION ||
+          body.guardrail?.decision !== "direct_executor"
+        ) {
+          json(res, 409, {
+            error: "This request is not authorized as a Local Task.",
+            code: "LOCAL_TASK_GUARD_REQUIRED",
+            guardrail,
+          });
+          return;
+        }
+        if (
+          body.operation !== guardrail.operation ||
+          body.permission_mode !== guardrail.permission_mode ||
+          body.max_provider_invocations !== 1
+        ) {
+          json(res, 409, {
+            error: "Local Task permissions do not match the task-routing decision.",
+            code: "LOCAL_TASK_GUARD_MISMATCH",
+            guardrail,
+          });
+          return;
+        }
+        const workspaceMode = String(
+          body.workspace_mode || guardrail.workspace_kind || "task_sandbox",
+        );
+        const repository = String(body.repository || "").trim() || null;
+        if (workspaceMode !== "repository" && workspaceMode !== "task_sandbox") {
+          json(res, 400, {
+            error: "workspace_mode must be task_sandbox or repository",
+            code: "unsupported_local_task_workspace",
+          });
+          return;
+        }
+        let preparedAttachments;
+        try {
+          preparedAttachments = await prepareRunAttachments({
+            attachments,
+            manifest: attachments.length > 0 ? body.attachment_manifest ?? [] : undefined,
+          });
+        } catch (error) {
+          json(res, 400, {
+            error: error instanceof Error ? error.message : "attachment rejected",
+          });
+          return;
+        }
+        let scenarioPack;
+        try {
+          scenarioPack = normalizeLocalTaskScenarioPack(body.scenario_pack);
+          validateLocalTaskScenarioInputs(scenarioPack, {
+            instruction,
+            attachments: preparedAttachments,
+          });
+        } catch (error) {
+          if (error instanceof LocalTaskScenarioPackError) {
+            json(res, 400, {
+              error: error.message,
+              code: error.code,
+              recovery: error.recovery,
+            });
+            return;
+          }
+          throw error;
+        }
+        let requestFingerprint;
+        try {
+          requestFingerprint = createLocalTaskRequestFingerprint({
+            instruction,
+            backend: body.backend,
+            operation: guardrail.operation,
+            permissionMode: guardrail.permission_mode,
+            workspaceMode,
+            repository,
+            expectedOutputs: body.expected_outputs,
+            providerTokenBudget: body.provider_token_budget,
+            timeoutMs: body.timeout_ms,
+            attachmentManifest: preparedAttachments,
+            scenarioPack,
+          });
+          hashLocalTaskIdempotencyKey(idempotencyKey);
+        } catch (error) {
+          json(res, 400, { error: error instanceof Error ? error.message : String(error) });
+          return;
+        }
+        let requestClaim;
+        while (true) {
+          requestClaim = localTaskRegistry.claimRequest(idempotencyKey, requestFingerprint);
+          if (requestClaim.status === "conflict") {
+            json(res, 409, {
+              error: "Idempotency-Key was already used for a different Local Task request.",
+              code: "LOCAL_TASK_IDEMPOTENCY_CONFLICT",
+            });
+            return;
+          }
+          if (requestClaim.status === "existing") {
+            res.setHeader("Location", `/v1/local-tasks/${requestClaim.task.id}`);
+            json(res, 200, {
+              ok: true,
+              replayed: true,
+              task: localTaskSnapshot(requestClaim.task),
+            });
+            return;
+          }
+          if (requestClaim.status === "pending") {
+            const pendingTask = await requestClaim.promise;
+            if (!pendingTask) continue;
+            res.setHeader("Location", `/v1/local-tasks/${pendingTask.id}`);
+            json(res, 200, {
+              ok: true,
+              replayed: true,
+              task: localTaskSnapshot(pendingTask),
+            });
+            return;
+          }
+          break;
+        }
+
+        let requestClaimCompleted = false;
+        let releaseUpdateWork = null;
+        let runtimeOwnsUpdateWork = false;
+        try {
+          if (!acceptsNewWork(updateManager)) {
+            json(res, 503, updateInProgressResponse(updateManager));
+            return;
+          }
+          releaseUpdateWork = acquireUpdateWork(updateManager);
+          if (!releaseUpdateWork) {
+            json(res, 503, updateInProgressResponse(updateManager));
+            return;
+          }
+          const inspection = normalizeBackendInspection(body.backend, availableCapabilities);
+          if (!inspection.compatible) {
+            const summary = backendPreflightSummary(body.backend, inspection);
+            json(res, 409, {
+              error: summary,
+              code: `desktop_executor_${inspection.status}`,
+            });
+            return;
+          }
+
+          let workspace;
+          if (workspaceMode === "repository") {
+            if (!repository) {
+              json(res, 400, { error: "repository is required for this Local Task" });
+              return;
+            }
+            const indexedRepository = await ensureRepositoryIndexed(repository);
+            if (!indexedRepository?.local_path) {
+              json(res, 409, {
+                error: `${repository} is not authorized on this SIMY CLI.`,
+                code: "repository_not_authorized",
+              });
+              return;
+            }
+            const id = createLocalTaskId();
+            const prepared = await prepareLocalTaskWorkspace({
+              taskId: id,
+              root: taskStorageRoot,
+              workspaceRoot: taskStorageRoot,
+            });
+            workspace = {
+              ...prepared,
+              id,
+              workspace_path: indexedRepository.local_path,
+            };
+          } else {
+            const id = createLocalTaskId();
+            workspace = {
+              id,
+              ...(await prepareLocalTaskWorkspace({
+                taskId: id,
+                root: taskStorageRoot,
+                workspaceRoot: dependencies.localTaskWorkspaceRoot,
+              })),
+            };
+          }
+          const stagedAttachments = await stagePreparedRunAttachments({
+            runId: workspace.id,
+            prepared: preparedAttachments,
+            root: taskStorageRoot,
+          });
+          const task = createLocalTask({
+            id: workspace.id,
+            instruction,
+            backend: body.backend,
+            operation: guardrail.operation,
+            permissionMode: guardrail.permission_mode,
+            workspaceMode,
+            repository,
+            workspacePath: workspace.workspace_path,
+            taskRoot: workspace.task_root,
+            inputsRoot: workspace.inputs_root,
+            outputsRoot: workspace.outputs_root,
+            outputsRootExpected: workspace.outputs_root_expected,
+            attachments: stagedAttachments,
+            expectedOutputs: body.expected_outputs,
+            scenarioPack,
+            providerTokenBudget: body.provider_token_budget,
+            timeoutMs: body.timeout_ms,
+            idempotencyKeyHash: hashLocalTaskIdempotencyKey(idempotencyKey),
+            requestFingerprint,
+          });
+          await persistLocalTask(task);
+          localTaskRegistry.create(task);
+          requestClaim.complete(task);
+          requestClaimCompleted = true;
+          const runLocalTask = dependencies.runLocalTask || startLocalTask;
+          task.operation_promise = Promise.resolve(runLocalTask(task))
+            .catch(async (error) => {
+              task.status = "failed";
+              task.control_state = "complete";
+              task.error = error instanceof Error ? error.message : String(error);
+              task.reason_code ||= "local_task_runtime_error";
+              task.completed_at = new Date().toISOString();
+              task.updated_at = task.completed_at;
+              await persistLocalTask(task);
+            })
+            .finally(() => {
+              task.operation_promise = null;
+              releaseUpdateWork();
+            });
+          runtimeOwnsUpdateWork = true;
+          res.setHeader("Location", `/v1/local-tasks/${task.id}`);
+          json(res, 202, {
+            ok: true,
+            replayed: false,
+            task: localTaskSnapshot(task),
+          });
+          return;
+        } finally {
+          if (!requestClaimCompleted) requestClaim.release();
+          if (releaseUpdateWork && !runtimeOwnsUpdateWork) releaseUpdateWork();
+        }
+      }
       const directExecutionMatch = url.pathname.match(/^\/v1\/direct-execution\/([^/]+)$/);
       if (req.method === "GET" && directExecutionMatch) {
         if (!isSessionValid(session, Date.now(), apiOrigin)) {
@@ -486,11 +1037,18 @@ export async function startAgent({
         });
         directRegistry.create(task);
         const runDirectTask = dependencies.runDirectTask || startDirectTask;
-        void Promise.resolve(runDirectTask(task)).catch((error) => {
-          task.status = "failed";
-          task.error = error instanceof Error ? error.message : String(error);
-          task.updated_at = new Date().toISOString();
-        });
+        const releaseUpdateWork = acquireUpdateWork(updateManager);
+        if (!releaseUpdateWork) {
+          json(res, 503, updateInProgressResponse(updateManager));
+          return;
+        }
+        void Promise.resolve(runDirectTask(task))
+          .catch((error) => {
+            task.status = "failed";
+            task.error = error instanceof Error ? error.message : String(error);
+            task.updated_at = new Date().toISOString();
+          })
+          .finally(releaseUpdateWork);
         json(res, 202, { ok: true, task: directTaskSnapshot(task) });
         return;
       }
@@ -878,6 +1436,10 @@ export async function startAgent({
 
       json(res, 404, { error: "not found" });
     } catch (err) {
+      if (err instanceof LocalTaskFileCapabilityError) {
+        json(res, 400, localTaskFileErrorPayload(err));
+        return;
+      }
       json(res, 500, { error: err instanceof Error ? err.message : "internal error" });
     }
   });
@@ -915,23 +1477,38 @@ export async function startAgent({
     startHeartbeatTimer();
   }
 
+  let shutdownPromise = null;
+  const shutdown = () => {
+    if (shutdownPromise) return shutdownPromise;
+    shutdownPromise = (async () => {
+      if (heartbeatTimer) clearInterval(heartbeatTimer);
+      await durableLocalTaskWorker?.close?.();
+      updateManager?.stop?.();
+      registry.close();
+      localTaskRegistry.close();
+    })();
+    return shutdownPromise;
+  };
   server.on("close", () => {
-    if (heartbeatTimer) clearInterval(heartbeatTimer);
-    updateManager?.stop?.();
-    registry.close();
+    void shutdown().catch((error) => reportDurableLocalTaskError(error, quiet));
   });
   return {
     server,
     port,
     registry,
     directRegistry,
+    localTaskRegistry,
+    durableLocalTaskWorker,
+    shutdown,
     webOrigin: apiOrigin,
     get loginUrl() {
       return loginUrl?.toString() ?? null;
     },
     workspace,
     repositoryScanRoot,
-    capabilities: availableCapabilities,
+    get capabilities() {
+      return refreshAvailableCapabilities();
+    },
     updates: updateManager,
     controls: {
       repositoryInventory: () => [...repositoryInventory],
@@ -1132,6 +1709,13 @@ function reportHeartbeatError(error, quiet) {
   );
 }
 
+function reportDurableLocalTaskError(error, quiet) {
+  if (quiet) return;
+  console.error(
+    `SIMY Local Task worker: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
 function reportStartupConnectionError(error, quiet) {
   if (quiet) return;
   console.error(
@@ -1212,6 +1796,18 @@ async function capabilities() {
       executor_version_preflight: true,
       desktop_executor: true,
       direct_execution: true,
+      local_tasks: true,
+      local_task_attachments: true,
+      local_task_artifacts: true,
+      local_task_streaming: true,
+      local_task_idempotency: true,
+      local_task_reconciliation: true,
+      local_task_control_plane: true,
+      pipeline_local_task_artifacts: true,
+      durable_local_task_attachments: true,
+      durable_local_task_scenario_packs: true,
+      durable_local_task_steps: true,
+      bounded_local_task_subtasks: true,
     },
     session_ttl_hours: 48,
   };
@@ -1375,6 +1971,38 @@ function canonicalAgenticLoopPath(pathname) {
   return pathname.replace(/^\/v1\/coding-loop(?=\/|$)/, "/v1/agentic-loop");
 }
 
+function streamLocalTask(res, task) {
+  if (!task) {
+    json(res, 404, { error: "Local Task not found" });
+    return;
+  }
+  res.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive",
+  });
+  const send = (event, data) => {
+    res.write(`event: ${event}\n`);
+    res.write(`data: ${JSON.stringify(data)}\n\n`);
+  };
+  send("snapshot", localTaskSnapshot(task));
+  const listener = (event) => {
+    send(event.type || "event", event);
+    if (["succeeded", "failed", "stopped"].includes(event.state)) {
+      send("snapshot", localTaskSnapshot(task));
+    }
+  };
+  task.emitter.on("event", listener);
+  const heartbeat = setInterval(() => res.write(": heartbeat\n\n"), 15_000);
+  heartbeat.unref?.();
+  const close = () => {
+    clearInterval(heartbeat);
+    task.emitter.off("event", listener);
+  };
+  res.on("close", close);
+  res.on("error", close);
+}
+
 function streamRun(res, run) {
   if (!run) {
     json(res, 404, { error: "run not found" });
@@ -1408,7 +2036,11 @@ function applyCors(req, res, webOrigin) {
       res.setHeader("Access-Control-Allow-Private-Network", "true");
     }
   }
-  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+  res.setHeader(
+    "Access-Control-Allow-Headers",
+    "Content-Type, Authorization, Idempotency-Key",
+  );
+  res.setHeader("Access-Control-Expose-Headers", "Location");
   res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
 }
 
@@ -1428,20 +2060,91 @@ async function readCodingLoopStart(req) {
   if (!contentType.toLowerCase().startsWith("multipart/form-data")) {
     return { body: await readJson(req), attachments: [] };
   }
+  const form = await readMultipartForm(req);
+  const payload = form.get("payload");
+  if (typeof payload !== "string") throw new Error("multipart payload field is required");
+  const attachments = form
+    .getAll("attachments")
+    .filter((value) => value && typeof value === "object" && typeof value.arrayBuffer === "function");
+  return { body: JSON.parse(payload), attachments };
+}
+
+async function readAttachmentStage(req) {
+  const contentType = String(req.headers["content-type"] || "");
+  if (!contentType.toLowerCase().startsWith("multipart/form-data")) {
+    throw new LocalTaskFileCapabilityError(
+      "Choose files to attach before continuing.",
+      {
+        code: "local_task_attachment_multipart_required",
+        recoveryAction: {
+          id: "reattach_file",
+          label: "Attach the files again",
+          description: "Choose the original files again.",
+        },
+      },
+    );
+  }
+  const form = await readMultipartForm(req);
+  const requestedVersion = form.get("capability_version");
+  if (
+    requestedVersion !== null &&
+    requestedVersion !== LOCAL_TASK_FILE_CAPABILITY_VERSION
+  ) {
+    throw new LocalTaskFileCapabilityError(
+      "Update SIMY CLI before attaching files.",
+      {
+        code: "local_task_attachment_version_unsupported",
+        recoveryAction: {
+          id: "update_cli",
+          label: "Update SIMY CLI",
+          description: "Update and restart SIMY CLI, then attach the files again.",
+        },
+      },
+    );
+  }
+  // Caller-provided names, MIME types, sizes, and hashes are intentionally not
+  // trusted. The CLI derives and verifies the complete manifest from File bytes.
+  return form
+    .getAll("attachments")
+    .filter(
+      (value) =>
+        value &&
+        typeof value === "object" &&
+        typeof value.arrayBuffer === "function",
+    );
+}
+
+export async function readMultipartForm(
+  req,
+  { maxBytes = 52 * 1024 * 1024 } = {},
+) {
+  const contentType = String(req.headers["content-type"] || "");
+  const declaredSize = Number(req.headers["content-length"]);
+  if (Number.isFinite(declaredSize) && declaredSize > maxBytes) {
+    throw multipartTooLargeError();
+  }
   const chunks = [];
   let size = 0;
   for await (const chunk of req) {
     size += chunk.length;
-    if (size > 52 * 1024 * 1024) throw new Error("attachment request exceeds the 52 MB limit");
+    if (size > maxBytes) throw multipartTooLargeError();
     chunks.push(Buffer.from(chunk));
   }
-  const form = await new Response(Buffer.concat(chunks), {
+  return new Response(Buffer.concat(chunks), {
     headers: { "Content-Type": contentType },
   }).formData();
-  const payload = form.get("payload");
-  if (typeof payload !== "string") throw new Error("multipart payload field is required");
-  const attachments = form
-    .getAll("attachments")
-    .filter((value) => value && typeof value === "object" && typeof value.arrayBuffer === "function");
-  return { body: JSON.parse(payload), attachments };
+}
+
+function multipartTooLargeError() {
+  return new LocalTaskFileCapabilityError(
+    "The attached files are larger than the 50 MiB request limit.",
+    {
+      code: "local_task_attachment_request_too_large",
+      recoveryAction: {
+        id: "reduce_file_size",
+        label: "Use smaller files",
+        description: "Compress, shorten, or split the files before attaching them again.",
+      },
+    },
+  );
 }