Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the per-section files the session_agent_harness job type writes under ~/.blobhub-worker/jobs/. For the generic top-level layout (identity.yaml, credentials.yaml, instance.yaml, config.yaml, logs/{instance_id}/worker.jsonl) see Filesystem Layout.

​
Tree

~/.blobhub-worker/jobs/
└── session_agent_harness-{session_id}/
    ├── section.yaml             # per-section runtime state (event-poll cursor, attachment)
    ├── logs/
    │   └── section.log
    └── threads/
        └── {thread_alias}/
            ├── thread.yaml      # per-thread state (agent state, agent_session_id, cursors)
            └── logs/
                └── thread.log   # full untruncated agent stdio + tool I/O
The agent runs with cwd = workspace.work_folder; the worker keeps no separate agent-session directory on disk. Session resume is SDK-managed and keyed by agent_session_id (recorded in thread.yaml). job_id is deterministic: session_agent_harness-{session_id}. This guarantees stable paths across restarts, reinstalls, and config edits — and namespaces this job type away from any future ones.

​
File-by-file

​
section.yaml — per-section runtime state

Persisted by the worker. Recovery on next start re-reads this. 
name: my-project
job_type: session_agent_harness
session:
  org_id: org_01J...
  blob_id: blb_01J...
  revision_id: rev_01J...
  session_id: ses_01J...
attachment:
  status: attached                    # attached | refused
  attached_at: 2026-05-27T12:35:01Z
  error:
    code: null
    message: null
events:
  last_processed_at: 2026-05-27T12:40:00Z

​
logs/section.log

Section-scoped JSON-line log: poll cadence, event dispatch, thread discovery.

​
threads/{alias}/thread.yaml — per-thread state

The worker’s local, authoritative-for-recovery view of a thread, plus the inbound/outbound item cursors. This local layout differs from the wire envelope: it keeps workspace.agent_type and agent.state, and the agent_session_id resume pointer and error block are local-only — they never appear on the wire. The mapping is documented on Job Session Object. 
alias: my-feature-x
session: { ... }
workspace:
  agent_type: claude_code         # local layout keeps agent_type here (wire uses agent.type)
  work_folder: /Users/me/projects/foo
agent:
  state: active                   # "" | pending | active | completed | failed
  agent_session_id: ag_sess_...   # local-only resume pointer (never on the wire)
  error:                          # local-only failure detail (surfaces via thread_failed)
    code: null
    message: null
items:
  last_consumed:
    item_id: itm_01J...
    created_at: 2026-05-27T12:50:00Z
  last_posted:
    item_id: itm_01J...
    created_at: 2026-05-27T12:50:05Z

​
threads/{alias}/logs/thread.log

Captures the full untruncated agent stdio + tool I/O. When the worker truncates a thread item to fit the 350 KB budget, the local log retains the full payload — see Thread Items.

​
Why both server-side metadata and thread.yaml?

  • The server-side envelope is authoritative for handoff. Anyone with API access (web UI, SDK, another tool) reads it to see the agent state machine.
  • thread.yaml is authoritative for local recovery. The worker writes it before any externally observable side-effect, so a crash-restart finds a truthful local record.

​
See also