OpenOmniBot Documentation

The assists module provides a streamlined set of capabilities for managing public task lifecycles, chat requests, and state callbacks. It is composed of several core components:

• AssistsCore: The primary public interface for interacting with tasks.
• StateMachine: Handles the management of task states.
• TaskManager: Responsible for task registration and scheduling.
• controller/http: Manages chat and model requests.
• api: Contains public models, enumerations, and listeners.

ReTerminal provides a modern terminal experience with the following capabilities:

• Basic Terminal: Core terminal emulation.
• Virtual Keys: On-screen keyboard support.
• Multiple Sessions: Ability to manage and switch between different terminal sessions.
• Rootfs Support: Support for Alpine Linux and Ubuntu rootfilesystems.
• Configurable Keyboard Shortcuts: Customizable shortcuts for actions like Paste and Session Management.

Prompt caching (both automatic and explicit) is compliant with Zero Data Retention (ZDR) policies. Anthropic does not store the raw text of your prompts or Claude responses.

Key technical details regarding cache data:

• Storage: KV (key-value) cache representations and cryptographic hashes of cached content are stored only in memory and are never stored at rest.
• Lifecycle: The minimum lifecycle for a cache entry is 5 minutes (Standard) or 60 minutes (Extended), after which it is deleted quickly (though not immediately).
• Isolation: Cache entries are isolated between different organizations.

For full details on ZDR eligibility for all features, refer to the API and Data Retention documentation.

Omnibot skills are self-contained directories located within the workspace at .omnibot/skills/<skill-id>/.

An agent discovers a skill by reading the SKILL.md file's YAML frontmatter. To ensure successful discovery and execution, a skill should follow a specific directory layout to separate logic, documentation, and static files.

Recommended Directory Layout:

skill-id/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Resource Usage Guidelines:

• scripts/: Use for fragile flows, repetitive code, or tasks requiring deterministic output.
• references/: Use for schemas, API notes, policy text, or domain documentation that is too large for the main body.
• assets/: Use for templates, starter projects, icons, or example files that need to be copied or edited.

When a request with prompt caching is sent:

1. The system checks if the prompt prefix (up to the specified cache breakpoint) is already cached from a recent query.
2. If found, it uses the cached version, reducing latency and cost.
3. If not found, it processes the full prompt and caches the prefix after the response begins.

Lifecycle and Duration:

• The default cache lifetime is 5 minutes.
• Using cached content refreshes the cache at no extra cost.
• A 1-hour cache duration is available for an additional fee.

Most request blocks can be cached using automatic caching or by applying the cache_control marker.

Cacheable elements:

• tools: Definitions within the tools array.
• system: Content blocks within the system array.
• messages.content: Content blocks for user and assistant turns (text, images, documents).
• Tool use and tool results: Content blocks within messages.content.

Non-cacheable elements:

• Thinking blocks: Cannot be directly marked with cache_control. However, they are cached automatically when they appear in previous assistant turns and are passed back in subsequent requests (e.g., during tool use cycles).
• Sub-content blocks: Elements like citations cannot be cached directly; you must cache the top-level block (e.g., the document block containing the citations).
• Empty text blocks: Cannot be cached.

You can use both 1-hour and 5-minute cache control in a single request, but you must follow a specific ordering rule: cache entries with a longer TTL must appear before entries with a shorter TTL (i.e., 1-hour cache blocks must precede 5-minute cache blocks).

Billing Logic for Mixed TTLs

The API identifies three billing positions based on token counts:

1. Position A: The token count at the highest cache hit (0 if no hit).
2. Position B: The token count at the highest 1-hour cache_control block following Position A (defaults to A if none exists).
3. Position C: The token count at the final cache_control block.

You are charged for:

• Cache read tokens for A.
• 1-hour cache write tokens for (B - A).
• 5-minute cache write tokens for (C - B).

OpenOmniBot supports two types of time-based automation:

• Scheduled Tasks: These execute full subagent flows. A subagent can be assigned a complete task and behaves like a full agent.
• Alarms: These are used for reminder-only purposes.

Caching follows a hierarchy: tools → system → messages. A change at any level invalidates that level and all subsequent levels.

Note: When passing non-tool results in an extended thinking request, all previous thinking blocks and subsequent context are removed from the cache.

Prompt caching introduces a specific pricing structure and lifecycle:

Pricing

• Cache Breakpoints: Free to define.
• Cache Writing: Costs 25% more than base input tokens (for a 5-minute TTL).
• Cache Reading: Costs 10% of the base input token price.
• Uncached Content: Charged at regular input token rates.

Lifecycle (TTL)

• Default TTL: 5 minutes. Every use of the cached content refreshes this lifecycle.
• Extended TTL: Anthropic also provides a 1-hour cache TTL option for longer-lived content.