coding-agents 0.0.1.dev0__tar.gz

coding_agents-0.0.1.dev0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: coding-agents
+Version: 0.0.1.dev0
+Summary: The reference software engineering harness and runtime for autonomous coding agents.
+Author-email: Coding Agents Authors <authors@example.com>
+License: MIT
+Keywords: coding-agents,llm-agents,software-engineering,harness,autonomous-coding,swe-bench
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.20.0; extra == "llm"
+Requires-Dist: openai>=1.0.0; extra == "llm"
+
+# Coding Agents: Foundations, Architecture, Harnesses, and Enterprise Practice
+
+*Building, Orchestrating, Evaluating, and Scaling AI Software Engineers*
+
+A Peanutbook manuscript. Build it with `bubble-build`; read the source in
+`chapter*/`.
+
+---
+
+## What this book argues
+
+One claim, stated in Chapter 1 and earned over the following eleven:
+
+> **A coding agent is not a language model with a code prompt. It is a software
+> engineering system built around a model.**
+
+The question it answers is not whether AI can write code. That is settled, and
+settling it mattered less than everyone expected. The question is:
+
+> **How do we engineer software-development systems in which humans and coding
+> agents work together reliably on large production codebases?**
+
+Roughly seventy percent of the text is architecture, large-codebase practice,
+verification, evaluation, security, and multi-agent engineering. The other
+thirty percent uses specific systems as concrete implementations, because
+abstract discussion of agents is unfalsifiable and boring. That ratio is
+deliberate: the named products will be replaced, some of them before this is in
+print. The questions in the other seventy percent will not.
+
+---
+
+## Register
+
+The voice is already set by the first three chapters. Match it. These are
+descriptions of what the existing prose does, not aspirations.
+
+**Address the reader as "you." Never "we."** Across the written chapters: 89
+instances of *you*, one of *we*. The reader is an engineer doing this work, not
+a co-author being carried along.
+
+**First person singular is rationed, and only ever for first-hand experience.**
+Four instances in fifteen thousand words, all of the form *"in notes I wrote in
+March 2024."* Use it to introduce evidence you personally hold. Never for
+opinion — the argument should stand without the byline.
+
+**State the claim, then earn it.** The paragraph shape is: assertion,
+mechanism, consequence. Not: build-up, build-up, reveal.
+
+**Prefer the corrective construction.** *X is not Y. It is Z.* — "The context
+window is not storage. It is a working set." "File context is not repository
+context." This is the book's most characteristic sentence, because most of what
+it has to teach is a correction to a reasonable-sounding wrong model.
+
+**End on the consequence, not the hedge.** A sentence that trails off into
+*"...but of course this depends on your situation"* has wasted the reader's
+attention. If it depends, say what it depends on.
+
+**No hype vocabulary.** No *revolutionary*, *seamless*, *game-changing*,
+*paradigm shift*, *cutting-edge*. The existing chapters contain none. Enthusiasm
+is conveyed by precision, not adjectives.
+
+**Concrete over abstract, always.** A number with a date beats a
+characterization. A named failure beats "challenges." A worked example beats a
+principle.
+
+**Date every number, or state only the shape.** The field moves fast enough that
+an undated figure is worse than none, and a book that quotes a leaderboard
+without saying when looks careless within a year. Where a figure carries an
+argument, cite the paper and the date. Where only the trend matters, describe
+the trend.
+
+**Name few products, and never rank them.** A book that ranks models has a shelf
+life measured in months.
+
+**Say what did not work.** Anyone can write "here are the best practices." The
+material worth reading is *"we thought the bottleneck was X and it was Y."* The
+author's own failed work is the strongest evidence in the book; use it.
+
+**Admit uncertainty in the text, not in a hedge.** "This is model-specific and
+worth measuring on your own workload" is honest. "This may or may not apply" is
+noise.
+
+### Structural habits
+
+| Element | Convention |
+| :--- | :--- |
+| `>IMPORS:` box | One claim, stated once. About six per chapter. |
+| `>NOTES:` box | An aside the reader can skip. About two per chapter. |
+| Cross-references | Constant — roughly one per 230 words. Every chapter says which chapter takes a thread further. |
+| Figure captions | 20 words maximum, stating the claim. Longer explanation goes in the paragraph that introduces the figure. |
+| `<!-- -->` comments | Author notes, verification lists, publication gates. Dropped from the PDF. |
+| Chapter ending | A named handoff to the next chapter. |
+
+### Two things that are not register, but read like it
+
+**`>NOTES:` blocks print.** They are for the reader. Notes to yourself go in
+HTML comments, which pandoc drops.
+
+**Every chapter opens with a real, attributed epigraph.** Brooks (Ch 1), Parnas
+(Ch 2), Pike (Ch 3). Do not invent quotes, and do not attribute the book's own
+theses to anyone — those belong in `>IMPORS:` boxes.
+
+---
+
+## Shelf life
+
+The book is written for a **5–10 year spine and a 2–3 year surface**, and the
+two need to stay physically separable.
+
+What is being bet on lasting: the verification principle, context as a working
+set with an allocator, file context against repository context, benchmarks
+scoring a harness rather than a model, paired evaluation, the prefill/decode
+asymmetry, and the seven-component decomposition — which survives on Parnas's
+test, not on fashion, because each component is a decision that changes
+independently of the others.
+
+What will rot on schedule: model names, context sizes, prices, benchmark
+numbers, API shapes, and the current claim that frontier general models beat
+code-only models. All of it is real and all of it belongs in the book.
+
+This ships on KDP, where a revised interior is a re-upload rather than a print
+run, so the cost of carrying perishable material is low and the book can afford
+more of it than a traditionally published one. But **the thing that does not get
+revised is the reviews.** A one-star "already out of date" from the first
+edition sits on the same product page as the fourth, and no amount of iteration
+removes it. So perishable content is still quarantined into clearly dated
+sections — not to make revision cheap, but because a reader forgives datedness
+they were warned about and punishes datedness that presented itself as current.
+
+Handled that way the perishable sections invert from liability to asset: a
+section titled *The Frontier, as of <month year>* is a reason to buy the new
+edition. Put the edition and its date on the title page, and keep a short
+revision record in the back matter.
+
+The genuine risk is not that details age. It is that the **harness framing
+itself** gets absorbed — models that do multi-hour repository work with no
+scaffold would turn Part II into a historical chapter. The hedge is to write the
+harness chapters around *why* a harness exists — verification, budget, policy,
+accountability — rather than *how to build one*. Those four survive the
+absorption, because someone still has to verify the diff, pay for it, constrain
+it, and answer for it.
+
+The lifespan is therefore mostly decided by whether the book's own concepts get
+adopted: the Coding Agent Stack, the Evolution Ladder, the Agent-Ready
+Repository, Harness Engineering. A book that is cited for its framework outlives
+its examples. A book that only summarizes today's tools does not, however well
+written.
+
+---
+
+## Structure
+
+Four parts, twelve chapters, following one line of development:
+
+```text
+Static Agent -> Stateful -> Persistent -> Multi-Agent -> Self-Evolving
+```
+
+| # | Chapter | Words | State |
+| ---: | :--- | ---: | :--- |
+| | **Part I — Foundations** | | |
+| 1 | Code Language Models | 4,300 | drafted |
+| 2 | Anatomy of a Coding Agent | 6,200 | drafted |
+| 3 | Context and Repository Understanding | 4,100 | drafted |
+| | **Part II — The Agent Harness** | | |
+| 4 | Tools, Skills, and Agent Harnesses | 4,700 | drafted |
+| 5 | Planning and Spec-Driven Development | 4,600 | drafted |
+| 6 | Coding, Debugging, and Refactoring | 4,500 | drafted |
+| 7 | Verification and Repair | | outline |
+| | **Part III — Coding Agents in Production** | | |
+| 8 | Coding Agents at Scale | | outline |
+| 9 | Long-Running and Multi-Agent Systems | | outline |
+| 10 | Evaluation, Observability, and Economics | | outline |
+| 11 | Security and Enterprise Deployment | | outline |
+| | **Part IV — The Next Generation** | | |
+| 12 | Self-Evolving Coding Agents | | outline |
+
+Front matter is in `chapterx/` — the preface is outlined, not written, and it
+owns the author-credibility argument and the book-structure walkthrough.
+`chapter2/_draft-from-ch1.md` is the original Chapter 1, kept because its
+forty-line agent and enterprise retrospective still have somewhere to go.
+
+The concepts the book has to deliver, not merely name: the **Coding Agent
+Stack**, the **Agentic Software Engineering Loop**, the **Agent-Ready
+Repository** and its readiness score, **Harness Engineering**, and the **Coding
+Agent Evolution Ladder**.
+
+---
+
+## Building
+
+```bash
+conda activate usao
+
+bubble-convert 3              # one chapter, while drafting
+bubble-build --style square   # the whole book -> book_square.pdf
+bubble-single-star            # style lint
+```
+
+`bubble-convert` does **not** run figure scripts; only `bubble-build` does. When
+you change a figure while drafting, run it yourself first:
+
+```bash
+cd chapter3-*/img && python myfig.py && cd ../..
+```
+
+Check captions before building:
+
+```bash
+grep -rn '^!\[' chapter*/*.md | sed 's/^\(.*\):!\[\(.*\)\](.*/\1|\2/' \
+  | awk -F'|' '{n=split($2,a," "); if (n>20) printf "%d words: %s\n", n, $1}'
+```
+
+Figures are generated by Python scripts in each chapter's `img/`, never
+committed as hand-made images. The conventions are in
+`.claude/skills/peanutbook-figures/`; mindmaps need `mathicon`.
+
+---
+
+## Source material, and the gate on it
+
+`raw/` holds the author's Oracle talk and design notes from 2023–2024. Read
+`raw/README.md` before using any of it.
+
+The short version: the model rankings in those notes are dead, and the methods
+are not. The recitation probe, paired evaluation, and the generate–verify–repair
+loop all come from there and all still hold. Cite the papers with dates, never
+the slides. Abstract employer-internal specifics into general lessons, strip
+colleague names and email addresses, and confirm publication clearance.
+
+---
+
+## Before this ships
+
+- [ ] Preface written — it owns the author's position and the book's structure
+- [ ] Every date, benchmark size, and figure verified against its source
+- [ ] The frontier claims in Chapter 1 re-checked and stamped
+- [ ] `author` set in `peanut.config`; covers replaced
+- [ ] Every `@fig:` resolves, no caption over 20 words, `bubble-single-star` clean

coding_agents-0.0.1.dev0/README.md

@@ -0,0 +1,239 @@
+# Coding Agents: Foundations, Architecture, Harnesses, and Enterprise Practice
+
+*Building, Orchestrating, Evaluating, and Scaling AI Software Engineers*
+
+A Peanutbook manuscript. Build it with `bubble-build`; read the source in
+`chapter*/`.
+
+---
+
+## What this book argues
+
+One claim, stated in Chapter 1 and earned over the following eleven:
+
+> **A coding agent is not a language model with a code prompt. It is a software
+> engineering system built around a model.**
+
+The question it answers is not whether AI can write code. That is settled, and
+settling it mattered less than everyone expected. The question is:
+
+> **How do we engineer software-development systems in which humans and coding
+> agents work together reliably on large production codebases?**
+
+Roughly seventy percent of the text is architecture, large-codebase practice,
+verification, evaluation, security, and multi-agent engineering. The other
+thirty percent uses specific systems as concrete implementations, because
+abstract discussion of agents is unfalsifiable and boring. That ratio is
+deliberate: the named products will be replaced, some of them before this is in
+print. The questions in the other seventy percent will not.
+
+---
+
+## Register
+
+The voice is already set by the first three chapters. Match it. These are
+descriptions of what the existing prose does, not aspirations.
+
+**Address the reader as "you." Never "we."** Across the written chapters: 89
+instances of *you*, one of *we*. The reader is an engineer doing this work, not
+a co-author being carried along.
+
+**First person singular is rationed, and only ever for first-hand experience.**
+Four instances in fifteen thousand words, all of the form *"in notes I wrote in
+March 2024."* Use it to introduce evidence you personally hold. Never for
+opinion — the argument should stand without the byline.
+
+**State the claim, then earn it.** The paragraph shape is: assertion,
+mechanism, consequence. Not: build-up, build-up, reveal.
+
+**Prefer the corrective construction.** *X is not Y. It is Z.* — "The context
+window is not storage. It is a working set." "File context is not repository
+context." This is the book's most characteristic sentence, because most of what
+it has to teach is a correction to a reasonable-sounding wrong model.
+
+**End on the consequence, not the hedge.** A sentence that trails off into
+*"...but of course this depends on your situation"* has wasted the reader's
+attention. If it depends, say what it depends on.
+
+**No hype vocabulary.** No *revolutionary*, *seamless*, *game-changing*,
+*paradigm shift*, *cutting-edge*. The existing chapters contain none. Enthusiasm
+is conveyed by precision, not adjectives.
+
+**Concrete over abstract, always.** A number with a date beats a
+characterization. A named failure beats "challenges." A worked example beats a
+principle.
+
+**Date every number, or state only the shape.** The field moves fast enough that
+an undated figure is worse than none, and a book that quotes a leaderboard
+without saying when looks careless within a year. Where a figure carries an
+argument, cite the paper and the date. Where only the trend matters, describe
+the trend.
+
+**Name few products, and never rank them.** A book that ranks models has a shelf
+life measured in months.
+
+**Say what did not work.** Anyone can write "here are the best practices." The
+material worth reading is *"we thought the bottleneck was X and it was Y."* The
+author's own failed work is the strongest evidence in the book; use it.
+
+**Admit uncertainty in the text, not in a hedge.** "This is model-specific and
+worth measuring on your own workload" is honest. "This may or may not apply" is
+noise.
+
+### Structural habits
+
+| Element | Convention |
+| :--- | :--- |
+| `>IMPORS:` box | One claim, stated once. About six per chapter. |
+| `>NOTES:` box | An aside the reader can skip. About two per chapter. |
+| Cross-references | Constant — roughly one per 230 words. Every chapter says which chapter takes a thread further. |
+| Figure captions | 20 words maximum, stating the claim. Longer explanation goes in the paragraph that introduces the figure. |
+| `<!-- -->` comments | Author notes, verification lists, publication gates. Dropped from the PDF. |
+| Chapter ending | A named handoff to the next chapter. |
+
+### Two things that are not register, but read like it
+
+**`>NOTES:` blocks print.** They are for the reader. Notes to yourself go in
+HTML comments, which pandoc drops.
+
+**Every chapter opens with a real, attributed epigraph.** Brooks (Ch 1), Parnas
+(Ch 2), Pike (Ch 3). Do not invent quotes, and do not attribute the book's own
+theses to anyone — those belong in `>IMPORS:` boxes.
+
+---
+
+## Shelf life
+
+The book is written for a **5–10 year spine and a 2–3 year surface**, and the
+two need to stay physically separable.
+
+What is being bet on lasting: the verification principle, context as a working
+set with an allocator, file context against repository context, benchmarks
+scoring a harness rather than a model, paired evaluation, the prefill/decode
+asymmetry, and the seven-component decomposition — which survives on Parnas's
+test, not on fashion, because each component is a decision that changes
+independently of the others.
+
+What will rot on schedule: model names, context sizes, prices, benchmark
+numbers, API shapes, and the current claim that frontier general models beat
+code-only models. All of it is real and all of it belongs in the book.
+
+This ships on KDP, where a revised interior is a re-upload rather than a print
+run, so the cost of carrying perishable material is low and the book can afford
+more of it than a traditionally published one. But **the thing that does not get
+revised is the reviews.** A one-star "already out of date" from the first
+edition sits on the same product page as the fourth, and no amount of iteration
+removes it. So perishable content is still quarantined into clearly dated
+sections — not to make revision cheap, but because a reader forgives datedness
+they were warned about and punishes datedness that presented itself as current.
+
+Handled that way the perishable sections invert from liability to asset: a
+section titled *The Frontier, as of <month year>* is a reason to buy the new
+edition. Put the edition and its date on the title page, and keep a short
+revision record in the back matter.
+
+The genuine risk is not that details age. It is that the **harness framing
+itself** gets absorbed — models that do multi-hour repository work with no
+scaffold would turn Part II into a historical chapter. The hedge is to write the
+harness chapters around *why* a harness exists — verification, budget, policy,
+accountability — rather than *how to build one*. Those four survive the
+absorption, because someone still has to verify the diff, pay for it, constrain
+it, and answer for it.
+
+The lifespan is therefore mostly decided by whether the book's own concepts get
+adopted: the Coding Agent Stack, the Evolution Ladder, the Agent-Ready
+Repository, Harness Engineering. A book that is cited for its framework outlives
+its examples. A book that only summarizes today's tools does not, however well
+written.
+
+---
+
+## Structure
+
+Four parts, twelve chapters, following one line of development:
+
+```text
+Static Agent -> Stateful -> Persistent -> Multi-Agent -> Self-Evolving
+```
+
+| # | Chapter | Words | State |
+| ---: | :--- | ---: | :--- |
+| | **Part I — Foundations** | | |
+| 1 | Code Language Models | 4,300 | drafted |
+| 2 | Anatomy of a Coding Agent | 6,200 | drafted |
+| 3 | Context and Repository Understanding | 4,100 | drafted |
+| | **Part II — The Agent Harness** | | |
+| 4 | Tools, Skills, and Agent Harnesses | 4,700 | drafted |
+| 5 | Planning and Spec-Driven Development | 4,600 | drafted |
+| 6 | Coding, Debugging, and Refactoring | 4,500 | drafted |
+| 7 | Verification and Repair | | outline |
+| | **Part III — Coding Agents in Production** | | |
+| 8 | Coding Agents at Scale | | outline |
+| 9 | Long-Running and Multi-Agent Systems | | outline |
+| 10 | Evaluation, Observability, and Economics | | outline |
+| 11 | Security and Enterprise Deployment | | outline |
+| | **Part IV — The Next Generation** | | |
+| 12 | Self-Evolving Coding Agents | | outline |
+
+Front matter is in `chapterx/` — the preface is outlined, not written, and it
+owns the author-credibility argument and the book-structure walkthrough.
+`chapter2/_draft-from-ch1.md` is the original Chapter 1, kept because its
+forty-line agent and enterprise retrospective still have somewhere to go.
+
+The concepts the book has to deliver, not merely name: the **Coding Agent
+Stack**, the **Agentic Software Engineering Loop**, the **Agent-Ready
+Repository** and its readiness score, **Harness Engineering**, and the **Coding
+Agent Evolution Ladder**.
+
+---
+
+## Building
+
+```bash
+conda activate usao
+
+bubble-convert 3              # one chapter, while drafting
+bubble-build --style square   # the whole book -> book_square.pdf
+bubble-single-star            # style lint
+```
+
+`bubble-convert` does **not** run figure scripts; only `bubble-build` does. When
+you change a figure while drafting, run it yourself first:
+
+```bash
+cd chapter3-*/img && python myfig.py && cd ../..
+```
+
+Check captions before building:
+
+```bash
+grep -rn '^!\[' chapter*/*.md | sed 's/^\(.*\):!\[\(.*\)\](.*/\1|\2/' \
+  | awk -F'|' '{n=split($2,a," "); if (n>20) printf "%d words: %s\n", n, $1}'
+```
+
+Figures are generated by Python scripts in each chapter's `img/`, never
+committed as hand-made images. The conventions are in
+`.claude/skills/peanutbook-figures/`; mindmaps need `mathicon`.
+
+---
+
+## Source material, and the gate on it
+
+`raw/` holds the author's Oracle talk and design notes from 2023–2024. Read
+`raw/README.md` before using any of it.
+
+The short version: the model rankings in those notes are dead, and the methods
+are not. The recitation probe, paired evaluation, and the generate–verify–repair
+loop all come from there and all still hold. Cite the papers with dates, never
+the slides. Abstract employer-internal specifics into general lessons, strip
+colleague names and email addresses, and confirm publication clearance.
+
+---
+
+## Before this ships
+
+- [ ] Preface written — it owns the author's position and the book's structure
+- [ ] Every date, benchmark size, and figure verified against its source
+- [ ] The frontier claims in Chapter 1 re-checked and stamped
+- [ ] `author` set in `peanut.config`; covers replaced
+- [ ] Every `@fig:` resolves, no caption over 20 words, `bubble-single-star` clean

coding_agents-0.0.1.dev0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "coding-agents"
+version = "0.0.1.dev0"
+description = "The reference software engineering harness and runtime for autonomous coding agents."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Coding Agents Authors", email = "authors@example.com" }
+]
+keywords = [
+    "coding-agents",
+    "llm-agents",
+    "software-engineering",
+    "harness",
+    "autonomous-coding",
+    "swe-bench"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Code Generators",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+]
+dependencies = [
+    "pydantic>=2.0.0",
+    "rich>=13.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+llm = [
+    "anthropic>=0.20.0",
+    "openai>=1.0.0",
+]
+
+[project.scripts]
+coding-agent = "coding_agents.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+coding_agents = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+

coding_agents-0.0.1.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

coding_agents-0.0.1.dev0/src/coding_agents/__init__.py

@@ -0,0 +1,37 @@
+"""Coding Agents: The reference harness and runtime for autonomous coding systems."""
+
+from coding_agents.core.agent import CodingAgent
+from coding_agents.core.budget import Budget
+from coding_agents.core.models import StopCondition, Trajectory, TurnRecord, ToolCall, ToolResult
+from coding_agents.tools.patch_editor import PatchEditor
+from coding_agents.tools.bash_tool import BashTool
+from coding_agents.sandbox.policy import PolicyGate
+from coding_agents.sandbox.worktree import WorktreeSandbox
+from coding_agents.verification.pipeline import VerificationPipeline, VerificationManifest
+from coding_agents.verification.fault_localizer import FaultLocalizer
+from coding_agents.verification.oscillation import OscillationDetector
+from coding_agents.evolution.skill_miner import SkillMiner
+from coding_agents.evolution.parallel_planner import ParallelPlanningEngine
+
+__version__ = "0.0.1.dev0"
+
+__all__ = [
+    "CodingAgent",
+    "Budget",
+    "StopCondition",
+    "Trajectory",
+    "TurnRecord",
+    "ToolCall",
+    "ToolResult",
+    "PatchEditor",
+    "BashTool",
+    "PolicyGate",
+    "WorktreeSandbox",
+    "VerificationPipeline",
+    "VerificationManifest",
+    "FaultLocalizer",
+    "OscillationDetector",
+    "SkillMiner",
+    "ParallelPlanningEngine",
+]
+