copilot-operator 0.1.0

package/dist/src/protocol/parser.js

@@ -0,0 +1,224 @@
+/**
+ * Turns one Copilot reply into a validated set of steps.
+ *
+ * The input is the **raw markdown** of the reply, obtained by clicking "Copy Response" and
+ * reading the clipboard. It is never the rendered DOM text: code blocks in the Copilot UI are
+ * virtualized and interleave line numbers with the code, and a reply has already been
+ * observed coming back from `innerText` with a chunk of valid JSON simply missing.
+ */
+import { ReplySchema } from './replySchema.js';
+import { ReviewSchema } from './reviewSchema.js';
+/** Every fenced block in a markdown string, with its info string. */
+export function extractFencedBlocks(markdown) {
+    const blocks = [];
+    // Fences of three or more backticks or tildes; the closing fence must be at least as long.
+    const re = /^([ \t]*)(`{3,}|~{3,})[ \t]*([^\n`]*)\n([\s\S]*?)^[ \t]*\2[ \t]*$/gm;
+    let m;
+    while ((m = re.exec(markdown)) !== null) {
+        blocks.push({ lang: (m[3] ?? '').trim().toLowerCase(), body: m[4] ?? '' });
+    }
+    return blocks;
+}
+/**
+ * Strips the line numbers the chat's code widget injects, as a last-resort repair when the
+ * text came from the DOM rather than the clipboard. A line that is nothing but digits, in a
+ * block whose other lines are not, is a gutter number.
+ */
+export function stripLineNumbers(body) {
+    const lines = body.split(/\r?\n/);
+    const numbered = lines.filter((l) => /^\s*\d+\s*$/.test(l)).length;
+    if (numbered < 2 || numbered * 2 < lines.length - numbered)
+        return body;
+    return lines.filter((l) => !/^\s*\d+\s*$/.test(l)).join('\n');
+}
+function findJsonCandidates(markdown) {
+    const blocks = extractFencedBlocks(markdown);
+    const out = [];
+    for (const b of blocks) {
+        if (b.lang === 'json')
+            out.push(b.body);
+    }
+    // Copilot sometimes tags the block `JSON` in the widget but emits no info string.
+    if (out.length === 0) {
+        for (const b of blocks) {
+            if (b.lang === '' && b.body.trimStart().startsWith('{'))
+                out.push(b.body);
+        }
+    }
+    // Nothing fenced at all: fall back to the outermost braces in the reply.
+    if (out.length === 0) {
+        const first = markdown.indexOf('{');
+        const last = markdown.lastIndexOf('}');
+        if (first >= 0 && last > first)
+            out.push(markdown.slice(first, last + 1));
+    }
+    return out;
+}
+/** Removes Copilot's 【n-hash】 citation markers and the whitespace they leave behind. */
+export function stripCitations(text) {
+    if (text === undefined)
+        return undefined;
+    return text.replace(/\s*【[^】]*】/g, '').replace(/[ 	]+$/gm, '').trim();
+}
+export function parseReply(markdown, opts) {
+    const candidates = findJsonCandidates(markdown);
+    if (candidates.length === 0) {
+        return {
+            ok: false,
+            reason: 'no-json-block',
+            detail: 'The reply contained no fenced ```json block and no JSON object at all.',
+        };
+    }
+    const errors = [];
+    for (const raw of candidates) {
+        for (const text of [raw, stripLineNumbers(raw)]) {
+            let value;
+            try {
+                value = JSON.parse(text);
+            }
+            catch (e) {
+                errors.push(`JSON.parse failed: ${e.message}`);
+                continue;
+            }
+            const result = ReplySchema.safeParse(value);
+            if (!result.success) {
+                errors.push(result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; '));
+                continue;
+            }
+            const reply = result.data;
+            // Copilot appends citation markers such as 【1-8313d0】 to prose it grounded in a file.
+            // They mean nothing outside the chat and would otherwise end up in the UI and the log.
+            reply.notes = stripCitations(reply.notes);
+            reply.summary = stripCitations(reply.summary);
+            const steps = reply.steps.map((s) => ({ ...s, shell: s.shell ?? opts.defaultShell }));
+            const markerHit = markdown.includes(opts.stopMarker);
+            const hasSummary = (reply.summary ?? '').trim().length > 0;
+            // The stop word alone is not enough to end a task any more: the summary is the
+            // deliverable, and a marker without one would let a task close with nothing to show.
+            // status "done" already guarantees a summary through the schema.
+            // A reply that gives up says so in `status`, and the stop word cannot override it: a
+            // model that writes "Край" under an explanation of why it cannot finish has ended the
+            // task, not completed it, and reading that as `done` would file a failure as a success.
+            const blocked = reply.status === 'blocked';
+            return {
+                ok: true,
+                reply: { ...reply, steps },
+                done: reply.status === 'done' || (markerHit && hasSummary && !blocked),
+                blocked,
+                json: text.trim(),
+            };
+        }
+    }
+    return {
+        ok: false,
+        reason: 'invalid-json',
+        detail: errors.slice(0, 4).join(' | '),
+    };
+}
+/**
+ * The same job for a reviewing conversation: find the json, validate it, hand it back.
+ *
+ * A sibling of `parseReply` rather than a generalisation of it. The two contracts differ in
+ * what they are allowed to say and in what ends them, and folding them into one parameterised
+ * function would mean every future change to either has to be reasoned about twice. The parts
+ * genuinely in common — finding the block, repairing line numbers, stripping citations — are
+ * shared as they are.
+ *
+ * There is no stop word here. A review ends through its verdict and nothing else, because a
+ * reviewer writing the implementer's stop word is a reviewer quoting the work, not finishing.
+ */
+export function parseReview(markdown, opts) {
+    const candidates = findJsonCandidates(markdown);
+    if (candidates.length === 0) {
+        return {
+            ok: false,
+            reason: 'no-json-block',
+            detail: 'The reply contained no fenced ```json block and no JSON object at all.',
+        };
+    }
+    const errors = [];
+    for (const raw of candidates) {
+        for (const text of [raw, stripLineNumbers(raw)]) {
+            let value;
+            try {
+                value = JSON.parse(text);
+            }
+            catch (e) {
+                errors.push(`JSON.parse failed: ${e.message}`);
+                continue;
+            }
+            const result = ReviewSchema.safeParse(value);
+            if (!result.success) {
+                errors.push(result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; '));
+                continue;
+            }
+            const review = result.data;
+            review.notes = stripCitations(review.notes);
+            review.summary = stripCitations(review.summary);
+            const steps = review.steps.map((x) => ({ ...x, shell: x.shell ?? opts.defaultShell }));
+            return { ok: true, review: { ...review, steps }, verdict: review.status, json: text.trim() };
+        }
+    }
+    return { ok: false, reason: 'invalid-json', detail: errors.slice(0, 4).join(' | ') };
+}
+/** The message sent back when a reply did not validate. Names the problem, nothing else. */
+export function formatErrorMessage(fail, attempt, maxAttempts) {
+    return [
+        `Your last reply did not match the required format (attempt ${attempt} of ${maxAttempts}).`,
+        fail.reason === 'no-json-block'
+            ? 'There was no fenced json code block in it.'
+            : `The json block did not validate: ${fail.detail}`,
+        'Resend the same answer as exactly one fenced code block tagged json, with the fields',
+        'status, steps and notes, and nothing else tagged json in the reply.',
+    ].join(' ');
+}
+/**
+ * Spots a command that arrived damaged rather than badly written.
+ *
+ * Copilot's own output pipeline eats a `[label]:` sequence, apparently reading it the way
+ * markdown reads a link-reference definition. PowerShell writes static calls as
+ * `[math]::Round(...)`, which contains exactly that sequence, so what reaches the runner is
+ * `:Round(...)`. Observed live three iterations in a row, and confirmed from the chat itself:
+ * the mangled form was already on screen, and Copilot's own notes complained that ":Round"
+ * had been emitted instead of "[math]::".
+ *
+ * The damage is not repairable here, because the type name is gone and guessing it would run
+ * a command nobody wrote. So it is detected, refused, and explained back to Copilot.
+ */
+export function findLikelyDamage(command) {
+    // A method call whose type literal has been eaten: `{:Round(`, `= :Round(`, `+ ::Round(`.
+    // `]` and `$name` before the colons are the intact forms, `[math]::Round` and `$m::Round`,
+    // so they must not match.
+    const eaten = /(^|[^\w.$:\]]):{1,2}[A-Za-z_]\w*\s*\(/.exec(command);
+    if (eaten) {
+        return (`"${eaten[0].trim()}" looks like a .NET static call whose type was lost in transit: ` +
+            '`[math]::Round(...)` arrives as `:Round(...)` because the chat consumes `[label]:`');
+    }
+    return null;
+}
+/** What to tell Copilot when a command arrived damaged, with alternatives that survive. */
+export function damageGuidance() {
+    /*
+     * The advice has to cover the call that was actually made, not one example of it.
+     *
+     * It named `[math]::Round` and offered number formatting, because rounding was the first
+     * casualty. A later run lost `[regex]::Escape`, `[regex]::Matches` and `[math]::Min` — and
+     * a model told only how to format a number has nothing to take from that. So the general
+     * rule leads (put the type in a variable, which works for every static call there is), and
+     * the native PowerShell way follows for the shapes that keep coming up.
+     */
+    return [
+        'A command you sent arrived with its type literal missing: `[regex]::Escape(...)` reached',
+        'the runner as `:Escape(...)`. Anything of the form `[name]:` is consumed before it gets',
+        'here, so no .NET static call written that way can survive.',
+        '**The rule that always works: put the type in a variable first, then call through it.**',
+        '`$re = [regex]; $re::Escape($x)` · `$m = [math]; $m::Round($x, 2)` — the variable has no',
+        'bracket before the colons, so nothing eats it. A space before `::` is a syntax error, not',
+        'a workaround.',
+        'Where PowerShell has its own way of doing it, that is shorter and safer still:',
+        'to escape for a match, compare with `-like` or use `.Replace()` and drop the regex;',
+        'to find every match, `Select-String -Pattern ... -AllMatches` and read `.Matches.Groups`;',
+        'for the smallest or largest, `Measure-Object -Minimum -Maximum`;',
+        'to format a number, `"{0:N2}" -f $x` or `$x.ToString("N2")`.',
+    ].join(' ');
+}

package/dist/src/protocol/replySchema.js

@@ -0,0 +1,207 @@
+/**
+ * The contract Copilot must answer in, as a schema.
+ *
+ * The prose version the user pastes into the chat lives in `prompts/level1.md`. This file is
+ * the enforcement: anything that does not validate here is rejected and Copilot is asked to
+ * resend. Being strict is deliberate. A half-understood reply that still parses is worse
+ * than a rejected one, because it runs commands nobody intended.
+ */
+import { z } from 'zod';
+export const ShellSchema = z.enum(['pwsh', 'powershell', 'cmd']);
+const CommandStep = z.object({
+    id: z.number().int().positive(),
+    /*
+     * The only kind of step there is.
+     *
+     * There used to be a second, `download`: the chat attached a file and the runner fetched it and
+     * ran it. That is gone — not disabled, removed — because a process that fetches a file and
+     * executes it is a loader whatever its intentions, and it is what put a security team on the
+     * phone. The message below is what a chat still writing the old form is told, since the reply
+     * comes straight back to it and "invalid literal" would teach it nothing.
+     */
+    type: z.literal('command', {
+        error: 'this runner has no file steps: it never fetches or runs a file the chat provides. Every step is ' +
+            'a `command`. For something too long for one line, write the file with Set-Content in one command ' +
+            'step and run it with its interpreter in the next.',
+    }),
+    shell: ShellSchema.optional(),
+    cmd: z.string().min(1),
+    expect: z.enum(['fast', 'long']).optional(),
+    timeoutSec: z.number().int().positive().optional(),
+    idleTimeoutSec: z.number().int().positive().optional(),
+});
+export const StepSchema = CommandStep;
+/**
+ * The shortest `summary` that counts as an explanation. Below this it is a label, not the
+ * deliverable the user asked for, and the reply is sent back.
+ */
+export const MIN_SUMMARY_CHARS = 40;
+/**
+ * How many different approaches must have been tried before a task may be given up on.
+ *
+ * Two is not a high bar, and that is the point: it is not meant to make giving up hard, it is
+ * meant to make it deliberate. A model that has tried one thing has not found a wall, it has
+ * found a first attempt, and the field forces that distinction to be written down where a
+ * person can read it and disagree.
+ */
+export const MIN_TRIED_APPROACHES = 2;
+/**
+ * One instruction that was not followed as written, and what was done instead.
+ *
+ * The field exists because the alternative was prose, and prose is where two real decisions
+ * went to die in one run. A task required `moduleResolution node`; the TypeScript that
+ * `npm install` fetched had removed it, so the implementer pinned an older TypeScript in one
+ * package of a repository whose other package kept the new one, and said so in `notes`. A task
+ * required `jsx preserve`; `next build` rewrote the file after every run, so the implementer
+ * restored the value after each build, and said so in `notes`. Nobody reads `notes`: not the
+ * reviewer, which is denied the implementer's account on purpose; not the commit message; not
+ * the register. Both were product decisions taken by a model and recorded nowhere anyone
+ * would look.
+ *
+ * As data, a deviation goes three places: onto the task and into the commit, where a person
+ * finds it; and to the reviewer, as a claim to test rather than an account to trust. A true
+ * claim is a finding about the task; a false one is a finding about the work. Either way the
+ * `about: task` path finally has an entrance that does not depend on the reviewer noticing on
+ * its own.
+ */
+export const DeviationSchema = z.object({
+    /** The instruction, quoted or closely paraphrased, so it can be found in the task text. */
+    instruction: z.string().trim().min(1),
+    /** What was done instead. */
+    did: z.string().trim().min(1),
+    /** Why the instruction could not be followed as written: the error, the version, the fact. */
+    why: z.string().trim().min(1),
+});
+/**
+ * A review finding the implementer says is wrong, with what shows it.
+ *
+ * The findings message used to say "if you believe a finding is wrong, say so in your summary
+ * with the evidence" — and the next reviewer never sees the summary, on purpose. So a wrong
+ * finding had no way to be answered: in one run a reviewer searched the page for label text
+ * the task never specified, found none, and the implementer — having objected once, in prose,
+ * to nobody — renamed the labels to match. As data, a dispute goes to the next reviewer as a
+ * claim to test, and to the record. The finding is named by the id the runner gave it.
+ */
+export const DisputeSchema = z.object({
+    /** The finding's id as it was given: `r1f2`. */
+    finding: z.string().trim().min(1),
+    /** Why it is wrong. */
+    why: z.string().trim().min(1),
+    /** What shows it: the command run and what came back, quoted. */
+    evidence: z.string().trim().min(1),
+});
+export const ReplySchema = z
+    .object({
+    /**
+     * How this reply ends the exchange, or does not.
+     *
+     * `continue` — here are steps to run, send me the output.
+     * `done` — the work is finished and verified, and `summary` says so.
+     * `blocked` — the work cannot be finished, and here is what was tried and what is in the way.
+     *
+     * `blocked` exists because the alternative is worse. Without it a model that has run out of
+     * ideas either claims `done` on work it did not do, or keeps sending steps until a limit
+     * cuts it off — and the second one has happened for fifteen iterations at a stretch, each
+     * costing a message, a reply and a report, and ending in a timeout that says nothing about
+     * why. A task that stops with "I tried these three things and this is in the way" is a
+     * result. A task that runs out of iterations is not.
+     */
+    status: z.enum(['continue', 'done', 'blocked']),
+    steps: z.array(StepSchema).default([]),
+    notes: z.string().optional(),
+    /**
+     * Required when `status` is `done` or `blocked`: what was done, in what order, what the
+     * result is, and what the user should know. Shown in the UI as the outcome of the task.
+     */
+    summary: z.string().optional(),
+    /**
+     * Required when `status` is `blocked`: the distinct approaches that were tried, one per
+     * entry. "Ran it again" is not an approach.
+     */
+    tried: z.array(z.string().trim().min(1)).default([]),
+    /** What would unblock it: a decision, a credential, a missing file, a corrected task. */
+    needed: z.string().optional(),
+    /**
+     * Instructions that could not be followed as written, with what was done instead and why.
+     * Accepted on any reply, because a deviation is made when it is made, not at the end; the
+     * runner keeps them for the task and merges repeats by instruction.
+     */
+    deviations: z.array(DeviationSchema).default([]),
+    /**
+     * Review findings the implementer says are wrong, by id, with evidence. Accepted on any
+     * reply; the runner keeps them for the task and hands them to the next reviewer.
+     */
+    disputed: z.array(DisputeSchema).default([]),
+})
+    .refine((r) => r.status !== 'continue' || r.steps.length > 0, {
+    message: 'status "continue" with an empty steps array would stall the run. ' +
+        'Send at least one step, or set status to "done" or "blocked".',
+})
+    .refine((r) => r.status === 'continue' || r.steps.length === 0, {
+    message: 'status "done" and status "blocked" both end the task, so they cannot carry steps. ' +
+        'Send the steps with status "continue" first, then end.',
+})
+    .refine((r) => r.status !== 'done' || (r.summary ?? '').trim().length >= MIN_SUMMARY_CHARS, {
+    message: 'status "done" requires a real summary: several sentences explaining what was done, ' +
+        'what the result is, and what the user should know. Put it in the "summary" field.',
+})
+    .refine((r) => r.status !== 'blocked' || (r.summary ?? '').trim().length >= MIN_SUMMARY_CHARS, {
+    message: 'status "blocked" requires a summary too: what state the work is in, what is done and ' +
+        'what is not, so somebody can pick it up from where you stopped.',
+})
+    .refine((r) => r.status !== 'blocked' || r.tried.length >= MIN_TRIED_APPROACHES, {
+    message: `status "blocked" requires "tried": at least ${MIN_TRIED_APPROACHES} genuinely different ` +
+        'approaches you attempted, one per array entry. Running the same command again is not a ' +
+        'second approach. If you have only tried one thing, try another before giving up.',
+});
+/** What makes two deviations the same one: the instruction, ignoring case and spacing. */
+function deviationKey(d) {
+    return d.instruction.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+/**
+ * The deviations a task has declared so far, with a new reply's merged in.
+ *
+ * A deviation reported in iteration 5 must survive a `done` in iteration 12 that does not
+ * repeat it, and a `done` that does repeat it must not list it twice. The instruction keeps
+ * the wording it was first declared with — that is the one written when it happened — while
+ * `did` and `why` take the latest, so a reason refined as the work goes on is not lost.
+ */
+export function mergeDeviations(existing, incoming) {
+    const merged = new Map();
+    for (const d of [...existing, ...incoming]) {
+        const key = deviationKey(d);
+        merged.set(key, { instruction: merged.get(key)?.instruction ?? d.instruction, did: d.did, why: d.why });
+    }
+    return [...merged.values()];
+}
+/** The deviations written out, for the commit message and the record. */
+export function describeDeviations(deviations) {
+    return deviations
+        .map((d, i) => `${i + 1}. Instruction: ${d.instruction}\n   Did instead: ${d.did}\n   Because: ${d.why}`)
+        .join('\n\n');
+}
+/**
+ * The deviations a task carries after a reply.
+ *
+ * A `continue` adds to the list. A `done` or `blocked` that carries deviations replaces it,
+ * because the closing reply is the final account: a deviation declared mid-way and undone
+ * since — `moduleResolution` set to Node16, then back to `node` once TypeScript was pinned —
+ * stood in the commit as a fact. A closing reply that names none keeps what was declared,
+ * because forgetting to repeat is more common than meaning to retract.
+ */
+export function resolveDeviations(existing, status, incoming) {
+    if (status !== 'continue' && incoming.length > 0)
+        return mergeDeviations([], incoming);
+    return mergeDeviations(existing, incoming);
+}
+/** Disputes so far with a reply's merged in: one per finding id, latest wording wins. */
+export function mergeDisputes(existing, incoming) {
+    const merged = new Map();
+    for (const d of [...existing, ...incoming])
+        merged.set(d.finding.toLowerCase().trim(), d);
+    return [...merged.values()];
+}
+/** The disputes written out, for the record and the next reviewer. */
+export function describeDisputes(disputes) {
+    return disputes.map((d, i) => `${i + 1}. Finding ${d.finding}: ${d.why}\n   Evidence: ${d.evidence}`).join('\n\n');
+}

package/dist/src/protocol/reporter.js

@@ -0,0 +1,75 @@
+/** Never send an attachment without text. This is the fallback if everything else is empty. */
+export const MINIMUM_COVERING_TEXT = 'Ето отговора от терминала. Файлът е прикачен.';
+/**
+ * A non-zero exit with nothing printed at all.
+ *
+ * In PowerShell that is what a cmdlet that found nothing looks like — `Get-NetTCPConnection`
+ * on a free port, `Get-Process` with no match — and the free port is the good outcome. Twice
+ * in one run a step ended this way at the exact moment the task had succeeded, and the model
+ * spent iterations proving with netstat that nothing was wrong. The runner cannot change the
+ * exit code; it can say what it sees.
+ */
+export function silentFailure(r) {
+    return r.outcome === 'completed' && r.exitCode !== 0 && r.stdout.trim() === '' && r.stderr.trim() === '';
+}
+function outcomeSummary(r) {
+    switch (r.outcome) {
+        case 'completed':
+            return silentFailure(r) ? `step ${r.id} exit ${r.exitCode} with no output at all` : `step ${r.id} exit ${r.exitCode}`;
+        case 'hard-timeout':
+            return `step ${r.id} hit its time limit`;
+        case 'idle-timeout':
+            return `step ${r.id} produced no output and was stopped`;
+        case 'aborted':
+            // Exit -4 is `refusedResult`: the runner declined it — a deny pattern, a repeat, damaged
+            // text, a shell that is not here — and it never reached a process. Calling all of those
+            // "aborted by the operator" told the model a person had stopped it, which is a reason to
+            // wait rather than to write the step again, and the reason it could act on was in the
+            // stderr underneath a sentence contradicting it.
+            return r.exitCode === -4 ? `step ${r.id} was not run; see why under it` : `step ${r.id} aborted by the operator`;
+        case 'spawn-error':
+            return `step ${r.id} could not be started`;
+    }
+}
+/**
+ * The covering message. Deliberately short: it can never approach the roughly 120 000
+ * character limit of the composer, because the output it describes is in the attachment.
+ */
+export function buildCoveringMessage(input) {
+    const { task, iteration, results, attachments, parts } = input;
+    const what = task?.trim() ? `"${task.trim()}", iteration ${iteration}` : `iteration ${iteration}`;
+    if (attachments.length === 0) {
+        // Should not happen, but an empty message is unsendable, so never return one.
+        return `${MINIMUM_COVERING_TEXT} (${what}, no file was produced)`;
+    }
+    const lines = [];
+    lines.push(`Terminal output for ${what}: ${results.length} step(s), ` +
+        `${results.map(outcomeSummary).join('; ')}.`);
+    if (parts && parts > 1) {
+        lines.push(`The output is split across ${parts} attached files: ${attachments.join(', ')}. ` +
+            `Read all of them, in order, before deciding the next steps.`);
+    }
+    else {
+        lines.push(`The full output is in the attached file ${attachments[0]}. ` +
+            `Read the whole file before deciding the next steps.`);
+    }
+    const stopped = results.filter((r) => r.outcome === 'idle-timeout' || r.outcome === 'hard-timeout');
+    if (stopped.length > 0) {
+        lines.push(`Note: ${stopped.map((r) => `step ${r.id}`).join(', ')} was stopped by the runner, not by the command itself.`);
+    }
+    const silent = results.filter(silentFailure);
+    if (silent.length > 0) {
+        lines.push(`Note: ${silent.map((r) => `step ${r.id}`).join(', ')} exited non-zero without printing anything. In PowerShell ` +
+            'that is usually a cmdlet that found nothing — a free port, no matching process — not a command that failed. ' +
+            'Decide from what the step was asking, not from the code alone.');
+    }
+    for (const note of input.notes ?? [])
+        lines.push(note);
+    return lines.join(' ');
+}
+/** Guard used right before clicking Send. Throws rather than sending an unsendable message. */
+export function assertSendable(text, attachments) {
+    if (text.trim().length === 0) {
+        throw new Error(`Refusing to send: the composer requires text, and ${attachments.length} attachment(s) alone cannot be sent.`);
+    }
+}