langgraph-acp 0.1.0__tar.gz

langgraph_acp-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+.venv/
+uv.lock.bak
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+node_modules/
+*.tsbuildinfo
+/conversations.sqlite3
+# Where a graph workflow remembers how far it got, written next to wherever
+# the server was started. Local state, like the conversation store above it.
+/graph-state/
+.claude/settings.local.json
+.codex/
+test-results/
+playwright-report/
+
+# Server-local secrets
+.env
+.env.*

langgraph_acp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

langgraph_acp-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: langgraph-acp
+Version: 0.1.0
+Summary: Use ACP-compatible agents as first-class LangGraph nodes.
+Project-URL: Homepage, https://github.com/OpenEngine/OpenEngine/tree/main/langgraph-acp
+Project-URL: Repository, https://github.com/OpenEngine/OpenEngine
+Project-URL: Issues, https://github.com/OpenEngine/OpenEngine/issues
+License-Expression: Apache-2.0
+Keywords: acp,agent-client-protocol,agents,langgraph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# langgraph-acp
+
+Use [ACP](https://agentclientprotocol.com)-compatible agents — Codex, Claude,
+and anything else that speaks the protocol — as first-class LangGraph nodes.
+
+```text
+LangGraph owns orchestration and workflow durability.
+ACP owns the agent conversation and agent-side session state.
+langgraph-acp owns the binding between the two.
+```
+
+The design and the ticket sequence live in
+[docs/langgraph-acp Architecture and Implementation Plan.md](https://github.com/OpenEngine/OpenEngine/blob/main/docs/langgraph-acp%20Architecture%20and%20Implementation%20Plan.md).
+
+## Status
+
+Tickets 1 to 4 of that plan: the core types, a connection to a real agent, the
+store that remembers which conversation belongs to which node, and the first
+working `ACPNode` end-to-end path.
+
+```python
+from langgraph_acp import ACPNode
+
+result = await ACPNode(agent="codex")("Review this change")
+print(result.message)
+```
+
+Available now:
+
+| | |
+| --- | --- |
+| `ACPNode` | a LangGraph-compatible async callable that runs one ACP turn |
+| `ACPAgentProvider`, `ACPAgentRegistry`, `default_registry` | names resolve to agents |
+| `StdioACPProvider`, `CodexACPProvider` | how an agent is launched |
+| `ACPClient`, `ACPCapabilities` | one live connection, and what it can do |
+| `ACPSession` | one conversation, and the turns run in it |
+| `ACPSessionSpec`, `ACPSessionStrategy` | which conversation a node speaks in |
+| `ACPSessionStore`, `InMemoryACPSessionStore` | which ACP session a node's identity resolves to |
+| `ACPWorkspace` | the filesystem context a session is given |
+| `ACPConfig`, `ACPRequirements` | settings requested, capabilities demanded |
+| `ACPEvent`, `ACPEventType` | streamed activity, normalized |
+| `ACPResult`, `ACPUsage` | what a turn returns, and what it cost |
+| `ACPError` and its subclasses | typed failures |
+
+Registering another ACP agent is a command line rather than a class:
+
+```python
+default_registry().register(
+    StdioACPProvider(name="gemini", command=["gemini", "--experimental-acp"])
+)
+```
+
+The minimal node takes its invocation input as the prompt and starts a fresh
+session each time. Runtime prompt resolvers, session reuse, MCP injection, and
+LangGraph event streaming arrive in the following tickets.
+
+## Session bindings
+
+`ACPSessionStore` maps a node's logical identity to the ACP session it speaks
+in, so that a workflow can pick a conversation back up later:
+
+```python
+store = InMemoryACPSessionStore()
+
+await store.put("pr-918", "reviewer", "sess_abc123")
+await store.get("pr-918", "reviewer")     # -> "sess_abc123"
+await store.delete("pr-918", "reviewer")
+```
+
+The identity is a pair, not a thread id, because one LangGraph thread routinely
+runs several agents — an implementer and three reviewers on the same pull
+request — and none of them may resume another's conversation.
+
+**A store holds ACP session identifiers and nothing else.** No conversation
+history, no agent messages, no tool history, no model context, no agent memory:
+the ACP agent owns all of that and restores it itself when asked to load
+`sess_abc123`. That is what makes a reply arriving on a webhook days later
+resume a live conversation without reconstructing a transcript — and why the
+store is the piece that has to be durable. `InMemoryACPSessionStore` is not; it
+lives as long as its process, which is right for tests, examples, and
+single-process graphs. The durable implementations arrive with Ticket 17 and
+change nothing about the interface.
+
+Two behaviours are placeholders that later tickets replace. Permission requests
+are streamed as `acp.permission.requested` and then declined, because the policy
+that could approve them does not exist yet; and the history an agent replays
+while loading a session is dropped, because no turn is streaming when it
+arrives.
+
+## Development
+
+A standalone distribution, deliberately outside the `uv` workspace at the root
+of this repository: it depends on nothing OpenEngine ships, targets a newer
+Python than the rest of the tree, and is intended to be published on its own.
+
+```bash
+cd langgraph-acp
+uv run pytest
+uv run mypy    # strict, over src/ and tests/
+```
+
+The package ships `py.typed`, so its annotations are a promise to a downstream
+type checker; `mypy --strict` runs in CI on both supported interpreters to keep
+it. Each field is annotated with what the constructor accepts, since
+`__post_init__` normalizes — a `Path` becomes a `str`, `"reuse"` becomes
+`ACPSessionStrategy.REUSE`.
+
+The dependency list is empty and stays empty: ACP is JSON-RPC over a pipe, so
+the client is stdlib `asyncio` written here rather than a second protocol
+library in every application that installs this one. The client tests launch a
+real child process — `tests/fake_agent.py`, an ACP agent that does nothing,
+correctly — because the thing under test is a process boundary.
+
+CI runs both only when something under `langgraph-acp/` changes.

langgraph_acp-0.1.0/README.md

@@ -0,0 +1,114 @@
+# langgraph-acp
+
+Use [ACP](https://agentclientprotocol.com)-compatible agents — Codex, Claude,
+and anything else that speaks the protocol — as first-class LangGraph nodes.
+
+```text
+LangGraph owns orchestration and workflow durability.
+ACP owns the agent conversation and agent-side session state.
+langgraph-acp owns the binding between the two.
+```
+
+The design and the ticket sequence live in
+[docs/langgraph-acp Architecture and Implementation Plan.md](https://github.com/OpenEngine/OpenEngine/blob/main/docs/langgraph-acp%20Architecture%20and%20Implementation%20Plan.md).
+
+## Status
+
+Tickets 1 to 4 of that plan: the core types, a connection to a real agent, the
+store that remembers which conversation belongs to which node, and the first
+working `ACPNode` end-to-end path.
+
+```python
+from langgraph_acp import ACPNode
+
+result = await ACPNode(agent="codex")("Review this change")
+print(result.message)
+```
+
+Available now:
+
+| | |
+| --- | --- |
+| `ACPNode` | a LangGraph-compatible async callable that runs one ACP turn |
+| `ACPAgentProvider`, `ACPAgentRegistry`, `default_registry` | names resolve to agents |
+| `StdioACPProvider`, `CodexACPProvider` | how an agent is launched |
+| `ACPClient`, `ACPCapabilities` | one live connection, and what it can do |
+| `ACPSession` | one conversation, and the turns run in it |
+| `ACPSessionSpec`, `ACPSessionStrategy` | which conversation a node speaks in |
+| `ACPSessionStore`, `InMemoryACPSessionStore` | which ACP session a node's identity resolves to |
+| `ACPWorkspace` | the filesystem context a session is given |
+| `ACPConfig`, `ACPRequirements` | settings requested, capabilities demanded |
+| `ACPEvent`, `ACPEventType` | streamed activity, normalized |
+| `ACPResult`, `ACPUsage` | what a turn returns, and what it cost |
+| `ACPError` and its subclasses | typed failures |
+
+Registering another ACP agent is a command line rather than a class:
+
+```python
+default_registry().register(
+    StdioACPProvider(name="gemini", command=["gemini", "--experimental-acp"])
+)
+```
+
+The minimal node takes its invocation input as the prompt and starts a fresh
+session each time. Runtime prompt resolvers, session reuse, MCP injection, and
+LangGraph event streaming arrive in the following tickets.
+
+## Session bindings
+
+`ACPSessionStore` maps a node's logical identity to the ACP session it speaks
+in, so that a workflow can pick a conversation back up later:
+
+```python
+store = InMemoryACPSessionStore()
+
+await store.put("pr-918", "reviewer", "sess_abc123")
+await store.get("pr-918", "reviewer")     # -> "sess_abc123"
+await store.delete("pr-918", "reviewer")
+```
+
+The identity is a pair, not a thread id, because one LangGraph thread routinely
+runs several agents — an implementer and three reviewers on the same pull
+request — and none of them may resume another's conversation.
+
+**A store holds ACP session identifiers and nothing else.** No conversation
+history, no agent messages, no tool history, no model context, no agent memory:
+the ACP agent owns all of that and restores it itself when asked to load
+`sess_abc123`. That is what makes a reply arriving on a webhook days later
+resume a live conversation without reconstructing a transcript — and why the
+store is the piece that has to be durable. `InMemoryACPSessionStore` is not; it
+lives as long as its process, which is right for tests, examples, and
+single-process graphs. The durable implementations arrive with Ticket 17 and
+change nothing about the interface.
+
+Two behaviours are placeholders that later tickets replace. Permission requests
+are streamed as `acp.permission.requested` and then declined, because the policy
+that could approve them does not exist yet; and the history an agent replays
+while loading a session is dropped, because no turn is streaming when it
+arrives.
+
+## Development
+
+A standalone distribution, deliberately outside the `uv` workspace at the root
+of this repository: it depends on nothing OpenEngine ships, targets a newer
+Python than the rest of the tree, and is intended to be published on its own.
+
+```bash
+cd langgraph-acp
+uv run pytest
+uv run mypy    # strict, over src/ and tests/
+```
+
+The package ships `py.typed`, so its annotations are a promise to a downstream
+type checker; `mypy --strict` runs in CI on both supported interpreters to keep
+it. Each field is annotated with what the constructor accepts, since
+`__post_init__` normalizes — a `Path` becomes a `str`, `"reuse"` becomes
+`ACPSessionStrategy.REUSE`.
+
+The dependency list is empty and stays empty: ACP is JSON-RPC over a pipe, so
+the client is stdlib `asyncio` written here rather than a second protocol
+library in every application that installs this one. The client tests launch a
+real child process — `tests/fake_agent.py`, an ACP agent that does nothing,
+correctly — because the thing under test is a process boundary.
+
+CI runs both only when something under `langgraph-acp/` changes.

langgraph_acp-0.1.0/build-constraints.txt

@@ -0,0 +1,23 @@
+# Hash-locked build backend for the PyPI release of langgraph-acp. Regenerate with:
+#   echo 'hatchling==<version>' | uv pip compile - --generate-hashes --universal \
+#     --python-version 3.11 --no-header -o build-constraints.txt
+hatchling==1.27.0 \
+    --hash=sha256:971c296d9819abb3811112fc52c7a9751c8d381898f36533bb16f9791e941fd6 \
+    --hash=sha256:d3a2f3567c4f926ea39849cdf924c7e99e6686c9c8e288ae1037c8fa2a5d937b
+    # via build-system.requires
+packaging==26.3 \
+    --hash=sha256:94edc256424af38762eb31306eed28beb9f0efc50a8837492c9d6fd6004aed79 \
+    --hash=sha256:d7193f7c8e4e93f444fde0262bf90af30e16fa0ad0ad44cb553c87339b23cd1c
+    # via hatchling
+pathspec==1.1.1 \
+    --hash=sha256:17db5ecd524104a120e173814c90367a96a98d07c45b2e10c2f3919fff91bf5a \
+    --hash=sha256:a00ce642f577bf7f473932318056212bc4f8bfdf53128c78bbd5af0b9b20b189
+    # via hatchling
+pluggy==1.6.0 \
+    --hash=sha256:7dcc130b76258d33b90f61b658791dede3486c3e6bfb003ee5c9bfb396dd22f3 \
+    --hash=sha256:e920276dd6813095e9377c0bc5566d94c932c33b27a3e3945d8389c374dd4746
+    # via hatchling
+trove-classifiers==2026.9.21.13 \
+    --hash=sha256:0a9ebc8d4e2f3e8a22848c5258033035bec17a3012ac3fea16dbaa764489eb71 \
+    --hash=sha256:8b1ff4f9c191b1040b71c37f1e445ab99732911e3cd91de52838453a854d7a17
+    # via hatchling

langgraph_acp-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "langgraph-acp"
+version = "0.1.0"
+description = "Use ACP-compatible agents as first-class LangGraph nodes."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+keywords = ["acp", "agent-client-protocol", "agents", "langgraph"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+# INVARIANT: no dependencies. ACP is JSON-RPC over a pipe, so the client is
+# stdlib asyncio written here rather than a second protocol library in every
+# application that installs this one; LangGraph arrives with the node, and
+# naming an agent is confined to `langgraph_acp.providers`.
+# Enforced by tests/test_public_api.py.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/OpenEngine/OpenEngine/tree/main/langgraph-acp"
+Repository = "https://github.com/OpenEngine/OpenEngine"
+Issues = "https://github.com/OpenEngine/OpenEngine/issues"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langgraph_acp"]
+
+[dependency-groups]
+dev = ["langgraph>=1.0", "mypy>=1.15", "pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Live adapter runs are deselected by default and opted into with
+# `-m compatibility`, which is what the scheduled compatibility workflow does.
+# They install the adapter from npm and talk to a real agent, so a default run
+# that included them would mean "did we break something, or is the registry
+# slow today?". The same convention, and the same reasoning, as the root
+# `pyproject.toml`.
+addopts = "-q -m 'not compatibility'"
+markers = [
+    "compatibility: launches the real ACP adapter; scheduled rather than per-PR",
+]
+
+[tool.mypy]
+# `py.typed` promises a downstream type checker that these annotations are
+# true, and only a type checker run against them keeps that promise. The tests
+# are checked too: they are where the spellings this package documents are
+# written out, so an annotation that rejects a documented call fails here.
+strict = true
+files = ["src", "tests"]

langgraph_acp-0.1.0/src/langgraph_acp/__init__.py

@@ -0,0 +1,134 @@
+"""ACP-compatible agents as first-class LangGraph nodes.
+
+The boundary this package exists to hold:
+
+    LangGraph owns orchestration and workflow durability.
+    ACP owns the agent conversation and agent-side session state.
+    langgraph-acp owns the binding between the two.
+
+What is here is the vocabulary, the connection beneath it, and the first node
+that joins the two halves: `ACPNode` resolves an agent, opens and initializes a
+connection, starts a session, runs a prompt, and returns an `ACPResult`.
+
+    ACPAgentRegistry -> ACPAgentProvider -> ACPClient -> ACPSession
+         "codex"          how to reach      one live     one conversation
+                             an agent       connection      and its turns
+
+    ACPSessionStore     (thread_id, session_key) -> "sess_abc123"
+                        the binding, and only ever the binding
+
+Naming an agent is confined to `langgraph_acp.providers`. Everything else --
+every core type, the registry, the client, the session -- is written without
+knowing whether it is talking to Codex or to something released next year, and
+`"codex"` is a string a registry resolves rather than an import anyone makes.
+
+Serialization follows one rule, so "does this have a `to_dict`?" has an answer
+that does not need looking up. Types that leave the process serialize:
+`ACPEvent` into a stream, `ACPResult` into LangGraph state. Types that only
+configure a node -- `ACPSessionSpec`, `ACPWorkspace`, `ACPConfig`,
+`ACPRequirements` -- do not: they are written in Python beside the graph, and a
+graph definition is code rather than data.
+
+Every field is annotated with what the constructor *accepts*, not with what it
+stores: `__post_init__` normalizes, so a `Path` becomes a `str`, a list becomes
+a tuple, and `"reuse"` becomes `ACPSessionStrategy.REUSE`. The stored value is
+always an instance of the declared type but usually a narrower one. A stdlib
+dataclass has no way to declare the two separately, and since `py.typed` ships
+here, the spelling a caller writes is the one the annotation has to admit.
+
+Containers handed in are copied, and so are containers handed back out by
+`to_dict`. The copy is deep, because ACP payloads are nested and a shallow one
+would leave the interesting part shared.
+"""
+
+from langgraph_acp._json import JSONObject, JSONValue
+from langgraph_acp.agent import (
+    ACPAgentProvider,
+    ACPAgentRegistry,
+    StdioACPProvider,
+    default_registry,
+)
+from langgraph_acp.client import PROTOCOL_VERSION, ACPCapabilities, ACPClient
+from langgraph_acp.config import ACPConfig, ACPRequirements, UnsupportedOption
+from langgraph_acp.continuation import ACPContinuation, resume_continuation
+from langgraph_acp.elicitation import (
+    ACPElicitationHandler,
+    ACPElicitationRequest,
+    ACPElicitationResponse,
+)
+from langgraph_acp.errors import (
+    ACPAgentCapabilityError,
+    ACPAgentNotFoundError,
+    ACPConnectionError,
+    ACPError,
+    ACPSessionError,
+)
+from langgraph_acp.events import EVENT_NAMESPACE, ACPEvent, ACPEventType
+from langgraph_acp.node import ACPNode
+from langgraph_acp.permissions import (
+    CANCELLED,
+    ACPPermissionHandler,
+    ACPPermissionOption,
+    ACPPermissionOutcome,
+    ACPPermissionRequest,
+    deny_permission,
+)
+from langgraph_acp.providers.claude import CLAUDE_ACP_COMMAND, ClaudeACPProvider
+from langgraph_acp.providers.codex import CODEX_ACP_COMMAND, CodexACPProvider
+from langgraph_acp.result import ACPResult, ACPUsage
+from langgraph_acp.session import (
+    ACPPrompt,
+    ACPSession,
+    ACPSessionSpec,
+    ACPSessionStrategy,
+)
+from langgraph_acp.store import ACPSessionStore, InMemoryACPSessionStore
+from langgraph_acp.workspace import ACPWorkspace
+
+__all__ = [
+    "ACPAgentCapabilityError",
+    "ACPAgentNotFoundError",
+    "ACPAgentProvider",
+    "ACPAgentRegistry",
+    "ACPCapabilities",
+    "ACPClient",
+    "ACPConfig",
+    "ACPConnectionError",
+    "ACPContinuation",
+    "ACPElicitationHandler",
+    "ACPElicitationRequest",
+    "ACPElicitationResponse",
+    "ACPError",
+    "ACPEvent",
+    "ACPEventType",
+    "ACPNode",
+    "ACPPermissionHandler",
+    "ACPPermissionOption",
+    "ACPPermissionOutcome",
+    "ACPPermissionRequest",
+    "ACPPrompt",
+    "ACPRequirements",
+    "ACPResult",
+    "ACPSession",
+    "ACPSessionError",
+    "ACPSessionSpec",
+    "ACPSessionStore",
+    "ACPSessionStrategy",
+    "ACPUsage",
+    "ACPWorkspace",
+    "CANCELLED",
+    "CLAUDE_ACP_COMMAND",
+    "CODEX_ACP_COMMAND",
+    "ClaudeACPProvider",
+    "CodexACPProvider",
+    "EVENT_NAMESPACE",
+    "InMemoryACPSessionStore",
+    "JSONObject",
+    "JSONValue",
+    "PROTOCOL_VERSION",
+    "StdioACPProvider",
+    "UnsupportedOption",
+    "default_registry",
+    "deny_permission",
+    "resume_continuation",
+]

langgraph_acp-0.1.0/src/langgraph_acp/_json.py

@@ -0,0 +1,136 @@
+"""JSON-shaped values: the copies that isolate them, and the reads that check them.
+
+ACP speaks JSON-RPC, so a few fields here carry whatever the agent sent: event
+payloads, result content, config values. Typing those as `JSONValue` states that
+honestly rather than inventing a richer type before the tickets that normalize
+them exist.
+
+Mappings and sequences are copied on the way in and on the way out. These
+objects end up in LangGraph state and in streamed events, where a container
+still shared with the caller is a mutation arriving from somewhere else
+entirely. The copy is *deep*, because the shape this data actually has is
+nested -- an ACP `session/update` is `{"update": {...}}`, and a shallow copy
+would leave the interesting part shared while the docstring claimed otherwise.
+The cost is proportional to the number of containers, not to the text inside
+them: strings are immutable and are shared rather than duplicated.
+
+The copies produce plain `dict` and `tuple` rather than read-only views because
+LangGraph checkpointing pickles what it stores, and `MappingProxyType` cannot be
+pickled.
+
+A lone `str` is refused wherever a sequence is expected. It is iterable, so
+without the guard `additional_directories="/repos/docs"` becomes eleven
+single-character roots and the mistake surfaces as a bad ACP request much later.
+
+The `as_*` readers exist for `from_dict`, where the input is whatever a store or
+a checkpoint handed back. They check rather than coerce: a token count that
+returns as `"1200"` should fail at the boundary it crossed, not as an arithmetic
+error in whatever later sums it.
+"""
+
+from collections.abc import Iterable, Mapping
+from copy import deepcopy
+from typing import TypeAlias, TypeVar
+
+JSONValue: TypeAlias = (
+    str
+    | int
+    | float
+    | bool
+    | None
+    | Iterable["JSONValue"]
+    | Mapping[str, "JSONValue"]
+)
+
+#: What a `to_dict` returns: a mapping the caller may keep and mutate freely.
+JSONObject: TypeAlias = dict[str, JSONValue]
+
+T = TypeVar("T")
+
+
+def copied_mapping(values: Mapping[str, JSONValue] | None) -> JSONObject:
+    """A private `dict`, nested containers included, holding what `values` held."""
+    return deepcopy(dict(values or {}))
+
+
+def checked_sequence(values: Iterable[T] | None, *, field: str) -> tuple[T, ...]:
+    """The values as a tuple, refusing the string that is quietly a sequence."""
+    if isinstance(values, (str, bytes)):
+        raise TypeError(
+            f"{field} takes a sequence of values, not the single "
+            f"{type(values).__name__} {values!r}: iterating one yields a "
+            "separate entry per character, which is never what was meant"
+        )
+    return tuple(values or ())
+
+
+def copied_sequence(
+    values: Iterable[JSONValue] | None, *, field: str
+) -> tuple[JSONValue, ...]:
+    """A private tuple, nested containers included, holding what `values` held."""
+    return tuple(deepcopy(value) for value in checked_sequence(values, field=field))
+
+
+def _wrong(field: str, expected: str, value: object) -> TypeError:
+    return TypeError(
+        f"{field} must be {expected}, not the {type(value).__name__} {value!r}"
+    )
+
+
+def as_str(value: object, *, field: str) -> str:
+    """`value` as the string it should already be."""
+    if isinstance(value, str):
+        return value
+    raise _wrong(field, "a string", value)
+
+
+def as_optional_str(value: object, *, field: str) -> str | None:
+    return None if value is None else as_str(value, field=field)
+
+
+def as_optional_int(value: object, *, field: str) -> int | None:
+    # `bool` is an `int` in Python, and is never a token count.
+    if value is None or (isinstance(value, int) and not isinstance(value, bool)):
+        return value
+    raise _wrong(field, "a whole number", value)
+
+
+def as_optional_float(value: object, *, field: str) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    raise _wrong(field, "a number", value)
+
+
+def as_mapping(value: object, *, field: str) -> JSONObject:
+    """`value` as a private mapping. A missing key reads as an empty one."""
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        return copied_mapping(value)
+    raise _wrong(field, "a mapping", value)
+
+
+def as_sequence(value: object, *, field: str) -> tuple[JSONValue, ...]:
+    """`value` as a private tuple. A missing key reads as an empty one."""
+    if value is None:
+        return ()
+    if not isinstance(value, Iterable):
+        raise _wrong(field, "a sequence of values", value)
+    return copied_sequence(value, field=field)
+
+
+__all__ = [
+    "JSONObject",
+    "JSONValue",
+    "as_mapping",
+    "as_optional_float",
+    "as_optional_int",
+    "as_optional_str",
+    "as_sequence",
+    "as_str",
+    "checked_sequence",
+    "copied_mapping",
+    "copied_sequence",
+]