@allurereport/plugin-agent 3.10.0 → 3.11.0

package/README.md

@@ -27,14 +27,13 @@ When enabled, the plugin writes:
 - `manifest/run.json`, `manifest/tests.jsonl`, and `manifest/findings.jsonl` for machine-readable review
 - copied run logs and other artifacts under `artifacts/`
 - `AGENTS.md` with guidance for consuming the directory
-- `manifest/expected.json` when `ALLURE_AGENT_EXPECTATIONS` is provided
-- `project/docs/allure-agent-mode.md` when the project has a guide at `docs/allure-agent-mode.md`
+- `manifest/expected.json` when inline flags, `--expectations <file>`, or plugin options provide expectations
 
 If no output directory is configured, the plugin does nothing.
 
 The plugin stays read-only by design. A separate harness layer can consume the
 generated manifests, plan enrichment work, and decide whether a rerun is ready to
-accept. See [the enrichment loop guide](../../docs/agent_enrichment_loop.md).
+accept.
 
 ## Verification Standard
 
@@ -42,19 +41,34 @@ accept. See [the enrichment loop guide](../../docs/agent_enrichment_loop.md).
 - Use `allure agent` for smoke checks too, even when the change is small or mechanical.
 - Only skip agent mode when it is impossible or when you are debugging agent mode itself.
 
-## Skills-First Workflow
+## CLI Capability Workflow
 
-The downstream workflow is intended to be skills-first:
+The installed CLI help is the local contract for agent mode. When an agent needs
+to choose supported commands or flags, detect the local CLI surface first:
 
-1. install the Allure skills bundle
-2. run the setup skill in a project
-3. let the setup skill create or update root `AGENTS.md`
-4. let the setup skill create `docs/allure-agent-mode.md`
-5. use Allure agent-mode in future test work through the project guide plus per-run manifests
+```shell
+allure --version
+allure agent capabilities --json
+allure agent --help
+allure agent query --help
+allure agent select --help
+allure agent latest --help
+allure agent state-dir --help
+```
 
-Every generated run includes an `AGENTS.md` playbook. When the project has
-`docs/allure-agent-mode.md`, the run output also copies that guide and tells agents
-to read it first.
+`allure agent capabilities --json` is the structured local contract for agents.
+`allure agent --help` includes the human-readable command task map. Each
+agent-mode command names the loop it supports, the problem signal that calls for
+it, and the task the agent should perform with it. For example, `allure agent
+latest` belongs to output recovery, `allure agent state-dir` belongs to tooling
+diagnosis, `allure agent query` belongs to output inspection,
+`allure agent select` belongs to rerun planning, and `--rerun-*` belongs to
+focused retry loops.
+
+Every generated run includes an `AGENTS.md` playbook with the same stable
+artifact-reading order, command task map, workflow guidance, and remediation
+rules. Reusable skills and common knowledge files should not hard-code
+version-specific flags; they should ask the local CLI when support is unclear.
 
 ## Install
 
@@ -90,30 +104,28 @@ The preferred CLI entrypoint is:
 npx allure agent -- npm test
 ```
 
-You can provide an explicit expectations file and output directory when you need deterministic paths:
+You can provide compact inline expectations for the common review path:
 
 ```shell
 npx allure agent \
-  --output ./out/agent-report \
-  --expectations ./out/agent-expected.yaml \
-  -- npm test
+	  --goal "Review feature A" \
+	  --expect-tests 3 \
+	  --expect-label feature=feature-a \
+	  --expect-step-containing "validate feature A" \
+	  --expect-steps 1 \
+	  -- npm test
 ```
 
-That command uses an agent-only profile by default, so configured presentation and export plugins such as Awesome, Dashboard, or TestOps are ignored for that run.
-
-You can also enable the plugin through lower-level environment variables when you need direct env control:
+Use an explicit expectations file and output directory when inline flags become awkward or you need deterministic paths:
 
 ```shell
-ALLURE_AGENT_OUTPUT=./out/agent-report npx allure run -- npm test
+npx allure agent \
+  --output ./out/agent-report \
+  --expectations ./out/agent-expected.yaml \
+  -- npm test
 ```
 
-To compare the run against an intended scope, provide an expectations file:
-
-```shell
-ALLURE_AGENT_OUTPUT=./out/agent-report \
-ALLURE_AGENT_EXPECTATIONS=./out/agent-expected.yaml \
-npx allure run -- npm test
-```
+That command uses an agent-only profile by default, so configured presentation and export plugins such as Awesome, Dashboard, or TestOps are ignored for that run.
 
 ## Options
 
@@ -121,19 +133,14 @@ The plugin accepts the following options:
 
 | Option | Description | Type | Default |
 |--------|-------------|------|---------|
-| `outputDir` | Directory where the markdown report will be written. Relative paths are resolved from the `allure` process working directory | `string` | `ALLURE_AGENT_OUTPUT` |
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `ALLURE_AGENT_OUTPUT` | Directory where the agent output should be written when `outputDir` is not set |
-| `ALLURE_AGENT_EXPECTATIONS` | Optional path to a YAML or JSON file describing expected and forbidden test scope |
-| `ALLURE_AGENT_COMMAND` | The executed command string recorded in `manifest/run.json` and `index.md` |
-| `ALLURE_AGENT_NAME` | Optional agent identifier recorded in `manifest/run.json` |
-| `ALLURE_AGENT_LOOP_ID` | Optional loop identifier recorded in `manifest/run.json` |
-| `ALLURE_AGENT_TASK_ID` | Optional task identifier recorded in `manifest/run.json` |
-| `ALLURE_AGENT_CONVERSATION_ID` | Optional conversation identifier recorded in `manifest/run.json` |
+| `outputDir` | Directory where the markdown report will be written. Relative paths are resolved from the `allure` process working directory | `string` | none |
+| `expectationsPath` | Path to a YAML or JSON file describing expected and forbidden test scope | `string` | none |
+| `expectations` | Inline expectations object. Use either `expectationsPath` or `expectations`, not both | `AgentExpectationsInput` | none |
+| `command` | Executed command string recorded in `manifest/run.json` and `index.md` | `string` | none |
+| `agentName` | Optional agent identifier recorded in `manifest/run.json` | `string` | none |
+| `loopId` | Optional loop identifier recorded in `manifest/run.json` | `string` | none |
+| `taskId` | Optional task identifier recorded in `manifest/run.json` | `string` | expectations task id |
+| `conversationId` | Optional conversation identifier recorded in `manifest/run.json` | `string` | none |
 
 ## Manifest Contract
 
@@ -148,8 +155,7 @@ The plugin emits a hybrid output:
   - `manifest/test-events.jsonl`
   - `manifest/tests.jsonl`
   - `manifest/findings.jsonl`
-  - `manifest/expected.json` when an expectations file is provided
-  - `project/docs/allure-agent-mode.md` when the project guide is available
+  - `manifest/expected.json` when expectations are provided
 
 `index.md` is the landing page for the run. It includes run identity, expected scope,
 advisory check summary, process logs, and grouped test links.
@@ -162,10 +168,20 @@ Each test markdown file includes:
 - retry history
 - advisory findings and rerun guidance when evidence is weak
 
+## Expectations
+
+The preferred `allure agent` workflow uses inline flags:
+
+- `--goal <text>` records the review intent.
+- `--expect-tests <count>` checks visible logical test count.
+- `--expect-label name=value`, `--expect-env <id>`, `--expect-test "<fullName>"`, and `--expect-prefix <prefix>` define expected scope. For a newly added test, use `--expect-test "<fullName>"` so a missing reported test becomes an explicit finding.
+- `--expect-step-containing <text>`, `--expect-steps <count>`, `--expect-attachments <count>`, and `--expect-attachment <name|name=value|content-type=value>` define evidence expectations per evidence-target logical test.
+
+The plugin normalizes inline expectations into `manifest/expected.json`.
+
 ## Expectations File
 
-When `ALLURE_AGENT_EXPECTATIONS` is set, the plugin accepts YAML or JSON, normalizes
-it into `manifest/expected.json`, and compares the run against it.
+When `--expectations <file>` or the plugin `expectationsPath` option is set, the plugin accepts YAML or JSON, normalizes it into `manifest/expected.json`, and compares the run against it.
 
 Expected top-level fields:
 
@@ -173,6 +189,7 @@ Expected top-level fields:
 goal: Validate feature A
 task_id: feature-a
 expected:
+  test_count: 3
   environments:
     - default
   full_names:
@@ -197,23 +214,27 @@ notes:
 Selectors are advisory. The plugin does not fail the run; it records findings in
 markdown and `manifest/findings.jsonl`.
 
-## Review Loop
+## Agent Workflow Pattern
 
-The intended usage pattern is:
+Use the smallest workflow that matches the task. For the common change-validation path:
 
-1. Run tests with `allure agent -- <command>`.
+1. Run tests with `allure agent --goal <text> --expect-test "<fullName>" --expect-label name=value --expect-step-containing <text> -- <command>`.
 2. Watch `manifest/run.json` and `manifest/test-events.jsonl` while the run is active.
 3. Review `index.md` plus the manifest files.
 4. If evidence is weak, add steps, attachments, labels, or parameters.
-5. Rerun the same scope with the same expectations file.
+5. Rerun the same scope with the same expectations.
 6. Accept the run or iterate based on advisory findings.
 
+When a prior agent run already captured failed tests, prefer
+`allure agent --rerun-latest --rerun-preset failed -- <command>` or
+`allure agent --rerun-from <output-dir> --rerun-preset failed -- <command>`
+instead of spending context reconstructing runner-specific test names.
+
 For small mechanical test changes, use a scoped agent-mode run for the smoke check
 too. Plain runner commands should be reserved for cases where agent mode is
 impossible or when you are debugging agent mode itself.
 
-For grouped coverage reviews, prefer one temp output directory and one expectations
-file per scope instead of trying to review a whole command matrix from a single run.
+For grouped coverage reviews, prefer one scoped expectation set per group instead of trying to review a whole command matrix from a single run.
 
 ## Test Enrichment Best Practices
 
@@ -246,25 +267,12 @@ When agent output does not fully model runner-visible failures:
 - treat the review as partial when suite-load, import, or setup failures are visible outside logical test files
 - keep console-only conclusions provisional until the missing modeling is understood
 
-## Project Guide
-
-Projects using the skills flow should keep a short root `AGENTS.md` and a deeper
-`docs/allure-agent-mode.md`.
-
-`AGENTS.md` should route all test-related work to the deeper guide. The deeper guide
-should explain:
-
-- the feature-delivery loop
-- the metadata-enrichment loop
-- per-run temp expectations and output paths
-- meaningful evidence rules
-- minimal metadata rules
-- future loops like flaky, known-issue, mute, and quality gates
-
 ## Copyable Agent Instructions
 
 The generated `AGENTS.md` already contains this guidance for each run. If you want
-the same policy in a project-level skill or agent prompt, you can start with:
+the same stable policy in a reusable skill or agent prompt, keep version-specific
+CLI details out of that reusable body and make agents inspect local CLI help when
+support is unclear:
 
 ```md
 ## Allure Agent Mode Instructions
@@ -273,15 +281,13 @@ the same policy in a project-level skill or agent prompt, you can start with:
 - Use `allure agent` for smoke checks too, even when the change is small or mechanical.
 - Only skip agent mode when it is impossible or when you are debugging agent mode itself.
 - After each agent-mode test run, print the `index.md` path from that run's output directory so users can open the run overview quickly.
-- Use `allure agent latest` to reopen the newest run when `--output` was omitted.
-- Use `allure agent state-dir` to inspect where the current project stores its latest-agent state.
-- Use `allure agent select --latest` or `allure agent select --from <output-dir>` to inspect the review-targeted test plan before rerunning.
-- Use `allure agent --rerun-latest -- <command>` or `allure agent --rerun-from <output-dir> -- <command>` to rerun only the selected tests.
-- Use `--rerun-preset review|failed|unsuccessful|all`, repeated `--rerun-environment <id>`, and repeated `--rerun-label name=value` when you need a narrower rerun selection from the previous output.
-- Use `ALLURE_AGENT_STATE_DIR` when you need to override where the current project stores latest-agent state for `latest`, `state-dir`, or `--rerun-latest`.
-- Use `ALLURE_AGENT_*` with `allure run` only as the lower-level fallback when you need direct environment control.
-- Generate or refresh `ALLURE_AGENT_EXPECTATIONS` before each targeted rerun.
-- Run tests with `ALLURE_AGENT_OUTPUT` and review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl`.
+- Use `allure --version`, `allure agent capabilities --json`, and `allure agent --help` before choosing flags when the local CLI surface is unknown.
+- Use `allure agent latest` to print the newest output directory and `index.md` path when `--output` was omitted.
+- Use `allure agent latest`, `state-dir`, `query`, `select`, and `--rerun-*` according to their loop/task/problem mapping instead of treating them as interchangeable helper commands.
+- Use `allure agent query --latest summary|tests|findings|test` or `allure agent query --from <output-dir> ...` to inspect prior output as focused JSON before manually opening raw manifests.
+- Use `allure agent select --from <output-dir> --output <file>` when you want the CLI to write the test plan and print a short summary with the file path, source output, preset, and selected count.
+- When rerunning previous failures, use `allure agent --rerun-latest --rerun-preset failed -- <command>` or `allure agent --rerun-from <output-dir> --rerun-preset failed -- <command>` instead of manually rebuilding runner-specific test names.
+- Run tests with `allure agent` and review `manifest/run.json`, `manifest/test-events.jsonl`, `index.md`, `manifest/tests.jsonl`, and `manifest/findings.jsonl`.
 - Enrich only the intended tests. Add real steps for real setup, actions, and assertions.
 - Attach only real runtime evidence such as payloads, responses, screenshots, DOM snapshots, diffs, logs, or traces.
 - Keep metadata minimal. Add labels or severity only when scope review, debugging, or quality policy uses them.
@@ -303,7 +309,7 @@ import {
 ```
 
 - `buildAgentExpectations(...)` converts a goal plus target/forbidden selectors into
-  the JSON shape expected by `ALLURE_AGENT_EXPECTATIONS`.
+  the expectations shape accepted by inline flags, expectations files, and the plugin expectations option.
 - `loadAgentOutput(...)` reads `manifest/run.json`, `manifest/tests.jsonl`, and
   `manifest/findings.jsonl`.
 - `planAgentEnrichmentReview(...)` maps `check_name` values to enrichment actions
@@ -325,5 +331,5 @@ The enrichment loop should add only real runtime evidence:
 Avoid dummy enrichment such as empty wrapper steps, placeholder `"passed"` text
 attachments, or labels that are never used downstream.
 
-For a fuller policy, remediation mapping, and JS/Vitest examples based on the
-existing sandbox tests, see [the enrichment loop guide](../../docs/agent_enrichment_loop.md).
+For remediation mapping and JS/Vitest examples based on the existing sandbox
+tests, inspect the package tests and generated run `AGENTS.md` guidance.

package/dist/capabilities.d.ts

@@ -0,0 +1,99 @@
+export declare const AGENT_CAPABILITIES_SCHEMA = "allure-agent-capabilities/v1";
+export declare const createAgentCapabilities: () => {
+    readonly schema: "allure-agent-capabilities/v1";
+    readonly commands: {
+        readonly help: {
+            readonly supported: true;
+            readonly usage: "allure --version; allure agent --help; allure agent capabilities";
+            readonly output: readonly ["human", "json"];
+        };
+        readonly run: {
+            readonly supported: true;
+            readonly usage: "allure agent [options] -- <command>";
+            readonly options: readonly ["--config", "--cwd", "--output", "--expectations", "--goal", "--task-id", "--expect-tests", "--expect-label", "--expect-env", "--expect-test", "--expect-prefix", "--expect-step-containing", "--forbid-label", "--expect-steps", "--expect-attachments", "--expect-attachment", "--environment", "--environment-name", "--silent", "--rerun-from", "--rerun-latest", "--rerun-preset", "--rerun-environment", "--rerun-label"];
+        };
+        readonly latest: {
+            readonly supported: true;
+            readonly usage: "allure agent latest [--cwd <dir>]";
+            readonly output: readonly ["agent output: <dir>", "agent index: <dir>/index.md"];
+        };
+        readonly stateDir: {
+            readonly supported: true;
+            readonly usage: "allure agent state-dir [--cwd <dir>]";
+            readonly environmentVariable: "ALLURE_AGENT_STATE_DIR";
+        };
+        readonly select: {
+            readonly supported: true;
+            readonly usage: "allure agent select (--latest | --from <output-dir>) [options]";
+            readonly presets: readonly ["review", "failed", "unsuccessful", "all"];
+            readonly filters: readonly ["environment", "label"];
+            readonly output: readonly ["stdout-testplan-json", "file-testplan-json", "file-summary"];
+        };
+        readonly query: {
+            readonly supported: true;
+            readonly usage: "allure agent query (--latest | --from <output-dir>) [summary|tests|findings|test] [options]";
+            readonly views: readonly ["summary", "tests", "findings", "test"];
+            readonly filters: readonly ["status", "environment", "label", "severity", "category", "check", "test"];
+            readonly output: readonly ["json"];
+        };
+        readonly rerun: {
+            readonly supported: true;
+            readonly usage: "allure agent (--rerun-latest | --rerun-from <output-dir>) [filters] -- <command>";
+            readonly presets: readonly ["review", "failed", "unsuccessful", "all"];
+            readonly filters: readonly ["environment", "label"];
+            readonly transport: "ALLURE_TESTPLAN_PATH";
+        };
+    };
+    readonly expectations: {
+        readonly inline: {
+            readonly supported: true;
+            readonly goal: true;
+            readonly taskId: true;
+            readonly expected: {
+                readonly testCount: true;
+                readonly labels: true;
+                readonly environments: true;
+                readonly fullNames: true;
+                readonly fullNamePrefixes: true;
+            };
+            readonly forbidden: {
+                readonly labels: true;
+                readonly environments: false;
+                readonly fullNames: false;
+                readonly fullNamePrefixes: false;
+            };
+            readonly evidence: {
+                readonly stepNameContains: true;
+                readonly minSteps: true;
+                readonly minAttachments: true;
+                readonly attachmentFilters: readonly ["name", "content-type"];
+            };
+        };
+        readonly file: {
+            readonly supported: true;
+            readonly formats: readonly ["yaml", "json"];
+        };
+    };
+    readonly output: {
+        readonly automaticTempDirectory: true;
+        readonly explicitOutputOption: "--output <dir>";
+        readonly schema: "allure-agent-output/v1";
+        readonly files: readonly ["index.md", "AGENTS.md", "manifest/run.json", "manifest/test-events.jsonl", "manifest/tests.jsonl", "manifest/findings.jsonl", "manifest/expected.json", "tests/<environment>/<slug>.md", "artifacts/global/"];
+    };
+    readonly unsupported: {
+        readonly discovery: true;
+        readonly configureIntegration: true;
+        readonly executionSignal: true;
+        readonly compare: true;
+        readonly flaky: true;
+        readonly duplicates: true;
+        readonly stale: true;
+        readonly suppressions: true;
+        readonly observe: true;
+        readonly interrupt: true;
+        readonly localAgentService: true;
+        readonly expectationControls: readonly ["--expect-evidence"];
+    };
+};
+export declare const AGENT_TASK_MAP_HELP = "Agent task map:\n  allure --version\n  allure agent --help\n  allure agent capabilities\n      Setup and capability detection. Use when the local CLI surface is unknown,\n      generated guidance may be stale, or an agent needs supported flags without\n      guessing.\n\n  allure agent --goal ... -- <command>\n      Run a test command with runtime evidence, scope expectations, and\n      agent-readable artifacts for review, debugging, smoke checks, or validation.\n\n  allure agent latest\n      Recover the newest agent output directory and index.md when --output was\n      omitted or a follow-up task needs the previous run.\n\n  allure agent state-dir\n      Show where project-scoped latest-run pointers are stored. Useful when\n      latest cannot find a run or CI/sandbox state looks wrong.\n\n  allure agent select --latest\n  allure agent select --from <output-dir>\n      Inspect/filter prior results and write an Allure test plan before rerun.\n\n  allure agent query --latest summary\n  allure agent query --from <output-dir> tests\n  allure agent query --from <output-dir> findings\n      Inspect prior agent output as focused JSON without manually loading raw\n      manifests. Use for summaries, filtered test lists, findings, or one test.\n\n  allure agent --rerun-latest -- <command>\n  allure agent --rerun-from <output-dir> -- <command>\n      Rerun the failed, unsuccessful, or selected tests from prior agent output\n      through Allure test plan support.\n\nEnvironment:\n  ALLURE_AGENT_STATE_DIR=<dir>\n      Override the project-scoped state directory. Useful in CI, sandboxes, or\n      multi-job setups that need a deterministic shared state location.\n";
+export declare const isAgentTaskMapHelpRequest: (args: string[]) => boolean;

package/dist/capabilities.js

@@ -0,0 +1,173 @@
+export const AGENT_CAPABILITIES_SCHEMA = "allure-agent-capabilities/v1";
+export const createAgentCapabilities = () => ({
+    schema: AGENT_CAPABILITIES_SCHEMA,
+    commands: {
+        help: {
+            supported: true,
+            usage: "allure --version; allure agent --help; allure agent capabilities",
+            output: ["human", "json"],
+        },
+        run: {
+            supported: true,
+            usage: "allure agent [options] -- <command>",
+            options: [
+                "--config",
+                "--cwd",
+                "--output",
+                "--expectations",
+                "--goal",
+                "--task-id",
+                "--expect-tests",
+                "--expect-label",
+                "--expect-env",
+                "--expect-test",
+                "--expect-prefix",
+                "--expect-step-containing",
+                "--forbid-label",
+                "--expect-steps",
+                "--expect-attachments",
+                "--expect-attachment",
+                "--environment",
+                "--environment-name",
+                "--silent",
+                "--rerun-from",
+                "--rerun-latest",
+                "--rerun-preset",
+                "--rerun-environment",
+                "--rerun-label",
+            ],
+        },
+        latest: {
+            supported: true,
+            usage: "allure agent latest [--cwd <dir>]",
+            output: ["agent output: <dir>", "agent index: <dir>/index.md"],
+        },
+        stateDir: {
+            supported: true,
+            usage: "allure agent state-dir [--cwd <dir>]",
+            environmentVariable: "ALLURE_AGENT_STATE_DIR",
+        },
+        select: {
+            supported: true,
+            usage: "allure agent select (--latest | --from <output-dir>) [options]",
+            presets: ["review", "failed", "unsuccessful", "all"],
+            filters: ["environment", "label"],
+            output: ["stdout-testplan-json", "file-testplan-json", "file-summary"],
+        },
+        query: {
+            supported: true,
+            usage: "allure agent query (--latest | --from <output-dir>) [summary|tests|findings|test] [options]",
+            views: ["summary", "tests", "findings", "test"],
+            filters: ["status", "environment", "label", "severity", "category", "check", "test"],
+            output: ["json"],
+        },
+        rerun: {
+            supported: true,
+            usage: "allure agent (--rerun-latest | --rerun-from <output-dir>) [filters] -- <command>",
+            presets: ["review", "failed", "unsuccessful", "all"],
+            filters: ["environment", "label"],
+            transport: "ALLURE_TESTPLAN_PATH",
+        },
+    },
+    expectations: {
+        inline: {
+            supported: true,
+            goal: true,
+            taskId: true,
+            expected: {
+                testCount: true,
+                labels: true,
+                environments: true,
+                fullNames: true,
+                fullNamePrefixes: true,
+            },
+            forbidden: {
+                labels: true,
+                environments: false,
+                fullNames: false,
+                fullNamePrefixes: false,
+            },
+            evidence: {
+                stepNameContains: true,
+                minSteps: true,
+                minAttachments: true,
+                attachmentFilters: ["name", "content-type"],
+            },
+        },
+        file: {
+            supported: true,
+            formats: ["yaml", "json"],
+        },
+    },
+    output: {
+        automaticTempDirectory: true,
+        explicitOutputOption: "--output <dir>",
+        schema: "allure-agent-output/v1",
+        files: [
+            "index.md",
+            "AGENTS.md",
+            "manifest/run.json",
+            "manifest/test-events.jsonl",
+            "manifest/tests.jsonl",
+            "manifest/findings.jsonl",
+            "manifest/expected.json",
+            "tests/<environment>/<slug>.md",
+            "artifacts/global/",
+        ],
+    },
+    unsupported: {
+        discovery: true,
+        configureIntegration: true,
+        executionSignal: true,
+        compare: true,
+        flaky: true,
+        duplicates: true,
+        stale: true,
+        suppressions: true,
+        observe: true,
+        interrupt: true,
+        localAgentService: true,
+        expectationControls: ["--expect-evidence"],
+    },
+});
+export const AGENT_TASK_MAP_HELP = `Agent task map:
+  allure --version
+  allure agent --help
+  allure agent capabilities
+      Setup and capability detection. Use when the local CLI surface is unknown,
+      generated guidance may be stale, or an agent needs supported flags without
+      guessing.
+
+  allure agent --goal ... -- <command>
+      Run a test command with runtime evidence, scope expectations, and
+      agent-readable artifacts for review, debugging, smoke checks, or validation.
+
+  allure agent latest
+      Recover the newest agent output directory and index.md when --output was
+      omitted or a follow-up task needs the previous run.
+
+  allure agent state-dir
+      Show where project-scoped latest-run pointers are stored. Useful when
+      latest cannot find a run or CI/sandbox state looks wrong.
+
+  allure agent select --latest
+  allure agent select --from <output-dir>
+      Inspect/filter prior results and write an Allure test plan before rerun.
+
+  allure agent query --latest summary
+  allure agent query --from <output-dir> tests
+  allure agent query --from <output-dir> findings
+      Inspect prior agent output as focused JSON without manually loading raw
+      manifests. Use for summaries, filtered test lists, findings, or one test.
+
+  allure agent --rerun-latest -- <command>
+  allure agent --rerun-from <output-dir> -- <command>
+      Rerun the failed, unsuccessful, or selected tests from prior agent output
+      through Allure test plan support.
+
+Environment:
+  ALLURE_AGENT_STATE_DIR=<dir>
+      Override the project-scoped state directory. Useful in CI, sandboxes, or
+      multi-job setups that need a deterministic shared state location.
+`;
+export const isAgentTaskMapHelpRequest = (args) => args.length === 2 && args[0] === "agent" && (args[1] === "--help" || args[1] === "-h");

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class AgentUsageError extends Error {
+    constructor(message: string);
+}
+export declare class AgentExpectationUsageError extends AgentUsageError {
+    readonly sourceOption?: string;
+    constructor(message: string, sourceOption?: string);
+}
+export declare const isAgentUsageError: (error: unknown) => error is AgentUsageError;
+export declare const isAgentExpectationUsageError: (error: unknown) => error is AgentExpectationUsageError;

package/dist/errors.js

@@ -0,0 +1,15 @@
+export class AgentUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AgentUsageError";
+    }
+}
+export class AgentExpectationUsageError extends AgentUsageError {
+    constructor(message, sourceOption) {
+        super(message);
+        this.name = "AgentExpectationUsageError";
+        this.sourceOption = sourceOption;
+    }
+}
+export const isAgentUsageError = (error) => error instanceof AgentUsageError;
+export const isAgentExpectationUsageError = (error) => error instanceof AgentExpectationUsageError;