pytest-copilot 2.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 (55) hide show
  1. pytest_copilot/__init__.py +133 -0
  2. pytest_copilot/copilot/__init__.py +47 -0
  3. pytest_copilot/copilot/_command_job.py +109 -0
  4. pytest_copilot/copilot/api.py +12 -0
  5. pytest_copilot/copilot/client.py +58 -0
  6. pytest_copilot/copilot/commands.py +265 -0
  7. pytest_copilot/copilot/config.py +133 -0
  8. pytest_copilot/copilot/contracts.py +222 -0
  9. pytest_copilot/copilot/controls.py +230 -0
  10. pytest_copilot/copilot/events.py +795 -0
  11. pytest_copilot/copilot/fixtures.py +289 -0
  12. pytest_copilot/copilot/personas.py +607 -0
  13. pytest_copilot/copilot/requests.py +350 -0
  14. pytest_copilot/copilot/result.py +309 -0
  15. pytest_copilot/copilot/runner.py +266 -0
  16. pytest_copilot/copilot/skills.py +104 -0
  17. pytest_copilot/copilot/task.py +546 -0
  18. pytest_copilot/core/__init__.py +77 -0
  19. pytest_copilot/core/errors.py +44 -0
  20. pytest_copilot/core/evals.py +521 -0
  21. pytest_copilot/core/plugin.py +403 -0
  22. pytest_copilot/core/prompt.py +167 -0
  23. pytest_copilot/core/result.py +543 -0
  24. pytest_copilot/core/serialization.py +128 -0
  25. pytest_copilot/core/skill.py +406 -0
  26. pytest_copilot/core/skill_evals.py +148 -0
  27. pytest_copilot/core/skill_grading.py +78 -0
  28. pytest_copilot/core/validation.py +83 -0
  29. pytest_copilot/execution/__init__.py +15 -0
  30. pytest_copilot/execution/cost.py +159 -0
  31. pytest_copilot/execution/rate_limiter.py +177 -0
  32. pytest_copilot/execution/servers.py +442 -0
  33. pytest_copilot/execution/skill_tools.py +228 -0
  34. pytest_copilot/fixtures/__init__.py +18 -0
  35. pytest_copilot/fixtures/factories.py +44 -0
  36. pytest_copilot/fixtures/iteration.py +16 -0
  37. pytest_copilot/onboarding.py +413 -0
  38. pytest_copilot/plugin.py +562 -0
  39. pytest_copilot/plugin_options.py +32 -0
  40. pytest_copilot/plugin_report.py +18 -0
  41. pytest_copilot/reporting/__init__.py +16 -0
  42. pytest_copilot/reporting/collector.py +203 -0
  43. pytest_copilot/reporting/generator.py +55 -0
  44. pytest_copilot/reporting/schema.py +5 -0
  45. pytest_copilot/testing/__init__.py +17 -0
  46. pytest_copilot/testing/banking.py +479 -0
  47. pytest_copilot/testing/banking_mcp.py +167 -0
  48. pytest_copilot/testing/todo.py +380 -0
  49. pytest_copilot/testing/todo_mcp.py +156 -0
  50. pytest_copilot/testing/types.py +31 -0
  51. pytest_copilot-2.0.0.dist-info/METADATA +177 -0
  52. pytest_copilot-2.0.0.dist-info/RECORD +55 -0
  53. pytest_copilot-2.0.0.dist-info/WHEEL +4 -0
  54. pytest_copilot-2.0.0.dist-info/entry_points.txt +5 -0
  55. pytest_copilot-2.0.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,607 @@
1
+ """IDE Personas for pytest-copilot Copilot support.
2
+
3
+ A ``Persona`` defines the runtime environment in which an agent under test
4
+ is expected to run. Each persona ensures the agent has the correct tool set
5
+ for its target IDE by injecting polyfill tools and adding a system-message
6
+ fragment that sets context.
7
+
8
+ Built-in personas
9
+ -----------------
10
+ ``VSCodePersona`` (default)
11
+ Simulates the VS Code Copilot extension. Polyfills ``runSubagent`` so
12
+ that agents written for VS Code dispatch sub-agents correctly.
13
+
14
+ ``ClaudeCodePersona``
15
+ Simulates Claude Code. Polyfills a ``task``-dispatch tool (same
16
+ mechanism as ``runSubagent``, named ``task`` to match Claude Code's
17
+ native API).
18
+
19
+ ``CopilotCLIPersona``
20
+ Simulates the GitHub Copilot terminal agent. No polyfills are needed —
21
+ ``task`` and ``skill`` are already in the SDK's native 16-tool set.
22
+ Adds a system-message fragment so the model knows its environment.
23
+
24
+ ``HeadlessPersona``
25
+ Raw SDK headless mode — no polyfills, no extra system message. Use
26
+ when you want to test exactly what the SDK exposes with no IDE context.
27
+
28
+ Usage::
29
+
30
+ from pytest_copilot.copilot import CopilotTask, VSCodePersona, ClaudeCodePersona
31
+
32
+ # Explicit — recommended for clarity
33
+ agent = CopilotTask(persona=VSCodePersona(), custom_agents=[...])
34
+
35
+ # Default — VSCodePersona is used automatically
36
+ agent = CopilotTask(custom_agents=[...])
37
+
38
+ # Headless — no IDE context, no polyfills
39
+ agent = CopilotTask(persona=HeadlessPersona())
40
+ """
41
+
42
+ from __future__ import annotations
43
+
44
+ from pathlib import Path
45
+ from typing import TYPE_CHECKING, Any
46
+
47
+ from pytest_copilot.copilot.contracts import (
48
+ CopilotCustomAgentConfig,
49
+ CopilotEventMapper,
50
+ CopilotNestedRunner,
51
+ CopilotTaskConfig,
52
+ declared_agent_tools,
53
+ merge_agent_mcp_servers,
54
+ require_custom_agent_name,
55
+ require_custom_agent_prompt,
56
+ require_mapping,
57
+ resolve_agent_reasoning_effort,
58
+ )
59
+
60
+ if TYPE_CHECKING:
61
+ from copilot.tools import Tool, ToolInvocation, ToolResult
62
+
63
+
64
+ # ---------------------------------------------------------------------------
65
+ # Base class
66
+ # ---------------------------------------------------------------------------
67
+
68
+
69
+ class Persona:
70
+ """Base class for IDE runtime personas.
71
+
72
+ Override ``apply()`` to inject polyfill tools and system-message
73
+ additions that match your target IDE's native tool set.
74
+
75
+ The ``apply()`` method is called by the runner *after*
76
+ ``agent.build_session_config()`` and *before* the session is created,
77
+ so modifications to ``session_config`` take effect immediately.
78
+
79
+ Phase-2 extension point: override ``create_client()`` to swap the
80
+ underlying SDK backend (e.g. Anthropic SDK for Claude Code).
81
+ """
82
+
83
+ def apply(
84
+ self,
85
+ agent: CopilotTaskConfig,
86
+ session_config: dict[str, Any],
87
+ mapper: CopilotEventMapper,
88
+ nested_runner: CopilotNestedRunner,
89
+ ) -> None:
90
+ """Modify *session_config* in-place to match this persona's environment.
91
+
92
+ Args:
93
+ agent: The ``CopilotTask`` being executed (read-only).
94
+ session_config: The session config dict built from ``agent``.
95
+ Mutate this to inject tools, update system_message, etc.
96
+ mapper: The ``EventMapper`` for the current run. Pass to
97
+ tool handlers that need to record subagent events.
98
+ """
99
+
100
+ def __repr__(self) -> str:
101
+ return f"{self.__class__.__name__}()"
102
+
103
+
104
+ # ---------------------------------------------------------------------------
105
+ # Headless (raw SDK baseline)
106
+ # ---------------------------------------------------------------------------
107
+
108
+
109
+ class HeadlessPersona(Persona):
110
+ """Raw SDK headless mode — no polyfills, no IDE system message.
111
+
112
+ Use this when you want to test exactly what the Copilot SDK exposes
113
+ with no runtime context added. This is the minimal baseline.
114
+ """
115
+
116
+
117
+ # ---------------------------------------------------------------------------
118
+ # GitHub Copilot CLI
119
+ # ---------------------------------------------------------------------------
120
+
121
+
122
+ class CopilotCLIPersona(Persona):
123
+ """GitHub Copilot terminal agent persona.
124
+
125
+ ``task`` and ``skill`` are already in the SDK's native 16-tool set, so
126
+ no polyfills are needed. This persona only adds a system-message
127
+ fragment so the model knows it is running inside the Copilot CLI and
128
+ can use ``task`` for sub-task dispatch.
129
+ """
130
+
131
+ _SYSTEM_MSG = "You are running inside GitHub Copilot CLI."
132
+ _INSTRUCTIONS_FILE = Path(".github") / "copilot-instructions.md"
133
+
134
+ def apply(
135
+ self,
136
+ agent: CopilotTaskConfig,
137
+ session_config: dict[str, Any],
138
+ mapper: CopilotEventMapper,
139
+ nested_runner: CopilotNestedRunner,
140
+ ) -> None:
141
+ _prepend_system_message(session_config, self._SYSTEM_MSG)
142
+ if agent.working_directory:
143
+ custom = _load_custom_instructions_file(
144
+ Path(agent.working_directory) / self._INSTRUCTIONS_FILE
145
+ )
146
+ if custom:
147
+ _prepend_system_message(session_config, custom)
148
+ _inject_skill_reference_tools(agent, session_config)
149
+
150
+
151
+ # ---------------------------------------------------------------------------
152
+ # VS Code
153
+ # ---------------------------------------------------------------------------
154
+
155
+
156
+ class VSCodePersona(Persona):
157
+ """VS Code Copilot extension persona.
158
+
159
+ Polyfills ``runSubagent`` so agents written for VS Code (where
160
+ ``runSubagent`` is a native tool) can dispatch custom sub-agents
161
+ correctly during testing.
162
+
163
+ The polyfill is only injected when ``agent.custom_agents`` is non-empty,
164
+ so using this persona with a plain agent has no side-effects.
165
+ """
166
+
167
+ _SYSTEM_MSG = "You are running inside VS Code."
168
+ _INSTRUCTIONS_FILE = Path(".github") / "copilot-instructions.md"
169
+
170
+ def apply(
171
+ self,
172
+ agent: CopilotTaskConfig,
173
+ session_config: dict[str, Any],
174
+ mapper: CopilotEventMapper,
175
+ nested_runner: CopilotNestedRunner,
176
+ ) -> None:
177
+ _prepend_system_message(session_config, self._SYSTEM_MSG)
178
+ if agent.working_directory:
179
+ custom = _load_custom_instructions_file(
180
+ Path(agent.working_directory) / self._INSTRUCTIONS_FILE
181
+ )
182
+ if custom:
183
+ _prepend_system_message(session_config, custom)
184
+ if agent.custom_agents:
185
+ tool = _make_runsubagent_tool(
186
+ agent,
187
+ agent.custom_agents,
188
+ mapper,
189
+ nested_runner,
190
+ )
191
+ _inject_tool(session_config, tool)
192
+ agents_block = _build_agents_block(agent.custom_agents, tool_name="runSubagent")
193
+ _prepend_system_message(session_config, agents_block)
194
+ _inject_skill_reference_tools(agent, session_config)
195
+
196
+
197
+ # ---------------------------------------------------------------------------
198
+ # Claude Code
199
+ # ---------------------------------------------------------------------------
200
+
201
+
202
+ class ClaudeCodePersona(Persona):
203
+ """Claude Code persona.
204
+
205
+ Current Copilot SDK releases already expose the native ``task`` tool, so
206
+ this persona only adds Claude-specific runtime context and the agent list
207
+ block that teaches the model which custom agents are available.
208
+ """
209
+
210
+ _SYSTEM_MSG = "You are running inside Claude Code."
211
+ _INSTRUCTIONS_FILE = Path("CLAUDE.md")
212
+
213
+ def apply(
214
+ self,
215
+ agent: CopilotTaskConfig,
216
+ session_config: dict[str, Any],
217
+ mapper: CopilotEventMapper,
218
+ nested_runner: CopilotNestedRunner,
219
+ ) -> None:
220
+ _prepend_system_message(session_config, self._SYSTEM_MSG)
221
+ if agent.working_directory:
222
+ custom = _load_custom_instructions_file(
223
+ Path(agent.working_directory) / self._INSTRUCTIONS_FILE
224
+ )
225
+ if custom:
226
+ _prepend_system_message(session_config, custom)
227
+ if agent.custom_agents:
228
+ agents_block = _build_agents_block(agent.custom_agents, tool_name="task")
229
+ _prepend_system_message(session_config, agents_block)
230
+ _inject_skill_reference_tools(agent, session_config)
231
+
232
+
233
+ # ---------------------------------------------------------------------------
234
+ # Helpers
235
+ # ---------------------------------------------------------------------------
236
+
237
+
238
+ def _load_custom_instructions_file(file_path: Path) -> str | None:
239
+ """Read a custom instructions file and return its content, or None if absent."""
240
+ if file_path.exists():
241
+ content = file_path.read_text(encoding="utf-8").strip()
242
+ return content or None
243
+ return None
244
+
245
+
246
+ def _prepend_system_message(session_config: dict[str, Any], message: str) -> None:
247
+ """Prepend *message* to the system_message in *session_config*.
248
+
249
+ If no system_message is set, creates one in "append" mode so it is
250
+ added to the CLI's built-in system message rather than replacing it.
251
+ """
252
+ existing = session_config.get("system_message") or {}
253
+ existing_content: str = existing.get("content") or ""
254
+ mode: str = existing.get("mode") or "append"
255
+ combined = f"{message}\n\n{existing_content}".strip()
256
+ session_config["system_message"] = {"mode": mode, "content": combined}
257
+
258
+
259
+ def _inject_tool(session_config: dict[str, Any], tool: "Tool") -> None:
260
+ """Append *tool* to the tools list in *session_config*."""
261
+ existing: list[Any] = list(session_config.get("tools") or [])
262
+ session_config["tools"] = existing + [tool]
263
+
264
+
265
+ def _build_agents_block(
266
+ custom_agents: list[CopilotCustomAgentConfig],
267
+ tool_name: str = "runSubagent",
268
+ ) -> str:
269
+ """Build the <agents> XML block that VS Code injects into the system prompt.
270
+
271
+ Mirrors ``computeAutomaticInstructions.ts`` in ``microsoft/vscode``:
272
+ lists available subagents by name and description so the model knows
273
+ which agents to dispatch and how to call them.
274
+
275
+ Args:
276
+ custom_agents: List of custom agent config dicts (each with at least
277
+ a ``name`` key, optionally ``description`` and ``argument_hint``).
278
+ tool_name: Name of the dispatch tool (``runSubagent`` for VS Code,
279
+ ``task`` for Claude Code).
280
+
281
+ Returns:
282
+ The ``<agents>…</agents>`` XML string to prepend to the system message.
283
+ """
284
+ lines: list[str] = [
285
+ "<agents>",
286
+ "Here is a list of agents that can be used when running a subagent.",
287
+ (
288
+ "Each agent has optionally a description with the agent's purpose "
289
+ "and expertise. When asked to run a subagent, choose the most "
290
+ "appropriate agent from this list."
291
+ ),
292
+ f"Use the {tool_name} tool with the agent name to run the subagent.",
293
+ (
294
+ f"You are an orchestrator. All task work must be delegated to "
295
+ f"subagents via the `{tool_name}` tool. "
296
+ f"Do not implement, edit files, or perform task work directly — "
297
+ f"delegate every phase of work to the appropriate subagent."
298
+ ),
299
+ ]
300
+ for a in custom_agents:
301
+ agent_name = require_custom_agent_name(a)
302
+ lines.append("<agent>")
303
+ lines.append(f"<name>{agent_name}</name>")
304
+ if desc := a.get("description"):
305
+ lines.append(f"<description>{desc}</description>")
306
+ if hint := a.get("argument_hint"):
307
+ lines.append(f"<argumentHint>{hint}</argumentHint>")
308
+ lines.append("</agent>")
309
+ lines.append("</agents>")
310
+ return "\n".join(lines)
311
+
312
+
313
+ def _make_runsubagent_tool(
314
+ parent_agent: CopilotTaskConfig,
315
+ custom_agents: list[CopilotCustomAgentConfig],
316
+ mapper: CopilotEventMapper,
317
+ nested_runner: CopilotNestedRunner,
318
+ ) -> "Tool":
319
+ """Build a ``runSubagent`` polyfill tool for the VS Code persona."""
320
+ return _make_subagent_dispatch_tool(
321
+ "runSubagent",
322
+ parent_agent,
323
+ custom_agents,
324
+ mapper,
325
+ nested_runner,
326
+ )
327
+
328
+
329
+ def _make_task_tool(
330
+ parent_agent: CopilotTaskConfig,
331
+ custom_agents: list[CopilotCustomAgentConfig],
332
+ mapper: CopilotEventMapper,
333
+ nested_runner: CopilotNestedRunner,
334
+ ) -> "Tool":
335
+ """Build a ``task`` polyfill tool for the Claude Code persona."""
336
+ return _make_subagent_dispatch_tool(
337
+ "task",
338
+ parent_agent,
339
+ custom_agents,
340
+ mapper,
341
+ nested_runner,
342
+ )
343
+
344
+
345
+ def _make_subagent_dispatch_tool(
346
+ tool_name: str,
347
+ parent_agent: CopilotTaskConfig,
348
+ custom_agents: list[CopilotCustomAgentConfig],
349
+ mapper: CopilotEventMapper,
350
+ nested_runner: CopilotNestedRunner,
351
+ ) -> "Tool":
352
+ """Build a subagent dispatch polyfill tool.
353
+
354
+ The Copilot CLI does not natively expose ``runSubagent`` or ``task`` in
355
+ SDK headless mode. This factory creates a Python-side ``Tool`` that
356
+ dispatches registered custom agents as nested ``run_copilot`` calls.
357
+
358
+ Args:
359
+ tool_name: Name to register the tool as (``"runSubagent"`` for VS Code,
360
+ ``"task"`` for Claude Code).
361
+ parent_agent: The orchestrator ``CopilotTask`` being executed.
362
+ custom_agents: List of custom agent config dicts (each with at least
363
+ a ``name`` key, optionally ``prompt``, ``description``).
364
+ mapper: The ``EventMapper`` for the current run, used to record
365
+ subagent lifecycle events.
366
+ """
367
+ from copilot.tools import Tool, ToolResult
368
+
369
+ agent_map: dict[str, CopilotCustomAgentConfig] = {
370
+ require_custom_agent_name(agent): agent for agent in custom_agents
371
+ }
372
+
373
+ async def _handler(invocation: "ToolInvocation") -> "ToolResult":
374
+ if not invocation.tool_call_id:
375
+ return ToolResult(
376
+ text_result_for_llm="Error: custom-agent dispatch is missing tool_call_id.",
377
+ result_type="failure",
378
+ )
379
+
380
+ try:
381
+ args = require_mapping(invocation.arguments or {})
382
+ except ValueError as exc:
383
+ return ToolResult(text_result_for_llm=f"Error: {exc}", result_type="failure")
384
+
385
+ agent_slug = args.get("agentSlug")
386
+ prompt_text = args.get("prompt")
387
+
388
+ if not isinstance(agent_slug, str) or not agent_slug:
389
+ available = sorted(agent_map)
390
+ return ToolResult(
391
+ text_result_for_llm=(
392
+ f"Error: agentSlug is required. Available agents: {available}"
393
+ ),
394
+ result_type="failure",
395
+ )
396
+
397
+ if not isinstance(prompt_text, str) or not prompt_text:
398
+ return ToolResult(
399
+ text_result_for_llm="Error: prompt is required for custom-agent dispatch.",
400
+ result_type="failure",
401
+ )
402
+
403
+ agent_cfg = agent_map.get(agent_slug)
404
+ if agent_cfg is None:
405
+ available = sorted(agent_map)
406
+ return ToolResult(
407
+ text_result_for_llm=(
408
+ f"Error: agent '{agent_slug}' not found. Available: {available}"
409
+ ),
410
+ result_type="failure",
411
+ )
412
+
413
+ try:
414
+ system_prompt = require_custom_agent_prompt(agent_cfg)
415
+ except ValueError as exc:
416
+ return ToolResult(text_result_for_llm=f"Error: {exc}", result_type="failure")
417
+
418
+ reasoning_effort = resolve_agent_reasoning_effort(
419
+ parent_model=parent_agent.model,
420
+ parent_reasoning_effort=parent_agent.reasoning_effort,
421
+ agent_config=agent_cfg,
422
+ )
423
+ allowed_tools = declared_agent_tools(agent_cfg)
424
+ mcp_servers = merge_agent_mcp_servers(parent_agent.mcp_servers, agent_cfg)
425
+
426
+ mapper.record_subagent_start(invocation_id=invocation.tool_call_id, name=agent_slug)
427
+
428
+ sub_agent = parent_agent.create_subagent(
429
+ name=agent_slug,
430
+ model=agent_cfg.get("model", parent_agent.model),
431
+ reasoning_effort=reasoning_effort,
432
+ instructions=system_prompt,
433
+ timeout_s=min(parent_agent.timeout_s, 600.0),
434
+ max_turns=min(parent_agent.max_turns, 30),
435
+ allowed_tools=allowed_tools,
436
+ mcp_servers=mcp_servers,
437
+ )
438
+
439
+ sub_result = await nested_runner(sub_agent, prompt_text)
440
+ sub_result.agent = sub_agent
441
+ mapper.record_subagent_result(
442
+ invocation_id=invocation.tool_call_id, name=agent_slug, result=sub_result
443
+ )
444
+
445
+ if sub_result.success:
446
+ mapper.record_subagent_complete(
447
+ invocation_id=invocation.tool_call_id,
448
+ name=agent_slug,
449
+ )
450
+ return ToolResult(
451
+ text_result_for_llm=sub_result.final_response or "Sub-agent completed.",
452
+ result_type="success",
453
+ )
454
+
455
+ mapper.record_subagent_failed(
456
+ invocation_id=invocation.tool_call_id,
457
+ name=agent_slug,
458
+ )
459
+ return ToolResult(
460
+ text_result_for_llm=f"Sub-agent '{agent_slug}' failed: {sub_result.error}",
461
+ result_type="failure",
462
+ )
463
+
464
+ return Tool(
465
+ name=tool_name,
466
+ description=(
467
+ f"Dispatch a named agent to perform a task using the {tool_name} tool. "
468
+ "The agent runs with its own instructions and returns its final response. "
469
+ f"Available agents: {sorted(agent_map)}"
470
+ ),
471
+ handler=_handler,
472
+ parameters={
473
+ "type": "object",
474
+ "properties": {
475
+ "agentSlug": {
476
+ "type": "string",
477
+ "description": "Machine-readable custom agent name to dispatch.",
478
+ "enum": sorted(agent_map),
479
+ },
480
+ "prompt": {
481
+ "type": "string",
482
+ "description": "Full task prompt to send to the custom agent.",
483
+ },
484
+ },
485
+ "required": ["agentSlug", "prompt"],
486
+ },
487
+ )
488
+
489
+
490
+ # ---------------------------------------------------------------------------
491
+ # Skill reference polyfills
492
+ # ---------------------------------------------------------------------------
493
+
494
+
495
+ def _inject_skill_reference_tools(
496
+ agent: CopilotTaskConfig,
497
+ session_config: dict[str, Any],
498
+ ) -> None:
499
+ """Inject ``list_skill_references`` and ``read_skill_reference`` polyfill tools.
500
+
501
+ The Copilot CLI SDK does not natively expose skill reference documents
502
+ as tools (unlike VS Code, which does). This polyfill scans the agent's
503
+ ``skill_directories`` for ``references/`` subdirectories and creates
504
+ Python-side tools so the model can discover and read reference docs.
505
+
506
+ Only injected when at least one skill directory has reference documents.
507
+ """
508
+ from pytest_copilot.copilot.skills import requested_skill_files
509
+ from pytest_copilot.core.plugin import _validate_skill_reference_names
510
+ from pytest_copilot.core.skill import Skill
511
+
512
+ configured = (
513
+ session_config if "skill_directories" in session_config else agent.build_session_config()
514
+ )
515
+ directories = configured.get("skill_directories")
516
+ if not directories:
517
+ return
518
+ disabled = configured.get("disabled_skills") or []
519
+ skills = [
520
+ Skill.from_path(path)
521
+ for path, name in requested_skill_files(directories).items()
522
+ if name not in disabled
523
+ ]
524
+ _validate_skill_reference_names(skills)
525
+ reference_files = {
526
+ name: skill.path / "references" / name for skill in skills for name in skill.references
527
+ }
528
+
529
+ if not reference_files:
530
+ return
531
+
532
+ from copilot.tools import Tool, ToolResult
533
+
534
+ # list_skill_references tool
535
+ async def _list_handler(invocation: "ToolInvocation") -> "ToolResult":
536
+ file_list = "\n".join(f"- {name}" for name in sorted(reference_files))
537
+ return ToolResult(
538
+ text_result_for_llm=f"Available skill reference documents:\n{file_list}",
539
+ result_type="success",
540
+ )
541
+
542
+ list_tool = Tool(
543
+ name="list_skill_references",
544
+ description=(
545
+ "List available skill reference documents. "
546
+ "These contain detailed domain knowledge (e.g., lookup tables, "
547
+ "specs, configuration guides) that supplements the skill instructions."
548
+ ),
549
+ handler=_list_handler,
550
+ parameters={"type": "object", "properties": {}},
551
+ )
552
+
553
+ # read_skill_reference tool
554
+ async def _read_handler(invocation: "ToolInvocation") -> "ToolResult":
555
+ args: dict[str, Any] = invocation.arguments or {}
556
+ filename = args.get("filename", "")
557
+
558
+ if not filename:
559
+ available = sorted(reference_files)
560
+ return ToolResult(
561
+ text_result_for_llm=f"Error: filename is required. Available: {available}",
562
+ result_type="failure",
563
+ )
564
+
565
+ ref_path = reference_files.get(filename)
566
+ if ref_path is None:
567
+ available = sorted(reference_files)
568
+ return ToolResult(
569
+ text_result_for_llm=f"Error: '{filename}' not found. Available: {available}",
570
+ result_type="failure",
571
+ )
572
+
573
+ content = ref_path.read_text(encoding="utf-8")
574
+ return ToolResult(text_result_for_llm=content, result_type="success")
575
+
576
+ read_tool = Tool(
577
+ name="read_skill_reference",
578
+ description=(
579
+ "Read a specific skill reference document by filename. "
580
+ "Use list_skill_references first to see what's available."
581
+ ),
582
+ handler=_read_handler,
583
+ parameters={
584
+ "type": "object",
585
+ "properties": {
586
+ "filename": {
587
+ "type": "string",
588
+ "description": "Name of the reference file to read.",
589
+ "enum": sorted(reference_files),
590
+ },
591
+ },
592
+ "required": ["filename"],
593
+ },
594
+ )
595
+
596
+ _inject_tool(session_config, list_tool)
597
+ _inject_tool(session_config, read_tool)
598
+
599
+ # Add system message about reference documents
600
+ refs_list = ", ".join(sorted(reference_files))
601
+ _prepend_system_message(
602
+ session_config,
603
+ f"You have skill reference documents available via the "
604
+ f"list_skill_references and read_skill_reference tools. "
605
+ f"Available references: {refs_list}. "
606
+ f"Use these for detailed lookup information.",
607
+ )