agentqit 0.1.0__tar.gz

agentqit-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Report incorrect runtime, CLI, or plugin integration behavior.
+body:
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Expected and actual behavior
+      description: Explain the problem and what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Include commands and synthetic configuration. Remove credentials and private records.
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: AgentQit version or commit, Python version, operating system, plugin version, and installation method.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Relevant output
+      description: Include the redacted JSON result or error, if available.

agentqit-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability privately
+    url: https://github.com/akimovWare/AgentQit/security/advisories/new
+    about: Use private reporting for vulnerabilities and sensitive reproduction details.

agentqit-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Propose a reusable capability or an integration improvement.
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: Describe the backend testing task and the current limitation.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: Explain how a human or agent would use the capability and observe its result.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives
+      description: Mention existing operations or plugin composition you have considered.

agentqit-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Change
+
+Describe the problem and the resulting behavior.
+
+## Validation
+
+List the relevant checks and their results. Explain any skipped checks.
+
+## Compatibility
+
+Describe changes to CLI arguments, JSON, configuration, plugin APIs, or packaged
+assets, if applicable. Link the updated documentation.

agentqit-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: Validate
+
+on:
+  push:
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  core:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, macos-15]
+        python: ["3.12", "3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.13.6"
+          python-version: ${{ matrix.python }}
+      - run: uv sync --frozen
+      - run: uv run python tools/check_public_content.py
+      - run: uv run ruff check src tests tools examples/orders/src
+      - run: uv run ruff format --check src tests tools examples/orders/src
+      - run: uv run pre-commit run --all-files
+      - run: uv run python tools/export_contracts.py --check
+      - run: uv run pytest
+      - run: uv build
+      - run: uv run python tools/verify_wheel.py dist
+      - run: uv run python tools/verify_archives.py dist
+      - run: uv run twine check --strict dist/*.whl dist/*.tar.gz
+      - run: uv venv .installed-check
+      - run: uv pip install --python .installed-check/bin/python dist/*.whl
+      - name: Verify isolated installation outside checkout
+        run: |
+          cd "$RUNNER_TEMP"
+          "$GITHUB_WORKSPACE/.installed-check/bin/python" -I "$GITHUB_WORKSPACE/tools/smoke_installed.py" --output "$RUNNER_TEMP/agentqit-smoke"
+
+  browser:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13", "3.14"]
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.13.6"
+          python-version: ${{ matrix.python }}
+      - run: uv sync --frozen --extra browser
+      - run: uv run playwright install --with-deps chromium --only-shell
+      - run: uv run pytest -m browser
+        env:
+          AGENTQIT_BROWSER_TESTS: "1"
+
+  context:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.13.6"
+          python-version: "3.12"
+      - run: uv sync --frozen
+      - run: uv run python tools/check_public_content.py
+      - name: Verify CLI/MCP workflows and catalog-size independence
+        run: uv run python tools/benchmark_interfaces.py --output .agentqit/context-review
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: interface-context-summary
+          path: .agentqit/context-review/summary.json
+          if-no-files-found: error
+
+
+  privacy:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.13.6"
+          python-version: "3.12"
+      - run: uv sync --frozen
+      - run: uv run python tools/check_public_content.py
+      - name: Install pinned secret scanner
+        run: go install github.com/zricethezav/gitleaks/v8@v8.30.1
+      - name: Scan reachable history without exposing matched values
+        run: '"$(go env GOPATH)/bin/gitleaks" git --redact --no-banner --log-opts="--all" .'

agentqit-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,98 @@
+name: Prepare release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Canonical package version (without v)
+        required: true
+        type: string
+      publish:
+        description: Publish verified artifacts (requires separate repository activation)
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+
+concurrency:
+  group: agentqit-release
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: validate
+    runs-on: ubuntu-24.04
+    env:
+      RELEASE_VERSION: ${{ inputs.version }}
+      PUBLISH_REQUESTED: ${{ inputs.publish }}
+      PUBLICATION_ENABLED: ${{ vars.AGENTQIT_PUBLISH_ENABLED }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          version: "0.13.6"
+          python-version: "3.12"
+      - run: uv sync --frozen
+      - run: uv build
+      - run: uv run python tools/verify_wheel.py dist
+      - run: uv run python tools/verify_archives.py dist
+      - run: uv run twine check --strict dist/*.whl dist/*.tar.gz
+      - name: Verify release identity and write checksums
+        shell: bash
+        run: |
+          flags=()
+          if [ "$PUBLISH_REQUESTED" = "true" ]; then
+            test "$PUBLICATION_ENABLED" = "true"
+            test "$GITHUB_REF" = "refs/tags/v$RELEASE_VERSION"
+            flags+=(--require-tag)
+          fi
+          uv run python tools/release_check.py dist --version "$RELEASE_VERSION" "${flags[@]}"
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: agentqit-release
+          path: dist/
+          if-no-files-found: error
+          retention-days: 14
+
+  publish:
+    if: inputs.publish && vars.AGENTQIT_PUBLISH_ENABLED == 'true'
+    needs: build
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+        with:
+          name: agentqit-release
+          path: release/
+      - name: Verify retained checksums and select distribution files
+        shell: python
+        run: |
+          import hashlib
+          import json
+          import pathlib
+          import shutil
+          source = pathlib.Path('release')
+          manifest = json.loads((source / 'release-manifest.json').read_text())
+          assert manifest['tag_verified'] is True
+          destination = pathlib.Path('dist')
+          destination.mkdir()
+          for name, details in manifest['files'].items():
+              assert pathlib.Path(name).name == name
+              assert name.endswith(('.whl', '.tar.gz'))
+              path = source / name
+              assert path.stat().st_size == details['bytes']
+              assert hashlib.sha256(path.read_bytes()).hexdigest() == details['sha256']
+              shutil.copyfile(path, destination / name)
+          assert len(list(destination.iterdir())) == 2
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+        with:
+          packages-dir: dist/

agentqit-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+.venv/
+.installed-check/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.uv-cache/
+.pre-commit-cache/
+.coverage
+coverage.*
+junit-*.xml
+htmlcov/
+dist/
+*.egg-info/
+.idea/
+.vscode/
+.DS_Store
+.codex/
+.qa-cli/
+.runs/
+.agentqit/
+playwright/.auth/
+.env
+.env.*
+!.env.example
+*.jks
+*.key
+
+# Local acceptance reports are retained for review, not published.
+/docs/products/*/reports/20*/

agentqit-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+minimum_pre_commit_version: "4.0.0"
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check
+        language: system
+        types_or: [python, pyi]
+      - id: ruff-format-check
+        name: ruff format check
+        entry: uv run ruff format --check
+        language: system
+        types_or: [python, pyi]

agentqit-0.1.0/AGENTS.md

@@ -0,0 +1,69 @@
+# Agent instructions
+
+## Project
+
+AgentQit provides application testing tools for AI agents. Read [the roadmap](docs/roadmap.md),
+[compatibility](docs/compatibility.md), and [the release guide](docs/releases.md) before changing code.
+Package publication requires an explicit maintainer instruction. Source changes
+use pull requests and the required CI checks.
+
+## Architecture
+
+- `qa_runtime` owns contracts, compilation, execution, ports, and adapters.
+- `qa_cli` owns argument parsing, configuration selection, and rendering.
+- Product plugins own their catalogs, topology, auth/TLS composition, and guides.
+- Core must not import CLI or product packages. CLI discovers products through
+  the `qa_runtime.products` entry point group.
+- Add ordinary operations in a workspace or plugin YAML catalog. Add Python only for
+  composition or a capability that existing handlers cannot express.
+- Keep `compile()` synchronous and free of network and credential access.
+  Execution and I/O ports are asynchronous; close resources with `aclose()`.
+- Browser support uses [explicit task sessions](docs/browser-runtime.md),
+  a browser port, and an adapter. Compilation does not launch or provision browsers.
+
+## Behavior and evidence
+
+- Requirements and canonical contracts define expectations. Service code helps
+  explain implementation; it does not establish the expected business result.
+- Return facts. Business assertions and verdicts belong to the caller.
+- Preserve the `CommandResult` envelope and documented exit codes. JSON stdout
+  contains exactly one document; diagnostics belong on stderr.
+- Do not introduce executable scenarios, arbitrary SQL/topic inputs, shell,
+  expression evaluation, or templates that execute code.
+- `admission` is discovery metadata; it is not a separate authorization gate.
+
+## Data and execution
+
+- Use synthetic examples, reserved `.invalid` hostnames, and fake ports in tests.
+- Keep system-specific contracts, source revisions, endpoints, records, and
+  credentials out of the reusable runtime and public examples.
+- Profiles contain nonsecret configuration and credential references only.
+  Secrets enter through `CredentialSource` and use the shared recursive redactor.
+- Keep TLS chain and hostname validation enabled.
+- Keep authenticated browser state out of Git. JSON redaction does not sanitize
+  screenshots or trace archives; handle those through scoped artifact policy.
+- Live execution requires a user task naming the target environment and scope.
+- Mutations require explicit user authorization, `--allow-mutation`, and exact
+  environment `qa`. MCP additionally requires operator-granted host capability;
+  a tool argument cannot grant it. Enforce admission before transport I/O.
+- After authorized QA, report created record IDs and effects. Keep those records
+  unless deletion was requested; restore temporary faults and locks.
+
+## Changes
+
+- Write public documentation and generated instructions in English.
+- Update behavior, focused tests, and affected guides together.
+- Normalize public errors through `RuntimeFailure` and the appropriate `ExitCode`.
+- Change dependencies in `pyproject.toml` through uv; never hand-edit `uv.lock`.
+- Start with focused tests, then run lint, format, and the full offline suite.
+  Packaging changes also require a build, archive inspection, and installation
+  checks outside the checkout.
+- Include relevant validation results and supported scope with each change.
+
+For a downstream plugin, follow [the integration workflow](docs/agent-integration.md).
+
+
+Browser-marked acceptance uses owned synthetic loopback fixtures and provisioned
+binaries. Run `AGENTQIT_BROWSER_TESTS=1 uv run pytest` after explicit browser setup.
+The standard suite runs without browser binaries. Supported platforms and test
+scope are documented in [verification](docs/verification.md).

agentqit-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0 - 2026-11-02
+
+- CPython 3.12, 3.13, and 3.14 support on macOS and Linux.
+- Product-neutral runtime and CLI with public dependency sources.
+- Local YAML workspaces and independently installed product plugins.
+- Local stdio MCP with bounded discovery, plans, observations, invocation, and checkpoints.
+- Interactive Playwright task sessions, scoped snapshot references, typed actions,
+  input masking, approved credential refs, screenshots, and private traces.
+- Shared UI/backend journals, expiry/session/operation limits, and uncertain-outcome handling.
+- Explicit environment credentials and standard Bearer/API-key header composition.
+- Synthetic Orders UI/API, a separate plugin distribution, and deliberate frontend fault acceptance.
+- Agent/contributor guides, CI, archive inspection, and isolated install checks.
+- Workspace-aware MCP discovery: backend task/evidence tools remain available;
+  browser-only tools appear only when browser capabilities are configured.
+- Installed-version commands, workspace schema export, frozen v1 consumer checks,
+  reviewed schema snapshots, and a documented compatibility/upgrade policy.
+- Reproducible CLI/MCP context accounting against synthetic local backend workflows.
+- Manual release preparation, source/tag/version checks, retained artifact hashes,
+  strict package metadata validation, and protected Trusted Publishing.

agentqit-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,16 @@
+# Community guidelines
+
+AgentQit welcomes respectful participation from people with different backgrounds
+and levels of experience.
+
+- Discuss ideas and technical evidence constructively.
+- Be patient with questions and acknowledge mistakes without personal attacks.
+- Do not harass, threaten, discriminate, or share another person's private information.
+- Keep issue and pull-request discussions relevant to the project.
+- Use synthetic data in examples and respect the security reporting policy.
+
+Maintainers may edit or remove disruptive content, close discussions, and restrict
+participation when necessary. Repeated or severe abuse can result in a permanent ban.
+
+Use GitHub's private reporting tools to report abusive content or account behavior.
+For a security vulnerability in AgentQit, follow [SECURITY.md](SECURITY.md).

agentqit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+Start with [the roadmap](docs/roadmap.md) and [architecture](docs/architecture.md).
+Please follow the [community guidelines](CODE_OF_CONDUCT.md).
+
+Keep changes small and explain the problem, resulting behavior, and validation.
+For a new operation, prefer a workspace or product YAML catalog. Change the runtime when a reusable
+capability is missing across systems.
+
+The development workflow is:
+
+```sh
+uv sync --frozen
+uv run ruff check src tests tools examples/orders/src
+uv run ruff format --check src tests tools examples/orders/src
+uv run pre-commit run --all-files
+uv run python tools/check_public_content.py
+uv run python tools/export_contracts.py --check
+uv run pytest
+uv build
+uv run python tools/verify_wheel.py dist
+uv run python tools/verify_archives.py dist
+uv run twine check --strict dist/*.whl dist/*.tar.gz
+```
+
+Tests use fake ports and owned synthetic fixtures. They must run without access
+to an application environment or real credentials.
+
+Public interface changes include the JSON envelope, exit codes, operation schema,
+plugin API, configuration aliases, and CLI arguments. Cover relevant boundaries
+and update their documentation in the same change.
+
+Packaging validation must inspect both wheel and source distribution, install
+from built artifacts outside the checkout, and exercise an independently built
+example plugin. Run focused tests first; repeat broader checks when changes or
+failures justify it.
+
+Write documentation, issue descriptions, and pull requests in English. Include
+only synthetic data in reproducible examples. Review [AGENTS.md](AGENTS.md) before
+using an agent to contribute.
+
+Native browser acceptance and clean-install validation are described in [verification](docs/verification.md).
+
+Read [compatibility](docs/compatibility.md) before changing a public contract and
+[the release guide](docs/releases.md) before preparing a version. Publication is
+disabled by default and requires a separate owner instruction.
+
+Before sharing changes, review the full diff and selected history for identifying
+information and operational data. Publication checks flag developer-local paths,
+non-example email addresses, unreviewed URL hosts, and operational files. Optional
+local denylists stay outside version control. Never add sensitive literals as test
+fixtures or scanner rules in this repository.

agentqit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentQit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentqit-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: agentqit
+Version: 0.1.0
+Summary: Application testing tools for AI agents
+Project-URL: Source, https://github.com/akimovWare/AgentQit
+Project-URL: Documentation, https://github.com/akimovWare/AgentQit/blob/main/README.md
+Project-URL: Issues, https://github.com/akimovWare/AgentQit/issues
+Project-URL: Changelog, https://github.com/akimovWare/AgentQit/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.12
+Requires-Dist: aiokafka<1,>=0.12
+Requires-Dist: anyio<5,>=4.8
+Requires-Dist: asyncpg<1,>=0.30
+Requires-Dist: botocore<2,>=1.42
+Requires-Dist: defusedxml<1,>=0.7
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: mcp<3,>=2
+Requires-Dist: protobuf<7,>=5
+Requires-Dist: pydantic-settings<3,>=2.7
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyjks<21,>=20
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: rich<15,>=13.9
+Requires-Dist: typer<1,>=0.15
+Provides-Extra: browser
+Requires-Dist: playwright<2,>=1.55; extra == 'browser'
+Description-Content-Type: text/markdown
+
+# AgentQit
+
+Application testing tools for AI agents.
+
+AgentQit exposes typed browser actions, reviewed backend operations, and observations
+with evidence. The agent selects checks from requirements and compares the returned
+facts with expected behavior. CLI and local stdio MCP share one execution runtime.
+
+CPython 3.12, 3.13, and 3.14; macOS and Linux.
+
+## Install
+
+With uv installed:
+
+```sh
+uv tool install --python 3.12 'agentqit[browser]>=0.1,<0.2'
+qa browser install --headless-only
+qa workspace init --directory ./my-qa --name sample
+```
+
+For backend-only use, omit `[browser]` and browser provisioning. Pin a reviewed
+version such as `==0.1.0` for a reproducible installation.
+
+Configure the workspace with reviewed operation YAML, your QA endpoints, and
+explicit credential references. Ordinary integrations use YAML; reusable catalogs
+and custom composition can use plugins.
+
+## Connect an agent
+
+Configure your MCP host to launch:
+
+```sh
+agentqit-mcp --workspace /absolute/path/to/my-qa
+```
+
+Interactive browser sessions use MCP. CLI also supports backend execution,
+discovery, planning, and diagnostics. Writes require operator authorization,
+caller opt-in, and `environment: qa`. Browser actions use scoped references;
+evidence artifacts remain local and private by default.
+
+## Update
+
+```sh
+uv tool upgrade agentqit
+```
+
+Updates follow the source and version constraints used at installation. Finish
+tasks and stop MCP before upgrading, then restart it. Re-provision browser binaries
+when Playwright changes. User YAML and credentials are separate from the application.
+
+## Guides
+
+- [Project overview](https://github.com/akimovWare/AgentQit)
+- [Workspace and authentication setup](https://github.com/akimovWare/AgentQit/blob/main/docs/workspaces.md)
+- [Agent integration](https://github.com/akimovWare/AgentQit/blob/main/docs/agent-integration.md)
+- [Browser sessions and evidence](https://github.com/akimovWare/AgentQit/blob/main/docs/browser-runtime.md)
+- [Installation and updates](https://github.com/akimovWare/AgentQit/blob/main/docs/distribution.md)
+- [Compatibility](https://github.com/akimovWare/AgentQit/blob/main/docs/compatibility.md)
+- [Security boundaries](https://github.com/akimovWare/AgentQit/blob/main/SECURITY.md)
+
+A completed operation is an execution fact. Business conclusions belong to the
+caller. Unknown write outcomes require state inspection before retrying.
+Plugins execute trusted code; this runtime is a local tool, not a shared remote service.
+
+[MIT license](https://github.com/akimovWare/AgentQit/blob/main/LICENSE).