From 259e10fd31a1857b399627e50d6e7ddea183e225 Mon Sep 17 00:00:00 2001 From: Hillary Mutisya <150286414+hillary-mutisya@users.noreply.github.com> Date: Fri, 5 Jun 2026 10:53:15 -0700 Subject: [PATCH 1/2] Update documentation diagrams --- .../capture_persist_register_execute.svg | 48 +++++++++++ .../images/workflow_capture_run_repair.svg | 42 ++++++++++ .../images/workflow_types_architecture.svg | 84 +++++++++++++++++++ ts/docs/architecture/workflows.md | 61 +++++--------- 4 files changed, 193 insertions(+), 42 deletions(-) create mode 100644 ts/docs/architecture/images/capture_persist_register_execute.svg create mode 100644 ts/docs/architecture/images/workflow_capture_run_repair.svg create mode 100644 ts/docs/architecture/images/workflow_types_architecture.svg diff --git a/ts/docs/architecture/images/capture_persist_register_execute.svg b/ts/docs/architecture/images/capture_persist_register_execute.svg new file mode 100644 index 0000000000..c1b75ee8e4 --- /dev/null +++ b/ts/docs/architecture/images/capture_persist_register_execute.svg @@ -0,0 +1,48 @@ + +Capture–Persist–Register–Execute with feedback loop +Linear pipeline from Capture through Persist, Register, and Execute, with a Feedback node closing the loop back to Capture + + + + + + + + +Capture + + + + + + +Persist + + + + + + +Register + + + + + + +Execute + + + + + +Feedback + + + + + + + + + \ No newline at end of file diff --git a/ts/docs/architecture/images/workflow_capture_run_repair.svg b/ts/docs/architecture/images/workflow_capture_run_repair.svg new file mode 100644 index 0000000000..fa3f8ca679 --- /dev/null +++ b/ts/docs/architecture/images/workflow_capture_run_repair.svg @@ -0,0 +1,42 @@ + +Workflow lifecycle: capture, run, repair +Three-stage workflow process where captured flows are executed via grammar matching and repaired in place when failures occur, with repaired flows re-registered back to the capture stage + + + + + + + +Capture +Agent receives goal +Writes domain API code +Registers as action + + + + + + +Run +User utterance +↓ +Grammar matching +↓ +Execute flow + + + + + + +Repair +Agent re-writes flows +if they fail in future +invocation + + + +Repaired flow re-registered + + \ No newline at end of file diff --git a/ts/docs/architecture/images/workflow_types_architecture.svg b/ts/docs/architecture/images/workflow_types_architecture.svg new file mode 100644 index 0000000000..12bcb21bc8 --- /dev/null +++ b/ts/docs/architecture/images/workflow_types_architecture.svg @@ -0,0 +1,84 @@ + +Workflow types architecture +Five workflow types branching from a grammar matcher into PowerShell, WebFlow, TaskFlow, ExcelFlow, and extensible types, each with their sandbox environment + + +User request + + + + +Grammar matcher + + + + + + + + + + + + + +PowerShell +PS script + + + + +WebFlow +TypeScript + + + + +TaskFlow +TypeScript + + + + +ExcelFlow +TypeScript + + + + +... + + + + + + + + + +Constrained +PS runspace + + + + +Node.js +Function() ++ WebUtilsAPI + + + + +Node.js +Function() ++ TaskFlowScriptAPI + + + + +Node.js +Function() ++ OfficeJS + + + diff --git a/ts/docs/architecture/workflows.md b/ts/docs/architecture/workflows.md index 3f2ca879ab..865c140910 100644 --- a/ts/docs/architecture/workflows.md +++ b/ts/docs/architecture/workflows.md @@ -29,6 +29,8 @@ trade one-time LLM reasoning for unlimited fast reuse. ### Three-phase lifecycle +![lifecycle](./images/workflow_capture_run_repair.svg) + The user-facing model is simple: | Phase | What happens | @@ -62,40 +64,24 @@ See [Common lifecycle](#common-lifecycle) for implementation details | **Script host** | A sandboxed execution environment for scripts (PowerShell constrained runspace, Node.js `new Function()` sandbox). | | **Self-repair** | Fallback to LLM reasoning when a workflow execution fails, with context about the failure to guide correction. | -### Three workflow types +### Workflow types -``` - +-----------------+ - User Request ------->| Grammar Matcher | - +--------+--------+ - | - +------------------+------------------+ - | | | - +--------v-------+ +-------v--------+ +-------v--------+ - | PowerShell | | WebFlow | | TaskFlow | - | (PS Script) | | (TypeScript) | | (TypeScript) | - +--------+-------+ +-------+--------+ +-------+--------+ - | | | - +--------v-------+ +-------v--------+ +-------v--------+ - | Constrained | | Node.js | | Node.js | - | PS Runspace | | Function() | | Function() | - | | | sandbox | | + ScriptAPI | - +----------------+ +----------------+ +----------------+ -``` +![types](./images/workflow_types_architecture.svg) -| Aspect | PowerShell | WebFlow | TaskFlow | -| ------------- | --------------------------------------- | ------------------------------------------------- | -------------------------------------------------- | -| **Domain** | OS / filesystem / processes | Web page interaction | Cross-agent workflows | -| **Language** | PowerShell | TypeScript | TypeScript | -| **Sandbox** | Constrained runspace + cmdlet whitelist | Frozen API + blocked identifiers (server-side) | `new Function()` + frozen API + blocked globals | -| **Execution** | `scriptHost.ps1` via child process | `new Function()` in Node.js with frozen API proxy | `executeTaskFlowScript()` with `TaskFlowScriptAPI` | -| **Scope** | System-wide | Per-site or global | Any agent combination | -| **Platform** | Windows only | Any (browser required) | Any | +| Aspect | PowerShell | WebFlow | TaskFlow | ExcelFlow | ... | +| ------------- | --------------------------------------- | ------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------ | -------------- | +| **Domain** | OS / filesystem / processes | Web page interaction | Cross-agent workflows | Excel / spreadsheet automation | _User-defined_ | +| **Language** | PowerShell | TypeScript | TypeScript | TypeScript | — | +| **Sandbox** | Constrained runspace + cmdlet whitelist | Frozen API + blocked identifiers (server-side) | `new Function()` + frozen API + blocked globals | `new Function()` + OfficeJS bridge | — | +| **Execution** | `scriptHost.ps1` via child process | `new Function()` in Node.js with frozen API proxy | `executeTaskFlowScript()` with `TaskFlowScriptAPI` | `new Function()` in Node.js with OfficeJS bridge | — | +| **Scope** | System-wide | Per-site or global | Any agent combination | Per-workbook or global | — | +| **Platform** | Windows only | Any (browser required) | Any | Any (Excel required) | Any | +| | -> **Design trade-off — why three separate workflow types instead of one?** +> **Design trade-off — why separate workflow types instead of one?** > > We could have a single unified workflow format that handles all domains. -> We chose three types because: +> We chose separate types because: > > 1. **Sandbox requirements differ** — PowerShell needs OS-level isolation > (constrained runspace); browser scripts need DOM access prevention; @@ -105,25 +91,16 @@ See [Common lifecycle](#common-lifecycle) for implementation details > 3. **Execution substrates differ** — PowerShell runs in a child process; > WebFlows proxy to the browser; TaskFlows call the dispatcher. > -> The cost is three parallel implementations of storage, dynamic schema, -> and grammar generation. See [Design principles](#design-principles) for -> the full list of architectural invariants. +> We derive common building blocks to handle storage, dynamic schema, +> and grammar generation. --- ## Common lifecycle -All three workflow types share a five-phase lifecycle: +All workflow types share a five-phase lifecycle: -``` - +-----------+ +----------+ +----------+ +-----------+ - | Capture |---->| Persist |---->| Register |---->| Execute | - +-----------+ +----------+ +----------+ +-----------+ - ^ | - | +----------+ | - +--------------| Feedback |<-------------------------+ - +----------+ -``` +![types](./images/capture_persist_register_execute.svg) ### Phase 1 — Capture From be1868afa0e4e114ec27c840c5a76ee117cc520d Mon Sep 17 00:00:00 2001 From: Hillary Mutisya <150286414+hillary-mutisya@users.noreply.github.com> Date: Fri, 5 Jun 2026 11:00:06 -0700 Subject: [PATCH 2/2] Update workflows.md --- ts/docs/architecture/workflows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ts/docs/architecture/workflows.md b/ts/docs/architecture/workflows.md index 865c140910..a745d70fc6 100644 --- a/ts/docs/architecture/workflows.md +++ b/ts/docs/architecture/workflows.md @@ -76,7 +76,7 @@ See [Common lifecycle](#common-lifecycle) for implementation details | **Execution** | `scriptHost.ps1` via child process | `new Function()` in Node.js with frozen API proxy | `executeTaskFlowScript()` with `TaskFlowScriptAPI` | `new Function()` in Node.js with OfficeJS bridge | — | | **Scope** | System-wide | Per-site or global | Any agent combination | Per-workbook or global | — | | **Platform** | Windows only | Any (browser required) | Any | Any (Excel required) | Any | -| | +| | > **Design trade-off — why separate workflow types instead of one?** >