Skip to content

docs(runtimes): the acp runtime, ADR 0049 and SDK 1.26.0 (#1634) - #1839

Merged
jhgaylor merged 1 commit into
mainfrom
stack/1634-8-docs
Sep 11, 2026
Merged

docs(runtimes): the acp runtime, ADR 0049 and SDK 1.26.0 (#1634)#1839
jhgaylor merged 1 commit into
mainfrom
stack/1634-8-docs

Conversation

@jhgaylor

@jhgaylor jhgaylor commented Sep 10, 2026

Copy link
Copy Markdown
Collaborator

The last PR of the stack. Everything the seven below it built is now
documented and released.

  • docs/catalog/runtimes/index.md gains the runtime, a row in the
    comparison table, a skills-layout row, and Running a program as an agent:
    the manifest, the five things that follow from the command being a shell
    line, and how the turn is priced.
  • Two traps have their own paragraphs, because both are silent and both
    cost a turn. Write exec before the program, or the login shell stays as the
    parent and an interrupt can leave the program running on a persistent
    sandbox. And nothing may print on stdout before the program starts, because a
    profile's banner lands in front of the first protocol message.
  • What "the same isolation" means is stated where it is weakest. The free
    string is safe because it runs where an environment's setup script already
    runs. On sandbox_provider: runner with the default backend that is a
    directory and the daemon's own user, so the page says so and links to
    trusted mode.
  • docs/concepts/agent.md, docs/concepts/permissions.md (both tables, since
    whether the command asks and how long a grant lasts are its decisions, not
    Fountain's), docs/sdk.md, docs/reference/glossary.md, docs/build/index.md
    and the three "all four runtimes speak ACP" lines.
  • SDK 1.25.0. Agent["model"] is string | null, and the two request
    bodies take string | null optionally. A client that assumed a string needs
    a null check; nothing else on the wire changed shape.

The docs suite, docs-style.py (its two findings are pre-existing pages I did
not touch), vale and destink all pass.


Stack for #1634 (merge top down; each PR is based on the one below it in the list):

PR What it is
1 #1832 Fountain.CommandRuntime and the host dispatch for acp
2 #1833 agents.runtime_command, and acp becomes a runtime you can name
3 #1834 skills mount on a runtime the library does not know
4 #1835 a turn on the acp runtime, end to end
5 #1836 refuse a turn whose agent no longer carries a command
6 #1837 the acp runtime in the agent form
7 #1838 a real ACP program through a whole turn
8 #1839 docs, CHANGELOG and SDK 1.25.0

Replaces #1677, which was the same feature as one 1,760-line branch.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A2iMoNvSvrkQQfnP4RzVi2

@lex00 lex00 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two things before this one goes in:

  • CHANGELOG.md line 50 has a stray >>>>>>> theirs marker that this commit introduced (it is in none of the source branches).
  • main moved to SDK 1.25.0 with #1809 after this stack was cut, so this release collides; it needs 1.26.0, and #1849 then needs 1.27.0 or the other way round depending on which lands first.

Approving the rest of the stack.

@jhgaylor
jhgaylor force-pushed the stack/1634-7-conformance branch from 5c6b9a2 to 39fc7ba Compare September 11, 2026 01:19
@jhgaylor
jhgaylor force-pushed the stack/1634-7-conformance branch from 39fc7ba to 238dd13 Compare September 11, 2026 01:41
@jhgaylor jhgaylor changed the title docs(runtimes): the acp runtime, and SDK 1.25.0 (#1634) docs(runtimes): the acp runtime, ADR 0049 and SDK 1.26.0 (#1634) Sep 11, 2026
@jhgaylor

Copy link
Copy Markdown
Collaborator Author

Rebased onto the current main. #1809 landed while this stack's CI was running and took 1.25.0 for the @managoat/fountain-sdk rename, so this bump is now 1.26.0 and its changelog entry sits above main's. All four edit sites moved together: package.json, package-lock.json (two spots), src/http.ts's USER_AGENT and CHANGELOG.md.

Worth noting the collision was invisible to the tooling: GitHub reported MERGEABLE the whole time, because two releases claiming the same version number is a semantic conflict and not a textual one.

@jhgaylor
jhgaylor force-pushed the stack/1634-7-conformance branch from 238dd13 to 1bc5c84 Compare September 11, 2026 02:04
@jhgaylor
jhgaylor force-pushed the stack/1634-7-conformance branch from 1bc5c84 to 179a369 Compare September 11, 2026 02:10
@jhgaylor
jhgaylor force-pushed the stack/1634-7-conformance branch from 179a369 to afadc23 Compare September 11, 2026 02:13
The last PR of the stack. Everything the seven below it built is now
documented, decided and released.

- **`decisions/0049-the-acp-runtime-runs-a-command-you-name.md`.** The
  free-string decision was justified in a moduledoc, a migration docstring and
  a docs page, and in none of them durably: it is the kind of choice that
  constrains future work, and "why not a catalog of blessed commands" will be
  asked again. The ADR carries that, the isolation claim and where it is
  weakest, the two silent shell traps, and the four alternatives. Index
  regenerated; `okf validate decisions` reports 0 errors and only the four
  actor-convention warnings that already sit on other ADRs.
- **`docs/catalog/runtimes/index.md`** gains the runtime, a row in the
  comparison table, a skills-layout row, and *Running a program as an agent*:
  the manifest, the five things that follow from the command being a shell
  line, and how the turn is priced.
- **Two traps have their own paragraphs**, because both are silent and both
  cost a turn. Write `exec` before the program, or the login shell stays as the
  parent and an interrupt can leave the program running on a persistent
  sandbox. And nothing may print on stdout before the program starts, because a
  profile's banner lands in front of the first protocol message.
- **What "the same isolation" means is stated where it is weakest.** On
  `sandbox_provider: runner` with the default backend it is a directory and the
  daemon's own user, so the page says so and links to trusted mode.
- `docs/concepts/agent.md`, `docs/concepts/permissions.md` (both tables, since
  whether the command asks and how long a grant lasts are its decisions, not
  Fountain's), `docs/sdk.md`, `docs/reference/glossary.md`, `docs/build/index.md`
  and the three "all four runtimes speak ACP" lines.
- **TypeScript SDK 1.26.0.** `Agent["model"]` is `string | null`, and the two
  request bodies take `string | null` optionally. A client that assumed a
  string needs a null check; nothing else on the wire changed shape. The Swift
  SDK's matching widening landed with the schema change earlier in the stack.

The docs suite, `docs-style.py` (its one finding is a pre-existing page I did
not touch), vale and destink all pass.

Closes #1634

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01A2iMoNvSvrkQQfnP4RzVi2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants