v0.3.3

Agentao 0.3.3

First release executing the Path A roadmap
(docs/design/path-a-roadmap.md). Pure-additive patch in the 0.3.x
series. Reduces friction for downstream projects that embed
agentao as a Python dependency. No required code change to
upgrade from 0.3.1.

Highlights

• PEP 561 py.typed marker. agentao/py.typed is now packaged
  in both wheel and sdist via
  [tool.hatch.build.targets.wheel].force-include. Downstream
  mypy / pyright consumers pick up Agentao's type hints
  instead of treating the package as untyped. Asserted in the CI
  smoke job so accidental removal from force-include fails
  loudly.

• README leads with embedding, not the CLI. A new
  ## Embed in 30 lines section sits at the top of README.md /
  README.zh.md with a runnable pure-injection snippet (no
  env-discovery, no implicit network, no global state). The
  previous CLI-install walkthrough is preserved verbatim under
  ## CLI Quickstart. This reflects the locked Path A positioning
  that agentao is primarily a library to embed in Python hosts.

• Embedded-construct CI smoke. .github/workflows/ci.yml smoke
  job now constructs the README snippet verbatim (no env, no
  network) using a tempdir for working_directory and a
  try/finally around agent.close(). Future regressions that
  make Agentao.__init__ open a connection or read process-wide
  env state will fail loudly on this step.

• Doc sync caused by the README pivot:

  • docs/EMBEDDING.md §8 migration title extended to 0.3.3; new
    "From 0.3.1" subsection notes the patch is Added-only.
  • docs/QUICKSTART.md re-titled "CLI — Quick Start Guide" with
    a top callout pointing embed users to EMBEDDING.md.
  • docs/README.md "Start Here" + "User Guides" surface
    EMBEDDING.md as the primary embed entrypoint (previously
    only ACP.md was listed).

Tests

2229 passed, 2 skipped on the post-release baseline (no
regressions from 0.3.1). No new test files in this release;
existing tests/test_imports.py and tests/test_harness_schema.py
continue to validate the public surface, and the new CI smoke
steps run on every wheel build.

Upgrade (from 0.3.1)

0.3.3 is strictly backwards-compatible. No required code
change. Existing calls into Agentao(...),
build_from_environment(...), capability protocols, and the
transport layer keep working unchanged.

pip install -U agentao

What's new for downstream type checkers (no opt-in needed; works
automatically once you upgrade):

mypy --strict your_host_app.py
# 'agentao' is now type-checked instead of skipped

SemVer note

0.3.3 is an Added-only patch — the 0.3.x series treats
additive public surfaces as patch-eligible during pre-1.0. There
are no removed fields, no renamed enum values, and no changed
semantics on existing surfaces.

Release Summary

• Version: 0.3.3
• Git tag: v0.3.3
• GitHub release type: regular release, not pre-release
• Publish workflow: .github/workflows/publish.yml

Roadmap reference

This release executes P0.1 + P0.2 + P0.3 of the Path A
roadmap. The next patch (0.3.4) is scheduled to land:

• P0.4 — public harness API mypy strict gate
• P0.5 — lazy imports across the package
• P0.6 — four embedding examples (FastAPI / pytest / Jupyter / Slack)
• P0.7 — embedded-contract regression tests
• P0.8 — JSONL audit sink for harness lifecycle events

0.4.0 will then ship the single planned break (P0.9 dependency
split into core + extras), well-prepared by the two prior
additive patches. Full per-item implementation plan in
docs/design/path-a-roadmap.md §9.

Full Changelog

See CHANGELOG.md for the 0.3.3 entry.