@yahyahammad/venastine 0.2.0 → 0.3.8

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 (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -0,0 +1,613 @@
1
+ """
2
+ tools/builtin/shell_sessions.py
3
+
4
+ ROADMAP_v3 §49, slices 1 and 2. The seven tools over shell sessions
5
+ (SS11): three that start one, one that types into an interactive one,
6
+ and three that act on this conversation's own.
7
+
8
+ WHAT A START IS. A `shell` command that keeps running after its call has
9
+ been answered. It is classified, approved and routed exactly as `shell`
10
+ would be -- the approval check IS `shell._shell_approval_check`, which the
11
+ registry requires by identity (SS16), and the TOCTOU guard is shell's own
12
+ `fallback_changed_refusal`. Nothing about where a command may run is decided
13
+ in this file. What is added is lifetime: a timeout the agent picks, clamped
14
+ once by the manager (SS13), and a wake when the session reports.
15
+
16
+ EXCEPT THE INTERACTIVE ONE (slice 2). `shell_interactive` opens a shell and
17
+ keeps it open, so the yes it obtains covers every line typed into it
18
+ afterwards -- which means the question cannot be asked about its first
19
+ line. Its gate is `shell._interactive_approval_check`, held by identity in
20
+ the same place and for the same reason, and the profile that routes it is
21
+ STATED rather than read off text (SS32). `shell_input` then asks nobody,
22
+ except for a line naming a protected segment (SS29) and never for a control
23
+ key (SS30).
24
+
25
+ WHERE THE SESSIONS LIVE. `core.shell_sessions.sessions`, the one manager;
26
+ this module is its tool face and owns no state. The owning thread is the
27
+ injected `memory`'s, never a param -- a model that could name the thread
28
+ could reach another conversation's sessions.
29
+
30
+ WHERE A START IS NOT OFFERED. Anywhere nothing will wake the run when a
31
+ session reports (SS17): a research pass, or any run outside a chat turn or a
32
+ subagent. All seven tools are hidden there by `available_check`, since
33
+ advertising a tool the model cannot usefully call is the D24 defect, and a
34
+ start is also refused before any approval prompt (`refusal_check`) and again
35
+ in the handler.
36
+ """
37
+
38
+ from __future__ import annotations
39
+
40
+ from typing import Literal, Optional
41
+
42
+ from pydantic import (
43
+ BaseModel,
44
+ Field,
45
+ StrictBool,
46
+ StrictInt,
47
+ )
48
+
49
+ import config
50
+ from core import shell_sessions as core_sessions
51
+ from security import capability, posture
52
+ from security.sandbox import SandboxUnavailable
53
+ from tools.base import invalid_params
54
+ from tools.builtin import shell
55
+
56
+ BACKGROUND = "shell_background"
57
+ MONITOR = "shell_monitor"
58
+ INTERACTIVE = "shell_interactive"
59
+ INPUT = "shell_input"
60
+
61
+ _KINDS = {BACKGROUND: core_sessions.KIND_BACKGROUND,
62
+ MONITOR: core_sessions.KIND_MONITOR,
63
+ INTERACTIVE: core_sessions.KIND_INTERACTIVE}
64
+
65
+
66
+ def available() -> bool:
67
+ """Whether this run can be woken when a session reports (SS17)."""
68
+ return core_sessions.has_consumer()
69
+
70
+
71
+ # ---------------------------------------------------------------------------
72
+ # ---- Schemas ----------------------------------------------------------------
73
+ # ---------------------------------------------------------------------------
74
+
75
+
76
+ _TIMEOUT_DESCRIPTION = (
77
+ "The longest this session may run, in seconds. Pick what the work needs: "
78
+ "while it runs the user's prompt is blocked. Above "
79
+ f"{config.SHELL_SESSION_TIMEOUT_CAP_S} it is capped at "
80
+ f"{config.SHELL_SESSION_TIMEOUT_CAP_S} and the result says so. When it is "
81
+ "reached the command is stopped and you are woken.")
82
+
83
+
84
+ class _StartParams(BaseModel):
85
+ command: str = Field(
86
+ ..., min_length=1,
87
+ description=("The shell command to start. It runs where `shell` would "
88
+ "run it and is approved the same way; read `ran_on` in "
89
+ "the result."))
90
+ rationale: str = Field(
91
+ default="",
92
+ description=shell.ShellParams.model_fields["rationale"].description)
93
+ timeout_s: StrictInt = Field(..., ge=1, description=_TIMEOUT_DESCRIPTION)
94
+ requires_network: StrictBool = Field(
95
+ default=False,
96
+ description=shell.ShellParams.model_fields[
97
+ "requires_network"].description)
98
+
99
+
100
+ def _backend_field():
101
+ """The `backend` field, on the two start tools that take one.
102
+
103
+ NOT on `_StartParams`, which `InteractiveParams` also inherits:
104
+ `start_interactive` refuses WSL and SSH by name (WSL's stream shape
105
+ there is unmeasured; SSH's was measured and is WORSE -- a remote pty
106
+ merges stderr into stdout and CRLFs every line), and a parameter
107
+ whose only legal value is the default is one the model will spend a
108
+ call discovering. A tool advertises what it can do.
109
+ """
110
+ return Field(
111
+ default="container",
112
+ description=shell.ShellParams.model_fields["backend"].description)
113
+
114
+
115
+ def _root_field():
116
+ """The `needs_root` field, on the two start tools that take one.
117
+
118
+ `_backend_field`'s sibling, and absent from `InteractiveParams` for
119
+ exactly `_backend_field`'s reason: `start_interactive` is the container
120
+ route or nothing (SS28), and in the container the shell is ALREADY
121
+ root, so the flag there would name a privilege the session has and a
122
+ backend it cannot reach.
123
+
124
+ A FRESH `Field`, not the one off `ShellParams` -- a `FieldInfo` belongs
125
+ to the model that owns it, and handing the same object to two models is
126
+ shared mutable state in the one place a schema must not drift. The
127
+ DESCRIPTION is read across, which is the part that has to stay one
128
+ sentence in one place.
129
+ """
130
+ return Field(
131
+ default=False,
132
+ description=shell.ShellParams.model_fields["needs_root"].description)
133
+
134
+
135
+ class BackgroundParams(_StartParams):
136
+ backend: Literal["container", "wsl", "ssh"] = _backend_field()
137
+ needs_root: StrictBool = _root_field()
138
+
139
+
140
+ class MonitorParams(_StartParams):
141
+ pattern: str = Field(
142
+ ..., min_length=1,
143
+ description=("An RE2 regular expression searched for in each line of "
144
+ "output; not anchored, so use ^ and $ to anchor. No "
145
+ "backreferences or lookaround. It is matched against the "
146
+ "raw output, and what you are shown is redacted."))
147
+ backend: Literal["container", "wsl", "ssh"] = _backend_field()
148
+ needs_root: StrictBool = _root_field()
149
+
150
+
151
+ _WAIT_DESCRIPTION = (
152
+ "How long to wait for output, in seconds, before returning anyway. "
153
+ "The call ALWAYS returns by then; the session keeps running and you "
154
+ "can read more with another shell_input carrying no text.")
155
+
156
+
157
+ class InteractiveParams(_StartParams):
158
+ command: str = Field(
159
+ ..., min_length=1,
160
+ description=(
161
+ "The first line to type into the shell -- `python3` for a "
162
+ "Python REPL, `psql ...` for a database client, or `pwd` if "
163
+ "you just want a shell to work in. Approving the session "
164
+ "approves everything you type into it afterwards, so this "
165
+ "line is a starting point and not a limit."))
166
+ wait_s: StrictInt = Field(default=10, ge=1, le=120,
167
+ description=_WAIT_DESCRIPTION)
168
+
169
+
170
+ class InputParams(BaseModel):
171
+ session: str = Field(..., min_length=1,
172
+ description="The session id, such as \"s1\".")
173
+ text: str = Field(
174
+ default="",
175
+ description=(
176
+ "The line to type. A newline is added for you. Leave it out "
177
+ "to type nothing and just read more output -- which is what "
178
+ "to do when a previous call came back `quiet` or `bound`."))
179
+ control: Optional[Literal["interrupt", "eof"]] = Field(
180
+ default=None,
181
+ description=(
182
+ "Send a control key instead of text: \"interrupt\" is Ctrl-C, "
183
+ "which stops whatever is running without closing the "
184
+ "session, and \"eof\" is Ctrl-D. Use interrupt when a "
185
+ "command will not finish or is waiting for input you cannot "
186
+ "give."))
187
+ wait_s: StrictInt = Field(default=10, ge=1, le=120,
188
+ description=_WAIT_DESCRIPTION)
189
+ wait_for: Optional[str] = Field(
190
+ default=None,
191
+ description=(
192
+ "An RE2 regular expression. Return as soon as a line of "
193
+ "output matches it, instead of waiting for the shell to come "
194
+ "back to its prompt. Useful when a program prints a prompt of "
195
+ "its own and then waits for you."))
196
+
197
+
198
+ class OutputParams(BaseModel):
199
+ session: str = Field(..., min_length=1,
200
+ description="The session id, such as \"s1\".")
201
+ offset: StrictInt = Field(
202
+ default=0, ge=0,
203
+ description=("The character to start from. Use `next_offset` from the "
204
+ "previous page."))
205
+ limit: Optional[StrictInt] = Field(
206
+ default=None, ge=1,
207
+ description=(f"How many characters to return; at most and by default "
208
+ f"{config.MAX_READ_CHARS}."))
209
+
210
+
211
+ class KillParams(BaseModel):
212
+ session: str = Field(..., min_length=1,
213
+ description="The session id, such as \"s1\".")
214
+
215
+
216
+ _SHARED = (
217
+ f"At most {config.SHELL_SESSION_MAX_LIVE} sessions run at once, shared with "
218
+ "any subagents, and the user's prompt is blocked while one of yours runs. "
219
+ "Read output with shell_output and stop a session with shell_kill.")
220
+
221
+
222
+ def _schema(name: str, description: str, model, required) -> dict:
223
+ input_schema = model.model_json_schema()
224
+ # §42 (RA4), shell's rule: the rationale is ADVERTISED as required and
225
+ # tolerated when absent, because approval is obtained before the params
226
+ # are validated and a hard requirement would spend a human's yes on a
227
+ # call that then fails.
228
+ input_schema["required"] = list(required)
229
+ return {"name": name, "description": description,
230
+ "input_schema": input_schema}
231
+
232
+
233
+ BACKGROUND_TOOL_SCHEMA = _schema(
234
+ BACKGROUND,
235
+ "Start a shell command that keeps running after this call returns -- a "
236
+ "test suite, a build, a server you need up while you work. The call "
237
+ "returns at once with a session id; when the command finishes or reaches "
238
+ "its timeout you are woken with its exit code and the end of its output, "
239
+ "so do not poll it. " + _SHARED,
240
+ BackgroundParams,
241
+ ("command", "rationale", "timeout_s", "requires_network"))
242
+
243
+ MONITOR_TOOL_SCHEMA = _schema(
244
+ MONITOR,
245
+ "Start a shell command in the background and be woken each time a line of "
246
+ "its output matches `pattern` -- when a log says ERROR, a server says it "
247
+ "is listening, a test fails -- and again when it finishes. Matches that "
248
+ "arrive while you are working are delivered together. " + _SHARED,
249
+ MonitorParams,
250
+ ("command", "pattern", "rationale", "timeout_s", "requires_network"))
251
+
252
+ _INTERACTIVE_SHARED = (
253
+ f"At most {config.SHELL_SESSION_MAX_LIVE} sessions run at once, shared "
254
+ "with any subagents. Unlike a background command an open shell does "
255
+ "NOT block the user, and nothing wakes you when it closes -- so close "
256
+ "it with shell_kill when you are done. It closes itself after "
257
+ f"{config.SHELL_SESSION_IDLE_TIMEOUT_S}s with nothing typed into it.")
258
+
259
+ INTERACTIVE_TOOL_SCHEMA = _schema(
260
+ INTERACTIVE,
261
+ "Open a shell inside the container and KEEP IT OPEN, so you can type "
262
+ "into it and read the reply: a Python or node REPL, a database "
263
+ "client, an ssh-less debugging session, anything where the next "
264
+ "command depends on what the last one printed. What you do in it "
265
+ "persists -- the working directory, environment variables, an "
266
+ "interpreter's state -- across your own turns. Send input with "
267
+ "shell_input. Programs that paint the whole screen (vim, htop, less) "
268
+ "are NOT supported: use shell for those or run them non-interactively. "
269
+ + _INTERACTIVE_SHARED,
270
+ InteractiveParams,
271
+ ("command", "rationale", "timeout_s", "requires_network"))
272
+
273
+ INPUT_TOOL_SCHEMA = _schema(
274
+ INPUT,
275
+ "Type a line into an interactive session and read what comes back. "
276
+ "The call always returns: it ends as soon as the shell comes back to "
277
+ "its prompt, or a line matches `wait_for`, or output goes quiet, or "
278
+ "`wait_s` runs out -- and `ended` says WHICH, which you need, because "
279
+ "only \"ready\" means the command finished. Silence does not: a "
280
+ "command that takes a minute is silent for a minute. When you get "
281
+ "anything else, call again with no text to keep reading. Do NOT send a "
282
+ "new command before you get \"ready\": the terminal queues it behind "
283
+ "the one still running, and the reply you get back may be the earlier "
284
+ "command's.",
285
+ InputParams, ("session",))
286
+
287
+ SESSIONS_TOOL_SCHEMA = {
288
+ "name": "shell_sessions",
289
+ "description": (
290
+ "List this conversation's background and monitor sessions: id, kind, "
291
+ "command, status, elapsed time, timeout, exit code, how much output "
292
+ "each has written and how many lines matched. Finished sessions stay "
293
+ "listed for a while."),
294
+ "input_schema": {"type": "object", "properties": {}, "required": []},
295
+ }
296
+
297
+ OUTPUT_TOOL_SCHEMA = _schema(
298
+ "shell_output",
299
+ "Read one of this conversation's background sessions' output by character "
300
+ f"offset. Only its first {config.SHELL_SESSION_OUTPUT_HEAD_CHARS} and most "
301
+ f"recent {config.SHELL_SESSION_OUTPUT_TAIL_CHARS} characters are kept; a "
302
+ "page that reaches the dropped middle says where the gap is and continues "
303
+ "past it. Output is not kept after the harness exits.",
304
+ OutputParams, ("session",))
305
+
306
+ KILL_TOOL_SCHEMA = _schema(
307
+ "shell_kill",
308
+ "Stop one of this conversation's background sessions. Returns its final "
309
+ "status, the end of its output and any matched lines you had not yet "
310
+ "been shown. You are not woken for a session you stopped yourself.",
311
+ KillParams, ("session",))
312
+
313
+
314
+ # ---------------------------------------------------------------------------
315
+ # ---- Before approval ----------------------------------------------------------
316
+ # ---------------------------------------------------------------------------
317
+
318
+
319
+ #: Why these params would not validate, in one line, or None.
320
+ #:
321
+ #: MOVED TO tools/base.py IN BATCH 146, where the refusal_check contract it
322
+ #: serves is defined, because file_ops' gates now need it too -- they were
323
+ #: the one pair in the tree that was not total over a JSON object, and this
324
+ #: is the renderer that made the sibling's refusals readable. The name stays
325
+ #: so the six call sites below read as they always did.
326
+ _invalid = invalid_params
327
+
328
+
329
+ def _start_refusal(name: str, model):
330
+ def refusal(params: dict, context=None) -> Optional[str]:
331
+ """§32 A7: a start that will be refused is not asked about. Bad
332
+ arguments, a bad pattern, nothing to wake, or the cap."""
333
+ invalid = _invalid(name, model, params)
334
+ if invalid:
335
+ return invalid
336
+ return core_sessions.sessions.start_refusal(
337
+ _KINDS[name], params.get("pattern"))
338
+ return refusal
339
+
340
+
341
+ background_refusal = _start_refusal(BACKGROUND, BackgroundParams)
342
+ monitor_refusal = _start_refusal(MONITOR, MonitorParams)
343
+ interactive_refusal = _start_refusal(INTERACTIVE, InteractiveParams)
344
+
345
+
346
+ def _start_notice(name: str):
347
+ def notice(params: dict, context=None) -> str:
348
+ """Shell's notice -- where it runs -- plus what a session adds: how
349
+ long it may keep running, and for a monitor what wakes the agent."""
350
+ text = shell._shell_approval_notice(params, context)
351
+ requested = params.get("timeout_s")
352
+ if isinstance(requested, int) and not isinstance(requested, bool) \
353
+ and requested >= 1:
354
+ timeout, capped = core_sessions.SessionManager.effective_timeout(
355
+ requested)
356
+ text += (f" Keeps running after this call returns, for up to "
357
+ f"{timeout}s"
358
+ + (f" (asked for {requested}s, capped)" if capped else "")
359
+ + ".")
360
+ pattern = params.get("pattern")
361
+ if name == MONITOR and isinstance(pattern, str):
362
+ text += f" Wakes the agent on every output line matching {pattern!r}."
363
+ return text
364
+ return notice
365
+
366
+
367
+ background_notice = _start_notice(BACKGROUND)
368
+ monitor_notice = _start_notice(MONITOR)
369
+
370
+
371
+ def interactive_notice(params: dict, context=None) -> str:
372
+ """Shell's interactive notice -- which says the yes covers the whole
373
+ session (SS29) -- plus how long the shell may live.
374
+
375
+ Not `_start_notice`: that one describes a COMMAND, and describing a
376
+ session's first line as though it were the thing being approved is
377
+ exactly what `_interactive_approval_check` refuses to do.
378
+ """
379
+ text = shell._interactive_approval_notice(params, context)
380
+ requested = params.get("timeout_s")
381
+ if isinstance(requested, int) and not isinstance(requested, bool) \
382
+ and requested >= 1:
383
+ timeout, capped = core_sessions.SessionManager.effective_timeout(
384
+ requested)
385
+ text += (f" Stays open for up to {timeout}s"
386
+ + (f" (asked for {requested}s, capped)" if capped else "")
387
+ + f", or {config.SHELL_SESSION_IDLE_TIMEOUT_S}s with "
388
+ f"nothing typed into it.")
389
+ return text
390
+
391
+
392
+ def input_refusal(params: dict, context=None) -> Optional[str]:
393
+ """§32 A7: a send that will be refused is not asked about."""
394
+ return _invalid(INPUT, InputParams, params)
395
+
396
+
397
+ def declared_control(params) -> str:
398
+ """Which control key a call asked for, or "" (batch 108).
399
+
400
+ `declared_network`, `declared_backend` and `declared_root`'s sibling,
401
+ and a function for their reason exactly: the gate reads the model's
402
+ tool-call input BEFORE Pydantic has seen it, so this value can be any
403
+ JSON at all. This was `params.get("control")` read for TRUTH, which is
404
+ a different question from the one `InputParams` asks and a wider one --
405
+ `"xyz"`, `True` and `["interrupt"]` are all truthy and none is a
406
+ control key.
407
+
408
+ ONLY A RECOGNISED KEY counts, and it is checked against
409
+ `core.shell_sessions.CONTROLS` -- the dict the RUNNER indexes -- rather
410
+ than against a second spelling of the two literals here. A gate and a
411
+ runner that each carry their own copy of the vocabulary is the drift
412
+ #157 came from, one field over.
413
+
414
+ WHAT WAS ACTUALLY SAFE ABOUT THE OLD READ, stated because it was true
415
+ and unwritten, which is the worse half. A control key skips approval
416
+ (SS30) and the skip sits ABOVE the mode switch, so it skipped even
417
+ under `always` -- and a call sending `control` AND `text` therefore
418
+ typed neither prompt nor question. It could not type the text either,
419
+ but only because `Sessions.send` is `if control: ... elif text: ...`
420
+ and DISCARDS the text. That property lives in another module's
421
+ if/elif, nothing named it, and a later change honouring both fields
422
+ would have silently stopped the gate asking. It is pinned by a test
423
+ now.
424
+
425
+ Narrowing this is monotonically safer and changes nothing that runs: an
426
+ unrecognised value now falls through to the ordinary ladder, where it
427
+ may cost one prompt, and `Optional[Literal["interrupt", "eof"]]`
428
+ refuses it at run time either way so nothing executes.
429
+ """
430
+ if not isinstance(params, dict):
431
+ return ""
432
+ asked = params.get("control")
433
+ if isinstance(asked, str) and asked in core_sessions.CONTROLS:
434
+ return asked
435
+ return ""
436
+
437
+
438
+ def input_approval_check(tool_name: str, params: dict) -> bool:
439
+ """Whether typing this line needs a human yes (SS29, SS30).
440
+
441
+ A RECOGNISED CONTROL key is ungated first, above the mode, for SS11's
442
+ reason:
443
+ `shell_kill` destroys the whole session and asks nobody, so
444
+ interrupting one command inside it cannot need more. It is also the
445
+ only escape from a command that will not finish, and a gate on the
446
+ escape hatch is a gate that fires exactly when it cannot be answered.
447
+
448
+ Otherwise the open call's approval covers this line (SS29) -- except
449
+ that a line naming a protected path segment asks anyway, which is
450
+ `_shell_approval_check`'s step 2 applied one layer along: the same
451
+ check, the same always-ASK polarity, and the same reason for never
452
+ being a deny (G2 -- this does not parse the text).
453
+ """
454
+ if declared_control(params):
455
+ return False
456
+ active = posture.current()
457
+ mode = capability.validate_mode(active.shell_approval_mode,
458
+ "config.SHELL_APPROVAL_MODE")
459
+ if mode == capability.ALWAYS:
460
+ return True
461
+ if mode == capability.NEVER:
462
+ return False
463
+ text = params.get("text", "") if isinstance(params, dict) else ""
464
+ return shell._command_touches_protected(text) is not None
465
+
466
+
467
+ def input_notice(params: dict, context=None) -> str:
468
+ text = params.get("text", "") if isinstance(params, dict) else ""
469
+ segment = shell._command_touches_protected(text)
470
+ where = (f" It names {segment}, which is protected -- the session's "
471
+ f"own approval does not cover that." if segment else "")
472
+ return (f"Types into an interactive shell this conversation already "
473
+ f"opened.{where}")
474
+
475
+
476
+ # ---------------------------------------------------------------------------
477
+ # ---- Handlers -------------------------------------------------------------------
478
+ # ---------------------------------------------------------------------------
479
+
480
+
481
+ def _outside(name: str) -> dict:
482
+ # Reachable only when dispatched outside a run: todo_write's reasoning.
483
+ return {"error": f"{name} is only available inside a conversation."}
484
+
485
+
486
+ def _start(name: str, model, params: dict, memory, call_id) -> dict:
487
+ invalid = _invalid(name, model, params)
488
+ if invalid:
489
+ return {"error": invalid}
490
+ if memory is None:
491
+ return _outside(name)
492
+ parsed = model(**params)
493
+ # ONE probe, read through `shell` so the approval check and this call
494
+ # see the same answer (§40 keeps the posture fixed; the probe is cached).
495
+ # SS37/SS40/SS54, before the probe and before anything is classified:
496
+ # a session that asked for WSL or SSH and cannot have it is refused by
497
+ # name. `shell_interactive` has no `backend` field, so this is the
498
+ # container for it and the refusal that DOES apply to it comes from
499
+ # `start_interactive` -- which is the one that knows why.
500
+ backend = getattr(parsed, "backend", shell.BACKEND_CONTAINER)
501
+ # `shell_interactive` has no `needs_root` for `_root_field`'s reason,
502
+ # so the getattr default is the honest answer rather than a guard.
503
+ needs_root = bool(getattr(parsed, "needs_root", False))
504
+ refusal = shell.uncontained_refusal(parsed.command, backend, needs_root)
505
+ if refusal is not None:
506
+ return {"error": refusal}
507
+ # See `shell.run` for why an uncontained call does not probe: the guard
508
+ # the probe feeds is about the insecure fallback, which it cannot take.
509
+ docker_up = (True if backend != shell.BACKEND_CONTAINER
510
+ else shell.is_docker_available())
511
+ if name == INTERACTIVE:
512
+ # SS32: what is approved is a SHELL, not the first line, so the
513
+ # profile that routes it says so rather than being read off text
514
+ # whose later lines are not there yet. It is also what the gate
515
+ # asked about -- `_interactive_approval_check` builds this same
516
+ # profile -- so §28's rule that the two agree still holds.
517
+ profile = shell.interactive_profile(parsed.requires_network)
518
+ # No `fallback_changed_refusal`: its subject is a command that
519
+ # would silently move to the insecure fallback, and SS28 gives an
520
+ # interactive session no route to move to. `start_interactive`
521
+ # refuses a missing runtime outright, and says what to install --
522
+ # where this would have said "retry, you will be asked", which
523
+ # for this kind is not true.
524
+ else:
525
+ profile = shell.classify_command(
526
+ parsed.command, config.WORKSPACE_DIR,
527
+ requires_network=parsed.requires_network)
528
+ if backend != shell.BACKEND_WSL:
529
+ refusal = shell.fallback_changed_refusal(
530
+ parsed.command, docker_up)
531
+ if refusal is not None:
532
+ return {"error": refusal}
533
+ try:
534
+ return core_sessions.sessions.start(
535
+ kind=_KINDS[name], command=parsed.command,
536
+ # §28: the SAME profile the approval check used -- the §50
537
+ # declaration included, which `start_sandboxed` already passes
538
+ # into the container argv as `profile.network` (NW4), so the
539
+ # flag reaches a session with no other change.
540
+ profile=profile,
541
+ docker_available=docker_up,
542
+ backend=backend,
543
+ needs_root=needs_root,
544
+ requested_timeout_s=parsed.timeout_s,
545
+ owner_thread=memory.thread_id,
546
+ workspace_dir=config.WORKSPACE_DIR,
547
+ call_id=call_id or "",
548
+ # Display only (§42, RA2): shown in the session's view, never
549
+ # read to decide anything.
550
+ rationale=parsed.rationale,
551
+ pattern=getattr(parsed, "pattern", None),
552
+ open_wait_s=getattr(parsed, "wait_s", 10))
553
+ except (core_sessions.SessionRefused, SandboxUnavailable) as e:
554
+ return {"error": str(e)}
555
+
556
+
557
+ def background_run(params: dict, memory=None, call_id=None) -> dict:
558
+ return _start(BACKGROUND, BackgroundParams, params, memory, call_id)
559
+
560
+
561
+ def monitor_run(params: dict, memory=None, call_id=None) -> dict:
562
+ return _start(MONITOR, MonitorParams, params, memory, call_id)
563
+
564
+
565
+ def interactive_run(params: dict, memory=None, call_id=None) -> dict:
566
+ return _start(INTERACTIVE, InteractiveParams, params, memory, call_id)
567
+
568
+
569
+ def input_run(params: dict, memory=None) -> dict:
570
+ invalid = _invalid(INPUT, InputParams, params)
571
+ if invalid:
572
+ return {"error": invalid}
573
+ if memory is None:
574
+ return _outside(INPUT)
575
+ parsed = InputParams(**params)
576
+ return core_sessions.sessions.send(
577
+ parsed.session, memory.thread_id, text=parsed.text,
578
+ control=parsed.control or "", wait_s=parsed.wait_s,
579
+ wait_for=parsed.wait_for)
580
+
581
+
582
+ def sessions_run(params: dict, memory=None) -> dict:
583
+ if memory is None:
584
+ return _outside("shell_sessions")
585
+ listed = core_sessions.sessions.list_for(memory.thread_id)
586
+ if not listed:
587
+ return {"sessions": [],
588
+ "note": "This conversation has no background sessions."}
589
+ return {"sessions": listed}
590
+
591
+
592
+ def output_run(params: dict, memory=None) -> dict:
593
+ invalid = _invalid("shell_output", OutputParams, params)
594
+ if invalid:
595
+ return {"error": invalid}
596
+ if memory is None:
597
+ return _outside("shell_output")
598
+ parsed = OutputParams(**params)
599
+ limit = min(parsed.limit or config.MAX_READ_CHARS, config.MAX_READ_CHARS)
600
+ return core_sessions.sessions.output(parsed.session, memory.thread_id,
601
+ offset=parsed.offset, limit=limit)
602
+
603
+
604
+ def kill_run(params: dict, memory=None) -> dict:
605
+ invalid = _invalid("shell_kill", KillParams, params)
606
+ if invalid:
607
+ return {"error": invalid}
608
+ if memory is None:
609
+ return _outside("shell_kill")
610
+ parsed = KillParams(**params)
611
+ return core_sessions.sessions.kill(parsed.session,
612
+ owner_thread=memory.thread_id,
613
+ reason=core_sessions.KILL_MODEL)