opencode-copilot-delegate 0.4.0 → 0.5.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # opencode-copilot-delegate
2
2
 
3
+ ## 0.5.0
4
+
5
+ ### Minor Changes
6
+
7
+ - e940a28: Drop `BUILTIN_AGENTS` and enrich tool schema descriptions
8
+
9
+ **`BUILTIN_AGENTS` removal.** The plugin previously advertised six "built-in" agent names — `default`, `explore`, `task`, `general-purpose`, `code-review`, `research` — inherited from VS Code Copilot Chat / OpenCode conventions. The standalone `@github/copilot` CLI v1.0.36 ships zero of these; passing any of them as `--agent <name>` causes Copilot CLI to fail at spawn time with `Error: No such agent: <name>, available:`. The constant has been removed. `discoverAgents` now returns user agents (filtered by repo override) followed by repo agents; `Agent.source` is `'user' | 'repo'`. `buildDescription` handles the empty-discovery case by emitting an actionable hint pointing at `~/.copilot/agents` and `.github/agents`.
10
+
11
+ **Tool schema enrichment.** The three exposed tools — `copilot_delegate`, `copilot_output`, `copilot_cancel` — now ship multi-paragraph tool descriptions covering what they do, when to use them, lifecycle, common pitfalls, and return-value shape. Per-parameter `.describe()` text spells out type, default, when-required, example values, and constraints. Examples follow the patterns Magic Context's `ctx_*` tools established. The new descriptions surface in OpenCode's tool registry exposure to LLMs and via `mise run opencode:doctor --only tools`.
12
+
13
+ No runtime behavior change beyond the agent discovery fix. Tool argument shapes are unchanged; existing callers continue to work without modification.
14
+
3
15
  ## 0.4.0
4
16
 
5
17
  ### Minor Changes
@@ -1,10 +1,22 @@
1
1
  export interface Agent {
2
2
  name: string;
3
- source: 'builtin' | 'user' | 'repo';
3
+ source: 'user' | 'repo';
4
4
  }
5
5
  interface DiscoverOptions {
6
6
  userAgentsDir?: string;
7
7
  repoAgentsDir?: string;
8
8
  }
9
+ /**
10
+ * Discover Copilot agents from the user and repo agent directories.
11
+ *
12
+ * Copilot CLI v1.0.36 ships zero built-in agents. Every `--agent <name>`
13
+ * argument must resolve to a discoverable `<name>.md` file in one of the
14
+ * standard agent directories (`~/.copilot/agents`, `.github/agents`, or
15
+ * `~/.copilot/installed-plugins/<plugin>/agents`). The plugin discovers the
16
+ * first two; bundled-with-plugin agents are out of scope for this discovery
17
+ * helper.
18
+ *
19
+ * Repo agents override user agents with the same name; the repo entry wins.
20
+ */
9
21
  export declare function discoverAgents(opts: DiscoverOptions): Agent[];
10
22
  export {};
@@ -1,2 +1,8 @@
1
1
  import type { Agent } from './agents';
2
+ /**
3
+ * Render a human-readable list of discovered agents for inclusion in the
4
+ * `copilot_delegate` tool description. Lists user and repo agents (no
5
+ * builtins; Copilot CLI v1.0.36 ships none). Truncates at MAX_DISPLAYED
6
+ * entries with a count of the rest.
7
+ */
2
8
  export declare function buildDescription(agents: Agent[]): string;
package/dist/index.js CHANGED
@@ -797,14 +797,6 @@ import { dirname as dirname2 } from "path";
797
797
  // src/discovery/agents.ts
798
798
  import { readdirSync } from "fs";
799
799
  import { basename } from "path";
800
- var BUILTIN_AGENTS = [
801
- "default",
802
- "explore",
803
- "task",
804
- "general-purpose",
805
- "code-review",
806
- "research"
807
- ];
808
800
  function scanDir(dir, source) {
809
801
  try {
810
802
  const entries = readdirSync(dir);
@@ -817,22 +809,24 @@ function scanDir(dir, source) {
817
809
  }
818
810
  }
819
811
  function discoverAgents(opts) {
820
- const builtins = BUILTIN_AGENTS.map((name) => ({
821
- name,
822
- source: "builtin"
823
- }));
824
812
  const userAgents = opts.userAgentsDir ? scanDir(opts.userAgentsDir, "user") : [];
825
813
  const repoAgents = opts.repoAgentsDir ? scanDir(opts.repoAgentsDir, "repo") : [];
826
- const builtinNames = new Set(BUILTIN_AGENTS);
827
814
  const overriddenNames = new Set(repoAgents.map((a) => a.name));
828
- const filteredUser = userAgents.filter((a) => !builtinNames.has(a.name)).filter((a) => !overriddenNames.has(a.name));
829
- const filteredRepo = repoAgents.filter((a) => !builtinNames.has(a.name));
830
- return [...builtins, ...filteredUser, ...filteredRepo];
815
+ const filteredUser = userAgents.filter((a) => !overriddenNames.has(a.name));
816
+ return [...filteredUser, ...repoAgents];
831
817
  }
832
818
 
833
819
  // src/discovery/description.ts
834
820
  var MAX_DISPLAYED = 20;
835
821
  function buildDescription(agents) {
822
+ if (agents.length === 0) {
823
+ return [
824
+ "No Copilot agents discovered.",
825
+ "Add `.agent.md` files to `~/.copilot/agents` (user-level) or",
826
+ "`.github/agents` (repo-level) to make them available here."
827
+ ].join(`
828
+ `);
829
+ }
836
830
  const displayed = agents.slice(0, MAX_DISPLAYED);
837
831
  const remaining = agents.length - MAX_DISPLAYED;
838
832
  const lines = ["Available Copilot agents:"];
@@ -840,7 +834,7 @@ function buildDescription(agents) {
840
834
  lines.push(` - ${agent.name} (${agent.source})`);
841
835
  }
842
836
  if (remaining > 0) {
843
- lines.push(` ... and ${remaining} more (use copilot_list_agents to see all)`);
837
+ lines.push(` ... and ${remaining} more (see ~/.copilot/agents or .github/agents)`);
844
838
  }
845
839
  return lines.join(`
846
840
  `);
@@ -9724,11 +9718,29 @@ function getAllTasks() {
9724
9718
  }
9725
9719
 
9726
9720
  // src/tools/cancel.ts
9721
+ var TOOL_DESCRIPTION = [
9722
+ "Cancel a running Copilot delegation.",
9723
+ "",
9724
+ "Aborts the in-flight subprocess via its `AbortController`; the subprocess receives SIGTERM through",
9725
+ "its process tree and the task transitions to `cancelled`. Any pending `copilot_output` block calls",
9726
+ "unblock immediately with the cancelled envelope.",
9727
+ "",
9728
+ "Returns `{ cancelled, was_running }`:",
9729
+ "- `cancelled: true, was_running: true` \u2014 task was running and the abort signal was sent.",
9730
+ "- `cancelled: false, was_running: false` \u2014 task is unknown to this process, or already terminal",
9731
+ " (`succeeded` / `failed` / `cancelled`). Idempotent \u2014 safe to call multiple times.",
9732
+ "",
9733
+ "Use when:",
9734
+ "- The user changes direction during a long-running delegation and the task's output is no longer needed.",
9735
+ "- The agent has determined a delegation has gone wrong (e.g., wrong agent selected) and a fresh delegate is preferable to waiting.",
9736
+ "- Concurrency limit pressure \u2014 cancel a stale low-priority task to free a slot for a higher-priority delegation."
9737
+ ].join(`
9738
+ `);
9727
9739
  function createCancelTool() {
9728
9740
  return tool({
9729
- description: "Cancel a running Copilot delegation.",
9741
+ description: TOOL_DESCRIPTION,
9730
9742
  args: {
9731
- task_id: tool.schema.string().describe("Task ID returned by copilot_delegate.")
9743
+ task_id: tool.schema.string().describe("The task ID returned by `copilot_delegate(...)`. Format: `cpl_<...>`. Required. Idempotent \u2014 non-running task IDs return `{ cancelled: false, was_running: false }` without error.")
9732
9744
  },
9733
9745
  async execute(args) {
9734
9746
  const task = getTask(args.task_id);
@@ -10031,19 +10043,45 @@ function appendRepeatedFlag(args, flag, values) {
10031
10043
  args.push(flag, value);
10032
10044
  }
10033
10045
  }
10046
+ var TOOL_DESCRIPTION2 = [
10047
+ "Delegate a task to GitHub Copilot CLI as a background subprocess.",
10048
+ "",
10049
+ "Returns a `task_id` immediately so the parent agent can continue other work in parallel.",
10050
+ "When Copilot completes, a `system-reminder` is injected into this OpenCode session and the",
10051
+ "agent retrieves the structured result with `copilot_output(task_id)`.",
10052
+ "",
10053
+ "Use for:",
10054
+ "- Long-running research, implementation, or multi-step automation that would otherwise stall the parent session.",
10055
+ "- Running multiple Copilot calls in parallel (subject to a 10-call concurrency cap, enforced here).",
10056
+ "- Isolating Copilot tool permissions per-task via `allow_tool` / `deny_tool`.",
10057
+ "",
10058
+ "Do not use for:",
10059
+ "- Short single-turn prompts the parent session can answer directly.",
10060
+ "- Tasks where the prompt would contain secrets \u2014 Copilot CLI exposes prompts in `ps` output (upstream limitation).",
10061
+ "",
10062
+ "Lifecycle:",
10063
+ "1. `copilot_delegate(...)` \u2192 returns `{ task_id }`. The subprocess starts immediately.",
10064
+ "2. Continue with other work; do not poll `copilot_output` while the task is running.",
10065
+ "3. When the task ends (success, error, or cancellation) a `system-reminder` arrives in this session.",
10066
+ "4. `copilot_output(task_id)` returns the structured envelope (status, exit_code, final_message, summary, events, ...).",
10067
+ "5. `copilot_cancel(task_id)` aborts a running task at any time.",
10068
+ "",
10069
+ "Concurrency: at most 10 Copilot delegations may be running concurrently per OpenCode session. Exceeding the cap returns `{ error: ... }` and the agent should wait for an in-flight task to complete or cancel.",
10070
+ "",
10071
+ "Agent argument: `--agent <name>` must resolve to a discovered `<name>.md` file in `~/.copilot/agents` (user-level) or `.github/agents` (repo-level). An unrecognized name is rejected by Copilot CLI at spawn time.",
10072
+ ""
10073
+ ].join(`
10074
+ `);
10034
10075
  function createDelegateTool(options) {
10035
10076
  return tool2({
10036
- description: `Delegate a task to GitHub Copilot CLI as a background subprocess.
10037
- ` + `Returns a task_id immediately; parent agent continues other work.
10038
- ` + `When Copilot completes, a system-reminder is injected into this session.
10039
- ` + "Retrieve the structured result with `copilot_output(task_id)`.\n\n" + options.description,
10077
+ description: `${TOOL_DESCRIPTION2}${options.description}`,
10040
10078
  args: {
10041
- prompt: tool2.schema.string().min(1).describe("The prompt to send to Copilot CLI."),
10042
- agent: tool2.schema.string().optional().describe("Copilot agent name. Omit for default."),
10043
- model: tool2.schema.string().optional().describe("Model override. Omit for default."),
10044
- add_dir: tool2.schema.string().array().optional().describe("Additional directories to allow."),
10045
- allow_tool: tool2.schema.string().array().optional().describe("Tool patterns to allow."),
10046
- deny_tool: tool2.schema.string().array().optional().describe("Tool patterns to deny.")
10079
+ prompt: tool2.schema.string().min(1).describe("The instruction Copilot should execute. The prompt body is the entire user-visible task; Copilot owns the planning, tool selection, and execution. Required and must be non-empty. Visible in `ps` output (upstream limitation) \u2014 never include secrets, tokens, or PII."),
10080
+ agent: tool2.schema.string().optional().describe("Agent name (without .md extension) to use for this task. Must match a discovered agent file in `~/.copilot/agents` or `.github/agents`. The list of currently discovered agents appears at the bottom of this tool description; an empty list means no agents are discoverable and `agent` must be omitted. Omit to use the Copilot CLI default."),
10081
+ model: tool2.schema.string().optional().describe("Override the default model for this task. Accepts any model string Copilot CLI recognizes \u2014 for example `claude-opus-4.7`, `claude-sonnet-4.7`, or `gpt-5`. Omit to use the user's configured default."),
10082
+ add_dir: tool2.schema.string().array().optional().describe('Additional repository paths to grant Copilot access to (multi-repo workflows). Each entry becomes a `--add-dir <path>` flag. Use absolute paths. Examples: `["/Users/me/repo-a", "/Users/me/repo-b"]`.'),
10083
+ allow_tool: tool2.schema.string().array().optional().describe('Copilot tool patterns to allow during this task. Each entry becomes an `--allow-tool <pattern>` flag. Examples: `"shell(*)"`, `"edit"`, `"fetch"`. See the Copilot CLI docs for the full pattern syntax. Layered with `deny_tool` when both are present.'),
10084
+ deny_tool: tool2.schema.string().array().optional().describe('Copilot tool patterns to deny during this task. Each entry becomes a `--deny-tool <pattern>` flag. Examples: `"shell(rm)"`, `"shell(curl)"`. Use to harden a task by blocking dangerous operations even if `allow_tool` would permit them.')
10047
10085
  },
10048
10086
  async execute(args, ctx) {
10049
10087
  const runningCount = getAllTasks().filter((task2) => task2.status === "running").length;
@@ -10207,16 +10245,45 @@ function buildEnvelope(input) {
10207
10245
  }
10208
10246
 
10209
10247
  // src/tools/output.ts
10248
+ var DEFAULT_TIMEOUT_MS = 30000;
10249
+ var MAX_TIMEOUT_MS = 120000;
10210
10250
  function isValidTaskId(taskId) {
10211
10251
  return taskId.length > 0 && taskId.startsWith("cpl_");
10212
10252
  }
10253
+ var TOOL_DESCRIPTION3 = [
10254
+ "Retrieve the structured result envelope for a delegated Copilot task.",
10255
+ "",
10256
+ "Most calls happen after a `copilot_delegate(...)` task triggers its completion `system-reminder`",
10257
+ "in this session. The envelope contains everything the agent needs to act on the result:",
10258
+ "",
10259
+ "- `task_id`, `status` (`running` | `succeeded` | `failed` | `cancelled` | `unknown`)",
10260
+ "- `exit_code`, `duration_ms`, `started_at`, `ended_at`",
10261
+ "- `agent_name`, `model_name`, `args` (the original CLI args)",
10262
+ "- `final_message`: the assistant's last user-visible response, or null",
10263
+ "- `error_text`: stderr tail when the subprocess failed",
10264
+ "- `summary`: counts of tool calls, files changed, and tokens consumed",
10265
+ "- `events` (when present): the sequence of parsed JSONL events from Copilot",
10266
+ "",
10267
+ "When to call:",
10268
+ "- After receiving a completion `system-reminder` for a known `task_id`.",
10269
+ "- On demand if the agent needs to inspect a still-running task \u2014 pass `block: true` to wait briefly for completion.",
10270
+ "- On task IDs the parent agent saved earlier in the session.",
10271
+ "",
10272
+ "Block mode (`block: true`):",
10273
+ "- If the task is still running, wait up to `timeout_ms` (default 30000, capped at 120000) for completion.",
10274
+ "- On timeout, returns the envelope with `timed_out: true` and the agent should call again later.",
10275
+ "- For research-style delegations that may exceed 120s, prefer non-blocking polling \u2014 call this tool again after each `system-reminder` instead of holding open a single long block.",
10276
+ "",
10277
+ 'Unknown task IDs return `{ task_id, status: "unknown", error }` rather than throwing.'
10278
+ ].join(`
10279
+ `);
10213
10280
  function createOutputTool() {
10214
10281
  return tool3({
10215
- description: "Retrieve the structured result envelope for a delegated Copilot task.",
10282
+ description: TOOL_DESCRIPTION3,
10216
10283
  args: {
10217
- task_id: tool3.schema.string().describe("Task ID returned by copilot_delegate."),
10218
- block: tool3.schema.boolean().optional().describe("Wait for completion. Default false."),
10219
- timeout_ms: tool3.schema.number().int().min(0).max(120000).optional().describe("Max wait ms when block is true. Default 30000.")
10284
+ task_id: tool3.schema.string().describe("The task ID returned by `copilot_delegate(...)`. Format: `cpl_<...>`. Required."),
10285
+ block: tool3.schema.boolean().optional().describe("If the task is still running, wait for completion up to `timeout_ms` before returning. Default `false` \u2014 returns immediately with the current state. Set to `true` only when the agent has nothing else to do but wait."),
10286
+ timeout_ms: tool3.schema.number().int().min(0).max(MAX_TIMEOUT_MS).optional().describe("Maximum wait in milliseconds when `block` is `true`. Default 30000. Range 0\u2013120000 (the upper cap protects the OpenCode session from a single hung delegation). For long research tasks, prefer multiple non-blocking calls over a long block.")
10220
10287
  },
10221
10288
  async execute(args) {
10222
10289
  if (!isValidTaskId(args.task_id)) {
@@ -10235,7 +10302,7 @@ function createOutputTool() {
10235
10302
  });
10236
10303
  }
10237
10304
  if (args.block && task.status === "running") {
10238
- const timeoutMs = Math.max(0, Math.min(args.timeout_ms ?? 30000, 120000));
10305
+ const timeoutMs = Math.max(0, Math.min(args.timeout_ms ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS));
10239
10306
  let timer;
10240
10307
  const completed = await Promise.race([
10241
10308
  task.completionPromise.then(() => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-copilot-delegate",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "OpenCode plugin that delegates tasks to GitHub Copilot CLI as background subprocesses",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",