- chat.md, overview.md: how a streamed token renders only the live reply (runSummaries, the 32 ms notice gap, LiveThreadRuntime, the bounded highlighter, memoized panels) and that the columns resize. - model-capabilities.md, agent.md, data-model.md, 07-dev-setup.md: the two chat modes, their gates and defaults, where a pick is stored, the 0-id fix, and how to re-run the OpenRouter sweep and regenerate capabilities.json. - RELEASE.md: the steps 2.2.0 was released by, from the bump (with its PowerShell form) to the tag on the merge, the Known issues, an optional update check and publishing with --latest; dry runs are signed. - 06-repo-readme.md, AGENTS.md, README.md's comment: the README's structure, how to change it and its translations, re-checking the format table, and replacing the demo video. - Stale statements fixed (the Apple agreement, opencode never shipped, three languages, Studio's exec(), proposal statuses, the roadmap), and each gap still open after the release in its doc's Known gaps, linked to #2219-#2230.
87 KiB
Agent
A chat thread can be the agent's. opencode, started by Electron, then answers it in steps: it finds passages with SurfSense's search, reads a folder of the workspace's extracted text with its own tools, cites what it found as a chat answer does, makes Word documents, PDFs, PowerPoint decks and Excel workbooks as versioned scripts that SurfSense runs and lets it look at, starting a Word document or a deck from the user's own file when asked, starts other Studio jobs, writes what else it produces to an output folder, and reaches every model through SurfSense. It has no shell (ADR 0039). Every installer and dev run carries opencode, unless SURFSENSE_LOCAL_OPENCODE_ENABLED=0 is set when it is staged. Which engine a thread gets is decided when the thread opens: the user picks Basic (Q&A) or Agentic in the composer, and every model may pick Agentic unless a technical gate keeps it out (which threads get it). How to run it from a dev build is in 07-dev-setup.
Code: surfsense_local/backend/modules/agent/, surfsense_local/electron/src/main/sidecars/opencode.ts, surfsense_local/electron/src/main/docx-snapshot/, surfsense_local/electron/scripts/opencode/, surfsense_local/frontend/src/features/agent/, surfsense_local/frontend/src/features/docx-snapshot/
Decisions: ADR 0039, which supersedes ADR 0028 in part. The remaining work is in the agent proposal and the file agent proposal.
The parts
| Part | Where | Does |
|---|---|---|
| Staging | electron/scripts/opencode/ |
pnpm build:opencode fetches opencode 1.18.34 and ripgrep 15.1.0, each checked against its SHA-256, into electron/opencode/ (packaging), for every build unless enabled.mjs is told otherwise; check-stage.mjs runs both from the stage, electron-builder's after-sign.mjs hook runs it on the signed copy before any installer is made, and release CI runs it on each installer's copy |
| Process | electron/src/main/sidecars/opencode.ts, opencode-home.ts, opencode-leftovers.ts, watchAgentConfig in sidecars/boot.ts |
starts, stops and cleans up opencode serve (overview) |
| Engine choice | backend/modules/agent/engine_choice.py |
whether a thread opened now is the agent's |
| Configuration | opencode_config.py, prompts/agent.md, skills/ |
the file opencode runs with, and the skills it may load |
| Readiness | opencode_runtime.py, model_window.py, model_reads_images.py |
an opencode serving the current configuration |
| Model endpoint | model_endpoint/ |
the two routes opencode's provider calls, one per wire API, for every model |
| Tools | tool_endpoint/, pdf_tools/ |
SurfSense's search, Studio, document and PDF tools, served to opencode over MCP, one address per thread |
| Thread folders | thread_folder/ |
each thread's folder: the text of the sources it may use, in the user's folders and linked from one cache per workspace, and copies of the figures and pages it was shown |
| Previews | previews/, electron/src/main/docx-snapshot/, frontend/src/features/docx-snapshot/ |
page images of a document the agent made, so it can check them |
| Office support | backend/modules/office_support/ |
the one door to LibreOffice for previews, recalculated workbooks and PDF conversion, closed while Office support is off (office pack) |
| Client | opencode_client/ |
the only code that knows opencode 1.x's HTTP API |
| Threads | agent_threads/, and the chat routes that hand over to it |
opening, sending to, reading and deleting an agent thread (chat) |
| Ticked sources | agent_threads/turn_sources.py, agent_threads/scope_note.py, tool_endpoint/turn_scope.py |
the sources a thread may use, mirrored into its folder, told to the model and held to by the tools |
| Screen | frontend/src/features/agent/ |
a reply's steps, the versions it made, the sources a turn works from, and the approval dialog |
Which threads get it
A new thread is the agent's when it is opened in Agentic mode: the mode the user picked in the composer, or with none picked the selected model's default, Agentic for a model measured at or near the bar on a remote host and Basic (Q&A) otherwise (model capabilities). No measured score keeps a model out of Agentic. Only technical gates do: no opencode staged; a stated no on tool calls, which is the remote catalog's tool_call: false under the connection's catalog provider or a local model's template without supports_tool_calls in llama-server; or a stated window under 32,768 tokens. A catalog that says nothing of tool calls, and a runtime that cannot be read, let a model in, with the untested warning. A local model's template and window are read only when a thread asks for Agentic, since reading them loads the model. SURFSENSE_LOCAL_AGENT_UNTESTED_MODELS=1, set in the environment Electron starts the API from, makes Agentic the default for every model the user has not picked a mode for and lifts the window floor; a stated no on tool calls, or no opencode, still keeps Agentic out (engine_choice.py). Agentic asked for and gated is refused with 409 and its code; asked for while opencode does not become ready, 503 agent_unavailable; in both, no thread is made. A thread that asked for nothing opens as a chat then. A thread keeps its engine; its row stores the opencode session that holds its turns (data model). Once the selected model changes to one a technical gate keeps out, a turn sent to the thread is refused with 409 before any prompt is sent: the user chooses another model or starts a new chat. The screen says the thread can't continue with that model, in the user's language, with "Start a new chat" in place of Retry, as for a legacy thread (unsupported-model.ts).
From a thread to a running opencode
- Electron, at boot. Where an opencode is staged, Electron picks its port, a random password and a random Word snapshot key, passes them to the API alone, and removes any
agent/opencode.jsonthe last run left. opencode does not start yet. Where none is staged, Electron passes nothing, and the API mounts none of the routes opencode calls or that answer it: the model endpoint, the tool endpoint, the permission answer and the Word snapshot routes. - The API, when a thread first needs the agent.
ready_opencode()reads the selected model's window: what llama-server loaded a local model with, what a ChatGPT plan states for its model, or thecontextthe remote catalog records, else 32,768. It reads the route the model answers on. It reads whether the model reads images (Image input). It writes<data>/agent/opencode.json, readable by this user only, and only when its contents change. - Electron, on that file. Checked every 2 seconds: opencode starts once the file exists and stops when it goes. A crash restarts it, at most once every 10 seconds. A rewrite does not restart it.
- The API, until opencode serves it. opencode reads its configuration per folder, the first time the folder is used, and keeps what it read. So the API checks the running server's version is
1.18.34, readsGET /config, and callsPOST /global/disposeonce if what is loaded is not the provider package, launch key, window and image input just written. It returns when they match, or after 60 seconds with "not ready". Every call has a timeout, because opencode accepts a connection a moment before it answers it.
The configuration
| Setting | Value |
|---|---|
| Provider | one, surfsense, at http://<API host>:<API port>/agent/model/v1, with the launch key as its API key; enabled_providers lists only it. Its package follows the route the selected model answers on (connections): @ai-sdk/openai-compatible for /chat/completions, @ai-sdk/openai, which calls /responses, for a ChatGPT plan's model or one recorded as served only there |
| Models | model and small_model both name the selected model, so nothing asks for a second one the router would load in its place. Its entry declares tool_call, and image input (modalities.input ["text", "image"] and attachment: true) only for a model that reads images |
| Limits | context and input are the window W; output is min(W/4, 32,000); compaction.reserved is min(output, max(W/10, 8,192)), with compaction.auto on |
| Waiting | headerTimeout off and chunkTimeout 30 minutes, because a local model can take minutes before its first byte |
| Skills | skills.paths names the shipped skills folder, inside the API's own files when frozen |
| Permissions | bash is denied; edit and write are allowed under a thread's outputs/ and denied elsewhere: the allow matches any path holding /agent/threads/*/outputs/, so denies after it refuse such a path under a thread's sources/, .opencode/ (which opencode loads agent definitions from), its tool-output folder and the skills folder, and any file named AGENTS.md, CONTEXT.md or CLAUDE.md in three spellings, since the match ignores case only on Windows; another thread's outputs/ matches the allow but is outside the thread's folder, which external_directory refuses; external_directory is denied except the skills folder, with any path holding /../ denied after that allow; skill allows only SurfSense's own skills, surfsense-documents, surfsense-data and surfsense-pdf; webfetch, websearch, task and question are denied; SurfSense's tools run without asking, by opencode's default |
| Agent | surfsense, the default, whose prompt replaces opencode's coding prompt with how to work on the user's sources (prompts/agent.md) |
| Off | share, snapshot, autoupdate |
The API makes a new launch key at every start (launch_key.py), so a configuration from an earlier run never opens the model endpoint or the tools. opencode adds its own allow for its tool-output folder after these rules, where it keeps a long tool result for the agent to page through; nothing here denies it.
The documents skill
skills/surfsense-documents/SKILL.md is SurfSense's own text. It teaches the script contract (write the file to OUTPUT_PATH, open source images at IMAGES_DIR/<name>.png, a template's copy at TEMPLATE_PATH, python-docx for Word, ReportLab for PDF, python-pptx for decks, xlsxwriter or openpyxl for workbooks, matplotlib for charts saved as a PNG and placed), clean-document habits (built-in heading and list styles, real tables with a header row, A4 unless the user is in the US or Canada, images at most the text width), decks (16:9, layouts by name, placeholders, tables, pictures, native or matplotlib charts, speaker notes), workbooks (number formats, header rows, column widths, formulas where a total is meant, stored with the value each comes to, frozen panes, native charts), starting from a source's Word file or deck (keep its styles, headers, footers and layouts; remove its own body or slides), matching a look from surfsense_source_pages, charts from a source figure's values, editing (read the script, change only what was asked, make every requested change and say what was assumed, render with artifact_id), checking the previews or a workbook's summary, and the stop rule. Its Word, PDF, PowerPoint, Excel and two template examples run through the real runner in a test.
opencode finds it through skills.paths and offers it by its name and description; the agent loads it with opencode's skill tool, which the permission allows for this skill only, so neither opencode's built-in skills nor any the user installed for their own opencode load. The prompt tells the agent to load it before a Word document, a PDF, a deck or a workbook and repeats the editing rule in one line, because a compaction can drop a loaded skill from the context while the prompt stays. bundling/api.spec ships it (packaging).
skills/surfsense-revisions/SKILL.md, also SurfSense's own text and allowed the same way, teaches revising the user's own file: when to revise it rather than render a new document, document_id for the first edit and artifact_id after, quotes copied exactly from one paragraph and unique, every Word edit a tracked change with no way to turn tracking off, internal comments, comments (internal ones too) that rest only on the document or the user's request and never from laws, regulations or market practice outside them, each format's operations, and reading the report, the notes and the previews. The prompt is unchanged: the tool's description names the skill.
The data skill
skills/surfsense-data/SKILL.md is SurfSense's own text too. It teaches when to analyse (arithmetic over rows, grouping, joining, a chart) and when to read a source's text in sources/ instead, the analysis contract (INPUT_DIR with read-only copies and manifest.json, OUTPUT_DIR, the kinds of file kept, the libraries, 120 seconds), loading each format with pandas (separators, thousands, encodings, every sheet of a workbook, a header below the first row), looking at an unknown layout before computing, cleaning (stripped column names, numbers and dates coerced, a sheet's own total row dropped), printing only the figures asked for, saving tables and charts, placing a chart in a document by its name, and the stop rule. Its two examples run through the real runner in a test. It loads as the documents skill does; the prompt does not name it, so the analysis tool's description says to load it.
The PDF skill
skills/surfsense-pdf/SKILL.md is SurfSense's own text. It maps requests to the three PDF tools in a table, says how to name a source and an artifact and how a merge orders them, the page range syntax with what each example means, that stamps are written in the PDF's language and that {page} is the page's own number, that a form is listed before it is filled, with what each kind of field takes, and that only the user's values go in, when to flatten, and what cannot be done: signatures, XFA forms and password-protected files. It says the user's own file never changes. A test checks that every tool it names is offered and that its range examples parse as it says. It loads as the other skills do; the PDF tools' descriptions point at it.
Image input
model_reads_images.py answers whether the selected model reads images as the chat does (ADR 0034): llama-server's /models for a local model, the remote catalog's modalities.input under the connection's catalog provider for a remote one. A model the catalog does not know, or whose entries disagree, answers no, with no developer switch, because an image a text-only model refuses fails the request and opencode re-sends it with every later one.
When the entry declares image input, an image a tool returns reaches the model: an image opencode's read returns, and each MCP image item a SurfSense tool returns, which opencode keeps as a file attachment of the step. The openai-compatible SDK cannot carry media in a tool result, so opencode moves the images into a user message after the step, starting "Attached media from tool result:", and the model endpoint passes each part through as an OpenAI image_url. On /responses, opencode's OpenAI provider keeps them in the call's own function_call_output, as input_image items after its text, and the relay passes that output on unchanged, a ChatGPT plan's too. Without the declaration, opencode replaces each image with an error text before the request leaves it, so surfsense_render_document draws no previews and says why, surfsense_source_pages is not offered, the endpoint drops any image item from a result when the configuration changed during the call and adds a line saying so, and the skill tells the agent to check the script and the returned text instead. A live run carried page images to Claude Sonnet 5.5 through Anthropic's OpenAI-compatible API, and the model described them correctly. The prompt tells the agent that text inside an image, such as a source's page, is data, since it now arrives in a user message unasked.
Folders
<data>/agent/
├── opencode.json the configuration the API writes
├── opencode-process.json the running opencode's pid, port and password, for the next boot
└── opencode/ opencode's home: its XDG config, data, cache and state, sessions included
<data>/data/workspaces/<id>/agent/
├── text/ `<source id>-<sha256 of its text, 16 hex>.md`, one per version of a source's text
└── threads/<thread id>/ one agent thread's folder, opencode's instance directory for its session
├── sources/ the thread's sources: `Library/<folder>/…/<title> [<id>].md`, each a hard link into text/
│ ├── figures/ `<source id>-<n>.png`, a copy of each figure `surfsense_list_images` listed
│ └── pages/ `<source id>-p<n>.png`, a page `surfsense_source_pages` drew
└── outputs/ what the agent writes; never touched by SurfSense except previews/ and analysis/
├── previews/<artifact id>-v<n>/page-<k>.png
├── previews/<artifact id>/page-<k>.png a page of a PDF a PDF tool made
└── analysis/<run>/ the tables and charts one `surfsense_analyze_data` run saved
Each agent thread works in its own folder (thread_folder/). Its session is created there, and its turns sync, register the tools, stream, check status and answer approvals there. sources/ holds only the sources the thread's scope resolves to (the ticked sources), each at the path of its folder in the Library, so the agent finds a source where the user filed it; an unfiled artifact ticked by id sits at the top. Paths are decided from the workspace's live folders and the source's own row, never the scope, so a tick never moves another source (mirror_path.py): characters a file system refuses become _, leading and trailing dots and spaces go (a leading dot would hide a folder from grep and glob), a name is cut at 100 characters, a Windows device name, an instruction file's name, outputs (so no mirrored folder passes for the agent's on macOS, where the edit rules match case as written but the disk ignores it) or a top-level figures or pages gains _, siblings equal once made safe get [f<folder id>], and a folder whose directory would pass 247 characters, or leave under 24 for a file within 259, has the deepest uncut folder of its chain cut to 8 characters and its id, so a folder is always one directory. A title is then cut to fit; past that the file goes to the top as <8 characters> [<id>].md, and one that fits nowhere is left out with a warning. The [<id>] always stays. Lengths are counted in UTF-16 units, as Windows counts them, so an emoji counts two. Figures, pages and previews have names that cannot be cut, so each is checked against the same 259 and 247 (path_budget.py): where the thread's folder sits too deep for one, a figure's line says it has no copy to open, surfsense_source_pages is refused, and a render gets no previews, each in a sentence. A file's partial copy is never named longer than the file.
Before each turn the folder is brought in line in short transactions, never writing a file inside one (sync.py): the layout and the sources with text in one, then their text 200 at a time. Each text is written once to text/ under its digest and hard-linked into the thread, so threads share one file per version and Defender scans it once; on a disk without hard links (FAT, exFAT) each thread gets a copy, logged once. Anything else in sources/, file, folder, link or junction, is removed without following links, empty folders are pruned, and figures and pages of sources no longer in scope go. Anything under outputs/ named like an instruction file is renamed with a trailing _. At most every 10 minutes, cache files older than 10 minutes that no thread links are deleted. Syncs of one thread are serialised; two threads syncing one changed source at once may leave one a turn behind. The first sync in each workspace per run removes the folders every thread once shared, agent/sources/ and agent/outputs/previews/ (the rest of agent/outputs/ stays until the workspace goes), and any threads/<n>/ that is no agent thread of the workspace.
Deleting a thread aborts and deletes its session, disposes its opencode instance with POST /instance/dispose?directory=<thread folder>, deletes the row (its artifacts stay), then removes the folder once any sync of it has finished; a turn that reaches its sync after that ends its stream with an error frame and writes nothing.
Instances. At most six thread instances stay in opencode (live_instances.py). A turn, a read of the thread back and opening its session each count as a use; after each turn the least recently used instances past six are disposed with POST /instance/dispose?directory=<thread folder>, never one whose turn is streaming, which is where an approval waits too. A disposed thread's next call starts a new instance from its stored session. Instances are picked one at a time, so two turns ending together never dispose one twice, and a turn that begins while its instance is being disposed waits for opencode to answer before adding its tools, which the dying instance would lose. A thread deleted while its turn streams is not listed again when the turn ends. Deleting a workspace disposes each of its threads' instances first.
Legacy threads. A thread opened before threads had folders has its session in agent/, and a session cannot move. Such a thread is told apart by its session's directory (GET /session/{id}) and stays readable, but a turn is refused with 409 before anything is sent: "This agent chat was started before each chat kept its own sources. Start a new chat to continue." (legacy_thread.py). The screen shows that sentence in the user's language under the unsent message, with "Start a new chat" in place of Retry (outdated-thread.ts). Its old files in agent/outputs/ stay until the workspace is deleted. Moving the data folder makes every agent thread legacy. A thread whose session opencode no longer has, where GET /session/{id} answers 404, is refused with the same 409 and sentence, so the screen offers a new chat there too. Only a legacy answer is kept for the run: a session in its thread's folder is asked about before every turn, since opencode can lose it after an earlier turn worked.
The model endpoint
POST /agent/model/v1/chat/completions and POST /agent/model/v1/responses (model_endpoint/) are opencode's only way to a model. Each refuses a request without this process's launch key with 401, resolves the selected model on every request, answers 409 with code wrong_route when the model answers on the other route, and marks it in use while the turn runs. /chat/completions on the local runtime admits each request as interactive work, beside chat (admission).
- Local: llama-server's router at
{llamacpp_base_url}/v1, under the selected model's name. - Remote: the connection's URL with its own key, once
egress.require()allows its host; a refused host answers403naming it, before any connection opens (egress). - The request, on
/chat/completions:toolsandtool_choicepass through; everysystemanddevelopermessage is joined into one system message first, because local chat templates want one there; assistant turns with no text and no call are dropped; control tokens such as<|im_end|>in user and tool text are split by a zero-width space, because tool results carry the user's documents. Image parts pass through untouched. opencode names its session inx-session-affinityon every request; a remote host that routes a conversation by a key gets that name as one (connections), so an agent's steps reach the machine that cached their prompt. - The reply: the model's own status and body pass through, so opencode reads a full window from llama-server's own wording and compacts. A stream passes byte for byte, a whole line at a time; only a line feed ends a line, so U+2028, U+2029 and U+0085, which a model leaves raw inside its JSON, never split one, here or in any other reader of a stream (
sse_lines.py). SurfSense's own errors are{"error": {"message": …}}. Every/chat/completionsstream ends with[DONE], added when the model leaves it out; a/responsesstream ends on its own terminal event (response.completed,response.incomplete,response.failedorerror, listed once instream_endings.pyfor the chat's client too), and one that stops or breaks before it gets anerrorevent, because opencode's provider takes a stream that just stops as a finished step. opencode retries that step after a pause; the words the broken attempt streamed stay in the thread until the turn'scompletedframe replaces them with the stored reply. There is no limit on waiting; opencode's configuration sets its own. /responses: for a model recorded as served only there, the connection's URL with its key; for a ChatGPT plan, its token and the plan's limits (responses_relay/, ChatGPT subscription). The step passes through otherwise unchanged, under the selected model's name.
SurfSense's tools
POST /agent/tools/workspaces/{workspace_id}/threads/{thread_id} (tool_endpoint/) answers opencode's MCP client: MCP 2025-11-25 over Streamable HTTP, stateless and JSON only, written without an MCP library. It answers initialize, tools/list, tools/call and ping, and 202 to a notification. It refuses a request without the launch key with 401, one carrying an Origin header, as a web page's does, with 403, another protocol version with 400, a workspace that does not exist with 404, and GET with 405. The workspace and thread in the path scope every tool, because a tool call names neither its folder nor its session (the ticked sources); the old address without a thread answers 404.
| Tool, as the model sees it | Takes | Does |
|---|---|---|
surfsense_search_sources |
query |
the chat's own retrieve() over the thread's sources; up to 5 passages, each as <passage cite="[<chunk id>]" source="sources/<path>" lines="<a>-<b>">, the path being the source's in the thread's folder and the lines that file's |
surfsense_create_artifact |
format, one of Studio's formats except docx, pdf, pptx and xlsx; source_ids, the numbers at the end of the source files' names; instructions, at most 2,000 characters |
Studio's own create_artifact_job(), which returns at once with the artifact pending. A source not ticked for the turn is refused. Asked for one of those four, it refuses and names surfsense_render_document, because Studio's draft keeps no script to edit |
surfsense_render_document |
title; format, docx, pdf, pptx or xlsx; script; artifact_id, to make the next version of, refused for any version of a document Studio made, which Refine rewrites in Studio, and for a revised copy or a converted PDF, which keep no script and have no Refine, naming surfsense_revise_document or the Word version or deck to change and convert again (unscripted_base.py); images, names from surfsense_list_images, of ticked sources only; template_source_id, a ticked source's own .docx for docx or .pptx for pptx, kept by later versions |
runs the script as a new version in Studio and waits for it (below) |
surfsense_read_document |
artifact_id, of any version, or document_id, a workbook source; sheet, a workbook's sheet; offset, an optional 1-based line, or a workbook's row, to start from |
the agent's newest version's number (a lineage it continued from a Studio draft before such renders were refused skips Studio's later versions), artifact id, title, format, status and the images it places, and its script in pages of at most 1,000 lines and 40,000 bytes under "Script, lines a-b of n", ending with the offset of the next page, so a result stays under opencode's truncation limits (script_page.py). A document Studio made is refused, as a render continuing one is: "This document was made in Studio: refine it there, or make a new document." Given the artifact_id of a revised copy, it reads the copy's newest ready version as it reads now (read_revised_copy.py): a Word copy's body with every author's tracked changes marked inline as <ins author="…"> and <del author="…">, [comment N] after the text each comment is on, then each comment with its author, whether it is internal, and that text (word_marked_text.py), under its counts of tracked changes and comments; a deck's text slide by slide; a workbook's cells as below. Word and deck text come in pages of lines as a script does. Excel and PowerPoint keep no tracked changes, so their opening counts the edits applied over the copy's versions instead. Every answer ends its opening with the artifact_id to revise. Given document_id, a ticked .xlsx or .xlsm source, or the artifact_id of a revised copy of one, it returns the workbook's cells instead, read from the file itself (the source's original, or the copy's newest ready version) with openpyxl in read-only mode and formulas as written: each sheet's name and used range, then each non-empty cell as B7 = 1250.5, A1 = "text" or C3 = =SUM(C2:C2), under the same 40,000 bytes (read_workbook.py, cell_map.py). sheet reads one sheet and offset is then the row to start from; a cut map ends with the row and the call that reads on, or, when one row holds more cells than a map shows, the first cell left out and the next row to read on from. The file is read once the tool's database reads have ended, so a big workbook's seconds of reading never hold SQLite's write lock. Sheet headings take at most a quarter of the map; the sheets past that are only named, up to 4,000 bytes, then counted. The indexed text of a workbook is Docling's tables, without sheet names, addresses or formulas, so the revise tool and the revisions skill send the agent here first. Any other source is refused, pointing at sources/. |
surfsense_list_images |
source_ids |
each source's figures, one line each: its name, size in pixels, page and caption when known, and its copy under sources/figures/ to open with read; or that the source has none, is not in this workspace, or has its figures being extracted, which queues the figures-only pass (documents). A source not ticked for the turn is refused |
surfsense_source_pages |
document_id; pages, at most four page or slide numbers from 1, the first ones when left out |
a PDF, Word or PowerPoint source's own pages as images with the result, in ascending order, with the source's page or slide count; copies at most 1,000 pixels on their long side stay in sources/pages/<id>-p<n>.png for a closer look (below). Offered only when opencode.json declares image input. A source not ticked for the turn, an image, a note or any other kind of file is refused in a sentence saying what to use instead |
surfsense_convert_document |
artifact_id, a Word or PowerPoint version the agent rendered, or document_id, a ticked .docx or .pptx source, exactly one; format, pdf |
a new PDF document in Studio, made by LibreOffice from a copy, the file converted never written, and the PDF's page count, its first 1,000 characters and up to four page previews as images (below). Listed whether or not Office support is on, so the tool list never changes mid-thread; while it is off, refused with "Converting to PDF needs Office support, which is off on this computer" and where the user turns it on. A source not ticked for the turn, a workbook, a PDF, a version not ready and any other file are refused in a sentence |
surfsense_revise_document |
document_id, a ticked source's .docx, .xlsx, .xlsm or .pptx, or artifact_id, a revised copy it made, one of the two; operations, 1 to 200 objects each with its op |
checks the edits on a scratch copy, then makes a revised copy's next version in Studio and waits for it (below) |
surfsense_analyze_data |
title, what the analysis finds out; document_ids, ticked .xlsx, .csv or .tsv sources; script |
runs the script over copies of those sources' files in the Studio worker and waits for it: what it printed, each table it saved, each chart's name for surfsense_render_document's images and the charts as images (below). A source not ticked for the turn, an old .xls workbook or any other kind of file is refused in a sentence saying what to do instead |
surfsense_pdf_pages |
operation, merge, extract, split, rotate or reorder; document_ids, ticked PDF sources; artifact_ids, PDF artifacts; pages, a range such as "1-3,7"; angle, 90, 180 or 270 for rotate; title |
one new PDF artifact, or one per range for split, at most 20 (below) |
surfsense_pdf_stamp |
kind, watermark, page_numbers, header or footer; document_id or artifact_id; text, with {page} and {total} for page numbers; position, one of six corners and centres; pages; title |
a new PDF artifact with the text drawn upright on each page named, as the page is shown |
surfsense_pdf_form |
action, list or fill; document_id or artifact_id; fields, an object of field name to value; flatten; title |
list: each field's full name, kind, pages, value now and options. fill: a new PDF artifact with the fields set, or, flattened, with the values drawn into the pages and no fields left |
The schemas are flat, in a fixed order, and the same on every turn, and a test pins them. An optional integer *_id sent as 0 is dropped before the tool runs, since ids count from 1 (offered_tools.py): OpenAI's models fill every field a tool lists, so a render with no template asked for source 0, was refused, and was sent again until the turn ran out. In the OpenRouter screening no OpenAI model rendered a document before this, and the models it had failed were screened again (model capabilities). A required id of 0 still reaches its tool, which says it is wrong. A call the tool cannot carry out comes back as a tool error the model reads: no query, no sources named, Studio's own reason such as "Needs a chat model", or a search before onboarding has chosen an embedder or while its files are missing, which points the model at grep. A source's own text loses any passage tag, so it cannot make up a label. A tool runs in one transaction off the event loop, except a tool that waits on another process or does slow file work (waits on tool.py), which commits its own short transactions so the write lock never stays held meanwhile: surfsense_render_document, surfsense_revise_document, surfsense_list_images, which reads each source's index once and copies the figures after its commit, surfsense_source_pages, which may wait on LibreOffice or Electron, surfsense_convert_document, which waits for its Studio job, surfsense_analyze_data, which waits on the Studio worker, and the three PDF tools, which read and write files. A tool returning images only (needs_image_input) is listed and run only for a model that reads images; a tool added later comes after it, so each model's list keeps its order from turn to turn. A result is one text item, then, for surfsense_render_document, surfsense_revise_document, surfsense_convert_document and surfsense_source_pages, one MCP image item per page, for surfsense_analyze_data one per chart, and for the PDF tools one per page shown ({type: "image", data, mimeType: "image/jpeg"}, a ToolResult in tool.py); an error is text only, since opencode drops an error's images.
Before each turn the API adds the tools to the thread's folder with opencode's POST /mcp?directory=…: the server surfsense, the thread's URL, the launch key as a header, OAuth off, and a call timeout of 200 seconds, where a call would otherwise get the MCP SDK's 60 (registration.py). opencode keeps it in memory for that folder's instance alone and drops it when it reloads, so it is added on every turn, nothing is written to opencode.json, which every folder shares, and two threads' turns at once each keep their own. opencode then lists the tools and names them surfsense_<tool>. When it cannot reach them, the turn runs with its own tools and the API logs why. The chat panel shows their steps as "Searched the sources for …", "Started … in Studio", "Created Title v1", "Revised Title v2", "Read the script behind a document", "Looked for images in 2 sources" and "Ran the analysis Title", or "Analysed data" while its title is still being written. A PDF tool's step says what it did, by its operation, kind or action: "Merged PDFs", "Split a PDF", "Numbered a PDF’s pages", "Filled in a PDF form" and so on, or "Worked on PDF pages" while its input is still being written.
Documents the agent makes
render_document.py gives each call one deadline when it starts, 190 seconds, 10 inside the registration's timeout, so opencode never reports a bare timeout for a version that was made:
- Create. Studio's script-documents service makes the version in one short transaction: v1 of a new document, or the next version of the one
artifact_idnames, and queues Studio's job to run it (studio); the version records the thread that rendered it. A refusal, such as an image name the workspace does not hold, comes back as a tool error. A call withoutartifact_idwhose title matches, ignoring case and spaces, a document of the same format the thread already rendered and that is not failed or cancelled, is refused in one sentence naming that document's artifact id: passartifact_id <id>to change it, or give a new document a different title. Weaker models leftartifact_idout of edits, so a change became a second document (Gemma 4 31B in 5 of 18 ladder runs, Ministral 14B in 2, Qwen3.6 35B-A3B in 1, results); the same title in another format, "now a PDF version", is a new document (same_title_documents.py). The refusal runs nothing, so it is not one of a turn's failed runs. - Wait. Up to 150 seconds, within the deadline, it looks at the version's status every half second, each look its own committed read; a look that finds the database locked rolls back and tries again on the next (
job_outcome.py). - Ready. The result starts with
Rendered artifact <id>, version <n>: <title>(rendered_label.py), then the page count of a PDF, the slide count of a deck, the worksheet count of a workbook (a chartsheet counts as a chart, as in its summary) or the paragraph count of a Word file, the first 1,500 characters of its text, and up to four page or slide previews as images after the text, in page order, or why there are none. The text names the pages shown ("come with this result as images, in order: page 1, page 2"), tells the agent to look at every one, and names the folder of the larger copies once rather than each path, so the agent is not invited to open every page again withread. A page that cannot be encoded is left out and named with its path; when none can be, the result says there are no previews. The text names what drew the pages: LibreOffice by its version, with headers and footers included and fonts that can still differ a little; or, without Office support, SurfSense's Word viewer, which leaves out headers and footers, or the slide viewer, which can differ from PowerPoint. A workbook has no previews: its result carries its whole summary instead (each sheet's used range and first rows, and its formulas, studio) and asks the model to check it. A line from the version'srecalculationrecord says whether the values are real: "LibreOffice 26.8.0.3 recalculated the workbook: the summary and Studio show the values of 3 formulas, saved in the file, and Excel recalculates again on open", with a count of formulas left blank when LibreOffice gave one no value; or "Values not recalculated: Office support is off." (or LibreOffice's reason, such as being busy), telling the model the values shown are what the script saved and to check each formula itself. Reading the ready version is tried again while the database stays locked past SQLite's busy wait; at the deadline the result says the version is ready without its text. - Failed. A tool error with the run's error and the traceback's last lines, and the stop rule. A failure of the script itself, whose stored reason starts
Script error:, asks for a fix rendered from theartifact_id; any other, such as a full disk or the embedder, asks for the same script to be rendered again and the user told if it fails the same way. The stop rule reads: "If this is your third failed run for this request, stop and tell the user what failed." Studio does not retry a failed script document, so the version stays failed and the fix is the next version. Small models ignored the rule (Qwen3.5 9B rendered 21 times in one turn, Gemma 8), so the tool holds it (failed_renders.py): after a turn's third failed render or revision, which share one limit as both make Studio versions, each further one in that turn is refused without running, naming what failed: "3 renders failed in this request, so no more renders or revisions run until the user's next message. Stop now: tell the user what failed and what you tried.", or "1 revision and 2 renders failed in this request, …" Calls opencode makes at once count too: no more run at once than failures are left in the turn, and a further call waits for one of them to end. A success between failures does not reset the count; the user's next message does, and a render still running from the turn before counts toward that turn, not the new one. - Not done in time. A version still being made, behind other Studio work, comes back as a plain result starting
Queued artifact <id>, version <n>: <title>, saying it appears in Studio when ready and must not be rendered again. A cancelled or deleted version is a tool error without the stop rule.
The script, not the file, is what a version keeps, so the next edit reads it with surfsense_read_document, changes it and renders it again. Another format, such as a PDF of a Word document, is a new document at v1.
Converting to PDF
convert_document.py refuses while office_engine() is None, then creates a pending PDF artifact whose metadata names what to convert, conversion: {artifact_id, document_id}, as v1 of its own document, and queues Studio's job (studio). It waits up to 150 seconds within a 190-second deadline, as a render does, and reads the ready version back the same way (ready_version.py). Its result starts with the same Rendered artifact <id>, version 1: <title> line, so the thread links the PDF, then "A PDF of 3 pages, converted by LibreOffice 26.8.0.3 from artifact 40, which is unchanged", the text's start and the PDF's page previews (version_pages.py), telling the agent to fix the Word version or deck and convert again if the layout is wrong. A job that fails comes back as "Converting to PDF failed: " and LibreOffice's sentence; converting again makes another PDF.
Revised copies the agent makes
revise_document.py edits a copy of the user's file; the file itself is never written (studio). The call takes the same 190-second deadline as a render:
- Check. One id is needed:
document_idfor a source, held to the turn's ticked sources, orartifact_idfor a revised copy, which needs no scope, as the agent's outputs do not. A source that is not a file on disk, or not a.docx,.xlsx,.xlsmor.pptx, is refused with "SurfSense revises .docx, .xlsx, .xlsm and .pptx files."; so is an artifact that is not a revised copy, and a copy with a version still being made. A seconddocument_idcall on a source this thread already revised is refused naming that copy'sartifact_id, as a render's same title is. The schema is flat: which fields eachopneeds is the engine's to check. - Dry run. The engine runs on a scratch copy of the input, outside any transaction. An operation it refuses saves nothing and makes no version: the tool error is "Nothing was saved.", every operation's line (
#1 replace_text refused (QUOTE_NOT_FOUND): …, the othersskipped (BATCH_REFUSED)), and "Fix the refused operation and send all N again." Refusals are not failed runs, so they do not count toward the three-failures stop. - Create and wait. The version is made in one short transaction from the copy's SHA-256, which the job checks again, and waited for as a render is.
- Ready. The result starts
Rendered artifact <id>, version <n>: <stem> (revised), so the step links the copy as a render's does, then "Revised copy of source 42 (MSA_Acme.docx), version 2 from version 1. 4 of 4 operations applied; 7 tracked changes, 2 comments.", each operation's line and any note the user must hear (FORMULAS_NOT_RECALCULATED), the opening text or a workbook's summary, and up to four page or slide previews, Word's showing tracked changes, drawn by LibreOffice with Office support on and then named as its (revised_result.py). A failed version is a failed run, with the stop rule, and counts toward the limit renders share; the refusal names it a revision.
Analyses
analyze_data.py answers a question about a table with arithmetic the model would otherwise do in its head. It checks each source against the turn's ticks, takes its original file (source_files.py), commits, and queues the run on the Studio worker, where the runner gives the script read-only copies and keeps what it saves (studio). The source's own file is only ever copied. The call waits up to 190 seconds, as a render does:
- Done. The result starts
Analysis run <run>: <title>, then what the script printed, its first 6,000 characters and 200 lines with a note to print less when cut; each of up to five saved.csvor.tsvtables, while they fit in 24,000 bytes, as<file>, R rows and C columns:and its first 20 rows and 8 columns in Markdown, read with thecsvmodule since the API ships no pandas (table_preview.py); each.pngchart's name,analysis-<run>-<stem>, with its path; the first six charts as images when the model reads images, else a line saying it cannot; the other files kept and the first 20 not kept, with a count of the rest; andoutputs/analysis/<run>/. These caps hold the result under opencode's cut of 50 KB and 2,000 lines, counted in bytes, so a table of Chinese text does not spill into opencode's shared tool-output folder. - Failed. A tool error with the error line, cut at 2,000 characters, the traceback's last lines that fit in 6,000, what it printed first, "Fix the script and run it again." and the stop rule. Analyses keep their own count of a turn's failed runs (
failed_renders.py): after three, a further analysis is refused with "3 analysis runs failed in this request, so no more analysis runs run until the user's next message.", while renders and revisions keep theirs. - Not done in time. The worker busy or not running past the deadline is a tool error that asks the agent to tell the user and not run it again; it is not a failed run.
A chart's name goes in surfsense_render_document's images like a figure's, and its PNG is copied to IMAGES_DIR/<name>.png (chart_names.py). It is looked up in the rendering thread's own outputs/analysis/, so a chart from another thread is refused: "This chat has no analysis chart named …". A chart counts as no source of the document.
PDFs the agent works on
The PDF tools (pdf_pages.py, pdf_stamp.py, pdf_form.py) run no script and ask no model: modules/pdf_tools/ reads the PDFs with pypdf and writes new bytes, in the API process. A call reads its inputs in one short transaction (pdf_inputs.py): a source must be ticked for the turn and be an uploaded .pdf; an artifact must be a PDF of the workspace with its file on disk, from any thread, as surfsense_read_document reads any. Neither file is ever written. Each new PDF is kept at once as a new artifact (made_file.py): its file stored, the artifact pending, its metadata naming what made it (made_by: the tool and its operation, pages, angle, stamp or the names of the fields filled, never their values) and what it came from (derived_from: the sources' and the artifacts' ids), and Studio's job queued to index its text (studio). It keeps no spec, so it is a document of its own at no version, never a version of its input, and surfsense_render_document refuses to continue it. The result's first line is Made artifact <id>: <title> for one PDF; a split lists each part. The pages shown are the first four of a merge, an extract or a reorder, the pages turned or stamped, the pages holding the fields filled, or the first page of each of the first four parts, drawn at most 1,000 pixels on their long side into outputs/previews/<artifact id>/ and sent as the render's previews are, when the model reads images; otherwise the result says there are none.
Each refusal is a sentence: a file past 200 MB or 1,000 pages, PDFs past 200 MB together, refused before any is read, one damaged or not a PDF, one that asks for a password (one that opens with an empty password, locked only against changes, is read), a page past the end with the count, a range that does not parse with the syntax and the start of what was written, ranges naming more than 20,000 pages in all, counted before any list of pages is made, a reorder that drops or repeats a page saying which, a merge past 1,000 pages, a split into more than 20 parts, an unknown field with the form's field names, a value a choice or radio group does not offer with its first 50 options, text with no width to draw, a read-only, signature or button field, and an XFA-only form. A hybrid form's XFA is dropped from the copy, so Acrobat shows the values set. Stamps draw in Helvetica, which needs no file, when the text fits Windows-1252, else in the first of a list of system fonts (Arial, Nirmala UI, Malgun Gothic, Microsoft YaHei, Yu Gothic, MS Gothic, SimSun on Windows; Arial Unicode or Arial on macOS; DejaVu, Noto, Droid and WenQuanYi on Linux) that has every character, embedded as a subset; with none, the call is refused (stamp_font.py). Flattening draws each visible field's appearance into its page and removes the fields (form_flatten.py); pypdf's own flatten loses the second button of a radio group. A stamp and a flattened field are both drawn as form XObjects after the page's own content streams, which are kept as stored and never decoded (drawn_over.py): a PDF of a few KB can hold one stream that decodes to many MB on every page. Each page drawn on gets resources of its own, since pages often share one dictionary. A form's listing names at most 20 options a field and the start of a long value, and stops at 30,000 bytes.
Previews
previews_for() (previews/) draws up to four pages or slides of a ready version as PNGs 1,000 pixels wide, at most 4,000 high, into the calling thread's outputs/previews/<artifact id>-v<n>/, with pypdfium2 under the process's one lock (shared/pdfium.py). It runs only when opencode.json declares image input for the model. A page that would come out under 100 pixels on a side is skipped and named in the reason. It is called after the version's files are read and the transaction committed, with the time the call has left. Each page drawn goes into the result as a JPEG made from its PNG (inline_images.py): flattened on white, scaled down to at most 750,000 pixels (an image past 40 million pixels, which a script can save in a few KB, is refused unread) and 1,568 on the long side, at quality 80. Anthropic bills an image by its pixels, so an A4 page costs about 1,000 tokens rather than the PNG's 1,890, and at about 80 to 100 KB it is half the PNG's bytes. The encoding is deterministic, which the live harness relies on. The PNGs stay on disk for a closer look with read.
- PDF: the file's own pages.
- Word and PowerPoint with Office support on: LibreOffice converts a copy of the whole file to PDF, within 60 seconds or what the call has left, and pypdfium2 draws its first four pages; the result names LibreOffice and its version (office pack). When LibreOffice is busy, times out or fails, the version falls back to Electron below and the result gives LibreOffice's reason first.
- Word and PowerPoint without it: Electron prints the file. The API queues a request and waits up to 30 seconds, or what the call has left, and skips the preview below 3 seconds. Electron polls the routes below every 2 seconds, opens the frontend's snapshot page (
docx-snapshot.html) in a hidden window with the file's URL and format, lays it out with the in-app viewer's library for that format, docx-preview for Word or pptx-renderer for a deck, and prints pages 1 to 4 withprintToPDF; pypdfium2 then draws that PDF. The pages show the file as the app's viewer lays it out, not as Microsoft Office does; a Word document's leave out headers and footers, which docx-preview places in a page box that print pagination replaces. - No Electron, as in the Docker stack and the tests: the snapshot service counts Electron gone after 60 seconds without a poll, and a Word or PowerPoint version gets no pages and the reason.
- Excel: none; the result carries the workbook's summary.
Source pages
surfsense_source_pages (tool_endpoint/source_pages.py, previews/source_pages.py) draws a source's own pages so the agent can match a look it cannot take as a template, such as a PDF brand guide. It only reads the source's original file. A PDF's pages are drawn from the file with pypdfium2, and its page count is exact. With Office support on, LibreOffice converts a copy of the whole Word file or deck to PDF and the pages asked for are drawn from it, so a Word file's page count is exact and the result names LibreOffice; a deck whose PDF has fewer slides than its package (LibreOffice leaves hidden slides out) and any LibreOffice failure fall back to Electron, the failure's reason said first. Otherwise: a deck's slides are counted from its package and a slide it lacks is refused before printing; Electron prints the slides asked for, as it prints the agent's own decks. A Word file is printed the same way; its count is exact when the print comes up short of the pages asked for, else "at least" the last page drawn, said to be not known in all, or "an unknown number" when nothing was printed. The page count Word saves in the file is not used: python-docx and other writers leave a template's there ("1 page"), which once contradicted the page 4 drawn beside it. A print that comes back with another number of pages than asked for draws none, rather than label a page as another. Each page drawn comes back with the result as a JPEG made as a render's previews are, and its PNG, at most 1,000 pixels on its long side, stays under sources/pages/.
The snapshot routes, mounted only beside an opencode (previews/router.py):
| Method | Path | Does |
|---|---|---|
GET |
/agent/previews/docx-snapshots/next |
takes the oldest waiting request as {id, file_url, format, pages}: file_url is the artifact's files/primary URL, or for a source the request's own file route; format is docx or pptx; pages is printToPDF's page ranges, 1-4 for a version's previews; 204 when none |
GET |
/agent/previews/docx-snapshots/{request_id}/file |
the source's original file a taken request prints, until it is answered; 404 otherwise |
POST |
/agent/previews/docx-snapshots/{request_id}/pdf |
the printed PDF; 413 over 50 MB, 422 for a body that is not a PDF, 404 when no one waits for it |
POST |
/agent/previews/docx-snapshots/{request_id}/failure |
why it could not be printed, at most 500 characters |
Each but file refuses a caller with an Origin header, and one without Authorization: Bearer <key>, the key Electron made at boot and passed to the API as SURFSENSE_LOCAL_DOCX_SNAPSHOT_KEY (snapshot_key.py), because any process on the machine can reach loopback. The file route is fetched by the print window itself, which sends an Origin and holds no key, as it fetches an artifact's file: the request id, a random 128-bit value only the key's holder is handed, lets it in, and only while that request is being printed.
Electron's side (docx-snapshot/) takes the next request at once after taking one, prints up to three at a time, gives each print 25 seconds, under the API's 30, and each call to the API 10. A request names its format, docx or pptx, and its pages as printToPDF page ranges; one without them is a Word file's pages 1 to 4, and a format or range it cannot print is reported as the request's failure without printing. A PDF the API refuses is reported as the request's failure. The page lays a Word file out as above, and a deck with @aiden0z/pptx-renderer, the in-app viewer's library: every slide on a page of the deck's own slide size, read from the file, printed with no margin, once each slide's pictures, backgrounds and charts are drawn (features/docx-snapshot/). The document is untrusted, since a source can steer the script that wrote it, so the hidden window runs sandboxed with no preload, in its own in-memory session whose requests may reach only the page's own files and object URLs and the one file being printed, and it never navigates. The page's policy allows only its own script, inline styles, data-URL and object-URL images, data-URL fonts, and connections to loopback; docx-preview renders no altChunk, whose HTML it would put in an unsandboxed frame, and the deck renderer gets no pdf.js, which would start a worker. A page whose script did not start is reported as such, with the window's first console error.
A turn
The thread routes in chat hand an agent thread to agent_threads/:
- The turn's sources are stored and resolved (the ticked sources) and opencode is made ready. A legacy thread is then refused (folders), and so is a model that cannot run the agent. The stream then opens with
agent-preparing,{count}, the number of sources the folder will hold, since a big scope's first sync takes about 30 seconds; the screen shows "Preparing 1,200 sources…" until the next frame. The thread's folder is brought in line inside the stream, and a sync that fails ends it with an error frame. The tools are then added to the thread's opencode instance at the thread's address. - The thread folder's event stream is opened before the message is sent, so no event of the turn is missed. The message goes with
prompt_async, naming the selected model, so a thread keeps working after a model change, and with the scope note beside it unless the thread's scope is every source. - Events for the thread's session become the chat's frames, plus
agent-step,permission-requestandpermission-replied(turn_frames.py). Each answer part after the first opens a new paragraph; a part's leading line breaks and a part of breaks only never stream, and its trailing breaks are held until text follows, so parts join with one blank line, as the stored reply's stripped parts do (replies.py). Breaks inside a part, a code block's among them, stream as written. A completedsurfsense_render_documentorsurfsense_revise_documentstep carriesartifact: {id, title, version, created}, read from its result's first line, which only a ready version gets; it is null while the call runs and when the script failed (steps.py). A version not ready in time has none in the turn's frames; reading the thread back fills it from the result'sQueued artifactline once that version is ready (ready_renders.py).createdis true when no earlier version of the same root has made its file, so a document whose v1 failed is "Created" at v2; it is looked up in the database for the stream and on read-back, and a step sent while the database is locked goes without it and gets it on read-back. The screen then reads "Created Title v1" or "Updated Title to v2", whatever the format, or "Revised Title v2" for a revised copy ("Edited a copy of a source file" until it has a version), and a click opens that version in Studio. A step carries no attachment: the page images opencode keeps on a render's or a source-pages step never reach the thread, live or read back. A completedsurfsense_convert_documentstep carries the sameartifactfrom its first line, withoutcreated, and reads "Converted Title to PDF", opening the PDF on a click; while it runs, or when it was refused, "Converted a document to PDF". Asurfsense_source_pagesstep reads "Looked at pages of Title", the title taken from the turn's scope, else, for a turn on every source or past 200, from the first line of the step's result, or "Looked at pages of a source" while the step runs. Text parts of one turn on either side of a tool call are kept as separate paragraphs, live and stored. - A stream silent for 20 seconds, twice opencode's heartbeat, is reopened, and so is one that drops; after a reopen, an idle session ends the turn. Twenty failures in a row end it with an error. Any other error once the stream is open, such as the database failing during the sync, ends it with an error frame of kind
unknownand[DONE]. - On
session.idle,completedcarries the reply as opencode stored it: the text of every assistant message opencode wrote for this turn, joined. A label one of the session's searches returned becomes[citation:<chunk id>]through the chat's ownresolve_citations(), and any other bracketed number is dropped (citations.py). Acitationsframe comes first when the reply cites anything. - The turn runs as a run in the background (chat): a client that hangs up stops following it, not the turn. Stop and quit abort the session's turn, and Stop first notes itself in the session's metadata, since opencode stores both as the same abort (chat). While a
permission-requestwaits, the run's state isneeds-approval.
Compaction. When the window fills, opencode compacts the session mid-turn: a user message holding a compaction part, a summary it writes for itself, then a user message that carries the turn on. compaction.py tells them apart, so they fold into the turn they happened in: the summary is never streamed as the reply nor joined into the stored one, and the carrying-on message opens no new turn when the thread is read back. opencode's ContextOverflowError is not shown, since opencode compacts and carries on from it. A summary that fails ends the turn with one error frame, and one that failed because even the summary was too long says "The conversation is too long to continue here; start a new thread."
The ticked sources
The chat panel sends the sources ticked in the sources panel with every message, and they bound an agent turn as they bound a chat's retrieval, resolved the same way in one transaction (turn_sources.py): a sent source_scope is stored on the thread; with none, document_ids is checked as a chat checks it (load_selected_sources, 422 for a source not in the workspace, 409 for one not ready) and stored as {document_ids}; with neither, the thread's stored scope holds, and a thread that never stored one uses every source. The scope resolves to its ready sources, with no cap, so a ticked folder of any size is the whole turn; every source means the workspace's files and notes and its filed artifacts, never an unfiled one (source scope). An empty result is no sources.
- The folder holds it. The thread's
sources/is brought in line with the resolved sources before the turn, soread,grepandglobreach no other source (folders). A Studio artifact filed in a ticked folder is mirrored like any source. - The model is told. Unless the stored scope is every source, the message goes to opencode with a second text part marked
synthetic, which opencode 1.18.34 accepts onprompt_async, keeps as not the user's, and passes to the model inside the user's message (scope_note.py). Its first line is SurfSense's tag,[surfsense-scope: 3,7], past 200 sources[surfsense-scope: count=N], or[surfsense-scope: none]; the rest says the user chose N sources for this chat, to use only those, and that passages read earlier from other sources no longer apply, or that no sources are selected, or, when every ticked source is still being read, that none is ready yet. Up to 20 sources, it names each one's file by its path undersources/, as the thread's sync lays it out, in double quotes, which a mirrored name never holds though it can hold a backtick, and says to open it withreador search it withsurfsense_search_sources: Qwen3 1.7B, told only that the source was "the file insources/", guessedsources/17.mdand gave up. Told the path, asked about Boston's CM11 contract, Qwen3 1.7B (UD-Q4_K_XL, on llama.cpp) read the file and answered from its clause 5.2, and Qwen3 4B (Q2_K) and Qwen3 8B searched it and answered. Past 20, or when one ticked source has no text to mirror, it says they are the files insources/and names none. Every note ends by saying SurfSense added it and it is never to be repeated, as a small model began its answer with the tag. It lives in the session, so a compaction keeps it, and each turn carries the ticks of the moment it was sent. - The tools hold to it. Each thread registers the tools at its own address, and a tool call resolves the thread's stored scope in one short transaction (
turn_scope.py), so ticks stored between turns hold the next call.surfsense_search_sourcessearches only those sources, and with none says so instead;surfsense_list_images,surfsense_source_pages,surfsense_create_artifactand the PDF tools refuse a source outside them, naming at most 20 of the sources that are in it and then "and N more: the files insources/";surfsense_render_documentrefuses an image or a template from one, including the template a next version would keep from its base, and places an analysis chart only from its own thread;surfsense_revise_documentandsurfsense_analyze_datarefuse a source outside them. An address naming no agent thread of the workspace is refused rather than widened. Artifacts the agent rendered are its outputs, sosurfsense_read_documentneeds no scope, nor does a render that continues one, beyond its template. - The thread shows it. Reading the thread back takes the note out of the user's text and returns
content.scope:{document_ids, titles}, keeping the sources that still exist, or for a counted tag{document_ids: [], titles: [], count}. Under the user's message the screen shows "Working from Plan.pdf", up to three names inline, else "Working from 5 sources" with the names on hover, "Working from 5,000 sources" with nothing on hover for a counted tag, or "Working from no sources": live from theagent-scopeframe that followsagent-preparing, which carries the same shape, and on read-back from the stored scope (working-from.tsx). A turn on every source, and every chat thread, shows none.
Approvals
The agent has no shell, so it asks for no command. opencode still asks for a permission left at its default, such as doom_loop when the same tool call with the same input comes a third time in a row. The request reaches the thread as permission-request. The screen shows the oldest waiting one in an alert dialog, with Deny and Allow once, and Esc answering Deny. The answer goes to POST /chat/threads/{thread_id}/permissions/{request_id}, which passes once or reject to opencode. SurfSense never answers always. opencode rejects every other request waiting in the same session when one is rejected, and the dialog says so when others wait.
Network
opencode needs no host beyond loopback: its model is the model endpoint, and its tools are its own and SurfSense's, on the API's port. Its environment is built from a few system variables rather than inherited. It sets OPENCODE_DISABLE_MODELS_FETCH, OPENCODE_DISABLE_SHARE, OPENCODE_DISABLE_LSP_DOWNLOAD, OPENCODE_DISABLE_AUTOUPDATE, OPENCODE_DISABLE_DEFAULT_PLUGINS, OPENCODE_PURE, OPENCODE_DISABLE_PROJECT_CONFIG, OPENCODE_DISABLE_EXTERNAL_SKILLS and OPENCODE_DISABLE_CLAUDE_CODE. Its proxy variables point at 127.0.0.1:9, where nothing listens, with loopback exempted, so a fetch this misses fails rather than leaving the machine. The npm install opencode would otherwise run at startup is skipped: its config folder holds an empty node_modules and a lockfile naming the package. ripgrep is the shipped one, first on its PATH. Settings › Network gains nothing: opencode is never a destination, and a remote model's host is checked as its connection's.
A document script is another matter: it runs in the Studio worker's runner, which gives it an environment of a few system variables and no secrets but does not stop it opening connections (ADR 0039, studio).
Tests
- Backend:
tests/integration/agent/andtests/unit/agent/. The client, readiness and thread tests start the staged opencode against a scripted model, and the thread tests also run the real API on a port. The tool endpoint tests drive the app in-process, as opencode's MCP client calls it. They skip wherepnpm build:opencodehas not staged a build. Each builds the app as Electron starts it beside an opencode;test_routes_without_opencode.pybuilds it without one.test_document_flow.pyplays a whole document flow through the tool endpoint with no model: a logo's figure, Word v1 with the logo and a chart, its script read back, v2, and a PDF whose previews come back as images.test_office_documents.pyrenders decks, workbooks and documents made from a source's template through the real runner, with Electron played on the snapshot queue for a deck's slides,test_source_pages.pydraws sources' pages with Electron played on the snapshot queue and LibreOffice by a stand-in (tests/office_stand_in.py; every test starts with Office support off),test_convert_document.pyconverts versions and sources through the stand-in with Studio's worker on a thread,integration/office_support/test_libreoffice.py(markeroffice) converts a Word file and recalculates a workbook on the LibreOffice installed on the machine, named explicitly, or skips,test_documents_skill.pyandtest_data_skill.pyrun the skills' examples through the real runner,test_analyze_data.pyruns analyses on the Studio worker played on a thread and places a chart in a Word file, andtest_compacted_turns.pyreads compacted sessions back.test_tool_scope.pyholds each tool to a turn's ticked sources in-process,test_thread_folders.pylays out, links and sweeps thread folders,test_thread_isolation.pyruns two threads in the real opencode and checks neither reads,greps norglobs the other's sources,unit/agent/test_mirror_path.pychecks the mirror's names and length cuts, andtest_agent_scope.pysends ticked, empty and omitted selections, a ticked folder past 1,000 sources and a thread's stored scope through the real opencode.test_pdf_tools.pycalls the PDF tools in-process over uploaded PDFs and artifacts,test_pdf_skill.pychecks the PDF skill against the tools and the range parser,tests/unit/pdf_tools/covers each operation, stamp and form on PDFs built with ReportLab, andtests/integration/artifacts/test_made_files.pytakes a made file through Studio's job. - Live:
tests/live/drives the real path against Claude Sonnet on a spend budget, skipped unless asked for (07-dev-setup).tests/live/sweep/runs its smoke, PDF brief and board pack cases over OpenRouter's tool-calling models for the capability list. - Electron: the sidecar tests in
electron/src/main/sidecars/, the snapshot poller, session, print-option and page-answer tests inelectron/src/main/docx-snapshot/, and the pins, switch and stage-check tests inelectron/scripts/opencode/. - Frontend:
features/agent/agent-thread.test.tsx, on the real dashboard against a stream that waits for the test's answer, a legacy thread's history and refusal inoutdated-agent-thread.test.tsx, the Working-from line's cases, the counted one included, inworking-from.test.tsx, the step labels inagent-steps.test.tsx, and the snapshot page's Word and deck layout, altChunk and policy tests infeatures/docx-snapshot/.
Known gaps
- The measured levels that set a new chat's default are screening runs on remote hosts, so every model served from this computer starts Basic (Q&A) until the user picks Agentic (model capabilities).
- The model endpoint neither simplifies tool schemas to what llama.cpp's grammar takes nor turns a tool call a model writes as text into a real one, so small local models stall where a remote one would not.
- A file the agent writes to
outputs/with its own tools does not become an artifact; onlysurfsense_render_document,surfsense_revise_document,surfsense_convert_documentand the PDF tools make one. An analysis's tables and charts stay inoutputs/analysis/too, outside Studio, until a document places them. - An analysis waits on the Studio worker's four threads. Behind four long Studio jobs it is dropped after 60 seconds unstarted, and the call waits out its 190 seconds before saying so.
- A Studio job the agent starts with
surfsense_create_artifactruns on the same local model as the agent, so the agent's next step waits behind it. - An artifact the agent starts with
surfsense_create_artifactrecords neither the thread nor the step that made it, and one it renders records its thread but not the step: the tool call reaches SurfSense without the step. - A thread's folder narrows what its agent can reach to its own sources, but does not close it. Through two holes in opencode, each below, an agent can still read what is outside its folder: a git repository above the data folder opens every thread's folder, and opencode's tool-output folder is shared by all; closing either needs a change in opencode. Through SurfSense's own tools it can too: a script
surfsense_render_documentorsurfsense_analyze_dataruns can read any file the user can (Studio), and the text the render returns shows what it put in the document, another thread's sources included; andsurfsense_read_documentreads any document the agent rendered in the workspace, from any thread and filed in an unticked folder too, and such a script can hold what that thread's agent took from its own sources. - After the ticks change mid-turn through
PUT /source-scope, the tools follow the new ones at once but the folder only at the next turn; the app sends ticks with each message, never mid-turn. - A folder renamed or moved renames its sources' files between turns; the agent finds them again with
glob. - Up to six thread instances stay in opencode, about 30 MB of its memory each after a turn with SurfSense's tools, measured on 1.18.34 (
test_thread_isolation.py); deleting a thread did not give its share back to the system right away. Instances opencode holds from before the API last started are not known to the cap. - A passage's label is its chunk id, a number of several digits, which a small local model copies less reliably than a chat answer's
[1]to[5]. A mistyped label is dropped, so the citation is lost rather than wrong. Nothing has measured how many are lost. - A bracketed number the agent writes that no search returned is dropped from the stored reply but not from the streamed one, so the two differ. In a live run Claude cited files it had read without searching by the
[n]at the end of their names, as labels, and the saved reply lost them. - Bringing a thread's
sources/in line reads the text of every source in its scope before each turn, to hash it: at 3,000 sources of 40 KB, 0.8 s a turn once synced, 2.8 s for a second thread linking them, and 13 s the first time, writing the cache (test_thread_folders.py, Windows with Defender on). The firstgrepover a newly written cache pays Defender's scan of each file once per machine. - On a disk without hard links each thread holds its own copy of each text, and pays Defender's scan again.
- A configuration rewrite, which a change of model, window or image input causes, ends every running agent turn in every workspace.
- Opening the first agent thread waits for opencode to start and for a local model to load, up to a minute, with nothing on screen but the thread being created.
- When SurfSense's data folder sits inside a git repository, such as a home folder kept in git, opencode counts the repository's root as its project, not the thread's folder. Then every thread's agent can read,
grepandglobevery other thread's folder, including sources not ticked for it, and every other workspace's, without asking. Nothing detects it (#2229). - No test runs opencode with every connection beyond loopback refused to check that it opens none.
- When opencode cannot stay up, each chat opened in Agentic waits the full 60 seconds before its
503, and Electron starts opencode again every 10 seconds while its configuration stands, each exit showing the generic "A background service stopped" toast again, which names neither the agent nor the cause. A failure to spawn it at all is not reported as a crash (overview) (#2228). - opencode's tool-output folder is shared by every thread in every workspace and open to each one's agent: a tool result over 50 KB or 2,000 lines is kept there for 7 days (SurfSense's own tools stay under that limit;
surfsense_read_documentpages long scripts), and another thread's agent, in the same workspace or another, can list and read it without asking. Per-thread folders do not change this. - On macOS and Linux, opencode checks an absolute path as written, so its own allow for its tool-output folder also matches a path that climbs out of it with
... The skills folder's allow has a..deny after it; the tool-output folder's cannot, since opencode adds that allow after SurfSense's rules. Windows normalises the path first. - Every page image the agent is shown, each render's previews and each page it opens, stays in its context until a compaction, and Anthropic's OpenAI-compatible API reports no prompt caching, so each request bills them again: about 1,000 tokens a page a request. Nothing drops the images of a version a newer one superseded. Anthropic caps the images in one request, so about 25 four-page renders in one uncompacted thread could reach it.
- opencode's compaction estimates base64 as text, so one inline page is over its 15,000-token budget for the recent turns it keeps: a turn holding a page image is always summarised, never kept as it was.
- A thread whose model changes to one that reads no images sends opencode's "Cannot read image" error in place of every stored image on every later request.
- opencode's stored messages carry every attachment, about 0.35 MB a four-page render, and the API reads them all at every turn's end and when a thread opens.
- claude-sonnet-5-5's window is the 1,000,000 tokens the catalog records, not confirmed against Anthropic's OpenAI-compatible endpoint. No live run has come near it; if the real window is smaller, a request fails on it before compaction starts.
- Without Office support, Word previews leave out headers and footers, and lay a document out as docx-preview does, which can differ from Word. The agent is told the first. Slide previews are pptx-renderer's, which can differ from PowerPoint; the agent is told so. LibreOffice's layout is closer, but not Word's own either.
- Without Office support, a Word source's page count is known only when a print comes up short; a page asked for past the end fails as Electron's print does.
- With Office support on, each preview or source-pages call converts the whole file again: nothing keeps LibreOffice's PDF of a version or a source, and a long document's conversion counts against the call's time.
- A converted PDF is a new document each time; converting a newer version does not make the next version of the earlier PDF.
- A PDF tool's step is not linked to the artifact it made, as a render's is: the user finds it in Studio.
- A stamp in Devanagari or another script that needs shaping draws its letters unjoined: reportlab places glyphs one by one.
- The PDF tools neither sign a signature field nor fill an XFA-only form, and cannot open a PDF that needs a password.
- A next version keeps its template; to drop it, the agent starts a new document.
- The Word preview path through a real Electron window has no automated test; it was checked by hand, and the live tests print Word with LibreOffice behind the same routes.
- A fourth Word snapshot requested while three print waits for a free print, and the API's 30 seconds start when the request is queued, so it can time out before Electron answers.