shikiru-cli 0.2.0__py3-none-any.whl

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 (319) hide show
  1. shikiru/__init__.py +1 -0
  2. shikiru/__main__.py +8 -0
  3. shikiru/agents/__init__.py +3 -0
  4. shikiru/agents/contracts.py +590 -0
  5. shikiru/agents/registry.py +87 -0
  6. shikiru/agents/sdk/__init__.py +17 -0
  7. shikiru/agents/sdk/reset_time.py +137 -0
  8. shikiru/agents/sdk/turn.py +335 -0
  9. shikiru/agents/settings.py +151 -0
  10. shikiru/agents/testing/__init__.py +26 -0
  11. shikiru/agents/testing/contract_suite.py +653 -0
  12. shikiru/agents/testing/resume.py +15 -0
  13. shikiru/bootstrap.py +1277 -0
  14. shikiru/cli/__init__.py +1 -0
  15. shikiru/cli/app.py +770 -0
  16. shikiru/cli/context.py +63 -0
  17. shikiru/cli/render.py +1475 -0
  18. shikiru/cli/report.py +156 -0
  19. shikiru/cli/session_prompt.py +63 -0
  20. shikiru/cli/view.py +131 -0
  21. shikiru/clock.py +41 -0
  22. shikiru/config/__init__.py +8 -0
  23. shikiru/config/defaults.toml +131 -0
  24. shikiru/config/loader.py +178 -0
  25. shikiru/config/settings.py +392 -0
  26. shikiru/dashboard/__init__.py +3 -0
  27. shikiru/dashboard/actions_list.py +799 -0
  28. shikiru/dashboard/activity.py +150 -0
  29. shikiru/dashboard/app.py +1765 -0
  30. shikiru/dashboard/blocker_evidence.py +122 -0
  31. shikiru/dashboard/blocker_rows.py +84 -0
  32. shikiru/dashboard/briefing_view.py +871 -0
  33. shikiru/dashboard/contract.py +1086 -0
  34. shikiru/dashboard/covered.py +32 -0
  35. shikiru/dashboard/detail.py +1209 -0
  36. shikiru/dashboard/detail_fold.py +244 -0
  37. shikiru/dashboard/detail_hint.py +68 -0
  38. shikiru/dashboard/details_list_view.py +150 -0
  39. shikiru/dashboard/diagnostics.py +80 -0
  40. shikiru/dashboard/diagnostics_sections.py +186 -0
  41. shikiru/dashboard/evidence_table.py +123 -0
  42. shikiru/dashboard/extra_details.py +214 -0
  43. shikiru/dashboard/fault_guidance.py +216 -0
  44. shikiru/dashboard/fold_bodies.py +276 -0
  45. shikiru/dashboard/help_keys.py +166 -0
  46. shikiru/dashboard/help_screen.py +204 -0
  47. shikiru/dashboard/interaction.py +17 -0
  48. shikiru/dashboard/ladder_editor.py +544 -0
  49. shikiru/dashboard/live_settings.py +62 -0
  50. shikiru/dashboard/motion.py +368 -0
  51. shikiru/dashboard/orchestration_fields.py +201 -0
  52. shikiru/dashboard/palette.py +1606 -0
  53. shikiru/dashboard/palette_app.py +89 -0
  54. shikiru/dashboard/palette_drafts.py +33 -0
  55. shikiru/dashboard/resolution.py +573 -0
  56. shikiru/dashboard/resolution_view.py +302 -0
  57. shikiru/dashboard/row_list.py +256 -0
  58. shikiru/dashboard/section_rows.py +173 -0
  59. shikiru/dashboard/services.py +665 -0
  60. shikiru/dashboard/session_history.py +402 -0
  61. shikiru/dashboard/shikiru_init_ascii_art.txt +40 -0
  62. shikiru/dashboard/task_picker.py +358 -0
  63. shikiru/dashboard/tick.py +59 -0
  64. shikiru/dashboard/timeline_filter.py +129 -0
  65. shikiru/dashboard/timeline_section.py +385 -0
  66. shikiru/dashboard/usage_body.py +269 -0
  67. shikiru/dashboard/views.py +2314 -0
  68. shikiru/dashboard/wizard.py +1389 -0
  69. shikiru/domain/__init__.py +1 -0
  70. shikiru/domain/acceptance.py +130 -0
  71. shikiru/domain/activity.py +28 -0
  72. shikiru/domain/attempts.py +333 -0
  73. shikiru/domain/briefing.py +257 -0
  74. shikiru/domain/commands.py +219 -0
  75. shikiru/domain/decisions.py +231 -0
  76. shikiru/domain/docker.py +262 -0
  77. shikiru/domain/engine_uptime.py +87 -0
  78. shikiru/domain/escalation.py +194 -0
  79. shikiru/domain/escalation_evidence.py +186 -0
  80. shikiru/domain/escalation_panel.py +144 -0
  81. shikiru/domain/events.py +71 -0
  82. shikiru/domain/evidence_export.py +89 -0
  83. shikiru/domain/faults.py +86 -0
  84. shikiru/domain/feedback.py +180 -0
  85. shikiru/domain/feedback_rounds.py +172 -0
  86. shikiru/domain/fencing.py +31 -0
  87. shikiru/domain/ladder.py +102 -0
  88. shikiru/domain/ladder_text.py +44 -0
  89. shikiru/domain/levels.py +44 -0
  90. shikiru/domain/motion.py +199 -0
  91. shikiru/domain/packet_evidence.py +377 -0
  92. shikiru/domain/pushes.py +47 -0
  93. shikiru/domain/quota_blocks.py +44 -0
  94. shikiru/domain/quota_waits.py +219 -0
  95. shikiru/domain/recovery.py +194 -0
  96. shikiru/domain/reports.py +498 -0
  97. shikiru/domain/results.py +217 -0
  98. shikiru/domain/runs.py +85 -0
  99. shikiru/domain/scheduling.py +231 -0
  100. shikiru/domain/status_tasks.py +40 -0
  101. shikiru/domain/steps.py +325 -0
  102. shikiru/domain/tasks.py +174 -0
  103. shikiru/domain/timeline.py +208 -0
  104. shikiru/domain/timeline_phrases.py +271 -0
  105. shikiru/domain/versions.py +18 -0
  106. shikiru/domain/workflow.py +372 -0
  107. shikiru/engine/__init__.py +0 -0
  108. shikiru/engine/acceptance.py +90 -0
  109. shikiru/engine/agents.py +61 -0
  110. shikiru/engine/cosmetic_decorator.py +99 -0
  111. shikiru/engine/daemon.py +409 -0
  112. shikiru/engine/dependency.py +37 -0
  113. shikiru/engine/escalation_filing.py +110 -0
  114. shikiru/engine/escalations.py +401 -0
  115. shikiru/engine/events.py +285 -0
  116. shikiru/engine/evidence.py +81 -0
  117. shikiru/engine/fault_reporter.py +144 -0
  118. shikiru/engine/feedback.py +577 -0
  119. shikiru/engine/feedback_audit.py +80 -0
  120. shikiru/engine/feedback_intake.py +95 -0
  121. shikiru/engine/feedback_snapshot.py +148 -0
  122. shikiru/engine/flow.py +87 -0
  123. shikiru/engine/handlers/__init__.py +33 -0
  124. shikiru/engine/handlers/base.py +148 -0
  125. shikiru/engine/handlers/engine.py +24 -0
  126. shikiru/engine/handlers/escalations.py +174 -0
  127. shikiru/engine/handlers/operator.py +81 -0
  128. shikiru/engine/handlers/tasks.py +237 -0
  129. shikiru/engine/history.py +128 -0
  130. shikiru/engine/integration.py +1234 -0
  131. shikiru/engine/integration_turns.py +337 -0
  132. shikiru/engine/layout_guard.py +362 -0
  133. shikiru/engine/lifecycle.py +60 -0
  134. shikiru/engine/monitor.py +317 -0
  135. shikiru/engine/notification_delivery.py +124 -0
  136. shikiru/engine/notification_feed.py +57 -0
  137. shikiru/engine/notifier.py +91 -0
  138. shikiru/engine/pull_request_closing.py +117 -0
  139. shikiru/engine/push_service.py +177 -0
  140. shikiru/engine/quota_probe_threads.py +79 -0
  141. shikiru/engine/quota_reconciler.py +210 -0
  142. shikiru/engine/quota_schedule.py +24 -0
  143. shikiru/engine/quota_waits.py +102 -0
  144. shikiru/engine/reconcile.py +91 -0
  145. shikiru/engine/recovery.py +284 -0
  146. shikiru/engine/retention.py +102 -0
  147. shikiru/engine/root_preparation.py +86 -0
  148. shikiru/engine/scheduler.py +320 -0
  149. shikiru/engine/session_guard.py +46 -0
  150. shikiru/engine/sessions.py +95 -0
  151. shikiru/engine/signalled.py +75 -0
  152. shikiru/engine/step_runner.py +140 -0
  153. shikiru/engine/supervisor.py +101 -0
  154. shikiru/engine/takeover.py +223 -0
  155. shikiru/engine/task_facts.py +46 -0
  156. shikiru/engine/tick_guard.py +95 -0
  157. shikiru/engine/titles.py +297 -0
  158. shikiru/engine/transitions.py +79 -0
  159. shikiru/engine/turn_context.py +206 -0
  160. shikiru/engine/turn_execution.py +30 -0
  161. shikiru/engine/turn_loop.py +230 -0
  162. shikiru/engine/turn_processes.py +79 -0
  163. shikiru/engine/turns.py +457 -0
  164. shikiru/errors.py +144 -0
  165. shikiru/helper/__init__.py +3 -0
  166. shikiru/helper/helper.py +182 -0
  167. shikiru/helper/models.py +11 -0
  168. shikiru/mcp/__init__.py +1 -0
  169. shikiru/mcp/server.py +196 -0
  170. shikiru/operator/__init__.py +33 -0
  171. shikiru/operator/attachment.py +24 -0
  172. shikiru/operator/commands.py +319 -0
  173. shikiru/operator/detectors.py +374 -0
  174. shikiru/operator/doctor.py +351 -0
  175. shikiru/operator/events.py +57 -0
  176. shikiru/operator/evidence_export.py +498 -0
  177. shikiru/operator/evidence_writer.py +78 -0
  178. shikiru/operator/lifecycle.py +294 -0
  179. shikiru/operator/plugin_checks.py +194 -0
  180. shikiru/operator/probe.py +287 -0
  181. shikiru/operator/queries.py +1601 -0
  182. shikiru/operator/services.py +36 -0
  183. shikiru/operator/sessions.py +378 -0
  184. shikiru/operator/strip_views.py +162 -0
  185. shikiru/operator/timeline.py +416 -0
  186. shikiru/operator/toml_text.py +62 -0
  187. shikiru/palette.py +18 -0
  188. shikiru/paths.py +91 -0
  189. shikiru/plugins/__init__.py +0 -0
  190. shikiru/plugins/agents/__init__.py +1 -0
  191. shikiru/plugins/agents/claude/__init__.py +5 -0
  192. shikiru/plugins/agents/claude/agent.py +251 -0
  193. shikiru/plugins/agents/claude/context.py +116 -0
  194. shikiru/plugins/agents/claude/headless.py +92 -0
  195. shikiru/plugins/agents/claude/hook.py +57 -0
  196. shikiru/plugins/agents/claude/model_catalog.py +105 -0
  197. shikiru/plugins/agents/claude/options.py +62 -0
  198. shikiru/plugins/agents/claude/turn.py +1018 -0
  199. shikiru/plugins/agents/codex/__init__.py +5 -0
  200. shikiru/plugins/agents/codex/agent.py +486 -0
  201. shikiru/plugins/agents/codex/headless.py +166 -0
  202. shikiru/plugins/agents/codex/home.py +14 -0
  203. shikiru/plugins/agents/codex/model_catalog.py +128 -0
  204. shikiru/plugins/agents/codex/options.py +94 -0
  205. shikiru/plugins/agents/codex/quota.py +195 -0
  206. shikiru/plugins/agents/codex/sandbox.py +31 -0
  207. shikiru/plugins/agents/codex/sandbox_probe.py +97 -0
  208. shikiru/plugins/agents/codex/turn.py +767 -0
  209. shikiru/plugins/agents/codex/usage.py +106 -0
  210. shikiru/plugins/agents/shared_settings.py +62 -0
  211. shikiru/plugins/widgets/__init__.py +3 -0
  212. shikiru/plugins/widgets/dialogue.py +144 -0
  213. shikiru/plugins/widgets/disk.py +123 -0
  214. shikiru/plugins/widgets/docker.py +225 -0
  215. shikiru/plugins/widgets/escalations.py +402 -0
  216. shikiru/plugins/widgets/faults.py +204 -0
  217. shikiru/plugins/widgets/header.py +321 -0
  218. shikiru/plugins/widgets/queue.py +1140 -0
  219. shikiru/plugins/widgets/queue_hint.py +93 -0
  220. shikiru/plugins/widgets/resources.py +105 -0
  221. shikiru/plugins/widgets/strips.py +82 -0
  222. shikiru/plugins/widgets/usage.py +176 -0
  223. shikiru/private.py +94 -0
  224. shikiru/process.py +535 -0
  225. shikiru/prompts/__init__.py +3 -0
  226. shikiru/prompts/renderer.py +85 -0
  227. shikiru/prompts/templates/_base.md.j2 +17 -0
  228. shikiru/prompts/templates/_macros.md.j2 +61 -0
  229. shikiru/prompts/templates/conflicts.md.j2 +22 -0
  230. shikiru/prompts/templates/consult.md.j2 +5 -0
  231. shikiru/prompts/templates/continue.md.j2 +4 -0
  232. shikiru/prompts/templates/feedback_analysis.md.j2 +29 -0
  233. shikiru/prompts/templates/feedback_rework.md.j2 +33 -0
  234. shikiru/prompts/templates/feedback_verify.md.j2 +33 -0
  235. shikiru/prompts/templates/handoff.md.j2 +23 -0
  236. shikiru/prompts/templates/implement.md.j2 +13 -0
  237. shikiru/prompts/templates/plan.md.j2 +30 -0
  238. shikiru/prompts/templates/rework.md.j2 +13 -0
  239. shikiru/prompts/templates/triage.md.j2 +20 -0
  240. shikiru/prompts/templates/verify.md.j2 +29 -0
  241. shikiru/store/__init__.py +1 -0
  242. shikiru/store/commands.py +242 -0
  243. shikiru/store/database.py +297 -0
  244. shikiru/store/escalations.py +240 -0
  245. shikiru/store/events.py +213 -0
  246. shikiru/store/feedback.py +266 -0
  247. shikiru/store/migrations/001_initial.sql +63 -0
  248. shikiru/store/migrations/002_headless_turns.sql +31 -0
  249. shikiru/store/migrations/003_drop_command_handled_at.sql +1 -0
  250. shikiru/store/migrations/004_repo_base_ref.sql +3 -0
  251. shikiru/store/migrations/005_complexity_explicit.sql +3 -0
  252. shikiru/store/migrations/006_events_kind_index.sql +1 -0
  253. shikiru/store/migrations/007_notification_cursor.sql +1 -0
  254. shikiru/store/migrations/008_reported_usage.sql +1 -0
  255. shikiru/store/migrations/009_billing_declarations.sql +2 -0
  256. shikiru/store/migrations/010_canonical_quota_windows.sql +3 -0
  257. shikiru/store/migrations/012_drop_task_quota_evidence.sql +2 -0
  258. shikiru/store/migrations/013_push_targets.sql +7 -0
  259. shikiru/store/migrations/014_agent_block_time.sql +6 -0
  260. shikiru/store/migrations/015_repair_orphan_agent_blocks.sql +3 -0
  261. shikiru/store/migrations/016_feedback_rounds.sql +29 -0
  262. shikiru/store/migrations/017_feedback_round_comments.sql +5 -0
  263. shikiru/store/migrations/__init__.py +1 -0
  264. shikiru/store/notification_cursor.py +29 -0
  265. shikiru/store/pushes.py +117 -0
  266. shikiru/store/quotas.py +153 -0
  267. shikiru/store/reader.py +310 -0
  268. shikiru/store/retention.py +92 -0
  269. shikiru/store/runs.py +227 -0
  270. shikiru/store/tasks.py +949 -0
  271. shikiru/telemetry/__init__.py +1 -0
  272. shikiru/telemetry/disk.py +167 -0
  273. shikiru/telemetry/docker.py +164 -0
  274. shikiru/telemetry/resources.py +296 -0
  275. shikiru/tmux/__init__.py +3 -0
  276. shikiru/tmux/client.py +637 -0
  277. shikiru/tmux/decorator.py +225 -0
  278. shikiru/tmux/layout.py +200 -0
  279. shikiru/tmux/session.py +381 -0
  280. shikiru/ui/__init__.py +9 -0
  281. shikiru/ui/age.py +45 -0
  282. shikiru/ui/bubbles.py +41 -0
  283. shikiru/ui/compact.py +1209 -0
  284. shikiru/ui/console.py +49 -0
  285. shikiru/ui/fold.py +50 -0
  286. shikiru/ui/gated_static.py +117 -0
  287. shikiru/ui/gauge.py +40 -0
  288. shikiru/ui/glyphs.py +109 -0
  289. shikiru/ui/keys.py +57 -0
  290. shikiru/ui/live_interval.py +42 -0
  291. shikiru/ui/popup.py +311 -0
  292. shikiru/ui/quota_status.py +26 -0
  293. shikiru/ui/recent_window.py +78 -0
  294. shikiru/ui/screen.py +57 -0
  295. shikiru/ui/section.py +193 -0
  296. shikiru/ui/session.py +65 -0
  297. shikiru/ui/size.py +17 -0
  298. shikiru/ui/splash.py +42 -0
  299. shikiru/ui/status.py +47 -0
  300. shikiru/ui/status_strip.py +149 -0
  301. shikiru/ui/stream.py +152 -0
  302. shikiru/ui/strip.py +332 -0
  303. shikiru/ui/theme.py +83 -0
  304. shikiru/ui/tokens.py +51 -0
  305. shikiru/view_log.py +126 -0
  306. shikiru/workspace/__init__.py +3 -0
  307. shikiru/workspace/base_refs.py +160 -0
  308. shikiru/workspace/caches.py +136 -0
  309. shikiru/workspace/facts.py +118 -0
  310. shikiru/workspace/git.py +601 -0
  311. shikiru/workspace/github.py +744 -0
  312. shikiru/workspace/messages.py +107 -0
  313. shikiru/workspace/reports.py +145 -0
  314. shikiru/workspace/roots.py +180 -0
  315. shikiru_cli-0.2.0.dist-info/METADATA +428 -0
  316. shikiru_cli-0.2.0.dist-info/RECORD +319 -0
  317. shikiru_cli-0.2.0.dist-info/WHEEL +4 -0
  318. shikiru_cli-0.2.0.dist-info/entry_points.txt +18 -0
  319. shikiru_cli-0.2.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,294 @@
1
+ """Engine and dashboard process lifecycle service boundaries."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import sys
7
+ from typing import TYPE_CHECKING, Literal
8
+
9
+ from pydantic import BaseModel, ConfigDict
10
+
11
+ from shikiru.config.loader import load_settings
12
+ from shikiru.domain.tasks import Status
13
+ from shikiru.errors import EXIT_COMMAND_REJECTED, ShikiruError
14
+ from shikiru.operator.attachment import admit_attachment
15
+ from shikiru.operator.commands import Ack, AckStatus
16
+ from shikiru.paths import engine_output_path
17
+ from shikiru.private import make_private_dir
18
+ from shikiru.process import TURN_STOP_GRACE
19
+ from shikiru.tmux.client import FORMAT_PANE_ID, exact_target
20
+ from shikiru.tmux.session import bind_palette_key, session_name
21
+
22
+ if TYPE_CHECKING:
23
+ from collections.abc import Awaitable, Callable, Sequence
24
+ from pathlib import Path
25
+
26
+ from shikiru.clock import Clock
27
+ from shikiru.config.settings import Settings
28
+ from shikiru.operator.services import OperatorServices
29
+ from shikiru.process import SubprocessRunner
30
+ from shikiru.tmux.client import Tmux
31
+ from shikiru.tmux.session import SessionView
32
+
33
+
34
+ if TYPE_CHECKING:
35
+ OperatorFactory = Callable[[Path, Settings], OperatorServices]
36
+ PluginValidator = Callable[[Settings], Awaitable[None]]
37
+ EngineState = Callable[[Path], bool]
38
+
39
+ PACKAGE_NAME = "shikiru"
40
+ DISTRIBUTION_NAME = "shikiru-cli"
41
+ CLI_ENGINE_COMMAND = "engine"
42
+ CLI_DASH_COMMAND = "dash"
43
+ CLI_PALETTE_COMMAND = "palette"
44
+ CLI_PALETTE_ORIGIN_PANE_OPTION = "--origin-pane"
45
+ PALETTE_COMMAND = (
46
+ sys.executable,
47
+ "-m",
48
+ PACKAGE_NAME,
49
+ CLI_PALETTE_COMMAND,
50
+ CLI_PALETTE_ORIGIN_PANE_OPTION,
51
+ FORMAT_PANE_ID,
52
+ )
53
+ ENGINE_START_POLL_SECONDS = 0.05
54
+ ENGINE_OUTPUT_TAIL_BYTES = 2000
55
+ ENGINE_EXITED_MESSAGE = "the engine process exited before it acquired its lock"
56
+ RESTART_BLOCKING_STATUSES = (Status.RUNNING, Status.INTEGRATING)
57
+ STOP_NOT_CONFIRMED_MESSAGE = "the engine did not confirm the stop"
58
+
59
+
60
+ class EngineExitedError(ShikiruError):
61
+ """The engine process started by `start` ended without ever holding its lock."""
62
+
63
+
64
+ class RestartRefusedError(ShikiruError):
65
+ """A restart would interrupt running tasks and was not forced."""
66
+
67
+ exit_code = EXIT_COMMAND_REJECTED
68
+
69
+ def __init__(self, task_ids: Sequence[str]) -> None:
70
+ """Record the running tasks that block the restart."""
71
+ super().__init__(
72
+ f"restart refused while tasks are running: {', '.join(task_ids)}; "
73
+ "wait for them to finish or run restart with --force"
74
+ )
75
+ self.task_ids = tuple(task_ids)
76
+
77
+
78
+ class ProjectLifecycle:
79
+ """Run a project's engine and session through injected process boundaries."""
80
+
81
+ def __init__(
82
+ self,
83
+ *,
84
+ runner: SubprocessRunner,
85
+ tmux: Tmux,
86
+ session: SessionView,
87
+ clock: Clock,
88
+ operator_factory: OperatorFactory,
89
+ plugin_validator: PluginValidator,
90
+ engine_up: EngineState,
91
+ ) -> None:
92
+ """Store process, tmux, state-service and validation boundaries."""
93
+ self._runner = runner
94
+ self._tmux = tmux
95
+ self._session = session
96
+ self._clock = clock
97
+ self._operator_factory = operator_factory
98
+ self._plugin_validator = plugin_validator
99
+ self._engine_up = engine_up
100
+
101
+ async def start(
102
+ self,
103
+ root: Path,
104
+ overrides: Sequence[str],
105
+ *,
106
+ attach: bool,
107
+ inside_tmux: bool = False,
108
+ current_pane: str | None = None,
109
+ ) -> StartResult:
110
+ """Validate a project and start or reuse its engine and tmux session."""
111
+ settings = load_settings(root, overrides)
112
+ name = session_name(settings.project.name)
113
+ target = exact_target(name)
114
+ same_client = await admit_attachment(self._tmux, name, current_pane) if attach else False
115
+ await self._plugin_validator(settings)
116
+ await self._session.ensure(
117
+ settings.project.name,
118
+ root,
119
+ home_command=command_with_overrides(home_command(root), overrides),
120
+ )
121
+ await bind_palette_key(self._tmux, PALETTE_COMMAND)
122
+ started = False
123
+ if not self._engine_up(root):
124
+ output = engine_output_path(root)
125
+ make_private_dir(output.parent)
126
+ pid = self._runner.spawn_detached(
127
+ command_with_overrides(
128
+ (
129
+ sys.executable,
130
+ "-m",
131
+ PACKAGE_NAME,
132
+ "--project",
133
+ str(root),
134
+ CLI_ENGINE_COMMAND,
135
+ ),
136
+ overrides,
137
+ ),
138
+ output=output,
139
+ )
140
+ started = True
141
+ await self._wait_for_engine(
142
+ root,
143
+ up=True,
144
+ seconds=settings.orchestration.engine_start_seconds,
145
+ failure="engine did not acquire its lock after start",
146
+ spawned=pid,
147
+ output=output,
148
+ )
149
+ if attach and not same_client:
150
+ self._runner.replace(self._tmux.guarded_client_argv(name, switch=inside_tmux))
151
+ return StartResult(started=started, engine="up", session=target)
152
+
153
+ async def stop(
154
+ self,
155
+ root: Path,
156
+ overrides: Sequence[str],
157
+ *,
158
+ kill_session: bool,
159
+ ) -> Ack:
160
+ """Stop a running engine and optionally remove its tmux session."""
161
+ settings = load_settings(root, overrides)
162
+ target = exact_target(session_name(settings.project.name))
163
+ if not self._engine_up(root):
164
+ if kill_session and await self._tmux.target_exists(target):
165
+ await self._tmux.kill_session(target)
166
+ return Ack(
167
+ id=0,
168
+ status=AckStatus.DONE,
169
+ result={"stopped": False},
170
+ message="engine already stopped",
171
+ )
172
+ services = self._operator_factory(root, settings)
173
+ try:
174
+ ack = await services.commands.stop_engine()
175
+ finally:
176
+ services.close()
177
+ if ack.status is AckStatus.DONE:
178
+ await self._wait_for_engine(
179
+ root,
180
+ up=False,
181
+ seconds=settings.orchestration.shutdown_seconds + TURN_STOP_GRACE,
182
+ failure="engine did not release its lock after stop",
183
+ )
184
+ if kill_session and ack.status is AckStatus.DONE and await self._tmux.target_exists(target):
185
+ await self._tmux.kill_session(target)
186
+ return ack
187
+
188
+ async def restart(
189
+ self,
190
+ root: Path,
191
+ overrides: Sequence[str],
192
+ *,
193
+ force: bool,
194
+ ) -> RestartResult:
195
+ """Stop a running engine, refusing while tasks run unless forced, then start it again."""
196
+ settings = load_settings(root, overrides)
197
+ restarted = self._engine_up(root)
198
+ if restarted:
199
+ if not force:
200
+ running = self._running_task_ids(root, settings)
201
+ if running:
202
+ raise RestartRefusedError(running)
203
+ ack = await self.stop(root, overrides, kill_session=False)
204
+ if ack.status is not AckStatus.DONE:
205
+ raise ShikiruError(ack.message or STOP_NOT_CONFIRMED_MESSAGE)
206
+ started = await self.start(root, overrides, attach=False)
207
+ return RestartResult(restarted=restarted, engine=started.engine, session=started.session)
208
+
209
+ def _running_task_ids(self, root: Path, settings: Settings) -> list[str]:
210
+ services = self._operator_factory(root, settings)
211
+ try:
212
+ tasks = services.queries.list_tasks(statuses=RESTART_BLOCKING_STATUSES)
213
+ finally:
214
+ services.close()
215
+ return [task.id for task in tasks]
216
+
217
+ async def _wait_for_engine(
218
+ self,
219
+ root: Path,
220
+ *,
221
+ up: bool,
222
+ seconds: float,
223
+ failure: str,
224
+ spawned: int | None = None,
225
+ output: Path | None = None,
226
+ ) -> None:
227
+ deadline = self._clock.now().timestamp() + seconds
228
+ while self._engine_up(root) != up:
229
+ if spawned is not None and self._runner.identify(spawned) is None:
230
+ raise EngineExitedError(_with_output(ENGINE_EXITED_MESSAGE, output))
231
+ if self._clock.now().timestamp() >= deadline:
232
+ raise ShikiruError(_with_output(failure, output))
233
+ await self._clock.sleep(ENGINE_START_POLL_SECONDS)
234
+
235
+
236
+ def _with_output(message: str, output: Path | None) -> str:
237
+ if output is None:
238
+ return message
239
+ with output.open("rb") as handle:
240
+ handle.seek(0, os.SEEK_END)
241
+ handle.seek(max(0, handle.tell() - ENGINE_OUTPUT_TAIL_BYTES))
242
+ tail = handle.read().decode(errors="replace").strip()
243
+ detail = f"engine output ({output}):\n{tail}" if tail else f"engine printed nothing ({output})"
244
+ return f"{message}\n{detail}"
245
+
246
+
247
+ def home_command(root: Path) -> tuple[str, ...]:
248
+ """Return the command of the session's home window: the dashboard of the project at `root`."""
249
+ return (sys.executable, "-m", PACKAGE_NAME, "--project", str(root), CLI_DASH_COMMAND, "--home")
250
+
251
+
252
+ def task_dashboard_command(root: Path, task_id: str) -> tuple[str, ...]:
253
+ """Return the explicit task dashboard command for `task_id` in `root`."""
254
+ return (
255
+ sys.executable,
256
+ "-m",
257
+ PACKAGE_NAME,
258
+ "--project",
259
+ str(root),
260
+ CLI_DASH_COMMAND,
261
+ "--task",
262
+ task_id,
263
+ )
264
+
265
+
266
+ def command_with_overrides(command: tuple[str, ...], overrides: Sequence[str]) -> tuple[str, ...]:
267
+ """Insert global `--set` values before the hidden engine or dashboard command."""
268
+ command_index = next(
269
+ index
270
+ for index, part in enumerate(command)
271
+ if part in {CLI_ENGINE_COMMAND, CLI_DASH_COMMAND}
272
+ )
273
+ override_parts = tuple(part for override in overrides for part in ("--set", override))
274
+ return (*command[:command_index], *override_parts, *command[command_index:])
275
+
276
+
277
+ class StartResult(BaseModel):
278
+ """The started state and tmux target returned by a project start request."""
279
+
280
+ model_config = ConfigDict(extra="forbid", frozen=True)
281
+
282
+ started: bool
283
+ engine: Literal["up"]
284
+ session: str
285
+
286
+
287
+ class RestartResult(BaseModel):
288
+ """Whether a running engine was stopped, and the engine and session a restart left up."""
289
+
290
+ model_config = ConfigDict(extra="forbid", frozen=True)
291
+
292
+ restarted: bool
293
+ engine: Literal["up"]
294
+ session: str
@@ -0,0 +1,194 @@
1
+ """Create configured agent plugins and report their health through one boundary."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+ from typing import TYPE_CHECKING
7
+
8
+ from shikiru.agents.contracts import (
9
+ AgentContext,
10
+ CheckResult,
11
+ ModelCatalog,
12
+ assess_model_choice,
13
+ model_catalog_for,
14
+ )
15
+ from shikiru.agents.settings import AgentOptionsError, AgentSettings, settings_for
16
+ from shikiru.errors import ShikiruError
17
+
18
+ _SETTINGS_UNSUPPORTED_DETAIL = "agent does not expose editable settings"
19
+ _MODEL_CATALOG_UNSUPPORTED_DETAIL = "agent does not expose an authoritative model catalog"
20
+
21
+ if TYPE_CHECKING:
22
+ from collections.abc import Mapping, Sequence
23
+ from typing import Any
24
+
25
+ from shikiru.agents.contracts import Agent
26
+ from shikiru.agents.registry import AgentRegistry
27
+ from shikiru.clock import Clock
28
+ from shikiru.process import SubprocessRunner
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class PluginCheckResult:
33
+ """One plugin's doctor checks, or the expected error that prevented them."""
34
+
35
+ name: str
36
+ checks: tuple[CheckResult, ...] = ()
37
+ error: str | None = None
38
+ catalog: ModelCatalog | None = None
39
+
40
+ @property
41
+ def ok(self) -> bool:
42
+ return self.error is None and bool(self.checks) and all(check.ok for check in self.checks)
43
+
44
+ @property
45
+ def detail(self) -> str:
46
+ if self.error is not None:
47
+ return self.error
48
+ if not self.checks:
49
+ return "plugin returned no checks"
50
+ failures = [f"{check.name}: {check.detail}" for check in self.checks if not check.ok]
51
+ return "; ".join(failures) if failures else "all checks passed"
52
+
53
+
54
+ @dataclass(frozen=True)
55
+ class OptionsRejection:
56
+ """A plugin's refusal of its options and the option at fault, when it says which."""
57
+
58
+ detail: str
59
+ key: str | None = None
60
+
61
+
62
+ @dataclass(frozen=True)
63
+ class AgentCapabilityResult:
64
+ """Generic capabilities an operator surface may use to offer an agent."""
65
+
66
+ headless: bool
67
+ error: str | None = None
68
+
69
+
70
+ class PluginChecks:
71
+ """Run `Agent.doctor()` through the same registry for init, start and doctor."""
72
+
73
+ def __init__(self, registry: AgentRegistry, runner: SubprocessRunner, clock: Clock) -> None:
74
+ """Use the shared registry and runtime boundaries for plugin checks."""
75
+ self._registry = registry
76
+ self._runner = runner
77
+ self._clock = clock
78
+
79
+ def names(self) -> tuple[str, ...]:
80
+ """Return names available from the injected agent registry."""
81
+ return self._registry.names()
82
+
83
+ async def check(
84
+ self,
85
+ name: str,
86
+ options: Mapping[str, Any],
87
+ models: Sequence[str] = (),
88
+ *,
89
+ include_model_catalog: bool = False,
90
+ ) -> PluginCheckResult:
91
+ """Create `name` with `options` and run its doctor for `models`, reporting failures."""
92
+ try:
93
+ agent = self._registry.create(
94
+ name,
95
+ AgentContext(options=options, runner=self._runner, clock=self._clock),
96
+ )
97
+ except (ShikiruError, OSError, TimeoutError) as error:
98
+ detail = str(error) or type(error).__name__
99
+ return PluginCheckResult(name=name, error=detail)
100
+ catalog = await _agent_model_catalog(agent) if include_model_catalog else None
101
+ if include_model_catalog and catalog is None:
102
+ catalog = ModelCatalog(error=_MODEL_CATALOG_UNSUPPORTED_DETAIL)
103
+ checked_models = tuple(models)
104
+ if catalog is not None and catalog.error is None and catalog.complete:
105
+ checked_models = tuple(
106
+ model
107
+ for model in checked_models
108
+ if assess_model_choice(model, None, catalog).supported is not False
109
+ )
110
+ try:
111
+ checks = await agent.doctor(checked_models)
112
+ except (ShikiruError, OSError, TimeoutError) as error:
113
+ detail = str(error) or type(error).__name__
114
+ return PluginCheckResult(name=name, error=detail, catalog=catalog)
115
+ return PluginCheckResult(name=name, checks=tuple(checks), catalog=catalog)
116
+
117
+ async def model_catalog(self, name: str, options: Mapping[str, Any]) -> ModelCatalog | None:
118
+ """Return authoritative choices when the plugin offers them, or an explicit failure."""
119
+ try:
120
+ agent = self._registry.create(
121
+ name,
122
+ AgentContext(options=options, runner=self._runner, clock=self._clock),
123
+ )
124
+ return await _agent_model_catalog(agent)
125
+ except (ShikiruError, OSError, TimeoutError) as error:
126
+ detail = str(error) or type(error).__name__
127
+ return ModelCatalog(error=detail)
128
+
129
+ def capabilities(self, name: str, options: Mapping[str, Any]) -> AgentCapabilityResult:
130
+ """Report generic optional capabilities without exposing plugin implementation details."""
131
+ try:
132
+ agent = self._registry.create(
133
+ name,
134
+ AgentContext(options=options, runner=self._runner, clock=self._clock),
135
+ )
136
+ except (ShikiruError, OSError, TimeoutError) as error:
137
+ detail = str(error) or type(error).__name__
138
+ return AgentCapabilityResult(headless=False, error=detail)
139
+ provider = getattr(agent, "headless", None)
140
+ if provider is None:
141
+ return AgentCapabilityResult(headless=False)
142
+ if not callable(provider):
143
+ return AgentCapabilityResult(
144
+ headless=False,
145
+ error="agent returned an invalid headless capability",
146
+ )
147
+ try:
148
+ return AgentCapabilityResult(headless=provider() is not None)
149
+ except (ShikiruError, OSError, TimeoutError) as error:
150
+ detail = str(error) or type(error).__name__
151
+ return AgentCapabilityResult(headless=False, error=detail)
152
+
153
+ def settings(self, name: str) -> AgentSettings:
154
+ """Return the editable settings `name` offers, or why it offers none."""
155
+ try:
156
+ agent = self._create(name, {})
157
+ offered = settings_for(agent)
158
+ except (ShikiruError, OSError, TimeoutError) as error:
159
+ detail = str(error) or type(error).__name__
160
+ return AgentSettings(agent=name, supported=False, error=detail)
161
+ if offered is None:
162
+ return AgentSettings(agent=name, supported=False, error=_SETTINGS_UNSUPPORTED_DETAIL)
163
+ return AgentSettings(agent=name, settings=offered)
164
+
165
+ def options_rejection(self, name: str, options: Mapping[str, Any]) -> OptionsRejection | None:
166
+ """Return the plugin's rejection of `options`, or `None` when it accepts them."""
167
+ try:
168
+ self._create(name, options)
169
+ except (ShikiruError, OSError, TimeoutError) as error:
170
+ detail = str(error) or type(error).__name__
171
+ return OptionsRejection(detail=detail, key=_rejected_key(error))
172
+ return None
173
+
174
+ def _create(self, name: str, options: Mapping[str, Any]) -> Agent:
175
+ return self._registry.create(
176
+ name, AgentContext(options=options, runner=self._runner, clock=self._clock)
177
+ )
178
+
179
+
180
+ async def _agent_model_catalog(agent: Agent) -> ModelCatalog | None:
181
+ try:
182
+ return await model_catalog_for(agent)
183
+ except (ShikiruError, OSError, TimeoutError) as error:
184
+ detail = str(error) or type(error).__name__
185
+ return ModelCatalog(error=detail)
186
+
187
+
188
+ def _rejected_key(error: BaseException) -> str | None:
189
+ cause: BaseException | None = error
190
+ while cause is not None:
191
+ if isinstance(cause, AgentOptionsError):
192
+ return cause.key
193
+ cause = cause.__cause__
194
+ return None