@bevel-software/ael 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,164 @@
+/**
+ * `@bevel-software/ael` — the agentic execution layer.
+ *
+ * One library, imported by the platform and shipped into run containers,
+ * holding everything that reads an `.agent` or a `.workflow` file and
+ * everything that runs a session from them. The platform never parses either
+ * file kind itself; the runner never knows what a step does. See the design
+ * node `idea-bevel-platform-background-agents` in the knowledge base.
+ */
+
+// Files
+export {
+  AGENT_FILE_EXTENSION,
+  AgentParseError,
+  MAX_ENV_VARIABLES,
+  agentSlug,
+  normalizeEntryPath,
+  parseAgentFile,
+  type AgentDefinition,
+  type AgentEnvVar,
+  type EnvSource,
+  type HarnessName,
+} from './agent/agent-file.js';
+export {
+  ERROR_NAMES,
+  TERMINAL_TARGETS,
+  WORKFLOW_FILE_EXTENSION,
+  WorkflowParseError,
+  environmentOf,
+  evaluate,
+  isTerminalTarget,
+  nextAfter,
+  parseWorkflowFile,
+  PERSONAL_EXECUTOR_NAME,
+  stepByName,
+  stepSlug,
+  stripReservedKeys,
+  type CatchRule,
+  type ChoiceRule,
+  type Comparator,
+  type EntryBudget,
+  type Environment,
+  type ErrorName,
+  type ParamSource,
+  type ParametersDef,
+  type RequiredParam,
+  type RetryRule,
+  type StepDef,
+  type StepKind,
+  type SystemPromptSpec,
+  type TerminalTarget,
+  type WorkflowDefinition,
+} from './workflow/workflow-file.js';
+export {
+  ATTEMPTS_KEY,
+  ENTRIES_KEY,
+  RETRIES_KEY,
+  decide,
+  errorForVerdict,
+  isRetryKeyOf,
+  retryKey,
+  type FailureContext,
+  type FailureDecision,
+} from './workflow/failure-policy.js';
+export {
+  ParameterResolutionError,
+  firstLinkTarget,
+  firstUrl,
+  getSection,
+  graphFor,
+  interpolate,
+  parseKeyValueField,
+  resolveParameters,
+  type GraphReader,
+  type ParameterGraph,
+  type ResolvedParameters,
+} from './workflow/parameters.js';
+
+// Runs
+export {
+  type ActorKey,
+  type Harness,
+  type PlatformEndpoints,
+  type RunEvent,
+  type RunInput,
+  type SessionResult,
+  type SessionStartParams,
+  type SessionState,
+  type Verdict,
+} from './run/contract.js';
+export { VERDICT_NUDGE, head, parseOutputs, parseVerdict, tail } from './run/verdict.js';
+export { outcomeFromResult, threadStatusOf } from './run/outcome.js';
+export { PlatformRunReporter, type FetchLike, type RunReporterOptions } from './run/reporter.js';
+export { SkillNotReadable, composeSystemPrompt } from './run/system-prompt.js';
+export { ENCRYPTED_ENCODING, EncryptingPayloadCodec, dataConverterFor, isEncrypted } from './temporal/payload-codec.js';
+export { OUTCOME_MARKER, parseOutcomeLine, runStep, type RunStepDeps } from './cli/run-step.js';
+export { formatEvent, runLocally, unrunnableLocally, type LocalRunOptions, type LocalRunResult } from './cli/run-local.js';
+
+// Executors: the container half of the contract, on a host of its own.
+export { DEPLOYMENT_LABEL, IMAGE_TAG_PREFIX, OWNER_LABEL, VOLUME_LABEL, createExecutor, harnessNodeCommand, imageTagFor, volumeNameFor, type Executor, type ExecutorOptions } from './executor/activities.js';
+export { createInPlaceExecutor, type InPlaceExecutorOptions } from './executor/in-place.js';
+export { EXECUTOR_INSTANCE, PERSONAL_EXECUTOR_API, personalExecutorHooks, runPersonalExecutor, runWorkerStarter, type PersonalExecutorOptions, type WaitingRun, type WorkerStarterOptions, type PersonalJob, type PersonalJobResult } from './executor/personal.js';
+export type { ContainerDriver, ContainerLimits, ContainerMount, ContainerRunResult, ContainerRunSpec, ContainerVolume } from './executor/driver.js';
+export { Slots } from './executor/slots.js';
+export { MIN_REDACTABLE_LENGTH, NO_REDACTION, Redactor } from './shared/redact.js';
+// The schedule grammar, also served browser-side as `@bevel-software/ael/schedule`.
+export { durationMs, isCron, isDuration, isTimeZone, isoToInstant, parseIsoDateTime, wallClockToInstant, type IsoDateTime } from './shared/schedule.js';
+export { renderTranscript, type TranscriptMeta } from './transcript/render.js';
+
+// Work items: the knowledge-base node a multi-step run keeps up to date.
+export {
+  DEFAULT_FIELDS,
+  appendToSection,
+  applyWorkItemUpdate,
+  filedAtOf,
+  getSection as getNodeSection,
+  headingName,
+  parseState,
+  parseWorkItem,
+  renderProgress,
+  serializeState,
+  setSection,
+  type FieldNames,
+  type ParsedWorkItem,
+  type WorkItemState,
+  type WorkItemUpdate,
+} from './workitem/node.js';
+
+// Harnesses
+export { PiInProcessHarness, type PiInProcessOptions } from './harness/pi-in-process.js';
+export { ClaudeCodeHarness, type ClaudeCodeOptions } from './harness/claude-code.js';
+
+// The interpreter's contract with the platform and the executors. The
+// workflows themselves are the `@bevel-software/ael/workflows` entry, which a
+// Temporal worker bundles on its own.
+export {
+  EXECUTOR_TASK_QUEUE,
+  INTERPRETER_STATE_KEYS,
+  resumableState,
+  MAX_STEP_RESTARTS,
+  PLATFORM_RESTART,
+  PLATFORM_TASK_QUEUE,
+  CONTAINER_STEP_HEARTBEAT_MS,
+  PERSONAL_EXECUTOR_SILENCE_MS,
+  personalExecutorQueue,
+  deploymentExecutorQueue,
+  namedExecutorQueue,
+  type Actor,
+  type AgentStepInput,
+  type AgentStepOutcome,
+  type ContainerStepInput,
+  type ExecutorActivities,
+  type PrepareContainerStepResult,
+  type InterpretInput,
+  type InterpretResult,
+  type InterpreterActivities,
+  type RunStatus,
+  type ToolChainInput,
+  type ToolChainOutcome,
+  type Transition,
+} from './interpreter/contract.js';
+// What a dispatcher answers to its `dispatcherState` query (a type alone: the
+// workflow itself stays in the `./workflows` entry).
+export type { DispatchSettings, DispatcherState } from './interpreter/dispatcher.workflow.js';

package/src/interpreter/contract.ts

@@ -0,0 +1,403 @@
+import type { AgentDefinition } from '../agent/agent-file.js';
+import type { ActorKey, PlatformEndpoints, RunInput, SessionState, Verdict } from '../run/contract.js';
+import type { WorkflowDefinition } from '../workflow/definition.js';
+import type { FieldNames } from '../workitem/node.js';
+
+/**
+ * The seam between the interpreter (a Temporal workflow, deterministic, no
+ * I/O) and the world. Everything with a side effect is an activity the
+ * platform implements on its own worker, or an executor implements on its
+ * queue; the interpreter only ever sees the values they return. This file is
+ * types only: it is loaded inside the workflow sandbox too.
+ */
+
+export interface Actor {
+  userId: string;
+  email: string;
+}
+
+/** What starts one run of a workflow. */
+export interface InterpretInput {
+  /** The run's thread id; the parent of every step thread. */
+  runId: string;
+  workflowPath: string;
+  actor: Actor;
+  /** The trigger's input: a webhook body, Run now text, the kb node, the `ask` prompt. */
+  input: RunInput;
+  /**
+   * The executor this run's container steps run on, by name (`laptop`,
+   * `gpu-1`), chosen where the run was started (Run now,
+   * `schedule_workflow`, the trigger's settings) — not by the file, so one
+   * workflow runs anywhere. Every step runs there and nowhere else, waiting
+   * while it is not connected. Absent: any of the deployment's executors.
+   */
+  executor?: string;
+  /**
+   * Whose executor `executor` is, resolved when the run started: one of the
+   * deployment's own, or the actor's personal one (no run reaches another
+   * person's). Absent with `executor` set: personal (a run started before
+   * deployment executors had names).
+   */
+  executorKind?: 'deployment' | 'personal';
+  /**
+   * The node a kb trigger fired on: where the run's parameters are read from.
+   * A `status` condition claims it, so it is the work item too; a `change`
+   * condition only watches it — the run reads the node and writes nothing to
+   * it. Absent for every other start.
+   */
+  subjectPath?: string;
+  /** The work item that tracks this run, when the workflow has more than one step. */
+  workItemPath: string | null;
+  /** The item's field names, when its trigger chose them (a kb trigger's status and owner fields); the defaults otherwise. */
+  workItemFields?: FieldNames;
+  /** STATE to start from (a released item keeps its counters cleared, but a resumed one keeps its outputs). */
+  initialState?: Record<string, unknown>;
+  /**
+   * A thread whose stored session state the first step starts from: a
+   * continued `ask` conversation. The step still gets a thread of its own;
+   * only the harness's context is carried over.
+   */
+  continueFromThreadId?: string;
+  /** The task queue container steps go to when no executor has claimed this run yet. */
+  executorQueue?: string;
+  /** The structure version a continued execution started under: the file is checked against it, not re-baselined. */
+  workflowVersion?: string;
+  /** How often a gate with a probe re-checks, in seconds. */
+  gatePollSeconds?: number;
+  /** How long a gate without a probe may wait for its signal, in seconds. */
+  gateTimeoutSeconds?: number;
+  /** Test hook: continue as new after this many steps, as if Temporal had suggested it; production leaves it unset. */
+  continueAfterSteps?: number;
+  /**
+   * Set by the interpreter alone when it continues as new inside a gate:
+   * the gate's deadline (epoch milliseconds), so a gate polled across
+   * executions still times out when it would have.
+   */
+  gateDeadline?: number;
+  /**
+   * Set by the interpreter alone when it continues as new while a step is
+   * paused on an account limit: the step and the thread it paused on, so
+   * the step goes on on that thread, from the state it saved, instead of a
+   * new one beside a thread left `waiting`.
+   */
+  pausedThread?: { step: string; threadId: string };
+  /**
+   * Set by the interpreter alone when it continues as new: the steps this
+   * run has taken so far, so `MAX_RUN_STEPS` counts the whole run and a
+   * cycling workflow cannot start afresh with every execution.
+   */
+  stepsTaken?: number;
+  /**
+   * Set by the interpreter alone when it continues as new inside a probed
+   * gate: the probe's errors in a row so far, so the cap on consecutive
+   * errors counts the same across executions.
+   */
+  probeErrors?: number;
+  /**
+   * Set by the dispatcher alone on the runs it starts: the run counts
+   * against its trigger's cap, so it gives its slot back while it waits at a
+   * gate and asks for one before the step after it. A run nobody caps (Run
+   * now, a schedule) has no slot to give or ask for.
+   */
+  capped?: boolean;
+  /**
+   * Set by the interpreter alone when it continues as new at a gate: the
+   * run gave its slot back already, and asks for one when it goes on.
+   */
+  slotGivenBack?: boolean;
+}
+
+export type RunStatus = 'done' | 'failed' | 'blocked' | 'cancelled';
+
+export interface InterpretResult {
+  status: RunStatus;
+  state: Record<string, unknown>;
+  /** Why it stopped, for a failed or blocked run. */
+  reason?: string;
+}
+
+/** A step attempt's input: everything an agent step needs, already interpolated. */
+export interface AgentStepInput {
+  runId: string;
+  workflowPath: string;
+  stepName: string;
+  stepIndex: number;
+  attempt: number;
+  actor: Actor;
+  /** The `.agent` to run as; null means the deployment's default configuration. */
+  agentPath: string | null;
+  systemPrompt: { skill?: string; extend?: string } | null;
+  instructions: string;
+  verdict: string | null;
+  expectedOutputs: string[];
+  workItemPath: string | null;
+  input: RunInput;
+  state: Record<string, unknown>;
+  params: Record<string, string>;
+  /** The step's thread, opened before the step by `openStepThread` (or the resumed one): its identity is on record before anything runs. */
+  threadId: string;
+  /** A step thread to resume (the state is in the thread store), after a crash. */
+  resumeThreadId: string | null;
+  /** A thread whose stored session state this new step thread starts from; set on the first attempt of the first step only. */
+  continueFromThreadId: string | null;
+  /** The executor this run is pinned to, when a container step ran before. */
+  executorQueue: string | null;
+  environment: WorkflowDefinition['environment'];
+}
+
+export type AgentStepOutcome =
+  | { kind: 'verdict'; verdict: Verdict; threadId: string; outputs: Record<string, unknown> | null; reason: string | null; executorQueue?: string }
+  | { kind: 'no-verdict'; threadId: string; reason: string; executorQueue?: string }
+  | { kind: 'timeout'; threadId: string | null; reason: string; executorQueue?: string }
+  | { kind: 'harness-error'; threadId: string | null; reason: string; executorQueue?: string }
+  | { kind: 'blocked'; threadId: string | null; reason: string }
+  /** The provider refused the ACCOUNT: the executor pauses, the step is re-run after `resetAt`. */
+  | { kind: 'account-limit'; threadId: string | null; resetAt: number | null; text: string; executorQueue?: string };
+
+/**
+ * Everything a container session needs, prepared by the platform before the
+ * step goes to an executor queue: the step, its thread, the run key, where
+ * the platform is from outside, the configuration, the composed messages and
+ * the environment, the state to resume from, and what to run in — the image,
+ * or the Dockerfile's content (the executor has no knowledge base to read it
+ * from). Serializable: it travels through Temporal.
+ */
+export interface ContainerStepInput {
+  step: AgentStepInput;
+  threadId: string;
+  actorKey: ActorKey;
+  platform: PlatformEndpoints & {
+    /** The platform's API root, where the session reports events and state. */
+    apiUrl: string;
+  };
+  agent: AgentDefinition;
+  systemPrompt: string;
+  /** The first user message, composed by the platform as it is for an in-process step. */
+  message: string;
+  /** The configuration's `env:`, resolved. Visible to the agent by construction; redacted from everything stored. */
+  env: Record<string, string>;
+  state: SessionState | null;
+  /** An `image` environment: the reference to pull. */
+  image: string | null;
+  /** A `dockerfile` environment: the file's content; the executor builds it, tagged by its hash. */
+  dockerfile: string | null;
+  expectVerdict: boolean;
+  timeoutMs: number;
+  /** The run moved executors: the workspace is new, and the session is told so. */
+  freshWorkspace: boolean;
+}
+
+export type PrepareContainerStepResult = { kind: 'ready'; input: ContainerStepInput } | { kind: 'blocked'; threadId: string | null; reason: string };
+
+/** What an executor implements, on the shared queue and on its own. */
+/** The signal a run sends its dispatcher as it ends, with its run id. A name, not a definition: the two workflows must not import each other. */
+export const RUN_SETTLED_SIGNAL = 'runSettled';
+/** The signal a capped run sends its dispatcher as it reaches a gate, with its run id: its slot under the cap is free, its key stays held. */
+export const RUN_AT_GATE_SIGNAL = 'runAtGate';
+/** The signal a capped run sends its dispatcher when it is past its gate and has work to do, with its run id: it waits for `SLOT_GRANTED_SIGNAL`. */
+export const RUN_NEEDS_SLOT_SIGNAL = 'runNeedsSlot';
+/** The dispatcher's answer to `RUN_NEEDS_SLOT_SIGNAL`, sent to the run: it holds a slot again. */
+export const SLOT_GRANTED_SIGNAL = 'slotGranted';
+
+export interface ExecutorActivities {
+  runContainerStep(input: ContainerStepInput): Promise<AgentStepOutcome>;
+  /** The run is over: its workspace volume on this executor goes. */
+  releaseRun(input: { runId: string }): Promise<void>;
+}
+
+export interface ToolChainInput {
+  runId: string;
+  workflowPath: string;
+  stepName: string;
+  actor: Actor;
+  /** The chain's source, interpolated. */
+  chain: string;
+  state: Record<string, unknown>;
+  params: Record<string, string>;
+  workItemPath: string | null;
+}
+
+export type ToolChainOutcome =
+  | { kind: 'outcome'; outcome: string; threadId: string | null }
+  | { kind: 'error'; reason: string; threadId: string | null };
+
+/** What the interpreter tells the platform at every transition; the platform writes the work item and the run thread. */
+export interface Transition {
+  runId: string;
+  workflowPath: string;
+  workItemPath: string | null;
+  workItemFields?: FieldNames;
+  actor: Actor;
+  /** The step the run is now in, or the terminal status. */
+  status: string;
+  stepName: string | null;
+  /** The run is parked in this step — on a gate, an account limit — until something outside it answers. */
+  waiting: boolean;
+  /** One line for the work item's Log, or null when the transition is silent. */
+  log: string | null;
+  state: Record<string, unknown>;
+  /** Thread ids per step attempt, for the work item's transcript links. */
+  threadIds: Record<string, string>;
+  happyPath: string[];
+}
+
+/**
+ * The activities the interpreter calls. The platform implements every one on
+ * its worker; an executor implements `runAgentStep` for container
+ * environments on its queue, with the same signature.
+ */
+export interface InterpreterActivities {
+  /** Read and parse the workflow from the default branch. Throws when missing or invalid. */
+  loadWorkflow(input: { workflowPath: string; actor: Actor }): Promise<WorkflowDefinition>;
+  /** Resolve the workflow's parameters from the node the run is about: the trigger's node, or the work item. */
+  resolveRunParameters(input: { definition: WorkflowDefinition; nodePath: string | null; actor: Actor }): Promise<{ values: Record<string, string>; missing: string[] }>;
+  /**
+   * The step's thread, a child of the run, before the step runs. The
+   * interpreter chooses its id (`threadId`), so a retried call — the row was
+   * inserted, the completion was lost — opens no second thread: the same id
+   * is answered.
+   */
+  openStepThread(input: { runId: string; workflowPath: string; actor: Actor; stepName: string; attempt: number; workItemPath: string | null; threadId: string }): Promise<{ threadId: string }>;
+  /**
+   * A step thread whose activity never answered (the worker died, the task
+   * timed out): closed as failed with the reason, so the interpreter's
+   * harness error leaves no thread running. Nothing happens to a thread
+   * already closed.
+   */
+  closeStepThread(input: { threadId: string; reason: string }): Promise<void>;
+  /**
+   * An in-process step ended, however it ended: every key it may still hold
+   * is revoked, what the key used is charged to the key the run names (read
+   * from the run's own thread, the one place it is kept), and the thread's
+   * status is written from the outcome — all retried until the stores
+   * answer, the charge made once however many times. The step's own
+   * activity revokes as it ends too, but cannot be retried, and writes no
+   * status and charges nothing; this one is the record.
+   */
+  finishAgentStep(input: { threadId: string; outcome: AgentStepOutcome }): Promise<void>;
+  runAgentStep(input: AgentStepInput): Promise<AgentStepOutcome>;
+  /**
+   * A container step, before it goes to an executor: the thread, the run key,
+   * the configuration and its environment, the Dockerfile's content. Blocked
+   * when the configuration cannot run (an unreadable file, a missing vault entry).
+   */
+  prepareContainerStep(input: AgentStepInput): Promise<PrepareContainerStepResult>;
+  /** A container step ended, however it ended: the run key is revoked, what it used charged once to the key the run names, the step thread closed. */
+  finishContainerStep(input: { threadId: string; keyId: string | null; outcome: AgentStepOutcome | null; error: string | null }): Promise<void>;
+  runToolChain(input: ToolChainInput): Promise<ToolChainOutcome>;
+  /** A gate's probe: a tool chain answering one of the gate's outcomes or `wait`. */
+  runProbe(input: ToolChainInput): Promise<ToolChainOutcome>;
+  recordTransition(input: Transition): Promise<void>;
+  notifyRunFailed(input: { runId: string; workflowPath: string; actor: Actor; status: RunStatus; reason: string }): Promise<void>;
+  /** A firing that will never run (replaced by a newer one, or waiting when its trigger was removed): its run thread is closed with the reason. */
+  withdrawRun(input: { runId: string; reason: string }): Promise<void>;
+  /**
+   * Which of these runs still have an execution running. The dispatcher asks
+   * about the runs it inherited from the execution before it: it started none
+   * of them, so their end reaches it only as the run's own signal — and a run
+   * terminated, or ended without finishing, sends none.
+   */
+  runsInFlight(input: { runIds: string[] }): Promise<{ running: string[] }>;
+  /**
+   * A schedule fired: create the run (its thread, its work item) and start
+   * the interpreter. A Temporal schedule can only start a workflow, so the
+   * `startScheduledRun` workflow calls this, then runs the interpreter on
+   * the answer as its child and waits for it. Null when the trigger is gone
+   * or paused: nothing to run. The workflow chooses the run's id (`runId`,
+   * replay-safe), so a retried call — the thread and the node were made,
+   * the completion was lost — prepares the same run, not a second one
+   * beside a first left running.
+   */
+  startTriggeredRun(input: { triggerId: string; firedAt: string; runId: string }): Promise<{ run: InterpretInput | null }>;
+}
+
+/** The interpreter's own STATE keys. A step's outputs may never write them. */
+export const INTERPRETER_STATE_KEYS = [
+  'step',
+  'verdict',
+  'attempt',
+  'attempts',
+  'retries',
+  'entries',
+  'assignee',
+  'blocker',
+  'lastError',
+  'sessionIds',
+  'workflowId',
+  'workflowVersion',
+  'resumeStep',
+] as const;
+
+/**
+ * What a run takes over from a work item an earlier run left its STATE on (a
+ * ticket released back to its trigger's status): the steps' own outputs (a
+ * branch, a pull request's address) and the step the earlier run stopped in,
+ * as `resumeStep`. Everything a runner keeps for itself is left behind —
+ * counters, sessions, the last error, and the keys the workflow reserves — so
+ * the new run has its budgets whole and resumes no session of another run.
+ * The position is `resumeStep` when the earlier run recorded one, else `step`
+ * (a runner that kept the step's name there); the interpreter starts at the
+ * top when no step has that name.
+ */
+export function resumableState(state: Record<string, unknown>, reservedKeys: readonly string[] = []): Record<string, unknown> {
+  const own = new Set<string>([...INTERPRETER_STATE_KEYS, ...reservedKeys]);
+  const kept = Object.fromEntries(Object.entries(state).filter(([key]) => !own.has(key)));
+  const at = typeof state.resumeStep === 'string' ? state.resumeStep : typeof state.step === 'string' ? state.step : null;
+  return at ? { ...kept, resumeStep: at } : kept;
+}
+
+/**
+ * The most steps one run executes before it is blocked as looping: a file
+ * whose `then:` routing cycles while every step passes would otherwise start
+ * paid model sessions without end. The interpreter's guard and the local
+ * runner's, one number.
+ */
+export const MAX_RUN_STEPS = 500;
+
+/** The queue the platform's own worker polls: `environment: none` steps and every non-step activity. */
+export const PLATFORM_TASK_QUEUE = 'platform';
+
+/**
+ * The failure an in-process step raises when the platform stopped under it (a deploy, a restart): not the step's
+ * own failure, so the interpreter runs it again on the worker that comes up, on its own thread, from its saved
+ * session (`MAX_STEP_RESTARTS` times at most). A worker that died without a word is the same thing, seen as a
+ * missed heartbeat.
+ */
+export const PLATFORM_RESTART = 'PlatformRestart';
+/** How often one step goes on after the platform restarted under it, before the restart counts as its failure. */
+export const MAX_STEP_RESTARTS = 2;
+/** The queue the deployment's executors share: a step no run has pinned or named an executor for. */
+export const EXECUTOR_TASK_QUEUE = 'executors';
+
+/** The queue of the deployment's executor by that name: the runs pinned to it, and the runs that name it. */
+export function deploymentExecutorQueue(name: string): string {
+  return `executor-${name}`;
+}
+
+/** The queue a run that names an executor sends every container step to. */
+export function namedExecutorQueue(input: Pick<InterpretInput, 'executor' | 'executorKind' | 'actor'>): string | null {
+  if (!input.executor) return null;
+  return input.executorKind === 'deployment' ? deploymentExecutorQueue(input.executor) : personalExecutorQueue(input.actor.userId, input.executor);
+}
+
+/**
+ * The queue of a person's executor by that name. Derived from the run's own
+ * person, never from anything a file says about whom: a workflow naming
+ * `executor: laptop` reaches the laptop of whoever the run acts for, and no
+ * file can send a step to somebody else's machine.
+ */
+export function personalExecutorQueue(userId: string, name: string): string {
+  return `personal-${userId}-${name}`;
+}
+
+/**
+ * How long a step an executor took may go without a "still alive" before the
+ * platform gives it up (the executor reports every 30 s). Every executor
+ * reaches the platform over HTTPS, personal or the deployment's. Under
+ * the container step's heartbeat limit on purpose, so the platform's own
+ * reason ("stopped answering") is the one the run records, not Temporal's.
+ */
+export const PERSONAL_EXECUTOR_SILENCE_MS = 90_000;
+
+/** A container step's heartbeat limit on Temporal; above {@link PERSONAL_EXECUTOR_SILENCE_MS}. */
+export const CONTAINER_STEP_HEARTBEAT_MS = 2 * 60_000;