From 70321dcd130332c6479420bf8a0a183e7aef6bc6 Mon Sep 17 00:00:00 2001 From: Copilot Date: Thu, 2 Apr 2026 06:52:20 +0000 Subject: [PATCH] docs: document --session-state-dir flag and AWF_SESSION_STATE_DIR env var Add the --session-state-dir CLI flag and AWF_SESSION_STATE_DIR environment variable to the documentation, introduced in #1593. - docs/usage.md: add --session-state-dir to the CLI options list (after --proxy-logs-dir), and expand the Agent Session State description to mention the flag's timeout-safe, predictable-path behaviour useful for GitHub Actions artifact uploads - docs/environment.md: add AWF_SESSION_STATE_DIR to the internal variables table and update the note to clarify it is user-configurable Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/environment.md | 3 ++- docs/usage.md | 8 +++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/environment.md b/docs/environment.md index aa9ccf90..8b939c8a 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -102,9 +102,10 @@ The following environment variables are set internally by the firewall and used | `AWF_DNS_SERVERS` | Comma-separated list of trusted DNS servers | `8.8.8.8,8.8.4.4` | | `AWF_CHROOT_ENABLED` | Whether chroot mode is enabled | `true` | | `AWF_HOST_PATH` | Host PATH passed to chroot environment | `/usr/local/bin:/usr/bin` | +| `AWF_SESSION_STATE_DIR` | Directory for Copilot CLI session state output (equivalent to `--session-state-dir`) | *(unset)* | | `NO_PROXY` | Domains bypassing Squid (host access mode) | `localhost,host.docker.internal` | -**Note:** These are set automatically based on CLI options and should not be overridden manually. +**Note:** Most of these are set automatically based on CLI options and should not be overridden manually. `AWF_SESSION_STATE_DIR` is an exception — it is the environment-variable equivalent of `--session-state-dir` and can be set by users to configure a predictable session-state output path. ## GitHub Actions `setup-*` Tool Availability diff --git a/docs/usage.md b/docs/usage.md index 4f17525c..28d20903 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -53,6 +53,9 @@ Options: allowed to these servers (default: 8.8.8.8,8.8.4.4) --proxy-logs-dir Directory to save Squid proxy logs to (writes access.log directly to this directory) + --session-state-dir Directory to save Copilot CLI session state (events.jsonl, session + data). Writes directly during execution (timeout-safe, predictable + path). Also configurable via AWF_SESSION_STATE_DIR env var. --enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false) @@ -847,9 +850,12 @@ sudo awf \ **Agent Session State:** - Contains structured conversation data written by Copilot CLI (e.g., `events.jsonl`) -- Location: `/tmp/awf-agent-session-state-/` +- Default location: `/tmp/awf-agent-session-state-/` - View with: `cat /tmp/awf-agent-session-state-/events.jsonl` - Useful for triage dashboards, benchmarking, and debugging Copilot CLI runs +- Use `--session-state-dir ` (or `AWF_SESSION_STATE_DIR`) to write session state to a + predictable path during execution — ideal for artifact upload in GitHub Actions where the + runner may time out before cleanup completes **Squid Logs:** - Contains all HTTP/HTTPS traffic (allowed and denied)