QuickOps SDK

Overview

QuickOps SDK lets plugins access the current QuickOps capabilities that are hosted by the CoreApp runtime while the CoreBox entry is owned by the official touch-quickops plugin: capability summaries, running sessions, local system info, network/file diagnostics, and recent local Flow audit summaries. The target shape is to keep moving migratable business logic into the official touch-quickops plugin plus host capability boundaries.

Imports

Plugin Prelude scripts can use global quickOps / plugin.quickOps directly. Plugin renderer contexts can use useQuickOps(), or create the SDK explicitly when a channel is already available.

import { createQuickOpsSDK, useQuickOps } from '@talex-touch/utils/plugin/sdk'

// index.js / Prelude global context
const capabilitiesFromPrelude = await quickOps.capabilities()

// Plugin renderer context
const quickOps = useQuickOps()
const capabilities = await quickOps.capabilities()

// When a plugin channel is already available
const quickOpsFromChannel = createQuickOpsSDK(channel)
const sessions = await quickOpsFromChannel.sessions()

Renderer / app code can use the transport domain SDK:

import { createQuickOpsSdk } from '@talex-touch/utils/transport/sdk/domains/quick-ops'
import { useTuffTransport } from '@talex-touch/utils/transport'

const quickOps = createQuickOpsSdk(useTuffTransport())
const sessions = await quickOps.sessions()

API Overview

Developer Preview

The QuickOps Developer CoreBox surface is owned by the official plugins/touch-quickops plugin. When the plugin recognizes commands such as json, url encode, base64 decode, jwt decode, regex test, markdown table, csv to markdown, markdown to csv, timestamp, date, timezone, uuid, short id, qr code, and case snake, it calls quickOps.developerPreview({ query }).

When developerPreview() returns ready, it includes a PreviewCardPayload, and the official plugin renders core-preview-card. Normal previews expose preview-copy-primary; QR previews add plugin-owned execute actions and call saveDeveloperPreview() for saving.

const result = await quickOps.developerPreview({
  query: {
    text: 'json {"ok":true}',
    inputs: []
  }
})

if (result.state === 'ready') {
  renderCorePreviewCard(result.payload)
}

saveDeveloperPreview() supports PreviewSDK QR SVG payloads only. The output directory is fixed to CoreApp app.getPath('temp')/tuff-quickops, and a successful save writes the file path to the clipboard. It is not a general file-write API.

const saved = await quickOps.saveDeveloperPreview({
  format: 'png',
  payload: result.payload
})

if (saved.state === 'saved') {
  console.info(saved.path)
}

The generic CoreApp PreviewProvider no longer registers the QuickOps Developer ability, reads clipboard fallback for Developer commands, or exposes QR save actions. Plugins must not fall back to private PreviewProvider APIs, raw IPC, or direct clipboard reads to bypass the allowDeveloperTools policy.

Files Input Routing

The official plugins/touch-quickops manifest declares acceptedInputTypes: ["text", "files"]. When a CoreBox query includes Files input, the plugin parses the JSON string array from query.inputs[].type === "files" and uses the first valid path as the default path for fileHash(), fileBase64(), or pathFormat(); an explicit path in the command text still wins.

CoreApp file search providers now only own indexing, file open, reveal, and generic path-copy actions. Path-copy actions use generic action ids: file-copy-path, file-copy-shell-path, file-copy-url, plus file-copy-windows-path / file-copy-wsl-path when platform path conversion is available; do not add new quick-ops-* file-search action ids. QuickOps Hash/Base64 result rendering and command routing must stay in the official plugin; do not add new QuickOps execute actions back to file search results or provider onExecute() branches.

Choose An Extension Path

First decide whether you are composing QuickOps or changing official QuickOps capabilities. Normal plugins should compose by default and leave the quickops.* namespace untouched.

Plugins must not register new quickops.* targets or call private QuickOps IPC. Plugin-owned capabilities should use their own feature ids / target ids and treat QuickOps results as context input.

Capability Matrix

const info = await quickOps.capabilities()

for (const entry of info.entries) {
  if (entry.status === 'disabled') {
    console.info(`${entry.id} disabled: ${entry.reason}`)
  }
}

Common disabled reasons:

Recent Audit Summary

auditRecent() returns recent local summaries for QuickOps Flow deliveries. It stores observable decisions only, not payload values.

const audit = await quickOps.auditRecent({ limit: 10 })

for (const entry of audit.entries) {
  console.log(entry.targetId, entry.decision, entry.reason, entry.payloadKeys)
}

Response fields:

The audit summary is cleared when the module is destroyed. It is not enterprise centralized audit or compliance retention.

Flow Extension Pattern

QuickOps built-in Flow targets are registered by CoreApp. If a plugin needs to compose with QuickOps, dispatch to existing targets through the Flow SDK instead of private IPC.

import { createFlowSDK } from '@talex-touch/utils/plugin/sdk'

const flow = createFlowSDK(channel, 'my-plugin-id')

const result = await flow.dispatch({
  type: 'json',
  data: {},
  context: {
    sourcePluginId: 'my-plugin-id'
  }
}, {
  preferredTarget: 'quickops.system-info',
  skipSelector: true,
  requireAck: true
})

if (result.state === 'blocked') {
  console.warn(result.reason)
}

QuickOps targets marked requireConfirm=true must receive a one-time confirmationToken from app UI before delivery and pass it in dispatch options, for example quickops.keep-awake, quickops.copy-to-clipboard, quickops.open-folder, and quickops.temp-text-file.

Flow Target Catalog

Public QuickOps targets use the quickops.<target> naming pattern. Targets are grouped into read-only, low-risk session control, and confirmation-required actions:

Plugins can use read-only target results as context for their own workflows. Confirmation-required targets must not run silently in the background, and old confirmationToken values must not be cached.

Third-Party Extension Patterns

Normal plugins should not mutate the built-in QuickOps runtime. Use these extension patterns instead:

Plugin-defined Ops can read the capability matrix first, then call Flow from their own UI, CoreBox result, or command handler:

import { createFlowSDK, useQuickOps } from '@talex-touch/utils/plugin/sdk'

const quickOps = useQuickOps()
const flow = createFlowSDK(channel, 'my-plugin-id')

async function runNetworkSummary() {
  const capabilities = await quickOps.capabilities()
  const hasNetwork = capabilities.entries.some((entry) =>
    entry.id.startsWith('quickops.network.') && entry.status !== 'disabled'
  )

  if (!hasNetwork) {
    return { state: 'blocked', reason: 'quickops-network-disabled' }
  }

  return flow.dispatch({ type: 'json', data: {} }, {
    preferredTarget: 'quickops.network-status',
    skipSelector: true,
    requireAck: true
  })
}

Plugin-Owned Ops Checklist

1. Declare the actual required permissions and reasons in the Manifest. Do not borrow QuickOps permissions.
2. Use the plugin's own namespace, such as a plugin feature id or custom Flow target.
3. Read capabilities() before execution and surface disabled policy, unsupported platform, and degraded reasons in your UI.
4. Reuse Permission / Flow confirmation when writing clipboard, writing files, opening folders, calling external services, or changing local state.
5. Return stable blocked / degraded reasons instead of fake success.
6. Log and audit target, decision, reason, payload keys, or lengths only; do not record sensitive payload values.

Changing Official QuickOps

Only repository maintainers should change official QuickOps capabilities. When adding or changing a common capability, prefer moving it into plugins/touch-quickops; Electron / OS-bound parts must remain behind CoreApp host capabilities.

The official plugin already owns the CoreBox root-result entry, expanded read-only panels, Developer preview, settings summary entry, and low-risk session-control triggers: capabilities, sessions, auditRecent, system info, Tuff diagnostics, disk space, directory usage, network status, local IP, port status, DNS query, file hash, file Base64, recent download, common directory, path format, format text, Developer preview, battery status, system proxy, quickops settings, plus stop-all-sessions and timer / Pomodoro / clean-screen / awake / stopwatch stop/pause/resume/lap/reset controls. Read-only panels fetch through the globalThis.quickOps transition facade; Developer preview calls developerPreview() through the CoreApp host facade and renders core-preview-card, while QR saves call saveDeveloperPreview() to write under the Tuff QuickOps temp directory; the settings summary reads current policy/defaults through capabilities and diagnostics without mutating CoreApp host policy; low-risk session controls dispatch through the injected Flow SDK to existing QuickOps Flow targets; file hash/Base64/path format support both text and files input routing. The plugin also owns the QuickOps Flow/AI source-level adapter contract: command routing emits redacted flowAdapterTrace, confirmation-required actions only show the App UI confirmationToken requirement, and high-risk requests such as kill port fail closed without a dispatch payload. The plugin must not execute high-risk actions or fall back to private IPC. Confirmation-required actions need a confirmationToken issued by App UI, so the plugin may only render the confirmation-required notice. CoreApp currently keeps the QuickOpsRuntimeHost / quickOpsRuntime host boundary, platform capabilities, Flow confirmation, policy/evidence gates, AppSetting schema / settings read path, and typed bridge. CoreApp no longer keeps a QuickOps natural-language resolver implementation, and the generic PreviewProvider, file search providers, plus CoreApp Tools settings no longer own QuickOps product surfaces. For the next migratable entries, extend this plugin's command routing and rendering path; writable settings require an official-plugin allowlisted host capability, and must not use private IPC to mutate settings. Do not reintroduce a CoreApp QuickOps CoreBox provider, Tools settings controls, generic PreviewProvider Developer surface, or file-search-specific QuickOps execute branch.

Keep these layers in sync:

Built-in capability checklist:

1. Classify the capability as read-only, low-risk session control, confirmation-required action, or high-risk action.
2. Read-only capabilities may enter the SDK facade; state-changing, file-writing, clipboard-writing, folder-opening, or external-network capabilities must prefer Flow targets and confirmation.
3. High-risk capabilities must not enter the plugin SDK by default. Add policy, permission, confirmation UI, audit, and real evidence first.
4. If the change touches settings surfaces, add a read-only summary in plugins/touch-quickops first. Writable settings need an official-plugin allowlisted host capability, permission reasons, and evidence before they can mutate AppSetting.quickOps; do not call private IPC.
5. Update focused tests for plugin command routing, runtime helpers, Flow delivery, policy fail-closed behavior, redacted ACK / audit, and typed transport surface.
6. Run quickops:surface:audit --strict to catch raw channels, SDK bypasses, or runtime facade drift.
7. Run quickops:flow-ai:audit --strict. It should prove the Flow target catalog, confirmation set, policy blocking, redacted ACK / audit, plugin-side Flow dispatch adapter / trace, and runtime dispatch bridge contracts; if a new capability does not update those source-level contracts, it should fail closed.
8. Document only capabilities backed by evidence. Missing packaged, cross-platform, visual, real AI UI orchestration, or confirmation UI evidence must stay marked as incomplete; do not treat Flow metadata, resolver/bridge focused tests, or mock artifacts as complete evidence.

Extension Guidance

1. Use capabilities() before showing an entry point.
2. Use sessions() for live status, but do not persist session ids as durable state.
3. Use auditRecent() for a local recent status panel, but do not upload it as enterprise audit.
4. Custom execution paths should declare Manifest permissions and reuse Permission / Flow confirmation.
5. File, network, clipboard, and system-state extensions must return explicit degraded / blocked reasons instead of fake success.

Related Documentation

• TuffTransport
• Flow SDK
• Permission SDK
• Tuff QuickOps User Guide