diff --git a/pkg/cli/README.md b/pkg/cli/README.md index 9d9ae50143c..9c727f5e403 100644 --- a/pkg/cli/README.md +++ b/pkg/cli/README.md @@ -221,25 +221,45 @@ The `cli` package exports many types used across its command implementations. Th | `ActionlintStats` | struct | Static-analysis statistics from an actionlint run | | `AddInteractiveConfig` | struct | Configuration for the interactive `add-wizard` command | | `AgenticAssessment` | struct | Agentic behavior assessment derived from audit logs | +| `AmbientContextMetrics` | struct | Token metrics for ambient context (input, cached, effective token counts) | +| `Argument` | struct | A command-line argument definition from the MCP registry API | | `ArtifactSet` | string alias | Named set of artifacts (e.g. `"agent"`, `"detection"`) | +| `AuditComparisonClassification` | struct | A classification label and reason codes for an audit comparison | | `AuditComparisonData` | struct | Full comparison between two audit runs | | `AuditComparisonBaseline` | struct | Baseline metrics for an audit comparison | | `AuditComparisonDelta` | struct | Numeric delta between baseline and compare run | +| `AuditComparisonIntDelta` | struct | Integer-valued delta in an audit comparison | +| `AuditComparisonMCPFailureDelta` | struct | MCP failure count delta in an audit comparison | +| `AuditComparisonRecommendation` | struct | A recommendation produced by an audit comparison | +| `AuditComparisonStringDelta` | struct | String-valued delta in an audit comparison | | `AuditEngineConfig` | struct | Engine configuration captured in an audit run | | `AuditLogEntry` | struct | A structured entry from the agent audit log | | `AwContext` | struct | Agentic workflow context parsed from the run | | `AwInfo` | struct | Top-level `gh-aw` metadata block from an audit artifact | +| `AwInfoSteps` | struct | Step-level metadata in `aw_info.json` (e.g. firewall type) | +| `BashCommandsDiff` | struct | Per-command diff of bash tool calls between two audit runs | | `BehaviorFingerprint` | struct | Pattern fingerprint of agent behavior across turns | | `CheckState` | string alias | CI check state (`"success"`, `"failure"`, `"pending"`, ...) | | `CodemodResult` | struct | Result of a single codemod transformation | +| `CommandProvider` | interface | Interface implemented by Cobra root commands for shell-completion helpers | | `CompilationStats` | struct | Statistics from a compilation run (files, errors, warnings) | | `CompileValidationError` | struct | A validation error emitted during compilation | | `CombinedTrialResult` | struct | Combined results from multiple trial runs | | `ContinuationData` | struct | State for multi-turn agent continuations | | `CopilotCodingAgentDetector` | struct | Detector for Copilot coding-agent log patterns | +| `CopilotWorkflowStep` | struct | A single step from a Copilot setup-steps YAML file | +| `CreatedItemReport` | struct | Report of an item created by a safe-output action (type, URL, number, repo) | | `CrossRunSummary` | struct | Summary of cross-run metrics across multiple workflow runs | | `DependencyInfo` | struct | Metadata for a single dependency in `go.mod` or `package.json` | +| `DependencyInfoWithIndirect` | struct | `DependencyInfo` extended with an `Indirect` flag | +| `DevcontainerBuild` | struct | Build configuration section of `devcontainer.json` | +| `DevcontainerCodespaces` | struct | GitHub Codespaces-specific settings in `devcontainer.json` | | `DevcontainerConfig` | struct | Parsed `.devcontainer/devcontainer.json` configuration | +| `DevcontainerCustomizations` | struct | VSCode customizations block in `devcontainer.json` | +| `DevcontainerRepoPermissions` | struct | Repository permissions block in `devcontainer.json` | +| `DevcontainerVSCode` | struct | VSCode-specific settings block in `devcontainer.json` | +| `DifcFilteredEvent` | struct | A DIFC-filtered event from the MCP gateway log | +| `DockerUnavailableError` | struct | Error returned when the Docker daemon is not reachable | | `DomainAnalysis` | struct | Aggregated per-domain network request analysis | | `DomainBuckets` | struct | Domain requests bucketed by category (allow, deny, unknown) | | `DomainDiffEntry` | struct | Per-domain diff between two runs | @@ -251,15 +271,22 @@ The `cli` package exports many types used across its command implementations. Th | `FileInfo` | struct | File metadata captured during a workflow run | | `Finding` | struct | A finding from a security scanner (Zizmor/Poutine/Actionlint) | | `FirewallAnalysis` | struct | Analysis of AWF network firewall logs | +| `FirewallDiff` | struct | Diff of firewall domain access between two audit runs | +| `FirewallDiffSummary` | struct | Summary statistics for a firewall diff | | `FirewallLogEntry` | struct | A single entry from the AWF firewall log | | `GatewayLogEntry` | struct | A log entry from the MCP gateway proxy | | `GatewayMetrics` | struct | Aggregate metrics from MCP gateway logs | +| `GatewayServerMetrics` | struct | Per-server metrics from the MCP gateway | +| `GatewayToolMetrics` | struct | Per-tool metrics from the MCP gateway | +| `GitHubRateLimitDiff` | struct | Diff of GitHub API rate-limit consumption between two audit runs | | `GitHubRateLimitEntry` | struct | A GitHub API rate-limit snapshot from the agent run | | `GitHubWorkflow` | struct | Minimal GitHub Actions workflow metadata | +| `GuardPolicyEvent` | struct | A single guard-policy evaluation event from the MCP gateway log | | `GuardPolicySummary` | struct | Summary of guard-policy evaluations during a run | | `InitOptions` | struct | Options for `InitRepository` | | `JobData` | struct | Data for a single GitHub Actions job | | `JobInfo` | struct | Metadata for a GitHub Actions job | +| `JobInfoWithDuration` | struct | `JobInfo` extended with a human-readable duration string | | `ListWorkflowRunsOptions` | struct | Options for listing workflow runs | | `LockFileStatus` | struct | Status of a compiled `.lock.yml` file | | `LogsData` | struct | Full log data downloaded for a workflow run | @@ -270,43 +297,72 @@ The `cli` package exports many types used across its command implementations. Th | `MCPPackage` | struct | An npm/pip package entry used by an MCP server | | `MCPRegistryServerForProcessing` | struct | Server entry retrieved from the MCP registry | | `MCPServerHealth` | struct | Health metrics for a single MCP server | +| `MCPServerHealthDetail` | struct | Detailed health breakdown for a single MCP server | | `MCPSlowestToolCall` | struct | The slowest tool call recorded for an MCP server | | `MCPToolCall` | struct | A single MCP tool invocation from an agent turn | +| `MCPToolDiffEntry` | struct | Per-tool diff entry between two audit runs | | `MCPToolSummary` | struct | Aggregated MCP tool usage summary | | `MCPToolUsageData` | struct | Per-tool usage counts and latencies | +| `MCPToolUsageSummary` | struct | Aggregate MCP tool usage summary for a run | +| `MCPToolsDiff` | struct | Full diff of MCP tool calls between two audit runs | +| `MCPToolsDiffSummary` | struct | Summary statistics for an MCP tools diff | | `MetricsData` | struct | Core performance metrics for a workflow run | | `MetricsTrendData` | struct | Trend data for a metric across multiple runs | +| `MissingDataReport` | struct | Report of missing expected data in a run | +| `MissingDataSummary` | struct | Aggregated summary of missing-data reports | +| `MissingToolReport` | struct | Report of a missing MCP tool during a run | +| `MissingToolSummary` | struct | Aggregated summary of missing-tool reports | | `ModelTokenUsage` | struct | Token usage for a single AI model | +| `ModelTokenUsageRow` | struct | A single row in a model token usage table | | `NoopReport` | struct | Report for a noop safe-output event | | `ObservabilityInsight` | struct | An insight derived from observability data | | `OverviewData` | struct | High-level overview data for a workflow run | | `PRCheckRun` | struct | A single CI check run attached to a pull request | | `PRCommitStatus` | struct | A commit status context for a pull request | | `PRInfo` | struct | Pull-request metadata used by `gh aw pr` commands | +| `PerRunFirewallBreakdown` | struct | Per-run firewall domain breakdown in a cross-run report | | `PerformanceMetrics` | struct | Performance counters for a workflow run | | `PolicyAnalysis` | struct | Analysis of guard-policy evaluation results | | `PolicyManifest` | struct | A manifest of guard policies applied during a run | +| `PolicyRule` | struct | A single firewall policy rule from the policy manifest | +| `PolicySummaryDisplay` | struct | Display-friendly summary of policy evaluation results | +| `PollResult` | int alias | Result code returned by `PollWithSignalHandling` | | `ProcessedRun` | struct | A fully-processed workflow run with parsed artifacts | | `ProjectConfig` | struct | Configuration for `gh aw project new` | | `PromptAnalysis` | struct | Analysis of the prompt sent to the agent | +| `ProxyInfo` | struct | Proxy server configuration for network requests | +| `PullRequest` | struct | A GitHub pull request | | `RPCMessageEntry` | struct | A single RPC message from MCP gateway logs | | `Recommendation` | struct | An actionable recommendation derived from audit data | | `RedactedDomainsAnalysis` | struct | Analysis of redacted domain entries in firewall logs | +| `RedactedDomainsLogSummary` | struct | Summarised redacted-domain log data | | `Release` | struct | A GitHub release entry | | `Remote` | struct | A Git remote | | `RepoSpec` | struct | A parsed repository specifier (`owner/repo[@ref]`) | | `Repository` | struct | A GitHub repository | | `RuleHitStats` | struct | Statistics for a single AWF firewall rule | | `RunData` | struct | All data collected for a single workflow run | +| `RunMetricsDiff` | struct | Diff of core metrics between two audit runs | | `RunSummary` | struct | Summary of a workflow run | +| `SafeOutputChainMetrics` | struct | Metrics for safe-output action chains in a run | | `SafeOutputSummary` | struct | Summary of safe-output events in a run | +| `SafeOutputTypeDetail` | struct | Detailed information for a single safe-output type | | `SecretInfo` | struct | Metadata for a configured repository secret | | `SecretRequirement` | struct | A required secret for a workflow | +| `ServerDetail` | struct | Full details for a server from the MCP registry API | +| `ServerListResponse` | struct | Response envelope from the MCP registry `/v0.1/servers` endpoint | +| `ServerResponse` | struct | Response envelope wrapping server data and registry metadata | | `SessionAnalysis` | struct | Analysis of agent session metadata | | `ShellType` | string alias | Shell type detected by `DetectShell` (e.g. `"bash"`, `"zsh"`) | | `SourceSpec` | struct | A parsed workflow source specifier (local, remote, or registry) | +| `TaskDomainInfo` | struct | Domain information associated with a specific agent task | +| `TokenUsageDiff` | struct | Diff of token usage between two audit runs | | `TokenUsageEntry` | struct | Per-request token usage from the agent | | `TokenUsageSummary` | struct | Aggregated token usage for a workflow run | +| `ToolCallDiffEntry` | struct | Per-tool-call diff entry between two audit runs | +| `ToolCallInfo` | type alias | Alias for `workflow.ToolCallInfo` — a single tool call record | +| `ToolCallsDiff` | struct | Full diff of tool calls between two audit runs | +| `ToolCallsDiffSummary` | struct | Summary statistics for a tool calls diff | | `ToolTransition` | struct | A transition between tool calls in an agent episode | | `ToolUsageInfo` | struct | Usage information for a single tool | | `ToolUsageSummary` | struct | Aggregated tool usage statistics | @@ -316,6 +372,7 @@ The `cli` package exports many types used across its command implementations. Th | `TrialRepoContext` | struct | Repository context used during a trial run | | `VSCodeMCPServer` | struct | An MCP server entry in `.vscode/mcp.json` | | `VSCodeSettings` | struct | Parsed `.vscode/settings.json` | +| `ValidationResult` | struct | Result of a workflow compilation validation pass | | `Workflow` | struct | Minimal workflow metadata used in list operations | | `WorkflowDomainsDetail` | struct | Detailed per-workflow domain information | | `WorkflowDomainsSummary` | struct | Summary of domains used across workflows | @@ -326,6 +383,7 @@ The `cli` package exports many types used across its command implementations. Th | `WorkflowMCPMetadata` | struct | MCP server metadata scanned from a workflow file | | `WorkflowNode` | struct | A node in the workflow dependency graph | | `WorkflowOption` | struct | A selectable workflow option for interactive prompts | +| `WorkflowRun` | struct | A GitHub Actions workflow run record | | `WorkflowRunInfo` | struct | Summary of a workflow run from the GitHub API | | `WorkflowSpec` | struct | A fully resolved workflow specification with source metadata | | `WorkflowStats` | struct | Aggregate statistics for a workflow | diff --git a/pkg/console/README.md b/pkg/console/README.md index 290f48fc08c..4fdcd3992db 100644 --- a/pkg/console/README.md +++ b/pkg/console/README.md @@ -91,6 +91,14 @@ gh aw compile workflow.md > log.txt # Spinner disabled The `ProgressBar` component provides a reusable progress bar with TTY detection and graceful fallback for non-TTY environments. +### Public API + +| Function / Method | Signature | Description | +|------------------|-----------|-------------| +| `NewProgressBar` | `func(total int64) *ProgressBar` | Creates a determinate progress bar for a known total byte count | +| `NewIndeterminateProgressBar` | `func() *ProgressBar` | Creates an indeterminate progress bar for operations of unknown size (WASM build only) | +| `(*ProgressBar).Update` | `func(current int64) string` | Updates progress and returns a formatted display string; in TTY mode renders a gradient bar, in non-TTY mode returns a text percentage | + ### Features - **Scaled gradient effect**: Smooth color transition from purple to cyan as progress advances diff --git a/pkg/parser/README.md b/pkg/parser/README.md index 69d7efea157..e5b1d9114be 100644 --- a/pkg/parser/README.md +++ b/pkg/parser/README.md @@ -36,6 +36,7 @@ The package is designed for use both in the main CLI binary and in WebAssembly c | `ScheduleParser` | struct | Converts natural-language schedules to cron expressions | | `DeprecatedField` | struct | A deprecated frontmatter field with migration guidance | | `FileReader` | func type | `func(filePath string) ([]byte, error)` — abstraction for file reading | +| `InlineSubAgent` | struct | A single inline sub-agent definition extracted via the `## agent: \`name\`` syntax | ### Functions @@ -148,6 +149,18 @@ The package is designed for use both in the main CLI binary and in WebAssembly c | `IsLabelOnlyEvent` | `func(eventValue any) bool` | Detects whether a trigger only activates on label events | | `IsNonConflictingCommandEvent` | `func(eventValue any) bool` | Detects whether a trigger is a non-conflicting slash command | +#### Inline Sub-Agent Processing + +Inline sub-agents are secondary agent definitions embedded in the same markdown file as the primary workflow, delimited by `## agent: \`name\`` level-2 headings. Each sub-agent may carry its own frontmatter block (only `description` and `model` are valid fields) plus a prompt body. + +| Function | Signature | Description | +|----------|-----------|-------------| +| `ExtractInlineSubAgents` | `func(markdown string) (mainMarkdown string, agents []InlineSubAgent, err error)` | Splits markdown into the main workflow section and any inline sub-agent definitions | +| `ValidateInlineSubAgentsFrontmatter` | `func(markdown string) []string` | Validates inline sub-agent frontmatter in a full workflow file (strips top-level frontmatter first); returns advisory warning strings | +| `ValidateInlineSubAgentsInBody` | `func(body string) []string` | Validates inline sub-agent frontmatter in an already-stripped markdown body | +| `GetEngineSubAgentDir` | `func(engineID string) string` | Returns the relative directory used for sub-agent files for a given engine (`claude` → `.claude/agents`, etc.) | +| `GetEngineSubAgentExt` | `func(engineID string) string` | Returns the file extension for sub-agent files for a given engine (`.md` for `claude`/`codex`/`gemini`, `.agent.md` otherwise) | + #### Virtual Filesystem and Workflow Update Helpers | Function | Signature | Description | diff --git a/pkg/workflow/README.md b/pkg/workflow/README.md index 5c2a17b4181..e3ef0bc779b 100644 --- a/pkg/workflow/README.md +++ b/pkg/workflow/README.md @@ -186,6 +186,58 @@ The package is intentionally large (~320 source files) because it encodes all Gi | `ParseFilterConfig` | `func(map[string]any) SafeOutputFilterConfig` | Parses a filter configuration block | | `SafeOutputsConfigFromKeys` | `func([]string) *SafeOutputsConfig` | Creates a config from a list of type keys | +### Sandbox Configuration + +The sandbox subsystem controls which agent firewall (AWF) or sandbox runtime is used during workflow execution. + +| Type | Kind | Description | +|------|------|-------------| +| `SandboxType` | string alias | Sandbox type identifier (`"awf"`, `"default"`) | +| `SandboxConfig` | struct | Top-level sandbox configuration; supports new `agent`/`mcp` fields and legacy `type`/`config` fields | +| `AgentSandboxConfig` | struct | Agent-side sandbox configuration (ID, version, command, mounts, memory, env) | +| `SandboxRuntimeConfig` | struct | Anthropic Sandbox Runtime (SRT) configuration (filesystem, network, violations) | +| `SRTNetworkConfig` | struct | Network configuration for SRT (allowed/blocked domains, Unix sockets) | +| `SRTFilesystemConfig` | struct | Filesystem configuration for SRT (denyRead, allowWrite, denyWrite) | + +#### Sandbox Constants + +| Name | Type | Description | +|------|------|-------------| +| `SandboxTypeAWF` | `SandboxType` | AWF sandbox type (`"awf"`) | +| `SandboxTypeDefault` | `SandboxType` | Alias for AWF for backward compatibility (`"default"`) | + +### MCP Scripts + +The MCP Scripts subsystem provides inline custom tool definitions (JavaScript, shell, Python, or Go) that are compiled into a local MCP server at workflow runtime. + +| Type | Kind | Description | +|------|------|-------------| +| `MCPScriptsConfig` | struct | Parsed `mcp-scripts:` block; holds transport mode and a map of tool configurations | +| `MCPScriptToolConfig` | struct | Configuration for a single MCP script tool (description, inputs, script/run/py/go, env, timeout) | +| `MCPScriptParam` | struct | An input parameter for a script tool (type, description, required, default) | +| `MCPScriptsToolJSON` | struct | Tool entry serialized to `tools.json` for the MCP server | +| `MCPScriptsConfigJSON` | struct | Top-level `tools.json` structure (serverName, version, logDir, tools list) | + +#### MCP Scripts Constants + +| Name | Type | Description | +|------|------|-------------| +| `MCPScriptsModeHTTP` | `string` | The only supported transport mode for MCP scripts (`"http"`) | +| `MCPScriptsDirectory` | `string` | Runtime directory where MCP scripts files are generated | + +#### MCP Scripts Functions + +| Function | Signature | Description | +|----------|-----------|-------------| +| `HasMCPScripts` | `func(*MCPScriptsConfig) bool` | Returns whether any MCP script tools are configured | +| `IsMCPScriptsEnabled` | `func(*MCPScriptsConfig) bool` | Returns whether MCP scripts are enabled (currently equivalent to `HasMCPScripts`) | +| `GenerateMCPScriptsToolsConfig` | `func(*MCPScriptsConfig) string` | Generates the `tools.json` configuration file content for the MCP scripts server | +| `GenerateMCPScriptsMCPServerScript` | `func(*MCPScriptsConfig) string` | Generates the HTTP entry-point script for the MCP scripts server | +| `GenerateMCPScriptJavaScriptToolScript` | `func(*MCPScriptToolConfig) string` | Generates the `.cjs` tool handler for a JavaScript `script:` tool | +| `GenerateMCPScriptShellToolScript` | `func(*MCPScriptToolConfig) string` | Generates the `.sh` tool handler for a `run:` shell tool | +| `GenerateMCPScriptPythonToolScript` | `func(*MCPScriptToolConfig) string` | Generates the `.py` tool handler for a `py:` Python tool | +| `GenerateMCPScriptGoToolScript` | `func(*MCPScriptToolConfig) string` | Generates the `.go` tool handler for a `go:` Go tool | + ### Network Permissions | Type | Kind | Description | @@ -330,6 +382,12 @@ The package is intentionally large (~320 source files) because it encodes all Gi | `IsRelease` | `func() bool` | Returns whether this is a release build | | `IsReleasedVersion` | `func(string) bool` | Checks whether a version string is a release | +### Workflow Header Generation + +| Function | Signature | Description | +|----------|-----------|-------------| +| `GenerateWorkflowHeader` | `func(sourceFile, generatedBy, customInstructions string) string` | Generates the standard ASCII-art + regeneration-instructions header comment for compiled lock files; `sourceFile` is the `.md` source path, `generatedBy` names the generator, and `customInstructions` is appended verbatim | + ### Validation Functions | Function | Signature | Description |