Workflow Execution Graph Orchestration

Workflow Engagement Baseline

Prioritize Workflow deployments over Plugin implementations when the operational objective is to codify repetitive tool chains into a reproducible execution graph, rather than exposing novel capability footprints.

Typical structural signals necessitating a Workflow:

• Iterative chronological navigation targeting identical DOM architectures.
• Aggregated parallel telemetry extraction (e.g., localStorage, cookies, network dumps, URL indexing).
• Standardized security state capture pipelines (Authorization extraction -> HAR export -> Audit trace generation).
• Rigid enforcement of execution order, concurrency constraints, and uniform parameter baselines within a shared declarative contract.

Standard Development Iteration Bus

1. Mount the Environment Topology

• Source Template: jshook_workflow_template
• Mount Main Process Pointer: export MCP_WORKFLOW_ROOTS=<path-to-cloned-jshook_workflow_template>
• PowerShell: $env:MCP_WORKFLOW_ROOTS = "<path-to-cloned-jshook_workflow_template>"

2. Pre-compilation Constraint Verification

pnpm install
pnpm run build
pnpm run check

Engineering Protocol: The project remains TS-first and keeps workflow.ts as the source entrypoint; repositories should not commit dist/workflow.js. During installation, however, the local build step is expected to produce dist/workflow.js, and the installer should persist that compiled file as the runtime entry to avoid importing TypeScript directly from node_modules.

3. Graph Identity Allocation

Mutate the core identifier fields prior to architectural design:

• workflowId (Use reverse-domain syntax if applicable)
• displayName
• description
• tags
• Configuration prefix matching (e.g., workflows.templateCapture.*)

Repository Constraints:

• workflow.ts must be maintained as the versionized source.
• dist/workflow.js remains an ephemeral artifact and must be appended to .gitignore.

4. DAG (Directed Acyclic Graph) Design Synthesis

Conceptualize nodes structurally prior to logic population:

• Identify critically sequential bottleneck stages.
• Isolate read-only telemetry probes safe for parallel execution mapping.
• Mandate explicit retry policies and timeout bounds on unstable nodes.
• Map conditional routing vectors (Branching).

Abstract Syntax Tree (AST) API Resolution

import type {
  WorkflowExecutionContext,
} from '@jshookmcp/extension-sdk/workflow';
import {
  defineWorkflow,
  toolStep,
  sequenceStep,
  parallelStep,
  branchStep,
} from '@jshookmcp/extension-sdk/workflow';

WorkflowContract Declaration Hierarchy

Static Identity Schema

• kind: 'workflow-contract'
• version: 1
• id
• displayName
• description
• tags
• timeoutMs
• defaultMaxConcurrency
• chainsWith (optional — successor workflow ids declared by this workflow)
• prerequisites (optional — workflow ids that should complete before this one)

Chain Composition Metadata

Reverse-engineering workflows form natural chains (frida hook → SSL pinning bypass → traffic decode). Declare them through the defineWorkflow builder:

• chainsWith(next: string[]): workflow ids that naturally follow this workflow after it completes (outgoing edges: declarer → successors).
• prerequisites(previous: string[]): workflow ids that should complete before this workflow runs.

export default defineWorkflow('workflow.ssl_bypass.v1', 'SSL Pinning Bypass', (w) =>
  w
    .description('Disable certificate pinning on a hooked runtime.')
    .prerequisites(['workflow.frida_hook.v1'])
    .chainsWith(['workflow.traffic_decode.v1'])
    .buildGraph(() =>
      sequenceStep('bypass', (s) =>
        s.tool('bypass', 'frida_bridge', { input: { action: 'template' } })),
    ),
);

The workflow_suggest tool recommends next steps from the client-supplied list of already-executed workflow ids ({ executed: string[] } — the server stays stateless):

• Candidates chained from an executed workflow rank first; the reason names the chain.
• Workflows with all prerequisites satisfied rank before those with missing ones; gaps are listed in missingPrerequisites.
• Already-executed workflows are never suggested; unknown ids are returned in unmatched.
• With no chain metadata declared anywhere, suggestions is honestly empty.

list_extension_workflows / list_extensions attach chainsWith / prerequisites on workflows that declare them.

build(ctx) Execution Pipeline

Mandatory closure returning a declarative DAG matrix. Procedural side-effects within the builder scope are strictly prohibited.

Node Factory APIs

toolStep(id, toolName, options?)

Instantiates an atomic MCP tool execution constraint.

Optional capability vectors:

• input
• retry
• timeoutMs

sequenceStep(id, config?)

Enforces strict synchronous chronological execution.

Applicable structural usage:

• Pre-flight setup proceeding critical page navigation.
• Sequential mutation operations dependent on preceding DOM side-effects.
• Deterministic teardown and state extraction phases.

parallelStep(id, config?)

Abstracts concurrent execution queues without deterministic ordering.

Applicable structural usage:

• Immutable read-only telemetry scraping.
• Firing isolated network metric probes.

Strict Limitation: Parallel projection is solely applicable when node executions do not inflict mutating side-effects upon a shared target context.

branchStep(id, predicateId, config?)

Deploys conditional logic routing gates.

Technical dependencies:

• predicateId strictly maps to an internal registered predicate string, prohibiting arbitrary string evaluation layers.
• Upon dual residency of predicateId and predicateFn, the programmatic predicateFn closure executes with highest priority.

Capabilities Provided by WorkflowExecutionContext

ctx.invokeTool(toolName, args)

Direct execution passthrough mapped to the MCP tool layer during node execution logic.

ctx.getConfig(path, fallback)

Injects configuration invariants retrieved from the upstream mapping tier.

ctx.emitSpan(...) / ctx.emitMetric(...)

Telemetric observation channels for distributed trace tracking and metric analysis.

Structural Concurrency Constraints

Safe Parallel Matrix (Non-Mutating)

• page_local_storage with action: 'get'
• page_cookies with action: 'get'
• network_get_requests
• page_list_frames
• console_get_logs

Strict Sequential Matrix (Mutating)

• Page Navigation constraints
• DOM Clicks and Key input simulations
• Any atomic operation capable of displacing internal process state or resulting in cascaded mutations.

Context Reentry Affirmation

Assert the lifecycle integrity via the service terminal sequence:

1. reload_extensions
2. list_extensions
3. list_extension_workflows
4. run_extension_workflow

Pre-execution compilation loop baseline:

pnpm run build

Prioritize transpiled .js footprints over .ts sources upon overlapping candidate declarations.

Conventional Transgressions

• Abstracting explicit novel capabilities via convoluted Workflows instead of utilizing Plugin extensions.
• Assigning parallel execution topology across nodes inflicting cross-mutation upon shared states.
• Evading structural safety mappings (Omission of Retry/Timeout definitions) on highly volatile nodes.
• Discrepancies in configuration prefix strings deteriorating the ctx.getConfig(...) retrieval channel.
• Disseminating localized compilation artifacts (dist/workflow.js) upstream.