DocumentationArchitecture
Execution and recovery
Follow a message from acceptance to completion, including interrupted streams and uncertain tool results.
On this page
From message to resultConversations and runsTool side effectsWorker and provider recoveryCancellation and schedulingFollow the implementationA run belongs to the account, not to the screen displaying it. This makes an agent useful when a phone sleeps, a browser reloads or a worker restarts.
The Impo API is the application interface used by clients and the gadget gateway. The Agent API is the server's interface for agent execution, currently supplied by Rebyte. A worker connects these two interfaces. Clients do not call the Agent API directly.
From message to result#
- The client saves its command with a stable
clientMessageIdand posts it to the Impo API. - The Impo API validates the request and owner, and commits the accepted message. After the commit it starts or signals that conversation's Temporal workflow, which runs the conversation's messages one at a time, oldest first.
- The workflow runs the turn as a Temporal activity on a worker, which sends the accepted input to the Agent API. If that worker stops, Temporal retries the activity on another worker, which reconciles with the Agent API by stable identifiers before writing anything new.
- The Agent API returns text and tool calls. The worker dispatches tools through Impo's registry and persists results before acknowledging them upstream.
- Clients subscribe to projected events. On reconnect they recover saved history and active submission state.
The stream uses the shared application protocol. A transport close is not proof of completion. Clients reconcile truncated streams rather than guessing the outcome.
Conversations and runs#
Main Chat is the person's primary conversation. Other conversations use the existing /tasks API and taskId identifiers. iOS calls these Conversations and calls scheduled entry points Triggers; the other clients still use Task labels. Completing one run does not close its conversation.
The current Agent API adapter uses Rebyte's Saved Agents and Sessions:
Main Chat uses one Saved Agent per user and a current Session. Session rotation bounds active context while keeping the entire conversation readable through historical bindings. Current defaults rotate before unsent input after six idle hours, eight turns or the configured context estimate threshold.
Each Task uses an independent Session and can accept follow-up messages. A gadget's continuing Conversation is one such Task, reused for its voice, text and events. It processes one turn at a time; a long turn delays later messages.
Tasks do not receive native-device tools or recursive task-creation tools. They can use configured server tools, including connected services and account-owned gadget commands. Adding a tool to the server registry does not automatically expose it to every execution context.
Tool side effects#
Each tool definition declares a timeout and retry policy. A read can generally be repeated. A transactional operation needs a durable idempotency receipt. An operation that moves hardware or plays audio may have an uncertain outcome and must not be repeated blindly.
Agent text is not a receipt. The UI should report completion from accepted execution state, and a tool should distinguish an accepted request from its eventual physical outcome.
Worker and provider recovery#
Leases fence expired workers so they cannot overwrite a replacement's result. Every Agent and Session creation carries an idempotency key derived from the record it serves. When a remote response is lost, the retry sends the same request under the same key and receives the resource that already exists, so a failed connection never duplicates work.
Cancellation and scheduling#
Closing a view only removes its subscription. An explicit cancellation command asks the execution layer to stop; the final state follows reconciliation with the remote turn.
Temporal coordinates scheduled triggers and background work. Each scheduled-task occurrence admits an ordinary Task with its own conversation. Revisions fence old timers, and overlapping occurrences are skipped. Keep timers separate from the task execution they admit.
Follow the implementation#
- Client protocol: commands, events and recovery.
- Runtime repository: durable admission and state.
- Rebyte repository: provider bindings and execution.
- Scheduled tasks: revisions, overlap and occurrence admission.