Omniscio

Plugin Bridge Capabilities (part 2)

The second half of the plugin bridge: brokering files and commands in a granted project, picking single binary documents, structured model output, speech-to-text, sharing, spend totals and inbox cards.

On this page

What it is

Part 2 of the Plugin Bridge Capabilities page. Part 1 covers the bridge itself — the permission model, and the host-primitive, session and session-history capabilities — while this half carries the file, document and output capabilities: brokering files and commands in a granted project, single binary documents, structured model output, speech-to-text, sharing, spend totals and inbox cards.

Where to find it

Reached as on the main page: from a plugin’s own code, through the bridge object the host hands it, never an Omniscio screen. The grants authorizing the file-facing capabilities here (a project a plugin may read, write or run commands in) live in Settings → Plugins.

How it behaves

One subsection per capability: what it lets a plugin do, the permission it takes, what the host refuses, and the bounds it enforces.

ctx.workspace — read files inside a project the user picked (permission: workspace.read)

Lets a plugin read actual files on disk inside one project the user explicitly chose — the "look at the repo you're reporting on" capability. It is the widest read the bridge grants: sessionHistory hands over a text projection of database rows; this hands over raw file bytes, so the host wraps it in a tighter envelope.

Worker-backend only. The workspace namespace is refused on the webview path — there is no Omniscio.workspace. A webview is a plugin's untrusted half; filesystem reads are brokered only to the worker backend, where the permission gate runs before dispatch.

  • Default-deny, one project at a time. A plugin reads nothing until the user grants it. requestAccess pops a picker; the user picks one project, and the grant covers it plus its worktrees — nothing else.

  • Secrets stay out, even inside a granted project. A granted root is not wholly readable: .env*, id_rsa*, *.pem/key/pfx/p12, .netrc and friends hit the app's own deny-floor.

  • The built-in sentinel projects are never in scope. __claude__ and its siblings resolve to real directories the user never picked, so a sentinel check refuses them first. (Omniscio's ~/.claude tree is separate — unreachable from a project grant.)

  • Revocable, and it lands mid-read. Grants persist and are revocable in Settings → Plugins → "Folders this plugin can reach". A long glob re-checks the grant as it walks, so revoking stops an in-flight read.

  • Visible after the fact. That panel lists the commands the plugin actually ran in those folders — each distinct command, its count, last run time, and whether it ran without asking (only two exact git status forms ever do). The list survives revocation. Headless: GET /plugins/:id/workspace-commands.

  • And you can retire ONE of them, without revoking the folder. Each command has a Stop allowing button asking whether you mean this exact command or every command with that program name; blocked commands get a section with Allow again, so a block is never one-way. Headless: GET/POST /plugins/:id/workspace-command-denies.

    • It can only ever take away. A block cannot make a command run — the per-call confirm is the only approval — and an unreadable block list refuses the command, never allows it. That is deliberately the opposite of the grant check: "I could not tell" must not mean "carry on".
    • It lands even mid-flight. Checked at the shared gate and AGAIN immediately before the command starts, so it stops a command whose confirmation dialog is still on screen, a job already executing it, and the two git status forms that normally run without asking — the one unattended path most needing it.
    • It blocks a spelling, not a capability. /usr/bin/git, GIT and git.exe all match a git block, but npx is not npm, and a shell wrapper is a different program again.
    • What it does NOT cover (a half-true safety control is worse than none): a plugin that can start an agent session in your repo, one holding the system permission (its own code starts programs outside this path), and launchBuild. The panel says so, and warns explicitly on a system plugin, where a block cannot hold at all.
    • Blocks apply to every copy of that project on the machine, worktrees included; they never expire, survive a reinstall, and travel with a portable backup — losing a grant fails safe, losing a block would not.
  • Bounded. The walk is capped on entries, directories and depth, honours .gitignore, and refuses a second concurrent glob from the same plugin.

  • One list of worktrees, and it is live. listWorktrees(projectId) blocks on git rather than reading a cache, so a picker is correct on first open instead of showing only "main" until a cache fills. listProjects deliberately carries NO worktrees — two lists of one thing with different freshness is the bug being avoided.

  • Anything listed is readable. List and permission gate share one selection rule, so a worktree just offered cannot be refused on the next read.

Arguments are positional, and everything after resolve is addressed by a handle ({ projectId, worktree, path }) rather than a bare path, so a checked location cannot be swapped between check and read. worktree is required and nullable; null means the project's main checkout, exactly — never "whichever copy happens to have that file".

// 1) ask the user to grant a project (opens the picker)
await ctx.workspace.requestAccess()

// 2) see what you're allowed to read
const projects = ctx.workspace.listProjects() // [{ projectId, name }] — granted only, NO worktrees

// 3) list that project's worktrees — blocking + live, main pinned first
const worktrees = await ctx.workspace.listWorktrees(projects[0].projectId)
// [{ path, ref, isMain, label, createdAt, checkouts, session, updatedAt }]
//   ref        — the value to put in a Scope; null for main
//   label      — 'main', or the folder name with any -YYYYMMDD-HHMMSS stamp split off
//   createdAt  — that stamp as an ISO date, or null; render it as a relative age
//   checkouts  — [{ repoPath, branch }]; branch null = detached. 1 for a repo,
//                1..n for an umbrella folder holding several repos
//   session    — { id, name, status } when Omniscio owns the worktree, else null
//   updatedAt  — the owning session's last activity, else the folder's mtime

const scope = { projectId: projects[0].projectId, worktree: worktrees[0].ref }

// 4) glob returns entries (path relative to the root, POSIX separators) — turn them into handles
const entries = await ctx.workspace.glob(scope, ['**/*.test.ts']) // [{ path, size, mtimeMs, isDir }]
const handles = entries.filter((e) => !e.isDir).map((e) => ({ ...scope, path: e.path }))

// 5) read a batch — max 256 handles; one bad handle never fails the rest
for (const r of await ctx.workspace.readFiles(handles.slice(0, 256))) {
  if ('content' in r) use(r.handle.path, r.content)
  else console.warn(r.handle.path, r.error)
}

// or resolve a single path to a handle, then act on it
const handle = await ctx.workspace.resolve('package.json') // handle | null
if (handle && (await ctx.workspace.exists(handle))) {
  const text = await ctx.workspace.readFile(handle)
}

A worktree is a hard scope, not a filter: every call takes one, and results from another worktree are unreachable by design. listWorktrees is single-flight per plugin — a second concurrent call is refused, not queued, and that limit is per METHOD, so two different projects cannot be enumerated at once either.

readFiles caps the batch on handle count, total bytes and per-file bytes — chunk your own list rather than passing thousands at once. glob takes an optional third argument ({ exclude, includeIgnored, includeNodeModules, includeWorktrees }), a closed allow-list: any other key is dropped before the walker sees it.

workspace.write and workspace.exec ship as the write + exec slice (elevated tier): workspace.writeFile / writeFiles / mkdir / deleteFile behind a hardened write gate — each mutating call carrying a REQUIRED last-known-modification-time token, so a plugin can never silently clobber a change it did not see — and TWO ways to run a command: workspace.run (one-shot, bounded) and workspace.exec (a JOB that can run for hours, polled via execStatus / execResults / execCancel). Declaring either without workspace.read is rejected at validation; details below.

Engine detail + invariants: plugin-workspace-read-contract.md (reads, grants, worktrees) and plugin-workspace-exec-contract.md (both command paths).

ctx.workspace write + exec — create/change/delete files and run approved commands (permission workspace.write / workspace.exec, elevated tier)

The same granted-project broker, extended to MUTATE. A plugin holding workspace.write can writeFile(handle, content, expectedMtimeMs, opts?), writeFiles([{ handle, content, expectedMtimeMs }], opts?), mkdir(handle) and deleteFile(handle, expectedMtimeMs, opts?) inside a granted project and its worktrees — behind the SAME ordered gate (permission → grant → worktree scope → path shape → secret deny-floor), hardened for writes so no write ever creates through a symlink or an intermediate directory it did not first prove. The deny-floor is segment-level: .env as a directory, .npmrc/.netrc/keys and .git/* anywhere in the chain are refused; alternate-data-stream (:) paths are rejected. Deleting a file the plugin did NOT itself create requires a native confirm you can't skip — only files it authored delete silently.

expectedMtimeMs is REQUIRED — you cannot write blind. It is the file's last-known modification time, exactly as stat() returns it, and the host's answer to two plugins (or a plugin and the user's editor) clobbering each other:

  • null means I believe this file does not exist — a create. If it exists, the call is refused as stale and nothing is written.
  • a number means I believe it exists with exactly this mtime — an overwrite. If it changed since you looked, same stale refusal, and the file on disk is untouched.

So the shape is always stat → decide → write with the mtime you just read; on a stale refusal, re-read and retry. There is deliberately no "just overwrite whatever is there" — that is the lost update this refuses. The stale refusal has its OWN message, distinct from "not available to this plugin", so you can tell retry from give up.

mkdir takes no token because it already behaves like one: creating a directory that exists is refused, never a silent success.

Writes are atomic and preserve the file's permissions. The bytes go to a scratch file beside the target, are flushed to disk and renamed into place — a crash or failure can never leave a half-written file under the real name, and a 0600 secrets file or 0755 script keeps its mode. Two honest limits: the guarantee holds against other plugins and Omniscio, but the user's editor holds no lock, and on filesystems with one-second timestamps (HFS+, exFAT, many network mounts) a change-and-change-back inside one tick can slip past the check.

opts takes an optional encoding. The default is UTF-8 text, so existing calls are unchanged. Pass 'base64' to write a binary file (an image, a PDF, a zip): content is then the base64 of the raw bytes, which the host decodes and writes exactly. Everything else about the write is the same — the gate, the modification-time token, the atomic swap. The size caps (8 MiB per file, 16 MiB per batch) count the DECODED bytes. A string that is not valid base64, or that decodes to more than the cap, is refused and nothing is written; for writeFiles the encoding applies to every entry and one bad entry refuses the whole call. Reads are still text only.

Every successful write, folder creation and delete is recorded — one row each, with path, byte count and time — in a table the plugin cannot reach or erase. Reads are not: they roll up into a per-day counter, because a row per read is roughly 13,000 rows for one index rebuild. Refused and stale attempts are logged host-side but not stored.

workspace.run({ scope, command, args, timeoutMs }) runs a bounded command in the granted project through the host's own hardened spawn: git status --porcelain/--short runs silently, and EVERYTHING else (any other command, any path arguments) pops a native confirm showing the exact command + folder. The child runs credential-stripped, with a PATH excluding the project, output capped at 1 MiB, killed on timeout. Since 2026-10-26 the plugin worker denies child_process for EVERY plugin, system included: the worker is forked without --allow-child-process, so a backend that tries to start a program is refused with a sentence pointing at ctx.workspace.exec. A host-mediated path (workspace.run / workspace.exec here, window.Omniscio.process.spawn from a plugin's webview) is therefore the only way any plugin reaches a subprocess. Worker-backend only, like the reads — the phone bridge reaches no workspace method.

Which do I call — run or exec? The names do not tell you, so: run if the command finishes in seconds and you want its output back; exec if it runs for minutes or hours and you want to watch it. A test suite is exec. git rev-parse is run.

// One-shot: returns when the command exits, 30s default / 120s hard max.
const { code, stdout } = await ctx.workspace.run({ scope, command: 'git', args: ['status', '--porcelain'] })

// A job: returns a handle immediately, then you poll it.
const { started, jobId } = await ctx.workspace.exec({ scope, command: 'npm', args: ['test'] })
const status = await ctx.workspace.execStatus(jobId)                 // state, exit code, pid-free
const page = await ctx.workspace.execResults(jobId, { consoleCursor }) // head+tail console + results
await ctx.workspace.execCancel(jobId)

A job differs from run in ways worth knowing:

  • It always asks. run may skip the dialog only for git status --porcelain/--short; a job never does — it is unbounded, so a silent shortcut would hand a plugin an unattended hours-long process nobody approved.
  • It has no time limit — it dies from silence, not age. Nothing is killed for running long; a job is killed when BOTH streams go quiet for 15 minutes. A timeoutMs you send is dropped.
  • Starting the same job twice gives you the one already running — no second dialog, no second directory, the incumbent's jobId back and started: false.
  • Output keeps the head and the tail. A long run's interesting parts are its first and last lines, so the middle is dropped, never the ends.
  • PATH points the other way. run strips the project's own node_modules/.bin so a repo cannot plant a shadow git; exec prepends it, because running the project's own vitest is the point. Both spawn the exact command the user read in the dialog.
  • Job ids are per-plugin capabilities — another plugin's job id looks like one that never existed, and no host filesystem path is ever returned.

A job is stopped when the app quits, when the plugin is disabled or uninstalled, or when its worker crashes; a leftover scratch dir is reclaimed at the next launch. While a job runs, its worktree will not be retired out from under it.


documents.* — read one binary file the user picked, and save new ones (no permission)

The only way a plugin touches the raw bytes of a file outside its own data directory — built for a PDF viewer that has to save annotations back into the user's own PDF, and hand the person new files made from it. Like export.savePdf, the native dialog is the consent, so it needs no declared permission; unlike ctx.workspace, it is one file rather than a tree, and it can write — either into the file the person opened, or into a new one they place.

A picker mints Handles: opaque capabilities, one per file the person chose. A Handle carries an unguessable id, the basename, the length, a fixed read/read-write bit and a loopback URL. It never carries a path, and picking adds no folder grant — so a plugin cannot name a file, open one it wasn't handed, or widen its reach.

const [doc] = await Omniscio.documents.open({ mode: 'readwrite' }) // native dialog
const bytes = await (await fetch(doc.url)).arrayBuffer() // read: a loopback GET
const { length } = await Omniscio.documents.append(doc.id, deltaBase64, {
  expectedLength: doc.size // what you believe is on disk right now
})
await Omniscio.documents.close(doc.id) // also: list(), stat(id)

Saving is append-only compare-and-append (ADR 0004): you send an increment, not a whole file. expectedLength is the compare — pass the length your last save returned, and feed each returned length into the next call. Four things a plugin author must know:

  • A save may never discard more bytes than it writes. That lets a half-finished save be repaired by replaying it, and stops a foreign edit larger than your Delta being silently eaten. Refusals carry a stable [code] in the message (shorter-than-expected, discards-more-than-it-writes, not-the-picked-document, read-only-handle, …) so you can tell "someone else changed this file" from "you asked for something impossible" — branch on the code, never the prose, which the host rewords.
  • A Handle authorizes a file, not a path — call stat after anything else touches it. Every "Save" in Preview or Word writes a temp file and renames over the original, which the OS counts as a different file. Both paths that move bytes refuse it: append fails with not-the-picked-document, and fetching the URL returns 404 — neither follows a file the user did not choose. documents.stat is the one call that adopts the replacement: it re-checks that what is now at that path is still something the user was allowed to pick, and carries the Handle over. So after an external save the sequence is stat → append, and stat is what you should be calling anyway to get expectedLength. If the path now leads somewhere protected, or to something not a regular file, stat refuses too and the Handle stops working. Identity is dev+ino plus, on Windows and macOS, the file's birth time — so a same-path replacement reusing the inode is still recognised as a different file.
  • A read and a save are ordered, never interleaved. Fetching the URL during a save waits for it and cannot return a half-written body.
  • The host refuses reads AND writes into sensitive trees (~/.claude, .ssh, .env, private keys) even when the user picks one in the dialog. A multi-select is all-or-nothing: one refused file fails the whole call rather than returning fewer Handles than the person chose.
  • Handles are a bounded resource. At most 32 open per plugin, no file over 64 MiB, and open() is rate-limited (burst of 5) — each call throws a modal dialog at the person. Extra codes: too-many-handles, file-too-large, too-many-requests, protected-path, not-a-file, could-not-read.
  • doc.url carries a per-Handle secret. It is …/@doc/<id>.<token>, and the token authorizes the read. Treat the whole URL as the capability: don't log it or put it where another plugin or a page could read it. It dies when the Handle closes, the plugin is disabled, or the plugin is uninstalled.

Reopening a file after a restart — remember, grants, reopen, forget

A Handle dies with the app: a plugin showing a library of previously-opened documents had every row fall back to a file dialog when Omniscio restarted — for a file the person opened yesterday and knows they opened. Ask for the pick to be remembered, and you can reopen that file later with no dialog:

// Ask the host to remember what the person picks.
const [doc] = await Omniscio.documents.open({ mode: 'readwrite', remember: true })

// …a restart later: what may this plugin reopen?
const remembered = await Omniscio.documents.grants() // [{ grantId, name, mode, lastOpenedAt }]
const doc2 = await Omniscio.documents.reopen(remembered[0].grantId) // an ordinary Handle
await Omniscio.documents.forget(remembered[0].grantId) // drop one yourself

What a plugin author must know:

  • remember is a request, not a grant. The first time your plugin asks, the person is asked once — "Let your plugin reopen files you pick without asking again?" — and their answer, yes or no, is remembered so they are never asked twice. If they say no, nothing is remembered and grants() stays empty; that is normal, not an error.
  • The ask never blocks the pick. open() returns its Handles immediately whether or not the person has answered; never wait on the dialog. Call grants() afterwards to see what got remembered.
  • Never store grant ids yourself — always ask grants(). Your copy cannot see a revoke, so a stored id would offer the person a row guaranteed to fail; the host is always current.
  • reopen gives you an ordinary Handle. Same shape, same id rules, same stat / append / fetch(url) behaviour, same 32-handle cap; nothing else in this section changes.
  • A grant names ONE file, and carries no path. grants() hands you a basename, as a Handle does.
  • Handle these three refusals distinctly — they need different things from the person:
    • unknown-grant — revoked, expired, or never yours. Drop the row and show the picker.
    • permission-denied — the operating system is blocking it, not your plugin and not a broken file. On macOS this is a Files-and-Folders privacy prompt the person declined; send them to System Settings rather than implying the document is damaged. The grant survives, so it works once they allow it.
    • could-not-read — the file is genuinely gone or moved. The host deletes that grant itself, so it is not in the next grants().
  • Grants are bounded and they decay. At most 64 per plugin (least-recently-opened dropped past that), and a grant unused for 90 days stops working — a library lasts "while the person is actually using these", not forever. reopen shares open's rate limit, so a loop hits too-many-requests.
  • Everything is revoked when the plugin is disabled or uninstalled — grants and the remember permission both. A disable is a revoke, not a pause: after a re-enable the person is asked again and your library starts empty. Do not design around keeping it.
  • The person can see and take back every remembered file under Settings → Plugins, in "Files this plugin can reopen", and can turn remembering off entirely. Treat an empty grants() as legitimate at any time.

Saving a NEW file — saveCopy and saveCopies

append only reaches the file the person already opened. To hand them a new file — a split part, a page selection, a page picture — there are two methods, and neither one is ever given a path.

// One file. The native Save window is the consent; replacing is atomic.
const one = await Omniscio.documents.saveCopy({
  name: 'pages 1-3.pdf', // a SUGGESTION for the window
  base64,
  filters: [{ name: 'PDF', extensions: ['pdf'] }]
})
if (!one.saved) return // the person cancelled — not an error
console.log(one.names) // ['pages 1-3.pdf'] — bare names, never a path

// Several files into a folder the person picks. Never replaces anything.
const many = await Omniscio.documents.saveCopies({
  title: 'Where should the parts go?',
  files: [{ name: 'part 1.pdf', base64 }, { name: 'part 2.pdf', base64 }]
})
console.log(many.names) // what was ACTUALLY written, after any numbering

What a plugin author must know:

  • The window IS the consent. No method takes a folder or a path, and a copy leaves no folder grant and no Handle behind — so the next copy asks the person again. Never design a flow that assumes you can save twice from one answer.
  • A copy never touches the document you opened. Its bytes, and the file on disk, are unchanged.
  • saveCopy may replace, atomically. Answering the window with an existing file replaces it, but only once the whole new copy is ready — an interrupted save leaves the old file intact.
  • saveCopies never replaces. Each name is reserved exclusively and a clash gets a number: report.pdf becomes report (2).pdf. The names you get back are what was actually written, which is how you learn what a clash was renamed to. A call that fails part-way removes the copies it had already written.
  • Names are names. A bare file name only: no / or \, no . or .., no control characters. The host checks it again and refuses with bad-name.
  • Size is one bridge call. About 24 MiB of decoded bytes per call, shared across every file in a saveCopies call; past that you get copy-too-large. Save fewer at a time rather than looping to spray files — every attempt still needs the person to answer a window.
  • Other codes to branch on: could-not-write (the disk refused it — macOS privacy prompts show up here), protected-path (somewhere the app will not write), too-many-requests (the shared pacing bucket), name-exhausted (that folder already holds every numbered variant).

This capability ships switched off. documents.* sits behind an in-development flag, so every call answers This capability is not available. until the user turns on Plugin document access in Settings. Treat that refusal as a normal state, not an error — it is deliberately identical for a method that does not exist, so a switched-off build tells you nothing about the surface.

Engine detail + invariants: documents-bridge-contract.md.


ai.generateStructured — fill a schema with the model (permission: ai)

Metered, forced-tool generation: the plugin hands the host a JSON schema (the "tool") plus a prompt; the host forces the model to produce a value matching that shape (on the user's Anthropic account) and returns the structured object. Ideal for outlines, cards, extraction — anything wanting typed data back, not prose. A host-enforced per-plugin daily spend cap protects the user's bill, and prompt/system text is capped at 32 KB as a spend guard.

const outline = await Omniscio.ai.generateStructured({
  prompt: 'Draft a 5-slide outline about our Q3 results',
  tool: {
    name: 'make_outline',
    description: 'Return the deck outline', // optional
    inputSchema: {
      // a JSON Schema object
      type: 'object',
      properties: { slides: { type: 'array', items: { type: 'string' } } },
      required: ['slides']
    }
  },
  systemPrompt: 'You are a concise deck writer.', // optional
  premium: true, // optional — opt into the higher-tier model
  maxOutputTokens: 8192 // optional — longest answer, 1 to 16,384 (default 4,096)
})
// -> outline is the validated tool input, e.g. { slides: [...] }

A cut-off answer is refused, never returned. If the model runs out of room before it finishes filling the schema, the call rejects with "The AI's answer was too long and was cut off before it finished. Try asking for less at once." — the half-written object never reaches your plugin, because a partial object still parses cleanly and would look complete. The call is still billed against your plugin's daily cap. Ask for less per call (one page, one section, fewer items) or a longer answer with maxOutputTokens (below), and retry. If the model stops early for any other reason, the call rejects with "The model did not return structured output. Please try again."

Ask for the answer length you need. maxOutputTokens is the longest answer the model may write, in output tokens: a whole number from 1 to 16,384, and 4,096 when omitted. A value outside that range — 0, 16,385, a fraction, a string — is refused with an error naming the range ("maxOutputTokens must be a whole number from 1 to 16,384"), never quietly changed, and nothing is billed. A longer answer gets more time: 60 seconds per started 4,096 tokens, up to 190 seconds; near the top of the range the model may not finish in time and the call fails as timed out — so ask for what one call needs. A longer answer also costs more: one call can spend up to four times a default-length one against your daily cap, checked before each call rather than reserved. The host accepts only the fields shown above; any other field is dropped.

The simpler ai.generateMessage / ai.generateTitle / ai.isConfigured methods remain for plain-text needs. They answer to the same per-plugin daily cap and attribution on both surfaces — a background-worker call is metered against your plugin exactly as a pane call, so a timed job cannot spend past your cap by moving to the worker. generateStructured also takes an optional Claude model (the plugin's pick); without one, premium chooses as before.


Choosing the AI engine and model — ai.generateMessage options and ai.listEngines (permission: ai)

A plugin's user can pick which AI provider AND which model does each kind of AI work. Check the host first: only a host whose host.getCapabilities() lists ai-engine-choice honours a pick.

const caps = await Omniscio.host.getCapabilities()
if (caps.includes('ai-engine-choice')) {
  const list = await Omniscio.ai.listEngines()
  // list.defaults.writing / list.defaults.session — what "Use Omniscio's default" means now
  // list.engines[] — { id, label, ready, writing, writingReady, canRunNoTools, defaultModel, models[], data }
  const engine = list.engines.find((e) => e.writing && e.writingReady)
  const pick = { provider: engine.id, model: engine.models[0]?.id }
  const text = await Omniscio.ai.generateMessage(system, user, pick)
} else {
  // An older host: offer "Use Omniscio's default" only, and send exactly two arguments.
}

What to know:

  • A writing call is text in, text out. Claude runs on the user's Anthropic API key, as before. Another vendor runs as ONE direct request to its Anthropic-compatible endpoint on the user's own pay-as-you-go key: DeepSeek, Kimi, MiniMax, Meta, Qwen and OpenRouter (writing: true). Engines with their own agent runtime (Codex, Gemini, Cursor, Grok, …) and subscription-billed ones (GLM coding plan, GPT and Grok via the proxy) are agent sessions only, refused for writing with a plain sentence. A writing call never becomes an agent session, so a scraped article in a prompt can never make it act on the machine.
  • Send the third argument only with a pick, and only to a host with the token — an older host refuses three arguments. A worker must never pass an explicit undefined (it arrives as null: a current host reads "no pick", an older one refuses).
  • The daily $5 cap covers every engine, counted from real token usage at list price under the plugin's own label. A deadline refusal always contains the words "timed out".
  • Needs ai AND sessions for a writing call on another vendor.
  • listEngines() is the host's live registry (one entry per model, the host pickers' own rule). ready says an agent session can start here; writingReady says a writing call would be served, which needs the user's own key, so the two can differ. data ({ operator, hostedIn, passesOn, dependsOnModel }) is where the engine takes the text: compose the privacy sentence from it, never type a list into the plugin.
  • The plugin session floor shapes this list. While the floor applies to the asking plugin, engines outside the Claude family read ready: false (writingReady is unchanged), and the top-level agentsLocked is true: a hidden session answers in text only unless it asks for access: 'web', so send the user to the plugin's full-access switch before a feature that needs tools. A web session stays web-only and on Claude-family engines even under full access. An older host omits the field. See Plugin agent safety floor.
  • canRunNoTools says whether a session with every tool denied can run on the engine: a plugin session that did not ask for tools, or the floor's text-only lock. It is true for the engines that run on the Claude program and false for Codex, Gemini, Cursor and the other engines with their own agent runtime, which cannot hold that lock. It describes the engine, not the plugin, so no floor switch moves it: offer an engine for a no-tools feature only when it is both ready and canRunNoTools. An older host omits the field, so read a missing value as unknown, never as false.
  • Manifest: a select storing a pick declares "optionsSource": "ai-engines" and keeps its static options as the declared fallback; the host accepts any well-formed pick (<provider> or <provider>:<model>) by shape, so a retired model never blocks a save.

Governed by plugin-ai-engine-choice-contract.md.


Showing a choice — modelPicker.open (no permission)

A plugin never draws its own dropdown: it asks the app to open its one picker over the plugin's button and gets back the row the person picked. The name is historical — the rows are yours, so it serves a model choice, a project choice, a run location, anything.

const caps = await Omniscio.host.getCapabilities()
if (caps.includes('model-picker')) {
  const r = button.getBoundingClientRect()
  const picked = await Omniscio.modelPicker.open({
    value: stored,                  // '' = the default row
    defaultLabel: 'Claude, Sonnet', // what the default resolves to; the app adds "Use default (…)"
    options: [{ value: 'deepseek:v4', label: 'V4', group: 'DeepSeek' }],
    anchor: { x: r.x, y: r.y, width: r.width, height: r.height },
    title: 'Writing model'
  })
  if (picked !== null) save(picked) // null = dismissed
} else {
  // An older host: show a plain select over the same rows.
}

What to know:

  • The plugin owns the rows. Build them from ai.listEngines() and your own rules; every row needs a group, which becomes its heading. disabled + reason shows a row the person cannot pick yet ("not set up"). At most 500 rows and 200 characters per label.
  • A row can carry a picture. icon is one of four shapes the app draws itself — { kind: 'emoji', char }, { kind: 'badge', label, bg, fg }, { kind: 'tile', label, bg }, or { kind: 'image', dataUri }. Colours must be hex, a data URI must be PNG/JPEG/WebP/GIF base64 under 32 KB, and nothing else crosses — you pick a shape and a colour, never markup. The app shows it in the row and on the closed control.
  • Only an offered row comes back. The answer is '', null, or one of your enabled values, and the app refuses an answer from anywhere but the window showing your panel.
  • One at a time. A second open while one is showing answers null at once, as does an open from a hidden panel. The menu sits on your button, clamped to your frame.
  • A rejection means fall back. The call rejects where the app cannot draw it; show the plain select then.
  • On the phone the page answers the call itself, the same way.

Governed by session-launcher-contract.md ("Plugins borrow the launcher").


ai.generateTextViaSubscription — write on the person's Claude plan (permissions: ai and ai.subscription)

Writing text on the person's own Claude plan, with the stored key kept as the backup. A host that has it lists ai-plan-text in host.getCapabilities(), and only to a plugin whose manifest declares ai.subscription; a plugin without that permission is never told the token.

const caps = await Omniscio.host.getCapabilities()
let text = null
if (caps.includes('ai-plan-text')) text = await Omniscio.ai.generateTextViaSubscription(system, user)
if (text === null) text = await Omniscio.ai.generateMessage(system, user)

What to know:

  • Text only, no tools. The answer comes from a one-shot run of the Claude program with no built-in tools, no tool servers, no settings layer and none of the person's own customizations. The app reads the program's own start-up report and refuses the answer if any tool appears.
  • Only while the plugin is turned on, on the worker leg too.
  • Only for a plugin that declared ai.subscription. A call from a plugin without it is refused with the same code and sentence as any other plan failure, so a plugin that falls back to its key on that code keeps working. The token and the call use the one check, declaresAiSubscription.
  • The same limits as a picture call: the plugin's daily AI limit (zero means stopped), the worst-case reservation and at most 3 calls in flight. Plan usage is counted against that limit at its API-equivalent value in its own tally, which never appears in any spend view; it clears when the app restarts. Decks keeps its pooled deck budget, as everywhere else.
  • One refusal for every failure. Code plugin-ai-plan-unavailable (window leg) and the fixed sentence "Your Claude plan could not write this right now. Try again later, or use your API key instead." (both legs). It never says why, so a plugin cannot learn which sign-in the person uses. On the window bridge a refusal resolves null; a worker's call rejects.
  • Arguments: system prompt up to 32 KB (may be empty), request 1 character to 32 KB, and an optional { model } naming a Claude model. A provider or a picture is refused.
  • The host never switches payer. It never answers from the stored key by itself; the plugin calls generateMessage as its backup.

Governed by plugin-ai-plan-text-contract.md.


stt.* — turn a recording into text (permission: stt, plus microphone to record)

The speech-to-text mirror of read-aloud: the plugin hands the host a recording and gets a transcript back. The host owns the speech-provider key throughout, so it never reaches plugin code — the plugin only sees audio it recorded and text it got back.

Recording and transcribing are two separate permissions, on purpose. microphone lets a plugin open the mic inside its own webview; stt lets it send a recording off-device to whichever cloud speech service the user configured. They leak differently — one opens a live sensor, the other ships speech to a third party — and a plugin can legitimately want either alone (record-and-keep-local, or transcribe a file the user already had). Holding stt does not let you record, nor microphone transcribe.

// Decide whether to render a mic button at all.
if (await Omniscio.stt.isConfigured()) showMicButton()

// mimeType is optional and advisory — the host sniffs the real container from the
// bytes and the sniff wins, so a wrong or missing label cannot corrupt the upload.
const { text } = await Omniscio.stt.transcribe(audioBase64, {
  mimeType: 'audio/webm;codecs=opus', // optional
  language: 'en' // optional
})

Accepted containers: audio/webm (incl. ;codecs=opus), audio/ogg, audio/mp4, audio/mpeg, audio/wav. WebM/Opus is the best-tested path — it is the MediaRecorder default.

Silence is a success, not an error. A recording the provider heard nothing in resolves with { text: '' }; only a real failure rejects. Do not treat empty text as a failure, or a rejection as empty text — the two are deliberately distinguishable, and collapsing them makes an expired API key show up as "no speech detected".

Failures reject with a machine-readable err.code, so branch on that, not prose: SERVICE_UNAVAILABLE (no provider configured, or the provider failed), VALIDATION_FAILED (empty audio, or over the size cap), RATE_LIMITED (the user's daily voice-spend cap is reached), and FORBIDDEN / PAYMENT_REQUIRED (cloud transcription is a Pro perk). isConfigured() is a snapshot and can go stale — the user may remove their key between your check and your call, so keep the catch either way.

Bounds: one complete recording per call (batch only — no streaming API), and audio is capped at 10 MB decoded, matching the limit the speech providers themselves enforce so the two never disagree. Oversize audio is rejected, never truncated and never uploaded — a clipped recording would transcribe into a sentence that stops mid-word, reading as a transcription bug rather than a size error. Spend is bounded by the user's existing daily voice-spend cap and the Pro entitlement check, both running before anything paid happens.


export.savePdf — render your HTML to a PDF file (no permission)

Turns a self-contained HTML string into a PDF and writes it through the OS Save dialog (the dialog is the consent, so — like export.saveFile — it needs no declared permission). Under the hood it drives the app's own hardened, sandboxed htmlToPdf (offscreen window, JavaScript disabled, single-flight, timeout-bounded), so a plugin produces polished PDFs without shipping its own PDF engine.

await Omniscio.export.savePdf({
  filename: 'deck.pdf', // required, ≤255 chars
  html: '<!doctype html>…', // required, self-contained HTML, ≤20 MB
  preferCSSPageSize: true, // optional — honor the document's @page size
  landscape: true // optional
})

Only those two print booleans are surfaced (no header/footer templates from untrusted plugin input); the plugin supplies the HTML, rendered client-side from your own components. Resolves { saved: true | false }, like export.saveFile — never where the file went.


Binary files — encoding: 'base64' on export.writeFiles and fs.readFile / fs.writeFile (no new permission)

A plugin can now save and read files that are not text — images, PDFs, zips — without the bytes being mangled on the way. Every call that takes file content accepts an optional encoding: 'utf8' (the default, so nothing you already wrote changes) or 'base64'.

await AgentMC.export.writeFiles({
  directory: pickedFolder, // from export.pickFolder, as before
  files: [
    { name: 'report.md', content: '# Hello' }, // text, as before
    { name: 'logo.png', content: pngBase64, encoding: 'base64' } // raw bytes
  ]
})

const bytes = await ctx.fs.readFile('cache/logo.png', { encoding: 'base64' })
await ctx.fs.writeFile('cache/copy.png', bytes, { encoding: 'base64' })
  • Writes decode the base64 and write the exact bytes. The string must be strict base64: only A-Z a-z 0-9 + /, = padding, and a length that is a multiple of 4. Anything else is refused with a plain message and nothing is written; with export.writeFiles the whole batch is checked first, so one bad file means none are saved.
  • Size limits count the decoded bytes, using the limits each call already had: 20,000,000 bytes per file for export.writeFiles, 20 MiB for fs.writeFile. Over the limit is refused and nothing is written.
  • Reads (fs.readFile with 'base64') return a file's raw bytes as base64, up to the 64 MiB read limit. This is also how a plugin reads a file from a folder the person picked: the same folder grant, protected-files list and link checks apply as for a text read, and the document extractors that turn a PDF or Word file into text are skipped, because you asked for bytes.
  • Nothing about where a file may go changes. ../ paths, links that lead out of the allowed folder, ungranted folders and the protected-files list are refused for base64 exactly as they are for text.

Workspace files take the same option on writes: see workspace.writeFile / writeFiles above. In the plugin SDK, ctx.fs and AgentMC.export.writeFiles carry the typed option (the SDK reference regenerates from the host schemas).


Uploads a self-contained HTML artifact through Omniscio's share relay (authed by the signed-in user's identity) and returns a public token + URL — the mechanism behind "Publish" in the app. Lets a plugin turn a rendered document into a shareable link.

const { token, url, expiresAt } = await Omniscio.share.publishArtifact({
  html: '<!doctype html>…', // required, ≤20 MB
  fileName: 'deck.html', // optional
  title: 'Q3 Deck', // optional
  fullBleed: true, // optional — edge-to-edge layout
  expiresInDays: 14 // optional — a SHORTER life than the 30-day default, 1 to 30
})

expiresInDays may only shorten a link: 1 to 30 whole days, and anything outside that range is refused rather than clamped, so a plugin never believes it asked for a shorter life than it got. A publish that names no lifetime keeps the 30-day default, and no link is ever given a longer life than 30 days. The result reports expiresAt, the moment the link stops working, read back from the stored link rather than echoed from the request: a publish of a page that already has a live link can shorten that link, and the date returned is always the real one.

The host records which plugin published the link, so only that plugin can revoke it later. A plugin's publishes never reuse another publisher's link, even for identical HTML. The handler loads the share service on first call, keeping its heavy page builder out of app start-up, and the HTML travels inline, so no folder grant is involved.


Revokes a link the SAME plugin published with share.publishArtifact. Check for it first: host.getCapabilities() includes share-revoke-artifact on a host that has it, and older hosts have no share.revokeArtifact at all.

const { revoked, deferred } = await Omniscio.share.revokeArtifact({ token })
  • { revoked: true, deferred: false } — the link is down. Asking again gives the same answer.
  • { revoked: false, deferred: true } — the link is yours and the revoke is recorded, but the share service could not be reached. Omniscio's periodic sweep finishes the take-down, so it is safe to forget the token.
  • { revoked: false, deferred: false } — there is no link of yours under that token. It may be unknown, another plugin's, the person's own share, already deleted, or published before the host recorded publishers. Every one of those gives this same answer, so the reply never reveals whose a token is. The person can still revoke any link from Shares.
  • The phone relay answers it too; the host works out which plugin is asking, never the page.

spend.getBreakdown — read the user's AI-spend totals (permission: spend)

Returns the host's already-computed "all AI spend" breakdown — the honest two-half story Omniscio's daily-spend inbox card tells — as typed, plain data a plugin can render as it likes:

  1. Agent coding value — your coding sessions priced at API rates but covered by your flat subscription. This is the VALUE of the work, not money out of pocket.
  2. Background-feature spend — real, token-metered charges for background AI features (title generation, digests and the like), with the true out-of-pocket slice (charges billed to a real API key) broken out.

The call takes no arguments: the host resolves "now" and your local timezone itself, so a plugin has no window or timezone to abuse. It is read-only and returns global totals across all your accounts (no plugin-scoped slice). The return is the locked SpendReportBreakdown shape (three windows — yesterday / last 7 days / last 30 days — plus yesterday's per-engine, per-feature and notable-charge drill-downs); all money is USD.

const b = await Omniscio.spend.getBreakdown()
// b.windows.yesterday.codingValue   -> coding VALUE (covered by your plan, not a bill)
// b.windows.yesterday.outOfPocket   -> real money billed to an API key
// b.windows.week / b.windows.month  -> rolling 7- and 30-day windows
// b.codingEngines / b.backgroundFeatures / b.notableCharges -> yesterday's drill-downs

The shape is a published contract: Omniscio only ever ADDS fields, never renames or repurposes one, so a plugin compiled against an older version keeps reading it. The bundled Daily Spend Report plugin uses exactly this read for its daily card.


members.list — read the people in the workspace you are using (permission: members.read)

ctx.members.list() (a backend) and Omniscio.members.list() (a panel) return the active workspace's roster, one entry per person:

const people = await Omniscio.members.list()
// [{ id, displayName, avatarUrl, role }, ...]  role: 'owner' | 'admin' | 'member' | 'guest'

What to know:

  • The call takes no arguments. With no workspace parameter, a plugin reads only the workspace the person is using right now. Switching workspace switches the list on the next call; nothing is cached on your side of the bridge.
  • Four fields, and only four. id, displayName, avatarUrl and role — built key by key, so an email address, an invite state or any other field never crosses. avatarUrl is null for a person with no picture.
  • It fails closed until the app knows where you are. Omniscio answers only from the workspace its own screen has told it you are using; until then the call refuses rather than guessing from your sign-in, so a plugin never sees another workspace's people.
  • The personal workspace returns just the signed-in person.
  • A refusal is a refusal. Signed out, a workspace you no longer belong to, or an app that has not reported your workspace rejects with a plain sentence (MembersErrorCode rides on err.code) rather than an empty list, so "could not read the roster" never looks like "nobody is here".
  • It goes through the one Members service — the same list, removal and roles the Members screen shows.
  • Guests appear with role: 'guest' because they are in the workspace; invite state never does.
  • The phone relay does not expose it — desktop and worker only.

inbox.postAlert — drop a persistent markdown card in the inbox (permission: inbox)

Posts one persistent inbox card whose body is markdown (rendered through Omniscio's markdown pipeline, so headings, tables and lists all work). The card survives restart and lives in the user's inbox until they archive or snooze it — the right tool for a digest, a daily report, or a "here's what I found" summary. It reuses the same inbox permission as inbox.setItems (no separate permission to declare).

await Omniscio.inbox.postAlert({
  title: 'AI Spend, Monday Jul 20', // required, ≤300 chars
  body: '## Yesterday\n\n| Period | Value |\n|:--|--:|\n| Yesterday | $34.2k |', // required markdown, ≤50 KB
  dedupKey: 'daily-report', // optional — coalesce repeats into ONE refreshing row
  chatRouteTag: 'my-plugin', // optional — your own plugin id; also posts the card into Team Chat
  inboxVisible: false, // optional — with a chatRouteTag, post to Team Chat only, not the inbox
  openPlugin: true // optional — the card gets an "Open the plugin" button that opens YOUR panel
})

Host-enforced guarantees a plugin cannot override:

  • It is always an agent-sourced text card. The host forces the source kind and a text body, so a plugin can neither impersonate a non-agent source nor post a non-text payload.
  • The dedupKey is namespaced. Whatever key you pass is stored as plugin:<yourPluginId>:<dedupKey>, so your card can never hijack or coalesce an Omniscio-internal alert (an app card keyed, say, memory-commit-pressure-high), and two plugins picking the same key never collide. Omit the key and the host derives plugin:<yourPluginId>:auto:<hash of title + body>, so a plugin that retries or re-posts the same card every tick coalesces onto ONE card instead of piling up duplicates, while different content still gets its own card (F134).
  • openPlugin keys are host-built. The key becomes plugin-open:<yourPluginId>:<dedupKey>; you cannot point the button at another plugin.
  • A Team Chat route tag must be your own plugin id. chatRouteTag is kept only when it equals the calling plugin's id and is not one of the app's reserved built-in tags; anything else is dropped. The card then reaches whichever Team Chat channels the person routed that tag to in their alert-routing rules — none, until they set one up.
  • inboxVisible: false only takes a card out of the inbox when it goes to Team Chat. It is honored only alongside a kept chatRouteTag, so a plugin can post a chat-only message (Good Things uses it to post "Sam recognized Jo" to the team while the writer's own inbox says "You recognized Jo") but can never make an ordinary card silently disappear.

The post is fire-and-forget: it inherits the user's "agent alerts" setting (if they've turned agent alerts off, nothing is posted) and it never throws back into your plugin.

Where it lives: src/main/ipc/plugin-bridge/inbox-handler.ts is the ONE implementation of both inbox methods. The v2 worker path (plugin-enable.ts, realContext.inbox) delegates to it, so the forced envelope and the dedupKey prefix are never duplicated. inbox.setItems replaces the plugin's whole item set and is published through inbox-items-publish.ts, the single producer that validates the items, caches the last set for the panel's pull-hydrate and emits the push. The argument schemas live in src/shared/plugin-capabilities/args.ts (INBOX_SCHEMAS): setItems is capped at 500 items there before the handler runs, and each item's shape is then enforced by the pluginInboxItemsPayload push schema (push-event-schemas/plugin.ts).

inbox.resolveAlert — withdraw your own card (permission: inbox, backend only)

await ctx.inbox.resolveAlert({ dedupKey: 'queue', openPlugin: true })

Pass the same dedupKey and openPlugin you posted with; it withdraws only your own card, and nothing to withdraw is not an error. It is not available from a panel (Omniscio.inbox), only from the backend ctx.

http.uploadFile — send a picked-folder file to a listed website (permission: network.upload)

A plugin panel can upload one file the person shared with it — a file inside a folder they picked with export.pickFolder — to a website its manifest names in uploadHosts ("uploadHosts": ["rupload.facebook.com"]). The permission and the list go together: a manifest with one and not the other is refused at install.

  • The person approves the list once. The first upload shows a native dialog naming the plugin and every listed site; nothing is sent before Allow. A Don't allow is remembered until the app restarts or the plugin is turned off and on, so a plugin cannot nag. A list that gains a site asks again; a site no longer listed is never sent to.
  • https only, to an exact listed name. No other scheme, no port, no username or password in the address, no wildcard or subdomain, and a name that resolves to a private address is refused when the connection opens.
  • Only a file from a picked folder, judged after following links, never a credentials, key or .env file even inside one, and at most 2 GB. Omniscio opens the file, checks it is the same file it approved, and streams exactly its bytes, so the contents never pass through plugin code.
  • No redirect is followed — a 3xx answer comes back to the plugin as is. Plugin-set Host, Content-Length and connection headers are dropped; sizeHeader asks Omniscio to put the file's byte count in a header the site needs (Facebook's file_size).
  • Turning the plugin off or uninstalling it forgets the approval, and every allow, deny and forget is written to the plugin audit trail.

The call returns the site's answer as { ok, status, statusText, headers, bodyText } and has its own 60-minute limit, so a large video is not cut off by the bridge's usual time limit. Plugin panels only: a backend worker cannot upload. Locked by plugin-file-upload-contract.md and http-upload-handler.test.ts.

How these fit together

A common "generate → render → deliver" flow uses all four: ai.generateStructured to produce typed content (optionally seeded from sessionHistory), your own client-side renderer to build the HTML, then export.savePdf (local file) or share.publishArtifact (a link) to deliver it. Declare the permissions you use in manifest.json — for the above: ["ai", "sessions.readHistory", "firebase"] (export needs none).

Plugin Bridge Capabilities is the first half of this page — the permission model, and the host-primitive and session capabilities. Every capability here leans on the same install-time consent, described in the marketplace consent flow; Plugin CLI Discovery covers how a session finds and drives an installed plugin.

Opening the item named by a plugin alert

With openPlugin: true, the button opens your plugin and sends the complete raw dedupKey as the existing navigate command payload { itemId }. For example, newsletter-scheduled-send:not-sent:issue-123 arrives intact. Handle that command in your panel and choose the matching issue; unknown or deleted items should fall back to your home view. Opening an alert does not send email or run its suggested action.

The host waits until the matching panel is ready. Popped-out alerts first open in the main window, where the button can deliver the destination. Stopped-run and reconnect alerts still open the plugin without an item target. Historical non-actionable alerts remain as saved and can coexist with newer actionable alerts.

Last verified 2026-10-28