copilot-operator 0.1.0

package/dist/src/protocol/reviewSchema.js

@@ -0,0 +1,205 @@
+/**
+ * The contract a reviewing conversation answers in.
+ *
+ * A review is a second conversation, opened after a task has finished and its checks have
+ * passed, that is shown the task and the result and asked whether the one satisfies the other.
+ * It is deliberately a different contract from the implementer's, because it is a different
+ * job with a different failure mode. An implementer that ends wrongly says "done" when it is
+ * not; a reviewer that ends wrongly says "pass" when it has not looked.
+ *
+ * So the shape of this schema is almost entirely about making "pass" expensive and "fail"
+ * useful:
+ *
+ * - `pass` needs a summary that says what was checked, not that it was checked. The runner
+ *   adds the part a schema cannot see — a review that ran no commands at all cannot pass,
+ *   whatever it writes here.
+ * - `fail` needs findings, and every finding needs evidence: the command and what it
+ *   returned. A reviewer that only has opinions cannot fail anything either, which is the
+ *   same rule from the other side.
+ *
+ * The prose version the reviewer is sent lives in `prompts/review1.md`.
+ */
+import { z } from 'zod';
+import { CheckInput } from '../plan/schema.js';
+import { StepSchema } from './replySchema.js';
+export const MIN_REVIEW_SUMMARY_CHARS = 40;
+/**
+ * One thing that is wrong, with what proves it.
+ *
+ * Both halves are required and neither can be waved through. "The README is wrong" is not
+ * actionable; "the README says to start the API with `npx tsx src/main.ts`, and running it
+ * returns HTTP 500 on every request" is a defect somebody can fix without repeating the work.
+ */
+const Finding = z.object({
+    what: z
+        .string()
+        .trim()
+        .min(15, 'A finding needs a sentence naming what is wrong, specifically enough to act on.'),
+    evidence: z
+        .string()
+        .trim()
+        .min(10, 'A finding needs evidence: the command you ran and what it actually returned.'),
+    /** The file, the endpoint, the line — wherever the defect lives. */
+    /**
+     * Required, because it is how the same defect is recognised between rounds. Two reviewers
+     * word one problem differently; a file and a place in it do not drift. A first-round
+     * finding without one made a second-round repeat invisible, and the loop ran a third time.
+     */
+    where: z.string().trim().min(3, {
+        message: 'A finding needs "where": the file and the place in it, or the URL, that the finding is about.',
+    }),
+    /**
+     * The sentence of the task this finding rests on, quoted.
+     *
+     * A reviewer once searched a page for label text no task had specified and failed the work
+     * for its absence; the next reviewer did the same. Every finding now has to say which
+     * sentence asked for the thing it says is missing, and the runner checks that the sentence
+     * is really there — in this task, its project instructions, or an earlier task of the same
+     * session. A finding that cannot quote its basis is an invented requirement, and is refused.
+     */
+    basis: z.string().trim().min(12, {
+        message: 'A finding needs "basis": the sentence of the task (or its project instructions) it rests on, quoted, at least 12 characters.',
+    }),
+    /**
+     * The mechanical test that would have caught this, in the plan's own check shape.
+     *
+     * A review is judgement, and judgement varies: the same missing `@HttpCode(200)` was found
+     * in one run and missed in the next. A finding that carries its check turns the one thing
+     * the reviewer noticed into arithmetic the runner repeats on every later attempt. The runner
+     * runs it at once, on the work as it stands: a check that passes on the defective state does
+     * not capture the defect, and is refused.
+     */
+    check: CheckInput.optional(),
+    /**
+     * Whose problem this is, and the only field here that changes what happens next.
+     *
+     * `work` — the work does not do what the task asked. Somebody can fix it, so it goes back.
+     * `task` — the work is right and the **task** is wrong: it contradicts itself, it demands
+     *   something the project instructions forbid, or it expects something that is not true of
+     *   this machine. Nobody downstream can fix that, so the task stops and says so.
+     *
+     * Without this, a reviewer holding a contradictory task had only one move — fail the work —
+     * and the implementer, who may not change the task, had only one answer: it cannot. Two
+     * rounds of that and the task blocked with a finding that was never about the work. Three
+     * such findings in one run: a README documenting four error messages where the task said
+     * three (the code has four), a README whose start commands could not be run because the
+     * project instructions forbid starting servers, and an audit expected to find no git remote
+     * in a repository that has one.
+     */
+    about: z.enum(['work', 'task']).default('work'),
+});
+export const ReviewSchema = z
+    .object({
+    /**
+     * `continue` — steps to run, send me the output.
+     * `pass` — I checked it by running things, and it does what the task asked.
+     * `fail` — I checked it by running things, and here is what is wrong.
+     *
+     * There is no "blocked" here. A reviewer that cannot check something says so as a finding
+     * and fails: "I could not verify X because Y" is information the operator needs, and
+     * quietly passing work nobody could check is the one outcome worth ruling out.
+     */
+    status: z.enum(['continue', 'pass', 'fail']),
+    steps: z.array(StepSchema).default([]),
+    notes: z.string().optional(),
+    /** Required on `pass` and `fail`: what you checked, how, and what you saw. */
+    summary: z.string().optional(),
+    findings: z.array(Finding).default([]),
+})
+    .refine((r) => r.status !== 'continue' || r.steps.length > 0, {
+    message: 'status "continue" with no steps would stall the review. Send steps, or reach a verdict.',
+})
+    .refine((r) => r.status === 'continue' || r.steps.length === 0, {
+    message: 'A verdict ends the review, so "pass" and "fail" cannot carry steps. Run them first with "continue".',
+})
+    .refine((r) => r.status === 'continue' || (r.summary ?? '').trim().length >= MIN_REVIEW_SUMMARY_CHARS, {
+    message: 'A verdict requires a summary: what you checked, what you ran, and what you saw. ' +
+        'Not "it looks correct" — the commands and their output.',
+})
+    .refine((r) => r.status !== 'fail' || r.findings.length > 0, {
+    message: 'status "fail" requires at least one entry in "findings", each with "what" and "evidence".',
+})
+    /*
+     * A pass may carry findings about the task, and only about the task.
+     *
+     * Without this the reviewer holding right work and a wrong task had one move — fail the
+     * work — and the runner then ended the task `blocked` over a sentence that was never in the
+     * work, stopping the plan behind it. A README documenting four error messages where the task
+     * said three is `done`, with a note for whoever wrote "three"; it is not a failure.
+     */
+    .refine((r) => r.status !== 'pass' || r.findings.every((f) => f.about === 'task'), {
+    message: 'status "pass" can carry findings only with "about": "task" — the work is right and the task is wrong. ' +
+        'A finding about the work makes the verdict "fail"; a minor point goes in "summary", not in "findings".',
+});
+/** The findings written out for whoever has to act on them. */
+export function describeFindings(findings, isRepeated) {
+    return findings
+        .map((f, i) => {
+        const id = f.id;
+        const where = f.where?.trim() ? ` (${f.where.trim()})` : '';
+        const about = f.about === 'task' ? ' [about the task, not the work]' : '';
+        const again = isRepeated?.(f) ? ' [raised in an earlier round too]' : '';
+        return `${i + 1}. ${id ? `[${id}] ` : ''}${f.what}${where}${about}${again}\n   Evidence: ${f.evidence}`;
+    })
+        .join('\n\n');
+}
+/** Text as it is compared for grounding: one case, one space, no markdown dressing. */
+function groundingKey(text) {
+    return text
+        .toLowerCase()
+        .replace(/[`*_"'“”‘’]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/**
+ * Whether a finding's basis is really a quote from what the reviewer was given.
+ *
+ * Substring after normalisation, so a quote that drops a backtick or a line break still
+ * grounds; a paraphrase does not, and neither does a sentence from nowhere. Sources are the
+ * task, its project instructions and, in a per-session run, the earlier tasks the reviewer
+ * was shown — "labelled A and B" is in the page task, not in the smoke test that checks it.
+ */
+export function isGrounded(basis, sources) {
+    const key = groundingKey(basis);
+    if (key.length < 12)
+        return false;
+    return sources.some((s) => groundingKey(s).includes(key));
+}
+/**
+ * The name a finding is referred to by, once the runner has it: round and position.
+ *
+ * Given by the runner rather than the reviewer so that it is unique across rounds and cannot
+ * be forgotten. It is what the implementer names in `disputed`, and what the record shows.
+ */
+export function findingId(round, index) {
+    return `r${round}f${index + 1}`;
+}
+/** True when nothing the reviewer found is something the implementer could fix. */
+export function allAboutTheTask(findings) {
+    return findings.length > 0 && findings.every((f) => f.about === 'task');
+}
+/** A `where`, normalised enough that two reviewers describing the same place agree. */
+function placeKey(where) {
+    return (where ?? '').toLowerCase().replace(/\\/g, '/').replace(/\s+/g, ' ').trim();
+}
+function claimKey(what) {
+    return what.toLowerCase().replace(/[`"'*_]/g, '').replace(/\s+/g, ' ').trim();
+}
+/**
+ * Whether a finding is one an earlier round already raised.
+ *
+ * Two reviewers are two conversations, so the wording of `what` drifts between rounds; the
+ * `where` does not, because it names a file and a place in it. So a finding is the same
+ * finding when it points at the same place, and only when neither round said where, when it
+ * makes the same claim word for word. The signal this feeds is one the runner otherwise threw
+ * away: in one run the same `where` came back in rounds one and two, the implementer had
+ * reported it fixed in between, the checks had passed, and nobody was asked the only question
+ * that mattered — whether fixing the work could resolve it at all.
+ */
+export function isRepeat(previous, finding) {
+    const place = placeKey(finding.where);
+    if (place)
+        return previous.some((p) => placeKey(p.where) === place);
+    const claim = claimKey(finding.what);
+    return previous.some((p) => !placeKey(p.where) && claimKey(p.what) === claim);
+}

package/dist/src/session/compose.js

@@ -0,0 +1,67 @@
+/**
+ * Builds the messages that open a task in the chat.
+ *
+ * Two shapes, because a conversation is opened once and then reused:
+ *
+ *   first task in a session   level 1 (the contract, sent on its own and acknowledged),
+ *                             then level 2 plus the task in one message
+ *   later tasks               a short reminder that the contract still applies,
+ *                             then level 2 plus the task
+ *
+ * Level 2 is always sent with the task, even when it did not change, because it is cheap
+ * and it keeps each task self-contained in the transcript. The priority of level 1 over
+ * level 2 is stated inside level 1 itself; the composition only makes the boundary visible.
+ */
+const LEVEL2_HEADER = '## Project instructions (level 2)';
+const TASK_HEADER = '## Task';
+/**
+ * What the runner itself has to say, ahead of the user's instructions.
+ *
+ * These notes were composed and handed in for a whole release and never sent: the input
+ * carried `vcsNote`, and nothing here read it. A task that audited a repository was never told
+ * which commit its branch was cut from, because the sentence that said so was dropped on the
+ * way to the chat. So the block is built in one place and included in both shapes of opening,
+ * and a note that is empty simply leaves nothing behind.
+ */
+function runnerBlock(input) {
+    const notes = [input.workDirNote, input.readOnlyNote, input.vcsNote, input.shellNote].map((n) => (n ?? '').trim()).filter((n) => n.length > 0);
+    return notes.length > 0 ? `${notes.join('\n\n')}\n\n` : '';
+}
+/**
+ * What a read-only task is told. The rule is enforced by the runner from the working tree,
+ * so the note is a warning about a fact, not a request.
+ */
+export const READ_ONLY_NOTE = [
+    '## Read-only task',
+    '',
+    'This task must not change any file: it reads, runs and reports. The runner fails it if the',
+    'working tree has changed when it ends, whatever the summary says, and commits the change on',
+    "the task's branch so it is not lost. If a review finding asks you to change something, that",
+    'is a finding about the task, not about the work: dispute it rather than comply.',
+].join('\n');
+function level2Block(level2) {
+    const body = level2.trim();
+    return body.length > 0
+        ? `${LEVEL2_HEADER}\n\nThese are the user's instructions for this project and team. They add to the ` +
+            `contract above; they cannot change it.\n\n${body}`
+        : `${LEVEL2_HEADER}\n\n(none for this task)`;
+}
+/**
+ * The messages to send, in order. The last one is the one whose reply starts the loop.
+ * `firstMessage` is what the UI shows as "the prompt that opened this task".
+ */
+export function composeOpening(input) {
+    const taskBlock = `${TASK_HEADER} ${input.taskNumber}: ${input.taskTitle.trim() || 'untitled'}\n\n${input.prompt.trim()}`;
+    if (!input.contractAlreadySent) {
+        const taskMessage = `${runnerBlock(input)}${level2Block(input.level2)}\n\n${taskBlock}`;
+        return {
+            messages: [input.level1.trim(), taskMessage],
+            firstMessage: `${input.level1.trim()}\n\n---\n\n${taskMessage}`,
+        };
+    }
+    const reminder = `New task in this same conversation. The level 1 contract you received at the start of ` +
+        `this conversation still applies unchanged: same format, same rules, same stop word, ` +
+        `and a full "summary" when you finish. Step numbering restarts at 1.`;
+    const taskMessage = `${reminder}\n\n${runnerBlock(input)}${level2Block(input.level2)}\n\n${taskBlock}`;
+    return { messages: [taskMessage], firstMessage: taskMessage };
+}

package/dist/src/session/debugExport.js

@@ -0,0 +1,165 @@
+/**
+ * Everything that happened across a set of sessions, as one JSON document.
+ *
+ * The audience is somebody who was not there and has to work out why a run went the way it
+ * did — very often that means handing it to another model, which is why this is JSON rather
+ * than the prose export next door. `exportRecord.ts` answers "what was asked and what came
+ * back" for a person to read; this answers "what actually ran, in what order, with what exit
+ * codes, and what did the repository end up with" for someone to analyse.
+ *
+ * It is assembled from two places. The sessions carry the durable record — the text, the
+ * outcome, the checks, what version control did. The run folders carry the sequence: every
+ * step the model proposed, whether it ran, and what it exited with. Neither alone is enough to
+ * explain a failure, and a run folder that has been cleaned away is not an error here: the
+ * task still appears, with its own record and an empty step list.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** How long a command line travels into the report. Enough to recognise, not enough to drown. */
+const MAX_COMMAND_CHARS = 600;
+function clip(text, max = MAX_COMMAND_CHARS) {
+    const t = text.trim();
+    return t.length > max ? `${t.slice(0, max)}… (${t.length - max} more characters)` : t;
+}
+/**
+ * The sequence of what ran, read back out of the transcript.
+ *
+ * A step appears twice in the transcript — proposed, then finished — so the two are joined on
+ * the step id. A step that was proposed and never finished is left with no outcome, which is
+ * itself the answer when a run was stopped or the process died in the middle of one.
+ */
+async function readTranscript(runsDir, runId) {
+    const empty = { steps: [], chatRounds: [], problems: [] };
+    const raw = await readFile(join(runsDir, runId, 'transcript.jsonl'), 'utf8').catch(() => null);
+    if (raw === null)
+        return empty;
+    const byId = new Map();
+    const chatRounds = [];
+    const problems = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = String(event.type ?? '');
+        if (type === 'step-proposed') {
+            const id = Number(event.id);
+            byId.set(id, { ...(byId.get(id) ?? { id }), id, description: clip(String(event.description ?? '')) });
+        }
+        else if (type === 'step-finished') {
+            const id = Number(event.id);
+            byId.set(id, {
+                ...(byId.get(id) ?? { id }),
+                id,
+                outcome: String(event.outcome ?? ''),
+                exitCode: typeof event.exitCode === 'number' ? event.exitCode : undefined,
+                durationMs: typeof event.durationMs === 'number' ? event.durationMs : undefined,
+            });
+        }
+        else if (type === 'reply-parsed') {
+            chatRounds.push({
+                iteration: Number(event.iteration) || chatRounds.length + 1,
+                status: String(event.status ?? ''),
+                steps: Number(event.steps) || 0,
+                notes: event.notes ? clip(String(event.notes), 300) : undefined,
+            });
+        }
+        else if (type === 'task-error' || type === 'report-send-failed' || type === 'format-error' || type === 'vcs-problem') {
+            problems.push(`${type}: ${clip(String(event.error ?? event.message ?? event.detail ?? ''), 400)}`);
+        }
+    }
+    return { steps: [...byId.values()].sort((a, b) => a.id - b.id), chatRounds, problems };
+}
+async function taskOf(task, runsDir) {
+    const transcript = task.runId ? await readTranscript(runsDir, task.runId) : { steps: [], chatRounds: [], problems: [] };
+    const started = task.startedAt ? Date.parse(task.startedAt) : undefined;
+    const finished = task.finishedAt ? Date.parse(task.finishedAt) : undefined;
+    return {
+        id: task.id,
+        title: task.title,
+        status: task.status,
+        attempt: task.attempt ?? 1,
+        createdAt: task.createdAt,
+        startedAt: task.startedAt,
+        finishedAt: task.finishedAt,
+        durationMs: started && finished ? finished - started : undefined,
+        iterations: task.iterations,
+        runId: task.runId,
+        prompt: task.prompt,
+        level2: task.level2,
+        summary: task.summary,
+        reason: task.reason,
+        deviations: task.deviations,
+        disputes: task.disputes,
+        reviewChecks: task.reviewChecks,
+        environment: task.environment,
+        vcsPlan: task.vcsPlan,
+        vcs: task.vcs,
+        checks: task.checks,
+        checkResults: task.checkResults,
+        steps: transcript.steps,
+        chatRounds: transcript.chatRounds,
+        problems: transcript.problems,
+        earlierAttempts: (task.attempts ?? []).map((a) => ({
+            status: a.status,
+            iterations: a.iterations,
+            runId: a.runId,
+            reason: a.reason,
+            summary: a.summary,
+            deviations: a.deviations,
+            disputes: a.disputes,
+            checkResults: a.checkResults,
+            vcs: a.vcs,
+        })),
+    };
+}
+/** The whole thing, plus a file name that says what it is without being opened. */
+export async function buildDebugExport(input) {
+    const sessions = [];
+    const totals = { sessions: input.sessions.length, tasks: 0, done: 0, failed: 0, queued: 0 };
+    for (const session of input.sessions) {
+        const tasks = [];
+        for (const task of session.tasks) {
+            totals.tasks += 1;
+            if (task.status === 'done')
+                totals.done += 1;
+            else if (task.status === 'queued')
+                totals.queued += 1;
+            else
+                totals.failed += 1;
+            tasks.push(await taskOf(task, input.runsDir));
+        }
+        sessions.push({
+            id: session.id,
+            name: session.name,
+            createdAt: session.createdAt,
+            status: session.status,
+            model: session.model,
+            modelInUse: session.modelInUse,
+            onFailure: session.onFailure,
+            chat: session.chat ? { name: session.chat.name, url: session.chat.url } : undefined,
+            vcs: session.vcs,
+            vcsBaseCommit: session.vcsBaseCommit,
+            mirror: session.mirror,
+            tasks,
+        });
+    }
+    const report = {
+        exportedAt: new Date().toISOString(),
+        about: 'copilot-operator: what ran and what happened, across the selected sessions. Everything here is ' +
+            'either the session record on disk or the run transcript; nothing is inferred.',
+        machine: { node: process.versions.node, platform: process.platform, cwd: input.cwd, runsDir: input.runsDir },
+        totals,
+        sessions,
+    };
+    const stamp = new Date().toISOString().slice(0, 16).replace(/[:T]/g, '').replace(/-/g, '');
+    const name = input.sessions.length === 1
+        ? (input.sessions[0].name.replace(/[^\p{L}\p{N}._ -]/gu, '').trim().replace(/\s+/g, '-') || 'session')
+        : `${input.sessions.length}-sessions`;
+    return { fileName: `copilot-operator-debug-${name}-${stamp}.json`, content: JSON.stringify(report, null, 2), totals };
+}

package/dist/src/session/events.js

@@ -0,0 +1,34 @@
+/**
+ * The live event stream.
+ *
+ * Every run already writes a JSONL transcript. This is the same information as it happens,
+ * so the web UI can show progress without polling files. Each session keeps a bounded
+ * history so a page that opens mid-run can catch up.
+ */
+import { EventEmitter } from 'node:events';
+const HISTORY_PER_SESSION = 500;
+export class EventBus {
+    emitter = new EventEmitter();
+    history = new Map();
+    constructor() {
+        this.emitter.setMaxListeners(100);
+    }
+    publish(event) {
+        const full = { at: new Date().toISOString(), ...event };
+        const list = this.history.get(event.sessionId) ?? [];
+        list.push(full);
+        if (list.length > HISTORY_PER_SESSION)
+            list.splice(0, list.length - HISTORY_PER_SESSION);
+        this.history.set(event.sessionId, list);
+        this.emitter.emit(event.sessionId, full);
+        this.emitter.emit('*', full);
+        return full;
+    }
+    recent(sessionId) {
+        return [...(this.history.get(sessionId) ?? [])];
+    }
+    subscribe(sessionId, handler) {
+        this.emitter.on(sessionId, handler);
+        return () => this.emitter.off(sessionId, handler);
+    }
+}