Built-in tools#

See tool permission modes and live changes for approval behavior and changes during a task.

OpenProgram ships a set of functions registered as tools that the model calls directly in chat. This page lists them one by one, following the openprogram/programs/tools/ directory: what each tool does and which keys or local dependencies it needs. Most tools require zero configuration; the ones that need keys cluster in web search and images.

Files and code#

Document versions#

For Word, PowerPoint, PDF, images, and other binary files, the model can generate a separate temporary result and publish it with write(file_path="/absolute/final.docx", source_path="/absolute/staged.docx"). source_path and text content are mutually exclusive. The source must be a regular local file of at most 64 MiB. Existing targets must first be read; binary reads return metadata and establish the same freshness check as text reads.

Publishing during a conversation records complete before/after bytes in that turn's file history. The record survives reopening the conversation and restarting the application. Undo and reapply use these saved versions and refuse to overwrite conflicting later changes. New files can also be undone. This does not require a Git repository in the project folder.

A failed later history commit preserves the previously published version. If a write is interrupted before its result is recorded, file history reports that the result is unconfirmed and blocks exact recovery; it does not assume the operation succeeded or that no file changed. Corrupt history blocks further recorded writes instead of replacing the history with an empty record. After a failed initial attempt, reread the current file before retrying. Versions are retained with the turn and follow its existing history retention policy. New local document generators use the same source_path publication interface; they do not need a separate version store.

Binary versions preserve formatting and embedded media, but the current Review pane does not compare document layout or show Word tracked changes. Ordinary shell commands that overwrite the final file directly are not recorded as exact turn mutations. Previously unrecorded versions cannot be reconstructed from a file card or command output; scripts should write a separate result and use write to publish it.

Project files open in Preview. For supported UTF-8 text files, choose Edit to change the file; changes save automatically, and Ctrl/Cmd+S can flush immediately. Switching Preview and Edit preserves the editor's undo history. History shows retained before/after versions and can restore a selected version. If a save fails or the disk file changes elsewhere, the draft remains available for retry, export, or explicit discard. Closing a file waits for its pending changes; a failed save keeps the tab open. Chat attachments use the same preview window in read-only mode.

Manual changes made through the project file editor also retain before/after bytes, independently of conversation history. Each successful write is published immediately. Consecutive changes from the same editor are grouped for at most five minutes; closing a group or detecting an intervening external change starts another version. Restoring a retained version creates a new history entry and checks the current file revision before overwriting it. Project-owned history remains readable while a project's disk is disconnected; writing and restoring require an available project location. It follows the registered project when its location changes. The document API accepts bounded binary content up to 64 MiB; this does not by itself provide an editor for every binary format.

PDF preview provides page navigation, zoom and text search; searches cover the first 500 pages and state that limit for longer documents. PSD preview shows the saved composite and layer names for 8-bit RGB files, and TIFF preview shows the first page. These decoders accept at most 64 MiB and bound the rendered image size. Common images open in preview by default; audio and video use browser playback controls, with codec support depending on the browser. Damaged or unsupported files retain an original-file download. Previewing a retained history version uses its retained bytes. Decoder assets are local and load only when the corresponding format is opened. These preview modes do not edit PDF, PSD, TIFF, audio or video files.

Office support is an optional local installation shared by presentations, documents and spreadsheets. The default App and runtime do not bundle it. Opening an Office file without the component displays Install and Cancel; no download starts until you choose Install. The download is about 699 MiB and includes ONLYOFFICE resources, fonts, licenses and source materials. Files are processed locally. Installation verifies the pinned archive and all resource files before selecting a complete version. A failed installation can be retried; existing installations remain available. On success, the current document opens automatically without restarting the App. Cancel leaves the original-file download available, and Installation options lets you choose again. The local Office host is unavailable through remote application access. PDF viewing does not require this component. The file window supports Preview and Edit for DOCX, PPTX, XLSX, ODT, ODP and ODS. Preview is the default. A centered status shows resource preparation and document opening. Closing during startup cancels the pending editor; a startup failure offers Retry. Edit waits for the native editor to become writable; changes then save automatically. Switching Preview, tabs, split layouts or History retains the current editor and its native undo history. Closing waits for pending input and publication; a failed write retains the document for retry. History previews are read-only and restoring a version creates a new retained version. Legacy DOC, PPT and XLS files can be explicitly converted to a new DOCX, PPTX or XLSX path; the original is preserved and an existing destination is rejected. Attachments remain read-only, and the original-file download remains available when the editor cannot load. These windows do not provide semantic Office redlines.

Static PNG, JPEG and WebP files support Edit with crop, rotation, drawing, shapes and text. Changes save automatically through the document history controller; switching Preview, History, tabs or routes preserves native undo/redo. Failed publication keeps the editable draft available for retry, and closing waits for export. Convert to PNG creates a separate file and rejects an existing destination. Animated PNG/WebP and 16-bit PNG remain read-only. Editing accepts at most 64 MiB, 16 million pixels and 16,384 pixels per side; unsupported or damaged input retains the original download. Image editing exports rendered pixels and does not promise preservation of embedded metadata. Attachments and historical previews remain read-only.

The same History view combines manual edits and confirmed model file changes for the project-relative file. Model entries read the retained before/after bytes from the original session checkpoint; they do not copy the session into a second archive. Restoring one version changes only this file and creates a new manual history entry after checking the current revision. Archived sessions retain their file history; permanently deleting a session makes its model versions unavailable. Manual history remains independent. Older session history is indexed in bounded batches: Continue loading history advances the next batch, and incomplete or unverifiable history is labeled explicitly. Legacy paths are included only when their project ownership can be established. Moving a project does not change the identity of newly recorded file history; offline versions remain readable, while restoration requires an available project location.

Execution#

execute_code returns stdout, stderr and the observed exit code. A nonzero exit or timeout is an error result; partial output remains available to diagnose the failure. Success requires a zero exit code. Each call uses a fresh Python subprocess.

One-shot command directories#

bash starts a new shell for every call. Use the optional workdir argument to select the starting directory for that call, for example bash(command="npm test", workdir="apps/web"). This is tool-call notation; the ordinary Python export is an AgentTool, not a direct shell function.

Local relative paths resolve from the currently bound worktree, or the host process directory when no worktree is bound. Absolute paths are also accepted. Paths are literal: ~, environment variables and shell expressions are not expanded. Omit workdir to retain the existing worktree/backend default. A directory change or export inside one command does not affect another call. workdir does not change the worktree binding or the base used by file tools.

Missing, non-directory or denied workdirs fail without running the requested command; the tool does not create them or fall back to a different location. Selecting a directory does not grant access to it. Under a local sandbox policy, explicit workdirs must already satisfy the original workspace's read/write policy, including symlinks and extra authorized roots. Execution remains inside that original sandbox boundary. An unavailable configured sandbox is not bypassed for an explicit workdir.

SSH and Docker interpret explicit workdirs as POSIX paths in the backend filesystem, not paths on the host. Relative remote paths require an absolute POSIX worktree binding. A guarded directory change prevents the command list from running if that directory is unavailable; Docker does not create the requested directory via -w. When a host sandbox policy is active, explicit remote workdirs are refused until backend-native path authorization is available. Omitting workdir preserves the existing backend behavior.

Results include the selected local starting cwd, or requested_cwd for remote paths whose canonical location is not independently observed. This is not an ending-directory report or a promise of persistent shell state. Long-running processes remain the separate process tool's responsibility; bash does not control the Desktop integrated terminal.

Web#

web_search backends and keys (arXiv and DuckDuckGo need no key and are always available):

The chat Web Search switch controls whether web_search is available for that message. Turning it off excludes the tool even in automatic tool mode. When enabled, the search schema is available immediately, including when Tools is off. Turning it on still respects the Agent's disabled tools and permissions. Tool profile choices belong to each conversation and survive tab changes and refreshes.

Search keys take effect on subsequent calls without restarting. An unavailable saved default falls back to another available provider; an explicitly named unavailable provider reports an error that gives the reason (for example the missing key) and lists the providers usable now. Jina search requires JINA_API_KEY. DuckDuckGo reads its no-JavaScript results page and returns the first page of hits (about ten); a bot challenge or an unreadable page is reported as an error, not as an empty search.

combine="race" returns the first nonempty successful response. Named providers that cannot run are skipped; if none can run, the error lists each one with its reason. combine="rrf" retains results completed before the deadline. Total failure is reported as an error, distinct from a successful empty search. Already running requests finish under their transport timeouts.

Images and PDF#

Image tools return an error result when the selected provider is unavailable, its request fails, or an image cannot be saved. mixture_of_agents also returns an error result for unknown model references, when every reference fails, or when synthesis fails. A successful answer remains successful even when some references fail or its text contains the word Error. Ordinary Python execute(...) calls retain their string results.

Session and collaboration#

Collaboration splits into four domains, one word each — see agent collaboration §1.

job_output remains available when the collaboration message allowance is exhausted; reading an existing result does not consume that allowance. New Agent deliveries still obey their limits. To cancel a task, use its execution controls; API cancellation uses execution.command with action="execution.cancel" and the current execution version. This catalog has no job_stop tool.

canvas and agent_browser registered tools mark explicit validation and dependency/process failures as errors. Successful Canvas content and successful CLI stdout remain successful even when the text begins with Error:. Plain Python execute() calls keep their string return values.