@ravshansbox/pi-next-issue 2.5.10 → 2.7.0

package/README.md

@@ -13,12 +13,25 @@ It needs `git`, `npx` and an authenticated [`gh`](https://cli.github.com/). It w
 Run this in pi, inside a git repository:
 
 - `/next-issue` starts a run of this repository when none is going, and stops the run when one is going. A stop takes effect after the current round, and the issue keeps its saved state, so the next run resumes it.
+- The `next_issue_start` tool lets the model start a run. When no run is going, it starts a run like `/next-issue`. When a run is going, it starts nothing and reports the current run, which picks up new issues by itself. It never stops a run, and it does not ask for confirmation. Its result says whether it started a run.
 
 The footer shows the issue, the stage, the number of tool calls and the time spent on the issue, for example `next-issue #12 · review 1 · 37 tools · 4m12s`. After a run ends, it keeps the last summary. In the terminal, it uses the dim colour of the theme, like the rest of the footer. A note appears when an issue is done, needs a human or fails while pi is open. Pi does not repeat the notes of a run that ended before it opened.
 
+## Create an issue
+
+The package ships the `create-issue` skill. Ask pi to write an issue, or run `/skill:create-issue <problem>`. Pi then:
+
+1. restates the problem and reads the code when the problem touches it;
+2. asks numbered questions until none is open;
+3. shows the title and the body, and asks once whether to create the issue and start a run;
+4. runs `gh issue create --body-file` with the body from [`template.md`](skills/create-issue/template.md) and the `status:todo` label;
+5. calls `next_issue_start` when you asked for a run.
+
+Pi does not implement the issue in that session. The worker does the work. The body holds the sections of the [issue format](../next-issue/README.md#issue-format).
+
 ## Worker
 
-The extension does no work itself. On `/next-issue` it connects to the `next-issue` worker on the socket file `~/.pi/agent/next-issue.sock`. When no worker answers, it starts one with `npx -y next-issue@<version> serve`, where `<version>` is the version of the extension, or `latest` when the extension runs from a source checkout with version `0.0.0`, in the background, and writes the output of the worker to `~/.pi/agent/next-issue-worker.log`.
+The extension does no work itself. On `/next-issue` or `next_issue_start` it connects to the `next-issue` worker on the socket file `~/.pi/agent/next-issue.sock`. When no worker answers, it starts one with `npx -y next-issue@<version> serve`, where `<version>` is the version of the extension, or `latest` when the extension runs from a source checkout with version `0.0.0`, in the background, and writes the output of the worker to `~/.pi/agent/next-issue-worker.log`.
 
 - Every pi on the machine shares the one worker, and every pi in a repository shows the run of that repository, whoever started it.
 - Opening pi does not start a worker. It only shows a run when a worker is going.

package/index.ts

@@ -5,6 +5,7 @@ import {
   type ExtensionContext,
   getAgentDir,
 } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
 import { repoRoot } from './src/git.ts';
 import { type Progress, spawnWorker, WorkerClient, type WorkerEvent } from './src/worker.ts';
 
@@ -144,7 +145,7 @@ export function createExtension(options: Options) {
         render();
       } else if (event.type === 'runs') {
         onProgress(root === undefined ? undefined : event.runs[root]);
-      } else if (event.root === root) {
+      } else if (event.type === 'error' && event.root === root) {
         ui?.notify(`next-issue cannot start: ${event.message}`, 'error');
       }
     };
@@ -189,19 +190,84 @@ export function createExtension(options: Options) {
       ui = undefined;
     });
 
+    const connect = async (ctx: ExtensionContext) => {
+      root = await options.root(ctx.cwd);
+      if (ctx.hasUI) {
+        show(ctx);
+        follow();
+      }
+      const client = shared(options.client);
+      await client.ensure();
+      return { client, root, progress: client.runs[root] };
+    };
+
+    const going = (progress: Progress | undefined): progress is Progress =>
+      progress?.status === 'running' || progress?.status === 'stopping';
+
+    const accepted = (client: WorkerClient, root: string, signal: AbortSignal | undefined) =>
+      new Promise<void>((resolve, reject) => {
+        const finish = (error?: Error) => {
+          stop();
+          signal?.removeEventListener('abort', abort);
+          if (error === undefined) {
+            resolve();
+          } else {
+            reject(error);
+          }
+        };
+        const abort = () => finish(new Error('next_issue_start was cancelled'));
+        const stop = client.subscribe((event) => {
+          if (event.type === 'error' && event.root === root) {
+            finish(new Error(event.message));
+          } else if (event.type === 'closed') {
+            finish(new Error('the worker closed the connection'));
+          } else if (event.type === 'runs' && going(event.runs[root])) {
+            finish();
+          }
+        });
+        if (signal?.aborted) {
+          abort();
+        } else {
+          signal?.addEventListener('abort', abort, { once: true });
+        }
+      });
+
+    pi.registerTool({
+      name: 'next_issue_start',
+      label: 'Start next-issue',
+      description:
+        'Start a next-issue run of the GitHub issues of this repository when none is going. Starts the worker when needed. When a run is going, starts nothing and reports that run, which picks up new issues by itself.',
+      promptSnippet: 'Start a next-issue run of this repository when none is going',
+      parameters: Type.Object({}),
+      async execute(_toolCallId, _params, signal, _onUpdate, ctx) {
+        const { client, root, progress } = await connect(ctx);
+        if (going(progress)) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `A run of ${root} is going already, so nothing started: ${formatStatus(progress, Date.now())}. It picks up new issues by itself.`,
+              },
+            ],
+            details: { started: false, root },
+          };
+        }
+        const accepting = accepted(client, root, signal);
+        client.send({ type: 'start', root, merge: true });
+        await accepting;
+        return {
+          content: [{ type: 'text', text: `Started a next-issue run of ${root}.` }],
+          details: { started: true, root },
+        };
+      },
+    });
+
     pi.registerCommand('next-issue', {
       description: 'Start or stop working through the GitHub issues of this repository',
       handler: async (_args, ctx) => {
         try {
-          root = await options.root(ctx.cwd);
-          if (ctx.hasUI) {
-            show(ctx);
-            follow();
-          }
-          const client = shared(options.client);
-          await client.ensure();
-          const progress = client.runs[root];
-          if (progress?.status === 'running' || progress?.status === 'stopping') {
+          const { client, root, progress } = await connect(ctx);
+          if (going(progress)) {
             client.send({ type: 'stop', root });
           } else {
             client.send({ type: 'start', root, merge: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ravshansbox/pi-next-issue",
-  "version": "2.5.10",
+  "version": "2.7.0",
   "description": "Pi extension that works through GitHub issues with the next-issue worker",
   "license": "MIT",
   "type": "module",
@@ -16,12 +16,16 @@
   "keywords": [
     "pi-package",
     "pi-extension",
+    "pi-skill",
     "github",
     "issues"
   ],
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "scripts": {
@@ -34,7 +38,8 @@
     "check": "npm run typecheck && npm run lint && npm run format:check && npm test"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
@@ -45,7 +50,8 @@
   },
   "files": [
     "index.ts",
-    "src"
+    "src",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"

package/skills/create-issue/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: create-issue
+description: Turn a problem into a clear GitHub issue that the next-issue worker can claim. Use when the user wants to write, file or create an issue.
+---
+
+# Create an issue
+
+Turn the problem of the user into one GitHub issue in the format of `template.md`, next to this file.
+
+1. Understand the problem. Restate it in your own words.
+2. Investigate the code when the problem touches it. Read the relevant files and note what you find, with file paths.
+3. Ask numbered questions about anything that is unclear: the scope, the expected behaviour, the acceptance criteria. Label options with letters and recommend one. Ask again until no question is open.
+4. Write the body from `template.md` into a temporary file. Keep every heading of the template and its order. Leave `Open questions` empty.
+5. Show the title and the body to the user. Ask once whether to create the issue and start a run: a) create the issue and start a run, b) create the issue only, c) change the draft. Change the draft and show it again until the user picks a or b.
+6. Only after the user picks a or b, create the issue:
+
+   ```bash
+   gh issue create --title "<title>" --body-file <file> --label status:todo
+   ```
+
+7. Tell the user the issue url.
+8. Only when the user picked a, call the `next_issue_start` tool, and tell the user what it reports.
+
+Once the issue exists, do not implement it in this session. The next-issue worker does the work. Do not ask about a run a second time.
+
+## Sections
+
+- Problem: what is wrong or missing, and who it affects.
+- Context and findings: what you found in the code and the docs, with paths.
+- Acceptance criteria: a list of checks that show the issue is done, each one observable.
+- Out of scope: what the issue does not cover.
+- Open questions: empty when the issue is created.

package/skills/create-issue/template.md

@@ -0,0 +1,9 @@
+## Problem
+
+## Context and findings
+
+## Acceptance criteria
+
+## Out of scope
+
+## Open questions

package/src/worker.ts

@@ -31,7 +31,8 @@ export type WorkerMessage =
 
 export type WorkerEvent =
   | { type: 'runs'; runs: Record<string, Progress> }
-  | { type: 'error'; root: string; message: string };
+  | { type: 'error'; root: string; message: string }
+  | { type: 'closed' };
 
 export type WorkerOptions = {
   socketPath: string;
@@ -227,6 +228,7 @@ export class WorkerClient {
       socket.once('close', () => {
         if (this.socket === socket) {
           this.socket = undefined;
+          this.emit({ type: 'closed' });
           this.scheduleReconnect();
         }
         if (!hello) {