Expose workflow-authoring tools through Android IPC

morten-olsen commented

2026-09-16 09:17:59 +02:00

Owner

Context

Authoring flows directly in the app is inefficient for complex automation. The engine already has workflow, trigger, action, event, registry, and execution seams that can support programmatic authoring, inspection, validation, and testing.

We need a transport-neutral authoring-tool surface so an agent or another authoring client can work with the engine without bypassing its validation, registry, or gateway boundaries. The long-term consumers may include an in-app agent using an OpenAI-compatible BYOK provider, Android IPC clients, an app-hosted HTTP server for desktop tooling, and MCP over streaming HTTP.

Scope

Implement the first useful vertical slice as option 2: Android IPC for an explicitly authorized external client. Keep the tool definitions and request/response model independent of this transport so the other options can reuse them.

Define a versioned, machine-readable authoring-tool contract with stable tool names, input schemas, result schemas, and actionable error states.
Provide read tools to list and describe workflows; list and describe installed trigger/event/action definitions and named sources; and retrieve the validation/runtime-relevant details an author needs to compose a flow.
Provide mutation tools to create, update, and delete workflow drafts through the existing workflow and registry seams. Mutations must run the same validation as the app UI and return diagnostics rather than partially applying invalid documents.
Provide testing tools that validate a workflow or individual node against supplied fixture inputs and report deterministic execution/validation results. Testing must not invoke live Android side effects, external intents, broadcasts, or production workflow execution.
Expose the contract through an Android IPC adapter. Verify the caller from platform-derived UID/package identity, require explicit user approval for a scoped authorization, and fail closed if identity or policy cannot be established.
Record observable authorization, validation, and execution failures without leaking workflow contents or secret values to an unauthorized caller.
Keep Android IPC as an adapter over shared modules; do not route binder/intent callbacks directly into workflows.

Non-goals

Do not add an OpenAI-compatible provider, API-key storage, or in-app chat UX in this issue.
Do not start an HTTP server or implement MCP/streaming HTTP in this issue.
Do not grant ambient workflow read/write/execute access to every installed app.
Do not expose a generic arbitrary-code or raw-database API.

Acceptance

A separately packaged, explicitly authorized Android client can discover available authoring tools and use the supported read tools to inspect the installed authoring surface.
That client can create or update a valid draft workflow, retrieve it, and receive structured diagnostics for an invalid update with no partial mutation.
That client can run the supported workflow and node test operations with fixtures; the results are deterministic and no live platform side effect is observed.
An unauthorized caller, a caller whose verified identity cannot be established, and a caller outside its approved scope are all rejected with distinct observable failure states and leave engine state unchanged.
The shared tool contract is covered by focused tests, while the IPC adapter has an Android integration scenario proving caller authorization and one successful end-to-end authoring operation.
The tool contract is transport-neutral enough for a later in-app agent, app-hosted HTTP server, or MCP adapter to invoke it without duplicating engine behavior.

## Context Authoring flows directly in the app is inefficient for complex automation. The engine already has workflow, trigger, action, event, registry, and execution seams that can support programmatic authoring, inspection, validation, and testing. We need a transport-neutral authoring-tool surface so an agent or another authoring client can work with the engine without bypassing its validation, registry, or gateway boundaries. The long-term consumers may include an in-app agent using an OpenAI-compatible BYOK provider, Android IPC clients, an app-hosted HTTP server for desktop tooling, and MCP over streaming HTTP. ## Scope Implement the first useful vertical slice as **option 2: Android IPC for an explicitly authorized external client**. Keep the tool definitions and request/response model independent of this transport so the other options can reuse them. - Define a versioned, machine-readable authoring-tool contract with stable tool names, input schemas, result schemas, and actionable error states. - Provide read tools to list and describe workflows; list and describe installed trigger/event/action definitions and named sources; and retrieve the validation/runtime-relevant details an author needs to compose a flow. - Provide mutation tools to create, update, and delete workflow drafts through the existing workflow and registry seams. Mutations must run the same validation as the app UI and return diagnostics rather than partially applying invalid documents. - Provide testing tools that validate a workflow or individual node against supplied fixture inputs and report deterministic execution/validation results. Testing must not invoke live Android side effects, external intents, broadcasts, or production workflow execution. - Expose the contract through an Android IPC adapter. Verify the caller from platform-derived UID/package identity, require explicit user approval for a scoped authorization, and fail closed if identity or policy cannot be established. - Record observable authorization, validation, and execution failures without leaking workflow contents or secret values to an unauthorized caller. - Keep Android IPC as an adapter over shared modules; do not route binder/intent callbacks directly into workflows. ## Non-goals - Do not add an OpenAI-compatible provider, API-key storage, or in-app chat UX in this issue. - Do not start an HTTP server or implement MCP/streaming HTTP in this issue. - Do not grant ambient workflow read/write/execute access to every installed app. - Do not expose a generic arbitrary-code or raw-database API. ## Acceptance - A separately packaged, explicitly authorized Android client can discover available authoring tools and use the supported read tools to inspect the installed authoring surface. - That client can create or update a valid draft workflow, retrieve it, and receive structured diagnostics for an invalid update with no partial mutation. - That client can run the supported workflow and node test operations with fixtures; the results are deterministic and no live platform side effect is observed. - An unauthorized caller, a caller whose verified identity cannot be established, and a caller outside its approved scope are all rejected with distinct observable failure states and leave engine state unchanged. - The shared tool contract is covered by focused tests, while the IPC adapter has an Android integration scenario proving caller authorization and one successful end-to-end authoring operation. - The tool contract is transport-neutral enough for a later in-app agent, app-hosted HTTP server, or MCP adapter to invoke it without duplicating engine behavior.

morten-olsen commented

2026-09-16 09:47:08 +02:00

Author

Owner

Tracking decision: keep the remaining surfaces in this issue for now. Once the Android IPC vertical slice has landed, create separate Forgejo tickets for (1) the in-app OpenAI-compatible BYOK agent, (3) the app-hosted HTTP authoring server, and (4) the streaming-HTTP MCP server. Each follow-on ticket must consume the shared transport-neutral authoring-tool contract rather than duplicate engine behavior.

morten-olsen commented

2026-09-16 11:59:31 +02:00

Author

Owner

Implemented and pushed in 82c983b.

Delivered:

versioned transport-neutral authoring tool contract for workflow, action, event, and named-source inspection;
shared typed WorkflowAuthoring module used by the app UI and tool adapter for atomic validated create/update/delete operations;
deterministic workflow and node fixture tests that never invoke live read, write, suspension, JavaScript, intent, broadcast, or production-run effects;
exported Messenger IPC adapter with Android UID/package/signing-certificate verification, explicit read/write/test approvals, scope expansion, bounded messages, and content-free audit history;
Settings → Authoring approval, revocation, and recent-access UI;
focused JVM contract tests and an on-device scenario using a separately packaged client UID.

Verification:

AuthoringToolModuleTest passed.
AuthoringIpcServiceTest passed on the Pixel 9 Android 16 emulator.
task ci:quality passed.

Implemented and pushed in 82c983b. Delivered: - versioned transport-neutral authoring tool contract for workflow, action, event, and named-source inspection; - shared typed WorkflowAuthoring module used by the app UI and tool adapter for atomic validated create/update/delete operations; - deterministic workflow and node fixture tests that never invoke live read, write, suspension, JavaScript, intent, broadcast, or production-run effects; - exported Messenger IPC adapter with Android UID/package/signing-certificate verification, explicit read/write/test approvals, scope expansion, bounded messages, and content-free audit history; - Settings → Authoring approval, revocation, and recent-access UI; - focused JVM contract tests and an on-device scenario using a separately packaged client UID. Verification: - AuthoringToolModuleTest passed. - AuthoringIpcServiceTest passed on the Pixel 9 Android 16 emulator. - task ci:quality passed.

morten-olsen closed this issue

2026-09-16 11:59:37 +02:00

morten-olsen referenced this issue

2026-09-16 12:05:36 +02:00

Add an in-app BYOK authoring agent #14

morten-olsen referenced this issue

2026-09-16 12:05:36 +02:00

Expose authoring tools through MCP Streamable HTTP #15

morten-olsen referenced this issue

2026-09-16 12:05:36 +02:00

Expose authoring tools through an app-hosted HTTP server #16

morten-olsen referenced this issue