gamai-plugins 0.2.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. gamai_plugins-0.2.2/LICENSE +21 -0
  2. gamai_plugins-0.2.2/PKG-INFO +220 -0
  3. gamai_plugins-0.2.2/README.md +202 -0
  4. gamai_plugins-0.2.2/gamai_plugins/__init__.py +2 -0
  5. gamai_plugins-0.2.2/gamai_plugins/cli.py +134 -0
  6. gamai_plugins-0.2.2/gamai_plugins/mcp.py +89 -0
  7. gamai_plugins-0.2.2/gamai_plugins/plugins/protean/plugin.json +64 -0
  8. gamai_plugins-0.2.2/gamai_plugins/plugins/protean/run.py +788 -0
  9. gamai_plugins-0.2.2/gamai_plugins/plugins/protean/seccomp.json +134 -0
  10. gamai_plugins-0.2.2/gamai_plugins/plugins/team/plugin.json +105 -0
  11. gamai_plugins-0.2.2/gamai_plugins/plugins/team/run.py +59 -0
  12. gamai_plugins-0.2.2/gamai_plugins/plugins/team/team_core.py +642 -0
  13. gamai_plugins-0.2.2/gamai_plugins/plugins/trust/plugin.json +76 -0
  14. gamai_plugins-0.2.2/gamai_plugins/plugins/trust/run.py +680 -0
  15. gamai_plugins-0.2.2/gamai_plugins.egg-info/PKG-INFO +220 -0
  16. gamai_plugins-0.2.2/gamai_plugins.egg-info/SOURCES.txt +25 -0
  17. gamai_plugins-0.2.2/gamai_plugins.egg-info/dependency_links.txt +1 -0
  18. gamai_plugins-0.2.2/gamai_plugins.egg-info/entry_points.txt +6 -0
  19. gamai_plugins-0.2.2/gamai_plugins.egg-info/requires.txt +3 -0
  20. gamai_plugins-0.2.2/gamai_plugins.egg-info/top_level.txt +1 -0
  21. gamai_plugins-0.2.2/pyproject.toml +40 -0
  22. gamai_plugins-0.2.2/setup.cfg +4 -0
  23. gamai_plugins-0.2.2/tests/test_cli.py +40 -0
  24. gamai_plugins-0.2.2/tests/test_mcp.py +23 -0
  25. gamai_plugins-0.2.2/tests/test_protean.py +74 -0
  26. gamai_plugins-0.2.2/tests/test_team.py +222 -0
  27. gamai_plugins-0.2.2/tests/test_trust.py +262 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 gamAI
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,220 @@
1
+ Metadata-Version: 2.4
2
+ Name: gamai-plugins
3
+ Version: 0.2.2
4
+ Summary: Portable trust, sandbox and team plugins for AI agents (MCP + CLI).
5
+ Author: gamAI
6
+ License-Expression: MIT
7
+ Keywords: ai-agents,mcp,sandbox,trust,team
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: Operating System :: POSIX :: Linux
10
+ Classifier: Operating System :: Microsoft :: Windows
11
+ Classifier: Topic :: Security
12
+ Requires-Python: >=3.10
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Provides-Extra: crypto
16
+ Requires-Dist: cryptography>=42; extra == "crypto"
17
+ Dynamic: license-file
18
+
19
+ # gamAI plugins
20
+
21
+ Portable, dependency-light plugins for AI agents: **policy evaluation**,
22
+ **sandbox execution** and **team coordination**. The same code is exposed as an
23
+ MCP server, a CLI and a plain Python function, so it can run in Claude Code,
24
+ opencode, Codex, Cursor, LangChain or a custom agent loop.
25
+
26
+ > Status: `0.2.2` — small, explicit about its limits, and hardened against the
27
+ > failures found in an external-style audit. `protean` is a namespace sandbox,
28
+ > not a VM and not a hardened multi-tenant boundary.
29
+
30
+ ## Plugins
31
+
32
+ | Plugin | What it does | Default |
33
+ |---|---|---|
34
+ | `trust` | Evaluates allow/deny policy with audit; verifies package integrity (never executes a manifest). | missing/invalid policy ⇒ deny |
35
+ | `protean` | Runs a command in a sandbox with a lease receipt, risk-routed substrates and JSONL evidence. | `low` = bubblewrap |
36
+ | `team` | Deterministic goal split, isolated clone, persistent state, at most one optional LLM call per task. | deterministic fallback |
37
+
38
+ ## Install
39
+
40
+ ```bash
41
+ pip install -e .
42
+ # optional Ed25519 verification for trust
43
+ pip install -e '.[crypto]'
44
+ ```
45
+
46
+ Linux is recommended for `protean`:
47
+
48
+ ```bash
49
+ sudo apt-get install bubblewrap # risk=low
50
+ # Docker is optional; risk=medium/high use docker runc
51
+ ```
52
+
53
+ `risk=low` mounts a minimal read-only root (`/usr/bin`, `/usr/sbin`,
54
+ `/usr/lib`, `/usr/share`, `/bin`, `/sbin`, `/lib`, `/lib64`). `/etc` is a tmpfs
55
+ with an allowlist of non-secret files; `/etc/shadow`, `gshadow`, `sudoers`,
56
+ host SSH keys and private TLS keys are not exposed. `/root`, `/home`, `/opt`,
57
+ `/var` and `/run` are not mounted. `/tmp` is a 32 MiB tmpfs, and `prlimit`
58
+ caps address space and process count when available.
59
+
60
+ **The allowlist checks only the first executable token.** Shell syntax can run
61
+ other binaries present in the mounted root. The sandbox, not the allowlist, is
62
+ the security boundary. Available binaries depend on the substrate: the default
63
+ Docker image has `sh` and `python3`, but not `bash`, `git` or `node`; use a
64
+ custom `PROTEAN_IMAGE` if you need them.
65
+
66
+ ## MCP
67
+
68
+ ```json
69
+ {
70
+ "mcpServers": {
71
+ "gamai-plugins": {
72
+ "command": "gamai-plugins-mcp"
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ The server exposes six namespaced tools:
79
+
80
+ ```text
81
+ trust_managed_policy
82
+ trust_marketplace_verify
83
+ protean_run
84
+ team_create
85
+ team_dispatch
86
+ team_status
87
+ ```
88
+
89
+ ## CLI
90
+
91
+ ```bash
92
+ gamai-plugins list
93
+ gamai-plugins call trust managed_policy '{"action":"load"}'
94
+ gamai-plugins call protean run '{"cmd":"echo hi","risk":"low","timeout_s":5}'
95
+ gamai-plugins call team team_create '{"goal":"review this change","agents":2}'
96
+ gamai-plugins mcp
97
+ ```
98
+
99
+ Or the per-plugin entry points:
100
+
101
+ ```bash
102
+ gamai-trust managed_policy '{"action":"check","tool":"shell"}'
103
+ gamai-protean run '{"cmd":"uname -a","risk":"low"}'
104
+ gamai-team team_status '{"team_id":"team-..."}'
105
+ ```
106
+
107
+ CLI exit code is non-zero when a tool returns `ok:false` or a trust decision is
108
+ `deny`, so shell/CI gates can use it.
109
+
110
+ ## Python
111
+
112
+ ```python
113
+ from gamai_plugins.cli import call
114
+
115
+ print(call("protean", "run", {"cmd": "echo hi", "risk": "low", "timeout_s": 5}))
116
+ ```
117
+
118
+ ## Policy and integrity semantics
119
+
120
+ `trust_managed_policy` is an **evaluator**, not an enforcement point. The caller
121
+ must enforce the returned `decision`. A valid policy without `default` is
122
+ `deny`; deny rules win. Paths are normalized and shell segments are evaluated
123
+ separately.
124
+
125
+ `trust_marketplace_verify` returns:
126
+
127
+ - `integrity_ok` — every expected file matches and there is no unexpected,
128
+ truncated or symlinked content;
129
+ - `trusted` — integrity is complete and the signature verifies with a **pinned**
130
+ key (`public_key` argument or `GAMAI_TRUST_PUBKEY`);
131
+ - `status` — `verified`, `self_signed`, `unsigned`, `failed` or `unverified`.
132
+
133
+ A self-signed manifest is not trusted. Without a manifest the result is
134
+ `unverified`, not a silent pass. See [docs/MANIFEST.md](docs/MANIFEST.md) for
135
+ the canonical signing form and `scripts/sign_manifest.py`.
136
+
137
+ ## Team semantics
138
+
139
+ `team_create` creates a shared clone (not a source worktree) with
140
+ `core.hooksPath` pointing at an empty directory, so an untrusted repository
141
+ cannot execute hooks later. State is written before isolation, so a slow clone
142
+ does not leave a registered workspace without state.
143
+
144
+ `team` prompts and role hints are currently Bosnian. That is intentional, not a
145
+ translation layer; make it configurable if you need another language. Dispatch
146
+ is serialized per team: the LLM call happens while the team lock is held, so
147
+ concurrent dispatches wait rather than racing state.
148
+
149
+ ## Configuration
150
+
151
+ | Variable | Used by | Meaning |
152
+ |---|---|---|
153
+ | `GAMAI_POLICY` | trust | policy JSON; default `~/.config/gamai/trust/policy.json` |
154
+ | `GAMAI_AUDIT` | trust | audit JSONL; default `~/.local/state/gamai/trust/audit.jsonl` |
155
+ | `GAMAI_AUDIT_DISABLE` | trust | `1` disables audit **only when the policy does not require audit** |
156
+ | `GAMAI_TRUST_PUBKEY` | trust | pinned Ed25519 key (PEM, 64 hex, or base64 raw 32 bytes) |
157
+ | `GAMAI_HOME` | trust | base config dir; default `~/.config/gamai` |
158
+ | `GAMAI_STATE` | trust | base state dir; default `~/.local/state/gamai` |
159
+ | `PROTEAN_HOME` | protean | data dir; default `~/.config/gamai/protean` |
160
+ | `PROTEAN_IMAGE` | protean | Docker image for medium/high; default `python:3.12-alpine` |
161
+ | `PROTEAN_HIGH_REMOTE` | protean | `1` allows high risk to use the configured remote gVisor |
162
+ | `PROTEAN_REMOTE_HOST` | protean | optional remote host for `critical` + gVisor |
163
+ | `PROTEAN_REMOTE_PORT`, `PROTEAN_REMOTE_KEY`, `PROTEAN_REMOTE_USER` | protean | SSH details for the remote substrate |
164
+ | `PROTEAN_KNOWN_HOSTS` | protean | SSH known_hosts; default `~/.ssh/known_hosts` |
165
+ | `PROTEAN_SSH_STRICT` | protean | `yes`, `accept-new` (default) or `no` |
166
+ | `GAMAI_TEAM_STATE_DIR` | team | state dir; default `~/.local/state/gamai/teams` |
167
+ | `GAMAI_TEAM_WORKTREES` | team | workspace dir; default `~/.cache/gamai/teams` |
168
+ | `GAMAI_TEAM_REPO` | team | default repo for isolation when `repo` is omitted |
169
+ | `GAMAI_TEAM_LLM_BUDGET` | team | max LLM calls per team; default 50 |
170
+ | `GAMAI_TEAM_LLM_TIMEOUT` | team | per-call timeout; default 40 s |
171
+ | `GAMAI_LLM_URL` | team | optional HTTPS endpoint for one LLM call per task; HTTP only for loopback |
172
+ | `GAMAI_LLM_TOKEN` | team | optional `X-Token` sent to that endpoint |
173
+ | `GAMAI_TEAM_AGENT` | team | default backend name; default `agent` |
174
+
175
+ No secret is stored in this repository. `protean` creates a per-install
176
+ `lease.key` at runtime with mode `600`.
177
+
178
+ ## Safety model
179
+
180
+ - **Trust is fail-closed:** missing/invalid policy, invalid manifest or a
181
+ required audit failure yields deny/failure.
182
+ - **Manifest is data:** `trust` hashes and verifies packages; it never executes
183
+ a manifest.
184
+ - **Lease is a receipt, not authorization:** `protean` mints and verifies the
185
+ lease in the same process. It binds command/genome/TTL for evidence, but it
186
+ is not an external policy decision.
187
+ - **Substrate routing:** `low` uses bubblewrap; `medium`/`high` use Docker with
188
+ no network, dropped capabilities, read-only root and resource limits;
189
+ `critical` is denied unless a remote gVisor host is explicitly configured.
190
+ - **Bounded output:** `protean` captures at most 64 KiB per stream and returns
191
+ at most 8,000 characters; evidence runs are pruned to the newest 200.
192
+ - **Audit cannot be disabled when required:** `GAMAI_AUDIT_DISABLE=1` is
193
+ ignored when the policy says `audit: true`; audit failure becomes
194
+ `deny`/`audit_failed`.
195
+ - **Team is not an authorization boundary.** It coordinates work; the backend
196
+ decides what it executes. LLM redirects are not followed and public plain
197
+ HTTP is refused; the configured HTTPS origin still receives the token by
198
+ design.
199
+ - **Docker socket is root-equivalent.** Do not expose `protean` medium/high to
200
+ untrusted users.
201
+ - **Trust score is heuristic:** `trust_score` is a documented 0–100 heuristic,
202
+ not a cryptographic proof.
203
+
204
+ Read [SECURITY.md](SECURITY.md) and [THREAT_MODEL.md](THREAT_MODEL.md) before
205
+ using this in production.
206
+
207
+ ## Development
208
+
209
+ ```bash
210
+ python -m unittest discover -s tests -v
211
+ python -m gamai_plugins.mcp --selftest
212
+ python scripts/smoke_mcp.py
213
+ ```
214
+
215
+ The tests do not need network access, Docker, or an LLM. `protean` low-risk
216
+ tests use bubblewrap when available; Windows runs the same suite without it.
217
+
218
+ ## License
219
+
220
+ MIT.
@@ -0,0 +1,202 @@
1
+ # gamAI plugins
2
+
3
+ Portable, dependency-light plugins for AI agents: **policy evaluation**,
4
+ **sandbox execution** and **team coordination**. The same code is exposed as an
5
+ MCP server, a CLI and a plain Python function, so it can run in Claude Code,
6
+ opencode, Codex, Cursor, LangChain or a custom agent loop.
7
+
8
+ > Status: `0.2.2` — small, explicit about its limits, and hardened against the
9
+ > failures found in an external-style audit. `protean` is a namespace sandbox,
10
+ > not a VM and not a hardened multi-tenant boundary.
11
+
12
+ ## Plugins
13
+
14
+ | Plugin | What it does | Default |
15
+ |---|---|---|
16
+ | `trust` | Evaluates allow/deny policy with audit; verifies package integrity (never executes a manifest). | missing/invalid policy ⇒ deny |
17
+ | `protean` | Runs a command in a sandbox with a lease receipt, risk-routed substrates and JSONL evidence. | `low` = bubblewrap |
18
+ | `team` | Deterministic goal split, isolated clone, persistent state, at most one optional LLM call per task. | deterministic fallback |
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ pip install -e .
24
+ # optional Ed25519 verification for trust
25
+ pip install -e '.[crypto]'
26
+ ```
27
+
28
+ Linux is recommended for `protean`:
29
+
30
+ ```bash
31
+ sudo apt-get install bubblewrap # risk=low
32
+ # Docker is optional; risk=medium/high use docker runc
33
+ ```
34
+
35
+ `risk=low` mounts a minimal read-only root (`/usr/bin`, `/usr/sbin`,
36
+ `/usr/lib`, `/usr/share`, `/bin`, `/sbin`, `/lib`, `/lib64`). `/etc` is a tmpfs
37
+ with an allowlist of non-secret files; `/etc/shadow`, `gshadow`, `sudoers`,
38
+ host SSH keys and private TLS keys are not exposed. `/root`, `/home`, `/opt`,
39
+ `/var` and `/run` are not mounted. `/tmp` is a 32 MiB tmpfs, and `prlimit`
40
+ caps address space and process count when available.
41
+
42
+ **The allowlist checks only the first executable token.** Shell syntax can run
43
+ other binaries present in the mounted root. The sandbox, not the allowlist, is
44
+ the security boundary. Available binaries depend on the substrate: the default
45
+ Docker image has `sh` and `python3`, but not `bash`, `git` or `node`; use a
46
+ custom `PROTEAN_IMAGE` if you need them.
47
+
48
+ ## MCP
49
+
50
+ ```json
51
+ {
52
+ "mcpServers": {
53
+ "gamai-plugins": {
54
+ "command": "gamai-plugins-mcp"
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ The server exposes six namespaced tools:
61
+
62
+ ```text
63
+ trust_managed_policy
64
+ trust_marketplace_verify
65
+ protean_run
66
+ team_create
67
+ team_dispatch
68
+ team_status
69
+ ```
70
+
71
+ ## CLI
72
+
73
+ ```bash
74
+ gamai-plugins list
75
+ gamai-plugins call trust managed_policy '{"action":"load"}'
76
+ gamai-plugins call protean run '{"cmd":"echo hi","risk":"low","timeout_s":5}'
77
+ gamai-plugins call team team_create '{"goal":"review this change","agents":2}'
78
+ gamai-plugins mcp
79
+ ```
80
+
81
+ Or the per-plugin entry points:
82
+
83
+ ```bash
84
+ gamai-trust managed_policy '{"action":"check","tool":"shell"}'
85
+ gamai-protean run '{"cmd":"uname -a","risk":"low"}'
86
+ gamai-team team_status '{"team_id":"team-..."}'
87
+ ```
88
+
89
+ CLI exit code is non-zero when a tool returns `ok:false` or a trust decision is
90
+ `deny`, so shell/CI gates can use it.
91
+
92
+ ## Python
93
+
94
+ ```python
95
+ from gamai_plugins.cli import call
96
+
97
+ print(call("protean", "run", {"cmd": "echo hi", "risk": "low", "timeout_s": 5}))
98
+ ```
99
+
100
+ ## Policy and integrity semantics
101
+
102
+ `trust_managed_policy` is an **evaluator**, not an enforcement point. The caller
103
+ must enforce the returned `decision`. A valid policy without `default` is
104
+ `deny`; deny rules win. Paths are normalized and shell segments are evaluated
105
+ separately.
106
+
107
+ `trust_marketplace_verify` returns:
108
+
109
+ - `integrity_ok` — every expected file matches and there is no unexpected,
110
+ truncated or symlinked content;
111
+ - `trusted` — integrity is complete and the signature verifies with a **pinned**
112
+ key (`public_key` argument or `GAMAI_TRUST_PUBKEY`);
113
+ - `status` — `verified`, `self_signed`, `unsigned`, `failed` or `unverified`.
114
+
115
+ A self-signed manifest is not trusted. Without a manifest the result is
116
+ `unverified`, not a silent pass. See [docs/MANIFEST.md](docs/MANIFEST.md) for
117
+ the canonical signing form and `scripts/sign_manifest.py`.
118
+
119
+ ## Team semantics
120
+
121
+ `team_create` creates a shared clone (not a source worktree) with
122
+ `core.hooksPath` pointing at an empty directory, so an untrusted repository
123
+ cannot execute hooks later. State is written before isolation, so a slow clone
124
+ does not leave a registered workspace without state.
125
+
126
+ `team` prompts and role hints are currently Bosnian. That is intentional, not a
127
+ translation layer; make it configurable if you need another language. Dispatch
128
+ is serialized per team: the LLM call happens while the team lock is held, so
129
+ concurrent dispatches wait rather than racing state.
130
+
131
+ ## Configuration
132
+
133
+ | Variable | Used by | Meaning |
134
+ |---|---|---|
135
+ | `GAMAI_POLICY` | trust | policy JSON; default `~/.config/gamai/trust/policy.json` |
136
+ | `GAMAI_AUDIT` | trust | audit JSONL; default `~/.local/state/gamai/trust/audit.jsonl` |
137
+ | `GAMAI_AUDIT_DISABLE` | trust | `1` disables audit **only when the policy does not require audit** |
138
+ | `GAMAI_TRUST_PUBKEY` | trust | pinned Ed25519 key (PEM, 64 hex, or base64 raw 32 bytes) |
139
+ | `GAMAI_HOME` | trust | base config dir; default `~/.config/gamai` |
140
+ | `GAMAI_STATE` | trust | base state dir; default `~/.local/state/gamai` |
141
+ | `PROTEAN_HOME` | protean | data dir; default `~/.config/gamai/protean` |
142
+ | `PROTEAN_IMAGE` | protean | Docker image for medium/high; default `python:3.12-alpine` |
143
+ | `PROTEAN_HIGH_REMOTE` | protean | `1` allows high risk to use the configured remote gVisor |
144
+ | `PROTEAN_REMOTE_HOST` | protean | optional remote host for `critical` + gVisor |
145
+ | `PROTEAN_REMOTE_PORT`, `PROTEAN_REMOTE_KEY`, `PROTEAN_REMOTE_USER` | protean | SSH details for the remote substrate |
146
+ | `PROTEAN_KNOWN_HOSTS` | protean | SSH known_hosts; default `~/.ssh/known_hosts` |
147
+ | `PROTEAN_SSH_STRICT` | protean | `yes`, `accept-new` (default) or `no` |
148
+ | `GAMAI_TEAM_STATE_DIR` | team | state dir; default `~/.local/state/gamai/teams` |
149
+ | `GAMAI_TEAM_WORKTREES` | team | workspace dir; default `~/.cache/gamai/teams` |
150
+ | `GAMAI_TEAM_REPO` | team | default repo for isolation when `repo` is omitted |
151
+ | `GAMAI_TEAM_LLM_BUDGET` | team | max LLM calls per team; default 50 |
152
+ | `GAMAI_TEAM_LLM_TIMEOUT` | team | per-call timeout; default 40 s |
153
+ | `GAMAI_LLM_URL` | team | optional HTTPS endpoint for one LLM call per task; HTTP only for loopback |
154
+ | `GAMAI_LLM_TOKEN` | team | optional `X-Token` sent to that endpoint |
155
+ | `GAMAI_TEAM_AGENT` | team | default backend name; default `agent` |
156
+
157
+ No secret is stored in this repository. `protean` creates a per-install
158
+ `lease.key` at runtime with mode `600`.
159
+
160
+ ## Safety model
161
+
162
+ - **Trust is fail-closed:** missing/invalid policy, invalid manifest or a
163
+ required audit failure yields deny/failure.
164
+ - **Manifest is data:** `trust` hashes and verifies packages; it never executes
165
+ a manifest.
166
+ - **Lease is a receipt, not authorization:** `protean` mints and verifies the
167
+ lease in the same process. It binds command/genome/TTL for evidence, but it
168
+ is not an external policy decision.
169
+ - **Substrate routing:** `low` uses bubblewrap; `medium`/`high` use Docker with
170
+ no network, dropped capabilities, read-only root and resource limits;
171
+ `critical` is denied unless a remote gVisor host is explicitly configured.
172
+ - **Bounded output:** `protean` captures at most 64 KiB per stream and returns
173
+ at most 8,000 characters; evidence runs are pruned to the newest 200.
174
+ - **Audit cannot be disabled when required:** `GAMAI_AUDIT_DISABLE=1` is
175
+ ignored when the policy says `audit: true`; audit failure becomes
176
+ `deny`/`audit_failed`.
177
+ - **Team is not an authorization boundary.** It coordinates work; the backend
178
+ decides what it executes. LLM redirects are not followed and public plain
179
+ HTTP is refused; the configured HTTPS origin still receives the token by
180
+ design.
181
+ - **Docker socket is root-equivalent.** Do not expose `protean` medium/high to
182
+ untrusted users.
183
+ - **Trust score is heuristic:** `trust_score` is a documented 0–100 heuristic,
184
+ not a cryptographic proof.
185
+
186
+ Read [SECURITY.md](SECURITY.md) and [THREAT_MODEL.md](THREAT_MODEL.md) before
187
+ using this in production.
188
+
189
+ ## Development
190
+
191
+ ```bash
192
+ python -m unittest discover -s tests -v
193
+ python -m gamai_plugins.mcp --selftest
194
+ python scripts/smoke_mcp.py
195
+ ```
196
+
197
+ The tests do not need network access, Docker, or an LLM. `protean` low-risk
198
+ tests use bubblewrap when available; Windows runs the same suite without it.
199
+
200
+ ## License
201
+
202
+ MIT.
@@ -0,0 +1,2 @@
1
+ """Portable GAMA plugins: trust, protean and team."""
2
+ __version__ = "0.2.2"
@@ -0,0 +1,134 @@
1
+ #!/usr/bin/env python3
2
+ """One CLI for all portable GAMA plugins."""
3
+ import json
4
+ import subprocess
5
+ import sys
6
+ from pathlib import Path
7
+
8
+ ROOT = Path(__file__).resolve().parent / "plugins"
9
+ PLUGINS = ("trust", "protean", "team")
10
+
11
+
12
+ def manifest(plugin):
13
+ with open(ROOT / plugin / "plugin.json", encoding="utf-8") as fh:
14
+ return json.load(fh)
15
+
16
+
17
+ def _public_name(plugin, tool_name):
18
+ return tool_name if tool_name.startswith(plugin + "_") else "%s_%s" % (plugin, tool_name)
19
+
20
+
21
+ def tools():
22
+ out = []
23
+ for plugin in PLUGINS:
24
+ m = manifest(plugin)
25
+ for tool in m.get("tools", []):
26
+ out.append({
27
+ "name": _public_name(plugin, tool["name"]),
28
+ "plugin": plugin,
29
+ "tool": tool["name"],
30
+ "description": tool.get("description", ""),
31
+ "inputSchema": tool.get("parameters", {"type": "object"}),
32
+ "timeout_s": tool.get("timeout_s", 90),
33
+ })
34
+ return out
35
+
36
+
37
+ def call(plugin, tool, args, timeout=None):
38
+ if plugin not in PLUGINS:
39
+ return {"ok": False, "err": "unknown plugin %r" % plugin}
40
+ path = ROOT / plugin / "run.py"
41
+ if not path.is_file():
42
+ return {"ok": False, "err": "plugin entrypoint missing"}
43
+ if timeout is None:
44
+ timeout = 90
45
+ for entry in tools():
46
+ if entry["plugin"] == plugin and entry["tool"] == tool:
47
+ timeout = int(entry.get("timeout_s") or 90)
48
+ break
49
+ try:
50
+ p = subprocess.run(
51
+ [sys.executable, str(path), tool],
52
+ input=json.dumps(args, ensure_ascii=False),
53
+ text=True, encoding="utf-8", errors="replace",
54
+ capture_output=True, timeout=timeout,
55
+ cwd=str(ROOT / plugin),
56
+ )
57
+ except subprocess.TimeoutExpired:
58
+ return {"ok": False, "err": "timeout after %ss" % timeout}
59
+ raw = (p.stdout or "").strip().splitlines()
60
+ for line in reversed(raw):
61
+ try:
62
+ return json.loads(line)
63
+ except Exception:
64
+ continue
65
+ return {"ok": False, "err": (p.stderr or p.stdout or "empty output").strip()[:500]}
66
+
67
+
68
+ def _print(obj):
69
+ print(json.dumps(obj, ensure_ascii=False, indent=2))
70
+
71
+
72
+ def main(argv=None):
73
+ argv = list(sys.argv[1:] if argv is None else argv)
74
+ if not argv or argv[0] in ("-h", "--help", "help"):
75
+ print("usage: gamai-plugins list | call <plugin> <tool> [json] | mcp")
76
+ return 0
77
+ cmd = argv[0]
78
+ if cmd == "list":
79
+ _print({"ok": True, "tools": tools()})
80
+ return 0
81
+ if cmd == "call":
82
+ if len(argv) < 3:
83
+ _print({"ok": False, "err": "usage: call <plugin> <tool> [json]"})
84
+ return 2
85
+ plugin, tool = argv[1], argv[2]
86
+ try:
87
+ args = json.loads(argv[3]) if len(argv) > 3 else {}
88
+ except Exception as exc:
89
+ _print({"ok": False, "err": "invalid json: %s" % exc})
90
+ return 2
91
+ if not isinstance(args, dict):
92
+ _print({"ok": False, "err": "arguments must be a JSON object"})
93
+ return 2
94
+ res = call(plugin, tool, args)
95
+ _print(res)
96
+ return 0 if res.get("ok") and res.get("allowed") is not False else 1
97
+ if cmd == "mcp":
98
+ from .mcp import main as mcp_main
99
+ return mcp_main()
100
+ _print({"ok": False, "err": "unknown command %r" % cmd})
101
+ return 2
102
+
103
+
104
+ def _plugin_main(plugin, argv=None):
105
+ argv = list(sys.argv[1:] if argv is None else argv)
106
+ if not argv:
107
+ _print({"ok": False, "err": "usage: gamai-%s <tool> [json]" % plugin})
108
+ return 2
109
+ args = {}
110
+ if len(argv) > 1:
111
+ try:
112
+ args = json.loads(argv[1])
113
+ except Exception as exc:
114
+ _print({"ok": False, "err": "invalid json: %s" % exc})
115
+ return 2
116
+ res = call(plugin, argv[0], args)
117
+ _print(res)
118
+ return 0 if res.get("ok") and res.get("allowed") is not False else 1
119
+
120
+
121
+ def trust_main(argv=None):
122
+ return _plugin_main("trust", argv)
123
+
124
+
125
+ def protean_main(argv=None):
126
+ return _plugin_main("protean", argv)
127
+
128
+
129
+ def team_main(argv=None):
130
+ return _plugin_main("team", argv)
131
+
132
+
133
+ if __name__ == "__main__":
134
+ raise SystemExit(main())
@@ -0,0 +1,89 @@
1
+ #!/usr/bin/env python3
2
+ """Minimal stdio MCP server for the portable GAMA plugins (stdlib only)."""
3
+ import json
4
+ import sys
5
+
6
+ from . import __version__
7
+ from .cli import call, tools
8
+
9
+ PROTOCOL = "2024-11-05"
10
+
11
+
12
+ def _tool_list():
13
+ return [{
14
+ "name": t["name"],
15
+ "description": "[%s] %s" % (t["plugin"], t["description"]),
16
+ "inputSchema": t["inputSchema"],
17
+ } for t in tools()]
18
+
19
+
20
+ def _find(name):
21
+ for t in tools():
22
+ if t["name"] == name:
23
+ return t
24
+ return None
25
+
26
+
27
+ def handle(req):
28
+ if not isinstance(req, dict):
29
+ return None
30
+ rid = req.get("id")
31
+ method = req.get("method")
32
+ if method == "initialize":
33
+ return {"jsonrpc": "2.0", "id": rid, "result": {
34
+ "protocolVersion": PROTOCOL,
35
+ "capabilities": {"tools": {}},
36
+ "serverInfo": {"name": "gamai-plugins", "version": __version__},
37
+ }}
38
+ if "id" not in req:
39
+ return None
40
+ if method == "notifications/initialized":
41
+ return None
42
+ if method == "ping":
43
+ return {"jsonrpc": "2.0", "id": rid, "result": {}}
44
+ if method == "tools/list":
45
+ return {"jsonrpc": "2.0", "id": rid, "result": {"tools": _tool_list()}}
46
+ if method == "tools/call":
47
+ params = req.get("params") or {}
48
+ name = params.get("name") or ""
49
+ args = params.get("arguments") or {}
50
+ t = _find(name)
51
+ if t is None:
52
+ return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32601, "message": "unknown tool %r" % name}}
53
+ res = call(t["plugin"], t["tool"], args, t.get("timeout_s"))
54
+ text = json.dumps(res, ensure_ascii=False, indent=2)
55
+ return {"jsonrpc": "2.0", "id": rid, "result": {
56
+ "content": [{"type": "text", "text": text}],
57
+ "isError": bool(res.get("ok") is False or res.get("allowed") is False),
58
+ }}
59
+ return {"jsonrpc": "2.0", "id": rid, "error": {"code": -32601, "message": "unknown method %r" % method}}
60
+
61
+
62
+ def main(argv=None):
63
+ argv = list(sys.argv[1:] if argv is None else argv)
64
+ for stream in (sys.stdin, sys.stdout):
65
+ try:
66
+ stream.reconfigure(encoding="utf-8", errors="replace")
67
+ except Exception:
68
+ pass
69
+ if "--selftest" in argv:
70
+ print(json.dumps({"ok": True, "tools": len(tools()), "names": [t["name"] for t in tools()]}, indent=2))
71
+ return 0
72
+ for line in sys.stdin:
73
+ line = line.strip()
74
+ if not line:
75
+ continue
76
+ try:
77
+ req = json.loads(line)
78
+ except Exception:
79
+ continue
80
+ requests = req if isinstance(req, list) else [req]
81
+ for item in requests:
82
+ out = handle(item)
83
+ if out is not None:
84
+ print(json.dumps(out, ensure_ascii=False), flush=True)
85
+ return 0
86
+
87
+
88
+ if __name__ == "__main__":
89
+ raise SystemExit(main())