ph-utcp 0.11.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.
@@ -0,0 +1,31 @@
1
+ # Build and environment
2
+ .venv/
3
+ dist/
4
+ build/
5
+ *.egg-info/
6
+ __pycache__/
7
+ *.py[cod]
8
+ jjt/
9
+ w2/
10
+
11
+ # Tooling caches
12
+ .pytest_cache/
13
+ .mypy_cache/
14
+ .ruff_cache/
15
+ .coverage
16
+ # Written by the guest's subprocess collectors and combined at the end of the
17
+ # run; see `conftest.GUEST_COVERAGE_RC`.
18
+ .coverage-guest*
19
+ htmlcov/
20
+ # Dropped at the repo root by pytest-textual-snapshot when a snapshot test
21
+ # fails. The reference snapshots under `__snapshots__/` are the committed
22
+ # expectation; this is the diff viewer for a run that did not match one.
23
+ snapshot_report.html
24
+
25
+ # Reference checkouts of the upstream projects this port reads from. Vendored
26
+ # locally so the plans' citations are verifiable; never part of this repo.
27
+ sources/
28
+
29
+ # Local scratch
30
+ .ph/
31
+ *.local.yaml
ph_utcp-0.11.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Charles Tabor
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,186 @@
1
+ Metadata-Version: 2.5
2
+ Name: ph-utcp
3
+ Version: 0.11.0
4
+ Summary: pH plugin: tools published as UTCP manuals, as tools a pH agent can call.
5
+ Project-URL: Homepage, https://github.com/chastabor/pH
6
+ Project-URL: Repository, https://github.com/chastabor/pH
7
+ Project-URL: Documentation, https://github.com/chastabor/pH/blob/main/docs/README.md
8
+ Project-URL: Issues, https://github.com/chastabor/pH/issues
9
+ Author: Charles Tabor
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: agent,llm,tools,utcp
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
21
+ Classifier: Topic :: Software Development
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.12
24
+ Requires-Dist: ph-core==0.11.0
25
+ Requires-Dist: utcp-cli<1.2,>=1.1.5
26
+ Requires-Dist: utcp<1.3,>=1.2
27
+ Description-Content-Type: text/markdown
28
+
29
+ # ph-utcp
30
+
31
+ *Tools published as [UTCP](https://utcp.io) manuals, as tools a pH agent can call.*
32
+
33
+ One row, `utcp`. Give it a manual call template — the object any UTCP harness
34
+ registers — and every tool the manual names becomes a pH tool: in the prompt,
35
+ through the pipeline, in the log, and in Code Mode's listing.
36
+
37
+ ```yaml
38
+ - id: utcp
39
+ name: utcp
40
+ config:
41
+ manuals:
42
+ - template:
43
+ name: weather
44
+ call_template_type: cli
45
+ commands:
46
+ - command: weather-tools manual
47
+ state: weather # a directory of the calling agent's scratch, for what it builds
48
+ writable: [] # shared paths outside the workspace its commands may write
49
+ tools:
50
+ forecast:
51
+ concurrency_safe: true
52
+ effect_free: true
53
+ ```
54
+
55
+ ## A UTCP tool sees what its agent sees
56
+
57
+ A `cli` tool's command is started by `ctx.shell` for the agent making the call:
58
+ in that agent's workspace, under that agent's sandbox, and ended by the call's
59
+ own cancellation. That makes a UTCP tool bounded the way `bash` is bounded.
60
+
61
+ **`permissions-fs` does not apply to it.** Those rules govern calls through
62
+ `ctx.fs`, and a subprocess is not one. What bounds a UTCP tool's reads and writes
63
+ is the sandbox.
64
+
65
+ ## Where a tool keeps what it builds
66
+
67
+ A tool that builds something *about* a tree — an index, a graph — changes no
68
+ file of it, so a read-only session should not stop it, and should still stop it
69
+ writing the tree. Two settings say where such a tool writes:
70
+
71
+ - **`state`** names a directory for the tool's working state. Each call's command
72
+ is told `$PH_TOOL_STATE=<the calling agent's scratch>/<state>`. The scratch is
73
+ writable under every sandbox mode; the workspace only under `workspace-write`.
74
+ It is per session and agent, so two agents never share state, and an agent
75
+ that restarts is told the same directory and finds what it built. A tool made
76
+ with `ph.toolcli` reads it with `state_dir()`.
77
+ - **`$PH_TOOL_AGENT`** names the agent that state belongs to, for a tool that
78
+ asks the session to do something on that agent's account — the text index's
79
+ embeddings through a model route are recorded in that agent's log. It is a
80
+ word from inside a sandbox: a session uses it for bookkeeping and grants
81
+ nothing by it.
82
+ - **Temporary files go in the scratch too.** Every confined command gets
83
+ `TMPDIR=<the agent's scratch>` from the shell seam: the sandbox leaves it no
84
+ writable `/tmp`, and a model library that makes one temporary file would
85
+ otherwise fail there.
86
+ - **`writable`** names paths outside the workspace that agents *share*: a grammar
87
+ cache, a model's weights. A grant holds under every sandbox mode. One that
88
+ overlaps the workspace — inside it, the root itself, or a directory containing
89
+ it — is refused and reported in `phern doctor`, because honoring it would make
90
+ the repository writable in a session whose person said it is not. So a
91
+ deployment whose workspace contains `$PH_CACHE` (a session started in the home
92
+ directory) gets no grant under the cache.
93
+
94
+ ## A host, for a manual whose tools are slow to start
95
+
96
+ ```yaml
97
+ - template: { name: notes, call_template_type: cli, commands: [{command: ph-notes manual}] }
98
+ state: notes
99
+ host:
100
+ command: [ph-notes, serve] # a `ph.toolcli` command, up to and including `serve`
101
+ label: notes index # what the footer and the completion note call it
102
+ warm: [notes_index] # tools it calls once when started unasked
103
+ eager: true # start it at a root agent's first step
104
+ idle_s: 900
105
+ ```
106
+
107
+ A manual can name a command that stays up and answers its tools on a socket, so
108
+ what they load — an embedding model — is loaded once, and a long piece of work
109
+ goes on past the call that asked for it. The row keeps one running for each tree
110
+ an agent works in:
111
+
112
+ - **Started as every command is**: by `ctx.shell`, for the agent, in its
113
+ workspace and under its sandbox. Each call is told the socket in
114
+ `$PH_TOOL_HOST`; a command that finds nobody there runs by itself, so a host is
115
+ never required for a call to be answered.
116
+ - **A job of the agent it serves** (`ctx.jobs`). It ends when the agent does and
117
+ when the manual's row unmounts, leaves by itself when idle, and is started
118
+ again by the next call. A daemon that restarts starts a new one; nothing is
119
+ picked up, and nothing needs to be, because what the tools build is on disk.
120
+ - **One a tree, not one an agent.** A child builds its own only when it has a
121
+ tree it writes for keeps: a worktree, an overlay. One in its parent's checkout,
122
+ or granted only to read the project — `readonly-scratch`, and the two
123
+ ephemeral kinds — uses its parent's host and its parent's `state`, and its
124
+ commands run in that tree, which is how a `ph.toolcli` command is told its
125
+ root. So a read-only fan-out is one index and one host however many children
126
+ it has. An answer about a tree other than the asking agent's own says so.
127
+ - **`eager`** starts it at a root agent's first step with the `warm` tools to
128
+ call, so an index is being built before anything asks for it — once for each
129
+ tree, and without holding the step up. A host that leaves when idle is started
130
+ again by the next call, not the next step, so an unchanged tree is not indexed
131
+ again for nobody.
132
+ - **Progress and its end.** A host's tools report to `progress.json` in the state
133
+ directory. While one works the footer says how far it has got ("notes index
134
+ 120/539 documents"); when it ends, and somebody is owed word of it — a call was
135
+ answered "still going", or the host began the work unasked — the agent is told,
136
+ with a note that waits for its next step and starts no turn. The note carries
137
+ what the run itself has to say of its end (`Progress.note`): what the tool's
138
+ result would have told a caller that waited.
139
+
140
+ Sockets are under `$PH_RUNTIME/utcp`, granted to the host and to each call. A
141
+ deployment with no job runner or no usable runtime directory runs every call by
142
+ itself.
143
+
144
+ ## What a manual cannot say
145
+
146
+ UTCP describes a tool with a name, a description and two schemas. pH's scheduler
147
+ and policy rows also read whether two calls may overlap and whether a call has
148
+ effects. Each defaults to the careful answer — not safe to overlap, has effects —
149
+ and the manual's `tools` table states otherwise per tool.
150
+
151
+ A UTCP tool has no idempotency key and no `reconcile`, so after a crash mid-call
152
+ its outcome is unknown to the model, as `DESIGN.md` says of any such tool.
153
+
154
+ ## A provider that is down
155
+
156
+ A manual whose discovery fails is skipped: a warning in the log, a line under
157
+ "UTCP tools" in `phern doctor`, and a note in the system prompt naming the
158
+ provider, so the model does not go looking for a tool that is not there. The
159
+ mount goes ahead with the manuals that answered.
160
+
161
+ ## Protocols
162
+
163
+ `cli` is allowed by default, because it is the one this row runs through pH's
164
+ own doors. Another protocol — `http`, `mcp` — runs inside the harness process by
165
+ the UTCP library's own client, outside the sandbox and its egress rules. To use
166
+ one, install its plugin (`utcp-http`, `utcp-mcp`) and name it in `protocols`.
167
+
168
+ ## Credentials
169
+
170
+ A template's `${VAR}` references are resolved from the environment when a call is
171
+ made. This row stores no values.
172
+
173
+ A command's environment starts as the deployment's scrubbed one, which drops
174
+ every variable whose name looks like a credential, and a template cannot name
175
+ its way past that. A manual's `pass_env` is how a deployment says one may pass:
176
+ the names of variables read from the harness's own environment each time one of
177
+ the manual's commands is started — a tool call, or its host — and set on that
178
+ command alone.
179
+
180
+ ## Publishing a pH tool as a manual
181
+
182
+ `ph.toolcli` turns a package's rows into a command line with a `manual`
183
+ subcommand; see `docs/cookbook/adding-a-tool.md`. A manual written that way sets
184
+ `envelope: true`, and its tools then read to an agent exactly as they would
185
+ registered in-process: the same value, the same rendered text, the same error
186
+ codes.
@@ -0,0 +1,158 @@
1
+ # ph-utcp
2
+
3
+ *Tools published as [UTCP](https://utcp.io) manuals, as tools a pH agent can call.*
4
+
5
+ One row, `utcp`. Give it a manual call template — the object any UTCP harness
6
+ registers — and every tool the manual names becomes a pH tool: in the prompt,
7
+ through the pipeline, in the log, and in Code Mode's listing.
8
+
9
+ ```yaml
10
+ - id: utcp
11
+ name: utcp
12
+ config:
13
+ manuals:
14
+ - template:
15
+ name: weather
16
+ call_template_type: cli
17
+ commands:
18
+ - command: weather-tools manual
19
+ state: weather # a directory of the calling agent's scratch, for what it builds
20
+ writable: [] # shared paths outside the workspace its commands may write
21
+ tools:
22
+ forecast:
23
+ concurrency_safe: true
24
+ effect_free: true
25
+ ```
26
+
27
+ ## A UTCP tool sees what its agent sees
28
+
29
+ A `cli` tool's command is started by `ctx.shell` for the agent making the call:
30
+ in that agent's workspace, under that agent's sandbox, and ended by the call's
31
+ own cancellation. That makes a UTCP tool bounded the way `bash` is bounded.
32
+
33
+ **`permissions-fs` does not apply to it.** Those rules govern calls through
34
+ `ctx.fs`, and a subprocess is not one. What bounds a UTCP tool's reads and writes
35
+ is the sandbox.
36
+
37
+ ## Where a tool keeps what it builds
38
+
39
+ A tool that builds something *about* a tree — an index, a graph — changes no
40
+ file of it, so a read-only session should not stop it, and should still stop it
41
+ writing the tree. Two settings say where such a tool writes:
42
+
43
+ - **`state`** names a directory for the tool's working state. Each call's command
44
+ is told `$PH_TOOL_STATE=<the calling agent's scratch>/<state>`. The scratch is
45
+ writable under every sandbox mode; the workspace only under `workspace-write`.
46
+ It is per session and agent, so two agents never share state, and an agent
47
+ that restarts is told the same directory and finds what it built. A tool made
48
+ with `ph.toolcli` reads it with `state_dir()`.
49
+ - **`$PH_TOOL_AGENT`** names the agent that state belongs to, for a tool that
50
+ asks the session to do something on that agent's account — the text index's
51
+ embeddings through a model route are recorded in that agent's log. It is a
52
+ word from inside a sandbox: a session uses it for bookkeeping and grants
53
+ nothing by it.
54
+ - **Temporary files go in the scratch too.** Every confined command gets
55
+ `TMPDIR=<the agent's scratch>` from the shell seam: the sandbox leaves it no
56
+ writable `/tmp`, and a model library that makes one temporary file would
57
+ otherwise fail there.
58
+ - **`writable`** names paths outside the workspace that agents *share*: a grammar
59
+ cache, a model's weights. A grant holds under every sandbox mode. One that
60
+ overlaps the workspace — inside it, the root itself, or a directory containing
61
+ it — is refused and reported in `phern doctor`, because honoring it would make
62
+ the repository writable in a session whose person said it is not. So a
63
+ deployment whose workspace contains `$PH_CACHE` (a session started in the home
64
+ directory) gets no grant under the cache.
65
+
66
+ ## A host, for a manual whose tools are slow to start
67
+
68
+ ```yaml
69
+ - template: { name: notes, call_template_type: cli, commands: [{command: ph-notes manual}] }
70
+ state: notes
71
+ host:
72
+ command: [ph-notes, serve] # a `ph.toolcli` command, up to and including `serve`
73
+ label: notes index # what the footer and the completion note call it
74
+ warm: [notes_index] # tools it calls once when started unasked
75
+ eager: true # start it at a root agent's first step
76
+ idle_s: 900
77
+ ```
78
+
79
+ A manual can name a command that stays up and answers its tools on a socket, so
80
+ what they load — an embedding model — is loaded once, and a long piece of work
81
+ goes on past the call that asked for it. The row keeps one running for each tree
82
+ an agent works in:
83
+
84
+ - **Started as every command is**: by `ctx.shell`, for the agent, in its
85
+ workspace and under its sandbox. Each call is told the socket in
86
+ `$PH_TOOL_HOST`; a command that finds nobody there runs by itself, so a host is
87
+ never required for a call to be answered.
88
+ - **A job of the agent it serves** (`ctx.jobs`). It ends when the agent does and
89
+ when the manual's row unmounts, leaves by itself when idle, and is started
90
+ again by the next call. A daemon that restarts starts a new one; nothing is
91
+ picked up, and nothing needs to be, because what the tools build is on disk.
92
+ - **One a tree, not one an agent.** A child builds its own only when it has a
93
+ tree it writes for keeps: a worktree, an overlay. One in its parent's checkout,
94
+ or granted only to read the project — `readonly-scratch`, and the two
95
+ ephemeral kinds — uses its parent's host and its parent's `state`, and its
96
+ commands run in that tree, which is how a `ph.toolcli` command is told its
97
+ root. So a read-only fan-out is one index and one host however many children
98
+ it has. An answer about a tree other than the asking agent's own says so.
99
+ - **`eager`** starts it at a root agent's first step with the `warm` tools to
100
+ call, so an index is being built before anything asks for it — once for each
101
+ tree, and without holding the step up. A host that leaves when idle is started
102
+ again by the next call, not the next step, so an unchanged tree is not indexed
103
+ again for nobody.
104
+ - **Progress and its end.** A host's tools report to `progress.json` in the state
105
+ directory. While one works the footer says how far it has got ("notes index
106
+ 120/539 documents"); when it ends, and somebody is owed word of it — a call was
107
+ answered "still going", or the host began the work unasked — the agent is told,
108
+ with a note that waits for its next step and starts no turn. The note carries
109
+ what the run itself has to say of its end (`Progress.note`): what the tool's
110
+ result would have told a caller that waited.
111
+
112
+ Sockets are under `$PH_RUNTIME/utcp`, granted to the host and to each call. A
113
+ deployment with no job runner or no usable runtime directory runs every call by
114
+ itself.
115
+
116
+ ## What a manual cannot say
117
+
118
+ UTCP describes a tool with a name, a description and two schemas. pH's scheduler
119
+ and policy rows also read whether two calls may overlap and whether a call has
120
+ effects. Each defaults to the careful answer — not safe to overlap, has effects —
121
+ and the manual's `tools` table states otherwise per tool.
122
+
123
+ A UTCP tool has no idempotency key and no `reconcile`, so after a crash mid-call
124
+ its outcome is unknown to the model, as `DESIGN.md` says of any such tool.
125
+
126
+ ## A provider that is down
127
+
128
+ A manual whose discovery fails is skipped: a warning in the log, a line under
129
+ "UTCP tools" in `phern doctor`, and a note in the system prompt naming the
130
+ provider, so the model does not go looking for a tool that is not there. The
131
+ mount goes ahead with the manuals that answered.
132
+
133
+ ## Protocols
134
+
135
+ `cli` is allowed by default, because it is the one this row runs through pH's
136
+ own doors. Another protocol — `http`, `mcp` — runs inside the harness process by
137
+ the UTCP library's own client, outside the sandbox and its egress rules. To use
138
+ one, install its plugin (`utcp-http`, `utcp-mcp`) and name it in `protocols`.
139
+
140
+ ## Credentials
141
+
142
+ A template's `${VAR}` references are resolved from the environment when a call is
143
+ made. This row stores no values.
144
+
145
+ A command's environment starts as the deployment's scrubbed one, which drops
146
+ every variable whose name looks like a credential, and a template cannot name
147
+ its way past that. A manual's `pass_env` is how a deployment says one may pass:
148
+ the names of variables read from the harness's own environment each time one of
149
+ the manual's commands is started — a tool call, or its host — and set on that
150
+ command alone.
151
+
152
+ ## Publishing a pH tool as a manual
153
+
154
+ `ph.toolcli` turns a package's rows into a command line with a `manual`
155
+ subcommand; see `docs/cookbook/adding-a-tool.md`. A manual written that way sets
156
+ `envelope: true`, and its tools then read to an agent exactly as they would
157
+ registered in-process: the same value, the same rendered text, the same error
158
+ codes.
@@ -0,0 +1,61 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "ph-utcp"
7
+ version = "0.11.0"
8
+ description = "pH plugin: tools published as UTCP manuals, as tools a pH agent can call."
9
+ readme = "README.md"
10
+ requires-python = ">=3.12"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "Charles Tabor" }]
14
+ keywords = ["agent", "llm", "tools", "utcp"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Intended Audience :: Developers",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
21
+ "Operating System :: POSIX :: Linux",
22
+ "Operating System :: MacOS",
23
+ "Topic :: Software Development",
24
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
25
+ "Typing :: Typed",
26
+ ]
27
+ # `utcp` is the client and its data model; `utcp-cli` is the one protocol this
28
+ # row runs through pH's own doors (`_library.PhCliProtocol`). The floors are the
29
+ # versions that were read: 1.1.5 is the CLI protocol whose arguments reach the
30
+ # shell as environment variables rather than as text spliced into the script,
31
+ # and the subclass here overrides two of its methods by name.
32
+ #
33
+ # **Ceilinged, because those two methods are private.** A release that renames
34
+ # either would leave the override dead and every command unconfined; the row
35
+ # refuses to mount then, and refuses an answer whose command did not pass through
36
+ # pH (`_library.require_ran`), but a minor version is the point to read the
37
+ # library again rather than find out from that refusal.
38
+ #
39
+ # No other protocol plugin is a dependency. A deployment that wants `http` or
40
+ # `mcp` manuals installs that plugin and names the type in the row's
41
+ # `protocols` — two steps on purpose, because those run inside the harness
42
+ # process and outside the sandbox.
43
+ dependencies = ["ph-core==0.11.0", "utcp>=1.2,<1.3", "utcp-cli>=1.1.5,<1.2"]
44
+
45
+ [project.urls]
46
+ Homepage = "https://github.com/chastabor/pH"
47
+ Repository = "https://github.com/chastabor/pH"
48
+ Documentation = "https://github.com/chastabor/pH/blob/main/docs/README.md"
49
+ Issues = "https://github.com/chastabor/pH/issues"
50
+
51
+ [project.entry-points."ph.bundles"]
52
+ utcp = "ph_utcp:BUNDLE"
53
+
54
+ [project.entry-points."ph.plugins"]
55
+ utcp = "ph_utcp:apply"
56
+
57
+ [tool.uv.sources]
58
+ ph-core = { workspace = true }
59
+
60
+ [tool.hatch.build.targets.wheel]
61
+ packages = ["src/ph_utcp"]