Application Bridge API

Reference for the communication layer between OOMU's interface (the Next.js/React front end) and its desktop engine (the Tauri/Rust back end).

The bridge is the boundary where the user-facing application asks the native engine to do work: read a file safely, save a configuration, install a capability package, run inference. This document describes how that boundary works and catalogues the commands most relevant to integrators.

---

1. How the bridge works

The front end never touches the filesystem, database, or models directly. It calls commands; named functions implemented in Rust and exposed through Tauri's IPC. The interface invokes them through a single typed wrapper.

1.1 The invoke wrapper

All calls go through the application's invoke helper (src/lib/invoke.ts), which wraps Tauri's core invoke:

import { invoke } from "@/lib/invoke";

const mods = await invoke<InstalledMod[]>("list_installed_mods");

• Signature: invoke<T>(command: string, args?: Record<string, unknown>): Promise<T>
• Generic T is the expected return type; the back-end result is deserialised into it.
• Runtime detection: when running inside the Tauri runtime, the call is dispatched to the native engine. In browser-based development (no Tauri runtime), the same call is routed to a local mock endpoint so the UI can be developed without the desktop shell.

1.2 Argument naming

Command arguments are passed as a plain object using camelCase keys. Tauri maps them to the corresponding snake_case parameters on the Rust command:

// Front end (camelCase)
await invoke("set_mod_active_state", { modId, active: nextState });

// Back end (snake_case parameters)
// fn set_mod_active_state(mod_id: String, active: bool, ...)

1.3 Error model

When a command fails, invoke throws an InvokeError rather than a raw rejection:

Expected cancellations (such as local_inference_cancelled) are surfaced distinctly from genuine failures, so the UI can treat a user-cancelled stream differently from an error.

---

2. Command reference

OOMU exposes a large command surface (roughly 290 commands as of the P1 expansion). This reference focuses on the categories an integrator works with most. Each command is a Tauri command invoked by name through the wrapper above. The full authoritative list is the set of #[tauri::command] functions registered in the Rust engine.

Convention: argument keys are shown in camelCase as the front end passes them. Return types describe the deserialised result.

2.1 Local context & path validation

These commands let the interface read user-selected files and folders safely, never by raw path access.

read_local_context

Reads a user file or directory into bounded text for use as conversation context, enforcing strict path safety.

• Args: { path: string }; must be an absolute path. A leading ~ is expanded to the user's home directory.
• Returns: { name, path, mimeType, byteCount, text, truncated }
• Safety behaviour:
• The path is canonicalised (aliases and symlinks are resolved to their real target) before any check, so a shortcut pointing outside the approved area is rejected on its real destination.
• The resolved path must fall within the approved roots: the user's home directory, the system temporary directory, or the current workspace directory. Anything outside is refused.
• Reads are bounded: per-file content is capped (96 KB per file), total context text is capped (128 KB), and directory walks are limited in depth (3 levels), entry count (240), and number of file excerpts (40). Oversized content is truncated and flagged with truncated: true.
• Directory mode: when path is a directory, the response mimeType is text/x-directory-context and text contains a structured, depth-limited listing with excerpts.

list_local_directory

Lists the contents of a directory within the approved roots, for building file pickers and workspace views without granting raw filesystem access.

choose_local_model_directory / get_local_model_directory

Open a native folder picker for the local model directory, and read the currently configured directory.

choose_mod_package_path

Opens a native file picker filtered to .oomu packages.

• Args: none
• Returns: string | null; the chosen path, or null if cancelled. Rejects non-.oomu selections with code mod_picker_invalid_file.

2.2 Configuration

Commands that persist user configuration to the encrypted local database.

2.3 Capability packages (Mods)

InstalledMod shape (camelCase over the IPC boundary):

type InstalledMod = {
  id: string;
  name: string;
  description: string;
  isActive: boolean;
  version: string;
  author: string;
  category: string;
  packageSize: string;
  lastUpdated: string;
  permissions: { label: string; detail: string }[];
  endpoints: string[];
};

2.4 Conversation & inference

Auto-Route (dynamic routing). When a session is bound to the special dynamic route, chat_turn scores each prompt's complexity and selects the engine per turn: below threshold → local Gemma; at/above → the provider marked as the Auto-Route target (or a cost-efficient cloud fallback). The per-session toggle is set via update_chat_session_dynamic_routing_override.

2.5 Workflows

Workflow composition (compose_workflow / edit_workflow) is gated by a feature flag (OOMU_WORKFLOW_AUTHORING_P0), enabled by default; when disabled these return a disabled response.

2.6 Trust & sandbox

See Privacy & Sandboxing for what these govern.

2.7 Locale, models & diagnostics

2.8 Projects

2.9 Tasks (the control plane)

2.10 Routines, background helper & channels

2.11 Connectors (work apps)

2.12 Documents & artifacts

2.13 Automation: browser & app control

2.14 Media, delegation, learning & remote

2.15 Capability bundles

2.16 First-run setup

---

3. Notes for integrators

• Treat every path through read_local_context. Do not attempt to pass raw paths to other commands expecting filesystem access; the safe-path boundary is enforced centrally and exists for the user's protection.
• Long-running work returns promptly. Heavy operations (installs, inference) run off the UI thread on the back end; the invoke promise resolves when the work completes or streams.
• Codes over messages for control flow. When you need to branch on a specific failure (cancellation, invalid file), check InvokeError.code, not the message text.

Related

• Capability Package Specification: the .oomu format the Mod commands operate on.
• Local Database Schema: where configuration commands persist their data.
• System Design Overview: how the front end and engine fit together.