Merge branch 'main' into test

Author: kevinbackhouse

.devcontainer/post-attach.sh

@@ -7,8 +7,8 @@ if [ -v CODESPACES ]; then
     if [ ! -v AI_API_TOKEN ]; then
         echo "⚠️ Running in Codespaces - please add AI_API_TOKEN to your Codespaces secrets"
     fi
-    if [ ! -v GITHUB_PERSONAL_ACCESS_TOKEN ]; then
-        echo "⚠️ Running in Codespaces - please add GITHUB_PERSONAL_ACCESS_TOKEN to your Codespaces secrets"
+    if [ ! -v GH_TOKEN ]; then
+        echo "⚠️ Running in Codespaces - please add GH_TOKEN to your Codespaces secrets"
     fi
 fi
 

.github/workflows/ci.yml

@@ -35,8 +35,7 @@ jobs:
 
     - name: Run static analysis
       run: |
-        # hatch fmt --check
-        echo linter errors will be fixed in a separate PR
+        hatch fmt --linter --check
 
     - name: Run tests
       run: hatch test --python ${{ matrix.python-version }} --cover --randomize --parallel --retries 2 --retry-delay 1

.github/workflows/smoketest.yaml

@@ -14,14 +14,12 @@ permissions:
   statuses: read # Required for checking if all commit statuses are "success" in order to deploy the PR
 
 jobs:
-  permission-check:
+  Linux:
     runs-on: ubuntu-latest
     environment: smoketest
     if: github.event.issue.pull_request  # Make sure the comment is on a PR
-    outputs:
-      allowed: ${{ steps.branch-deploy.outputs.continue }}
     steps:
-      - name: branch-deploy
+      - name: Branch Deploy
         id: branch-deploy
         uses: github/branch-deploy@48285b12b35e47e2dde0c27d2abb33daa846d98b # v11.0.0
         with:
@@ -31,35 +29,30 @@ jobs:
           stable_branch: "main"
           update_branch: "disabled"
 
-  run-tests:
-    runs-on: ubuntu-latest
-    environment: smoketest
-    needs: permission-check
-    if: needs.permission-check.outputs.allowed == 'true'
-    steps:
       - name: Setup Python
+        if: steps.branch-deploy.outputs.continue == "true"
         uses: actions/setup-python@v5
         with:
           python-version: '3.11'
 
       - name: Checkout the repo
-        uses: actions/checkout@v5
-
-      - name: Checkout the PR
-        env:
-          PR_NUMBER: ${{ github.event.issue.number }}
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh pr checkout $PR_NUMBER
+        if: steps.branch-deploy.outputs.continue == "true"
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ steps.branch-deploy.outputs.sha }}
 
       - name: Setup Python venv
+        if: steps.branch-deploy.outputs.continue == "true"
         run: |
           python -m venv .venv
           source .venv/bin/activate
           python -m pip install hatch
 
       - name: Run tests
+        if: steps.branch-deploy.outputs.continue == "true"
         env:
+          MODEL_TEMP: ${{ vars.SMOKETEST_TEMPERATURE }}
+          AI_API_ENDPOINT: ${{ vars.SMOKETEST_ENDPOINT }}
           AI_API_TOKEN: ${{ secrets.AI_API_TOKEN }}
           GITHUB_AUTH_HEADER: "Bearer ${{ secrets.GITHUB_TOKEN }}"
 

CODEOWNERS

@@ -1,2 +1,2 @@
 # This repository is maintained by: 
-* @m-y-mo @p- @jarlob @kevinbackhouse @sylwia-budzynska @kwstubbs
+* @m-y-mo @p- @jarlob @kevinbackhouse @sylwia-budzynska @kwstubbs @anticomputer

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 GitHub
+Copyright GitHub, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

NOTICE

@@ -1,9 +1,9 @@
 Seclab Taskflow Agent
-Copyright 2025 GitHub
+Copyright GitHub, Inc.
 
 This product includes software developed at GitHub (https://github.com) released under the terms
 of the MIT license (https://github.com/GitHubSecurityLab/seclab-taskflow-agent/blob/main/LICENSE)
-Copyright (c) 2025 GitHub
+Copyright GitHub, Inc.
 
 The Initial Developer of some parts of the framework, which are copied from, derived from, or
 inspired by jsonrpyc (https://github.com/riga/jsonrpyc) under the terms of the BSD 3-clause

README.md

@@ -1,13 +1,11 @@
 Bogus change to test the updated smoketest.yml
 
-# Seclab Taskflow Agent
+# GitHub Security Lab Taskflow Agent
 
 The Security Lab Taskflow Agent is an MCP enabled multi-Agent framework.
 
 The Taskflow Agent is built on top of the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/).
 
-While the Taskflow Agent does not integrate into the GitHub Dotcom Copilot UX, it does operate using the Copilot API (CAPI) as its backend, similar to Copilot IDE extensions.
-
 ## Core Concepts
 
 The Taskflow Agent leverages a GitHub Workflow-esque YAML based grammar to perform a series of tasks using a set of Agents.
@@ -18,38 +16,48 @@ Agents are defined through [personalities](examples/personalities/), that receiv
 
 Agents can cooperate to complete sequences of tasks through so-called [taskflows](doc/GRAMMAR.md).
 
-You can find a detailed overview of the taskflow grammar [here](taskflows/GRAMMAR.md) and example taskflows [here](examples/taskflows/).
+You can find a detailed overview of the taskflow grammar [here](doc/GRAMMAR.md) and example taskflows [here](examples/taskflows/).
 
 ## Use Cases and Examples
 
 The Seclab Taskflow Agent framework was primarily designed to fit the iterative feedback loop driven work involved in Agentic security research workflows and vulnerability triage tasks.
 
 Its design philosophy is centered around the belief that a prompt level focus of capturing vulnerability patterns will greatly improve and scale security research results as frontier model capabilities evolve over time.
 
-While the maintainer himself primarily uses this framework as a code auditing tool it also serves as a more generic swiss army knife for exploring Agentic workflows. For example, the GitHub Security Lab also uses this framework for automated code scanning alert triage.
+At GitHub Security Lab, we primarily use this framework as a code auditing tool, but it can also serve as a more generic swiss army knife for exploring Agentic workflows. For example, we also use this framework for automated code scanning alert triage.
 
 The framework includes a [CodeQL](https://codeql.github.com/) MCP server that can be used for Agentic code review, see the [CVE-2023-2283](examples/taskflows/CVE-2023-2283.yaml) taskflow for an example of how to have an Agent review C code using a CodeQL database ([demo video](https://www.youtube.com/watch?v=eRSPSVW8RMo)).
 
 Instead of generating CodeQL queries itself, the CodeQL MCP Server is used to provide CodeQL-query based MCP tools that allow an Agent to navigate and explore code. It leverages templated CodeQL queries to provide targeted context for model driven code analysis.
 
 ## Requirements
 
-Python >= 3.9 or Docker
+Python >= 3.10 or Docker
 
 ## Configuration
 
-Provide a GitHub token for an account that is entitled to use [GitHub Models](https://models.github.ai) via the `AI_API_TOKEN` environment variable. Further configuration is use case dependent, i.e. pending which MCP servers you'd like to use in your taskflows.
+Provide a GitHub token for an account that is entitled to use [GitHub Models](https://models.github.ai) via the `AI_API_TOKEN` environment variable. Further configuration is use case dependent, i.e. pending which MCP servers you'd like to use in your taskflows. In a terminal, you can add `AI_API_TOKEN` to the environment like this:
+
+```sh
+export AI_API_TOKEN=<your_github_token>
+```
+
+Or, if you are using GitHub Codespaces, then you can [add a Codespace secret](https://github.com/settings/codespaces/secrets/new) so that `AI_API_TOKEN` is automatically available when working in a Codespace.
 
-You can set persisting environment variables via an `.env` file in the project root.
+Many of the MCP servers in the [seclab-taskflow](https://github.com/GitHubSecurityLab/seclab-taskflows) repo also need an environment variable named `GH_TOKEN` for accessing the GitHub API. You can use two separate PATs if you want, or you can use one PAT for both purposes, like this:
+
+```sh
+export GH_TOKEN=$AI_API_TOKEN
+```
+
+We do not recommend storing secrets on disk, but you can persist non-sensitive environment variables by adding a `.env` file in the project root.
 
 Example:
 
 ```sh
-# Tokens
-AI_API_TOKEN=<your_github_token>
 # MCP configs
-GITHUB_PERSONAL_ACCESS_TOKEN=<your_github_token>
 CODEQL_DBS_BASE_PATH="/app/my_data/codeql_databases"
+AI_API_ENDPOINT="https://models.github.ai/inference"
 ```
 
 ## Deploying from Source
@@ -168,15 +176,15 @@ Every YAML files used by the Seclab Taskflow Agent must include a header like th
 
 ```yaml
 seclab-taskflow-agent:
-  version: 1
+  version: "1.0"
   filetype: taskflow
 ```
 
-The `version` number in the header should always be 1. It means that the
+The `version` number in the header is currently 1. It means that the
 file uses version 1 of the seclab-taskflow-agent syntax. If we ever need
 to make a major change to the syntax, then we'll update the version number.
 This will hopefully enable us to make changes without breaking backwards
-compatibility.
+compatibility. Version can be specified as an integer, float, or string.
 
 The `filetype` determines whether the file defines a personality, toolbox, etc.
 This means that different types of files can be stored in the same directory.
@@ -288,10 +296,10 @@ server_params:
   url: https://api.githubcopilot.com/mcp/
   #See https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md
   headers:
-    Authorization: "{{ env GITHUB_AUTH_HEADER }}"
+    Authorization: "{{ env('GITHUB_AUTH_HEADER') }}"
   optional_headers:
-    X-MCP-Toolsets: "{{ env GITHUB_MCP_TOOLSETS }}"
-    X-MCP-Readonly: "{{ env GITHUB_MCP_READONLY }}"
+    X-MCP-Toolsets: "{{ env('GITHUB_MCP_TOOLSETS') }}"
+    X-MCP-Readonly: "{{ env('GITHUB_MCP_READONLY') }}"
 ```
 
 You can force certain tools within a `toolbox` to require user confirmation to run. This can be helpful if a tool may perform irreversible actions and should require user approval prior to its use. This is done by including the name of the tool (function) in the MCP server in the `confirm` section:
@@ -320,7 +328,7 @@ seclab-taskflow-agent:
 
 taskflow:
   - task:
-      # taskflows can optionally choose any of the support CAPI models for a task
+      # taskflows can optionally choose any of the models supported by your API for a task
       model: gpt-4.1
       # taskflows can optionally limit the max allowed number of Agent task loop
       # iterations to complete a task, this defaults to 50 when not provided
@@ -339,7 +347,7 @@ taskflow:
         Finally, why are apples and oranges healthy to eat?
 
       # taskflows can set temporary environment variables, these support the general
-      # "{{ env FROM_EXISTING_ENVIRONMENT }" pattern we use elsewhere as well
+      # "{{ env('FROM_EXISTING_ENVIRONMENT') }}" pattern we use elsewhere as well
       # these environment variables can then be made available to any stdio mcp server
       # through its respective yaml configuration, see memcache.yaml for an example
       # you can use these to override top-level environment variables on a per-task basis
@@ -386,7 +394,7 @@ taskflow:
 
 Taskflows support [Agent handoffs](https://openai.github.io/openai-agents-python/handoffs/). Handoffs are useful for implementing triage patterns where the primary Agent can decide to handoff a task to any subsequent Agents in the `Agents` list.
 
-See the [taskflow examples](taskflows/examples) for other useful Taskflow patterns such as repeatable and asynchronous templated prompts.
+See the [taskflow examples](examples/taskflows) for other useful Taskflow patterns such as repeatable and asynchronous templated prompts.
 
 
 You can run a taskflow from the command line like this:
@@ -486,12 +494,12 @@ Files of types `taskflow` and `toolbox` allow environment variables to be passed
 server_params:
   ...
   env:
-    CODEQL_DBS_BASE_PATH: "{{ env CODEQL_DBS_BASE_PATH }}"
+    CODEQL_DBS_BASE_PATH: "{{ env('CODEQL_DBS_BASE_PATH') }}"
     # prevent git repo operations on gh codeql executions
     GH_NO_UPDATE_NOTIFIER: "disable"
 ```
 
-For `toolbox`, `env` can be used inside `server_params`. A template of the form `{{ env ENV_VARIABLE_NAME }}` can be used to pass values of the environment variable from the current process to the MCP server. So in the above, the MCP server is run with `GH_NO_UPDATE_NOTIFIER=disable` and passes the value of `CODEQL_DBS_BASE_PATH` from the current process to the MCP server. The templated paramater `{{ env CODEQL_DBS_BASE_PATH }}` is replaced by the value of the environment variable `CODEQL_DBS_BASE_PATH` in the current process.
+For `toolbox`, `env` can be used inside `server_params`. A template of the form `{{ env('ENV_VARIABLE_NAME') }}` can be used to pass values of the environment variable from the current process to the MCP server. So in the above, the MCP server is run with `GH_NO_UPDATE_NOTIFIER=disable` and passes the value of `CODEQL_DBS_BASE_PATH` from the current process to the MCP server. The templated parameter `{{ env('CODEQL_DBS_BASE_PATH') }}` is replaced by the value of the environment variable `CODEQL_DBS_BASE_PATH` in the current process.
 
 Similarly, environment variables can be passed to a `task` in a `taskflow`:
 
@@ -508,9 +516,9 @@ taskflow:
         MEMCACHE_BACKEND: "dictionary_file"
 ```
 
-This overwrites the environment variables `MEMCACHE_STATE_DIR` and `MEMCACHE_BACKEND` for the task only. A template `{{ env ENV_VARIABLE_NAME }}` can also be used.
+This overwrites the environment variables `MEMCACHE_STATE_DIR` and `MEMCACHE_BACKEND` for the task only. A template `{{ env('ENV_VARIABLE_NAME') }}` can also be used.
 
-Note that when using the template `{{ env ENV_VARIABLE_NAME }}`, `ENV_VARIABLE_NAME` must be the name of an environment variable in the current process.
+Note that when using the template `{{ env('ENV_VARIABLE_NAME') }}`, `ENV_VARIABLE_NAME` must be the name of an environment variable in the current process.
 
 ## Import paths
 

doc/GRAMMAR.md

@@ -133,10 +133,10 @@ Often we may want to iterate through the same tasks with different inputs. For e
     agents:
       - seclab_taskflow_agent.personalities.c_auditer
     user_prompt: |
-      The function has name {{ RESULT_name }} and body {{ RESULT_body }} analyze the function.
+      The function has name {{ result.name }} and body {{ result.body }} analyze the function.
 ```
 
-In the above, the first task fetches functions in the code base and creates a json list object, with each entry having a `name` and `body` field. In the next task, `repeat_prompt` is set to true, meaning that a task is created for each individual object in the list and the object fields are referenced in the templated prompt using `{{ RESULT_<fieldname> }}`. In other words, `{{ RESULT_name }}` in the prompt is replaced with the value of the `name` field of the object etc. For example, if the list of functions fetched from the first task is:
+In the above, the first task fetches functions in the code base and creates a json list object, with each entry having a `name` and `body` field. In the next task, `repeat_prompt` is set to true, meaning that a task is created for each individual object in the list and the object fields are referenced in the templated prompt using `{{ result.fieldname }}`. In other words, `{{ result.name }}` in the prompt is replaced with the value of the `name` field of the object etc. For example, if the list of functions fetched from the first task is:
 
 ```javascript
 [{'name' : foo, 'body' : foo(){return 1;}}, {'name' : bar, 'body' : bar(a) {return a + 1;}}]
@@ -152,7 +152,7 @@ etc.
 
 Note that when using `repeat_prompt`, the last tool call result of the previous task is used as the iterable. It is recommended to keep the task that creates the iterable short and simple (e.g. just make one tool call to fetch a list of results) to avoid wrong results being passed to the repeat prompt.
 
-The iterable can also contain a list of primitives like string or number, in which case, the template `{{ RESULT }}` can be used in the `repeat_prompt` prompt to parse the results instead:
+The iterable can also contain a list of primitives like string or number, in which case, the template `{{ result }}` can be used in the `repeat_prompt` prompt to parse the results instead:
 
 ```yaml
   - task:
@@ -173,7 +173,7 @@ The iterable can also contain a list of primitives like string or number, in whi
       agents:
         - seclab_taskflow_agent.personalities.assistant
       user_prompt: |
-        What is the integer value of {{ RESULT }}?
+        What is the integer value of {{ result }}?
 ```
 
 Repeat prompt can be run in parallel by setting the `async` field to `true`:
@@ -185,7 +185,7 @@ Repeat prompt can be run in parallel by setting the `async` field to `true`:
     agents:
       - seclab_taskflow_agent.personalities.c_auditer
     user_prompt: |
-      The function has name {{ RESULT_name }} and body {{ RESULT_body }} analyze the function.
+      The function has name {{ result.name }} and body {{ result.body }} analyze the function.
 ```
 
 An optional limit can be set to limit the number of asynchronous tasks via `async_limit`. If not set, the default value (5) is used.
@@ -198,7 +198,7 @@ An optional limit can be set to limit the number of asynchronous tasks via `asyn
     agents:
       - seclab_taskflow_agent.personalities.c_auditer
     user_prompt: |
-      The function has name {{ RESULT_name }} and body {{ RESULT_body }} analyze the function.
+      The function has name {{ result.name }} and body {{ result.body }} analyze the function.
 ```
 
 Both `async` and `async_limit` have no effect when used outside of a `repeat_prompt`.
@@ -211,7 +211,7 @@ At the moment, we do not support nested `repeat_prompt`. So the following is not
     agents:
       - seclab_taskflow_agent.personalities.c_auditer
     user_prompt: |
-      The function has name {{ RESULT_name }} and body {{ RESULT_body }} analyze the function.
+      The function has name {{ result.name }} and body {{ result.body }} analyze the function.
   - task:
     repeat_prompt: true
     ...
@@ -233,7 +233,7 @@ For example:
       agents:
         - seclab_taskflow_agent.personalities.assistant
       user_prompt: |
-        What kind of fruit is {{ RESULT }}?
+        What kind of fruit is {{ result }}?
 ```
 
 The string `["apple", "banana", "orange"]` is then passed directly to the next task.
@@ -349,7 +349,7 @@ taskflow:
       agents:
         - examples.personalities.fruit_expert
       user_prompt: |
-        Tell me more about {{ GLOBALS_fruit }}.
+        Tell me more about {{ globals.fruit }}.
 ```
 
 Global variables can also be set or overridden from the command line using the `-g` or `--global` flag:
@@ -422,10 +422,10 @@ A reusable taskflow can also have a templated prompt that takes inputs from its
       agents:
         - examples.personalities.fruit_expert
       user_prompt: |
-        Tell me more about {{ INPUTS_fruit }}.
+        Tell me more about {{ inputs.fruit }}.
 ```
 
-In this case, the template parameter `{{ INPUTS_fruit }}` is replaced by the value of `fruit` from the `inputs` of the user, which is apples in this case:
+In this case, the template parameter `{{ inputs.fruit }}` is replaced by the value of `fruit` from the `inputs` of the user, which is apples in this case:
 
 ```yaml
   - task:
@@ -437,9 +437,9 @@ In this case, the template parameter `{{ INPUTS_fruit }}` is replaced by the val
 
 ### Reusable Prompts
 
-Reusable prompts are defined in files of `filetype` `prompts`. These are like macros that get replaced when a templated parameter of the form `{{ PROMPTS_<import-path> }}` is encountered.
+Reusable prompts are defined in files of `filetype` `prompts`. These are like macros that get included using Jinja2's `{% include %}` directive.
 
-Tasks can incorporate templated prompts which are then replaced by the actual prompt. For example:
+Tasks can incorporate reusable prompts using the include directive. For example:
 
 Example:
 
@@ -449,8 +449,8 @@ Example:
         - examples.personalities.fruit_expert
       user_prompt: |
         Tell me more about apples.
-        
-        {{ PROMPTS_examples.prompts.example_prompt }}
+
+        {% include 'examples.prompts.example_prompt' %}
 ```
 and `examples.prompts.example_prompt` is the following: