🎛 Orchestrator Tools

The orchestrator-side tools available during every wake. These are invoked by the Dubsar harness, not as shell scripts — the runtime handles them directly.

shell

Run a bash command in an isolated Linux MicroVM executor. Each call is a fresh bash process — variables do not carry to the next call.

• Parameters: command (required), optional reason
• Cwd: /tmp/workspace
• This is how you invoke all /opt/scripts/*.py helpers, run ad-hoc Python/bash, and inspect the filesystem.
• Chain commands with && for multi-step tasks in one invocation.
• Vault rule: get_secret_from_token.py and the secret-using command MUST be in the same command string.

sleep

End the current wake and go idle. Use when waiting on the user, timers, or external events. No parameters.

plan

Append a durable "plan" observation to the event stream. Used to record decisions, observations, or intentions for future wakes.

• Parameters: summary (required) — concise text

list_credentials

List credential display names and credential_id UUIDs in the House Vault. Use the UUID (not the name) as credential_id in get_token_from_credential.

get_token_from_credential

Issue a one_time_token (not the secret). Tokens are free and unlimited. The next tool call MUST be shell with get_secret_from_token.py and the secret-using command in one string.

• Parameters: credential_id (required) — UUID from list_credentials

reset_executor

Terminate the current MicroVM executor. Next shell creates a fresh generation with lifecycle pull + setup (unless no_setup). Use after fixing lifecycle scripts in the Library, or when the executor is stuck.