Jobs

Jobs are durable execution units. JobDef stores the reusable definition; Job stores mutable execution state, history, locals, usage, errors, and continuation fields.

Symbol	Import path	Purpose	Stability
`JobDef`	`statek.executors.job`	Defines agent, metadata, warmup, prompt params, chat style, locale	Core
`Job`	`statek.executors.job`	Durable execution state	Core
`JobStatus`	`statek.executors.job`	Lifecycle enum	Core
`JobDefError`	`statek.executors.job`	Stored job-definition error	Core

`JobStatus`

JobStatus.READY
JobStatus.WARMING_UP
JobStatus.STARTED
JobStatus.SUSPENDED
JobStatus.DONE

Use JobStatus to query and tag jobs in dbzero.

`JobDef`

@db0.memo
@dataclass
class JobDef:
    agent: Agent
    metadata: Optional[dict[str, str]] = None
    job_params: Optional[dict[str, Any]] = None
    warmup_code: str | CodeBlock | Sequence[str | CodeBlock] | None = None
    _chat_style: Optional[ChatStyle] = None
    locale: Optional[StatekLocale] = None

Freezes the configuration used to create and run jobs.

Import path: from statek.executors.job import JobDef

Parameters

Name	Description
`agent`	Agent assigned to the job. The object is tagged with this agent.
`metadata`	Job metadata. If omitted, agent metadata is copied. `MODEL` is required.
`job_params`	Values passed into prompt formatting.
`warmup_code`	Optional Python code executed before the first LLM request.
`_chat_style`	Optional job-level `ChatStyle` override.
`locale`	Optional `StatekLocale` for language-specific behavior.

Properties and methods

Member	Returns	Description
`model`	`str	None`
`model_family`	`str	None`
`provider`	`str	None`
`chat_style`	`ChatStyle	None`
`set_error(error, collect_traceback=True)`	`None`	Stores a `JobDefError` tagged to this definition.
`get_errors()`	`Iterable[JobDefError]`	Yields stored definition errors.
`has_errors()`	`bool`	Returns whether errors exist.
`clear_errors()`	`None`	Removes stored definition errors.
`update_warmup_code(warmup_code)`	`None`	Parses and replaces warmup only when changed.
`set_chat_style(chat_style)`	`None`	Sets or clears the job chat-style override.

Raises

JobDef(...) raises ValueError when no MODEL metadata is available.

from statek.executors.job import JobDef
 
job_def = JobDef(
    agent=agent,
    metadata={"MODEL": "openai/gpt-5-mini"},
    warmup_code='print("ready")',
)

`Job`

@db0.memo
class Job:
    def __init__(
        self,
        job_def: JobDef,
        job_status: JobStatus = JobStatus.READY,
        py_env: PyEnv = None,
        chat_log: list[str | ChatLogItem | UserLogItem] = None,
        awaited_result: FutureResult | None = None,
        next_instr_num: int | None = None,
        warmup_block_num: int | None = None,
        error: JobDefError | None = None,
        created_at: datetime | None = None,
        parent_job: Job | None = None,
        model_family: str | None = None,
        model: str | None = None,
    )

Represents one durable unit of work and its persisted Python environment.

Import path: from statek.executors.job import Job

Important attributes

Attribute	Description
`job_def`	The immutable job definition.
`parent_job`	Parent job for subtasks, if any.
`py_env`	Python locals, console output, and exit status.
`chat_log`	Stored warmup, user, assistant, tool, and notification history.
`awaited_result`	Future that suspended the job, when status is `SUSPENDED`.
`next_instr_num`	Continuation instruction index after suspension.
`warmup_block_num`	Current warmup block index.
`error`	Stored job error, if terminated by an error path.
`created_at`	Creation timestamp.
`usage`	Accumulated LLM usage. See STATEK Metering for fields and cost resolution.
`num_completions`	Count of completed units observed when a `DONE` job is reactivated.

Common properties and methods

Member	Returns	Description
`status`	`JobStatus`	Current lifecycle status.
`model`	`str	None`
`model_family`	`str	None`
`system_prompt(difficulty=None)`	`str`	Formats the agent prompt for this job.
`find_locals(var_type=None, var_name=None, ext_scan=True)`	`Iterable[Any]`	Searches Python locals and persistent context.
`add_locals(**kwargs)`	`None`	Injects values into the Python local state.
`find_sub_task_handler(id=None)`	`SubTaskHandler	None`
`push_notification(handler)`	`None`	Adds a completed subtask notification.
`add_ext_ref(obj)`	`None`	Tracks an external memo reference.
`contains_ext_ref(obj)`	`bool`	Checks an external memo reference.
`add_error_handler(error_handler, context)`	`None`	Registers a handler for job termination errors.
`add_error_handlers_from(parent_job)`	`None`	Copies handlers from a parent job.
`notify_handlers(error=None)`	`None`	Invokes and clears registered handlers.
`tokens_per_sec()`	`float`	Approximate provider-token throughput from recorded job history and response timing.
`approx_token_usage`	`int`	Byte-based harness estimate: `(total_bytes_sent + total_bytes_received) // 4`.

See Error Handling for the cleanup pattern and handler caveats.

Raises

push_notification(...) raises RuntimeError if the handler has not completed. find_sub_task_handler(id=...) raises RuntimeError when a specific id has not completed.

from statek.executors.job import Job, JobStatus
 
job = Job(job_def=job_def, job_status=JobStatus.READY)
job.add_locals(customer_id="C-123")
 
print(job.status)
print(job.py_env.local_state["customer_id"])

Related APIs: Runners, Subtasks, Context.

Agents Tools