@codemation/host 0.7.0 → 0.9.0

package/src/credentials/InternalCredentialsBindingRegistrar.ts

@@ -0,0 +1,83 @@
+import { inject, injectable } from "@codemation/core";
+import type { Hono } from "hono";
+import type { Logger, LoggerFactory } from "../application/logging/Logger";
+import { ApplicationRequestError } from "../application/ApplicationRequestError";
+import { ApplicationTokens } from "../applicationTokens";
+import { CredentialBindingService } from "../domain/credentials/CredentialServices";
+import { InternalHmacAuthMiddleware } from "../pairing/InternalHmacAuthMiddleware";
+import type { InternalHonoApiRouteRegistrar } from "../presentation/http/hono/InternalHonoApiRouteRegistrar";
+
+/**
+ * Body shape pushed from the control-plane concierge when binding a
+ * credential instance to a workflow node slot.
+ *
+ * Note: the original story brief described the body as
+ * `{ credentialInstanceId, nodeId, slotName }`, but `CredentialBinding`
+ * requires a `workflowId` and the codebase uses `slotKey` (not `slotName`).
+ * The request shape was corrected here and on the matching concierge tool.
+ */
+type CredentialBindingBody = Readonly<{
+  workflowId: string;
+  nodeId: string;
+  slotKey: string;
+  credentialInstanceId: string;
+}>;
+
+/**
+ * Registers POST /internal/credentials/binding — HMAC-verified endpoint that
+ * lets the control-plane concierge bind a credential instance to a workflow
+ * node slot on behalf of a workspace user.
+ */
+@injectable()
+export class InternalCredentialsBindingRegistrar implements InternalHonoApiRouteRegistrar {
+  private readonly logger: Logger;
+
+  constructor(
+    @inject(InternalHmacAuthMiddleware) private readonly hmacMiddleware: InternalHmacAuthMiddleware,
+    @inject(CredentialBindingService) private readonly credentialBindingService: CredentialBindingService,
+    @inject(ApplicationTokens.LoggerFactory) loggerFactory: LoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("InternalCredentialsBindingRegistrar");
+  }
+
+  register(app: Hono): void {
+    app.post("/internal/credentials/binding", this.hmacMiddleware.handle(), async (c) => {
+      try {
+        const rawBody = c.get("body" as never) as string | undefined;
+        const body = (rawBody ? JSON.parse(rawBody) : await c.req.json()) as Partial<CredentialBindingBody>;
+
+        if (!body.workflowId || typeof body.workflowId !== "string") {
+          return c.json({ error: "workflowId is required" }, 400);
+        }
+        if (!body.nodeId || typeof body.nodeId !== "string") {
+          return c.json({ error: "nodeId is required" }, 400);
+        }
+        if (!body.slotKey || typeof body.slotKey !== "string") {
+          return c.json({ error: "slotKey is required" }, 400);
+        }
+        if (!body.credentialInstanceId || typeof body.credentialInstanceId !== "string") {
+          return c.json({ error: "credentialInstanceId is required" }, 400);
+        }
+
+        const binding = await this.credentialBindingService.upsertBinding({
+          workflowId: body.workflowId,
+          nodeId: body.nodeId,
+          slotKey: body.slotKey,
+          instanceId: body.credentialInstanceId,
+        });
+
+        this.logger.info(
+          `Credential binding upserted for workflow=${body.workflowId} node=${body.nodeId} slot=${body.slotKey}`,
+        );
+
+        return c.json({ ok: true, binding });
+      } catch (error) {
+        if (error instanceof ApplicationRequestError) {
+          return c.json(error.payload, error.status as 400 | 404);
+        }
+        this.logger.error("Credential binding handler error", error instanceof Error ? error : undefined);
+        return c.json({ error: "Internal server error" }, 500);
+      }
+    });
+  }
+}

package/src/credentials/LocalCredentialMaterialProvider.ts

@@ -0,0 +1,92 @@
+import { inject, injectable } from "@codemation/core";
+import type {
+  CallerContext,
+  CredentialMaterialProvider,
+  CredentialMaterialRef,
+  MaterialBundle,
+} from "@codemation/core";
+import { IllegalMaterialSourceError } from "@codemation/core";
+
+import { ApplicationTokens } from "../applicationTokens";
+import { CredentialSecretCipher } from "../domain/credentials/CredentialSecretCipher";
+import type { CredentialStore } from "../domain/credentials/CredentialServices";
+
+/**
+ * Local (OSS / standalone) implementation of `CredentialMaterialProvider`.
+ *
+ * Reads/writes OAuth material bytes through the existing `PrismaCredentialStore`
+ * (i.e. the workspace's `CredentialOAuth2Material` table). The
+ * `material:{source,ref}` pointer on the `CredentialInstance` row points back
+ * at the row's own instance id for local credentials.
+ *
+ * This provider is registered in DI; the resolver dispatches by `ref.source`.
+ *
+ * `callerContext` is accepted but ignored: standalone mode has no CP-side
+ * audit log. See `docs/design/credentials-oauth-unification.md`
+ * "Material provider seam".
+ */
+@injectable()
+export class LocalCredentialMaterialProvider implements CredentialMaterialProvider {
+  constructor(
+    @inject(ApplicationTokens.CredentialStore) private readonly credentialStore: CredentialStore,
+    @inject(CredentialSecretCipher) private readonly credentialSecretCipher: CredentialSecretCipher,
+  ) {}
+
+  async getMaterial(ref: CredentialMaterialRef, _context: CallerContext): Promise<MaterialBundle> {
+    this.assertLocalSource(ref);
+    const encrypted = await this.credentialStore.getOAuth2Material(ref.id);
+    if (!encrypted) {
+      throw new Error(`LocalCredentialMaterialProvider: no material for instance "${ref.id}"`);
+    }
+    const json = this.credentialSecretCipher.decrypt({
+      encryptedJson: encrypted.encryptedJson,
+      encryptionKeyId: encrypted.encryptionKeyId,
+      schemaVersion: encrypted.schemaVersion,
+    }) as {
+      accessToken?: unknown;
+      refreshToken?: unknown;
+      expiresAt?: unknown;
+      grantedScopes?: unknown;
+    };
+    return {
+      accessToken: typeof json.accessToken === "string" ? json.accessToken : "",
+      refreshToken: typeof json.refreshToken === "string" ? json.refreshToken : undefined,
+      expiresAt: typeof json.expiresAt === "string" ? json.expiresAt : undefined,
+      grantedScopes:
+        typeof json.grantedScopes === "string"
+          ? json.grantedScopes.split(/\s+/).filter((scope) => scope.length > 0)
+          : encrypted.scopes,
+    };
+  }
+
+  async setMaterial(ref: CredentialMaterialRef, material: MaterialBundle): Promise<void> {
+    this.assertLocalSource(ref);
+    const existing = await this.credentialStore.getOAuth2Material(ref.id);
+    const encrypted = this.credentialSecretCipher.encrypt({
+      accessToken: material.accessToken,
+      refreshToken: material.refreshToken ?? null,
+      expiresAt: material.expiresAt ?? null,
+      grantedScopes: material.grantedScopes.join(" "),
+    });
+    const now = new Date().toISOString();
+    await this.credentialStore.saveOAuth2Material({
+      instanceId: ref.id,
+      encryptedJson: encrypted.encryptedJson,
+      encryptionKeyId: encrypted.encryptionKeyId,
+      schemaVersion: encrypted.schemaVersion,
+      metadata: {
+        providerId: existing?.providerId ?? "",
+        connectedEmail: existing?.connectedEmail,
+        connectedAt: existing?.connectedAt,
+        scopes: [...material.grantedScopes],
+        updatedAt: now,
+      },
+    });
+  }
+
+  private assertLocalSource(ref: CredentialMaterialRef): void {
+    if (ref.source !== "local") {
+      throw new IllegalMaterialSourceError(ref.source, "LocalCredentialMaterialProvider");
+    }
+  }
+}

package/src/domain/credentials/CredentialInstanceService.ts

@@ -114,8 +114,9 @@ export class CredentialInstanceService {
     const timestamp = new Date().toISOString();
     const strippedPublic = this.stripEnvManagedFieldValues(publicFields, request.publicConfig ?? {});
     const strippedSecretForRef = this.stripEnvManagedFieldValues(secretFields, request.secretConfig ?? {});
+    const instanceId = randomUUID();
     const instance: CredentialInstanceRecord = {
-      instanceId: randomUUID(),
+      instanceId,
       typeId: request.typeId,
       displayName: request.displayName.trim(),
       sourceKind: request.sourceKind,
@@ -125,6 +126,9 @@ export class CredentialInstanceService {
       setupStatus: credentialType.definition.auth?.kind === "oauth2" ? "draft" : "ready",
       createdAt: timestamp,
       updatedAt: timestamp,
+      // New instances are local-mode by default. The CP material provider sets
+      // source="control-plane" when managed mode is detected.
+      material: { source: "local", ref: instanceId },
     };
     await this.credentialStore.saveInstance({
       instance,

package/src/domain/credentials/CredentialTypeRegistryImpl.ts

@@ -54,7 +54,11 @@ export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
         const nextType: AnyCredentialType =
           sourcePriority === SOURCE_PRIORITY[existing.source]
             ? { ...existing.type, definition }
-            : { definition, createSession: this.createUnsupportedSessionFactory(definition.typeId, source), test: this.createUnsupportedHealthTester(definition.typeId, source) };
+            : {
+                definition,
+                createSession: this.createUnsupportedSessionFactory(definition.typeId, source),
+                test: this.createUnsupportedHealthTester(definition.typeId, source),
+              };
         this.recordEntry(definition.typeId, { type: nextType, source });
         continue;
       }
@@ -90,7 +94,11 @@ export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
     return this.entries.get(typeId)?.type;
   }
 
-  private insert(source: CredentialTypeSource, type: AnyCredentialType, logger: ReturnType<LoggerFactory["create"]>): void {
+  private insert(
+    source: CredentialTypeSource,
+    type: AnyCredentialType,
+    logger: ReturnType<LoggerFactory["create"]>,
+  ): void {
     const typeId = type.definition.typeId;
     const existing = this.entries.get(typeId);
     const sourcePriority = SOURCE_PRIORITY[source];
@@ -119,7 +127,10 @@ export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
     this.bySource.get(entry.source)!.add(typeId);
   }
 
-  private createUnsupportedSessionFactory(typeId: CredentialTypeId, source: CredentialTypeSource): AnyCredentialType["createSession"] {
+  private createUnsupportedSessionFactory(
+    typeId: CredentialTypeId,
+    source: CredentialTypeSource,
+  ): AnyCredentialType["createSession"] {
     return async () => {
       throw new Error(
         `Credential type "${typeId}" (source "${source}") was registered with definition only — no createSession implementation is available in this runtime.`,
@@ -127,7 +138,10 @@ export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
     };
   }
 
-  private createUnsupportedHealthTester(typeId: CredentialTypeId, source: CredentialTypeSource): AnyCredentialType["test"] {
+  private createUnsupportedHealthTester(
+    typeId: CredentialTypeId,
+    source: CredentialTypeSource,
+  ): AnyCredentialType["test"] {
     return async () => ({
       status: "unknown" as const,
       message: `Credential type "${typeId}" (source "${source}") has no local test implementation.`,

package/src/domain/workflows/WorkflowActivationPreflightRules.ts

@@ -1,5 +1,10 @@
 import type { WorkflowCredentialHealthDto } from "../../application/contracts/CredentialContractsRegistry";
-import { getPersistedRuntimeTypeMetadata, injectable, type CredentialRequirement, type WorkflowDefinition } from "@codemation/core";
+import {
+  getPersistedRuntimeTypeMetadata,
+  injectable,
+  type CredentialRequirement,
+  type WorkflowDefinition,
+} from "@codemation/core";
 import { MissingRuntimeTriggerToken } from "@codemation/core/bootstrap";
 import { ManualTriggerNode } from "@codemation/core-nodes";
 
@@ -105,9 +110,7 @@ export class WorkflowActivationPreflightRules {
       const grantedSet = new Set(granted);
       const missing = required.filter((s) => !grantedSet.has(s));
       if (missing.length > 0) {
-        lines.push(
-          `Credential "${displayName}" missing scopes: ${missing.join(", ")}. Reconnect to grant.`,
-        );
+        lines.push(`Credential "${displayName}" missing scopes: ${missing.join(", ")}. Reconnect to grant.`);
       }
     }
 

package/src/dto.ts

@@ -12,6 +12,8 @@ export type {
   CreateCredentialInstanceRequest,
   UpdateCredentialInstanceRequest,
   UpsertCredentialBindingRequest,
+  AppGalleryEntry,
+  AppsResponse,
 } from "./application/contracts/CredentialContractsRegistry";
 
 export type {

package/src/hitl/ControlPlaneInboxChannel.ts

@@ -0,0 +1,102 @@
+import { inject, injectable } from "@codemation/core";
+import type {
+  InboxChannel,
+  InboxDeliverArgs,
+  InboxDelivery,
+  InboxOnDecisionArgs,
+  InboxOnTimeoutArgs,
+} from "@codemation/core";
+import type { Logger } from "../application/logging/Logger";
+import { PairedFetch } from "../pairing/PairedFetch";
+import type { PairingConfig } from "../pairing/pairing.types";
+import { PairingConfigToken } from "../pairing/PairingConfigToken";
+import { ServerLoggerFactory } from "../infrastructure/logging/ServerLoggerFactory";
+
+/**
+ * Inbox channel that pushes pending HITL tasks to the control plane via HMAC-signed HTTP.
+ *
+ * Registered only when `PairingConfig` is present (managed mode).
+ * The control plane stores the task in its own DB and renders the reviewer inbox.
+ * Decisions flow back to the framework via `POST /internal/hitl/tasks/:taskId/callback`.
+ */
+@injectable()
+export class ControlPlaneInboxChannel implements InboxChannel {
+  readonly kind = "control-plane-inbox" as const;
+
+  private readonly logger: Logger;
+
+  constructor(
+    @inject(PairedFetch) private readonly pairedFetch: PairedFetch,
+    @inject(PairingConfigToken) private readonly pairingConfig: PairingConfig,
+    @inject(ServerLoggerFactory) loggerFactory: ServerLoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("codemation.hitl.cp-inbox");
+  }
+
+  async deliver(args: InboxDeliverArgs): Promise<InboxDelivery> {
+    const { task, subject, priority, item } = args;
+
+    const body = {
+      taskId: task.taskId,
+      workspaceId: this.pairingConfig.workspaceId,
+      runId: task.runId,
+      nodeId: task.nodeId,
+      subject,
+      priority,
+      expiresAt: task.expiresAt.toISOString(),
+      resumeUrl: task.resumeUrl,
+      item: { json: item.json, hasBinary: item.binary != null },
+      agentReasoning: task.metadata?.agentReasoning as string | undefined,
+    };
+
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/hitl/tasks`;
+    const res = await this.pairedFetch.post(url, body);
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "<unreadable>");
+      throw new Error(`ControlPlaneInboxChannel: CP push failed with status ${res.status}: ${text}`);
+    }
+
+    const json = (await res.json()) as { inboxItemId: string };
+    this.logger.info(`HITL task delivered to CP inbox — taskId=${task.taskId} inboxItemId=${json.inboxItemId}`);
+
+    return { kind: "cp", inboxItemId: json.inboxItemId, workspaceId: this.pairingConfig.workspaceId };
+  }
+
+  async updateOnDecision(args: InboxOnDecisionArgs): Promise<void> {
+    if (args.delivery.kind !== "cp") return;
+
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/hitl/tasks/${args.delivery.inboxItemId}/resolved`;
+    const body = {
+      decision: args.decision,
+      actor: args.actor,
+      resolvedAt: new Date().toISOString(),
+    };
+
+    const res = await this.pairedFetch.post(url, body);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "<unreadable>");
+      this.logger.warn(
+        `Failed to notify CP of task decision — inboxItemId=${args.delivery.inboxItemId} status=${res.status} body=${text}`,
+      );
+    }
+  }
+
+  async updateOnTimeout(args: InboxOnTimeoutArgs): Promise<void> {
+    if (args.delivery.kind !== "cp") return;
+
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/hitl/tasks/${args.delivery.inboxItemId}/resolved`;
+    const body = {
+      decision: { kind: "timeout", policy: args.policy },
+      resolvedAt: new Date().toISOString(),
+    };
+
+    const res = await this.pairedFetch.post(url, body);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "<unreadable>");
+      this.logger.warn(
+        `Failed to notify CP of task timeout — inboxItemId=${args.delivery.inboxItemId} status=${res.status} body=${text}`,
+      );
+    }
+  }
+}

package/src/hitl/HitlResumeTokenSigner.ts

@@ -0,0 +1,80 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { inject, injectable } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { AppConfig } from "../presentation/config/AppConfig";
+
+/**
+ * Signs and verifies single-use HITL resume tokens.
+ *
+ * Token format: `<taskId>.<expiresAtUnix>.<schemaHash8>.<sigBase64Url>`
+ * Signature: HMAC-SHA256(AUTH_SECRET, `${taskId}.${expiresAtUnix}.${schemaHash8}`)
+ *
+ * Tokens are single-use (the HumanTask status transition from pending → decided/timed_out
+ * is the consumption mechanism — reuse returns 409).
+ */
+@injectable()
+export class HitlResumeTokenSigner {
+  // Cached secret bytes if AUTH_SECRET is present. Null otherwise — call sites that
+  // actually need to sign/verify will throw via requireSecret(). Deferring the throw
+  // to method invocation (instead of constructor) keeps test setups and bootstrap
+  // graphs that resolve the wider engine chain from failing when AUTH_SECRET is not
+  // set; production code paths that exercise HITL still fail loudly at use time.
+  private readonly secret: Buffer | null;
+
+  constructor(@inject(ApplicationTokens.AppConfig) appConfig: AppConfig) {
+    const raw = appConfig.env.AUTH_SECRET?.trim();
+    this.secret = raw ? Buffer.from(raw, "utf8") : null;
+  }
+
+  private requireSecret(): Buffer {
+    if (!this.secret) {
+      throw new Error("HitlResumeTokenSigner: AUTH_SECRET is required.");
+    }
+    return this.secret;
+  }
+
+  sign(args: { taskId: string; expiresAt: Date; schemaHash: string }): string {
+    const expiresAtUnix = String(Math.floor(args.expiresAt.getTime() / 1000));
+    const schemaHash8 = args.schemaHash.slice(0, 8);
+    const payload = `${args.taskId}.${expiresAtUnix}.${schemaHash8}`;
+    const sig = createHmac("sha256", this.requireSecret()).update(payload).digest("base64url");
+    return `${payload}.${sig}`;
+  }
+
+  verify(
+    token: string,
+  ):
+    | { ok: true; taskId: string; schemaHash: string; expiresAt: Date }
+    | { ok: false; reason: "malformed" | "bad_sig" | "expired" } {
+    const parts = token.split(".");
+    if (parts.length !== 4) {
+      return { ok: false, reason: "malformed" };
+    }
+    const [taskId, expiresAtUnixStr, schemaHash8, receivedSig] = parts as [string, string, string, string];
+
+    const expiresAtUnix = Number(expiresAtUnixStr);
+    if (!Number.isFinite(expiresAtUnix)) {
+      return { ok: false, reason: "malformed" };
+    }
+
+    const payload = `${taskId}.${expiresAtUnixStr}.${schemaHash8}`;
+    const expectedSig = createHmac("sha256", this.requireSecret()).update(payload).digest("base64url");
+    const expectedBuf = Buffer.from(expectedSig, "utf8");
+    const receivedBuf = Buffer.from(receivedSig, "utf8");
+    if (expectedBuf.length !== receivedBuf.length || !timingSafeEqual(expectedBuf, receivedBuf)) {
+      return { ok: false, reason: "bad_sig" };
+    }
+
+    const expiresAt = new Date(expiresAtUnix * 1000);
+    if (expiresAt <= new Date()) {
+      return { ok: false, reason: "expired" };
+    }
+
+    return { ok: true, taskId, schemaHash: schemaHash8, expiresAt };
+  }
+
+  /** SHA-256 hash of the full token string (used for revocation lookup). */
+  hashToken(token: string): string {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+  }
+}

package/src/hitl/HitlTimeoutJobScheduler.ts

@@ -0,0 +1,77 @@
+import { Queue } from "bullmq";
+import { inject, injectable } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { AppConfig } from "../presentation/config/AppConfig";
+import { RedisConnectionOptionsFactory } from "../infrastructure/scheduler/bullmq/RedisConnectionOptionsFactory";
+
+export const HITL_TIMEOUT_QUEUE_NAME_SUFFIX = "hitl.timeout";
+
+export interface HitlTimeoutJobPayload {
+  readonly kind: "hitl.timeout";
+  readonly taskId: string;
+}
+
+/**
+ * Schedules delayed BullMQ jobs that drive the timeout path for suspended HITL tasks.
+ * The processor (`HitlTimeoutJobProcessor`) handles these jobs.
+ *
+ * Job id: `hitl_timeout__<taskId>` — stable id allows reliable removal via `remove()`.
+ */
+@injectable()
+export class HitlTimeoutJobScheduler {
+  private queue: Queue | null = null;
+  private readonly queueName: string;
+  private readonly redisUrl: string;
+
+  constructor(@inject(ApplicationTokens.AppConfig) appConfig: AppConfig) {
+    const rawRedisUrl = appConfig.env.REDIS_URL ?? appConfig.env.CODEMATION_REDIS_URL;
+    // Defer URL parsing to queue construction so DI consumers that never enqueue
+    // (e.g. `codemation user create` with REDIS_URL="") can resolve this scheduler
+    // without throwing. fromUrl runs the first time getOrCreateQueue() fires.
+    this.redisUrl = rawRedisUrl && rawRedisUrl !== "" ? rawRedisUrl : "redis://127.0.0.1:6379";
+    const queuePrefix = appConfig.env.CODEMATION_BULLMQ_PREFIX ?? "codemation";
+    this.queueName = `${queuePrefix}.${HITL_TIMEOUT_QUEUE_NAME_SUFFIX}`;
+  }
+
+  async enqueueTimeoutJob(args: { taskId: string; expiresAt: Date }): Promise<void> {
+    const queue = this.getOrCreateQueue();
+    const delay = Math.max(0, args.expiresAt.getTime() - Date.now());
+    await queue.add("hitl.timeout", { kind: "hitl.timeout", taskId: args.taskId } satisfies HitlTimeoutJobPayload, {
+      jobId: this.makeJobId(args.taskId),
+      delay,
+      removeOnComplete: true,
+      removeOnFail: true,
+    });
+  }
+
+  async cancelTimeoutJob(taskId: string): Promise<void> {
+    const queue = this.getOrCreateQueue();
+    const job = await queue.getJob(this.makeJobId(taskId));
+    await job?.remove();
+  }
+
+  async close(): Promise<void> {
+    if (this.queue) {
+      await this.queue.close();
+      this.queue = null;
+    }
+  }
+
+  getQueueName(): string {
+    return this.queueName;
+  }
+
+  private getOrCreateQueue(): Queue {
+    if (!this.queue) {
+      const connectionOptions = RedisConnectionOptionsFactory.fromConfig({ url: this.redisUrl });
+      this.queue = new Queue(this.queueName, {
+        connection: connectionOptions as never,
+      });
+    }
+    return this.queue;
+  }
+
+  private makeJobId(taskId: string): string {
+    return `hitl_timeout__${taskId}`;
+  }
+}

package/src/hitl/HitlTimeoutWorker.ts

@@ -0,0 +1,138 @@
+import type { Job } from "bullmq";
+import { Worker } from "bullmq";
+import { inject, injectable } from "@codemation/core";
+import type { HumanTaskStore } from "@codemation/core";
+import { CodemationTelemetryAttributeNames, HumanTaskStoreToken } from "@codemation/core";
+import { Engine } from "@codemation/core/bootstrap";
+import { ApplicationTokens } from "../applicationTokens";
+import type { AppConfig } from "../presentation/config/AppConfig";
+import { RedisConnectionOptionsFactory } from "../infrastructure/scheduler/bullmq/RedisConnectionOptionsFactory";
+import type { HitlTimeoutJobPayload } from "./HitlTimeoutJobScheduler";
+import { HitlTimeoutJobScheduler } from "./HitlTimeoutJobScheduler";
+import { ResumeTelemetryContextForRun } from "../application/telemetry/ResumeTelemetryContextForRun";
+
+/**
+ * BullMQ worker that processes `hitl.timeout` jobs.
+ *
+ * - If `task.onTimeout === "auto-accept"`: marks the task `auto_accepted` and resumes the run
+ *   with `decision: { kind: "auto_accepted" }`.
+ * - If `task.onTimeout === "halt"`: marks the task `timed_out` and resumes the run
+ *   with `decision: { kind: "timed_out" }`.
+ *
+ * The engine's resume handler distinguishes halt vs. continue based on the decision kind
+ * (the first-class HITL states handle the halt-the-run path).
+ *
+ * `processTimeoutForTask` is public to allow direct testing without BullMQ.
+ */
+@injectable()
+export class HitlTimeoutWorker {
+  private readonly taskStore: HumanTaskStore;
+  private worker: Worker | null = null;
+  private readonly connectionOptions: Readonly<Record<string, unknown>>;
+
+  constructor(
+    @inject(HumanTaskStoreToken) taskStore: HumanTaskStore | undefined,
+    @inject(Engine) private readonly engine: Engine,
+    @inject(HitlTimeoutJobScheduler) private readonly scheduler: HitlTimeoutJobScheduler,
+    @inject(ApplicationTokens.AppConfig) appConfig: AppConfig,
+    @inject(ResumeTelemetryContextForRun) private readonly resumeTelemetry: ResumeTelemetryContextForRun,
+  ) {
+    if (!taskStore) {
+      throw new Error("HitlTimeoutWorker: HumanTaskStore is not registered.");
+    }
+    this.taskStore = taskStore;
+    const redisUrl = appConfig.env.REDIS_URL ?? appConfig.env.CODEMATION_REDIS_URL ?? "redis://127.0.0.1:6379";
+    this.connectionOptions = RedisConnectionOptionsFactory.fromConfig({ url: redisUrl });
+  }
+
+  start(): void {
+    this.worker = new Worker(
+      this.scheduler.getQueueName(),
+      async (job: Job) => {
+        await this.processJob(job);
+      },
+      { connection: this.connectionOptions as never },
+    );
+  }
+
+  async stop(): Promise<void> {
+    if (this.worker) {
+      await this.worker.close();
+      this.worker = null;
+    }
+  }
+
+  async processTimeoutForTask(taskId: string): Promise<void> {
+    const task = await this.taskStore.findById(taskId);
+    if (!task) return;
+    if (task.status !== "pending") return;
+
+    const now = new Date();
+
+    if (task.onTimeout === "auto-accept") {
+      await this.taskStore.markAutoAccepted(taskId);
+
+      // Emit hitl.task.timed_out on the run's trace.
+      const telemetry = await this.resumeTelemetry.forTask(taskId);
+      await telemetry?.addSpanEvent({
+        name: "hitl.task.timed_out",
+        attributes: {
+          [CodemationTelemetryAttributeNames.hitlTaskId]: taskId,
+          policy: "auto-accept",
+        },
+      });
+
+      await this.engine.resumeRun({
+        runId: task.runId,
+        taskId: task.id,
+        resumeContext: {
+          decision: { kind: "auto_accepted", at: now },
+          delivery: task.deliveryRef ?? null,
+          task: {
+            taskId: task.id,
+            runId: task.runId,
+            nodeId: task.nodeId,
+            expiresAt: task.expiresAt,
+            resumeUrl: "",
+          },
+        },
+      });
+    } else {
+      await this.taskStore.markTimedOut(taskId);
+
+      // Emit hitl.task.timed_out on the run's trace.
+      const telemetry = await this.resumeTelemetry.forTask(taskId);
+      await telemetry?.addSpanEvent({
+        name: "hitl.task.timed_out",
+        attributes: {
+          [CodemationTelemetryAttributeNames.hitlTaskId]: taskId,
+          policy: "halt",
+        },
+      });
+
+      await this.engine.resumeRun({
+        runId: task.runId,
+        taskId: task.id,
+        resumeContext: {
+          decision: { kind: "timed_out", at: now },
+          delivery: task.deliveryRef ?? null,
+          task: {
+            taskId: task.id,
+            runId: task.runId,
+            nodeId: task.nodeId,
+            expiresAt: task.expiresAt,
+            resumeUrl: "",
+          },
+        },
+      });
+    }
+  }
+
+  private async processJob(job: Job): Promise<void> {
+    const data = job.data as HitlTimeoutJobPayload;
+    if (!data || data.kind !== "hitl.timeout") {
+      throw new Error(`Unexpected job payload for hitl.timeout queue: ${JSON.stringify(data)}`);
+    }
+    await this.processTimeoutForTask(data.taskId);
+  }
+}