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.
- ph_utcp-0.11.0/.gitignore +31 -0
- ph_utcp-0.11.0/LICENSE +21 -0
- ph_utcp-0.11.0/PKG-INFO +186 -0
- ph_utcp-0.11.0/README.md +158 -0
- ph_utcp-0.11.0/pyproject.toml +61 -0
- ph_utcp-0.11.0/src/ph_utcp/__init__.py +1054 -0
- ph_utcp-0.11.0/src/ph_utcp/_library.py +263 -0
- ph_utcp-0.11.0/src/ph_utcp/bundle.yaml +15 -0
- ph_utcp-0.11.0/src/ph_utcp/py.typed +0 -0
- ph_utcp-0.11.0/tests/test_utcp.py +601 -0
|
@@ -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.
|
ph_utcp-0.11.0/PKG-INFO
ADDED
|
@@ -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.
|
ph_utcp-0.11.0/README.md
ADDED
|
@@ -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"]
|