traceforge-pcb 1.0.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 (219) hide show
  1. traceforge/__init__.py +3 -0
  2. traceforge/__main__.py +3 -0
  3. traceforge/acp_server.py +570 -0
  4. traceforge/agent.py +680 -0
  5. traceforge/altium/__init__.py +6 -0
  6. traceforge/altium/cfb.py +70 -0
  7. traceforge/altium/cli.py +60 -0
  8. traceforge/altium/model.py +163 -0
  9. traceforge/altium/outputs.py +24 -0
  10. traceforge/altium/pcb.py +301 -0
  11. traceforge/altium/project.py +328 -0
  12. traceforge/altium/schematic.py +400 -0
  13. traceforge/altium/tools.py +166 -0
  14. traceforge/approval.py +219 -0
  15. traceforge/attachments.py +346 -0
  16. traceforge/background.py +253 -0
  17. traceforge/bench/__init__.py +5 -0
  18. traceforge/bench/adapters.py +337 -0
  19. traceforge/bench/checks.py +410 -0
  20. traceforge/bench/cli.py +121 -0
  21. traceforge/bench/design.py +439 -0
  22. traceforge/bench/kicad.py +99 -0
  23. traceforge/bench/partscheck.py +159 -0
  24. traceforge/bench/review.py +100 -0
  25. traceforge/bench/runner.py +226 -0
  26. traceforge/bench/score.py +204 -0
  27. traceforge/bench/tasks.py +102 -0
  28. traceforge/chat.py +1185 -0
  29. traceforge/checks.py +328 -0
  30. traceforge/checks_sides.py +118 -0
  31. traceforge/cli.py +2224 -0
  32. traceforge/clipboard.py +107 -0
  33. traceforge/config.py +299 -0
  34. traceforge/context.py +276 -0
  35. traceforge/design/__init__.py +1 -0
  36. traceforge/design/constraints.py +397 -0
  37. traceforge/design/generate.py +1789 -0
  38. traceforge/design/outline.py +905 -0
  39. traceforge/design/schematic_layout.py +932 -0
  40. traceforge/design/schematic_lint.py +329 -0
  41. traceforge/design/schematic_route.py +207 -0
  42. traceforge/design/sheets.py +854 -0
  43. traceforge/design/sides.py +328 -0
  44. traceforge/design/spec.py +462 -0
  45. traceforge/design/specsheet.py +2351 -0
  46. traceforge/design/specsheet_render.py +183 -0
  47. traceforge/desktop/__init__.py +109 -0
  48. traceforge/desktop/keys.py +90 -0
  49. traceforge/desktop/project.py +443 -0
  50. traceforge/desktop/review.py +20 -0
  51. traceforge/desktop/server.py +1277 -0
  52. traceforge/desktop/static/app.css +223 -0
  53. traceforge/desktop/static/app.js +683 -0
  54. traceforge/desktop/static/highlight.js +77 -0
  55. traceforge/desktop/static/index.html +89 -0
  56. traceforge/desktop/static/md.js +90 -0
  57. traceforge/desktop/static/viewer.js +213 -0
  58. traceforge/desktop/symbols.py +212 -0
  59. traceforge/desktop/update.py +65 -0
  60. traceforge/diagnostics.py +67 -0
  61. traceforge/errata.py +219 -0
  62. traceforge/fab.py +108 -0
  63. traceforge/fab_layers.py +44 -0
  64. traceforge/features/__init__.py +6 -0
  65. traceforge/features/candidates.py +117 -0
  66. traceforge/features/cli.py +200 -0
  67. traceforge/features/package.py +433 -0
  68. traceforge/features/revdiff.py +224 -0
  69. traceforge/features/sarif.py +145 -0
  70. traceforge/features/viewer.py +265 -0
  71. traceforge/firmware/__init__.py +3 -0
  72. traceforge/firmware/cli.py +174 -0
  73. traceforge/firmware/drivers.py +372 -0
  74. traceforge/firmware/drivers_data.py +256 -0
  75. traceforge/firmware/mcus.py +177 -0
  76. traceforge/firmware/netlist.py +55 -0
  77. traceforge/firmware/pinmap.py +296 -0
  78. traceforge/firmware/scaffold.py +466 -0
  79. traceforge/firmware/toolchain.py +262 -0
  80. traceforge/hooks.py +237 -0
  81. traceforge/kicad/__init__.py +0 -0
  82. traceforge/kicad/cli.py +519 -0
  83. traceforge/kicad/diffpair.py +174 -0
  84. traceforge/kicad/edgegeom.py +191 -0
  85. traceforge/kicad/edit.py +405 -0
  86. traceforge/kicad/escape.py +1410 -0
  87. traceforge/kicad/formats.py +1073 -0
  88. traceforge/kicad/impedance.py +320 -0
  89. traceforge/kicad/install.py +75 -0
  90. traceforge/kicad/libraries.py +490 -0
  91. traceforge/kicad/models3d.py +942 -0
  92. traceforge/kicad/outputs.py +81 -0
  93. traceforge/kicad/pcb.py +787 -0
  94. traceforge/kicad/planes.py +1242 -0
  95. traceforge/kicad/project.py +136 -0
  96. traceforge/kicad/route.py +2698 -0
  97. traceforge/kicad/routegeom.py +164 -0
  98. traceforge/kicad/schematic.py +268 -0
  99. traceforge/kicad/sides.py +34 -0
  100. traceforge/kicad/stackup.py +424 -0
  101. traceforge/kicad_plugin/__init__.py +12 -0
  102. traceforge/kicad_plugin/actions.py +92 -0
  103. traceforge/kicad_plugin/cli.py +66 -0
  104. traceforge/kicad_plugin/client.py +86 -0
  105. traceforge/kicad_plugin/context.py +257 -0
  106. traceforge/kicad_plugin/discovery.py +81 -0
  107. traceforge/kicad_plugin/install.py +203 -0
  108. traceforge/kicad_plugin/overlay.py +60 -0
  109. traceforge/kicad_plugin/payload/action_plugin.py +65 -0
  110. traceforge/kicad_plugin/payload/ipc_main.py +42 -0
  111. traceforge/kicad_plugin/payload/plugin.json +90 -0
  112. traceforge/kicad_plugin/payload/requirements.txt +1 -0
  113. traceforge/kicad_plugin/views.py +202 -0
  114. traceforge/langchain.py +57 -0
  115. traceforge/local.py +580 -0
  116. traceforge/mcp_server.py +304 -0
  117. traceforge/models.py +310 -0
  118. traceforge/next_steps.py +110 -0
  119. traceforge/parts/__init__.py +52 -0
  120. traceforge/parts/alternates.py +488 -0
  121. traceforge/parts/bom.py +423 -0
  122. traceforge/parts/brief.py +705 -0
  123. traceforge/parts/catalog.py +297 -0
  124. traceforge/parts/cli_sourcing.py +156 -0
  125. traceforge/parts/data/duty_rates.yaml +37 -0
  126. traceforge/parts/data/hs_codes.yaml +103 -0
  127. traceforge/parts/datasheet.py +278 -0
  128. traceforge/parts/fx.py +100 -0
  129. traceforge/parts/model.py +185 -0
  130. traceforge/parts/net.py +187 -0
  131. traceforge/parts/offers.py +46 -0
  132. traceforge/parts/packages.py +397 -0
  133. traceforge/parts/pinout.py +714 -0
  134. traceforge/parts/providers/__init__.py +17 -0
  135. traceforge/parts/providers/base.py +100 -0
  136. traceforge/parts/providers/jlc.py +364 -0
  137. traceforge/parts/providers/keyed.py +661 -0
  138. traceforge/parts/report.py +508 -0
  139. traceforge/parts/supply.py +330 -0
  140. traceforge/parts/verify.py +455 -0
  141. traceforge/parts/web.py +575 -0
  142. traceforge/plans.py +70 -0
  143. traceforge/preferences.py +127 -0
  144. traceforge/prices.py +130 -0
  145. traceforge/prices.yaml +28 -0
  146. traceforge/prompts/__init__.py +54 -0
  147. traceforge/prompts/system.md +103 -0
  148. traceforge/providers.py +764 -0
  149. traceforge/remote/__init__.py +33 -0
  150. traceforge/remote/client.py +422 -0
  151. traceforge/remote/oidc.py +240 -0
  152. traceforge/remote/orgs.py +510 -0
  153. traceforge/remote/server.py +690 -0
  154. traceforge/remote/store.py +100 -0
  155. traceforge/review_changes.py +187 -0
  156. traceforge/routing.py +99 -0
  157. traceforge/runtime.py +435 -0
  158. traceforge/sessions.py +324 -0
  159. traceforge/sexpr.py +279 -0
  160. traceforge/sim/__init__.py +17 -0
  161. traceforge/sim/acmath.py +234 -0
  162. traceforge/sim/circuit.py +499 -0
  163. traceforge/sim/cli.py +162 -0
  164. traceforge/sim/engine.py +172 -0
  165. traceforge/sim/ltspice.py +175 -0
  166. traceforge/sim/measure.py +123 -0
  167. traceforge/sim/models.py +76 -0
  168. traceforge/sim/project.py +218 -0
  169. traceforge/sim/rawfile.py +123 -0
  170. traceforge/sim/results.py +298 -0
  171. traceforge/sim/tune.py +172 -0
  172. traceforge/skill_commands.py +165 -0
  173. traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
  174. traceforge/skill_library/compliance-review/SKILL.md +51 -0
  175. traceforge/skill_library/design-review/SKILL.md +47 -0
  176. traceforge/skill_library/errata-hunt/SKILL.md +30 -0
  177. traceforge/skill_library/firmware/SKILL.md +26 -0
  178. traceforge/skill_library/power-budget/SKILL.md +27 -0
  179. traceforge/skill_library/release-package/SKILL.md +29 -0
  180. traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
  181. traceforge/skill_library/thermal-review/SKILL.md +15 -0
  182. traceforge/skills.py +131 -0
  183. traceforge/thermal.py +557 -0
  184. traceforge/tools/__init__.py +48 -0
  185. traceforge/tools/agent_tools.py +213 -0
  186. traceforge/tools/base.py +303 -0
  187. traceforge/tools/batch.py +155 -0
  188. traceforge/tools/connections.py +245 -0
  189. traceforge/tools/files.py +777 -0
  190. traceforge/tools/firmware_tools.py +218 -0
  191. traceforge/tools/kicad_tools.py +1072 -0
  192. traceforge/tools/models3d_tools.py +141 -0
  193. traceforge/tools/parts_tools.py +473 -0
  194. traceforge/tools/processes.py +246 -0
  195. traceforge/tools/review_tools.py +178 -0
  196. traceforge/tools/sim_tools.py +230 -0
  197. traceforge/tui.py +620 -0
  198. traceforge/updates.py +124 -0
  199. traceforge/validate/__init__.py +77 -0
  200. traceforge/validate/builtins.py +1091 -0
  201. traceforge/validate/circuits.py +1240 -0
  202. traceforge/validate/config.py +410 -0
  203. traceforge/validate/default.yaml +113 -0
  204. traceforge/validate/design.py +191 -0
  205. traceforge/validate/explain.py +112 -0
  206. traceforge/validate/grounding.py +169 -0
  207. traceforge/validate/ipc2221.py +350 -0
  208. traceforge/validate/multilayer.py +805 -0
  209. traceforge/validate/netmodel.py +261 -0
  210. traceforge/validate/partcheck.py +472 -0
  211. traceforge/validate/report.py +280 -0
  212. traceforge/validate/review.py +322 -0
  213. traceforge/validate/runner.py +662 -0
  214. traceforge/workspace.py +171 -0
  215. traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
  216. traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
  217. traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
  218. traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
  219. traceforge_pcb-1.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,48 @@
1
+ """Tools the agent can call."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from traceforge.altium.tools import ALTIUM_TOOLS
6
+ from traceforge.tools.agent_tools import NOTE_TOOL, SKILL_TOOL, TODO_TOOL
7
+ from traceforge.tools.base import Registry, Tool, ToolContext, ToolError, ToolKind, to_text
8
+ from traceforge.tools.connections import CONNECTIONS_TOOL
9
+ from traceforge.tools.files import FILE_TOOLS
10
+ from traceforge.tools.firmware_tools import FIRMWARE_TOOLS
11
+ from traceforge.tools.kicad_tools import KICAD_TOOLS, PLAN_TOOL
12
+ from traceforge.tools.models3d_tools import MODELS3D_TOOLS
13
+ from traceforge.tools.parts_tools import PART_TOOLS
14
+ from traceforge.tools.processes import PROCESS_TOOLS
15
+ from traceforge.tools.review_tools import REVIEW_TOOLS
16
+ from traceforge.tools.sim_tools import SIM_TOOLS
17
+
18
+
19
+ def default_registry() -> Registry:
20
+ return Registry(
21
+ [
22
+ *FILE_TOOLS,
23
+ *PROCESS_TOOLS,
24
+ *KICAD_TOOLS,
25
+ *MODELS3D_TOOLS,
26
+ CONNECTIONS_TOOL,
27
+ *ALTIUM_TOOLS,
28
+ *PART_TOOLS,
29
+ *SIM_TOOLS,
30
+ *REVIEW_TOOLS,
31
+ *FIRMWARE_TOOLS,
32
+ PLAN_TOOL,
33
+ TODO_TOOL,
34
+ NOTE_TOOL,
35
+ SKILL_TOOL,
36
+ ]
37
+ )
38
+
39
+
40
+ __all__ = [
41
+ "Registry",
42
+ "Tool",
43
+ "ToolContext",
44
+ "ToolError",
45
+ "ToolKind",
46
+ "default_registry",
47
+ "to_text",
48
+ ]
@@ -0,0 +1,213 @@
1
+ """Tools about the agent's own work: todo list, subagents, project notes, skills."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from collections.abc import Awaitable, Callable
7
+ from typing import Any
8
+
9
+ from traceforge.tools.base import Tool, ToolContext, ToolError, ToolKind
10
+
11
+ # ------------------------------------------------------------------------- todos
12
+
13
+ TODO_STATUSES = ("pending", "in_progress", "completed")
14
+ MAX_TODOS = 50
15
+
16
+
17
+ def write_todos(args: dict[str, Any], ctx: ToolContext) -> str:
18
+ todos = args["todos"]
19
+ if len(todos) > MAX_TODOS:
20
+ raise ToolError(f"at most {MAX_TODOS} items; merge small steps")
21
+ clean: list[dict[str, str]] = []
22
+ for index, item in enumerate(todos, start=1):
23
+ if not isinstance(item, dict) or not str(item.get("content") or "").strip():
24
+ raise ToolError(f"item {index}: needs content")
25
+ status = item.get("status") or "pending"
26
+ if status not in TODO_STATUSES:
27
+ raise ToolError(f"item {index}: status must be one of {', '.join(TODO_STATUSES)}")
28
+ clean.append({"content": str(item["content"]).strip()[:500], "status": status})
29
+ ctx.state["todos"] = clean
30
+ done = sum(1 for t in clean if t["status"] == "completed")
31
+ marks = {"pending": "[ ]", "in_progress": "[~]", "completed": "[x]"}
32
+ lines = [f"{marks[t['status']]} {t['content']}" for t in clean]
33
+ note = ""
34
+ if clean and done < len(clean) and not any(t["status"] == "in_progress" for t in clean):
35
+ note = "\nNote: nothing is marked in_progress; mark the step you are working on."
36
+ return f"todo list updated ({done}/{len(clean)} done)\n" + "\n".join(lines) + note
37
+
38
+
39
+ TODO_TOOL = Tool(
40
+ "write_todos",
41
+ "Keep a todo list for multi-step work (3 or more distinct steps, or several requests at "
42
+ "once); skip it for simple tasks. Send the whole list each time: it replaces the previous "
43
+ "one. Mark one step in_progress before you start it and completed as soon as it is done "
44
+ "and verified; never mark a step completed while its checks fail. Add steps you discover "
45
+ "and remove ones that no longer apply. The user sees the list as progress. The list is not "
46
+ "the answer: after the last update, still report the result in your reply.",
47
+ {
48
+ "type": "object",
49
+ "properties": {
50
+ "todos": {
51
+ "type": "array",
52
+ "items": {
53
+ "type": "object",
54
+ "properties": {
55
+ "content": {"type": "string", "description": "the step, imperative"},
56
+ "status": {"type": "string", "enum": list(TODO_STATUSES)},
57
+ },
58
+ "required": ["content", "status"],
59
+ },
60
+ }
61
+ },
62
+ "required": ["todos"],
63
+ },
64
+ write_todos,
65
+ ToolKind.READ,
66
+ schedule=lambda args: "exclusive",
67
+ )
68
+
69
+ # ------------------------------------------------------------------------ notes
70
+
71
+ NOTE_NAME = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
72
+ MAX_NOTE_CHARS = 20_000
73
+
74
+
75
+ def save_note(args: dict[str, Any], ctx: ToolContext) -> str:
76
+ name = str(args["name"]).strip().lower().removesuffix(".md")
77
+ if not NOTE_NAME.match(name):
78
+ raise ToolError("name: lowercase letters, digits, '-' and '_' only, e.g. design_summary")
79
+ content = str(args["content"]).strip()
80
+ path = ctx.resolve(f".traceforge/notes/{name}.md", for_write=True)
81
+ path.parent.mkdir(parents=True, exist_ok=True)
82
+ if args.get("append") and path.exists():
83
+ content = path.read_text(encoding="utf-8").rstrip() + "\n\n" + content
84
+ if len(content) > MAX_NOTE_CHARS:
85
+ raise ToolError(
86
+ f"note would be {len(content)} characters (max {MAX_NOTE_CHARS}); condense it"
87
+ )
88
+ path.write_text(content + "\n", encoding="utf-8")
89
+ return f"saved {ctx.display(path)} ({len(content)} chars)"
90
+
91
+
92
+ NOTE_TOOL = Tool(
93
+ "save_note",
94
+ "Save a project note in .traceforge/notes/<name>.md. Notes are loaded at the start of every "
95
+ "new session in this project, so use them for what a later session must know: keep "
96
+ "'design_summary' current after significant work (architecture, key parts and why, nets "
97
+ "and rails, board size and stackup, check results, open issues), and record decisions and "
98
+ "preferences the user stated. Do not store secrets or transient details. append=true adds "
99
+ "to the note instead of replacing it.",
100
+ {
101
+ "type": "object",
102
+ "properties": {
103
+ "name": {"type": "string", "description": "e.g. design_summary, decisions"},
104
+ "content": {"type": "string", "description": "Markdown"},
105
+ "append": {"type": "boolean"},
106
+ },
107
+ "required": ["name", "content"],
108
+ },
109
+ save_note,
110
+ ToolKind.WRITE,
111
+ "name",
112
+ )
113
+
114
+ # ------------------------------------------------------------------------ skills
115
+
116
+
117
+ def load_skill(args: dict[str, Any], ctx: ToolContext) -> str:
118
+ from traceforge.skills import discover
119
+
120
+ skills, _ = discover(ctx.workspace)
121
+ skill = skills.get(str(args["name"]).strip().lower())
122
+ if skill is None:
123
+ known = ", ".join(sorted(skills)) or "none"
124
+ raise ToolError(f"no skill named {args['name']!r} (available: {known})")
125
+ if args.get("file"):
126
+ target = (skill.folder / str(args["file"])).resolve()
127
+ if skill.folder.resolve() not in target.parents or not target.is_file():
128
+ raise ToolError(f"{args['file']!r} is not a file of skill {skill.name}")
129
+ text = target.read_text(encoding="utf-8", errors="replace")
130
+ return text[:40_000] + ("\n... [truncated]" if len(text) > 40_000 else "")
131
+ files = skill.files()
132
+ extra = (
133
+ "\n\nSupporting files (read with load_skill name=... file=...): " + ", ".join(files)
134
+ if files
135
+ else ""
136
+ )
137
+ return f"# Skill: {skill.name} ({skill.source})\n\n{skill.body()}{extra}"
138
+
139
+
140
+ SKILL_TOOL = Tool(
141
+ "load_skill",
142
+ "Load the full instructions of a skill listed in the system prompt (or one of its "
143
+ "supporting files with file=...). Load a skill when the task matches its description.",
144
+ {
145
+ "type": "object",
146
+ "properties": {
147
+ "name": {"type": "string"},
148
+ "file": {"type": "string", "description": "a supporting file of the skill"},
149
+ },
150
+ "required": ["name"],
151
+ },
152
+ load_skill,
153
+ )
154
+
155
+ # ---------------------------------------------------------------------- subagents
156
+
157
+ SUBAGENT_TYPES = {
158
+ "explore": "read-only: reads files, searches, runs KiCad queries and checks, and can write "
159
+ "only to the scratch folder. Cheap to run several at once. Use it for research and "
160
+ "checks that need many tool calls but return a short answer: verify each part against "
161
+ "its footprint and datasheet, audit one subsystem or net class, survey a large project, "
162
+ "find where something is defined.",
163
+ "general": "the same tools as you (it can change files, subject to the same approvals). "
164
+ "Runs one at a time. Use it for a self-contained piece of work whose intermediate steps "
165
+ "you do not need to see.",
166
+ }
167
+
168
+ SubagentRunner = Callable[[str, str, ToolContext], Awaitable[str]]
169
+
170
+
171
+ async def task(args: dict[str, Any], ctx: ToolContext) -> str:
172
+ runner: SubagentRunner | None = ctx.state.get("subagent_runner")
173
+ if runner is None:
174
+ raise ToolError("subagents are not available in this session")
175
+ kind = args.get("subagent_type") or "explore"
176
+ if kind not in SUBAGENT_TYPES:
177
+ raise ToolError(f"subagent_type must be one of {', '.join(SUBAGENT_TYPES)}")
178
+ description = str(args["description"]).strip()
179
+ if len(description) < 20:
180
+ raise ToolError("description is too short: give the subagent the full task and context")
181
+ return await runner(kind, description, ctx)
182
+
183
+
184
+ TASK_TOOL = Tool(
185
+ "task",
186
+ "Delegate a task to a subagent with its own, fresh context. It sees only the description "
187
+ "you give it (not this conversation), works with its tools until done, and returns one "
188
+ "final report; its intermediate tool calls never enter your context. Use it to keep long "
189
+ "investigations out of your context and to run independent checks in parallel: several "
190
+ "task calls in one response run concurrently (explore subagents). Put everything the "
191
+ "subagent needs in description: the goal, file paths, part references, what to check, and "
192
+ "the exact form of the report you want back. Its report is not shown to the user, so "
193
+ "relay what matters. Types:\n"
194
+ + "\n".join(f"- {name}: {text}" for name, text in SUBAGENT_TYPES.items()),
195
+ {
196
+ "type": "object",
197
+ "properties": {
198
+ "description": {
199
+ "type": "string",
200
+ "description": "the complete task, context and expected report format",
201
+ },
202
+ "subagent_type": {"type": "string", "enum": list(SUBAGENT_TYPES)},
203
+ },
204
+ "required": ["description", "subagent_type"],
205
+ "additionalProperties": False,
206
+ },
207
+ task,
208
+ ToolKind.READ,
209
+ schedule=lambda args: (
210
+ "read" if args.get("subagent_type", "explore") == "explore" else "exclusive"
211
+ ),
212
+ spill=False,
213
+ )
@@ -0,0 +1,303 @@
1
+ """Tool registry shared by the local agent, the hosted server and the MCP server."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import re
7
+ from collections.abc import Awaitable, Callable
8
+ from dataclasses import dataclass, field
9
+ from enum import StrEnum
10
+ from pathlib import Path
11
+ from typing import Any
12
+
13
+ # Tool results longer than this are written to a file in the scratch folder and the
14
+ # model gets a head/tail preview plus the path (it can page through it with read_file).
15
+ SPILL_CHARS = 30_000
16
+ SPILL_HEAD = 12_000
17
+ SPILL_TAIL = 4_000
18
+
19
+
20
+ class ToolKind(StrEnum):
21
+ READ = "read" # never changes anything
22
+ WRITE = "write" # changes files in the workspace
23
+ SHELL = "shell" # runs a command
24
+ INTERACTIVE = "interactive" # asks the user
25
+
26
+
27
+ class ToolError(Exception):
28
+ """Raised by a tool to return an error result to the model."""
29
+
30
+
31
+ QuestionHandler = Callable[[str, list[str]], Awaitable[str]]
32
+ Notifier = Callable[[str, Any], Awaitable[None] | None]
33
+
34
+
35
+ @dataclass
36
+ class ToolOutput:
37
+ """A tool result with more than text: images the model should see.
38
+
39
+ ``images`` holds ``{"media_type": "image/png", "data": <base64>}`` items. Results
40
+ of this type are never spilled to a file.
41
+ """
42
+
43
+ text: str
44
+ images: list[dict[str, str]] = field(default_factory=list)
45
+
46
+ def blocks(self) -> list[dict[str, Any]]:
47
+ blocks: list[dict[str, Any]] = [{"type": "text", "text": self.text}]
48
+ for image in self.images:
49
+ blocks.append(
50
+ {
51
+ "type": "image",
52
+ "source": {
53
+ "type": "base64",
54
+ "media_type": image["media_type"],
55
+ "data": image["data"],
56
+ },
57
+ }
58
+ )
59
+ return blocks
60
+
61
+
62
+ @dataclass
63
+ class ToolContext:
64
+ workspace: Path
65
+ ask_user: QuestionHandler | None = None
66
+ scratch: Path | None = None # writable even in read-only mode (reviews, renders)
67
+ read_only: bool = False
68
+ shell_timeout: float = 120.0
69
+ state: dict[str, Any] = field(default_factory=dict)
70
+ # Progress events from inside a tool (subagent status, background processes).
71
+ notify: Notifier | None = None
72
+
73
+ def __post_init__(self) -> None:
74
+ self.workspace = Path(self.workspace).resolve()
75
+ if self.scratch is None:
76
+ self.scratch = self.workspace / ".traceforge" / "scratch"
77
+
78
+ def resolve(
79
+ self, raw: str | None, *, must_exist: bool = False, for_write: bool = False
80
+ ) -> Path:
81
+ """Resolve a model-supplied path and keep it inside the workspace."""
82
+ if raw is None or str(raw).strip() == "":
83
+ raw = "."
84
+ candidate = Path(str(raw)).expanduser()
85
+ if not candidate.is_absolute():
86
+ candidate = self.workspace / candidate
87
+ resolved = candidate.resolve()
88
+ scratch = self.scratch.resolve() if self.scratch else None
89
+ inside = resolved == self.workspace or self.workspace in resolved.parents
90
+ in_scratch = scratch is not None and (resolved == scratch or scratch in resolved.parents)
91
+ if not (inside or in_scratch):
92
+ raise ToolError(f"path {raw!r} is outside the workspace {self.workspace}")
93
+ if _is_sensitive(resolved):
94
+ raise ToolError(f"access to {raw!r} is not allowed (credentials or secrets)")
95
+ if for_write and self.read_only and not in_scratch:
96
+ raise ToolError("this session is read-only; only the scratch folder is writable")
97
+ if must_exist and not resolved.exists():
98
+ raise ToolError(f"{raw!r} does not exist")
99
+ return resolved
100
+
101
+ def display(self, path: Path) -> str:
102
+ try:
103
+ return path.relative_to(self.workspace).as_posix() or "."
104
+ except ValueError:
105
+ return str(path)
106
+
107
+
108
+ _SENSITIVE_NAMES = {".env", ".netrc", ".pypirc", "id_rsa", "id_ed25519", "credentials", ".npmrc"}
109
+ _SENSITIVE_PARTS = {".ssh", ".aws", ".gnupg", ".git/config"}
110
+
111
+
112
+ def _is_sensitive(path: Path) -> bool:
113
+ name = path.name.lower()
114
+ if name in _SENSITIVE_NAMES or name.startswith(".env.") or name.endswith((".pem", ".key")):
115
+ return True
116
+ text = path.as_posix().lower()
117
+ return any(f"/{part}" in text for part in _SENSITIVE_PARTS)
118
+
119
+
120
+ Handler = Callable[[dict[str, Any], ToolContext], Awaitable[Any] | Any]
121
+
122
+
123
+ @dataclass
124
+ class Tool:
125
+ name: str
126
+ description: str
127
+ input_schema: dict[str, Any]
128
+ handler: Handler
129
+ kind: ToolKind = ToolKind.READ
130
+ # Shown to the user in approval prompts: which argument holds the target.
131
+ target_arg: str | None = None
132
+ # False for tools whose output is already bounded and paged (read_file): spilling
133
+ # their output to a file the model would then read again does not help.
134
+ spill: bool = True
135
+ # Optional scheduling override: returns "read", "write" or "exclusive" for a call
136
+ # (see tools/batch.py). By default it follows ``kind``.
137
+ schedule: Callable[[dict[str, Any]], str] | None = None
138
+
139
+ def definition(self, *, eager: bool = False) -> dict[str, Any]:
140
+ definition = {
141
+ "name": self.name,
142
+ "description": self.description,
143
+ "input_schema": self.input_schema,
144
+ }
145
+ if eager:
146
+ definition["eager_input_streaming"] = True
147
+ return definition
148
+
149
+ async def call(self, arguments: dict[str, Any], context: ToolContext) -> Any:
150
+ problems = validate_arguments(self.input_schema, arguments)
151
+ if problems:
152
+ raise ToolError("invalid arguments: " + "; ".join(problems))
153
+ result = self.handler(arguments, context)
154
+ if hasattr(result, "__await__"):
155
+ result = await result # type: ignore[assignment]
156
+ return result
157
+
158
+
159
+ class Registry:
160
+ def __init__(self, tools: list[Tool] | None = None):
161
+ self._tools: dict[str, Tool] = {}
162
+ for tool in tools or []:
163
+ self.add(tool)
164
+
165
+ def add(self, tool: Tool) -> None:
166
+ if tool.name in self._tools:
167
+ raise ValueError(f"duplicate tool {tool.name}")
168
+ self._tools[tool.name] = tool
169
+
170
+ def get(self, name: str) -> Tool | None:
171
+ return self._tools.get(name)
172
+
173
+ def names(self) -> list[str]:
174
+ return list(self._tools)
175
+
176
+ def subset(self, kinds: set[ToolKind] | None = None, names: set[str] | None = None) -> Registry:
177
+ selected = [
178
+ t
179
+ for t in self._tools.values()
180
+ if (kinds is None or t.kind in kinds) and (names is None or t.name in names)
181
+ ]
182
+ return Registry(selected)
183
+
184
+ def definitions(self, *, eager: bool = False) -> list[dict[str, Any]]:
185
+ # Deterministic order keeps the prompt-cache prefix stable.
186
+ return [self._tools[name].definition(eager=eager) for name in sorted(self._tools)]
187
+
188
+
189
+ _TYPES = {
190
+ "string": str,
191
+ "integer": int,
192
+ "number": (int, float),
193
+ "boolean": bool,
194
+ "object": dict,
195
+ "array": list,
196
+ }
197
+
198
+
199
+ def validate_arguments(schema: dict[str, Any], arguments: Any) -> list[str]:
200
+ """Minimal JSON-schema check: required keys, primitive types, enums, item types.
201
+
202
+ Model output is untrusted; with eager input streaming the API does not
203
+ validate tool inputs, so every call is checked before it runs.
204
+ """
205
+ if not isinstance(arguments, dict):
206
+ return ["arguments must be an object"]
207
+ problems: list[str] = []
208
+ properties = schema.get("properties", {})
209
+ for key in schema.get("required", []):
210
+ if key not in arguments:
211
+ problems.append(f"missing required '{key}'")
212
+ for key, val in arguments.items():
213
+ spec = properties.get(key)
214
+ if spec is None:
215
+ if schema.get("additionalProperties") is False:
216
+ problems.append(f"unknown argument '{key}'")
217
+ continue
218
+ problems.extend(_check(spec, val, key))
219
+ return problems
220
+
221
+
222
+ def _check(spec: dict[str, Any], val: Any, key: str) -> list[str]:
223
+ expected = spec.get("type")
224
+ if expected:
225
+ kinds = expected if isinstance(expected, list) else [expected]
226
+ if val is None and "null" in kinds:
227
+ return []
228
+ python_types = tuple(
229
+ t
230
+ for k in kinds
231
+ if k in _TYPES
232
+ for t in (_TYPES[k] if isinstance(_TYPES[k], tuple) else (_TYPES[k],))
233
+ )
234
+ if python_types and (
235
+ not isinstance(val, python_types)
236
+ or (isinstance(val, bool) and bool not in python_types)
237
+ ):
238
+ return [f"'{key}' must be {'/'.join(kinds)}"]
239
+ if "enum" in spec and val not in spec["enum"]:
240
+ return [f"'{key}' must be one of {spec['enum']}"]
241
+ if isinstance(val, list) and "items" in spec:
242
+ problems = []
243
+ for index, item in enumerate(val[:1000]):
244
+ problems.extend(_check(spec["items"], item, f"{key}[{index}]"))
245
+ return problems[:5]
246
+ return []
247
+
248
+
249
+ def render(result: Any) -> str:
250
+ if isinstance(result, str):
251
+ return result
252
+ return json.dumps(result, indent=1, default=str, ensure_ascii=False)
253
+
254
+
255
+ _SAFE_ID = re.compile(r"[^A-Za-z0-9_.-]")
256
+
257
+
258
+ def spill(
259
+ text: str,
260
+ context: ToolContext,
261
+ tool_name: str,
262
+ tool_use_id: str,
263
+ *,
264
+ limit: int = SPILL_CHARS,
265
+ ) -> str:
266
+ """Bound a tool result: past ``limit`` characters, save it and return a preview."""
267
+ if len(text) <= limit:
268
+ return text
269
+ assert context.scratch is not None
270
+ folder = context.scratch / "tool-output"
271
+ name = _SAFE_ID.sub("_", f"{tool_name}-{tool_use_id}")[:120] + ".txt"
272
+ try:
273
+ folder.mkdir(parents=True, exist_ok=True)
274
+ (folder / name).write_text(text, encoding="utf-8")
275
+ where = context.display(folder / name)
276
+ except OSError:
277
+ where = None
278
+ head = text[:SPILL_HEAD]
279
+ tail = text[-SPILL_TAIL:]
280
+ omitted = len(text) - len(head) - len(tail)
281
+ lines = text.count("\n") + 1
282
+ note = (
283
+ f"[{tool_name} returned {len(text)} characters ({lines} lines); showing the first "
284
+ f"{len(head)} and the last {len(tail)}. "
285
+ + (
286
+ f"The full output is saved at {where}: page through it with read_file "
287
+ "(offset/limit) or search it with grep instead of re-running the tool.]"
288
+ if where
289
+ else "Narrow the request to see the rest.]"
290
+ )
291
+ )
292
+ return f"{note}\n{head}\n... [{omitted} characters omitted] ...\n{tail}"
293
+
294
+
295
+ def to_text(result: Any, limit: int = 60_000) -> str:
296
+ """Render a tool result for the model, bounded in size."""
297
+ if isinstance(result, ToolOutput):
298
+ result = result.text
299
+ text = render(result)
300
+ if len(text) > limit:
301
+ omitted = len(text) - limit
302
+ text = text[:limit] + f"\n... [truncated {omitted} characters; narrow the request]"
303
+ return text