tether-agents 0.3.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,14 @@
1
+ /target
2
+ **/*.rs.bk
3
+ *.jsonl
4
+ *.blobs/
5
+ *.halt
6
+ .tether/
7
+ .env
8
+ .DS_Store
9
+ node_modules/
10
+ __pycache__/
11
+ *.egg-info/
12
+ dist/
13
+ .venv/
14
+ .pytest_cache/
@@ -0,0 +1,113 @@
1
+ Metadata-Version: 2.5
2
+ Name: tether-agents
3
+ Version: 0.3.0
4
+ Summary: Python client for Tether: run agents you don't trust on infrastructure you do.
5
+ Project-URL: Repository, https://github.com/chizy7/tether
6
+ License-Expression: Apache-2.0
7
+ Requires-Python: >=3.9
8
+ Requires-Dist: grpcio>=1.85.3
9
+ Requires-Dist: protobuf<8,>=7.35.1
10
+ Provides-Extra: dev
11
+ Requires-Dist: grpcio-tools==1.85.3; extra == 'dev'
12
+ Requires-Dist: pytest>=8; extra == 'dev'
13
+ Description-Content-Type: text/markdown
14
+
15
+ # tether-agents
16
+
17
+ Python client for [Tether](https://github.com/chizy7/tether/tree/master/README.md). Your agent keeps its own loop;
18
+ it calls `run.complete` where it called its provider SDK and `run.call_tool`
19
+ where it ran a tool, and Tether does the rest: policy, sandbox, budgets and
20
+ the trace.
21
+
22
+ ```python
23
+ import tether
24
+
25
+ with tether.Run(policy="tether.toml") as run:
26
+ messages = [tether.user("Write hello.txt, then show me what is in it.")]
27
+ while True:
28
+ reply = run.complete(model="claude-opus-5-5", messages=messages)
29
+ messages.append(reply.message)
30
+ if not reply.tool_calls:
31
+ run.finish(reply.text)
32
+ break
33
+ results = [run.call_tool(call) for call in reply.tool_calls]
34
+ messages.append(tether.tool_results(results))
35
+ ```
36
+
37
+ A complete example is in [examples/raw-loop-py](https://github.com/chizy7/tether/tree/master/examples/raw-loop-py).
38
+
39
+ ## Install
40
+
41
+ ```
42
+ pip install tether-agents
43
+ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/chizy7/tether/releases/latest/download/tether-cli-installer.sh | sh
44
+ ```
45
+
46
+ The second line installs the `tether` binary, which carries the daemon the
47
+ SDK talks to. The SDK and the binary should be the same version.
48
+
49
+ To work on the SDK, from a checkout of the repository:
50
+
51
+ ```
52
+ pip install -e sdks/python
53
+ cargo build -p tetherd # the daemon the SDK talks to
54
+ export PATH="$PWD/target/debug:$PATH"
55
+ ```
56
+
57
+ ## How it works
58
+
59
+ The SDK is a thin client for the daemon, `tetherd`, over gRPC on a Unix
60
+ socket. Each method is one request and nothing in the SDK decides anything.
61
+
62
+ `tether.Run(...)` connects to the socket and starts a run. If no daemon
63
+ answers, it starts one: `$TETHERD` if set, else `tetherd` or `tether daemon`
64
+ from `PATH`. The daemon logs to `tetherd.log` beside the socket and exits by
65
+ itself a few seconds after its last run.
66
+
67
+ | | |
68
+ | --- | --- |
69
+ | `Run(policy=, provider=, script=, dir=, workspace=, agent=, betas=, socket=)` | Start a run. `provider` is `"anthropic"`, `"openai_compat"` (any server with an OpenAI-style `/chat/completions`, set by `OPENAI_BASE_URL` and `OPENAI_API_KEY`) or, with `script`, `"fake"` |
70
+ | `run.tools` | The tools the run offers |
71
+ | `run.complete(model=, messages=, tools=, params=)` | One model turn. Returns a `Reply` |
72
+ | `run.call_tool(call)` | Run a tool the model asked for. Returns a `ToolResult` |
73
+ | `run.finish(outcome)` | The agent is done |
74
+ | `run.halt()` | Trip the run's kill switch |
75
+ | `run.answer(subject_seq, allow)` | Answer a policy ask, from another thread |
76
+ | `run.events()` | Iterate the trace as it is written |
77
+ | `run.id`, `run.trace_path` | The run's id and where its trace is |
78
+
79
+ Used as a context manager, a run that leaves its block without a word is
80
+ finished, or halted if the block raised.
81
+
82
+ Things to know:
83
+
84
+ - Append `reply.message` to your history exactly as it is. It can hold blocks
85
+ only the provider understands, such as reasoning blocks, which must go back
86
+ unchanged.
87
+ - Check `reply.stop_reason` before acting. `refusal` and `max_tokens` are
88
+ replies that are not finished answers.
89
+ - A tool call that policy denies does not raise. It comes back as a
90
+ `ToolResult` with `is_error` set, like any other failed call.
91
+ - `tether.Halted` is raised when the run takes no more calls: a spent budget,
92
+ an unanswered ask, the kill switch, a provider failure. Anything else the
93
+ daemon refuses raises `tether.TetherError` with the gRPC status in `.code`.
94
+ - Arguments left unset fall back to `TETHER_POLICY`, `TETHER_DIR` and
95
+ `TETHER_SOCKET`, which `tether run -- python agent.py` sets.
96
+
97
+ ## Develop
98
+
99
+ ```
100
+ cd sdks/python
101
+ uv venv && uv pip install -e ".[dev]"
102
+ cargo build -p tetherd
103
+ .venv/bin/python -m pytest
104
+ ```
105
+
106
+ The tests start a real daemon from `target/debug/tetherd` and use the
107
+ scripted model, so they need no API key. The gRPC stubs in
108
+ `src/tether/_proto` are generated and committed; regenerate them after a
109
+ change to `proto/tether.proto`:
110
+
111
+ ```
112
+ uv run --no-project --with grpcio-tools sh scripts/gen_proto.sh
113
+ ```
@@ -0,0 +1,99 @@
1
+ # tether-agents
2
+
3
+ Python client for [Tether](https://github.com/chizy7/tether/tree/master/README.md). Your agent keeps its own loop;
4
+ it calls `run.complete` where it called its provider SDK and `run.call_tool`
5
+ where it ran a tool, and Tether does the rest: policy, sandbox, budgets and
6
+ the trace.
7
+
8
+ ```python
9
+ import tether
10
+
11
+ with tether.Run(policy="tether.toml") as run:
12
+ messages = [tether.user("Write hello.txt, then show me what is in it.")]
13
+ while True:
14
+ reply = run.complete(model="claude-opus-5-5", messages=messages)
15
+ messages.append(reply.message)
16
+ if not reply.tool_calls:
17
+ run.finish(reply.text)
18
+ break
19
+ results = [run.call_tool(call) for call in reply.tool_calls]
20
+ messages.append(tether.tool_results(results))
21
+ ```
22
+
23
+ A complete example is in [examples/raw-loop-py](https://github.com/chizy7/tether/tree/master/examples/raw-loop-py).
24
+
25
+ ## Install
26
+
27
+ ```
28
+ pip install tether-agents
29
+ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/chizy7/tether/releases/latest/download/tether-cli-installer.sh | sh
30
+ ```
31
+
32
+ The second line installs the `tether` binary, which carries the daemon the
33
+ SDK talks to. The SDK and the binary should be the same version.
34
+
35
+ To work on the SDK, from a checkout of the repository:
36
+
37
+ ```
38
+ pip install -e sdks/python
39
+ cargo build -p tetherd # the daemon the SDK talks to
40
+ export PATH="$PWD/target/debug:$PATH"
41
+ ```
42
+
43
+ ## How it works
44
+
45
+ The SDK is a thin client for the daemon, `tetherd`, over gRPC on a Unix
46
+ socket. Each method is one request and nothing in the SDK decides anything.
47
+
48
+ `tether.Run(...)` connects to the socket and starts a run. If no daemon
49
+ answers, it starts one: `$TETHERD` if set, else `tetherd` or `tether daemon`
50
+ from `PATH`. The daemon logs to `tetherd.log` beside the socket and exits by
51
+ itself a few seconds after its last run.
52
+
53
+ | | |
54
+ | --- | --- |
55
+ | `Run(policy=, provider=, script=, dir=, workspace=, agent=, betas=, socket=)` | Start a run. `provider` is `"anthropic"`, `"openai_compat"` (any server with an OpenAI-style `/chat/completions`, set by `OPENAI_BASE_URL` and `OPENAI_API_KEY`) or, with `script`, `"fake"` |
56
+ | `run.tools` | The tools the run offers |
57
+ | `run.complete(model=, messages=, tools=, params=)` | One model turn. Returns a `Reply` |
58
+ | `run.call_tool(call)` | Run a tool the model asked for. Returns a `ToolResult` |
59
+ | `run.finish(outcome)` | The agent is done |
60
+ | `run.halt()` | Trip the run's kill switch |
61
+ | `run.answer(subject_seq, allow)` | Answer a policy ask, from another thread |
62
+ | `run.events()` | Iterate the trace as it is written |
63
+ | `run.id`, `run.trace_path` | The run's id and where its trace is |
64
+
65
+ Used as a context manager, a run that leaves its block without a word is
66
+ finished, or halted if the block raised.
67
+
68
+ Things to know:
69
+
70
+ - Append `reply.message` to your history exactly as it is. It can hold blocks
71
+ only the provider understands, such as reasoning blocks, which must go back
72
+ unchanged.
73
+ - Check `reply.stop_reason` before acting. `refusal` and `max_tokens` are
74
+ replies that are not finished answers.
75
+ - A tool call that policy denies does not raise. It comes back as a
76
+ `ToolResult` with `is_error` set, like any other failed call.
77
+ - `tether.Halted` is raised when the run takes no more calls: a spent budget,
78
+ an unanswered ask, the kill switch, a provider failure. Anything else the
79
+ daemon refuses raises `tether.TetherError` with the gRPC status in `.code`.
80
+ - Arguments left unset fall back to `TETHER_POLICY`, `TETHER_DIR` and
81
+ `TETHER_SOCKET`, which `tether run -- python agent.py` sets.
82
+
83
+ ## Develop
84
+
85
+ ```
86
+ cd sdks/python
87
+ uv venv && uv pip install -e ".[dev]"
88
+ cargo build -p tetherd
89
+ .venv/bin/python -m pytest
90
+ ```
91
+
92
+ The tests start a real daemon from `target/debug/tetherd` and use the
93
+ scripted model, so they need no API key. The gRPC stubs in
94
+ `src/tether/_proto` are generated and committed; regenerate them after a
95
+ change to `proto/tether.proto`:
96
+
97
+ ```
98
+ uv run --no-project --with grpcio-tools sh scripts/gen_proto.sh
99
+ ```
@@ -0,0 +1,30 @@
1
+ [project]
2
+ name = "tether-agents"
3
+ version = "0.3.0"
4
+ description = "Python client for Tether: run agents you don't trust on infrastructure you do."
5
+ readme = "README.md"
6
+ license = "Apache-2.0"
7
+ requires-python = ">=3.9"
8
+ dependencies = [
9
+ # The committed stubs in tether/_proto were generated with these versions
10
+ # and refuse to load on older ones. Regenerate with scripts/gen_proto.sh.
11
+ "grpcio>=1.85.3",
12
+ "protobuf>=7.35.1,<8",
13
+ ]
14
+
15
+ [project.optional-dependencies]
16
+ # grpcio-tools is pinned so regenerating the stubs gives the committed bytes.
17
+ dev = ["pytest>=8", "grpcio-tools==1.85.3"]
18
+
19
+ [project.urls]
20
+ Repository = "https://github.com/chizy7/tether"
21
+
22
+ [build-system]
23
+ requires = ["hatchling"]
24
+ build-backend = "hatchling.build"
25
+
26
+ [tool.hatch.build.targets.wheel]
27
+ packages = ["src/tether"]
28
+
29
+ [tool.pytest.ini_options]
30
+ testpaths = ["tests"]
@@ -0,0 +1,18 @@
1
+ #!/bin/sh
2
+ # Regenerate the gRPC stubs from proto/tether.proto. Run from anywhere:
3
+ #
4
+ # uv run --with grpcio-tools sdks/python/scripts/gen_proto.sh
5
+ #
6
+ # The generated files are committed, so users of the SDK never need protoc.
7
+ set -eu
8
+ here=$(cd "$(dirname "$0")/.." && pwd)
9
+ out="$here/src/tether/_proto"
10
+ python -m grpc_tools.protoc \
11
+ --proto_path="$here/../../proto" \
12
+ --python_out="$out" \
13
+ --grpc_python_out="$out" \
14
+ tether.proto
15
+ # The generated service module imports its sibling as a top-level module.
16
+ # Make that import relative so the stubs work inside the package.
17
+ sed -i.bak 's/^import tether_pb2 as/from . import tether_pb2 as/' "$out/tether_pb2_grpc.py"
18
+ rm -f "$out/tether_pb2_grpc.py.bak"
@@ -0,0 +1,50 @@
1
+ """Python client for Tether.
2
+
3
+ Your agent keeps its own loop. It calls :meth:`Run.complete` where it called
4
+ its provider SDK and :meth:`Run.call_tool` where it ran a tool, and Tether
5
+ does the rest: policy, sandbox, budgets and the trace.
6
+
7
+ import tether
8
+
9
+ with tether.Run(policy="tether.toml") as run:
10
+ messages = [tether.user("Write hello.txt, then show me what is in it.")]
11
+ while True:
12
+ reply = run.complete(model="claude-opus-5-5", messages=messages)
13
+ messages.append(reply.message)
14
+ if not reply.tool_calls:
15
+ run.finish(reply.text)
16
+ break
17
+ results = [run.call_tool(call) for call in reply.tool_calls]
18
+ messages.append(tether.tool_results(results))
19
+
20
+ This module is a thin client for the daemon, ``tetherd``. Nothing here
21
+ decides anything: every call is one gRPC request.
22
+ """
23
+
24
+ from ._run import (
25
+ Event,
26
+ Halted,
27
+ Reply,
28
+ Run,
29
+ TetherError,
30
+ Tool,
31
+ ToolCall,
32
+ ToolResult,
33
+ system,
34
+ tool_results,
35
+ user,
36
+ )
37
+
38
+ __all__ = [
39
+ "Event",
40
+ "Halted",
41
+ "Reply",
42
+ "Run",
43
+ "TetherError",
44
+ "Tool",
45
+ "ToolCall",
46
+ "ToolResult",
47
+ "system",
48
+ "tool_results",
49
+ "user",
50
+ ]
File without changes
@@ -0,0 +1,62 @@
1
+ # -*- coding: utf-8 -*-
2
+ # Generated by the protocol buffer compiler. DO NOT EDIT!
3
+ # NO CHECKED-IN PROTOBUF GENCODE
4
+ # source: tether.proto
5
+ # Protobuf Python Version: 7.35.1
6
+ """Generated protocol buffer code."""
7
+ from google.protobuf import descriptor as _descriptor
8
+ from google.protobuf import descriptor_pool as _descriptor_pool
9
+ from google.protobuf import runtime_version as _runtime_version
10
+ from google.protobuf import symbol_database as _symbol_database
11
+ from google.protobuf.internal import builder as _builder
12
+ _runtime_version.ValidateProtobufRuntimeVersion(
13
+ _runtime_version.Domain.PUBLIC,
14
+ 7,
15
+ 35,
16
+ 1,
17
+ '',
18
+ 'tether.proto'
19
+ )
20
+ # @@protoc_insertion_point(imports)
21
+
22
+ _sym_db = _symbol_database.Default()
23
+
24
+
25
+
26
+
27
+ DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0ctether.proto\x12\ttether.v1\"\x07\n\x05\x45mpty\"\x18\n\x06RunRef\x12\x0e\n\x06run_id\x18\x01 \x01(\t\"\x9d\x01\n\x10\x43reateRunRequest\x12\r\n\x05\x61gent\x18\x01 \x01(\t\x12\x13\n\x0bpolicy_path\x18\x02 \x01(\t\x12\x0f\n\x07sandbox\x18\x03 \x01(\t\x12\x11\n\tworkspace\x18\x04 \x01(\t\x12\x10\n\x08provider\x18\x05 \x01(\t\x12\x13\n\x0bscript_path\x18\x06 \x01(\t\x12\x0b\n\x03\x64ir\x18\x07 \x01(\t\x12\r\n\x05\x62\x65tas\x18\x08 \x03(\t\"M\n\x03Run\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12\x12\n\ntrace_path\x18\x02 \x01(\t\x12\"\n\x05tools\x18\x03 \x03(\x0b\x32\x13.tether.v1.ToolSpec\"X\n\x08ToolSpec\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0e\n\x06server\x18\x02 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x03 \x01(\t\x12\x19\n\x11input_schema_json\x18\x04 \x01(\t\"h\n\x0cModelRequest\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12\r\n\x05model\x18\x02 \x01(\t\x12\x15\n\rmessages_json\x18\x03 \x01(\t\x12\r\n\x05tools\x18\x04 \x03(\t\x12\x13\n\x0bparams_json\x18\x05 \x01(\t\"\xcd\x01\n\rModelResponse\x12\x14\n\x0cmessage_json\x18\x01 \x01(\t\x12\'\n\ntool_calls\x18\x02 \x03(\x0b\x32\x13.tether.v1.ToolCall\x12\x14\n\x0cinput_tokens\x18\x03 \x01(\x04\x12\x15\n\routput_tokens\x18\x04 \x01(\x04\x12\x13\n\x0bstop_reason\x18\x06 \x01(\t\x12\x19\n\x11\x63\x61\x63he_read_tokens\x18\x07 \x01(\x04\x12\x1a\n\x12\x63\x61\x63he_write_tokens\x18\x08 \x01(\x04J\x04\x08\x05\x10\x06\"<\n\x08ToolCall\x12\n\n\x02id\x18\x01 \x01(\t\x12\x0c\n\x04name\x18\x02 \x01(\t\x12\x16\n\x0e\x61rguments_json\x18\x03 \x01(\t\"D\n\x0fToolCallRequest\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12!\n\x04\x63\x61ll\x18\x02 \x01(\x0b\x32\x13.tether.v1.ToolCall\"U\n\nToolResult\x12\n\n\x02id\x18\x01 \x01(\t\x12\x14\n\x0c\x63ontent_json\x18\x02 \x01(\t\x12\x10\n\x08is_error\x18\x03 \x01(\x08\x12\x13\n\x0b\x64uration_ms\x18\x04 \x01(\x04\"5\n\rFinishRequest\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12\x14\n\x0coutcome_json\x18\x02 \x01(\t\"0\n\x05\x45vent\x12\x0b\n\x03seq\x18\x01 \x01(\x04\x12\x0c\n\x04type\x18\x02 \x01(\t\x12\x0c\n\x04json\x18\x03 \x01(\t\"T\n\tAskAnswer\x12\x0e\n\x06run_id\x18\x01 \x01(\t\x12\x13\n\x0bsubject_seq\x18\x02 \x01(\x04\x12\r\n\x05\x61llow\x18\x03 \x01(\x08\x12\x13\n\x0b\x61nswered_by\x18\x04 \x01(\t2\x86\x03\n\x06Tether\x12\x38\n\tCreateRun\x12\x1b.tether.v1.CreateRunRequest\x1a\x0e.tether.v1.Run\x12=\n\x08\x43omplete\x12\x17.tether.v1.ModelRequest\x1a\x18.tether.v1.ModelResponse\x12=\n\x08\x43\x61llTool\x12\x1a.tether.v1.ToolCallRequest\x1a\x15.tether.v1.ToolResult\x12\x34\n\x06\x46inish\x12\x18.tether.v1.FinishRequest\x1a\x10.tether.v1.Empty\x12/\n\x06\x45vents\x12\x11.tether.v1.RunRef\x1a\x10.tether.v1.Event0\x01\x12\x30\n\x06\x41nswer\x12\x14.tether.v1.AskAnswer\x1a\x10.tether.v1.Empty\x12+\n\x04Halt\x12\x11.tether.v1.RunRef\x1a\x10.tether.v1.Emptyb\x06proto3')
28
+
29
+ _globals = globals()
30
+ _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
31
+ _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'tether_pb2', _globals)
32
+ if not _descriptor._USE_C_DESCRIPTORS:
33
+ DESCRIPTOR._loaded_options = None
34
+ _globals['_EMPTY']._serialized_start=27
35
+ _globals['_EMPTY']._serialized_end=34
36
+ _globals['_RUNREF']._serialized_start=36
37
+ _globals['_RUNREF']._serialized_end=60
38
+ _globals['_CREATERUNREQUEST']._serialized_start=63
39
+ _globals['_CREATERUNREQUEST']._serialized_end=220
40
+ _globals['_RUN']._serialized_start=222
41
+ _globals['_RUN']._serialized_end=299
42
+ _globals['_TOOLSPEC']._serialized_start=301
43
+ _globals['_TOOLSPEC']._serialized_end=389
44
+ _globals['_MODELREQUEST']._serialized_start=391
45
+ _globals['_MODELREQUEST']._serialized_end=495
46
+ _globals['_MODELRESPONSE']._serialized_start=498
47
+ _globals['_MODELRESPONSE']._serialized_end=703
48
+ _globals['_TOOLCALL']._serialized_start=705
49
+ _globals['_TOOLCALL']._serialized_end=765
50
+ _globals['_TOOLCALLREQUEST']._serialized_start=767
51
+ _globals['_TOOLCALLREQUEST']._serialized_end=835
52
+ _globals['_TOOLRESULT']._serialized_start=837
53
+ _globals['_TOOLRESULT']._serialized_end=922
54
+ _globals['_FINISHREQUEST']._serialized_start=924
55
+ _globals['_FINISHREQUEST']._serialized_end=977
56
+ _globals['_EVENT']._serialized_start=979
57
+ _globals['_EVENT']._serialized_end=1027
58
+ _globals['_ASKANSWER']._serialized_start=1029
59
+ _globals['_ASKANSWER']._serialized_end=1113
60
+ _globals['_TETHER']._serialized_start=1116
61
+ _globals['_TETHER']._serialized_end=1506
62
+ # @@protoc_insertion_point(module_scope)
@@ -0,0 +1,370 @@
1
+ # Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
2
+ """Client and server classes corresponding to protobuf-defined services."""
3
+ import grpc
4
+ import warnings
5
+
6
+ from . import tether_pb2 as tether__pb2
7
+
8
+ GRPC_GENERATED_VERSION = '1.85.3'
9
+ GRPC_VERSION = grpc.__version__
10
+ _version_not_supported = False
11
+
12
+ try:
13
+ from grpc._utilities import first_version_is_lower
14
+ _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
15
+ except ImportError:
16
+ _version_not_supported = True
17
+
18
+ if _version_not_supported:
19
+ raise RuntimeError(
20
+ f'The grpc package installed is at version {GRPC_VERSION},'
21
+ + ' but the generated code in tether_pb2_grpc.py depends on'
22
+ + f' grpcio>={GRPC_GENERATED_VERSION}.'
23
+ + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
24
+ + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
25
+ )
26
+
27
+
28
+ class TetherStub:
29
+ """The whole SDK surface. The agent's loop stays in the user's code; it calls
30
+ Complete and CallTool instead of a provider SDK and its own tool functions.
31
+ No logic lives in an SDK beyond type mapping.
32
+ """
33
+
34
+ def __init__(self, channel):
35
+ """Constructor.
36
+
37
+ Args:
38
+ channel: A grpc.Channel.
39
+ """
40
+ self.CreateRun = channel.unary_unary(
41
+ '/tether.v1.Tether/CreateRun',
42
+ request_serializer=tether__pb2.CreateRunRequest.SerializeToString,
43
+ response_deserializer=tether__pb2.Run.FromString,
44
+ _registered_method=True)
45
+ self.Complete = channel.unary_unary(
46
+ '/tether.v1.Tether/Complete',
47
+ request_serializer=tether__pb2.ModelRequest.SerializeToString,
48
+ response_deserializer=tether__pb2.ModelResponse.FromString,
49
+ _registered_method=True)
50
+ self.CallTool = channel.unary_unary(
51
+ '/tether.v1.Tether/CallTool',
52
+ request_serializer=tether__pb2.ToolCallRequest.SerializeToString,
53
+ response_deserializer=tether__pb2.ToolResult.FromString,
54
+ _registered_method=True)
55
+ self.Finish = channel.unary_unary(
56
+ '/tether.v1.Tether/Finish',
57
+ request_serializer=tether__pb2.FinishRequest.SerializeToString,
58
+ response_deserializer=tether__pb2.Empty.FromString,
59
+ _registered_method=True)
60
+ self.Events = channel.unary_stream(
61
+ '/tether.v1.Tether/Events',
62
+ request_serializer=tether__pb2.RunRef.SerializeToString,
63
+ response_deserializer=tether__pb2.Event.FromString,
64
+ _registered_method=True)
65
+ self.Answer = channel.unary_unary(
66
+ '/tether.v1.Tether/Answer',
67
+ request_serializer=tether__pb2.AskAnswer.SerializeToString,
68
+ response_deserializer=tether__pb2.Empty.FromString,
69
+ _registered_method=True)
70
+ self.Halt = channel.unary_unary(
71
+ '/tether.v1.Tether/Halt',
72
+ request_serializer=tether__pb2.RunRef.SerializeToString,
73
+ response_deserializer=tether__pb2.Empty.FromString,
74
+ _registered_method=True)
75
+
76
+
77
+ class TetherServicer:
78
+ """The whole SDK surface. The agent's loop stays in the user's code; it calls
79
+ Complete and CallTool instead of a provider SDK and its own tool functions.
80
+ No logic lives in an SDK beyond type mapping.
81
+ """
82
+
83
+ def CreateRun(self, request, context):
84
+ """Missing associated documentation comment in .proto file."""
85
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
86
+ context.set_details('Method not implemented!')
87
+ raise NotImplementedError('Method not implemented!')
88
+
89
+ def Complete(self, request, context):
90
+ """Agent asks for a model turn.
91
+ """
92
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
93
+ context.set_details('Method not implemented!')
94
+ raise NotImplementedError('Method not implemented!')
95
+
96
+ def CallTool(self, request, context):
97
+ """Agent asks for a tool. Policy, sandbox and trace all happen here.
98
+ """
99
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
100
+ context.set_details('Method not implemented!')
101
+ raise NotImplementedError('Method not implemented!')
102
+
103
+ def Finish(self, request, context):
104
+ """The agent is done. Records run.finished and closes the trace.
105
+ """
106
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
107
+ context.set_details('Method not implemented!')
108
+ raise NotImplementedError('Method not implemented!')
109
+
110
+ def Events(self, request, context):
111
+ """Tail the trace: every event so far, then each new one until the run ends.
112
+ """
113
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
114
+ context.set_details('Method not implemented!')
115
+ raise NotImplementedError('Method not implemented!')
116
+
117
+ def Answer(self, request, context):
118
+ """Resolve a policy.ask. The Complete or CallTool that asked is waiting.
119
+ """
120
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
121
+ context.set_details('Method not implemented!')
122
+ raise NotImplementedError('Method not implemented!')
123
+
124
+ def Halt(self, request, context):
125
+ """Trip the run's kill switch. It halts at its next event boundary.
126
+ """
127
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
128
+ context.set_details('Method not implemented!')
129
+ raise NotImplementedError('Method not implemented!')
130
+
131
+
132
+ def add_TetherServicer_to_server(servicer, server):
133
+ rpc_method_handlers = {
134
+ 'CreateRun': grpc.unary_unary_rpc_method_handler(
135
+ servicer.CreateRun,
136
+ request_deserializer=tether__pb2.CreateRunRequest.FromString,
137
+ response_serializer=tether__pb2.Run.SerializeToString,
138
+ ),
139
+ 'Complete': grpc.unary_unary_rpc_method_handler(
140
+ servicer.Complete,
141
+ request_deserializer=tether__pb2.ModelRequest.FromString,
142
+ response_serializer=tether__pb2.ModelResponse.SerializeToString,
143
+ ),
144
+ 'CallTool': grpc.unary_unary_rpc_method_handler(
145
+ servicer.CallTool,
146
+ request_deserializer=tether__pb2.ToolCallRequest.FromString,
147
+ response_serializer=tether__pb2.ToolResult.SerializeToString,
148
+ ),
149
+ 'Finish': grpc.unary_unary_rpc_method_handler(
150
+ servicer.Finish,
151
+ request_deserializer=tether__pb2.FinishRequest.FromString,
152
+ response_serializer=tether__pb2.Empty.SerializeToString,
153
+ ),
154
+ 'Events': grpc.unary_stream_rpc_method_handler(
155
+ servicer.Events,
156
+ request_deserializer=tether__pb2.RunRef.FromString,
157
+ response_serializer=tether__pb2.Event.SerializeToString,
158
+ ),
159
+ 'Answer': grpc.unary_unary_rpc_method_handler(
160
+ servicer.Answer,
161
+ request_deserializer=tether__pb2.AskAnswer.FromString,
162
+ response_serializer=tether__pb2.Empty.SerializeToString,
163
+ ),
164
+ 'Halt': grpc.unary_unary_rpc_method_handler(
165
+ servicer.Halt,
166
+ request_deserializer=tether__pb2.RunRef.FromString,
167
+ response_serializer=tether__pb2.Empty.SerializeToString,
168
+ ),
169
+ }
170
+ generic_handler = grpc.method_handlers_generic_handler(
171
+ 'tether.v1.Tether', rpc_method_handlers)
172
+ server.add_generic_rpc_handlers((generic_handler,))
173
+ server.add_registered_method_handlers('tether.v1.Tether', rpc_method_handlers)
174
+
175
+
176
+ # This class is part of an EXPERIMENTAL API.
177
+ class Tether:
178
+ """The whole SDK surface. The agent's loop stays in the user's code; it calls
179
+ Complete and CallTool instead of a provider SDK and its own tool functions.
180
+ No logic lives in an SDK beyond type mapping.
181
+ """
182
+
183
+ @staticmethod
184
+ def CreateRun(request,
185
+ target,
186
+ options=(),
187
+ channel_credentials=None,
188
+ call_credentials=None,
189
+ insecure=False,
190
+ compression=None,
191
+ wait_for_ready=None,
192
+ timeout=None,
193
+ metadata=None):
194
+ return grpc.experimental.unary_unary(
195
+ request,
196
+ target,
197
+ '/tether.v1.Tether/CreateRun',
198
+ tether__pb2.CreateRunRequest.SerializeToString,
199
+ tether__pb2.Run.FromString,
200
+ options,
201
+ channel_credentials,
202
+ insecure,
203
+ call_credentials,
204
+ compression,
205
+ wait_for_ready,
206
+ timeout,
207
+ metadata,
208
+ _registered_method=True)
209
+
210
+ @staticmethod
211
+ def Complete(request,
212
+ target,
213
+ options=(),
214
+ channel_credentials=None,
215
+ call_credentials=None,
216
+ insecure=False,
217
+ compression=None,
218
+ wait_for_ready=None,
219
+ timeout=None,
220
+ metadata=None):
221
+ return grpc.experimental.unary_unary(
222
+ request,
223
+ target,
224
+ '/tether.v1.Tether/Complete',
225
+ tether__pb2.ModelRequest.SerializeToString,
226
+ tether__pb2.ModelResponse.FromString,
227
+ options,
228
+ channel_credentials,
229
+ insecure,
230
+ call_credentials,
231
+ compression,
232
+ wait_for_ready,
233
+ timeout,
234
+ metadata,
235
+ _registered_method=True)
236
+
237
+ @staticmethod
238
+ def CallTool(request,
239
+ target,
240
+ options=(),
241
+ channel_credentials=None,
242
+ call_credentials=None,
243
+ insecure=False,
244
+ compression=None,
245
+ wait_for_ready=None,
246
+ timeout=None,
247
+ metadata=None):
248
+ return grpc.experimental.unary_unary(
249
+ request,
250
+ target,
251
+ '/tether.v1.Tether/CallTool',
252
+ tether__pb2.ToolCallRequest.SerializeToString,
253
+ tether__pb2.ToolResult.FromString,
254
+ options,
255
+ channel_credentials,
256
+ insecure,
257
+ call_credentials,
258
+ compression,
259
+ wait_for_ready,
260
+ timeout,
261
+ metadata,
262
+ _registered_method=True)
263
+
264
+ @staticmethod
265
+ def Finish(request,
266
+ target,
267
+ options=(),
268
+ channel_credentials=None,
269
+ call_credentials=None,
270
+ insecure=False,
271
+ compression=None,
272
+ wait_for_ready=None,
273
+ timeout=None,
274
+ metadata=None):
275
+ return grpc.experimental.unary_unary(
276
+ request,
277
+ target,
278
+ '/tether.v1.Tether/Finish',
279
+ tether__pb2.FinishRequest.SerializeToString,
280
+ tether__pb2.Empty.FromString,
281
+ options,
282
+ channel_credentials,
283
+ insecure,
284
+ call_credentials,
285
+ compression,
286
+ wait_for_ready,
287
+ timeout,
288
+ metadata,
289
+ _registered_method=True)
290
+
291
+ @staticmethod
292
+ def Events(request,
293
+ target,
294
+ options=(),
295
+ channel_credentials=None,
296
+ call_credentials=None,
297
+ insecure=False,
298
+ compression=None,
299
+ wait_for_ready=None,
300
+ timeout=None,
301
+ metadata=None):
302
+ return grpc.experimental.unary_stream(
303
+ request,
304
+ target,
305
+ '/tether.v1.Tether/Events',
306
+ tether__pb2.RunRef.SerializeToString,
307
+ tether__pb2.Event.FromString,
308
+ options,
309
+ channel_credentials,
310
+ insecure,
311
+ call_credentials,
312
+ compression,
313
+ wait_for_ready,
314
+ timeout,
315
+ metadata,
316
+ _registered_method=True)
317
+
318
+ @staticmethod
319
+ def Answer(request,
320
+ target,
321
+ options=(),
322
+ channel_credentials=None,
323
+ call_credentials=None,
324
+ insecure=False,
325
+ compression=None,
326
+ wait_for_ready=None,
327
+ timeout=None,
328
+ metadata=None):
329
+ return grpc.experimental.unary_unary(
330
+ request,
331
+ target,
332
+ '/tether.v1.Tether/Answer',
333
+ tether__pb2.AskAnswer.SerializeToString,
334
+ tether__pb2.Empty.FromString,
335
+ options,
336
+ channel_credentials,
337
+ insecure,
338
+ call_credentials,
339
+ compression,
340
+ wait_for_ready,
341
+ timeout,
342
+ metadata,
343
+ _registered_method=True)
344
+
345
+ @staticmethod
346
+ def Halt(request,
347
+ target,
348
+ options=(),
349
+ channel_credentials=None,
350
+ call_credentials=None,
351
+ insecure=False,
352
+ compression=None,
353
+ wait_for_ready=None,
354
+ timeout=None,
355
+ metadata=None):
356
+ return grpc.experimental.unary_unary(
357
+ request,
358
+ target,
359
+ '/tether.v1.Tether/Halt',
360
+ tether__pb2.RunRef.SerializeToString,
361
+ tether__pb2.Empty.FromString,
362
+ options,
363
+ channel_credentials,
364
+ insecure,
365
+ call_credentials,
366
+ compression,
367
+ wait_for_ready,
368
+ timeout,
369
+ metadata,
370
+ _registered_method=True)
@@ -0,0 +1,381 @@
1
+ """The client: one class, one gRPC request per method."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import shutil
8
+ import subprocess
9
+ import time
10
+ from dataclasses import dataclass
11
+ from pathlib import Path
12
+ from typing import Any, Iterator, Optional, Sequence, Union
13
+
14
+ import grpc
15
+
16
+ from ._proto import tether_pb2 as pb
17
+ from ._proto import tether_pb2_grpc as pb_grpc
18
+
19
+ DEFAULT_DIR = ".tether"
20
+
21
+ # How long to wait for a daemon this client started to answer on its socket.
22
+ _DAEMON_START_SECS = 10.0
23
+
24
+
25
+ class TetherError(RuntimeError):
26
+ """A call the daemon refused. ``code`` is the gRPC status code."""
27
+
28
+ def __init__(self, code: grpc.StatusCode, message: str) -> None:
29
+ super().__init__(message)
30
+ self.code = code
31
+
32
+
33
+ class Halted(TetherError):
34
+ """The run is halted or finished and takes no more calls.
35
+
36
+ Tether halts a run when a budget is spent, a policy ask goes unanswered,
37
+ the kill switch is tripped or the model fails. The message says which.
38
+ """
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class Tool:
43
+ """A tool the run offers, as listed when the run started."""
44
+
45
+ name: str
46
+ server: str
47
+ description: str
48
+ input_schema: Any
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class ToolCall:
53
+ """A tool the model asked for."""
54
+
55
+ id: str
56
+ name: str
57
+ arguments: Any
58
+
59
+
60
+ @dataclass(frozen=True)
61
+ class ToolResult:
62
+ """What a tool call came to.
63
+
64
+ A call that policy denied comes back here with ``is_error`` set, like any
65
+ other failed call. It does not raise.
66
+ """
67
+
68
+ id: str
69
+ content: Any
70
+ is_error: bool
71
+ duration_ms: int
72
+
73
+ def block(self) -> dict:
74
+ """This result as a content block for the next request's history."""
75
+ return {
76
+ "type": "tool_result",
77
+ "id": self.id,
78
+ "content": self.content,
79
+ "is_error": self.is_error,
80
+ }
81
+
82
+
83
+ @dataclass(frozen=True)
84
+ class Reply:
85
+ """One model turn.
86
+
87
+ Append ``message`` to your history exactly as it is. It can hold blocks
88
+ only the provider understands, which must go back unchanged. Look at
89
+ ``stop_reason`` before acting: ``refusal`` and ``max_tokens`` are replies
90
+ that are not finished answers.
91
+ """
92
+
93
+ message: dict
94
+ tool_calls: list
95
+ stop_reason: Optional[str]
96
+ input_tokens: int
97
+ output_tokens: int
98
+ cache_read_tokens: int
99
+ cache_write_tokens: int
100
+
101
+ @property
102
+ def text(self) -> str:
103
+ """The reply's text blocks, joined."""
104
+ blocks = self.message.get("content", [])
105
+ return "".join(b.get("text", "") for b in blocks if b.get("type") == "text")
106
+
107
+
108
+ @dataclass(frozen=True)
109
+ class Event:
110
+ """One event of the trace."""
111
+
112
+ seq: int
113
+ type: str
114
+ data: dict
115
+
116
+
117
+ def user(text: str) -> dict:
118
+ """A user message holding ``text``."""
119
+ return {"role": "user", "content": [{"type": "text", "text": text}]}
120
+
121
+
122
+ def system(text: str) -> dict:
123
+ """A system message holding ``text``. Put it first to make it the system prompt."""
124
+ return {"role": "system", "content": [{"type": "text", "text": text}]}
125
+
126
+
127
+ def tool_results(results: Sequence[ToolResult]) -> dict:
128
+ """The message that hands a turn's tool results back to the model."""
129
+ return {"role": "tool", "content": [result.block() for result in results]}
130
+
131
+
132
+ def _raise(error: grpc.RpcError) -> None:
133
+ code, message = error.code(), error.details() or ""
134
+ if code == grpc.StatusCode.FAILED_PRECONDITION:
135
+ raise Halted(code, message) from None
136
+ raise TetherError(code, message) from None
137
+
138
+
139
+ def _daemon_command() -> list:
140
+ """The command that starts the daemon: ``tetherd``, or ``tether daemon``."""
141
+ override = os.environ.get("TETHERD")
142
+ if override:
143
+ return [override]
144
+ if shutil.which("tetherd"):
145
+ return ["tetherd"]
146
+ if shutil.which("tether"):
147
+ return ["tether", "daemon"]
148
+ raise TetherError(
149
+ grpc.StatusCode.UNAVAILABLE,
150
+ "no daemon is running and neither tetherd nor tether is on PATH; "
151
+ "set TETHERD to the tetherd binary",
152
+ )
153
+
154
+
155
+ def _connect(socket: Path) -> grpc.Channel:
156
+ """A channel to the daemon on ``socket``, starting the daemon if needed."""
157
+
158
+ def ready(channel: grpc.Channel, seconds: float) -> bool:
159
+ try:
160
+ grpc.channel_ready_future(channel).result(timeout=seconds)
161
+ return True
162
+ except grpc.FutureTimeoutError:
163
+ return False
164
+
165
+ target = f"unix:{socket}"
166
+ # Over a Unix socket gRPC would send the socket's path as the HTTP/2
167
+ # authority, which the daemon's HTTP stack rejects. Name one instead.
168
+ options = [("grpc.default_authority", "localhost")]
169
+ channel = grpc.insecure_channel(target, options)
170
+ if socket.exists() and ready(channel, 1.0):
171
+ return channel
172
+ channel.close()
173
+
174
+ socket.parent.mkdir(parents=True, exist_ok=True)
175
+ with open(socket.parent / "tetherd.log", "ab") as log:
176
+ subprocess.Popen(
177
+ _daemon_command() + ["--socket", str(socket)],
178
+ stdin=subprocess.DEVNULL,
179
+ stdout=log,
180
+ stderr=log,
181
+ # Its own session, so it outlives this process and its Ctrl-C.
182
+ start_new_session=True,
183
+ )
184
+ deadline = time.monotonic() + _DAEMON_START_SECS
185
+ while time.monotonic() < deadline:
186
+ if socket.exists():
187
+ channel = grpc.insecure_channel(target, options)
188
+ if ready(channel, 1.0):
189
+ return channel
190
+ channel.close()
191
+ time.sleep(0.05)
192
+ raise TetherError(
193
+ grpc.StatusCode.UNAVAILABLE,
194
+ f"the daemon did not come up on {socket}; see {socket.parent / 'tetherd.log'}",
195
+ )
196
+
197
+
198
+ class Run:
199
+ """A run under Tether.
200
+
201
+ Creating one starts the run. Use it as a context manager: leaving the
202
+ block finishes the run, or halts it if the block raised.
203
+
204
+ ``policy`` is the path of a ``tether.toml``; without one there are no
205
+ rules and every tool call asks. ``provider`` is ``"anthropic"``,
206
+ ``"openai_compat"`` for a server with an OpenAI-style chat completions
207
+ endpoint (``OPENAI_BASE_URL``, ``OPENAI_API_KEY``) or, for tests and demos, ``"fake"`` with ``script`` naming a file of scripted
208
+ replies. ``dir`` is where the trace goes. Unset arguments fall back to
209
+ ``TETHER_POLICY``, ``TETHER_DIR`` and ``TETHER_SOCKET``, which
210
+ ``tether run -- <command>`` sets.
211
+ """
212
+
213
+ def __init__(
214
+ self,
215
+ *,
216
+ policy: Union[str, os.PathLike, None] = None,
217
+ provider: str = "anthropic",
218
+ script: Union[str, os.PathLike, None] = None,
219
+ dir: Union[str, os.PathLike, None] = None,
220
+ workspace: Union[str, os.PathLike, None] = None,
221
+ agent: str = "main",
222
+ betas: Sequence[str] = (),
223
+ socket: Union[str, os.PathLike, None] = None,
224
+ ) -> None:
225
+ # The daemon may have another working directory: send absolute paths.
226
+ def absolute(path: Union[str, os.PathLike, None]) -> str:
227
+ return str(Path(path).resolve()) if path else ""
228
+
229
+ run_dir = Path(dir or os.environ.get("TETHER_DIR") or DEFAULT_DIR).resolve()
230
+ socket_path = Path(
231
+ socket or os.environ.get("TETHER_SOCKET") or run_dir / "tetherd.sock"
232
+ ).resolve()
233
+ self._channel = _connect(socket_path)
234
+ self._stub = pb_grpc.TetherStub(self._channel)
235
+ self._over = False
236
+ try:
237
+ created = self._stub.CreateRun(
238
+ pb.CreateRunRequest(
239
+ agent=agent,
240
+ policy_path=absolute(policy or os.environ.get("TETHER_POLICY")),
241
+ workspace=absolute(workspace),
242
+ provider=provider,
243
+ script_path=absolute(script),
244
+ dir=str(run_dir),
245
+ betas=list(betas),
246
+ )
247
+ )
248
+ except grpc.RpcError as error:
249
+ self._channel.close()
250
+ _raise(error)
251
+ self.id: str = created.run_id
252
+ self.trace_path: str = created.trace_path
253
+ self.tools: list = [
254
+ Tool(t.name, t.server, t.description, json.loads(t.input_schema_json))
255
+ for t in created.tools
256
+ ]
257
+
258
+ def complete(
259
+ self,
260
+ *,
261
+ model: str,
262
+ messages: Sequence[dict],
263
+ tools: Optional[Sequence[str]] = None,
264
+ params: Optional[dict] = None,
265
+ ) -> Reply:
266
+ """Ask the model for its next turn.
267
+
268
+ ``messages`` is the whole history. ``tools`` names the tools to
269
+ offer; by default all of the run's. ``params`` is passed to the
270
+ provider as the request's other fields (``max_tokens``,
271
+ ``output_config`` and so on).
272
+ """
273
+ names = [tool.name for tool in self.tools] if tools is None else list(tools)
274
+ try:
275
+ response = self._stub.Complete(
276
+ pb.ModelRequest(
277
+ run_id=self.id,
278
+ model=model,
279
+ messages_json=json.dumps(list(messages)),
280
+ tools=names,
281
+ params_json=json.dumps(params) if params else "",
282
+ )
283
+ )
284
+ except grpc.RpcError as error:
285
+ self._over = error.code() == grpc.StatusCode.FAILED_PRECONDITION
286
+ _raise(error)
287
+ return Reply(
288
+ message=json.loads(response.message_json),
289
+ tool_calls=[
290
+ ToolCall(c.id, c.name, json.loads(c.arguments_json))
291
+ for c in response.tool_calls
292
+ ],
293
+ stop_reason=response.stop_reason or None,
294
+ input_tokens=response.input_tokens,
295
+ output_tokens=response.output_tokens,
296
+ cache_read_tokens=response.cache_read_tokens,
297
+ cache_write_tokens=response.cache_write_tokens,
298
+ )
299
+
300
+ def call_tool(self, call: ToolCall) -> ToolResult:
301
+ """Run a tool the model asked for, through policy and the sandbox."""
302
+ try:
303
+ result = self._stub.CallTool(
304
+ pb.ToolCallRequest(
305
+ run_id=self.id,
306
+ call=pb.ToolCall(
307
+ id=call.id,
308
+ name=call.name,
309
+ arguments_json=json.dumps(call.arguments),
310
+ ),
311
+ )
312
+ )
313
+ except grpc.RpcError as error:
314
+ self._over = error.code() == grpc.StatusCode.FAILED_PRECONDITION
315
+ _raise(error)
316
+ return ToolResult(
317
+ id=result.id,
318
+ content=json.loads(result.content_json),
319
+ is_error=result.is_error,
320
+ duration_ms=result.duration_ms,
321
+ )
322
+
323
+ def finish(self, outcome: Any = None) -> None:
324
+ """Say the agent is done. ``outcome`` is recorded in the trace."""
325
+ try:
326
+ self._stub.Finish(
327
+ pb.FinishRequest(run_id=self.id, outcome_json=json.dumps(outcome))
328
+ )
329
+ except grpc.RpcError as error:
330
+ _raise(error)
331
+ finally:
332
+ self._over = True
333
+
334
+ def halt(self) -> None:
335
+ """Trip the run's kill switch."""
336
+ try:
337
+ self._stub.Halt(pb.RunRef(run_id=self.id))
338
+ except grpc.RpcError as error:
339
+ _raise(error)
340
+ finally:
341
+ self._over = True
342
+
343
+ def answer(self, subject_seq: int, allow: bool, answered_by: str = "sdk") -> None:
344
+ """Answer a policy ask. The call that asked is waiting in another thread."""
345
+ try:
346
+ self._stub.Answer(
347
+ pb.AskAnswer(
348
+ run_id=self.id,
349
+ subject_seq=subject_seq,
350
+ allow=allow,
351
+ answered_by=answered_by,
352
+ )
353
+ )
354
+ except grpc.RpcError as error:
355
+ _raise(error)
356
+
357
+ def events(self) -> Iterator[Event]:
358
+ """The trace so far, then each new event until the run ends."""
359
+ try:
360
+ for event in self._stub.Events(pb.RunRef(run_id=self.id)):
361
+ yield Event(event.seq, event.type, json.loads(event.json))
362
+ except grpc.RpcError as error:
363
+ _raise(error)
364
+
365
+ def close(self) -> None:
366
+ """Close the connection. The run itself is not affected."""
367
+ self._channel.close()
368
+
369
+ def __enter__(self) -> "Run":
370
+ return self
371
+
372
+ def __exit__(self, exc_type, exc, traceback) -> None:
373
+ try:
374
+ if not self._over:
375
+ # Left without a word: done if the block ended, stopped if it raised.
376
+ if exc_type is None:
377
+ self.finish()
378
+ else:
379
+ self.halt()
380
+ finally:
381
+ self.close()
@@ -0,0 +1,220 @@
1
+ """The SDK against a real daemon, with the scripted model. No API key."""
2
+
3
+ import json
4
+ import os
5
+ import shutil
6
+ import subprocess
7
+ import tempfile
8
+ import threading
9
+ from pathlib import Path
10
+
11
+ import grpc
12
+ import pytest
13
+
14
+ import tether
15
+
16
+ REPO = Path(__file__).resolve().parents[3]
17
+
18
+ SCRIPT = {
19
+ "replies": [
20
+ [{"type": "tool_use", "id": "call_1", "name": "write_file",
21
+ "arguments": {"path": "notes.txt", "content": "from python\n"}}],
22
+ [{"type": "tool_use", "id": "call_2", "name": "exec",
23
+ "arguments": {"argv": ["rm", "notes.txt"]}}],
24
+ [{"type": "text", "text": "Done."}],
25
+ ]
26
+ }
27
+
28
+ POLICY = """
29
+ [[rule]]
30
+ name = "writes"
31
+ match = { tool = "sandbox.write_file" }
32
+ action = "allow"
33
+
34
+ [[rule]]
35
+ name = "no-rm"
36
+ match = { tool = "sandbox.exec", argv0 = "rm" }
37
+ action = "%s"
38
+ """
39
+
40
+
41
+ def tetherd() -> str:
42
+ path = os.environ.get("TETHERD") or str(REPO / "target" / "debug" / "tetherd")
43
+ if not Path(path).exists():
44
+ pytest.fail(f"{path} is not built; run `cargo build -p tetherd` first")
45
+ return path
46
+
47
+
48
+ @pytest.fixture
49
+ def where(monkeypatch):
50
+ """A short-lived directory with a script and a policy, and the daemon
51
+ binary named for the SDK to start. Short path: sockets have a length limit."""
52
+ monkeypatch.setenv("TETHERD", tetherd())
53
+ # Found now: one test empties PATH, and teardown runs before it is restored.
54
+ pkill = shutil.which("pkill")
55
+ for name in ("TETHER_SOCKET", "TETHER_DIR", "TETHER_POLICY"):
56
+ monkeypatch.delenv(name, raising=False)
57
+ with tempfile.TemporaryDirectory(prefix="tsdk") as tmp:
58
+ tmp = Path(tmp)
59
+ (tmp / "script.json").write_text(json.dumps(SCRIPT))
60
+ (tmp / "deny.toml").write_text(POLICY % "deny")
61
+ (tmp / "ask.toml").write_text(POLICY % "ask")
62
+ yield tmp
63
+ # Stop the daemon this test started rather than wait out its idle time.
64
+ if pkill:
65
+ subprocess.run([pkill, "-f", str(tmp / "runs" / "tetherd.sock")], check=False)
66
+
67
+
68
+ def start(where: Path, policy: str = "deny.toml", **kwargs) -> tether.Run:
69
+ return tether.Run(
70
+ policy=where / policy,
71
+ provider="fake",
72
+ script=where / "script.json",
73
+ dir=where / "runs",
74
+ **kwargs,
75
+ )
76
+
77
+
78
+ def trace(run: tether.Run) -> list:
79
+ return [json.loads(line) for line in Path(run.trace_path).read_text().splitlines()]
80
+
81
+
82
+ def test_an_agent_loop_runs_to_the_end(where):
83
+ with start(where) as run:
84
+ assert [tool.name for tool in run.tools] == ["exec", "read_file", "write_file", "list_dir"]
85
+ assert run.tools[0].input_schema["required"] == ["argv"]
86
+
87
+ messages = [tether.system("Be brief."), tether.user("Tidy up.")]
88
+ said = None
89
+ while said is None:
90
+ reply = run.complete(model="fake-1", messages=messages)
91
+ messages.append(reply.message)
92
+ if not reply.tool_calls:
93
+ said = reply.text
94
+ break
95
+ results = [run.call_tool(call) for call in reply.tool_calls]
96
+ messages.append(tether.tool_results(results))
97
+ run.finish(said)
98
+
99
+ assert said == "Done."
100
+ events = trace(run)
101
+ assert events[0]["type"] == "run.created"
102
+ assert events[-1]["type"] == "run.finished"
103
+ assert events[-1]["data"]["outcome"] == "Done."
104
+
105
+ # The write really happened, in the run's own workspace.
106
+ workspace = Path(run.trace_path).with_suffix(".workspace")
107
+ assert (workspace / "notes.txt").read_text() == "from python\n"
108
+
109
+ # The denied `rm` came back as a failed result, not an exception.
110
+ results = [e["data"] for e in events if e["type"] == "tool.result"]
111
+ assert [r["is_error"] for r in results] == [False, True]
112
+ decisions = [e["data"] for e in events if e["type"] == "policy.decision" and e["data"]["rule"]]
113
+ assert [d["rule"] for d in decisions] == ["writes", "no-rm"]
114
+
115
+
116
+ def test_reply_and_tool_result_carry_what_the_daemon_sent(where):
117
+ with start(where) as run:
118
+ reply = run.complete(model="fake-1", messages=[tether.user("Tidy up.")])
119
+ assert reply.message["role"] == "assistant"
120
+ assert reply.text == ""
121
+ assert reply.stop_reason is None
122
+ (call,) = reply.tool_calls
123
+ assert (call.id, call.name) == ("call_1", "write_file")
124
+ assert call.arguments == {"path": "notes.txt", "content": "from python\n"}
125
+
126
+ result = run.call_tool(call)
127
+ assert (result.id, result.is_error, result.content) == ("call_1", False, {"bytes": 12})
128
+ assert result.block() == {
129
+ "type": "tool_result", "id": "call_1", "content": {"bytes": 12}, "is_error": False,
130
+ }
131
+
132
+
133
+ def test_leaving_the_block_finishes_the_run_and_raising_halts_it(where):
134
+ with start(where) as finished:
135
+ finished.complete(model="fake-1", messages=[tether.user("Tidy up.")])
136
+ assert trace(finished)[-1]["type"] == "run.finished"
137
+
138
+ with pytest.raises(ValueError):
139
+ with start(where) as halted:
140
+ halted.complete(model="fake-1", messages=[tether.user("Tidy up.")])
141
+ raise ValueError("the agent broke")
142
+ last = trace(halted)[-1]
143
+ assert (last["type"], last["data"]["state"]) == ("run.state", "halted")
144
+ assert last["data"]["reason"] == "kill switch: halt requested"
145
+
146
+
147
+ def test_a_halted_run_raises_halted(where):
148
+ run = start(where)
149
+ run.halt()
150
+ with pytest.raises(tether.Halted) as error:
151
+ run.complete(model="fake-1", messages=[tether.user("More.")])
152
+ assert error.value.code == grpc.StatusCode.FAILED_PRECONDITION
153
+ with pytest.raises(tether.Halted):
154
+ run.call_tool(tether.ToolCall("x", "exec", {"argv": ["ls"]}))
155
+ run.close()
156
+
157
+
158
+ def test_an_ask_is_answered_from_another_thread(where):
159
+ with start(where, policy="ask.toml") as run:
160
+ run.complete(model="fake-1", messages=[tether.user("Tidy up.")])
161
+ outcome = {}
162
+
163
+ def call():
164
+ outcome["result"] = run.call_tool(tether.ToolCall("c", "exec", {"argv": ["rm", "-rf", "."]}))
165
+
166
+ waiting = threading.Thread(target=call)
167
+ waiting.start()
168
+ # The events stream shows the ask; answer it.
169
+ for event in run.events():
170
+ if event.type == "policy.ask":
171
+ assert "rm" in event.data["data"]["prompt"]
172
+ run.answer(event.data["data"]["subject"], allow=False, answered_by="pytest")
173
+ break
174
+ waiting.join(timeout=10)
175
+ assert not waiting.is_alive()
176
+ assert outcome["result"].is_error
177
+ assert outcome["result"].content == "denied by pytest"
178
+
179
+
180
+ def test_events_streams_the_whole_trace_of_a_finished_run(where):
181
+ with start(where) as run:
182
+ run.complete(model="fake-1", messages=[tether.user("Tidy up.")])
183
+ run.finish("early")
184
+ seen = list(run.events())
185
+ assert [event.seq for event in seen] == list(range(len(seen)))
186
+ assert [event.data for event in seen] == trace(run)
187
+
188
+
189
+ def test_refused_requests_raise_with_the_status(where):
190
+ with pytest.raises(tether.TetherError) as error:
191
+ tether.Run(policy=where / "missing.toml", provider="fake", script=where / "script.json", dir=where / "runs")
192
+ assert error.value.code == grpc.StatusCode.INVALID_ARGUMENT
193
+ assert not isinstance(error.value, tether.Halted)
194
+
195
+ with pytest.raises(tether.TetherError) as error:
196
+ tether.Run(policy=where / "deny.toml", provider="llama", dir=where / "runs")
197
+ assert error.value.code == grpc.StatusCode.UNIMPLEMENTED
198
+
199
+ with start(where) as run:
200
+ with pytest.raises(tether.TetherError) as error:
201
+ run.complete(model="fake-1", messages=[tether.user("hi")], tools=["teleport"])
202
+ assert error.value.code == grpc.StatusCode.INVALID_ARGUMENT
203
+
204
+
205
+ def test_environment_fills_in_what_was_not_passed(where, monkeypatch):
206
+ # What `tether run -- <command>` sets for the agent it starts.
207
+ monkeypatch.setenv("TETHER_DIR", str(where / "runs"))
208
+ monkeypatch.setenv("TETHER_POLICY", str(where / "deny.toml"))
209
+ with tether.Run(provider="fake", script=where / "script.json") as run:
210
+ pass
211
+ assert Path(run.trace_path).parent == (where / "runs").resolve()
212
+ assert trace(run)[0]["data"]["policy"] == (where / "deny.toml").read_text()
213
+
214
+
215
+ def test_no_daemon_and_no_binary_is_a_clear_error(where, monkeypatch):
216
+ monkeypatch.delenv("TETHERD")
217
+ monkeypatch.setenv("PATH", "/nonexistent")
218
+ with pytest.raises(tether.TetherError) as error:
219
+ start(where)
220
+ assert "neither tetherd nor tether is on PATH" in str(error.value)