mirror of
https://github.com/stablyai/orca.git
synced 2026-11-19 04:23:57 +00:00
Plugins that track workspaces and terminals across Orca had to read the private runtime token or shell out to the CLI. Host API 1.7 gives them the same through consented methods: - workspace.readContext (and workspace.changed) carry `workspaceId`, the id workspace.list gives; workspace.created/removed and agent.status.changed add `workspaceListId` beside their existing raw `workspaceId`, which keeps its meaning. - workspace.list rows name their `projectId`; opt-in `includeStatus` joins each row's agent state, unread flag, live terminal count and last activity from worktree.ps. - project.list (workspace:read), terminal.list (workspace:read), terminal.focus (workspace:write, desktop only, steers only this window) and terminal.close (terminal:send, reports whether the process is known to have stopped). - Runtime refusals (unknown or ambiguous workspace, stale or exited terminal) reach plugins as fixed messages instead of runtime wording. - Consent copy for workspace:read, workspace:write and terminal:send says what they now allow; terminal.focus and terminal.close are audited by terminal id. - PLUGIN_SCHEMA_NEWEST_SINCE covers the editor typography and theme video floors it missed, and the provisional 1.7 floor, so development builds accept plugins requiring them.
153 lines
5.3 KiB
TypeScript
153 lines
5.3 KiB
TypeScript
import { getBoundPluginHostMethod, type PluginHostServices } from './plugin-host-method-bindings'
|
|
import { isQualifiedPluginKey } from '../../../../shared/plugins/manifest/plugin-manifest'
|
|
import { gatePluginHostCall as decidePluginHostCall } from '../../../../shared/plugins/capabilities/plugin-capability-gate'
|
|
import type { PluginCapabilityKind } from '../../../../shared/plugins/capabilities/plugin-capabilities'
|
|
import { isPluginJsonObject } from '../../../../shared/plugins/manifest/plugin-json-object'
|
|
import type {
|
|
PluginHostCallOutcome,
|
|
PluginSurface
|
|
} from '../../../../shared/plugins/frames/plugin-protocol'
|
|
import type { PluginAuditLog } from '../../plugin-audit-log'
|
|
import {
|
|
PluginHostCallError,
|
|
UNSCOPED_PLUGIN_HOST_CALL,
|
|
type PluginHostCallScope
|
|
} from './plugin-host-call-scope'
|
|
|
|
/**
|
|
* Host API 1 handler bindings — the one place plugin-originated calls
|
|
* (panel bridge, worker hostCall, serve RPC relay) execute. Handlers
|
|
* delegate to runtime services through the structural `PluginHostServices`
|
|
* interface, so this module stays electron-free and the relay conformance
|
|
* suite can run the identical chokepoint against a fake service set.
|
|
*/
|
|
|
|
export type ExecutePluginHostCallInput = {
|
|
/** Qualified plugin key, bound host-side from authenticated identity. */
|
|
pluginId: string
|
|
method: string
|
|
params: unknown
|
|
surface: PluginSurface
|
|
/** Consented capability kinds; null = unknown/disabled/consent-stale. */
|
|
grantedCapabilities: readonly PluginCapabilityKind[] | null
|
|
services: PluginHostServices | null
|
|
audit?: Pick<PluginAuditLog, 'record'>
|
|
/** Re-checked right before the side effect; absent only in tests and the relay suite. */
|
|
scope?: PluginHostCallScope
|
|
}
|
|
|
|
export async function executePluginHostCall(
|
|
input: ExecutePluginHostCallInput
|
|
): Promise<PluginHostCallOutcome> {
|
|
if (!isQualifiedPluginKey(input.pluginId)) {
|
|
return { ok: false, code: 'invalid_request', error: 'invalid qualified plugin key' }
|
|
}
|
|
const gate = decidePluginHostCall(
|
|
{ grantedCapabilities: input.grantedCapabilities, surface: input.surface },
|
|
input.method
|
|
)
|
|
if (!gate.granted) {
|
|
return { ok: false, code: gate.code, error: gate.error }
|
|
}
|
|
const bound = getBoundPluginHostMethod(input.method)
|
|
if (!bound) {
|
|
return { ok: false, code: 'unknown_method', error: `unknown host method: ${input.method}` }
|
|
}
|
|
const prepared = bound.prepare(input.params)
|
|
if (!prepared.ok) {
|
|
return { ok: false, code: 'invalid_params', error: prepared.issue }
|
|
}
|
|
const services = input.services
|
|
if (!services) {
|
|
return { ok: false, code: 'unavailable', error: 'runtime is not available' }
|
|
}
|
|
const auditMutation = async (outcome: 'attempt' | 'ok' | 'error'): Promise<void> => {
|
|
if (bound.spec.mutation && input.audit) {
|
|
await input.audit.record({
|
|
ts: Date.now(),
|
|
actor: `plugin:${input.pluginId}`,
|
|
method: input.method,
|
|
summary: summarizeParams(input.method, prepared.params),
|
|
outcome
|
|
})
|
|
}
|
|
}
|
|
if (bound.spec.mutation) {
|
|
if (!input.audit) {
|
|
return {
|
|
ok: false,
|
|
code: 'unavailable',
|
|
error: 'mutation audit log is not available'
|
|
}
|
|
}
|
|
try {
|
|
// Failed intent logging must prevent mutation.
|
|
await auditMutation('attempt')
|
|
} catch {
|
|
return {
|
|
ok: false,
|
|
code: 'action_failed',
|
|
error: 'mutation audit log could not be written'
|
|
}
|
|
}
|
|
}
|
|
const scope = input.scope ?? UNSCOPED_PLUGIN_HOST_CALL
|
|
try {
|
|
// The audit write awaited: approval may have been revoked meanwhile.
|
|
scope.assertActive()
|
|
const validated = await prepared.execute({ pluginId: input.pluginId, services, scope })
|
|
if (!validated) {
|
|
await auditMutation('error').catch(() => undefined)
|
|
// Malformed host results must not leak unvalidated shapes through any plugin transport.
|
|
return {
|
|
ok: false,
|
|
code: 'action_failed',
|
|
error: `internal: malformed ${input.method} result`
|
|
}
|
|
}
|
|
await auditMutation('ok').catch(() => undefined)
|
|
return { ok: true, value: validated.value }
|
|
} catch (error) {
|
|
await auditMutation('error').catch(() => undefined)
|
|
if (error instanceof PluginHostCallError) {
|
|
const { code, message, retryAfterMs } = error
|
|
return {
|
|
ok: false,
|
|
code,
|
|
error: message,
|
|
...(retryAfterMs === undefined ? {} : { retryAfterMs })
|
|
}
|
|
}
|
|
return {
|
|
ok: false,
|
|
code: 'action_failed',
|
|
error: error instanceof Error ? error.message : String(error)
|
|
}
|
|
}
|
|
}
|
|
|
|
function summarizeParams(method: string, params: unknown): string {
|
|
const record = isPluginJsonObject(params) ? params : {}
|
|
switch (method) {
|
|
case 'terminal.sendText': {
|
|
const text = typeof record.text === 'string' ? record.text : ''
|
|
return `terminal=${String(record.terminalId)} bytes=${Buffer.byteLength(text, 'utf8')} enter=${record.enter === true}`
|
|
}
|
|
case 'terminal.focus':
|
|
case 'terminal.close':
|
|
return `terminal=${String(record.terminalId)}`
|
|
case 'notifications.show': {
|
|
const title = typeof record.title === 'string' ? record.title : ''
|
|
return `titleChars=${title.length}`
|
|
}
|
|
case 'storage.set':
|
|
case 'storage.delete':
|
|
case 'secrets.set':
|
|
case 'secrets.delete':
|
|
case 'settings.set':
|
|
return `key=${String(record.key)}`
|
|
default:
|
|
return ''
|
|
}
|
|
}
|