Durable tasks

A durable task runs on the SoulFire server. A detached task can continue after the SDK disconnects while its backend and bot remain available. Managed installation closes the local backend at scope exit. Scoped bot connection also stops bots started by that scope. Use an existing backend and a bot kept running when work must survive your application. Use a durable task for progress updates, cancellation, or shared bot control.

Start a task and keep its handleCopy Anchor Link

const task = yield* bot.tasks.autoEat(
  ["minecraft:bread"],
  { maximumMeals: 1 },
);

const result = yield* task.result();

A task handle exposes its stable ID and latest snapshot. Use it to refresh, watch revisions, wait for completion, decode the typed result, or cancel the task.

Attach ownership to a streamCopy Anchor Link

run* methods start a task and stream all revisions. Their default disconnect policy is CANCEL_WITH_CALL.

yield* bot.tasks.runAutoRespawn({
  maximumRespawns: 1,
}).pipe(Stream.runDrain);

from effect_py import fn, sync

@fn("consume stream")
def consume(event):
    yield from sync(lambda: print(event.task.status, event.task.progress))

yield from bot.tasks.run_auto_respawn(maximum_respawns=1).run_for_each(consume)

Interrupting the stream cancels its call-owned server task. Use a detached task handle when the work must survive the SDK process.

Observe progressCopy Anchor Link

const task = yield* bot.tasks.attackEntity(target);

yield* task.events().pipe(
  Stream.runForEach((event) =>
    Effect.logInfo(event.task?.progress?.message ?? "Working")
  ),
);

Progress includes a message, current count, optional total, and optional fraction. Terminal snapshots include a typed result or structured failure.

Cancel explicitlyCopy Anchor Link

yield* task.cancel("Target changed");

Cancellation is idempotent for a terminal task.

Choose conflict and reconnect policyCopy Anchor Link

Tasks declare resources such as movement, rotation, hands, inventory, containers, chat, and automation. Independent work can run together. Conflicts can reject, queue, replace, or suspend lower-priority tasks.

Reconnect policy controls what happens when the Minecraft connection changes:

• Fail the task because connection-scoped references are no longer valid.
• Pause and resume after reconnect.
• Continue when the task can safely reacquire state.

Reattach to a detached taskCopy Anchor Link

Store the task ID returned by start. A later SDK process can call bot.tasks.get(taskId, resultSchema) in TypeScript or bot.tasks.get(task_id, result_type) in Python, then resume watching its revisions.

Use an idempotency key when retrying task creation after an uncertain network failure. SoulFire returns the existing task when the owner, bot, key, and input match.