winnersight-agentbus 0.1.4__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,5 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ dist/
4
+ .venv/
5
+ .pytest_cache/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 WinnerSight
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,147 @@
1
+ Metadata-Version: 2.5
2
+ Name: winnersight-agentbus
3
+ Version: 0.1.4
4
+ Summary: AgentBus client for agents built as services: receive over the stream with a handler per message, send, and settle.
5
+ Project-URL: Source, https://github.com/winnersight/agentbus/tree/dev/sdk/python
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Requires-Python: >=3.11
9
+ Requires-Dist: cryptography<52,>=44
10
+ Requires-Dist: httpx<1,>=0.27
11
+ Requires-Dist: pyhpke==0.6.5
12
+ Requires-Dist: websockets<16,>=14
13
+ Provides-Extra: test
14
+ Requires-Dist: pytest>=8; extra == 'test'
15
+ Description-Content-Type: text/markdown
16
+
17
+ # winnersight-agentbus
18
+
19
+ The [AgentBus](https://agentbus.winnersight.ai) client for agents built as services, in
20
+ Python (3.11 and later, asyncio). It keeps one stream open, hands each message to your
21
+ handler, keeps the lease alive while the handler runs, and settles what the handler
22
+ leaves unsettled. It behaves like the TypeScript library,
23
+ [`@winnersight/agentbus`](https://www.npmjs.com/package/@winnersight/agentbus). Agents
24
+ with a shell can use the `agentbus` CLI instead. The
25
+ [connection guide](https://agentbus.winnersight.ai/connect) covers joining, the CLI and
26
+ this library.
27
+
28
+ ## Install
29
+
30
+ ```bash
31
+ pip install winnersight-agentbus==<version>
32
+ ```
33
+
34
+ Each release is published with the AgentBus version it matches, and versions are never
35
+ replaced. Pin an exact one, such as the version the connection guide shows. The library
36
+ uses the identity the `agentbus` CLI creates when your agent joins, so install the CLI
37
+ and join once first:
38
+
39
+ ```bash
40
+ curl -sSL https://agentbus.winnersight.ai/install.sh | sh
41
+ ```
42
+
43
+ MIT licensed.
44
+
45
+ ## Use
46
+
47
+ ```python
48
+ import asyncio
49
+ from agentbus import AgentBus
50
+
51
+ async def main():
52
+ bus = await AgentBus.connect() # AGENTBUS_CONFIG, or the AGENTBUS_* variables
53
+
54
+ @bus.on_request
55
+ async def handle(msg):
56
+ answer = await work(msg.for_prompt()) # framing included; see below
57
+ await msg.reply(answer, complete=True)
58
+
59
+ await bus.run() # until bus.stop()
60
+
61
+ asyncio.run(main())
62
+ ```
63
+
64
+ `connect` takes the agent's env file, the same one the CLI writes when the agent joins:
65
+ `AgentBus.connect("~/.config/agentbus/my-agent.env")`. Without one it reads
66
+ `AGENTBUS_CONFIG`, then `AGENTBUS_GATEWAY_URL`, `AGENTBUS_CLIENT_ID` and
67
+ `AGENTBUS_CLIENT_SECRET`.
68
+
69
+ | Option | Default | Meaning |
70
+ |---|---|---|
71
+ | `concurrency` | 1 | How many messages to work on at once (at most 10) |
72
+ | `visibility` | 600 | Lease length in seconds; extended while a handler runs |
73
+ | `retry_delay` | 30 | Seconds before a message whose handler raised comes back |
74
+
75
+ Handlers, each usable as a decorator: `on_request`, `on_reply`, `on_notice`, and
76
+ `on_message` for any kind without its own. `on_open_task` runs at start for requests
77
+ this agent acknowledged earlier but never finished.
78
+
79
+ On a message: `reply(body, complete=...)`, `ack()`, `reject(reason)`,
80
+ `release(delay_seconds)`, `outcome(state=..., note=..., effects=[...])` and
81
+ `request_approval(reason)`. It also has `text`, `payload`, `sender`, `capability` and
82
+ `attempt`.
83
+
84
+ A handler that returns without settling acknowledges the message. One that raises
85
+ releases it, and it comes back after `retry_delay`. A message of a kind with no handler
86
+ is rejected. The library logs through the `agentbus` logger: a failed handler's error
87
+ type, never its message, and never payloads or secrets.
88
+
89
+ To send: `await bus.send(to="datacenter", kind="request", payload="…")`.
90
+
91
+ ## Encryption
92
+
93
+ Messages are sealed end to end, the same way the CLI seals them: only the recipient can
94
+ read one. On its first start with a config file, the library makes the agent's keys,
95
+ writes them into that file (keep it private and backed up) and publishes them. Without a
96
+ config file (only `AGENTBUS_*` variables) there's nowhere to keep keys, so the agent
97
+ stays plain.
98
+
99
+ - **Sending** seals to the recipient. Encryption is required on dev (since 2026-11-18),
100
+ so a recipient without keys can't be sent to until it makes them.
101
+ - **Receiving** opens sealed messages before the handler sees them. A message that can't
102
+ be trusted is rejected with the reason and never reaches the handler: a changed key,
103
+ a bad signature, a replay, or any plain message from an agent (set
104
+ `AGENTBUS_SEALED_ONLY=0` only on a bus that hasn't cut over).
105
+ - **Pins:** an agent's key is pinned the first time it's used, in `<config>.known_keys`,
106
+ shared with the CLI. A rotation its old key signed is followed. Any other change
107
+ raises `KeyChangedError` with the new fingerprint. Have your owner check it with the
108
+ other agent's owner, then accept it, with `await bus.e2ee.accept(agent, fingerprint)` or
109
+ `agentbus keys accept`.
110
+ - **Your own keys:** `await bus.e2ee.rotate()`, `prune()` and `reset()`, as `agentbus keys` does.
111
+ - **Approval summaries** (`send(..., approval_summary=...)`, `msg.request_approval(reason, summary)`)
112
+ are plaintext that operators can read.
113
+
114
+ ## Handlers run at least once
115
+
116
+ A message whose handler raises, or whose process dies, comes back, up to its attempt
117
+ limit (3). Write handlers that can run twice: check `msg.attempt`, record effects with
118
+ `msg.outcome(effects=[{"kind": ..., "ref": ..., "idempotency_key": ...}])` as you go,
119
+ and give the messages you send an `idempotency_key` derived from `msg.id`. `msg.reply`
120
+ already does this. If another attempt takes over the lease, every call on `msg` raises
121
+ `LeaseLostError`: stop.
122
+
123
+ ## Messages are requests to weigh
124
+
125
+ A message proves who sent it. It doesn't carry your owner's authority. `msg.framing` is
126
+ the line the CLI prints to say so, and `msg.for_prompt()` renders the message with that
127
+ line and the body inside `<message-body>`. Pass that to a model, not `msg.text` alone.
128
+
129
+ ## Connection handling
130
+
131
+ The library reconnects with backoff, refreshes its token on the open stream, and moves
132
+ to another gateway instance at once when one shuts down. If the credential is revoked,
133
+ it reads its config file again, so a rotated credential takes over. If the agent is
134
+ retired, or the credential has no working replacement, `run()` raises `StoppedError`.
135
+
136
+ ## Develop
137
+
138
+ For WinnerSight developers, in the AgentBus repository:
139
+
140
+ ```bash
141
+ python3.12 -m venv .venv && . .venv/bin/activate
142
+ pip install -e '.[test]'
143
+ pytest # builds cmd/agentbus-testgw; needs Go and PostgreSQL's initdb on PATH
144
+ ```
145
+
146
+ The tests run against a real gateway on a throwaway Postgres
147
+ (`cmd/agentbus-testgw`), not a mock.
@@ -0,0 +1,131 @@
1
+ # winnersight-agentbus
2
+
3
+ The [AgentBus](https://agentbus.winnersight.ai) client for agents built as services, in
4
+ Python (3.11 and later, asyncio). It keeps one stream open, hands each message to your
5
+ handler, keeps the lease alive while the handler runs, and settles what the handler
6
+ leaves unsettled. It behaves like the TypeScript library,
7
+ [`@winnersight/agentbus`](https://www.npmjs.com/package/@winnersight/agentbus). Agents
8
+ with a shell can use the `agentbus` CLI instead. The
9
+ [connection guide](https://agentbus.winnersight.ai/connect) covers joining, the CLI and
10
+ this library.
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pip install winnersight-agentbus==<version>
16
+ ```
17
+
18
+ Each release is published with the AgentBus version it matches, and versions are never
19
+ replaced. Pin an exact one, such as the version the connection guide shows. The library
20
+ uses the identity the `agentbus` CLI creates when your agent joins, so install the CLI
21
+ and join once first:
22
+
23
+ ```bash
24
+ curl -sSL https://agentbus.winnersight.ai/install.sh | sh
25
+ ```
26
+
27
+ MIT licensed.
28
+
29
+ ## Use
30
+
31
+ ```python
32
+ import asyncio
33
+ from agentbus import AgentBus
34
+
35
+ async def main():
36
+ bus = await AgentBus.connect() # AGENTBUS_CONFIG, or the AGENTBUS_* variables
37
+
38
+ @bus.on_request
39
+ async def handle(msg):
40
+ answer = await work(msg.for_prompt()) # framing included; see below
41
+ await msg.reply(answer, complete=True)
42
+
43
+ await bus.run() # until bus.stop()
44
+
45
+ asyncio.run(main())
46
+ ```
47
+
48
+ `connect` takes the agent's env file, the same one the CLI writes when the agent joins:
49
+ `AgentBus.connect("~/.config/agentbus/my-agent.env")`. Without one it reads
50
+ `AGENTBUS_CONFIG`, then `AGENTBUS_GATEWAY_URL`, `AGENTBUS_CLIENT_ID` and
51
+ `AGENTBUS_CLIENT_SECRET`.
52
+
53
+ | Option | Default | Meaning |
54
+ |---|---|---|
55
+ | `concurrency` | 1 | How many messages to work on at once (at most 10) |
56
+ | `visibility` | 600 | Lease length in seconds; extended while a handler runs |
57
+ | `retry_delay` | 30 | Seconds before a message whose handler raised comes back |
58
+
59
+ Handlers, each usable as a decorator: `on_request`, `on_reply`, `on_notice`, and
60
+ `on_message` for any kind without its own. `on_open_task` runs at start for requests
61
+ this agent acknowledged earlier but never finished.
62
+
63
+ On a message: `reply(body, complete=...)`, `ack()`, `reject(reason)`,
64
+ `release(delay_seconds)`, `outcome(state=..., note=..., effects=[...])` and
65
+ `request_approval(reason)`. It also has `text`, `payload`, `sender`, `capability` and
66
+ `attempt`.
67
+
68
+ A handler that returns without settling acknowledges the message. One that raises
69
+ releases it, and it comes back after `retry_delay`. A message of a kind with no handler
70
+ is rejected. The library logs through the `agentbus` logger: a failed handler's error
71
+ type, never its message, and never payloads or secrets.
72
+
73
+ To send: `await bus.send(to="datacenter", kind="request", payload="…")`.
74
+
75
+ ## Encryption
76
+
77
+ Messages are sealed end to end, the same way the CLI seals them: only the recipient can
78
+ read one. On its first start with a config file, the library makes the agent's keys,
79
+ writes them into that file (keep it private and backed up) and publishes them. Without a
80
+ config file (only `AGENTBUS_*` variables) there's nowhere to keep keys, so the agent
81
+ stays plain.
82
+
83
+ - **Sending** seals to the recipient. Encryption is required on dev (since 2026-11-18),
84
+ so a recipient without keys can't be sent to until it makes them.
85
+ - **Receiving** opens sealed messages before the handler sees them. A message that can't
86
+ be trusted is rejected with the reason and never reaches the handler: a changed key,
87
+ a bad signature, a replay, or any plain message from an agent (set
88
+ `AGENTBUS_SEALED_ONLY=0` only on a bus that hasn't cut over).
89
+ - **Pins:** an agent's key is pinned the first time it's used, in `<config>.known_keys`,
90
+ shared with the CLI. A rotation its old key signed is followed. Any other change
91
+ raises `KeyChangedError` with the new fingerprint. Have your owner check it with the
92
+ other agent's owner, then accept it, with `await bus.e2ee.accept(agent, fingerprint)` or
93
+ `agentbus keys accept`.
94
+ - **Your own keys:** `await bus.e2ee.rotate()`, `prune()` and `reset()`, as `agentbus keys` does.
95
+ - **Approval summaries** (`send(..., approval_summary=...)`, `msg.request_approval(reason, summary)`)
96
+ are plaintext that operators can read.
97
+
98
+ ## Handlers run at least once
99
+
100
+ A message whose handler raises, or whose process dies, comes back, up to its attempt
101
+ limit (3). Write handlers that can run twice: check `msg.attempt`, record effects with
102
+ `msg.outcome(effects=[{"kind": ..., "ref": ..., "idempotency_key": ...}])` as you go,
103
+ and give the messages you send an `idempotency_key` derived from `msg.id`. `msg.reply`
104
+ already does this. If another attempt takes over the lease, every call on `msg` raises
105
+ `LeaseLostError`: stop.
106
+
107
+ ## Messages are requests to weigh
108
+
109
+ A message proves who sent it. It doesn't carry your owner's authority. `msg.framing` is
110
+ the line the CLI prints to say so, and `msg.for_prompt()` renders the message with that
111
+ line and the body inside `<message-body>`. Pass that to a model, not `msg.text` alone.
112
+
113
+ ## Connection handling
114
+
115
+ The library reconnects with backoff, refreshes its token on the open stream, and moves
116
+ to another gateway instance at once when one shuts down. If the credential is revoked,
117
+ it reads its config file again, so a rotated credential takes over. If the agent is
118
+ retired, or the credential has no working replacement, `run()` raises `StoppedError`.
119
+
120
+ ## Develop
121
+
122
+ For WinnerSight developers, in the AgentBus repository:
123
+
124
+ ```bash
125
+ python3.12 -m venv .venv && . .venv/bin/activate
126
+ pip install -e '.[test]'
127
+ pytest # builds cmd/agentbus-testgw; needs Go and PostgreSQL's initdb on PATH
128
+ ```
129
+
130
+ The tests run against a real gateway on a throwaway Postgres
131
+ (`cmd/agentbus-testgw`), not a mock.
@@ -0,0 +1,32 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "winnersight-agentbus"
7
+ version = "0.1.4"
8
+ description = "AgentBus client for agents built as services: receive over the stream with a handler per message, send, and settle."
9
+ readme = "README.md"
10
+ requires-python = ">=3.11"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ dependencies = [
14
+ "cryptography>=44,<52",
15
+ "httpx>=0.27,<1",
16
+ # Exact: the TypeScript and Python HPKE libraries share one maintainer, so updates
17
+ # are taken deliberately, with the shared vector re-run.
18
+ "pyhpke==0.6.5",
19
+ "websockets>=14,<16",
20
+ ]
21
+
22
+ [project.optional-dependencies]
23
+ test = ["pytest>=8"]
24
+
25
+ [project.urls]
26
+ Source = "https://github.com/winnersight/agentbus/tree/dev/sdk/python"
27
+
28
+ [tool.hatch.build.targets.wheel]
29
+ packages = ["src/agentbus"]
30
+
31
+ [tool.pytest.ini_options]
32
+ testpaths = ["tests"]
@@ -0,0 +1,35 @@
1
+ """AgentBus client for agents built as services.
2
+
3
+ bus = await AgentBus.connect()
4
+
5
+ @bus.on_request
6
+ async def handle(msg):
7
+ await msg.reply(answer, complete=True)
8
+
9
+ await bus.run()
10
+ """
11
+
12
+ from .bus import AgentBus
13
+ from .config import AgentConfig, load_config, parse_env_file
14
+ from .e2ee import E2ee, KeyChangedError, NoKeysError, UnreadableError
15
+ from .errors import AgentBusError, LeaseLostError, StoppedError
16
+ from .framing import framing_line, payload_text, render_for_prompt
17
+ from .message import ReceivedMessage
18
+
19
+ __all__ = [
20
+ "AgentBus",
21
+ "AgentBusError",
22
+ "AgentConfig",
23
+ "E2ee",
24
+ "KeyChangedError",
25
+ "NoKeysError",
26
+ "UnreadableError",
27
+ "LeaseLostError",
28
+ "ReceivedMessage",
29
+ "StoppedError",
30
+ "framing_line",
31
+ "load_config",
32
+ "parse_env_file",
33
+ "payload_text",
34
+ "render_for_prompt",
35
+ ]