agent-surface 0.1.0__tar.gz

agent_surface-0.1.0/.github/AGENTS.md

@@ -0,0 +1,8 @@
+# GitHub automation instructions
+
+These instructions extend the repository-root `AGENTS.md` for `.github/`.
+
+- Pin actions to immutable commit SHAs and retain least-privilege permissions.
+- Keep CI aligned with the supported Python versions and the local `make check` gate.
+- Releases use GitHub OIDC Trusted Publishing for TestPyPI and PyPI; never store API tokens here.
+- Keep issue and pull-request templates concise, structured, and actionable.

agent_surface-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,40 @@
+name: Bug report
+description: Report reproducible incorrect behavior
+title: "bug: "
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Include the expected and actual structured result or error.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: Provide the smallest runnable code and command that demonstrates the problem.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: agent-surface version
+      placeholder: 0.1.0
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, operating system, and relevant adapter versions.
+      placeholder: Python 3.12.12, macOS 15
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Remove credentials and sensitive payload data.

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

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/allenday/agent-surface/security/advisories/new
+    about: Report security issues privately.

agent_surface-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Propose a focused contract or capability change
+title: "feat: "
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What agent or human workflow is difficult today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed contract
+      description: Show representative Python, CLI, YAML, MCP, or schema behavior.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Include trade-offs, output bounds, and compatibility concerns when relevant.

agent_surface-0.1.0/.github/dependabot.yml

@@ -0,0 +1,16 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        patterns: ["*"]

agent_surface-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- What contract or behavior changes, and why? -->
+
+## Tests
+
+- [ ] Added or updated tests for behavior changes
+- [ ] Observed new tests fail before implementation
+- [ ] Ran `make check`
+- [ ] Updated public and agent-facing documentation where needed
+
+## Compatibility
+
+<!-- Note schema, YAML, CLI, MCP, packaging, or migration impact. Write “None” if absent. -->

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

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          cache-suffix: ${{ matrix.python-version }}
+      - name: Install locked dependencies
+        run: uv sync --frozen --all-extras --dev
+      - name: Run tests
+        run: uv run pytest
+
+  quality:
+    name: Quality and distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+          cache-suffix: quality
+      - name: Install locked dependencies
+        run: uv sync --frozen --all-extras --dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run mypy src
+      - name: Build distributions
+        run: uv build
+      - name: Validate distribution metadata
+        run: uvx twine check dist/*
+      - name: Smoke-test the built wheel
+        run: |
+          python -m venv /tmp/agent-surface-wheel
+          /tmp/agent-surface-wheel/bin/pip install dist/*.whl
+          /tmp/agent-surface-wheel/bin/python -c "import agent_surface; import importlib.resources as r; assert r.files('agent_surface.skills').joinpath('agent-friendly-cli-design/SKILL.md').is_file()"

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

@@ -0,0 +1,86 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+      - name: Install locked dependencies
+        run: uv sync --frozen --all-extras --dev
+      - name: Verify release tag
+        if: github.event_name == 'release'
+        run: >-
+          python -c "import os, tomllib;
+          version = tomllib.load(open('pyproject.toml', 'rb'))['project']['version'];
+          actual = os.environ['GITHUB_REF_NAME']; expected = f'v{version}';
+          assert actual == expected, f'release tag {actual!r} must equal {expected!r}'"
+      - name: Run release gate and build distributions
+        run: make check
+      - name: Validate distribution metadata
+        run: uvx twine check dist/*
+      - name: Store distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/agent-surface
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-surface
+    permissions:
+      id-token: write
+    steps:
+      - name: Retrieve distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

agent_surface-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
+build/
+dist/
+*.egg-info/

agent_surface-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

agent_surface-0.1.0/AGENTS.md

@@ -0,0 +1,86 @@
+# AGENTS.md
+
+These instructions apply to the entire repository. User instructions take precedence.
+
+## Project
+
+`agent-surface` is a Python 3.12+ library that projects typed operations through CLI, MCP, and
+schema adapters. Pydantic models and the operation registry are the source of truth. Agent-facing
+responses are YAML-first, bounded, discoverable, and transport-neutral.
+
+The core product invariant is HATEOAS: every response should expose a small, relevant, executable
+`next_actions` frontier. Excellent human DX—runnable examples, linked explanations, normal help,
+and precise reference docs—must reinforce rather than weaken that agent contract.
+
+## Setup and checks
+
+Work from the repository root and use the project venv. Do not install dependencies globally.
+
+```bash
+uv sync --frozen --all-extras --dev
+make check
+```
+
+Useful focused commands:
+
+```bash
+uv run pytest tests/test_operations.py -v
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+`make check` is the completion gate: tests, Ruff, mypy, and distribution builds must all pass.
+
+## Repository map
+
+- `src/agent_surface/contracts.py`: stable transport-neutral envelopes and actions
+- `src/agent_surface/budgets.py`: item/byte limits and explicit bounded collections
+- `src/agent_surface/rendering.py`: deterministic adaptive YAML and JSON rendering
+- `src/agent_surface/references.py`: stable custom-object identity and display codecs
+- `src/agent_surface/actions.py`: candidate compilation, policy binding, and cursor discovery
+- `src/agent_surface/operations.py`: typed registration and invocation
+- `src/agent_surface/app.py`: public application/decorator API
+- `src/agent_surface/adapters/`: sibling transport projections; see its scoped `AGENTS.md`
+- `src/agent_surface/skills/`: bundled `SKILL.md`, `reference.md`, and future sidecars
+- `examples/`: executable consumer integrations and end-to-end trajectories
+- `tests/`: executable behavior and package-resource contracts; see scoped instructions
+- `docs/`: tutorials, concepts, how-to guides, references, and approved plans
+- `.github/`: CI, release, dependency, and contributor automation
+- `docs/adoption.md`: consumer domain/integration/transport boundary
+- `docs/plans/`: approved designs and implementation plans
+
+## Implementation rules
+
+- Use test-driven development for behavior changes: observe RED, implement minimally, then GREEN.
+- Keep public models strict and serializable. Preserve stable error codes and original argv
+  boundaries.
+- Keep YAML as the default structured representation. Flow style is preferred for small leaf
+  collections; never use ellipsis as an omission marker.
+- Renderers never fabricate pagination and never silently truncate. Domain or integration code
+  must supply a concrete continuation action before bounding a collection.
+- Treat `next_actions` as a bounded relevant frontier. Expose totals, truncation, and a concrete
+  discovery action instead of expanding high-branch-factor graphs.
+- Introspection is opt-in: decorated methods and Pydantic fields may produce candidates, but
+  explicit policy decides which actions are published.
+- Never evaluate properties or descriptors during candidate discovery. Publication is deny-by-default;
+  compilation alone never authorizes an action.
+- Never serialize an exhaustive action graph. Page concrete actions or expose one parameterized slot
+  source with an immediate continuation.
+- Never use `str(object)` as a stable reference. Use an explicit reference codec.
+- Keep Click and MCP adapters thin; business logic belongs in the shared operation layer.
+- Project CLI and MCP as siblings from the registry; never implement one transport through another.
+- Keep public examples executable and documentation links valid. When output appears in docs, verify
+  it against the real command rather than hand-maintaining a divergent shape.
+- Preserve bundled skill sidecars as package data. When they change, test both source access and
+  built-wheel contents.
+- Do not commit `.venv/`, `dist/`, caches, credentials, or generated artifacts.
+
+## Changes and releases
+
+Keep commits focused and include tests for behavior changes. Do not push, publish, or modify a
+release workflow unless the user explicitly requests it. Publishing uses GitHub OIDC Trusted
+Publishing; never add PyPI passwords or API tokens to repository files or workflow secrets.
+
+Before handing off, inspect the diff and working tree, run `make check`, and report any checks that
+could not run.

agent_surface-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing
+
+Focused issues and pull requests are welcome. For substantial changes, open an issue or discussion
+first so the operation contract and adapter boundaries can be agreed before implementation.
+
+## Development
+
+Install [uv](https://docs.astral.sh/uv/), clone the repository, and create the locked Python 3.12+
+environment:
+
+```bash
+uv sync --frozen --all-extras --dev
+make check
+```
+
+Write a failing test before changing behavior. Keep CLI and MCP adapters thin, preserve structured
+error codes, and follow the YAML and bounded-discovery rules in [AGENTS.md](AGENTS.md).
+
+## Pull requests
+
+- Keep unrelated changes separate.
+- Explain the user-visible contract change and its motivation.
+- Add or update tests and documentation together with the code.
+- Run `make check` and include any platform-specific limitations in the PR description.
+- Use a concise imperative commit message, such as `feat: add bounded action discovery`.
+
+By contributing, you agree that your contribution is licensed under the MIT License.

agent_surface-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allen Day
+
+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.

agent_surface-0.1.0/Makefile

@@ -0,0 +1,18 @@
+.PHONY: sync test lint typecheck build check
+
+sync:
+	uv sync --frozen --all-extras --dev
+
+test:
+	uv run pytest
+
+lint:
+	uv run ruff check .
+
+typecheck:
+	uv run mypy src
+
+build:
+	uv build
+
+check: test lint typecheck build