@lmmslab/harness 0.0.0-stage → 0.81.0

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 (170) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +124 -2
  3. package/bin/harness.js +71 -0
  4. package/package.json +34 -4
  5. package/python/harness/README.md +72 -0
  6. package/python/harness/__init__.py +8 -0
  7. package/python/harness/__main__.py +3 -0
  8. package/python/harness/bench.py +124 -0
  9. package/python/harness/builtin/benches/README.md +5 -0
  10. package/python/harness/builtin/benches/none/bench.toml +6 -0
  11. package/python/harness/builtin/configs/README.md +26 -0
  12. package/python/harness/builtin/configs/assistant.toml +11 -0
  13. package/python/harness/builtin/configs/default.toml +33 -0
  14. package/python/harness/builtin/configs/deploy/example-api.toml +10 -0
  15. package/python/harness/builtin/configs/models/deepseek-api.toml +21 -0
  16. package/python/harness/builtin/configs/models/deepseek-flash.toml +12 -0
  17. package/python/harness/builtin/configs/models/grok-low.toml +8 -0
  18. package/python/harness/builtin/configs/models/grok-medium.toml +43 -0
  19. package/python/harness/builtin/configs/models/opus-5.5.toml +11 -0
  20. package/python/harness/builtin/environment/README.md +53 -0
  21. package/python/harness/builtin/environment/constraints.txt +31 -0
  22. package/python/harness/builtin/model-settings.js +143 -0
  23. package/python/harness/builtin/prompts/conversation/core.md +5 -0
  24. package/python/harness/builtin/prompts/conversation/pack.toml +12 -0
  25. package/python/harness/builtin/prompts/core/core.md +88 -0
  26. package/python/harness/builtin/prompts/core/pack.toml +9 -0
  27. package/python/harness/builtin/prompts/reflect/core.md +45 -0
  28. package/python/harness/builtin/prompts/reflect/pack.toml +7 -0
  29. package/python/harness/builtin/prompts/shared/agent-skills.md +5 -0
  30. package/python/harness/builtin/prompts/shared/agents.md +14 -0
  31. package/python/harness/builtin/prompts/shared/checklist.md +21 -0
  32. package/python/harness/builtin/prompts/shared/entries.md +86 -0
  33. package/python/harness/builtin/prompts/shared/environments.md +21 -0
  34. package/python/harness/builtin/prompts/shared/learning-goal.md +31 -0
  35. package/python/harness/builtin/prompts/shared/learning.md +27 -0
  36. package/python/harness/builtin/prompts/shared/mcp.md +9 -0
  37. package/python/harness/builtin/prompts/shared/world.md +1 -0
  38. package/python/harness/builtin/skills/README.md +10 -0
  39. package/python/harness/builtin/skills/agents/__init__.py +88 -0
  40. package/python/harness/builtin/skills/agents/skill.toml +11 -0
  41. package/python/harness/builtin/skills/checklist/__init__.py +32 -0
  42. package/python/harness/builtin/skills/checklist/skill.toml +9 -0
  43. package/python/harness/builtin/skills/conversation/__init__.py +23 -0
  44. package/python/harness/builtin/skills/conversation/skill.toml +8 -0
  45. package/python/harness/builtin/skills/entries/__init__.py +62 -0
  46. package/python/harness/builtin/skills/entries/skill.toml +8 -0
  47. package/python/harness/builtin/skills/environments/__init__.py +69 -0
  48. package/python/harness/builtin/skills/environments/skill.toml +9 -0
  49. package/python/harness/builtin/skills/experience/__init__.py +27 -0
  50. package/python/harness/builtin/skills/experience/skill.toml +9 -0
  51. package/python/harness/builtin/skills/instructions/__init__.py +29 -0
  52. package/python/harness/builtin/skills/instructions/skill.toml +9 -0
  53. package/python/harness/builtin/skills/learning/__init__.py +189 -0
  54. package/python/harness/builtin/skills/learning/skill.toml +7 -0
  55. package/python/harness/builtin/skills/mcp/__init__.py +54 -0
  56. package/python/harness/builtin/skills/mcp/skill.toml +10 -0
  57. package/python/harness/builtin/skills/memory/__init__.py +130 -0
  58. package/python/harness/builtin/skills/memory/skill.toml +13 -0
  59. package/python/harness/builtin/skills/verify/__init__.py +31 -0
  60. package/python/harness/builtin/skills/verify/skill.toml +7 -0
  61. package/python/harness/builtin/third_party/sources.toml +40 -0
  62. package/python/harness/cli.py +1182 -0
  63. package/python/harness/config/__init__.py +224 -0
  64. package/python/harness/config/agent.py +777 -0
  65. package/python/harness/core/__init__.py +52 -0
  66. package/python/harness/core/artifacts.py +46 -0
  67. package/python/harness/core/codec.py +160 -0
  68. package/python/harness/core/contracts.py +75 -0
  69. package/python/harness/core/episodes.py +150 -0
  70. package/python/harness/core/format.py +51 -0
  71. package/python/harness/core/http.py +124 -0
  72. package/python/harness/core/lanes.py +324 -0
  73. package/python/harness/core/linux_sandbox.py +55 -0
  74. package/python/harness/core/media.py +96 -0
  75. package/python/harness/core/memory.py +147 -0
  76. package/python/harness/core/ports.py +63 -0
  77. package/python/harness/core/procs.py +227 -0
  78. package/python/harness/core/remote.py +102 -0
  79. package/python/harness/core/spans.py +166 -0
  80. package/python/harness/core/trace.py +139 -0
  81. package/python/harness/core/wait.py +12 -0
  82. package/python/harness/core/worker.py +388 -0
  83. package/python/harness/core/worker_pipe.py +119 -0
  84. package/python/harness/embodiments.py +217 -0
  85. package/python/harness/extensions.py +112 -0
  86. package/python/harness/host/__init__.py +397 -0
  87. package/python/harness/host/client.py +201 -0
  88. package/python/harness/host/http.py +720 -0
  89. package/python/harness/host/listing.py +68 -0
  90. package/python/harness/host/server.py +189 -0
  91. package/python/harness/host/sessions.py +406 -0
  92. package/python/harness/host/tasks.py +1308 -0
  93. package/python/harness/host/workers.py +257 -0
  94. package/python/harness/host/workspaces.py +256 -0
  95. package/python/harness/model_list.py +117 -0
  96. package/python/harness/packages/__init__.py +73 -0
  97. package/python/harness/packages/addons.py +121 -0
  98. package/python/harness/packages/archive.py +122 -0
  99. package/python/harness/packages/describe.py +46 -0
  100. package/python/harness/packages/environments.py +448 -0
  101. package/python/harness/packages/fetch.py +57 -0
  102. package/python/harness/packages/manager.py +587 -0
  103. package/python/harness/packages/manifest.py +221 -0
  104. package/python/harness/packages/migrate.py +68 -0
  105. package/python/harness/packages/provision.py +38 -0
  106. package/python/harness/packages/registry.py +275 -0
  107. package/python/harness/packages/resolve.py +89 -0
  108. package/python/harness/packages/sources.py +141 -0
  109. package/python/harness/packages/state.py +213 -0
  110. package/python/harness/packages/versions.py +112 -0
  111. package/python/harness/paths.py +218 -0
  112. package/python/harness/providers.py +303 -0
  113. package/python/harness/runtime/__init__.py +8 -0
  114. package/python/harness/runtime/decision/__init__.py +1 -0
  115. package/python/harness/runtime/decision/loop.py +198 -0
  116. package/python/harness/runtime/decision/messages.py +271 -0
  117. package/python/harness/runtime/decision/model.py +424 -0
  118. package/python/harness/runtime/decision/prompts.py +248 -0
  119. package/python/harness/runtime/decision/protocol.py +169 -0
  120. package/python/harness/runtime/decision/thoughts.py +199 -0
  121. package/python/harness/runtime/events.py +213 -0
  122. package/python/harness/runtime/execution/__init__.py +1 -0
  123. package/python/harness/runtime/execution/attached.py +96 -0
  124. package/python/harness/runtime/execution/control.py +211 -0
  125. package/python/harness/runtime/execution/entries.py +665 -0
  126. package/python/harness/runtime/execution/kernel.py +811 -0
  127. package/python/harness/runtime/execution/noenv.py +84 -0
  128. package/python/harness/runtime/execution/results.py +40 -0
  129. package/python/harness/runtime/execution/session.py +871 -0
  130. package/python/harness/runtime/execution/skills.py +436 -0
  131. package/python/harness/runtime/learning/__init__.py +1 -0
  132. package/python/harness/runtime/learning/active.py +314 -0
  133. package/python/harness/runtime/learning/experience.py +48 -0
  134. package/python/harness/runtime/learning/fixtures.py +167 -0
  135. package/python/harness/runtime/learning/learner.py +651 -0
  136. package/python/harness/runtime/learning/library.py +504 -0
  137. package/python/harness/runtime/learning/reflect.py +151 -0
  138. package/python/harness/runtime/learning/usage.py +30 -0
  139. package/python/harness/runtime/learning/views.py +89 -0
  140. package/python/harness/runtime/reactive/__init__.py +1 -0
  141. package/python/harness/runtime/reactive/rules.py +549 -0
  142. package/python/harness/runtime/safety/__init__.py +1 -0
  143. package/python/harness/runtime/safety/approval.py +131 -0
  144. package/python/harness/runtime/safety/input.py +62 -0
  145. package/python/harness/runtime/safety/isolation.py +419 -0
  146. package/python/harness/runtime/safety/shield.py +129 -0
  147. package/python/harness/runtime/status.py +23 -0
  148. package/python/harness/runtime/task/__init__.py +7 -0
  149. package/python/harness/runtime/task/context.py +431 -0
  150. package/python/harness/runtime/task/delegation.py +468 -0
  151. package/python/harness/runtime/task/environments.py +268 -0
  152. package/python/harness/runtime/task/run.py +2878 -0
  153. package/python/harness/runtime/tick.py +909 -0
  154. package/python/harness/sdk/__init__.py +281 -0
  155. package/python/harness/services/__init__.py +6 -0
  156. package/python/harness/services/broker.py +35 -0
  157. package/python/harness/services/connectors.py +88 -0
  158. package/python/harness/services/mcp.py +298 -0
  159. package/python/harness/services/mcp_stdio.py +131 -0
  160. package/python/harness/services/placement.py +82 -0
  161. package/python/harness/services/registry.py +156 -0
  162. package/python/harness/settings.py +536 -0
  163. package/python/harness/terminal.py +79 -0
  164. package/python/harness/transcript.py +297 -0
  165. package/python/harness/tui/__init__.py +68 -0
  166. package/python/harness/tui/chat.py +1181 -0
  167. package/python/harness/tui/pty.py +81 -0
  168. package/python/harness/tui/renderer.py +45 -0
  169. package/python/harness/tui/timeline_rows.py +58 -0
  170. package/python/harness/tui/views.py +434 -0
@@ -0,0 +1,213 @@
1
+ """Events: the signals of a run, in one catalog.
2
+
3
+ An execution's event (Event) ends every bounded execution and goes up the tree of entries to
4
+ the rules that answer it (on()); one nobody answers escalates to the model as an Escalation.
5
+ A trace record (EVENTS) is what the run writes to its trace (core/trace.py), which the
6
+ timeline, the overlay, replay and the exported video all draw. A family of records is one
7
+ kind with an `action` (library), which record_kind() reads.
8
+ """
9
+
10
+ from dataclasses import asdict, dataclass, field
11
+ from typing import Any
12
+
13
+
14
+ # The kinds of an execution's event (Event.kind; a guard may raise one of its own name):
15
+ # nominal ends (NOMINAL), a time bound, the execution's scope, a guard, the shield, reactive
16
+ # code that broke its rules, a skill's error, the arm held back short of its target (contact
17
+ # or a load), the episode's end, the user's pause or message (both always reach the model; the
18
+ # message stops the program's own code, not the entries it started), an entry that failed,
19
+ # and a channel another entry has.
20
+ BUILTIN = ("COMPLETED", "PREDICATE_SATISFIED", "TIMEOUT", "REGION_EXIT", "GUARD_TRIGGERED", "SHIELD_REJECTED",
21
+ "REACTIVE_FAULT", "SKILL_ERROR", "BLOCKED", "EPISODE_ENDED", "USER_PAUSED", "USER_MESSAGE",
22
+ "ENTRY_FAILED", "CHANNEL_CONFLICT")
23
+ (COMPLETED, PREDICATE_SATISFIED, TIMEOUT, REGION_EXIT, GUARD_TRIGGERED, SHIELD_REJECTED, REACTIVE_FAULT, SKILL_ERROR,
24
+ BLOCKED, EPISODE_ENDED, USER_PAUSED, USER_MESSAGE, ENTRY_FAILED, CHANNEL_CONFLICT) = BUILTIN
25
+ # A program may continue after these without consulting a handler.
26
+ NOMINAL = frozenset({COMPLETED, PREDICATE_SATISFIED})
27
+
28
+
29
+ @dataclass
30
+ class Event:
31
+ """Why an execution ended: its kind (a built-in kind above or a guard's own action),
32
+ the source that raised it (a skill, a guard, "shield", "environment"), details, and
33
+ the robot step it happened at."""
34
+
35
+ kind: str
36
+ source: str
37
+ detail: dict[str, Any] = field(default_factory=dict)
38
+ tick: int | None = None
39
+
40
+ def to_dict(self) -> dict:
41
+ """The event as a plain dict."""
42
+ return asdict(self)
43
+
44
+
45
+ def input_refusal(receipt, step):
46
+ if conflict := receipt.get("conflict"):
47
+ return Event(CHANNEL_CONFLICT, "channels", conflict, step)
48
+ if not receipt["executed"]:
49
+ return Event(SHIELD_REJECTED, "shield", {"reasons": receipt["shield"]["reasons"]}, step)
50
+
51
+
52
+ @dataclass
53
+ class ExecutionTrace:
54
+ """What one bounded execution did, and why it ended."""
55
+
56
+ skill: str
57
+ parameters: dict[str, Any]
58
+ start_tick: int
59
+ end_tick: int
60
+ event: Event
61
+ samples: list[dict] = field(default_factory=list)
62
+ # A value for the calling program, never part of an event or serialized trace.
63
+ result: Any = field(default=None, repr=False)
64
+
65
+ @property
66
+ def ok(self) -> bool:
67
+ """Whether the execution ended nominally (COMPLETED or PREDICATE_SATISFIED)."""
68
+ return self.event.kind in NOMINAL
69
+
70
+ @property
71
+ def ticks(self) -> int:
72
+ """Robot steps the execution took."""
73
+ return self.end_tick - self.start_tick
74
+
75
+ def to_dict(self) -> dict:
76
+ """The trace as a plain dict, with `ok`."""
77
+ data = {"skill": self.skill, "parameters": self.parameters, "start_tick": self.start_tick,
78
+ "end_tick": self.end_tick, "event": self.event.to_dict(), "samples": self.samples}
79
+ data["ok"] = self.ok
80
+ return data
81
+
82
+ def __repr__(self) -> str:
83
+ return (f"Trace({self.skill}, {self.event.kind} from {self.event.source}, "
84
+ f"ticks={self.ticks})")
85
+
86
+
87
+ class Escalation(Exception):
88
+ """An event no handler resolved. It ends the current program."""
89
+
90
+ def __init__(self, trace: ExecutionTrace):
91
+ super().__init__(f"{trace.event.kind} in {trace.skill}")
92
+ self.trace = trace
93
+
94
+
95
+ class ProgramFinished(Exception):
96
+ """A program called finish(): its own checks say the task is done. The episode
97
+ ends without another model call."""
98
+
99
+ def __init__(self, summary: str = ""):
100
+ super().__init__(summary)
101
+ self.summary = str(summary)
102
+
103
+
104
+ class EpisodeEnded(Exception):
105
+ """The environment terminated or truncated the episode during a program."""
106
+
107
+ def __init__(self, trace: ExecutionTrace):
108
+ super().__init__("episode ended")
109
+ self.trace = trace
110
+
111
+
112
+ # Every kind of trace record: its source (the user; the agent, i.e. the main model; the program
113
+ # running in the kernel; the environment; the harness itself) and whether what it holds is part
114
+ # of what the model is shown. What each record holds is in the traces reference.
115
+ EVENTS = {
116
+ "execution_event": {"source": "program", "shown": False},
117
+ "program_output": {"source": "program", "shown": False},
118
+ "state": {"source": "harness", "shown": False},
119
+ "reset": {"source": "environment", "shown": True},
120
+ "screen_recording": {"source": "harness", "shown": False},
121
+ "library": {"source": "harness", "shown": True},
122
+ "user_message": {"source": "user", "shown": True},
123
+ "model_request": {"source": "harness", "shown": True},
124
+ "model_changed": {"source": "user", "shown": False},
125
+ "ahead": {"source": "harness", "shown": False},
126
+ "context_shortened": {"source": "harness", "shown": False},
127
+ "side_program": {"source": "harness", "shown": False},
128
+ "side_program_end": {"source": "harness", "shown": False},
129
+ "program_stopped": {"source": "harness", "shown": False},
130
+ "model_preempted": {"source": "harness", "shown": False},
131
+ "model_reply": {"source": "agent", "shown": True},
132
+ "agent_message": {"source": "agent", "shown": True},
133
+ "empty_reply": {"source": "harness", "shown": False},
134
+ "protocol_error": {"source": "harness", "shown": True},
135
+ "malformed_dropped": {"source": "harness", "shown": False},
136
+ "verify": {"source": "environment", "shown": True},
137
+ "confirmation_request": {"source": "harness", "shown": False},
138
+ "confirmation": {"source": "user", "shown": True},
139
+ "physical_request": {"source": "harness", "shown": False},
140
+ "physical_answer": {"source": "user", "shown": False},
141
+ "worker_approval_result": {"source": "harness", "shown": False},
142
+ "input": {"source": "environment", "shown": False},
143
+ "cell": {"source": "program", "shown": True},
144
+ "private_paths": {"source": "harness", "shown": False},
145
+ "file_access": {"source": "program", "shown": False},
146
+ "modules": {"source": "harness", "shown": False},
147
+ "experience": {"source": "program", "shown": False},
148
+ "experience_folded": {"source": "harness", "shown": False},
149
+ "tick_periods": {"source": "program", "shown": False},
150
+ "guard": {"source": "program", "shown": False},
151
+ "program_held": {"source": "harness", "shown": False},
152
+ "program_dropped": {"source": "harness", "shown": False},
153
+ "user_took_over": {"source": "harness", "shown": False},
154
+ "stuck": {"source": "harness", "shown": False},
155
+ "policy_to_end": {"source": "program", "shown": False},
156
+ "finish": {"source": "agent", "shown": False},
157
+ "finish_refused": {"source": "harness", "shown": True},
158
+ "wrap_up": {"source": "program", "shown": False},
159
+ "kernel_died": {"source": "harness", "shown": False},
160
+ "interrupted": {"source": "harness", "shown": False},
161
+ "error": {"source": "harness", "shown": False},
162
+ "cleanup_error": {"source": "harness", "shown": False},
163
+ "outcome": {"source": "environment", "shown": False},
164
+ "episode_video": {"source": "environment", "shown": False},
165
+ "late_receipt": {"source": "environment", "shown": False},
166
+ "plan": {"source": "program", "shown": False},
167
+ "stay_on_screen": {"source": "program", "shown": False},
168
+ "decision": {"source": "program", "shown": False},
169
+ "page_read": {"source": "environment", "shown": False},
170
+ "workspace_reclaimed": {"source": "harness", "shown": False},
171
+ "environment_attached": {"source": "harness", "shown": True},
172
+ "environment_refused": {"source": "harness", "shown": True},
173
+ "environment_released": {"source": "harness", "shown": True},
174
+ "agents_enabled": {"source": "harness", "shown": True},
175
+ "views": {"source": "program", "shown": False},
176
+ "agent_delegated": {"source": "program", "shown": False},
177
+ "agent_waited": {"source": "program", "shown": False},
178
+ "agent_sent": {"source": "program", "shown": False},
179
+ "agent_cancelled": {"source": "program", "shown": False},
180
+ "agent_report": {"source": "harness", "shown": False},
181
+ "span_start": {"source": "harness", "shown": False},
182
+ "span_end": {"source": "harness", "shown": False},
183
+ "model_text": {"source": "agent", "shown": False},
184
+ "mcp_submitted": {"source": "agent", "shown": False},
185
+ "mcp_dispatched": {"source": "agent", "shown": False},
186
+ "mcp_receipt": {"source": "agent", "shown": False},
187
+ "thought_queued": {"source": "agent", "shown": False},
188
+ "thought_started": {"source": "agent", "shown": False},
189
+ "thought_failed": {"source": "agent", "shown": False},
190
+ "thought_exited": {"source": "agent", "shown": False},
191
+ "thought_cancelled": {"source": "agent", "shown": False},
192
+ "escalation": {"source": "program", "shown": False},
193
+ "entry_start": {"source": "program", "shown": False},
194
+ "entry_claims": {"source": "program", "shown": False},
195
+ "entry_end": {"source": "program", "shown": False},
196
+ "skill_step": {"source": "program", "shown": False},
197
+ "world": {"source": "program", "shown": False},
198
+ }
199
+
200
+
201
+ def record_kind(record: dict) -> tuple[str, str | None]:
202
+ """A trace record's kind and, for a family (library), its action."""
203
+ kind = record.get("event") or ""
204
+ return kind, record.get("action") if kind == "library" else None
205
+
206
+
207
+ def step_of(start: dict, end: dict, call: str | None = None) -> dict:
208
+ """An execution's span_start and span_end (lane "skill") as a step of its skill, in the
209
+ shape of a skill_step record (core/spans.py step), so a reader takes both alike."""
210
+ event = end.get("event_kind") or ("error" if end.get("error") else COMPLETED)
211
+ return {"skill": start.get("name"), "call": call, "ok": event in NOMINAL, "event": event,
212
+ "seconds": float(end.get("time") or 0.0) - float(start.get("time") or 0.0),
213
+ "reason": end.get("reason") or end.get("error")}
@@ -0,0 +1 @@
1
+ """Bounded programs, skills and policy execution."""
@@ -0,0 +1,96 @@
1
+ """Another environment taken into a running conversation (use_environment).
2
+
3
+ A conversation starts in one environment, whose session is the kernel's and whose calls
4
+ are the program's plain names. When a step cannot be done there, the model asks for
5
+ another kind (skills/environments): the session host asks the user as their settings say,
6
+ takes a workspace of that kind and answers with what its session needs. The kernel then
7
+ builds that kind's session beside its own, each with its tick (runtime/tick.py) and its
8
+ entries, and gives programs its calls under the kind's name:
9
+
10
+ desktop.click(x, y) project.run_command("npm test") browser.read_page()
11
+
12
+ The attached session never connects to its worker itself. Every call goes over the
13
+ kernel's connection to the host (RelayedEnvironment), which holds the worker's key, checks
14
+ the call as it checks the conversation's own and keeps the user's approvals: a step with
15
+ the real mouse and keyboard stays under the physical-input policy after the desktop is
16
+ attached. So the kernel's network guard is as it was when the kernel started.
17
+ """
18
+
19
+ from harness.runtime.events import EpisodeEnded
20
+ from harness.runtime.execution import control
21
+
22
+ # Names of an attached session that programs do not get: ending the task is the
23
+ # conversation's own finish(), and library entries are the conversation's.
24
+ WITHHELD = ("finish", "library", "ClosedLoop")
25
+
26
+
27
+ class RelayedEnvironment:
28
+ """An attached environment's worker, reached through the session host."""
29
+
30
+ approval_key = None
31
+ program_controls = frozenset()
32
+
33
+ def __init__(self, name: str, timeout: float = 300.0, host_controls=()):
34
+ self.name = name
35
+ self.timeout = float(timeout)
36
+ self.host_controls = frozenset(host_controls)
37
+
38
+ def call(self, name: str, **arguments):
39
+ return control.host_call({"environment": self.name, "name": name, "arguments": arguments}, self.timeout)
40
+
41
+ def close(self) -> None:
42
+ pass
43
+
44
+
45
+ class Attached:
46
+ """The calls of an attached environment as attributes: desktop.click, project.read_file.
47
+ A call made after it was released, or after its episode ended, says so."""
48
+
49
+ def __init__(self, name: str, session):
50
+ calls = {key: value for key, value in session.namespace.items()
51
+ if not key.startswith("_") and key not in WITHHELD}
52
+ object.__setattr__(self, "_name", name)
53
+ object.__setattr__(self, "_calls", calls)
54
+ object.__setattr__(self, "_live", True)
55
+
56
+ def __getattr__(self, key):
57
+ calls = object.__getattribute__(self, "_calls")
58
+ name = object.__getattribute__(self, "_name")
59
+ if key not in calls:
60
+ raise AttributeError(f"{name} has no call {key}; it has {', '.join(sorted(calls))}")
61
+ value = calls[key]
62
+ if not callable(value):
63
+ return value
64
+
65
+ def call(*args, **kwargs):
66
+ if not object.__getattribute__(self, "_live"):
67
+ raise RuntimeError(f"{name} was released; use_environment({name!r}, why) takes it again")
68
+ try:
69
+ return value(*args, **kwargs)
70
+ except EpisodeEnded:
71
+ # Its worker ended its episode (a step limit): this conversation goes on.
72
+ raise RuntimeError(f"{name} has ended; release_environment({name!r}) gives it back") from None
73
+
74
+ call.__name__ = key
75
+ call.__doc__ = getattr(value, "__doc__", None)
76
+ return call
77
+
78
+ def __setattr__(self, key, value):
79
+ raise AttributeError("an attached environment's calls cannot be rebound")
80
+
81
+ def __dir__(self):
82
+ return sorted(object.__getattribute__(self, "_calls"))
83
+
84
+ def __repr__(self):
85
+ name = object.__getattribute__(self, "_name")
86
+ return f"<environment {name}: {', '.join(dir(self))}>"
87
+
88
+
89
+ def build(name: str, given: dict):
90
+ """The session of an attached environment from what the host answered: {"embodiment",
91
+ "knowledge", "episode_id", "skills", "timeout_seconds", "host_controls", and the keys a
92
+ session of that kind reads}. Its worker is reached through the host."""
93
+ from harness.runtime.execution.session import session_class
94
+
95
+ environment = RelayedEnvironment(name, given.get("timeout_seconds", 300.0), given.get("host_controls", ()))
96
+ return session_class(given["embodiment"], given.get("knowledge"))(dict(given), environment=environment)
@@ -0,0 +1,211 @@
1
+ """What the host asks of a running program besides its cells.
2
+
3
+ The kernel process reads the host's requests on a thread of its own, so a request
4
+ reaches a program while it runs: a pause (the user paused the conversation) makes the
5
+ next step of a bounded execution end it with USER_PAUSED (runtime/execution/session.py). A
6
+ message for the model (the user's, or the parent agent's) interrupts the program's own
7
+ code, not the entries it started: its execution ends at the next step with USER_MESSAGE,
8
+ and a wait of it (an entry's wait(), wait_agents()) raises that event at once
9
+ (runtime/execution/entries.py). The flags are cleared when the next cell starts. An answer is the host's reply to a request a
10
+ program sent it as a note (the user's answer to a physical-input request,
11
+ runtime/safety/input.py): the program waits for it, or for a pause. When a sub-agent the
12
+ program started ends, the host says so, and its entry ends (runtime/execution/entries.py).
13
+ """
14
+
15
+ import sys
16
+ import threading
17
+ import time
18
+ import uuid
19
+
20
+
21
+ _pause = threading.Event()
22
+ _message = threading.Event()
23
+ _answers = {}
24
+ _answered = threading.Condition()
25
+ _agent_listeners = []
26
+ _thoughts = set()
27
+ _physical = set()
28
+ _worker_calls = set()
29
+ _mcp_calls = set()
30
+ host_thoughts = False
31
+
32
+
33
+ def request_pause() -> None:
34
+ """Ask the running program to stop at its next execution step."""
35
+ with _answered:
36
+ _pause.set()
37
+ _answered.notify_all()
38
+
39
+
40
+ def request_message() -> None:
41
+ """Tell the running program a message for the model came."""
42
+ with _answered:
43
+ _message.set()
44
+ _answered.notify_all()
45
+
46
+
47
+ def clear() -> None:
48
+ """Forget earlier requests (a new cell starts)."""
49
+ _pause.clear()
50
+ _message.clear()
51
+
52
+
53
+ def message_arrived() -> bool:
54
+ """Whether a message for the model came while the program runs."""
55
+ return _message.is_set()
56
+
57
+
58
+ def pause_requested() -> bool:
59
+ """Whether the host asked the running program to pause."""
60
+ return _pause.is_set()
61
+
62
+
63
+ def wake_waiters():
64
+ with _answered:
65
+ _answered.notify_all()
66
+
67
+
68
+ def answer(identifier, value) -> None:
69
+ """The host's answer to the request `identifier`."""
70
+ with _answered:
71
+ identifier = str(identifier)
72
+ if isinstance(value, dict) and value.get("thought") and identifier not in _thoughts:
73
+ return
74
+ if isinstance(value, dict) and value.get("physical") and identifier not in _physical:
75
+ return
76
+ if isinstance(value, dict) and value.get("worker") and identifier not in _worker_calls:
77
+ return
78
+ if isinstance(value, dict) and value.get("mcp") and identifier not in _mcp_calls:
79
+ return
80
+ _answers[identifier] = value
81
+ _answered.notify_all()
82
+
83
+
84
+ def wait_answer(identifier, poll: float | None = None, stop=None, *, deadline: float | None = None,
85
+ interruptible=True):
86
+ """Wait for the host's answer, an interruption or an absolute monotonic deadline."""
87
+ identifier = str(identifier)
88
+ with _answered:
89
+ while identifier not in _answers:
90
+ if poll == 0 or (interruptible and _pause.is_set()) or (stop is not None and stop()):
91
+ return None
92
+ remaining = None if deadline is None else deadline - time.monotonic()
93
+ if remaining is not None and remaining <= 0:
94
+ return None
95
+ _answered.wait(poll if remaining is None else remaining if poll is None else min(poll, remaining))
96
+ return _answers.pop(identifier)
97
+
98
+
99
+ def worker_call(send, arguments, timeout):
100
+ """Relay a worker RPC over the kernel connection, with a finite receipt deadline."""
101
+ identifier = uuid.uuid4().hex
102
+ with _answered:
103
+ _worker_calls.add(identifier)
104
+ try:
105
+ deadline = time.monotonic() + timeout + 5
106
+ send({"op": "worker_request", "id": identifier, **arguments})
107
+ answer = wait_answer(identifier, deadline=deadline, interruptible=False)
108
+ finally:
109
+ with _answered:
110
+ _worker_calls.discard(identifier)
111
+ _answers.pop(identifier, None)
112
+ if answer is None:
113
+ raise RuntimeError("Worker receipt timed out; delivery may be unknown")
114
+ if "error" in answer:
115
+ raise RuntimeError(answer["error"])
116
+ return answer["value"]
117
+
118
+
119
+ def host_call(arguments, timeout):
120
+ """A worker call of an attached environment (runtime/execution/attached.py), made by the
121
+ session host: the kernel's own connection carries it, as it carries the host's controls."""
122
+ from harness.core import spans
123
+
124
+ if not spans.connected():
125
+ raise RuntimeError("An attached environment needs the conversation that runs this program")
126
+ return worker_call(spans._emit, arguments, timeout)
127
+
128
+
129
+ def ask_host(note, *, stop=None, **detail):
130
+ """Send the host a request as a note `note` and wait for its answer: the value, None
131
+ when the wait was interrupted (a pause, or `stop()`), ValueError with the host's reason
132
+ when it refused."""
133
+ from harness.core import spans
134
+
135
+ if not spans.connected():
136
+ raise RuntimeError(f"{note} needs the conversation that runs this program; none is connected")
137
+ identifier = uuid.uuid4().hex[:12]
138
+ spans.note(note, id=identifier, **detail)
139
+ answer = wait_answer(identifier, stop=stop)
140
+ if answer is None:
141
+ return None
142
+ if answer.get("error"):
143
+ raise ValueError(answer["error"])
144
+ return answer.get("value")
145
+
146
+
147
+ def think(role, text="", *, images=(), system=None, entry=None, frame=None, stop=None, **detail):
148
+ """Ask the session's host on behalf of a kernel entry."""
149
+ from harness.core import spans
150
+ from harness.runtime.decision.model import ChatReply
151
+ from harness.runtime.execution.entries import Cancelled, current_entry
152
+
153
+ sys.audit("harness.model_request", role)
154
+ if not host_thoughts or not spans.connected():
155
+ return None
156
+ if stop is None and threading.current_thread() is threading.main_thread():
157
+ stop = message_arrived
158
+ owner = current_entry()
159
+
160
+ def owner_cancelled():
161
+ return owner is not None and any(entry._cancel.is_set() for entry in owner.lineage())
162
+
163
+ identifier = uuid.uuid4().hex
164
+ with _answered:
165
+ _thoughts.add(identifier)
166
+ answer = None
167
+ try:
168
+ spans.note("thought", id=identifier, role=role, text=str(text), images=list(images),
169
+ system=system, entry=entry or spans.current_entry(), frame=frame, **detail)
170
+ answer = wait_answer(identifier, stop=lambda: owner_cancelled() or (stop is not None and stop()))
171
+ finally:
172
+ with _answered:
173
+ _thoughts.discard(identifier)
174
+ _answers.pop(identifier, None)
175
+ if answer is None:
176
+ spans.note("thought_cancel", id=identifier)
177
+ if owner_cancelled():
178
+ raise Cancelled(f"entry {owner.id} was cancelled")
179
+ if answer is None:
180
+ raise stopped(role)
181
+ if answer.get("error"):
182
+ raise RuntimeError(answer["error"])
183
+ value = answer.get("value")
184
+ return None if value is None else ChatReply(text=value["text"], usage=value.get("usage") or {},
185
+ seconds=float(value.get("seconds") or 0))
186
+
187
+
188
+ def stopped(skill: str = "program"):
189
+ """The typed escalation for an interrupted program wait."""
190
+ from harness.runtime.events import USER_MESSAGE, USER_PAUSED, Escalation, Event, ExecutionTrace
191
+
192
+ event = Event(USER_PAUSED if pause_requested() else USER_MESSAGE, "user")
193
+ return Escalation(ExecutionTrace(skill, {}, 0, 0, event))
194
+
195
+
196
+ def on_agent_ended(listener, remove: bool = False) -> None:
197
+ """Call listener(agent, report) when the host says a sub-agent ended (`remove`: stop)."""
198
+ if remove:
199
+ if listener in _agent_listeners:
200
+ _agent_listeners.remove(listener)
201
+ else:
202
+ _agent_listeners.append(listener)
203
+
204
+
205
+ def agent_ended(agent, report, *, cancelled=False) -> None:
206
+ """The host says the sub-agent `agent` ended, with its report."""
207
+ for listener in list(_agent_listeners):
208
+ try:
209
+ listener(agent, report, cancelled=cancelled)
210
+ except Exception:
211
+ pass