copilot-operator 0.1.13 → 0.1.16

package/dist/src/api/saveToDesktop.js

@@ -29,7 +29,7 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { extname, join } from 'node:path';
-import { resolveDesktopDir } from '../context/contextFiles.js';
+import { resolveDesktopDir } from '../context/desktopDir.js';
 /** The one folder under the Desktop that every saved log lands in. */
 export const LOGS_FOLDER = 'copilot-operator-logs';
 /** The folder every saved log goes into. */

package/dist/src/api/security.js

@@ -33,15 +33,23 @@
  * make the start-up race harder to debug for no gain.
  *
  * The web interface, when this process serves it (an install from npm, `cop start`): its pages are
- * static files and answer without a token — the host check still applies, so a rebound domain gets
+ * static files and are read without a token — the host check still applies, so a rebound domain gets
  * nothing — and every page hands the browser the token as a cookie scoped to `/api`, HttpOnly (no
  * script reads it) and SameSite=Strict (no other site's page sends it). The page's own requests
  * then carry it by themselves, the stream and the downloads included, and no URL ever holds it.
+ * Only a read is a page: a request that writes needs the token whatever its path says, so a path the
+ * guard calls a page and the router calls a route can at worst show something, never start a run.
  *
  * The honest limit, since this is the file somebody will quote: none of this contains a process
  * already running as the operator. It raises the floor from "anything on this machine, and quite a
- * few things off it" to "something that can read a file in the install". The boundary is still the
- * account the runner runs in.
+ * few things off it" to "something that can read a file in the install" — and, wherever the
+ * interface is served, to anything on this machine that can open that port and ask for a page, since
+ * the page is how a browser is given the token. In a package install that is this process's port.
+ * In a clone it is the Next.js dev server `npm start` runs on 127.0.0.1:3210, which this guard does
+ * not stand in front of: the token is built into that page's script (`NEXT_PUBLIC_COP_TOKEN`, see
+ * scripts/dev.mjs), as plain text that anything running in the page can read, where a package's
+ * HttpOnly cookie is out of a script's reach. A clone's API port serving no page of its own closes
+ * one way to the token, not every way. The boundary is still the account the runner runs in.
  */
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
@@ -111,9 +119,30 @@ export function tokenMatches(presented, expected) {
 }
 /** The cookie the served interface is given the token in. */
 export const TOKEN_COOKIE = 'cop_token';
-/** Whether a path is the web interface rather than the API. */
+/**
+ * Whether a path is the web interface rather than the API.
+ *
+ * Compared in lower case, because that is how the router compares it: Express matches a route
+ * without regard to case, so `/API/sessions` is the sessions route. Compared as written, it was a
+ * page to this test and needed no token, and a request with none listed the sessions and started
+ * a run (found on 2026-10-01).
+ */
 export function isInterfacePath(path) {
-    return path !== '/api' && !path.startsWith('/api/');
+    const p = path.toLowerCase();
+    return p !== '/api' && !p.startsWith('/api/');
+}
+/**
+ * Whether a request is a read of the served interface: a page or one of its files.
+ *
+ * The interface is static files, and static files are only ever read, so a request that writes is
+ * not the interface whatever its path is. Keeping the no-token exemption to GET and HEAD means the
+ * next disagreement between this guard and the router about what a path is — a spelling, an
+ * encoding, a prefix nobody thought of — can at worst answer a read, never start a run.
+ * An absent method is a GET, as it is for any request that names none.
+ */
+export function isInterfaceRequest(method, path) {
+    const m = (method ?? 'GET').toUpperCase();
+    return (m === 'GET' || m === 'HEAD') && isInterfacePath(path);
 }
 /** The `Set-Cookie` value that hands a served page the token. */
 export function tokenCookie(token) {
@@ -181,11 +210,12 @@ export function judgeRequest(req, opts) {
     if (!originAllowed(origin, opts.allowedOrigins)) {
         return { ok: false, status: 403, reason: 'origin', detail: `requests from ${origin} are not accepted by this API` };
     }
-    if (OPEN_PATHS.includes(req.path))
+    // In lower case, as the router matches it: `/API/health` is the health route too.
+    if (OPEN_PATHS.includes(req.path.toLowerCase()))
         return { ok: true };
-    // The interface's own files: answered to the right host with no token, since they are how the
+    // The interface's own files: read from the right host with no token, since they are how the
     // browser gets one. Only when this process serves them; see `localApiGuard`.
-    if (opts.servesInterface && isInterfacePath(req.path))
+    if (opts.servesInterface && isInterfaceRequest(req.method, req.path))
         return { ok: true };
     const presented = presentedToken({ headers: req.headers, query: (req.query ?? {}) });
     if (!tokenMatches(presented, opts.token)) {
@@ -213,9 +243,9 @@ export function localApiGuard(opts) {
             next();
             return;
         }
-        const verdict = judgeRequest({ path: req.path, headers: req.headers, query: req.query }, opts);
+        const verdict = judgeRequest({ method: req.method, path: req.path, headers: req.headers, query: req.query }, opts);
         if (verdict.ok) {
-            if (opts.servesInterface && isInterfacePath(req.path))
+            if (opts.servesInterface && isInterfaceRequest(req.method, req.path))
                 res.setHeader('Set-Cookie', tokenCookie(opts.token));
             next();
             return;

package/dist/src/api/server.js

@@ -1,18 +1,45 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
 /**
  * The API server: routes, the guard in front of them, the data folder's permissions, recovery of
  * whatever the previous process left running. See `main.ts` for the process around it.
  */
 import 'reflect-metadata';
-import { NestFactory } from '@nestjs/core';
+import { Catch, ConflictException } from '@nestjs/common';
+import { BaseExceptionFilter, NestFactory } from '@nestjs/core';
 import { join } from 'node:path';
 import { AppModule } from './app.module.js';
 import { OperatorService } from './operator.service.js';
+import { SettingsUnusableError } from './settings.js';
+import { PolicyLockUnusableError } from '../config/lockedPolicy.js';
 import { ensureApiToken, localApiGuard } from './security.js';
 import { secureDataDir } from './dataAcl.js';
 import { pruneRuns } from '../session/retention.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { installLayout } from '../config/layout.js';
+/**
+ * A settings file, or a policy lock, that cannot be used, answered the same way on every route: 409,
+ * with the message that names the file and says what to do (see `SettingsUnusableError` and
+ * `PolicyLockUnusableError`).
+ *
+ * Here, once, because the routes that meet it are most of them: every one whose work reads the
+ * settings, and reading the settings reads the locks. Left to the default it was "Internal server
+ * error" wherever a route did not wrap its errors, which included the Defaults page, the Project
+ * page and the model picker; a broken lock was that on the System page as well, until 2026-10-01.
+ */
+let SettingsUnusableFilter = class SettingsUnusableFilter extends BaseExceptionFilter {
+    catch(e, host) {
+        super.catch(new ConflictException(e.message), host);
+    }
+};
+SettingsUnusableFilter = __decorate([
+    Catch(SettingsUnusableError, PolicyLockUnusableError)
+], SettingsUnusableFilter);
 /**
  * Everything `main` used to do, as a function that returns the running server instead of owning the
  * process. `main.ts` calls it and turns a failure into an exit code; the end-to-end checks call it
@@ -43,6 +70,7 @@ export async function startApi(opts = {}) {
         exposedHeaders: ['content-disposition'],
     });
     app.setGlobalPrefix('api');
+    app.useGlobalFilters(new SettingsUnusableFilter(app.getHttpAdapter()));
     /*
      * Who may drive this. Mounted before routing so it covers every route including the SSE stream,
      * and so that no controller has to remember. See `security.ts` for why "it is only on localhost"
@@ -76,17 +104,26 @@ export async function startApi(opts = {}) {
         // The prebuilt interface, from the package: one process, one port, no dev server.
         app.useStaticAssets(webDir, { extensions: ['html'], index: 'index.html' });
     }
+    /*
+     * The settings, read before the port is open and before anything the last process left is
+     * recovered. A file the API cannot use stops it here, with the reason; read after the recovery,
+     * it stopped the API once the tasks were already marked aborted but not yet settled (their record
+     * goes in the runs folder the file names), and nothing comes back to settle them.
+     */
+    const ops = app.get(OperatorService);
+    const cfg = await ops.settings.load().catch(async (e) => {
+        await app.close();
+        throw e;
+    });
     await app.listen(PORT, '127.0.0.1');
     // Close whatever the previous process left open before anyone can look at it, rather than
     // waiting for the first request to trigger it.
-    const ops = app.get(OperatorService);
     await ops.bootstrap();
     /*
      * runs/ holds every step's raw output and, on a failure, a screenshot of the signed-in page —
      * as much the bot's records as data/ is, and until 2026-09-27 left with whatever permissions its
      * parent folder had. Narrowed the same way, and pruned to the configured retention.
      */
-    const cfg = await ops.settings.load();
     await mkdir(cfg.resolved.runsDir, { recursive: true });
     const runsAcl = secureDataDir(cfg.resolved.runsDir);
     if (!runsAcl.ok) {
@@ -101,14 +138,40 @@ export async function startApi(opts = {}) {
     const pruned = await pruneRuns(cfg.resolved.runsDir, cfg.runsRetentionDays);
     if (pruned.length > 0)
         log(`  removed ${pruned.length} run folder(s) older than ${cfg.runsRetentionDays} days (runsRetentionDays)`);
-    if (layout.webDir) {
-        log(`copilot-operator is running for ${layout.projectRoot}`);
-        log(`  open http://127.0.0.1:${PORT}/ in your browser`);
-        log(`  records are kept in ${layout.homeDir}`);
-    }
-    else {
-        log(`copilot-operator api listening on http://127.0.0.1:${PORT}/api  (web origin ${WEB_ORIGIN})`);
-        log(`  requests need the token in ${join(dataDir, 'api-token')}; npm start hands it to the UI`);
-    }
+    const lines = startupLines({
+        served: webDir !== null,
+        mode: layout.mode,
+        port: PORT,
+        webOrigin: WEB_ORIGIN,
+        projectRoot: layout.projectRoot,
+        homeDir: layout.homeDir,
+        tokenFile: join(dataDir, 'api-token'),
+    });
+    for (const line of lines)
+        log(line);
     return { app, port: PORT, token, dataDir, close: () => app.close() };
 }
+/**
+ * What the start-up tells the operator to open. Said by what is served, not by what the layout
+ * found, so the lines match the guard's choice in `startApi`.
+ *
+ * A clone's API serves no page, and `cop start` run in a clone ends up here as well as `npm start`
+ * does, so a clone's lines name the dev server that holds its interface. Without that, the only
+ * address in sight was this port, which answers a browser with a 401.
+ */
+export function startupLines(o) {
+    if (o.served) {
+        return [
+            `copilot-operator is running for ${o.projectRoot}`,
+            `  open http://127.0.0.1:${o.port}/ in your browser`,
+            `  records are kept in ${o.homeDir}`,
+        ];
+    }
+    const lines = [
+        `copilot-operator api listening on http://127.0.0.1:${o.port}/api  (web origin ${o.webOrigin})`,
+        `  requests need the token in ${o.tokenFile}; npm start hands it to the UI`,
+    ];
+    if (o.mode === 'checkout')
+        lines.push(`  this port serves no web interface: a clone's is the dev server npm start runs, at ${o.webOrigin}`);
+    return lines;
+}

package/dist/src/api/settings.js

@@ -4,10 +4,83 @@
  * The UI edits this file through the API. Anything not present falls back to the schema
  * defaults, so an empty file is a valid, safe configuration.
  */
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
-import { loadConfigObject } from '../config/schema.js';
+import { loadConfigObject, RunConfigSchema } from '../config/schema.js';
+import { readHandWritten } from '../config/handWritten.js';
+import { writeFileAtomically } from '../session/store.js';
+/**
+ * A settings file that is there and cannot be used: it cannot be read, it is not JSON, it is not an
+ * object of settings, or the schema refuses what it holds.
+ *
+ * Its own class because it is not the fault of the request that meets it, and every request that
+ * reads the settings meets it, not only the saves. As a plain error it was "Internal server error"
+ * on the Defaults page, the Project page and the model picker, the very pages the operator opens to
+ * find out what is wrong. The server answers this one the same way on every route, with this
+ * message (see `server.ts`), and `cop doctor` says it too, since the API will not start on it.
+ */
+export class SettingsUnusableError extends Error {
+    path;
+    problem;
+    constructor(path, 
+    /** What is wrong, said of the file: "is not valid JSON (…)". */
+    problem) {
+        // What every refusal says, so the way out is in the same message.
+        super(`${path} ${problem}. Mend it, or delete it to start again from the defaults; nothing has been saved over it.`);
+        this.path = path;
+        this.problem = problem;
+        this.name = 'SettingsUnusableError';
+    }
+}
+/**
+ * The text of a settings file as settings: `{}` when it is empty, an error when it is not an object
+ * of settings. The one reading of the file, for the API and for `cop doctor`, so the two cannot
+ * disagree about whether it is broken.
+ *
+ * A file that is there but cannot be read as settings is an error, never `{}`. Read as empty, it
+ * was written over by the next save of one setting — choosing a default model rewrote it as
+ * `{copilot: {defaultModel}}` — and everything else the operator had set was gone, without a word
+ * or a copy, while the program ran on the defaults in the meantime: another runs folder, no project,
+ * the stock limits.
+ */
+export function parseSettings(text, path) {
+    // A file saved by hand in Notepad or Windows PowerShell may start with a byte-order mark, which
+    // JSON.parse refuses; it is not part of the settings, and the file is not broken. Read through
+    // `readHandWritten`, the mark has gone already and said how the file is encoded, UTF-16 included;
+    // a text handed here with the mark still on it is read the same.
+    const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+    if (body.trim() === '')
+        return {};
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch (e) {
+        throw new SettingsUnusableError(path, `is not valid JSON (${e.message})`);
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new SettingsUnusableError(path, 'does not hold an object of settings');
+    }
+    return value;
+}
+/**
+ * Refuses settings the schema does not allow, as a problem of the file they were read from. For
+ * what is on disk, never for a request's own edit, which is the request's problem (see `save`).
+ */
+export function checkSettings(value, path) {
+    const parsed = RunConfigSchema.safeParse(value);
+    if (parsed.success)
+        return;
+    const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+    throw new SettingsUnusableError(path, `holds settings that are not allowed (${issues})`);
+}
+/**
+ * The settings of this install, with the defaults its layout implies: the one way they are built,
+ * for the API and for `cop doctor`, so the doctor reads them as the API that it vouches for will.
+ */
+export function settingsOf(layout) {
+    return new Settings(layout.projectRoot, layout.dataDir, layout.mode === 'package' ? { runsDir: layout.runsDir, level1File: join(layout.promptsDir, 'level1.md') } : {});
+}
 export class Settings {
     projectRoot;
     dataDir;
@@ -25,27 +98,95 @@ export class Settings {
         this.installDefaults = installDefaults;
         this.path = join(dataDir, 'settings.json');
     }
-    /** The raw object as saved, or `{}` when there is no file yet. */
+    /**
+     * The raw object as saved, or `{}` when there is no file yet (or an empty one). A file that is
+     * there and is not settings is refused by name (see `parseSettings`) until the operator mends it
+     * or deletes it.
+     */
     async raw() {
-        if (!existsSync(this.path))
-            return {};
+        let text;
         try {
-            return JSON.parse(await readFile(this.path, 'utf8'));
+            text = await readHandWritten(this.path);
         }
-        catch {
-            return {};
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return {};
+            throw new SettingsUnusableError(this.path, `could not be read (${e.message})`);
         }
+        return parseSettings(text, this.path);
     }
-    /** Parsed, defaulted and resolved against the project root. */
+    /**
+     * Parsed, defaulted and resolved against the project root.
+     *
+     * A file whose values the schema refuses stops here with the reason, as it always has; it is the
+     * file's problem, not the request's, so it is refused as one (see `SettingsUnusableError`).
+     * Anything else that stops the load is not this file's, and goes on as it is: a policy lock that
+     * does not parse is a `PolicyLockUnusableError`, answered by name on every route as this one is.
+     */
     async load() {
-        const raw = await this.raw();
-        return await loadConfigObject({ ...this.installDefaults, ...raw, dataDir: this.dataDir }, this.projectRoot, this.path);
+        const value = { ...this.installDefaults, ...(await this.raw()), dataDir: this.dataDir };
+        try {
+            return await loadConfigObject(value, this.projectRoot, this.path);
+        }
+        catch (e) {
+            checkSettings(value, this.path);
+            throw e;
+        }
     }
-    /** Validates before saving, so a bad edit is rejected rather than stored. */
+    /**
+     * Validates before saving, so a bad edit is rejected rather than stored.
+     *
+     * A file on disk that cannot be read is not written over either, even by a whole set of
+     * settings: the page that sends one built it on a copy read before the file broke, and whatever
+     * the operator has put in the file since, by hand, would go without a word, which is the silent
+     * replacement `raw` refuses, by another route.
+     */
     async save(value) {
-        const resolved = await loadConfigObject({ ...this.installDefaults, ...value, dataDir: this.dataDir }, this.projectRoot, this.path);
+        return await this.write(() => value, 'replaces');
+    }
+    /**
+     * Changes part of the settings: `change` is given what the file holds and returns all of it, as
+     * it is to be saved.
+     *
+     * For a save of one setting (the default model, the review model, the project), which must keep
+     * every other. The read and the write are one turn on the file, so two such saves at once each
+     * change what the other left: read before the turn, both read the same file, and the one written
+     * second put back the setting the first had just changed, though both answered 200. `change` is
+     * synchronous so it cannot wait for the file's turn from inside it; it may throw to refuse, and
+     * then nothing is written.
+     */
+    async update(change) {
+        return await this.write(change, 'keeps');
+    }
+    /**
+     * The one way the file is written: read, changed, validated and replaced in the file's turn (see
+     * `writeFileAtomically`). The read refuses a file that cannot be read, so nothing is ever saved
+     * over one. The write is atomic, because a crash in the middle of a plain write is one way a
+     * settings file stops parsing.
+     */
+    async write(next, rest) {
         await mkdir(dirname(this.path), { recursive: true });
-        await writeFile(this.path, JSON.stringify(value, null, 2), 'utf8');
+        let resolved;
+        await writeFileAtomically(this.path, async () => {
+            const raw = await this.raw();
+            const value = next(raw);
+            try {
+                resolved = await loadConfigObject({ ...this.installDefaults, ...value, dataDir: this.dataDir }, this.projectRoot, this.path);
+            }
+            catch (e) {
+                /*
+                 * A save of one setting carries every other over from the file, so a value the schema
+                 * refuses that was in the file already is refused again here. That is the file's problem,
+                 * as `load` says of it, not the request's: it was answered as a bad request that blamed the
+                 * new default model, without the way out, while a read of the same file named it. A whole
+                 * set replaces what the file holds, and what the schema refuses in it is the request's own.
+                 */
+                if (rest === 'keeps')
+                    checkSettings({ ...this.installDefaults, ...raw, dataDir: this.dataDir }, this.path);
+                throw e;
+            }
+            return JSON.stringify(value, null, 2);
+        });
         return resolved;
     }
     /** The schema defaults, for the UI to show what "not set" means. */