langchain-submilli 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. langchain_submilli-0.1.0/.gitignore +17 -0
  2. langchain_submilli-0.1.0/CHANGELOG.md +25 -0
  3. langchain_submilli-0.1.0/LICENSE +201 -0
  4. langchain_submilli-0.1.0/NOTES.md +287 -0
  5. langchain_submilli-0.1.0/PKG-INFO +361 -0
  6. langchain_submilli-0.1.0/README.md +329 -0
  7. langchain_submilli-0.1.0/examples/research/README.md +32 -0
  8. langchain_submilli-0.1.0/pyproject.toml +84 -0
  9. langchain_submilli-0.1.0/src/langchain_submilli/__init__.py +21 -0
  10. langchain_submilli-0.1.0/src/langchain_submilli/_app_tools.py +444 -0
  11. langchain_submilli-0.1.0/src/langchain_submilli/_middleware.py +538 -0
  12. langchain_submilli-0.1.0/src/langchain_submilli/_tools.py +248 -0
  13. langchain_submilli-0.1.0/src/langchain_submilli/py.typed +0 -0
  14. langchain_submilli-0.1.0/tests/__init__.py +0 -0
  15. langchain_submilli-0.1.0/tests/integration_tests/__init__.py +0 -0
  16. langchain_submilli-0.1.0/tests/integration_tests/conftest.py +129 -0
  17. langchain_submilli-0.1.0/tests/integration_tests/test_app_tools.py +205 -0
  18. langchain_submilli-0.1.0/tests/integration_tests/test_research.py +281 -0
  19. langchain_submilli-0.1.0/tests/scripted.py +59 -0
  20. langchain_submilli-0.1.0/tests/unit_tests/__init__.py +0 -0
  21. langchain_submilli-0.1.0/tests/unit_tests/fake_server.py +276 -0
  22. langchain_submilli-0.1.0/tests/unit_tests/test_app_tools.py +413 -0
  23. langchain_submilli-0.1.0/tests/unit_tests/test_deepagents.py +58 -0
  24. langchain_submilli-0.1.0/tests/unit_tests/test_middleware.py +321 -0
  25. langchain_submilli-0.1.0/tests/unit_tests/test_standard.py +60 -0
@@ -0,0 +1,17 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .pytest_cache/
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+ dist/
8
+ build/
9
+ *.egg-info/
10
+ .submilli-bin/
11
+
12
+ # Local only: model and service keys, the test server's home and token
13
+ .env
14
+ .submilli-test/
15
+ .submilli-test.log
16
+ .submilli-token
17
+ .benchmarks/
@@ -0,0 +1,25 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are recorded here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-10-15
10
+
11
+ First release, for submilli-server 0.4.1 and the `submilli` SDK 0.1.
12
+
13
+ ### Added
14
+
15
+ - `SubmilliMiddleware` for deepagents and any LangChain v1 agent: the server's
16
+ six tools, with the Blueprint's descriptions, and one session per thread,
17
+ bound to the variables and secrets from the run's context.
18
+ - Retries with an `Idempotency-Key` per tool call. A session that ended is
19
+ replaced, and the model is told. A thread whose variables changed is refused.
20
+ - `aclose_thread` to end a thread's session.
21
+ - `hide_filesystem_tools` to remove deepagents' own file and shell tools.
22
+ - `ptc` (programmatic tool calling): programs call the application's LangChain tools as `@tools`,
23
+ run through a `ToolNode` with the run's state and context.
24
+ - `interrupt_on` for `ptc` tools: a person approves each call, with
25
+ LangChain's human-in-the-loop request and decision shapes.
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,287 @@
1
+ # Notes
2
+
3
+ These are the decisions the brief left open, and what in submilli-runtime got in the way. The
4
+ package was built and tested against submilli-runtime at `60f2a857` (server 0.4.0, built from
5
+ source; the installed 0.3.0 binary was not used). Application tools (`ptc`, first named `expose_tools`) were added
6
+ for, and tested against, the published 0.4.1 release binaries, which also pass the restart and
7
+ expiry tests. The HTTP client now lives in its own package, `submilli`
8
+ (`packages/submilli` in the same workspace), described below. It was also tested against deepagents 0.7.24, langchain 1.4.5, langchain-core
9
+ 1.6.10, and langgraph 1.2.15.
10
+
11
+ ## Decisions
12
+
13
+ ### Tools
14
+
15
+ - **Names.** The tools keep the server's own names (`submilli__typescript__execute` and the
16
+ rest), without a prefix of ours. The server's responses refer to its tools by these names.
17
+ For example, a package search with no hits points to `submilli__typescript__builtins__docs`.
18
+ A renamed tool would contradict the text the model reads. The names also match the MCP
19
+ endpoint and the Vercel example.
20
+ - **Arguments.** `code`, `query` (default `""`), `name`, and `names`, with the field
21
+ descriptions of the server's MCP tools.
22
+ - **Descriptions.** They come from `GET /v1/blueprints/{name}/prompt`, which the middleware
23
+ fetches on the first model call, in `awrap_model_call`, and caches for the instance. It does
24
+ not fetch them in `__init__`, because that would need a blocking request while the agent is
25
+ built. The descriptions are set on the middleware's own tool objects. Until then, each tool
26
+ has a short fallback description, so it can be inspected before any run.
27
+ - **Result shape.** The content is JSON text with `result`, `console`, `error`, and `denied`, as
28
+ in the Vercel example. A denial adds `note`, which tells the model the denial is final. A
29
+ replaced session adds `notice`. `discovery_warnings` is passed through when present.
30
+ `ToolMessage.status` is `"error"` whenever `error` is set.
31
+ - **Artifact.** The artifact holds `{execution_id, session_id}`. An idempotency refusal adds
32
+ `refusal`, and `execution_id` when the server sent one.
33
+ - **Discovery tools never open a session.** `last_run` in a thread with no session answers in
34
+ text and does not open one.
35
+ - **langchain-core quirk.** A `StructuredTool` whose argument schema has no fields gets no
36
+ arguments at all, the injected `ToolRuntime` included. `last_run` and `builtins__list`
37
+ therefore carry a hidden `runtime` field marked `InjectedToolArg`.
38
+
39
+ ### Sessions
40
+
41
+ - **Where the session opens.** The session opens in `aafter_model`, when the model's message
42
+ first asks for `submilli__typescript__execute`. It does not open inside the tool. The update
43
+ from the `after_model` node is checkpointed before the tools node runs. A process that
44
+ crashes mid-call and resumes from that checkpoint retries in the same session, and the
45
+ idempotency key replays the run. Had the session opened inside the tool, the resumed call
46
+ would find no session, open a new one, and run the program a second time. If the tool runs
47
+ without the hook, it opens the session itself, with a per-thread lock, and returns it in a
48
+ `Command`.
49
+ - **State.** The state key is `submilli_session`: `{id, server, blueprint, variables}`. It is
50
+ marked `PrivateStateAttr`, so it is left out of the agent's input and output schemas, and
51
+ applications read it with `aget_state`. Its reducer replaces the old value. Parallel tool
52
+ calls that all find the session gone each write the same replacement, and the default
53
+ channel would reject more than one write in a step.
54
+ - **Variables are stored, secrets are not.** The variables are kept as values, so a mismatch
55
+ is an exact comparison. Secrets are recomputed from the context whenever they are needed.
56
+ - **Mismatch.** `abefore_agent` raises `SubmilliSessionMismatchError` before the model is
57
+ called. The message names the variables that differ, not their values. A mismatch is the
58
+ application's error, so it is raised rather than shown to the model. The tool checks again
59
+ before every execute.
60
+ - **Blueprint or server change on a thread.** When the stored session was opened for another
61
+ Blueprint or server, it is ignored and a new session is opened. The old session is left to
62
+ its idle timeout.
63
+ - **Closing.** `await middleware.aclose_thread(agent, config)` deletes the thread's session and
64
+ sets `submilli_session` to `None` with `aupdate_state`. The next execute opens a new session,
65
+ and it may bind another user. `middleware.client.sessions.delete(id)` is the low-level form.
66
+ Nothing closes a session automatically.
67
+ - **Retries.** On `404 unknown session`, the middleware opens a new session once per call, and
68
+ the next call reuses that replacement. On `409 session_requires_secrets`, it rebinds once and
69
+ retries. A second `409` raises `SubmilliError`.
70
+ - **Errors that are the application's raise; errors that are the model's are tool results.**
71
+ These raise: 401, invalid variables or secrets, an unknown Blueprint, and an unreachable
72
+ server. These come back as tool results: program failures, denials, and idempotency
73
+ refusals.
74
+
75
+ ### Idempotency
76
+
77
+ - The key is the tool call id when it is printable ASCII of at most 120 bytes. Otherwise it is
78
+ the sha256 hex digest of the id's UTF-8 bytes.
79
+ - This assumes tool call ids are unique within a thread, as Anthropic's and OpenAI's are. A
80
+ model that reuses an id, as the scripted model in `check.py` does (`call-1` for every call),
81
+ would get the recorded result of an earlier call with the same code. The tests use unique
82
+ ids.
83
+ - Across a session replacement nothing is deduplicated, because the ledger belongs to the
84
+ session.
85
+
86
+ ### Configuration
87
+
88
+ - `variables` and `secrets` accept a callable over `runtime.context` or a fixed mapping. The
89
+ default reads `user_id` from a dict key or an attribute, so a dict, a dataclass, and a
90
+ Pydantic model all work, and maps it to `userId`. Values must be strings; anything else raises
91
+ `TypeError`.
92
+ - `client=` takes a ready `submilli.AsyncSubmilli`, which can wrap your own `httpx.AsyncClient`.
93
+ The managed client keeps one `httpx.AsyncClient` per event loop, because applications and tests
94
+ often run several loops.
95
+ - The default request timeout is 330 s. The server may wait up to 300 s for a running request
96
+ with the same idempotency key.
97
+ - **Async only.** The tools' sync entry points raise `NotImplementedError` with a pointer to
98
+ `ainvoke`. deepagents does not require a sync API.
99
+ - One `SubmilliMiddleware` per agent: two instances would share the `submilli_session` key.
100
+
101
+ ### deepagents' file tools
102
+
103
+ - The middleware can hide them cleanly. `hide_filesystem_tools=True` filters `ls`, `read_file`,
104
+ `write_file`, `edit_file`, `delete`, `glob`, `grep`, and `execute` out of `request.tools` in
105
+ `awrap_model_call`. deepagents' own `_ToolExclusionMiddleware` uses the same mechanism. The
106
+ flag also refuses a call to one of them in `awrap_tool_call`. deepagents 0.7.24's
107
+ `FilesystemMiddleware` adds no system-prompt text of its own, so no prose is left describing
108
+ the hidden tools. The flag is opt-in, and the example uses it.
109
+ - **Limit.** deepagents' built-in `general-purpose` subagent is built with its own middleware
110
+ list, and user middleware does not reach it. It keeps deepagents' file tools and gets no
111
+ Submilli tools. The README says so, and points to `permissions=` for denying the file tools
112
+ there too.
113
+ - The flag also hides any tool of the app's own with one of those names, `execute` included.
114
+
115
+ ### Application tools (`ptc`)
116
+
117
+ Server 0.4.1 shipped SUB-1694: a session declares `tools`, programs call them through `@tools`,
118
+ each call suspends the run in memory, and the harness answers with `POST /v1/runs/{id}/resume`.
119
+
120
+ - **The option is `ptc`, not `tools`.** `AgentMiddleware.tools` is already the list of
121
+ tools a middleware gives the model. These tools are not given to the model. It was first
122
+ `expose_tools`; it was renamed before the first release to match `langchain-quickjs`'s
123
+ `CodeInterpreterMiddleware(ptc=...)`. Unlike there, it takes tool objects only, not names:
124
+ the session declares its tools when it opens, from the execute tool, which does not see the
125
+ agent's tool list.
126
+ - **Declaring.** The input schema is `tool.tool_call_schema`, so injected arguments
127
+ (`ToolRuntime`, `InjectedState`, `InjectedStore`) are not part of it. The output schema comes
128
+ from the function's return annotation through a pydantic `TypeAdapter`. It is `string` when
129
+ there is no annotation, when the annotation is a message, a `Command`, `Any`, or `str`, when
130
+ the tool is not `response_format="content"`, or when the annotation has no JSON schema.
131
+ Local `$ref`s are inlined, because the server's mapper does not resolve `$ref` and would type
132
+ the field `unknown`. A recursive reference becomes `{}`.
133
+ - **What the server can't type.** `dict[str, X]` (`additionalProperties`) comes back
134
+ `unknown`, with a warning when the session opens. It is declared anyway, because a program
135
+ can still narrow an `unknown`. The README tells users to return a `TypedDict` or a model.
136
+ - **Running a call.** It goes through a `ToolNode` built over the exposed tools, invoked with a
137
+ `ToolCallWithContext` and the execute tool's own config. That gives the agent's own injection,
138
+ error handling (`handle_tool_errors=True`, so a raising tool becomes a `failed` answer), and
139
+ `Command` validation. The nested call's id is the server's `call_id`. Other middleware's
140
+ `wrap_tool_call` hooks do not run around nested calls.
141
+ - **Values.** A tool declared as text returns the `ToolMessage` text. A structured tool returns
142
+ the parsed JSON of that text. A `ToolNode` writes a value that isn't JSON as its `str()`, so
143
+ structured tools run through a copy whose function returns `to_jsonable_python(...)`. That
144
+ makes a Pydantic model reach the program as an object. The copy keeps the signature
145
+ (`functools.wraps`), so injected arguments are still detected.
146
+ - **State updates.** A nested tool that returns a `Command` has its non-message updates
147
+ applied with the execute result. `ToolNode` only accepts a dict as a Command's update, so
148
+ updates to the same key are combined: dicts are merged (deepagents' `files`), and anything
149
+ else keeps the last value. A nested `Command.goto` is refused.
150
+ - **Approvals use LangGraph `interrupt()` inside the execute tool.** The request and decision
151
+ shapes are `HumanInTheLoopMiddleware`'s, one action per pause, so existing approval UIs work.
152
+ The hard part is that LangGraph gives a re-run task its earlier resume values by position,
153
+ while the server has already moved past the calls those values answered. Re-running the
154
+ tool replays the execute with the same `Idempotency-Key`, which answers the run's current
155
+ state, but the first interrupt of the re-run would get the first stored value. The middleware
156
+ therefore records, for each run, which call each pause was for. On a re-run it skips the
157
+ interrupts that belong to earlier calls (`interrupt(None)` returns a stored value without
158
+ raising) before it asks for the current one. Two approvals in one program are tested against
159
+ the fake and against a real 0.4.1 server.
160
+ - **The limit of that record.** It lives in the middleware's memory. When the thread is resumed
161
+ in another process, for example another worker, and the task already has resume values,
162
+ they can't be matched to calls. Then the call is answered `denied`, saying the approval
163
+ could not be matched; it is never matched by guessing. Whether the task has resume values is
164
+ read from LangGraph's scratchpad (`langgraph._internal._constants.CONFIG_KEY_SCRATCHPAD`),
165
+ which is private. A server-side history of a run's answered calls would make this
166
+ stateless.
167
+ - **The record also carries** the call records and state updates of a run interrupted
168
+ mid-way, so the invocation that finishes it reports every call, not only those after the
169
+ last pause.
170
+ - **Nested interrupts are not supported.** An exposed tool that calls `interrupt()` itself
171
+ would take resume values meant for approvals.
172
+ - **Lost runs.** A suspended run is lost when the server restarts (`404 unknown_run` on
173
+ resume). The model gets a `run_lost` result saying its effects are unknown, as for
174
+ `idempotency_incomplete`. `409 run_not_suspended` (a call timed out) and `400 unknown_call`
175
+ make the middleware read the run with `GET /v1/runs/{id}` and carry on. A `running` state is
176
+ polled with backoff.
177
+ - **Discovery.** With exposed tools, `packages__search` and `packages__docs` use
178
+ `/v1/sessions/{id}/packages/...`, so `@tools` is included, and those calls open the session
179
+ (in `aafter_model` too). Without exposed tools nothing changes.
180
+ - **Sessions keep their catalog.** `submilli_session.tools` holds a sha256 of the declared
181
+ catalog, and a session whose fingerprint differs is not reused. Sessions stored before this
182
+ field have none, which matches a middleware without exposed tools.
183
+ - **Seen on the real server.** `@tools` docs list every declared tool, including those the
184
+ Blueprint's filter refuses. The filter is checked on each call, which then fails with
185
+ `permission_denied`, `source: policy`, and the application never sees it. A tool with no
186
+ arguments is called as `tools.name()`.
187
+
188
+ ### Packaging, tests, CI
189
+
190
+ - The license is Apache-2.0, as submilli-runtime's. Python is 3.11 or later. Dependencies have
191
+ lower bounds at the tested versions, under the next major version (deepagents under 0.8),
192
+ and `uv.lock` pins the tested set. deepagents is an optional extra
193
+ (`langchain-submilli[deepagents]`), because the middleware works with any LangChain v1 agent.
194
+ - The package lives in the `github.com/submilli/submilli-python` workspace, next to `submilli`,
195
+ and its URLs point there.
196
+ - **Standard tests.** `ToolsUnitTests` runs for each of the six tools. `ToolsIntegrationTests`
197
+ invokes a tool synchronously and on its own, without an agent runtime, so it cannot apply
198
+ to these async, state-bound tools. It will apply to the future toolkit.
199
+ - **Integration tests.** Most run against an external server with the `research` Blueprint and
200
+ are skipped when none is reachable. The restart and expiry tests start their own server from
201
+ `SUBMILLI_BIN` or `PATH`, with a small Blueprint that needs no Package and declares a harness
202
+ secret. A restart does not force a `409`: see "Harness secrets survive restarts" below, so the
203
+ rebind path is covered by the unit tests only. Expiry uses `idle_timeout: 1s`: the test stops the server
204
+ for 1.5 s, and the server reaps the session when it starts again. The resume test reopens the
205
+ thread with a new middleware and agent over the same checkpointer, from the checkpoint taken
206
+ just before the tools node.
207
+ - **Typing.** The package ships `py.typed`. `mypy --strict` and pyright check the sources,
208
+ the tests, and the example, and `pyright --verifytypes` requires the public API to be fully
209
+ typed and documented (100%). The internal modules are private (`_middleware.py`, `_tools.py`,
210
+ `_app_tools.py`), and the public API is what `langchain_submilli` exports. Typing found two
211
+ things worth changing. `SubmilliMiddleware` was generic over a context type it could never
212
+ bind, so an agent built with `context_schema=` together with it failed type inference; it is
213
+ now `AgentMiddleware[SubmilliState, Any, Any]`. And the example now declares a `Context`
214
+ schema, so its `ainvoke(context=...)` type-checks.
215
+ - **CI** is the workspace's: ruff, mypy, pyright and `--verifytypes`, and the unit tests on
216
+ Python 3.11 to 3.13. Its integration job downloads the released `submilli-server` and runs
217
+ the tests that start their own server; those that need the `research` Blueprint's Packages
218
+ are skipped there. The integration fixture registers Blueprints over the admin API, so the
219
+ `submilli` CLI, which has no Linux release build, is not needed.
220
+ - The example keeps the brief's model id, `anthropic:claude-sonnet-5`. It uses an
221
+ `InMemorySaver` and closes the thread's session when it exits.
222
+
223
+ ### The `submilli` SDK
224
+
225
+ The HTTP client moved out of this package into `submilli`, a separate package in the same
226
+ workspace (`packages/submilli`). It knows the HTTP API and nothing about LangChain, so other
227
+ harnesses can use it. Both are published to PyPI on their own, from one repository, so a
228
+ change that spans both, such as application tools, is one pull request.
229
+
230
+ - **What moved.** The requests, the typed results and errors, `idempotency_key`, `$ref`
231
+ inlining, and the suspend and resume loop (`runs.complete`). The loop takes an
232
+ `on_tool_call` callback and lets an exception from it propagate, which leaves the run
233
+ waiting on the server. That is what a LangGraph interrupt needs.
234
+ - **What stayed.** The middleware, the six tools, the state schema, turning LangChain tools
235
+ into declarations, running nested calls through a `ToolNode`, approvals, and merging state
236
+ updates.
237
+ - **Names.** Some names changed: `IdempotencyRefusedError` is `submilli.IdempotencyError`, and
238
+ `SubmilliHTTPError` is `submilli.APIStatusError` with a subclass for each status. The
239
+ middleware no longer re-exports client types.
240
+ - **The dependency.** `submilli>=0.1.0,<0.2` on PyPI. In the workspace,
241
+ `[tool.uv.sources]` resolves it to `packages/submilli`. The published wheel names the PyPI
242
+ requirement, which CI checks.
243
+
244
+ ### Harness secrets survive restarts
245
+
246
+ The HTTP API reference says harness secrets are kept in memory only and do not survive a
247
+ restart. On 0.4.0 and 0.4.1 that is not what happens. The server stores them encrypted with
248
+ its secret-store key, in SQLite (`encrypted_harness_bindings`). It refuses session secrets
249
+ when no key is configured (`409`, "configure the secret-store encryption key before supplying
250
+ session secrets"). After a restart with a different key, it answers `409` "cannot decrypt
251
+ session secrets", not `session_requires_secrets`. The earlier restart test passed without ever
252
+ rebinding; it now says what it checks. The middleware's rebind on `session_requires_secrets`
253
+ stays, because the API still documents that answer.
254
+
255
+ ## What in submilli-runtime got in the way
256
+
257
+ Each item below is filed in Linear, in the Submilli team's `server` project.
258
+
259
+ 1. **MCP execute ignores idempotency.** (SUB-1685) `mcp/server.rs` passes `idempotency_key: None`. It
260
+ already reads Claude Code's `_meta["claudecode/toolUseId"]`, but only for the run record. If
261
+ the server took a key from MCP `_meta`, as a generic `submilli/idempotencyKey` or by reusing
262
+ the tool call id, MCP harnesses would get the same retry safety as this package.
263
+ 2. **HTTP execute cannot carry the tool call id.** (SUB-1686) `handlers/sessions.rs` records
264
+ `tool_call_id: None`. An HTTP harness has no way to put its tool call id in the run's record
265
+ and audit trail, except as the `Idempotency-Key`, which this package hashes when the id is
266
+ long. A `Submilli-Tool-Call-Id` header would close the gap.
267
+ 3. **A replay is not marked.** (SUB-1687) A replayed response is byte-identical to the original. A
268
+ `replayed: true` field, or a response header, would let the harness tell the model or the
269
+ application that nothing ran this time.
270
+ 4. **Error codes are sometimes prose.** (SUB-1688) `404 {"error":"unknown session"}`,
271
+ `"blueprint no longer exists"`, `"unknown blueprint"`, and the `400` bodies of
272
+ `POST /v1/sessions` (`"invalid variables: ..."`) put a sentence where other endpoints put a
273
+ stable snake_case code. The client has to match those strings.
274
+ 5. **`execution_id` on refusals is undocumented.** (SUB-1689) Refusals carry an `execution_id`:
275
+ `404 unknown session`, `409 session_requires_secrets`, and the idempotency refusals. The
276
+ HTTP API reference shows bodies without it.
277
+ 6. **`GET last-run` is ambiguous.** (SUB-1690) It answers `404` with an empty body both for an unknown
278
+ session and for a session with no recorded run.
279
+ 7. **`idle_timeout` is approximate.** (SUB-1691) A session idle past its timeout keeps answering until the
280
+ next reaper sweep, every 30 s (`REAP_INTERVAL` in `app.rs`), or a restart. That is harmless
281
+ for users, but a test cannot observe real expiry without restarting the server.
282
+ 8. **Two names for the server URL.** (SUB-1692) The `submilli server ...` commands read
283
+ `SUBMILLI_SERVER_URL`, while the harness examples, and so this package, use
284
+ `SUBMILLI_SERVER`.
285
+ 9. **The HTTP API has no file endpoints.** (SUB-1693) The MCP endpoint has `submilli__files__*`; the HTTP
286
+ API does not. This package therefore has no file tools, and the model reads files with
287
+ programs.