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.
requestAccesspops 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,.netrcand 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~/.claudetree 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
globre-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 statusforms 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 statusforms that normally run without asking — the one unattended path most needing it. - It blocks a spelling, not a capability.
/usr/bin/git,GITandgit.exeall match agitblock, butnpxis notnpm, 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
systempermission (its own code starts programs outside this path), andlaunchBuild. The panel says so, and warns explicitly on asystemplugin, 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 concurrentglobfrom 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.listProjectsdeliberately 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:
nullmeans 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.
runmay skip the dialog only forgit 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
timeoutMsyou send is dropped. - Starting the same job twice gives you the one already running — no second dialog, no second
directory, the incumbent's
jobIdback andstarted: 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.
PATHpoints the other way.runstrips the project's ownnode_modules/.binso a repo cannot plant a shadowgit;execprepends it, because running the project's ownvitestis 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
statafter 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:appendfails withnot-the-picked-document, and fetching the URL returns 404 — neither follows a file the user did not choose.documents.statis 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 isstat→append, andstatis what you should be calling anyway to getexpectedLength. If the path now leads somewhere protected, or to something not a regular file,statrefuses 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.urlcarries 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:
rememberis 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 andgrants()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. Callgrants()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. reopengives you an ordinary Handle. Same shape, same id rules, samestat/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 nextgrants().
- 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.
reopensharesopen's rate limit, so a loop hitstoo-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.
saveCopymay 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.saveCopiesnever replaces. Each name is reserved exclusively and a clash gets a number:report.pdfbecomesreport (2).pdf. Thenamesyou 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 withbad-name. - Size is one bridge call. About 24 MiB of decoded bytes per call, shared across every file in a
saveCopiescall; past that you getcopy-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 answersThis 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 asnull: 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
aiANDsessionsfor a writing call on another vendor. listEngines()is the host's live registry (one entry per model, the host pickers' own rule).readysays an agent session can start here;writingReadysays 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(writingReadyis unchanged), and the top-levelagentsLockedis true: a hidden session answers in text only unless it asks foraccess: '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. canRunNoToolssays 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 bothreadyandcanRunNoTools. 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 staticoptionsas 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 agroup, which becomes its heading.disabled+reasonshows 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.
iconis 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
nullat 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 resolvesnull; 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
generateMessageas 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; withexport.writeFilesthe 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 forfs.writeFile. Over the limit is refused and nothing is written. - Reads (
fs.readFilewith'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).
share.publishArtifact — publish HTML to a shareable link (permission: firebase)
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.
share.revokeArtifact — take down a link this plugin published (permission: firebase)
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:
- 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.
- 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,avatarUrlandrole— built key by key, so an email address, an invite state or any other field never crosses.avatarUrlisnullfor 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 (
MembersErrorCoderides onerr.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
dedupKeyis namespaced. Whatever key you pass is stored asplugin:<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 derivesplugin:<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). openPluginkeys are host-built. The key becomesplugin-open:<yourPluginId>:<dedupKey>; you cannot point the button at another plugin.- A Team Chat route tag must be your own plugin id.
chatRouteTagis 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: falseonly takes a card out of the inbox when it goes to Team Chat. It is honored only alongside a keptchatRouteTag, 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
.envfile 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
3xxanswer comes back to the plugin as is. Plugin-setHost,Content-Lengthand connection headers are dropped;sizeHeaderasks Omniscio to put the file's byte count in a header the site needs (Facebook'sfile_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).
Related
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