@lmmslab/harness 0.81.1 → 0.83.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 (80) hide show
  1. package/README.md +24 -35
  2. package/package.json +2 -2
  3. package/python/harness/README.md +3 -3
  4. package/python/harness/__init__.py +1 -1
  5. package/python/harness/builtin/configs/assistant.toml +0 -1
  6. package/python/harness/builtin/configs/default.toml +1 -1
  7. package/python/harness/builtin/prompts/conversation/core.md +2 -2
  8. package/python/harness/builtin/prompts/core/core.md +197 -45
  9. package/python/harness/builtin/prompts/core/pack.toml +2 -2
  10. package/python/harness/builtin/prompts/reflect/core.md +4 -13
  11. package/python/harness/builtin/prompts/reflect/pack.toml +3 -2
  12. package/python/harness/builtin/prompts/shared/learning-goal.md +5 -29
  13. package/python/harness/builtin/prompts/shared/learning.md +8 -10
  14. package/python/harness/builtin/prompts/shared/web.md +11 -0
  15. package/python/harness/builtin/skills/agents/__init__.py +24 -22
  16. package/python/harness/builtin/skills/entries/__init__.py +43 -28
  17. package/python/harness/builtin/skills/entries/skill.toml +2 -3
  18. package/python/harness/builtin/skills/environments/__init__.py +2 -9
  19. package/python/harness/builtin/skills/mcp/__init__.py +2 -3
  20. package/python/harness/builtin/skills/memory/__init__.py +2 -5
  21. package/python/harness/builtin/skills/web/__init__.py +92 -0
  22. package/python/harness/builtin/skills/web/skill.toml +9 -0
  23. package/python/harness/cli.py +85 -17
  24. package/python/harness/config/agent.py +36 -9
  25. package/python/harness/core/episodes.py +5 -4
  26. package/python/harness/core/lanes.py +3 -0
  27. package/python/harness/core/memory.py +5 -1
  28. package/python/harness/core/remote.py +4 -3
  29. package/python/harness/core/worker.py +58 -3
  30. package/python/harness/extensions.py +23 -2
  31. package/python/harness/host/__init__.py +43 -1
  32. package/python/harness/host/client.py +36 -6
  33. package/python/harness/host/http.py +19 -0
  34. package/python/harness/host/server.py +17 -3
  35. package/python/harness/host/sessions.py +3 -2
  36. package/python/harness/host/tasks.py +107 -26
  37. package/python/harness/host/workspaces.py +69 -7
  38. package/python/harness/model_list.py +1 -1
  39. package/python/harness/packages/manager.py +5 -1
  40. package/python/harness/providers.py +14 -5
  41. package/python/harness/runtime/decision/loop.py +105 -117
  42. package/python/harness/runtime/decision/messages.py +158 -55
  43. package/python/harness/runtime/decision/model.py +85 -22
  44. package/python/harness/runtime/decision/notices.py +66 -0
  45. package/python/harness/runtime/decision/prompts.py +15 -11
  46. package/python/harness/runtime/decision/protocol.py +12 -6
  47. package/python/harness/runtime/decision/thoughts.py +10 -16
  48. package/python/harness/runtime/events.py +28 -13
  49. package/python/harness/runtime/execution/attached.py +1 -1
  50. package/python/harness/runtime/execution/control.py +17 -35
  51. package/python/harness/runtime/execution/entries.py +204 -124
  52. package/python/harness/runtime/execution/kernel.py +471 -281
  53. package/python/harness/runtime/execution/managed.py +231 -0
  54. package/python/harness/runtime/execution/noenv.py +2 -2
  55. package/python/harness/runtime/execution/results.py +2 -0
  56. package/python/harness/runtime/execution/session.py +284 -115
  57. package/python/harness/runtime/learning/active.py +41 -50
  58. package/python/harness/runtime/learning/fixtures.py +2 -2
  59. package/python/harness/runtime/learning/learner.py +75 -2
  60. package/python/harness/runtime/learning/library.py +77 -10
  61. package/python/harness/runtime/learning/views.py +12 -1
  62. package/python/harness/runtime/reactive/__init__.py +1 -1
  63. package/python/harness/runtime/reactive/rules.py +29 -394
  64. package/python/harness/runtime/reactive/tree.py +611 -0
  65. package/python/harness/runtime/safety/approval.py +8 -3
  66. package/python/harness/runtime/safety/permissions.py +242 -0
  67. package/python/harness/runtime/status.py +7 -2
  68. package/python/harness/runtime/task/delegation.py +97 -58
  69. package/python/harness/runtime/task/environments.py +3 -4
  70. package/python/harness/runtime/task/inbound.py +64 -0
  71. package/python/harness/runtime/task/run.py +1231 -790
  72. package/python/harness/runtime/tick.py +257 -91
  73. package/python/harness/sdk/__init__.py +7 -4
  74. package/python/harness/settings.py +30 -5
  75. package/python/harness/terminal.py +10 -6
  76. package/python/harness/transcript.py +18 -6
  77. package/python/harness/tui/answer.py +51 -0
  78. package/python/harness/tui/chat.py +75 -26
  79. package/python/harness/tui/views.py +1 -0
  80. package/python/harness/builtin/prompts/shared/entries.md +0 -86
@@ -0,0 +1,242 @@
1
+ """What a program does on the machine it runs on, under the user's approvals.
2
+
3
+ A program of the model runs on the user's machine: it reads what the user can read. Three
4
+ kinds of step beyond its own folder go by the user's settings (approvals.programs and
5
+ approvals.rules; runtime/safety/approval.py holds the levels and the asking):
6
+
7
+ command it starts a process (the key of a rule and of "once": the program's name)
8
+ network it connects to a host that is not one of the environment's own services (the host)
9
+ write it creates, changes or moves a file outside its folder and the temporary
10
+ directory (the folder written in)
11
+
12
+ Two are sensitive steps (approval.SENSITIVE), which always wait for the user and are refused
13
+ where nobody can answer: opening a file that holds credentials, and deleting outside its
14
+ folder.
15
+
16
+ In the kernel an audit hook sees each such step before it happens and asks the conversation
17
+ (install); there Programs decides: never refuses, allow lets it through, ask_each asks
18
+ every time, ask_once_session once per conversation and key. Where nobody can be asked (a
19
+ run without a user) and the level asks, the step is refused with the reason: it never
20
+ waits and is never allowed silently. A user who skips confirmations (their physical-input
21
+ level is allow) is not asked; never still refuses. Every decision is a record of the
22
+ trace (program_permission).
23
+
24
+ Isolation (runtime/safety/isolation.py) is the stricter setting of evaluations: there
25
+ programs reach only the installation, the source and the services, and nothing is asked.
26
+ """
27
+
28
+ from fnmatch import fnmatchcase
29
+ import os
30
+ from pathlib import Path
31
+ import sys
32
+ import threading
33
+
34
+ from harness.runtime.safety.approval import LEVELS
35
+
36
+ ACTIONS = ("command", "network", "write")
37
+ DEFAULT_LEVEL = "ask_once_session"
38
+ # Folders and files that hold credentials, by name.
39
+ _CREDENTIAL_FOLDERS = frozenset((".ssh", ".aws", ".gnupg", ".kube", ".azure"))
40
+ _CREDENTIAL_FILES = frozenset((".env", ".netrc", ".git-credentials", ".harness_env", ".pypirc", "id_rsa", "id_ed25519",
41
+ "id_ecdsa", ".credentials.json"))
42
+ _PROCESS_EVENTS = ("subprocess.Popen", "os.system", "os.exec", "os.posix_spawn", "os.spawn", "os.startfile",
43
+ "pty.spawn")
44
+ _DELETES = ("os.remove", "os.rmdir", "shutil.rmtree")
45
+
46
+
47
+ def credentials(path: str) -> bool:
48
+ """Whether `path` is a file that holds credentials, by the names such files have."""
49
+ parts = Path(path).parts
50
+ name = parts[-1].lower() if parts else ""
51
+ return (name in _CREDENTIAL_FILES or name.startswith(".env.")
52
+ or any(part.lower() in _CREDENTIAL_FOLDERS for part in parts[:-1]))
53
+
54
+
55
+ def level_of(policy: dict, action: str, key: str) -> str:
56
+ """The level of approval.LEVELS for a step: the first rule of `policy` ({"programs":
57
+ level, "rules": [{level, action, match}]}) whose action is this one and whose match
58
+ (a glob, without case) fits `key`; else the policy's level, else DEFAULT_LEVEL."""
59
+ for rule in policy.get("rules") or ():
60
+ if rule.get("action") == action and fnmatchcase(key.lower(), str(rule.get("match") or "*").lower()):
61
+ return rule["level"]
62
+ return policy.get("programs") or DEFAULT_LEVEL
63
+
64
+
65
+ def rules(value) -> list:
66
+ """approvals.rules as kept: each {"level": one of LEVELS, "action": one of ACTIONS,
67
+ "match": a glob on the program's name, the host or the folder}."""
68
+ kept = []
69
+ for row in value:
70
+ if not isinstance(row, dict) or set(row) != {"level", "action", "match"}:
71
+ raise ValueError("a rule is {level, action, match}")
72
+ if row["level"] not in LEVELS:
73
+ raise ValueError(f"a rule's level is one of {', '.join(LEVELS)}")
74
+ if row["action"] not in ACTIONS:
75
+ raise ValueError(f"a rule's action is one of {', '.join(ACTIONS)}")
76
+ match = str(row["match"]).strip()
77
+ if not match or len(match) > 200:
78
+ raise ValueError("a rule's match is a glob of 1 to 200 characters: a program's name, a host or a folder")
79
+ kept.append({"level": row["level"], "action": row["action"], "match": match})
80
+ return kept
81
+
82
+
83
+ class Programs:
84
+ """The steps of one conversation's programs on the machine (TaskRun.programs)."""
85
+
86
+ def __init__(self, conversation):
87
+ self.conversation = conversation
88
+ self.granted = set()
89
+ self._lock = threading.Lock()
90
+
91
+ def handle(self, request: dict) -> dict:
92
+ """Answer the kernel's question about one step: {"value": "session" (it need not
93
+ ask again for this action and key) or "once"} or {"error": why it may not}."""
94
+ conversation, trace = self.conversation, self.conversation.trace
95
+ action, key, what = str(request.get("action")), str(request.get("key") or ""), str(request.get("what") or "")
96
+ sensitive = request.get("sensitive")
97
+ runtime = conversation.config.runtime
98
+ policy = runtime.get("approvals") or {}
99
+ level = "ask_each" if sensitive else level_of(policy, action, key)
100
+ skips = (runtime.get("physical") or {}).get("level") == "allow" and not sensitive
101
+ target = {"command": f"run the command {what}", "network": f"connect to {what}",
102
+ "write": f"write {what}"}.get(action, what) if not sensitive else what
103
+
104
+ def decided(allowed, why="", asked=False):
105
+ trace.emit("program_permission", action=action, key=key, what=what[:300], level=level, allowed=allowed,
106
+ asked=asked, **({"sensitive": sensitive} if sensitive else {}), **({"reason": why} if why else {}))
107
+ if not allowed:
108
+ return {"error": why}
109
+ return {"value": "session" if level in ("allow", "ask_once_session") and not sensitive else "once"}
110
+
111
+ if level == "never":
112
+ return decided(False, f"the user's settings never allow a program to {target} (approvals). Go on "
113
+ "without it and say what you could not do.")
114
+ with self._lock:
115
+ granted = (action, key) in self.granted
116
+ if skips or level == "allow" or level == "ask_once_session" and granted:
117
+ return decided(True)
118
+ if not conversation.interactive:
119
+ return decided(False, f"the user's settings ask before a program may {target} (approvals), and nobody "
120
+ "can be asked in this run. Go on without it and say what you could not do.")
121
+ accepted, reason = conversation._ask_user(sensitive or "program", target, action=action)
122
+ if not accepted:
123
+ return decided(False, f"the user did not allow the program to {target}" + (f": {reason}" if reason else "")
124
+ + ". Go on without it and say what you could not do.", asked=True)
125
+ if level == "ask_once_session":
126
+ with self._lock:
127
+ self.granted.add((action, key))
128
+ return decided(True, asked=True)
129
+
130
+
131
+ def install(allowed: set, writable: list, ask) -> None:
132
+ """In the kernel: before a program starts a process, connects to a host outside
133
+ `allowed` ((host, port) of the environment's services), changes a file outside
134
+ `writable`, or opens a file of credentials, ask the conversation: `ask(action=, key=,
135
+ what=, sensitive=)` gives "session" or "once", None when the question was interrupted,
136
+ and raises ValueError with the reason when the step may not be. The harness's own
137
+ threads (those alive now: they serve the answers) are not asked."""
138
+ import socket
139
+
140
+ own = frozenset(thread.ident for thread in threading.enumerate())
141
+ asking = threading.local()
142
+ granted, names = set(), {}
143
+ addresses = {}
144
+
145
+ def real(path) -> str:
146
+ return os.path.normcase(os.path.realpath(os.fsdecode(path)))
147
+
148
+ roots = tuple(dict.fromkeys(real(path) for path in writable))
149
+
150
+ def resolve():
151
+ for host, port in allowed:
152
+ try:
153
+ infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
154
+ except OSError:
155
+ continue
156
+ for info in infos:
157
+ addresses.setdefault(info[4][0], set()).add(port)
158
+
159
+ asking.busy = True
160
+ try:
161
+ resolve()
162
+ finally:
163
+ asking.busy = False
164
+
165
+ def decide(action, key, what, sensitive=None):
166
+ if getattr(asking, "busy", False) or threading.get_ident() in own:
167
+ return
168
+ if sensitive is None and (action, key) in granted:
169
+ return
170
+ asking.busy = True
171
+ try:
172
+ answer = ask(action=action, key=key, what=what, **({"sensitive": sensitive} if sensitive else {}))
173
+ except (ValueError, RuntimeError) as error:
174
+ raise PermissionError(str(error)) from None
175
+ finally:
176
+ asking.busy = False
177
+ if answer is None:
178
+ raise PermissionError("the question whether this step is allowed was interrupted")
179
+ if answer == "session":
180
+ granted.add((action, key))
181
+
182
+ def outside(path) -> str | None:
183
+ if isinstance(path, int) or path is None:
184
+ return None
185
+ resolved = real(path)
186
+ if "__pycache__" in resolved.split(os.sep):
187
+ return None # the interpreter's own compiled modules
188
+ return None if any(resolved == root or resolved.startswith(root.rstrip(os.sep) + os.sep)
189
+ for root in roots) else resolved
190
+
191
+ def command(event, args):
192
+ if event == "os.system":
193
+ line = os.fsdecode(args[0])
194
+ elif event == "subprocess.Popen":
195
+ line = args[1] if isinstance(args[1], (str, bytes)) else " ".join(map(os.fsdecode, args[1] or [args[0]]))
196
+ line = os.fsdecode(line)
197
+ else:
198
+ # (os.exec: path, args; os.spawn: mode, path, args; os.posix_spawn: path, argv; os.startfile: path)
199
+ line = os.fsdecode(next((part for part in args if isinstance(part, (str, bytes, os.PathLike))), ""))
200
+ first = line.split()[0] if line.split() else ""
201
+ name = os.path.basename(first.strip("\"'")).lower()
202
+ decide("command", name.removesuffix(".exe"), line[:300])
203
+
204
+ def hook(event, args):
205
+ if event == "socket.getaddrinfo":
206
+ if isinstance(args[0], str):
207
+ asking.name = args[0] # the name the next addresses of this thread stand for
208
+ elif event == "socket.connect":
209
+ address = args[1]
210
+ if not (isinstance(address, tuple) and len(address) >= 2):
211
+ return # a local socket
212
+ host, port = str(address[0]), address[1]
213
+ if port in addresses.get(host, ()):
214
+ return
215
+ name = names.setdefault(host, getattr(asking, "name", None) or host)
216
+ decide("network", name, f"{name}:{port}")
217
+ elif event.startswith(_PROCESS_EVENTS):
218
+ command(event, args)
219
+ elif event == "open":
220
+ path, mode, flags = args
221
+ if isinstance(path, int) or path is None:
222
+ return
223
+ writes = ((isinstance(mode, str) and any(c in mode for c in "wax+"))
224
+ or (isinstance(flags, int) and bool(flags & (os.O_WRONLY | os.O_RDWR | os.O_CREAT
225
+ | os.O_APPEND | os.O_TRUNC))))
226
+ if credentials(os.fsdecode(path)):
227
+ decide("read", real(path), f"open {os.fsdecode(path)}, which holds credentials", "credentials")
228
+ elif writes:
229
+ beyond = outside(path)
230
+ if beyond is not None:
231
+ decide("write", os.path.dirname(beyond), beyond)
232
+ elif event in _DELETES:
233
+ beyond = outside(args[0])
234
+ if beyond is not None:
235
+ decide("write", beyond, f"delete {beyond}", "deleting")
236
+ elif event in ("os.mkdir", "os.rename", "os.link", "os.symlink", "os.truncate", "os.chmod", "os.chown"):
237
+ for path in args[:2] if event in ("os.rename", "os.link") else args[:1]:
238
+ beyond = outside(path) if isinstance(path, (str, bytes, os.PathLike)) else None
239
+ if beyond is not None:
240
+ decide("write", os.path.dirname(beyond), beyond)
241
+
242
+ sys.addaudithook(hook)
@@ -7,8 +7,9 @@ WAITING_FOR_CONFIRMATION = "WAITING_FOR_CONFIRMATION"
7
7
  WAITING_FOR_INPUT = "WAITING_FOR_INPUT"
8
8
  FINISHED = "FINISHED"
9
9
  ERROR = "ERROR"
10
- # IDLE: waiting for the user's next message (interactive only); FINISHED: the episode is
11
- # over (its summary says why); ERROR: it ended in an error.
10
+ # IDLE: between turns (its reason says how the last turn ended): the conversation keeps
11
+ # everything and waits for what starts the next turn; FINISHED: the conversation is over
12
+ # (its summary says how its last turn ended); ERROR: it ended in an error.
12
13
  LIVE = (IDLE, RUNNING, PAUSED, WAITING_FOR_CONFIRMATION, WAITING_FOR_INPUT)
13
14
  ENDED = (FINISHED, ERROR, "INTERRUPTED")
14
15
  STATUSES = (*LIVE, FINISHED, ERROR)
@@ -21,3 +22,7 @@ def live(status) -> bool:
21
22
 
22
23
  class Closed(Exception):
23
24
  """The user closed the conversation while it waited."""
25
+
26
+
27
+ class Interrupted(Exception):
28
+ """The user ended the turn that ran."""
@@ -11,8 +11,9 @@ tree (host/sessions.py) and run in a workspace the session's Place gives it:
11
11
  "display": a new one of that kind)
12
12
  share the windows the parent holds now are handed over (the session's window
13
13
  ownership, `windows`: the computer package's WindowOwners.transfer): the
14
- sub-agent owns them while it runs, the parent cannot use them meanwhile, and
15
- they come back to the parent when the sub-agent ends.
14
+ sub-agent owns them while a turn of it runs, the parent cannot use them
15
+ meanwhile, and they come back to the parent when the turn ends (a message to
16
+ the sub-agent hands them over again).
16
17
  It still runs in a worker of its own (a worker serves one episode); its
17
18
  instruction names the windows it was handed.
18
19
 
@@ -30,12 +31,18 @@ its parent's budget, and its parent's, as it is spent. An agent at the session's
30
31
  nesting depth (`max_depth`, default 1: the main agent's sub-agents start none) cannot
31
32
  delegate.
32
33
 
33
- A sub-agent works on its task alone: its <finish> (or a used-up budget) ends it, and its
34
- report (status, result, usage, files) goes back to its parent, which wait_agents() gives
35
- it and whose trace keeps it (agent_report). A plain reply is a question to its parent:
36
- it waits, and wait_agents() returns, until the parent answers with send_agent(). The
37
- user may talk to any agent of the session from any frontend; what an agent asks the user
38
- (an approval, physical input) is listed with its session, where every frontend answers it.
34
+ A sub-agent is a model, and each turn of it a unit of the model that started it: its
35
+ answer (or a limit of the turn) ends the turn, and the turn's end, with its report (status,
36
+ result, usage, files), reaches its parent as every unit's end does (it wakes a waiting
37
+ parent), which wait_agents() also gives and whose trace keeps (agent_report). The sub-agent
38
+ is then idle with what it has (its history, its kernel, its workspace): send_agent() gives
39
+ it another message, more to do or the answer to what it asked, and it goes on; it ends when
40
+ its parent ends or cancels it (cancel_agent). Where no user takes part (a benchmark's run),
41
+ it ends with its first turn. The user may talk to any agent of the session from any
42
+ frontend; what an agent asks the user (an approval, physical input) is listed with its
43
+ session, where every frontend answers it. Each model has an embodiment of its own (a
44
+ workspace, or the windows handed over): two models acting on one embodiment at the same
45
+ time is not supported.
39
46
  """
40
47
 
41
48
  from copy import copy
@@ -60,10 +67,10 @@ OWN_FILES = {"events.jsonl", "manifest.json", "summary.json", "kernel.log", "met
60
67
  # Added to a sub-agent's system prompt in place of the interactive one.
61
68
  SUB_AGENT_PROMPT = (
62
69
  "\n\nYou are a sub-agent: another agent (the one that started you) gave you this task, and it waits for "
63
- "your result. When the task is done, <finish> with what it needs to know (what you found or did, and where "
64
- "any files are); that ends your work and your result goes back to it. To ask it something, reply in plain "
65
- "text without any block: you wait for its answer, which reaches you as \"Message from the agent that "
66
- "started you: ...\". The user may also write to you (\"Message from the user: ...\")."
70
+ "your result. A reply in plain text, without any block, is your answer and goes back to it: what it needs "
71
+ "to know (what you found or did, and where any files are), or a question you need answered. It ends this "
72
+ "turn; you keep what you have, and its next message, which reaches you as \"Message from the agent that "
73
+ "started you: ...\", starts your next turn. The user may also write to you (\"Message from the user: ...\")."
67
74
  )
68
75
  NO_DEEPER = " You cannot start sub-agents of your own."
69
76
 
@@ -104,7 +111,11 @@ class Child:
104
111
  self.windows = windows
105
112
  self.run = None
106
113
  self.started = time.time()
114
+ # What its last turn ended with (None while a turn runs), whether it waits between
115
+ # turns, and whether it ended.
107
116
  self.report = None
117
+ self.idle = False
118
+ self.ended = False
108
119
  self.cancel_requested = False
109
120
  self.error = None
110
121
 
@@ -184,8 +195,7 @@ class Agents:
184
195
  budget=request.get("budget"), model=request.get("model"),
185
196
  agent=request.get("agent"), multi_turn=request.get("multi_turn", False))
186
197
  elif operation == "wait":
187
- value = self.wait(conversation, request.get("ids"), timeout=request.get("timeout"),
188
- told=request.get("own", True), interrupt_at=request.get("interrupt_at"))
198
+ value = self.wait(conversation, request.get("ids"), timeout=request.get("timeout"))
189
199
  elif operation == "send":
190
200
  value = self.send(conversation, request.get("agent"), request.get("text"))
191
201
  elif operation == "cancel":
@@ -246,7 +256,7 @@ class Agents:
246
256
  instruction = task
247
257
  if workspace == "share":
248
258
  windows = self._held(parent)
249
- instruction += "\n\nResources lent to you until you finish: " + ", ".join(item["label"] for item in windows)
259
+ instruction += "\n\nResources lent to you while you work: " + ", ".join(item["label"] for item in windows)
250
260
  if external is not None:
251
261
  conversation = external(task, Path(parent.directory) / "agents" / agent, budget=budget,
252
262
  model=None if model is None else str(model), charge=parent._charge,
@@ -285,7 +295,7 @@ class Agents:
285
295
  child.run = agent
286
296
  conversation.identity = {"session": session or "local", "agent": agent,
287
297
  "parent": (parent.identity or {}).get("agent") or "main"}
288
- # The windows are the sub-agent's from now until it ends.
298
+ # The windows are the sub-agent's from now until its turn ends.
289
299
  for item in windows:
290
300
  self.windows.transfer(item["id"], parent.identity, conversation.identity)
291
301
  conversation.trace.subscribe(lambda record: self._watch(record, child))
@@ -338,45 +348,56 @@ class Agents:
338
348
  release()
339
349
  except Exception:
340
350
  pass
341
- self._ended(child)
351
+ with self._changed:
352
+ child.ended = True
353
+ reported = child.report is not None
354
+ self._changed.notify_all()
355
+ if not reported:
356
+ # (No turn of it gave a result: another harness's agent, or one that never began.)
357
+ self._turn_over(child)
342
358
 
343
- def _ended(self, child: Child) -> None:
344
- """A sub-agent ended: its windows go back, its last spending is charged, and its report
345
- goes to its parent."""
359
+ def _lend(self, child: Child, back: bool = False) -> None:
360
+ """The windows a sub-agent shares are its own while a turn of it runs, and its
361
+ parent's again (`back`) between its turns."""
346
362
  conversation, parent = child.conversation, child.parent
347
- if child.windows and conversation.identity and parent.identity:
348
- for window in child.windows:
349
- try:
350
- self.windows.transfer(window, conversation.identity, parent.identity)
351
- except ValueError:
352
- pass # it gave the window up (or its worker's process ended): it is free
363
+ if not (child.windows and conversation.identity and parent.identity):
364
+ return
365
+ owner, to = (conversation.identity, parent.identity) if back else (parent.identity, conversation.identity)
366
+ for window in child.windows:
367
+ try:
368
+ self.windows.transfer(window, owner, to)
369
+ except ValueError:
370
+ pass # its owner gave the window up (or its worker's process ended): it is free
371
+
372
+ def _turn_over(self, child: Child) -> None:
373
+ """A turn of a sub-agent ended (its turn_result record; the end of one that has no
374
+ turns): its windows go back, its spending is charged, and its report goes to its
375
+ parent, whose kernel ends the turn's unit: the model that started it hears of it
376
+ as of every unit's end."""
377
+ conversation, parent = child.conversation, child.parent
378
+ self._lend(child, back=True)
353
379
  conversation.charge_up()
354
- report = self.state(child, ended=True)
355
- invalidate = getattr(parent, "invalidate_lookahead", None)
356
- if invalidate is not None:
357
- invalidate()
380
+ report = self.state(child, over=True)
358
381
  parent.trace.emit("agent_report", **report)
359
382
  with self._changed:
360
383
  child.report = report
361
384
  self._changed.notify_all()
362
- # Its entry in the parent's program ends (runtime/execution/entries.py).
385
+ # Its unit in the parent's kernel ends (runtime/execution/entries.py).
363
386
  kernel = getattr(parent, "kernel", None)
364
387
  if kernel is not None:
365
388
  kernel.agent_ended(child.id, report, cancelled=child.cancel_requested)
366
389
 
367
- def state(self, child: Child, ended: bool = False) -> dict:
368
- """A sub-agent as its parent sees it: its status (running, waiting for approval, asks
369
- you (question), finished, closed, error, ...), its result or question, what it spent
370
- and its files."""
371
- if child.report is not None:
390
+ def state(self, child: Child, over: bool = False) -> dict:
391
+ """A sub-agent as its parent sees it: its status (running, waiting for approval, or
392
+ how its last turn ended: finished, budget_exhausted, closed, error, ...), its
393
+ result, what it spent and its files. `over`: its turn is just over."""
394
+ if child.report is not None and not over:
372
395
  return child.report
373
396
  conversation = child.conversation
374
397
  summary = conversation.summary or {}
375
398
  status = conversation.status
376
- if ended or not live(status):
399
+ if over or not live(status):
377
400
  word = summary.get("status") or ("error" if status == "ERROR" else "finished")
378
- elif status == "IDLE" and conversation.question:
379
- word = "asks"
380
401
  elif status == "IDLE" and getattr(conversation, "multi_turn", False) and conversation.result is not None:
381
402
  word = "ready"
382
403
  else:
@@ -387,7 +408,6 @@ class Agents:
387
408
  path.relative_to(directory).parts[:1]) if directory.is_dir() and word != "running" else []
388
409
  error = summary.get("error") or child.error
389
410
  return {"agent": child.id, "run": child.run, "status": word, "result": conversation.result,
390
- "question": conversation.question if word == "asks" else None,
391
411
  **({"error": error} if error and word == "error" else {}),
392
412
  "model_calls": summary.get("model_calls", 0) + conversation.agents_usage["model_calls"],
393
413
  "cost_usd": round(summary.get("cost_usd", 0.0) + conversation.agents_usage["cost_usd"], 6),
@@ -395,8 +415,18 @@ class Agents:
395
415
  "files": files[:50]}
396
416
 
397
417
  def _watch(self, record: dict, child: Child) -> None:
398
- if record.get("event") == "state":
418
+ """A record of a sub-agent's trace: the end of a turn is reported; a turn that
419
+ begins after one (a message of its parent or of the user, the end of a unit of
420
+ its own) has no report yet."""
421
+ event = record.get("event")
422
+ if event == "turn_result":
423
+ self._turn_over(child)
424
+ elif event == "state":
399
425
  with self._changed:
426
+ if record.get("status") == "IDLE":
427
+ child.idle = True
428
+ elif child.idle and record.get("status") == "RUNNING":
429
+ child.idle, child.report = False, None
400
430
  self._changed.notify_all()
401
431
  if record.get("reason") == "external_turn":
402
432
  child.parent.trace.emit("agent_report", **self.state(child))
@@ -405,11 +435,10 @@ class Agents:
405
435
  with self._changed:
406
436
  self._changed.notify_all()
407
437
 
408
- def wait(self, parent, ids=None, timeout=None, told=True, *, interrupt_at=None) -> dict:
409
- """Wait until each of `parent`'s sub-agents `ids` (default: all it started) has ended
410
- or asks it something, at most `timeout` seconds (None: as long as it takes), or until
411
- `parent` is paused or closed, or (`told`: the program's own code waits) a message
412
- for it comes; their states."""
438
+ def wait(self, parent, ids=None, timeout=None) -> dict:
439
+ """Wait until the turn of each of `parent`'s sub-agents `ids` (default: all it
440
+ started) is over, at most `timeout` seconds (None: as long as it takes), or until
441
+ `parent` is paused or closed; their states."""
413
442
  children = self.children(parent) if not ids else [self._mine(parent, agent) for agent in
414
443
  ([ids] if isinstance(ids, str) else ids)]
415
444
  if not children:
@@ -420,14 +449,11 @@ class Agents:
420
449
  deadline = None if timeout is None else began + float(timeout)
421
450
 
422
451
  def settled(child):
423
- return child.report is not None or self.state(child)["status"] in ("asks", "ready")
452
+ return child.report is not None or self.state(child)["status"] == "ready"
424
453
 
425
- if interrupt_at is None:
426
- interrupt_at = getattr(parent, "_interruptions", 0)
427
454
  with self._changed:
428
455
  while not all(settled(child) for child in children):
429
- if parent._closing or parent._pause or (told and getattr(parent, "_interruptions", 0) != interrupt_at) or (
430
- deadline is not None and time.monotonic() >= deadline):
456
+ if parent._closing or parent._pause or (deadline is not None and time.monotonic() >= deadline):
431
457
  break
432
458
  self._changed.wait(None if deadline is None else max(0, deadline - time.monotonic()))
433
459
  states = {child.id: self.state(child) for child in children}
@@ -437,14 +463,27 @@ class Agents:
437
463
  return states
438
464
 
439
465
  def send(self, parent, agent, text) -> dict:
440
- """A message from `parent` to its sub-agent `agent`, for its next model call."""
466
+ """A message from `parent` to its sub-agent `agent`: for its next model call while
467
+ its turn runs, else it starts its next turn, in which it goes on with what it has."""
441
468
  child = self._mine(parent, agent)
442
469
  text = str(text or "").strip()
443
470
  if not text:
444
471
  raise ValueError("say something")
445
- if child.report is not None:
446
- raise ValueError(f"sub-agent {agent} has ended ({child.report['status']})")
447
- child.conversation.send_message(text, sender="parent")
472
+ with self._changed:
473
+ if child.ended:
474
+ raise ValueError(f"sub-agent {agent} has ended ({(child.report or {}).get('status')})")
475
+ idle, report = child.report is not None, child.report
476
+ child.report = None
477
+ if idle:
478
+ self._lend(child)
479
+ try:
480
+ child.conversation.send_message(text, sender="parent")
481
+ except Exception:
482
+ with self._changed:
483
+ child.report = child.report or report
484
+ if idle:
485
+ self._lend(child, back=True)
486
+ raise
448
487
  parent.trace.emit("agent_sent", agent=child.id, text=text)
449
488
  return {"ok": True}
450
489
 
@@ -455,14 +494,14 @@ class Agents:
455
494
  child.cancel_requested = True
456
495
  child.conversation.close()
457
496
  with self._changed:
458
- self._changed.wait_for(lambda: child.report is not None, wait)
497
+ self._changed.wait_for(lambda: child.ended, wait)
459
498
  return self.state(child)
460
499
 
461
500
  def end_all(self, parent, wait: float = 30.0) -> None:
462
501
  """`parent` ends: so do its sub-agents (theirs first)."""
463
- children = [child for child in self.children(parent) if child.report is None]
502
+ children = [child for child in self.children(parent) if not child.ended]
464
503
  for child in children:
465
504
  child.cancel_requested = True
466
505
  child.conversation.close()
467
506
  with self._changed:
468
- self._changed.wait_for(lambda: all(child.report is not None for child in children), wait)
507
+ self._changed.wait_for(lambda: all(child.ended for child in children), wait)
@@ -31,8 +31,7 @@ or while it runs); request_agents asks the user, and a yes loads their calls and
31
31
  import threading
32
32
 
33
33
  from harness.embodiments import KINDS, embodiment_kind
34
-
35
- LEVELS = ("never", "ask_each", "ask_once_session", "allow")
34
+ from harness.runtime.safety.approval import LEVELS # noqa: F401 (the levels of environments.attach)
36
35
 
37
36
 
38
37
  class Refused(ValueError):
@@ -208,7 +207,7 @@ class Environments:
208
207
  prompt = (f"\n\nEnvironment `{kind}` ({label}) is attached to this conversation. Its calls are the ones "
209
208
  f"described below, each called as {kind}.NAME(...), never by the bare name; this conversation's "
210
209
  f"own calls stay as they are. release_environment({kind!r}) gives it back."
211
- + (f" {kind}.look() puts its view in your next turn; nothing of it is shown otherwise."
210
+ + (f" {kind}.look() puts its view with the program's result; nothing of it is shown otherwise."
212
211
  if KINDS[taken["embodiment"]].cameras else "") + "\n"
213
212
  + (taken.get("prompt") or "").strip() + "\n")
214
213
  from harness.core.remote import RemoteEnvironment
@@ -222,7 +221,7 @@ class Environments:
222
221
  "slot": threading.BoundedSemaphore(8), "prompt": prompt,
223
222
  "answer": {"session": session,
224
223
  "about": f"{kind} ({label}) is attached: call it as {kind}.NAME(...). Its calls are "
225
- "described in your instructions from the next turn on; "
224
+ "described in your instructions from your next reply on; "
226
225
  f"print({kind}) lists them now."}}
227
226
 
228
227
  def release(self, kind: str, *, reason=None, failed=None) -> bool:
@@ -0,0 +1,64 @@
1
+ """What the environment tells a run, pushed in.
2
+
3
+ A run keeps one entry for things that happen by themselves in its environment and that the
4
+ model must hear of: `TaskRun.tell(content)`, a message in the form conversations give
5
+ content (a string, or a list of text and image parts). Whoever calls it puts the message
6
+ before the model at once (a wait ends, a call in flight is asked again). Nothing is read
7
+ on time for it.
8
+
9
+ A worker reaches it over HTTP: when its profile says "tells", the run opens a listener on
10
+ this computer (one address and token for the run) and gives both to the worker
11
+ (`tell_to`); the worker's `tell()` (core/worker.py Tells) posts there.
12
+
13
+ POST <url> {"token", "content": "..." | [{"type": "text", "text"}, {"type": "image_url", "image_url": {"url"}}], "source"}
14
+ """
15
+
16
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
17
+ import hmac
18
+ import json
19
+ import secrets
20
+ import threading
21
+
22
+ # What one message may carry: its JSON, pictures included.
23
+ MAX_BYTES = 32 * 1024 * 1024
24
+
25
+
26
+ class Inbound:
27
+ """The listener of one run: `url` and `token` are what its worker is given."""
28
+
29
+ def __init__(self, run):
30
+ self.token = secrets.token_urlsafe(24)
31
+ inbound = self
32
+
33
+ class Handler(BaseHTTPRequestHandler):
34
+ def log_message(self, *_):
35
+ pass
36
+
37
+ def do_POST(self):
38
+ try:
39
+ length = int(self.headers.get("content-length") or 0)
40
+ if not 0 < length <= MAX_BYTES:
41
+ raise ValueError("a message is a JSON body")
42
+ told = json.loads(self.rfile.read(length))
43
+ if not hmac.compare_digest(str(told.get("token") or ""), inbound.token):
44
+ self.send_response(403)
45
+ self.end_headers()
46
+ return
47
+ run.tell(told["content"], told.get("source"))
48
+ answer, status = b'{"told": true}', 200
49
+ except Exception as error:
50
+ answer, status = json.dumps({"error": f"{type(error).__name__}: {error}"}).encode(), 400
51
+ self.send_response(status)
52
+ self.send_header("content-type", "application/json")
53
+ self.send_header("content-length", str(len(answer)))
54
+ self.end_headers()
55
+ self.wfile.write(answer)
56
+
57
+ self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
58
+ self.server.daemon_threads = True
59
+ self.url = f"http://127.0.0.1:{self.server.server_address[1]}/tell"
60
+ threading.Thread(target=self.server.serve_forever, name="harness-told", daemon=True).start()
61
+
62
+ def close(self) -> None:
63
+ self.server.shutdown()
64
+ self.server.server_close()