Actors

An Actor is a deployed definition for continuing interaction. A Session is its stable identity. Turns are FIFO units of work within the Session, and Runs provide the execution that serves them. One Run can process multiple Turns.

import { actor } from "@helmr/sdk"

export const assistant = actor({
  id: "assistant",
  idleTimeout: "90s",
  async run(session, ctx) {
    for (;;) {
      const turn = await session.receive()
      if (turn === null) return
      await turn.output.write({ type: "acknowledged", turnId: turn.id, runId: ctx.run.id })
      await turn.complete()
    }
  },
})

Start with a Computer and optional stable key, idempotency key and Run options. Then enqueue the first Turn separately. session.receive() consumes FIFO work; turn.onMessage handles interactions within that work. Interface routing, provider SDKs, native questions and approvals remain editable application code.

Input, output and lifecycle events share a retained sequence. An output stream ending does not complete a Turn: finish post-processing and explicitly call turn.complete or turn.fail. A failed Turn and a failed Session are distinct.

Turn settlement persists the result and advances the Session’s input cursor. It does not pause the Computer, upload its disk, or replace the running process. Following Turns can use the same files, processes, and in-memory SDK state. Computer checkpointing is a separate operation: a completed Turn does not promise that all local file changes have been saved outside the Worker. If the Worker is lost, completed results remain, while unpublished Computer changes may be lost and execution requires recovery.

Sessions are open, closing, closed, or failed. Closing drains accepted work. Interruption retains later Turns behind a hold until explicit resume; it does not replay the interrupted Turn. Uncertain execution requires reconciliation. An idle timeout can shorten the warm wait before checkpoint/suspension without closing the Session. Arbitrary provider sockets and promises are not managed waits.

Use a Task for bounded work, a Token for one externally completed value, and an Actor for continuing interaction with explicit work and message lifetimes. See Actors, Sessions and Turns for the API.