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.
- traceforge/__init__.py +3 -0
- traceforge/__main__.py +3 -0
- traceforge/acp_server.py +570 -0
- traceforge/agent.py +680 -0
- traceforge/altium/__init__.py +6 -0
- traceforge/altium/cfb.py +70 -0
- traceforge/altium/cli.py +60 -0
- traceforge/altium/model.py +163 -0
- traceforge/altium/outputs.py +24 -0
- traceforge/altium/pcb.py +301 -0
- traceforge/altium/project.py +328 -0
- traceforge/altium/schematic.py +400 -0
- traceforge/altium/tools.py +166 -0
- traceforge/approval.py +219 -0
- traceforge/attachments.py +346 -0
- traceforge/background.py +253 -0
- traceforge/bench/__init__.py +5 -0
- traceforge/bench/adapters.py +337 -0
- traceforge/bench/checks.py +410 -0
- traceforge/bench/cli.py +121 -0
- traceforge/bench/design.py +439 -0
- traceforge/bench/kicad.py +99 -0
- traceforge/bench/partscheck.py +159 -0
- traceforge/bench/review.py +100 -0
- traceforge/bench/runner.py +226 -0
- traceforge/bench/score.py +204 -0
- traceforge/bench/tasks.py +102 -0
- traceforge/chat.py +1185 -0
- traceforge/checks.py +328 -0
- traceforge/checks_sides.py +118 -0
- traceforge/cli.py +2224 -0
- traceforge/clipboard.py +107 -0
- traceforge/config.py +299 -0
- traceforge/context.py +276 -0
- traceforge/design/__init__.py +1 -0
- traceforge/design/constraints.py +397 -0
- traceforge/design/generate.py +1789 -0
- traceforge/design/outline.py +905 -0
- traceforge/design/schematic_layout.py +932 -0
- traceforge/design/schematic_lint.py +329 -0
- traceforge/design/schematic_route.py +207 -0
- traceforge/design/sheets.py +854 -0
- traceforge/design/sides.py +328 -0
- traceforge/design/spec.py +462 -0
- traceforge/design/specsheet.py +2351 -0
- traceforge/design/specsheet_render.py +183 -0
- traceforge/desktop/__init__.py +109 -0
- traceforge/desktop/keys.py +90 -0
- traceforge/desktop/project.py +443 -0
- traceforge/desktop/review.py +20 -0
- traceforge/desktop/server.py +1277 -0
- traceforge/desktop/static/app.css +223 -0
- traceforge/desktop/static/app.js +683 -0
- traceforge/desktop/static/highlight.js +77 -0
- traceforge/desktop/static/index.html +89 -0
- traceforge/desktop/static/md.js +90 -0
- traceforge/desktop/static/viewer.js +213 -0
- traceforge/desktop/symbols.py +212 -0
- traceforge/desktop/update.py +65 -0
- traceforge/diagnostics.py +67 -0
- traceforge/errata.py +219 -0
- traceforge/fab.py +108 -0
- traceforge/fab_layers.py +44 -0
- traceforge/features/__init__.py +6 -0
- traceforge/features/candidates.py +117 -0
- traceforge/features/cli.py +200 -0
- traceforge/features/package.py +433 -0
- traceforge/features/revdiff.py +224 -0
- traceforge/features/sarif.py +145 -0
- traceforge/features/viewer.py +265 -0
- traceforge/firmware/__init__.py +3 -0
- traceforge/firmware/cli.py +174 -0
- traceforge/firmware/drivers.py +372 -0
- traceforge/firmware/drivers_data.py +256 -0
- traceforge/firmware/mcus.py +177 -0
- traceforge/firmware/netlist.py +55 -0
- traceforge/firmware/pinmap.py +296 -0
- traceforge/firmware/scaffold.py +466 -0
- traceforge/firmware/toolchain.py +262 -0
- traceforge/hooks.py +237 -0
- traceforge/kicad/__init__.py +0 -0
- traceforge/kicad/cli.py +519 -0
- traceforge/kicad/diffpair.py +174 -0
- traceforge/kicad/edgegeom.py +191 -0
- traceforge/kicad/edit.py +405 -0
- traceforge/kicad/escape.py +1410 -0
- traceforge/kicad/formats.py +1073 -0
- traceforge/kicad/impedance.py +320 -0
- traceforge/kicad/install.py +75 -0
- traceforge/kicad/libraries.py +490 -0
- traceforge/kicad/models3d.py +942 -0
- traceforge/kicad/outputs.py +81 -0
- traceforge/kicad/pcb.py +787 -0
- traceforge/kicad/planes.py +1242 -0
- traceforge/kicad/project.py +136 -0
- traceforge/kicad/route.py +2698 -0
- traceforge/kicad/routegeom.py +164 -0
- traceforge/kicad/schematic.py +268 -0
- traceforge/kicad/sides.py +34 -0
- traceforge/kicad/stackup.py +424 -0
- traceforge/kicad_plugin/__init__.py +12 -0
- traceforge/kicad_plugin/actions.py +92 -0
- traceforge/kicad_plugin/cli.py +66 -0
- traceforge/kicad_plugin/client.py +86 -0
- traceforge/kicad_plugin/context.py +257 -0
- traceforge/kicad_plugin/discovery.py +81 -0
- traceforge/kicad_plugin/install.py +203 -0
- traceforge/kicad_plugin/overlay.py +60 -0
- traceforge/kicad_plugin/payload/action_plugin.py +65 -0
- traceforge/kicad_plugin/payload/ipc_main.py +42 -0
- traceforge/kicad_plugin/payload/plugin.json +90 -0
- traceforge/kicad_plugin/payload/requirements.txt +1 -0
- traceforge/kicad_plugin/views.py +202 -0
- traceforge/langchain.py +57 -0
- traceforge/local.py +580 -0
- traceforge/mcp_server.py +304 -0
- traceforge/models.py +310 -0
- traceforge/next_steps.py +110 -0
- traceforge/parts/__init__.py +52 -0
- traceforge/parts/alternates.py +488 -0
- traceforge/parts/bom.py +423 -0
- traceforge/parts/brief.py +705 -0
- traceforge/parts/catalog.py +297 -0
- traceforge/parts/cli_sourcing.py +156 -0
- traceforge/parts/data/duty_rates.yaml +37 -0
- traceforge/parts/data/hs_codes.yaml +103 -0
- traceforge/parts/datasheet.py +278 -0
- traceforge/parts/fx.py +100 -0
- traceforge/parts/model.py +185 -0
- traceforge/parts/net.py +187 -0
- traceforge/parts/offers.py +46 -0
- traceforge/parts/packages.py +397 -0
- traceforge/parts/pinout.py +714 -0
- traceforge/parts/providers/__init__.py +17 -0
- traceforge/parts/providers/base.py +100 -0
- traceforge/parts/providers/jlc.py +364 -0
- traceforge/parts/providers/keyed.py +661 -0
- traceforge/parts/report.py +508 -0
- traceforge/parts/supply.py +330 -0
- traceforge/parts/verify.py +455 -0
- traceforge/parts/web.py +575 -0
- traceforge/plans.py +70 -0
- traceforge/preferences.py +127 -0
- traceforge/prices.py +130 -0
- traceforge/prices.yaml +28 -0
- traceforge/prompts/__init__.py +54 -0
- traceforge/prompts/system.md +103 -0
- traceforge/providers.py +764 -0
- traceforge/remote/__init__.py +33 -0
- traceforge/remote/client.py +422 -0
- traceforge/remote/oidc.py +240 -0
- traceforge/remote/orgs.py +510 -0
- traceforge/remote/server.py +690 -0
- traceforge/remote/store.py +100 -0
- traceforge/review_changes.py +187 -0
- traceforge/routing.py +99 -0
- traceforge/runtime.py +435 -0
- traceforge/sessions.py +324 -0
- traceforge/sexpr.py +279 -0
- traceforge/sim/__init__.py +17 -0
- traceforge/sim/acmath.py +234 -0
- traceforge/sim/circuit.py +499 -0
- traceforge/sim/cli.py +162 -0
- traceforge/sim/engine.py +172 -0
- traceforge/sim/ltspice.py +175 -0
- traceforge/sim/measure.py +123 -0
- traceforge/sim/models.py +76 -0
- traceforge/sim/project.py +218 -0
- traceforge/sim/rawfile.py +123 -0
- traceforge/sim/results.py +298 -0
- traceforge/sim/tune.py +172 -0
- traceforge/skill_commands.py +165 -0
- traceforge/skill_library/circuit-simulation/SKILL.md +30 -0
- traceforge/skill_library/compliance-review/SKILL.md +51 -0
- traceforge/skill_library/design-review/SKILL.md +47 -0
- traceforge/skill_library/errata-hunt/SKILL.md +30 -0
- traceforge/skill_library/firmware/SKILL.md +26 -0
- traceforge/skill_library/power-budget/SKILL.md +27 -0
- traceforge/skill_library/release-package/SKILL.md +29 -0
- traceforge/skill_library/sourcing-brief/SKILL.md +24 -0
- traceforge/skill_library/thermal-review/SKILL.md +15 -0
- traceforge/skills.py +131 -0
- traceforge/thermal.py +557 -0
- traceforge/tools/__init__.py +48 -0
- traceforge/tools/agent_tools.py +213 -0
- traceforge/tools/base.py +303 -0
- traceforge/tools/batch.py +155 -0
- traceforge/tools/connections.py +245 -0
- traceforge/tools/files.py +777 -0
- traceforge/tools/firmware_tools.py +218 -0
- traceforge/tools/kicad_tools.py +1072 -0
- traceforge/tools/models3d_tools.py +141 -0
- traceforge/tools/parts_tools.py +473 -0
- traceforge/tools/processes.py +246 -0
- traceforge/tools/review_tools.py +178 -0
- traceforge/tools/sim_tools.py +230 -0
- traceforge/tui.py +620 -0
- traceforge/updates.py +124 -0
- traceforge/validate/__init__.py +77 -0
- traceforge/validate/builtins.py +1091 -0
- traceforge/validate/circuits.py +1240 -0
- traceforge/validate/config.py +410 -0
- traceforge/validate/default.yaml +113 -0
- traceforge/validate/design.py +191 -0
- traceforge/validate/explain.py +112 -0
- traceforge/validate/grounding.py +169 -0
- traceforge/validate/ipc2221.py +350 -0
- traceforge/validate/multilayer.py +805 -0
- traceforge/validate/netmodel.py +261 -0
- traceforge/validate/partcheck.py +472 -0
- traceforge/validate/report.py +280 -0
- traceforge/validate/review.py +322 -0
- traceforge/validate/runner.py +662 -0
- traceforge/workspace.py +171 -0
- traceforge_pcb-1.0.0.dist-info/METADATA +463 -0
- traceforge_pcb-1.0.0.dist-info/RECORD +219 -0
- traceforge_pcb-1.0.0.dist-info/WHEEL +4 -0
- traceforge_pcb-1.0.0.dist-info/entry_points.txt +2 -0
- 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
|
+
)
|
traceforge/tools/base.py
ADDED
|
@@ -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
|