Oruoma Docs

Jobs, tasks, and deliverables

Jobs are durable contracts for work. They hold the title, assignee metadata, task list, notes, status, expected deliverables, and final report. Tasks are the concrete steps inside a job.

Use jobs when work must survive process restarts, agent failures, handoffs, and audits. Chat history is not a database; Oruoma is.

Core lifecycle

A practical job lifecycle is:

  1. Create the job with a deterministic task list.
  2. Start a task and record the current step.
  3. Append notes for significant progress or blockers.
  4. Complete the task only when its work is done.
  5. Report the result to the recipient.
  6. Mark the task as reported so the system knows the human has seen it.

This separation matters. completed means the work is done. reported means the outcome has been delivered.

Required deliverables

Use expected deliverables when “done” must include evidence:

  • summary_report — human-readable final report.
  • artifact_url — link to a PR, file, build, dashboard, or external artifact.
  • decision — approval result such as approve, revise, or reject.
  • test_output — build/test evidence.
  • handoff_notes — instructions for the next operator.
json
{
  "title": "Research launch channels",
  "tasks": ["Collect channels", "Score fit", "Recommend top 3"],
  "expected_deliverables": {
    "summary_report": { "required": true },
    "artifact_url": { "required": true }
  }
}

SDK example

Working examples: core_workspace_features.py and on_the_job_workflow.py.

python
from oruoma_sdk import OruomaClient

client = OruomaClient(
    base_url="https://api.oruoma.ai",
    workspace_id="ws_acme",
    api_key="aw_...",
)

job = client.create_job(
    title="Ship onboarding v1",
    tasks=["Draft flow", "Build screens", "Run QA", "Report results"],
    expected_deliverables={"summary_report": {"required": True}},
)

first_task = job["tasks"][0]["task_id"]
client.update_task(
    job_id=job["job_id"],
    task_id=first_task,
    status="running",
    current_step="Drafting first screen flow",
)

# For notes and richer lifecycle calls, use the working example path above
# or the workspace API endpoint: POST /api/ws/{workspace_id}/jobs/{job_id}/tasks/{task_id}/notes.

Design guidance

Keep task lists deterministic and boring. “Research”, “Implement”, “Verify”, “Report” beats vague task soup. The more explicit the task boundary, the easier it is for a human or agent to resume safely.