Skip to content
Browse documentation
recipes

Interactive Agent

Adapt a local scratchpad assistant with streaming, approval-gated note writes and SQLite conversation history.

An assistant with a reviewable action

Chat with a scratchpad assistant, approve a note change, and reopen its saved conversation after restart. The Octane/Whisk browser receives streamed responses; the server owns the Agent, model credentials, Tool policy and SQLite transcript.

Try the approval flow

Configure SMOOTHIE_MODEL and a server-only OPENAI_API_KEY using the copied .env.example. Sending a message can incur model charges; approval protects the note write, not the preceding inference. Without model configuration, saved history remains readable but submission is disabled.

Ask “Remember that I prefer tea.” Approve the proposed note replacement to apply it, or reject it to cancel the turn without that write. Answer clarification questions in the same composer. Stop cancels the active execution; closing the tab only disconnects its stream. The README also describes a synthetic browser fixture that needs no credentials.

Where to make changes

shared/contracts.ts             # validated browser/server messages
targets/web/main.tsx             # chat, approvals and streamed presentation
targets/server/execution.ts      # instructions, Tools, policy and context
targets/server/assistant.ts      # admission and execution coordination
targets/server/repository.ts     # SQLite transcript and idempotent note writes
targets/server/logging.ts        # JSON-line provider log sink
targets/server/app.ts            # HTTP and SSE boundaries
targets/server/main.ts           # configuration and process lifetime

Replace the scratchpad Tools and repository with your domain, keeping authorization and effect idempotency explicit. See Application execution ownership for the Feature/Core boundary and Approval requests and decisions for review.

Read provider logs

Releases with targets/server/logging.ts write provider events as JSON lines to server stdout. Filter by invocationId to follow one model call and attemptId to inspect an individual request. Records include outcomes and safe error metadata; they omit prompts, responses, Tool arguments and credentials. Startup messages are separate plain-text lines.

Replace createJsonLineSink in logging.ts to send records to your logging service. Keep the sink on the server. Shutdown allows 1.5 seconds to drain pending records and reports delivery loss to stderr. See provider diagnostics for configuration and delivery limits.

Local history is not resumable execution

SQLite saves accepted inputs and validated terminal outputs. Restart marks unfinished turns interrupted; it does not resume inference or pending approvals. Active sessions and continuations remain in memory. Only one server may own the database at a time.

This profile has a fixed local owner and no authentication. Keep its listeners on loopback; do not expose it publicly. Browser history is bounded and stored records are not automatically pruned. Production asset hosting is not provided: build emits the browser files, while start runs only the API.

Follow the copied README for setup and deterministic tests, then the verification Guide. Those tests use synthetic providers; passing them does not qualify a live model or production service.