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.

When a session_agent_harness section attaches to a BlobHub session, it creates a session object whose alias is literally worker. This object serves two purposes at once:
  1. Affinity lock — the value’s metadata.user.user_id identifies which BlobHub user owns the session for this worker; a different user is refused with SESSION_OWNED_BY_DIFFERENT_USER.
  2. Activity log — the value is a thread-typed session object, so the worker can post items into it as it operates. The activity log is visible to the user (rendered by the standard thread widget) and forms an audit trail.

​
Value shape

type: thread
thread:
  attributes:
    name: worker
    description: BlobHub worker activity log
  metadata:
    user:
      user_id: usr_01J...
    instance:
      instance_id: ins_01J...
      version: 0.1.0
      started_at: 2026-05-27T12:35:00Z
      last_seen_at: 2026-05-27T12:36:30Z
      status: attached          # only value written in v1 (informational)
metadata.user.user_id is the only field consulted for affinity. Everything under metadata.instance is informational and changes on every start. The status field only ever carries attached in v1 — no other status value is written. On clean shutdown the worker leaves the object as it is (last_seen_at simply goes stale) and refreshes it on the next attach.

​
Attach algorithm

On blobhub-worker start, each section runs this sequence: A refused section is recorded in section.yaml.attachment with status: refused and the relevant error.code / error.message. The worker process keeps running other sections — only the refused section is stopped.

​
Heartbeat

While running, the worker periodically refreshes metadata.instance.last_seen_at via upload_session_object on the worker object. This is informational only — it does not drive takeover. A second worker attempting to attach with a different user_id is refused even if last_seen_at is fresh.

​
Detachment

There is no blobhub-worker detach command in v1. To free a session manually: 
# via REST: delete_session_object(session_id, alias="worker")
If the worker is running and observes the session_object_deleted event for the worker alias, it stops that section with SESSION_DETACHED_EXTERNALLY and tears down all agents for that section cleanly. Other sections continue.

​
Activity-log items

The worker posts items into its own worker thread as significant events happen:
metadata.typeWhen postedmetadata extras
attachedsection attach succeeded(none)
thread_registeredworker first observed a thread envelopethread: {alias}
thread_activepending → active for a threadthread: {alias, agent_session_id}
thread_failed* → failed for a threadthread: {alias, error: {code, message}}
thread_completedactive → completed (user-set clean stop)thread: {alias}
thread_removedthread envelope was deletedthread: {alias}
thread_recoveredthread resumed on worker restartthread: {alias, agent_session_id}
Each item’s content[0].text is a short human-readable rendering of the same event.

​
Strict-exclusive ownership

The affinity model is strict-exclusive at the user_id level. There is no auto-takeover, no heartbeat-based override, and no detach command in v1. If two worker installs share the same API key (same user_id), they will race to overwrite each other’s instance block silently — recommended workaround is one worker = one service-account user. See Reference.

​
See also