toolroll 0.5.0

package/dist/session-http.js

@@ -0,0 +1,154 @@
+import { SESSION_REQUEST_BYTES, SESSION_RESPONSE_BYTES, isSessionResponse, sessionDescriptor, validateSessionRequest, } from './session-contract.js';
+function readBody(request) {
+    return new Promise(resolve => {
+        let size = 0;
+        let chunks = [];
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            chunks = [];
+            resolve(result);
+        };
+        const cleanup = () => {
+            request.off('data', onData);
+            request.off('end', onEnd);
+            request.off('aborted', onAborted);
+            request.off('error', onError);
+            request.off('close', onClose);
+        };
+        const onData = (chunk) => {
+            // After rejecting an oversized request, drain without retaining it.
+            if (settled)
+                return;
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            size += bytes.length;
+            if (size > SESSION_REQUEST_BYTES)
+                finish({ ok: false, status: 413, reason: 'request-too-large', message: 'The session request is too large.' });
+            else
+                chunks.push(bytes);
+        };
+        const onEnd = () => {
+            cleanup();
+            if (settled)
+                return;
+            try {
+                const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+                finish({ ok: true, value });
+            }
+            catch {
+                finish({ ok: false, status: 400, reason: 'invalid-json', message: 'Send a valid UTF-8 JSON request.' });
+            }
+        };
+        const onAborted = () => {
+            finish({ ok: false, status: 400, reason: 'incomplete-request', message: 'The session request did not finish arriving.' });
+        };
+        const onError = () => { onAborted(); cleanup(); };
+        const onClose = () => { onAborted(); cleanup(); };
+        request.on('data', onData);
+        request.once('end', onEnd);
+        request.once('aborted', onAborted);
+        request.once('error', onError);
+        request.once('close', onClose);
+        if (request.aborted)
+            onAborted();
+    });
+}
+/** Handle this API family before the browser's form parser or login redirects.
+ * This adapter dispatches at most once. It owns no catalog, database or provider. */
+export async function handleSessionHttp(request, response, options) {
+    const path = (request.url ?? '').split('?')[0] ?? '';
+    if (path !== '/api/sessions' && !path.startsWith('/api/sessions/'))
+        return false;
+    const match = /^\/api\/sessions\/([a-z]+)$/.exec(request.url ?? '');
+    const spec = match?.[1] === undefined ? undefined : sessionDescriptor(match[1]);
+    const operation = spec?.operation;
+    const write = (status, body, notSent = false) => {
+        if (response.destroyed || response.writableEnded)
+            return;
+        response.statusCode = status;
+        response.setHeader('content-type', 'application/json; charset=utf-8');
+        response.setHeader('content-length', Buffer.byteLength(body));
+        response.setHeader('cache-control', 'no-store');
+        response.setHeader('x-content-type-options', 'nosniff');
+        if (notSent)
+            response.setHeader('x-standing-orders-session-delivery', 'not-sent');
+        else
+            response.removeHeader('x-standing-orders-session-delivery');
+        response.end(body);
+    };
+    const reject = (status, reason, message) => {
+        // No owner call has occurred. This marker is never inferred from an
+        // exception, a lost response, or a response too large to deliver.
+        const reply = { version: 1, ...(operation === undefined ? {} : { operation }), ok: false,
+            status: 'rejected', delivery: 'not-sent', retry: spec?.mutation === false ? 'safe-read' : 'never', reason, message, nextActions: [] };
+        write(status, JSON.stringify(reply), true);
+        request.resume();
+        return true;
+    };
+    if (!spec || operation === undefined)
+        return reject(404, 'unsupported-operation', 'This session operation is not supported.');
+    if (request.method !== 'POST') {
+        response.setHeader('allow', 'POST');
+        return reject(405, 'method-not-allowed', 'Session operations require POST.');
+    }
+    if (request.headers.origin !== undefined)
+        return reject(403, 'browser-request', 'Use the authenticated session client for this operation.');
+    const authorizationCount = request.rawHeaders.filter((_, index) => index % 2 === 0 && request.rawHeaders[index]?.toLowerCase() === 'authorization').length;
+    if (authorizationCount !== 1 || !/^Bearer (.+):(.+)$/.test(request.headers.authorization ?? '')) {
+        return reject(401, 'unauthenticated', 'Current operator bearer credentials are required.');
+    }
+    let actor;
+    try {
+        actor = await options.authenticate(request);
+    }
+    catch {
+        return reject(503, 'authentication-unavailable', 'Operator access could not be checked. Try again after the service is ready.');
+    }
+    if (actor === null || typeof actor.name !== 'string' || !actor.name.trim() || !Number.isSafeInteger(actor.generation) || actor.generation < 1) {
+        return reject(401, 'unauthenticated', 'Current operator bearer credentials are required.');
+    }
+    const media = request.headers['content-type']?.split(';')[0]?.trim().toLowerCase();
+    if (media !== 'application/json')
+        return reject(415, 'unsupported-media-type', 'Send the session request as application/json.');
+    const length = request.headers['content-length'];
+    if (length !== undefined && Number(length) > SESSION_REQUEST_BYTES)
+        return reject(413, 'request-too-large', 'The session request is too large.');
+    if (options.execute === null)
+        return reject(503, 'session-unavailable', 'The session owner is not ready.');
+    const body = await readBody(request);
+    if (!body.ok)
+        return reject(body.status, body.reason, body.message);
+    const validated = validateSessionRequest(operation, body.value);
+    if (!validated.ok)
+        return reject(400, 'invalid-request', validated.message);
+    if (request.aborted || response.destroyed)
+        return true;
+    const uncertain = (reason, message) => {
+        const sessionId = 'sessionId' in validated.request ? validated.request.sessionId : undefined;
+        return { version: 1, operation, ok: false, status: 'uncertain', delivery: 'unknown', retry: 'inspect-first', reason, message,
+            nextActions: [{ operation: sessionId ? 'show' : 'list', label: sessionId ? 'Inspect session' : 'Inspect saved sessions', ...(sessionId ? { sessionId } : {}) }] };
+    };
+    let reply;
+    let encoded;
+    let status;
+    try {
+        reply = await options.execute(actor, operation, validated.request);
+        if (!isSessionResponse(reply, operation))
+            throw new Error('Invalid owner response');
+        encoded = JSON.stringify(reply);
+        if (Buffer.byteLength(encoded) > SESSION_RESPONSE_BYTES) {
+            reply = uncertain('response-too-large', 'The owner response is too large to deliver. Inspect saved activity before continuing; this request was not retried.');
+            encoded = JSON.stringify(reply);
+        }
+        status = reply.status === 'rejected' ? 409 : reply.status === 'uncertain' ? 502 : reply.status === 'pending' ? 202 : 200;
+    }
+    catch {
+        reply = uncertain('unconfirmed-response', 'The owner response could not be confirmed. Inspect saved activity before continuing; this request was not retried.');
+        encoded = JSON.stringify(reply);
+        status = 502;
+    }
+    write(status, encoded);
+    return true;
+}

package/dist/session-server.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Store } from './store.js';
+import type { CodingWorkspace } from './coding-workspace.js';
+/** Bind the transport to createDecisionServer's existing catalog owner and
+ * live project admission. No cookie, coordinator token or caller-supplied actor
+ * can acquire installation-wide native coding authority through this adapter. */
+export declare function createSessionEndpoint(options: {
+    store: Store;
+    workspace: CodingWorkspace | null;
+    projects: () => readonly string[];
+    projectAllowed: (repo: string) => boolean;
+}): (request: IncomingMessage, response: ServerResponse) => Promise<boolean>;

package/dist/session-server.js

@@ -0,0 +1,37 @@
+import { realpathSync } from 'node:fs';
+import { authenticateAccount } from './scope.js';
+import { handleSessionHttp } from './session-http.js';
+import { SessionService } from './session-service.js';
+/** Bind the transport to createDecisionServer's existing catalog owner and
+ * live project admission. No cookie, coordinator token or caller-supplied actor
+ * can acquire installation-wide native coding authority through this adapter. */
+export function createSessionEndpoint(options) {
+    const { store } = options;
+    const authorized = (actor, repo) => {
+        const account = store.accountOf(actor.name);
+        return account !== null && account.revokedAt === null && account.generation === actor.generation && store.isInstanceOperator(actor.name)
+            && (repo === undefined || (options.projectAllowed(repo) && options.projects().includes(repo)));
+    };
+    const service = options.workspace === null || store.isDemo() ? null : new SessionService({ workspace: options.workspace, authorized,
+        project: (actor, input) => {
+            const path = realpathSync(input);
+            if (!authorized(actor, path) || !options.projects().includes(path))
+                throw Error('Choose a project already admitted to this installation.');
+            return path;
+        },
+    });
+    return (request, response) => handleSessionHttp(request, response, {
+        authenticate: request => {
+            const bearer = /^Bearer (.+):(.+)$/.exec(request.headers.authorization ?? '');
+            if (!bearer)
+                return null;
+            const name = bearer[1];
+            const authentication = authenticateAccount(store, name, bearer[2]);
+            if (!authentication.ok)
+                return null;
+            const actor = { name, generation: authentication.generation };
+            return authorized(actor) ? actor : null;
+        },
+        execute: service === null ? null : (actor, operation, request) => service.execute(actor, operation, request),
+    });
+}

package/dist/session-service.d.ts

@@ -0,0 +1,22 @@
+import { CodingWorkspace, type CodingActor } from './coding-workspace.js';
+import { type SessionOperation, type SessionResponse } from './session-contract.js';
+type Options = {
+    workspace: CodingWorkspace;
+    /** Recheck the live account generation and installation-wide operator role. */
+    authorized: (actor: CodingActor, repo?: string) => boolean;
+    /** Resolve only an admitted project. Never accept an arbitrary filesystem path. */
+    project: (actor: CodingActor, project: string) => string;
+};
+/** A narrow projection and operation boundary shared by authenticated adapters.
+ * This object never opens a second catalog or starts a competing provider. */
+export declare class SessionService {
+    private readonly options;
+    constructor(options: Options);
+    private authorize;
+    private view;
+    private next;
+    private inspect;
+    private result;
+    execute<O extends SessionOperation>(actor: CodingActor, operation: O, value: unknown): Promise<SessionResponse>;
+}
+export {};

package/dist/session-service.js

@@ -0,0 +1,157 @@
+import { realpathSync } from 'node:fs';
+import { CodingActionError, CodingWorkspace } from './coding-workspace.js';
+import { sessionDescriptor, validateSessionRequest } from './session-contract.js';
+import { savedSessionBrief } from './session-brief.js';
+const mutationMessages = { start: 'Session started.', send: 'Message delivered.', stop: 'Stop requested.', resume: 'Session reconnected.', recover: 'Saved activity reconciled. Inspect the current state before continuing.' };
+const expectedOf = (input) => ({ revision: input.expectedRevision, nativeThreadId: input.expectedThreadId, turnId: input.expectedTurnId });
+/** A narrow projection and operation boundary shared by authenticated adapters.
+ * This object never opens a second catalog or starts a competing provider. */
+export class SessionService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    authorize(actor, repo) {
+        if (!this.options.authorized(actor, repo))
+            throw new CodingActionError('This operation requires current operator access to the project.', 'rejected');
+    }
+    view(actor, id) {
+        const session = this.options.workspace.get(id, actor);
+        this.authorize(actor, session.repo);
+        return { id: session.id, repo: session.repo, title: session.title, status: session.status,
+            nativeThreadId: session.nativeThreadId, turnId: session.turnId,
+            revision: this.options.workspace.revision(id, actor), branch: session.branch, base: session.base,
+            error: session.error, deliveryReviewRequired: session.deliveryReviewRequired === true, updatedAt: session.updatedAt };
+    }
+    next(session) {
+        if (!session)
+            return [{ operation: 'list', label: 'Inspect sessions' }];
+        const sessionId = session.id;
+        const read = [{ operation: 'show', label: 'Inspect session', sessionId }, { operation: 'changes', label: 'Review changes', sessionId }];
+        if (session.deliveryReviewRequired || session.status === 'needs-input')
+            return [{ operation: 'open-ui', label: session.deliveryReviewRequired ? 'Review uncertain delivery' : 'Answer in the workspace', sessionId }, ...read];
+        if (session.status === 'uncertain')
+            return [{ operation: 'recover', label: 'Reconcile saved activity', sessionId }, ...read];
+        if (session.status === 'interrupted')
+            return [{ operation: 'resume', label: 'Reconnect session', sessionId }, ...read];
+        if (session.status === 'ready')
+            return [{ operation: 'send', label: 'Continue session', sessionId }, ...read];
+        if (session.status === 'working')
+            return [...read, { operation: 'send', label: 'Send a follow-up', sessionId }, { operation: 'stop', label: 'Stop this turn', sessionId }];
+        return read;
+    }
+    inspect(session) {
+        if (!session)
+            return [{ operation: 'list', label: 'Inspect saved sessions' }];
+        const sessionId = session.id;
+        const next = [{ operation: 'show', label: 'Inspect saved session', sessionId }, { operation: 'changes', label: 'Review changes', sessionId }];
+        if (session.deliveryReviewRequired || session.status === 'needs-input')
+            next.push({ operation: 'open-ui', label: session.deliveryReviewRequired ? 'Review uncertain delivery' : 'Answer in the workspace', sessionId });
+        else if (session.status === 'uncertain')
+            next.push({ operation: 'recover', label: 'Reconcile saved activity', sessionId });
+        return next;
+    }
+    result(actor, id, activity = false) {
+        const snapshot = this.options.workspace.snapshotBounded(id, actor), session = this.view(actor, id);
+        // Keep recent context and explicitly label omitted history. Native history
+        // remains authoritative; this bounded transport is not a memory rewrite.
+        let remaining = 1_000_000;
+        const items = [];
+        for (const item of snapshot.items.slice(-100).reverse()) {
+            const bytes = Buffer.byteLength(JSON.stringify(item));
+            if (bytes > remaining)
+                break;
+            items.unshift(item);
+            remaining -= bytes;
+        }
+        const requests = snapshot.requests.slice(0, 50).map(({ id, kind, title, detail }) => ({ id, kind, title: title.slice(0, 1000), detail: detail.slice(0, 8000) }));
+        const next = this.next(session)[0]?.label ?? 'Inspect session';
+        const truncated = snapshot.truncated || items.length !== snapshot.items.length || requests.length !== snapshot.requests.length || snapshot.requests.some(request => request.title.length > 1000 || request.detail.length > 8000);
+        return { session, ...(activity ? { items, requests } : {}), truncated, brief: savedSessionBrief(session, items, next, truncated) };
+    }
+    async execute(actor, operation, value) {
+        const rejected = (message, reason) => ({ version: 1, operation, ok: false, status: 'rejected', delivery: 'not-sent', retry: 'never', message, reason, nextActions: [] });
+        const validation = validateSessionRequest(operation, value);
+        if (!validation.ok)
+            return rejected(validation.message, 'invalid-request');
+        const input = validation.request;
+        const workspace = this.options.workspace;
+        let deliveryMayHaveOccurred = false;
+        try {
+            this.authorize(actor);
+            if (operation === 'list') {
+                const request = input;
+                const repo = request.project ? this.options.project(actor, request.project) : undefined;
+                const page = workspace.listBounded(actor, { limit: request.limit ?? 50, ...(repo === undefined ? {} : { repo }), authorized: project => this.options.authorized(actor, project) });
+                const sessions = page.sessions.map(s => this.view(actor, s.id));
+                return { version: 1, operation, ok: true, status: 'succeeded', delivery: 'confirmed', retry: 'safe-read', message: `${sessions.length} sessions${page.truncated ? ' shown; more may be available' : ''}.`, nextActions: [], result: { sessions, truncated: page.truncated } };
+            }
+            if (operation === 'show' || operation === 'changes') {
+                const { sessionId } = input;
+                this.view(actor, sessionId);
+                const changes = operation === 'changes' ? await workspace.changes(sessionId, actor) : undefined;
+                const result = this.result(actor, sessionId, operation === 'show' && input.view === 'activity');
+                if (changes)
+                    result.changes = changes;
+                return { version: 1, operation, ok: true, status: 'succeeded', delivery: 'confirmed', retry: 'safe-read', message: 'Saved session loaded.', nextActions: this.next(result.session), result };
+            }
+            const request = input;
+            let repo;
+            if (operation === 'start') {
+                repo = realpathSync(this.options.project(actor, request.project));
+                this.authorize(actor, repo);
+            }
+            else
+                this.view(actor, request.sessionId);
+            // Stable field order makes a JSON field-order difference the same request.
+            const fingerprint = JSON.stringify([operation, Object.keys(request).sort().map(k => [k, request[k]]), repo ?? null]);
+            const receipt = await workspace.command(actor, request.key, fingerprint, () => this.authorize(actor, repo), async () => {
+                const sessionId = operation === 'start' ? null : request.sessionId;
+                try {
+                    this.authorize(actor, repo);
+                    if (sessionId) {
+                        this.view(actor, sessionId);
+                        workspace.assertExpected(sessionId, actor, expectedOf(request));
+                    }
+                }
+                catch (error) {
+                    throw error instanceof CodingActionError ? error : new CodingActionError(error instanceof Error ? error.message : 'This session is unavailable.', 'rejected', sessionId ?? undefined);
+                }
+                deliveryMayHaveOccurred = true;
+                if (operation === 'start') {
+                    const start = request;
+                    return (await workspace.start(actor, { repo: repo, title: start.title, prompt: start.prompt, model: start.model ?? null, requestId: start.key })).id;
+                }
+                const expected = expectedOf(request);
+                if (operation === 'send')
+                    await workspace.send(sessionId, actor, request.prompt, request.key, expected);
+                else if (operation === 'stop')
+                    await workspace.stop(sessionId, actor, expected);
+                else if (operation === 'resume')
+                    await workspace.resume(sessionId, actor, expected);
+                else if (operation === 'recover')
+                    await workspace.recover(sessionId, actor, expected);
+                return sessionId;
+            });
+            // A replay reads a prior receipt without performing again. Losing access
+            // or failing to project that result cannot prove the original was unsent.
+            deliveryMayHaveOccurred ||= receipt.status !== 'rejected';
+            const id = receipt.sessionId ?? (operation === 'start' ? undefined : request.sessionId);
+            const result = { ...(id ? this.result(actor, id) : {}), receipt: { key: request.key, status: receipt.status } };
+            const status = receipt.status === 'accepted' ? 'succeeded' : receipt.status === 'pending' && result.session ? 'pending' : receipt.status === 'rejected' ? 'rejected' : 'uncertain';
+            const nextActions = status === 'pending' || status === 'uncertain' ? this.inspect(result.session) : this.next(result.session);
+            if (result.brief && (status === 'pending' || status === 'uncertain'))
+                result.brief = { ...result.brief, nextAction: nextActions[0]?.label ?? 'Inspect saved session' };
+            return { version: 1, operation, ok: status === 'succeeded' || status === 'pending', status,
+                delivery: status === 'rejected' ? 'not-sent' : status === 'uncertain' ? 'unknown' : 'confirmed', retry: 'inspect-first',
+                message: receipt.message ?? (status === 'succeeded' ? mutationMessages[operation] : 'Inspect saved activity before continuing. This request will not be sent again.'),
+                nextActions, result };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'The session operation could not finish.';
+            if (deliveryMayHaveOccurred)
+                return { version: 1, operation, ok: false, status: 'uncertain', delivery: 'unknown', retry: 'inspect-first', message, reason: 'unconfirmed-response', nextActions: [{ operation: 'list', label: 'Inspect saved sessions' }] };
+            return rejected(message, sessionDescriptor(operation)?.mutation ? 'not-admitted' : 'unavailable');
+        }
+    }
+}

package/dist/setup-guide.d.ts

@@ -0,0 +1,39 @@
+import { type ProviderId } from "./provider.js";
+export declare const ASSISTANTS: Record<ProviderId, {
+    name: string;
+    description: string;
+}>;
+export type ModelChoice = {
+    value: string;
+    label: string;
+};
+export declare function modelChoices(provider: ProviderId, configured: string | null, home?: string): ModelChoice[];
+export declare function detectPreparation(repo: string): {
+    command: string;
+    label: string;
+    evidence: string;
+} | null;
+/** Browser installation may write only this known file inside its project. */
+export declare function previewProjectInstructions(repo: string): {
+    ok: false;
+    message: string;
+    plan?: never;
+    content?: never;
+    fingerprint?: never;
+    installed?: never;
+} | {
+    message?: never;
+    ok: true;
+    plan: import("./skills.js").InstallPlan;
+    content: string;
+    fingerprint: string;
+    installed: boolean;
+};
+export declare function addProjectInstructions(repo: string, fingerprint: string): {
+    ok: false;
+    message: string;
+    plan?: never;
+    content?: never;
+    fingerprint?: never;
+    installed?: never;
+} | import("./skills.js").InstallResult;

package/dist/setup-guide.js

@@ -0,0 +1,93 @@
+/** Read-only suggestions for the shared desktop and browser setup flow. */
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { validModelId } from "./provider.js";
+import { planInstall, applyInstall, skillContent, SKILL_DIR, SKILL_FILE } from "./skills.js";
+export const ASSISTANTS = {
+    claude: { name: "Claude", description: "Use Claude Code for your tasks." },
+    codex: { name: "Codex", description: "Use your OpenAI coding assistant." },
+    gemini: { name: "Gemini", description: "Use Google's coding assistant." },
+    openrouter: { name: "OpenRouter", description: "Use a model from your OpenRouter account." },
+};
+export function modelChoices(provider, configured, home = homedir()) {
+    // Aliases documented at https://code.claude.com/docs/en/model-config.
+    let choices = provider === "claude"
+        ? [{ value: "sonnet", label: "Sonnet — everyday coding" }, { value: "opus", label: "Opus — complex tasks" },
+            { value: "haiku", label: "Haiku — smaller tasks" }]
+        : [];
+    if (provider === "codex") {
+        // Use the local CLI's own catalog, including account-specific availability.
+        try {
+            const path = join(home, ".codex", "models_cache.json");
+            if (lstatSync(path).size < 2_000_000) {
+                const data = JSON.parse(readFileSync(path, "utf8"));
+                choices = (Array.isArray(data.models) ? data.models : []).filter(one => one != null && one.visibility === "list" && typeof one.slug === "string" && validModelId(one.slug))
+                    .slice(0, 30).map(one => ({ value: one.slug, label: typeof one.display_name === "string" ? one.display_name.slice(0, 80) : one.slug }));
+            }
+        }
+        catch { /* A missing catalog leaves the explicit model option available. */ }
+    }
+    if (configured && !choices.some(one => one.value === configured))
+        choices.unshift({ value: configured, label: `${configured} — current choice` });
+    return choices;
+}
+export function detectPreparation(repo) {
+    const has = (file) => existsSync(join(repo, file));
+    if (has("package.json")) {
+        if (has("pnpm-lock.yaml"))
+            return { command: "pnpm install --frozen-lockfile", label: "Install project dependencies with pnpm", evidence: "pnpm-lock.yaml" };
+        if (has("yarn.lock"))
+            return { command: has(".yarnrc.yml") ? "yarn install --immutable" : "yarn install --frozen-lockfile", label: "Install project dependencies with Yarn", evidence: "yarn.lock" };
+        if (has("package-lock.json") || has("npm-shrinkwrap.json"))
+            return { command: "npm ci", label: "Install project dependencies with npm", evidence: has("package-lock.json") ? "package-lock.json" : "npm-shrinkwrap.json" };
+        if (has("bun.lock") || has("bun.lockb"))
+            return { command: "bun install --frozen-lockfile", label: "Install project dependencies with Bun", evidence: "Bun lockfile" };
+        return { command: "npm install", label: "Install project dependencies with npm", evidence: "package.json" };
+    }
+    if (has("uv.lock") && has("pyproject.toml"))
+        return { command: "uv sync --frozen", label: "Prepare the Python environment with uv", evidence: "uv.lock" };
+    if (has("Cargo.lock"))
+        return { command: "cargo fetch --locked", label: "Download Rust dependencies", evidence: "Cargo.lock" };
+    if (has("go.mod"))
+        return { command: "go mod download", label: "Download Go dependencies", evidence: "go.mod" };
+    return null;
+}
+/** Browser installation may write only this known file inside its project. */
+export function previewProjectInstructions(repo) {
+    try {
+        if (!lstatSync(repo).isDirectory())
+            return { ok: false, message: "This project folder is unavailable. Reconnect it before adding instructions." };
+    }
+    catch {
+        return { ok: false, message: "This project folder is unavailable. Reconnect it before adding instructions." };
+    }
+    for (const relative of [".claude", ".claude/skills", SKILL_DIR, join(SKILL_DIR, SKILL_FILE)]) {
+        const path = join(repo, relative);
+        try {
+            const entry = lstatSync(path);
+            if (entry.isSymbolicLink() || (relative === join(SKILL_DIR, SKILL_FILE) ? !entry.isFile() || entry.size > 2_000_000 : !entry.isDirectory()))
+                return { ok: false, message: "Project instructions use a linked folder or file. Choose a regular project folder before adding them." };
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const plan = planInstall(repo, false);
+    if (plan.skillAction === "refuse-foreign")
+        return { ok: false, message: "This project already has custom Toolroll instructions. They will be kept. You can continue setup without replacing them." };
+    const content = skillContent();
+    const current = existsSync(plan.skillPath) ? readFileSync(plan.skillPath, "utf8") : null;
+    const fingerprint = createHash("sha256").update(JSON.stringify({ repo, current, content })).digest("hex");
+    return { ok: true, plan, content, fingerprint, installed: current === content };
+}
+export function addProjectInstructions(repo, fingerprint) {
+    const preview = previewProjectInstructions(repo);
+    if (!preview.ok)
+        return preview;
+    if (preview.fingerprint !== fingerprint)
+        return { ok: false, message: "The project instructions changed. Review them again before saving." };
+    return applyInstall(repo, false);
+}

package/dist/sign-in-guard.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Password guessing (v99). Five wrong passwords in a row lock that account
+ * for 15 minutes, doubling with each further lock up to a day; a right one
+ * clears the count. Every password check counts: signing in, a request that
+ * carries a password, and each step-up inside the console. Unknown names
+ * count too, so guessing names gains nothing.
+ *
+ * Kept in memory, per database: a restart forgives, which someone locked out
+ * by another's guessing may need. The console reports each lock to the
+ * action ledger through onLock.
+ */
+export type GuardPolicy = {
+    failuresBeforeLock: number;
+    firstLockMs: number;
+    maxLockMs: number;
+};
+export declare const DEFAULT_GUARD_POLICY: GuardPolicy;
+export declare class PasswordGuard {
+    readonly policy: GuardPolicy;
+    private readonly accounts;
+    /** Told once per lock: the account (as typed), and for how long. */
+    onLock: ((account: string, lockMs: number) => void) | null;
+    constructor(policy?: GuardPolicy);
+    private static key;
+    /** Milliseconds this account stays locked (0: it may try). */
+    lockedFor(account: string, now: number): number;
+    failed(account: string, now: number): void;
+    succeeded(account: string): void;
+}
+/** The guard for one database (a store): every password check against it counts. */
+export declare function passwordGuardOf(owner: object): PasswordGuard;
+/**
+ * Wrong passwords from one address, across every account: at most `tries`
+ * in `windowMs`. What a lockout per account can't see (one address trying
+ * many names) this does.
+ */
+export declare class SourceBudget {
+    readonly tries: number;
+    readonly windowMs: number;
+    private readonly sources;
+    constructor(tries?: number, windowMs?: number);
+    /** Milliseconds until this address may try again (0: it may). */
+    waitFor(source: string, now: number): number;
+    failed(source: string, now: number): void;
+}

package/dist/sign-in-guard.js

@@ -0,0 +1,74 @@
+export const DEFAULT_GUARD_POLICY = { failuresBeforeLock: 5, firstLockMs: 15 * 60_000, maxLockMs: 24 * 60 * 60_000 };
+const TRACKED = 10_000;
+export class PasswordGuard {
+    policy;
+    accounts = new Map();
+    /** Told once per lock: the account (as typed), and for how long. */
+    onLock = null;
+    constructor(policy = DEFAULT_GUARD_POLICY) {
+        this.policy = policy;
+    }
+    static key(account) { return account.trim().toLowerCase().slice(0, 64); }
+    /** Milliseconds this account stays locked (0: it may try). */
+    lockedFor(account, now) {
+        const state = this.accounts.get(PasswordGuard.key(account));
+        return state === undefined ? 0 : Math.max(0, state.lockedUntil - now);
+    }
+    failed(account, now) {
+        const key = PasswordGuard.key(account);
+        const state = this.accounts.get(key) ?? { failures: 0, lockedUntil: 0, locks: 0 };
+        this.accounts.delete(key);
+        state.failures += 1;
+        if (state.failures >= this.policy.failuresBeforeLock) {
+            const lockMs = Math.min(this.policy.maxLockMs, this.policy.firstLockMs * 2 ** state.locks);
+            state.lockedUntil = now + lockMs;
+            state.locks += 1;
+            state.failures = 0;
+            this.onLock?.(account.trim().slice(0, 64), lockMs);
+        }
+        this.accounts.set(key, state);
+        // Bounded: the oldest tracked names go first.
+        while (this.accounts.size > TRACKED)
+            this.accounts.delete(this.accounts.keys().next().value);
+    }
+    succeeded(account) {
+        this.accounts.delete(PasswordGuard.key(account));
+    }
+}
+const guards = new WeakMap();
+/** The guard for one database (a store): every password check against it counts. */
+export function passwordGuardOf(owner) {
+    let guard = guards.get(owner);
+    if (guard === undefined) {
+        guard = new PasswordGuard();
+        guards.set(owner, guard);
+    }
+    return guard;
+}
+/**
+ * Wrong passwords from one address, across every account: at most `tries`
+ * in `windowMs`. What a lockout per account can't see (one address trying
+ * many names) this does.
+ */
+export class SourceBudget {
+    tries;
+    windowMs;
+    sources = new Map();
+    constructor(tries = 20, windowMs = 10 * 60_000) {
+        this.tries = tries;
+        this.windowMs = windowMs;
+    }
+    /** Milliseconds until this address may try again (0: it may). */
+    waitFor(source, now) {
+        const recent = (this.sources.get(source) ?? []).filter(at => now - at < this.windowMs);
+        return recent.length < this.tries ? 0 : this.windowMs - (now - recent[0]);
+    }
+    failed(source, now) {
+        const recent = (this.sources.get(source) ?? []).filter(at => now - at < this.windowMs);
+        recent.push(now);
+        this.sources.delete(source);
+        this.sources.set(source, recent.slice(-this.tries));
+        while (this.sources.size > TRACKED)
+            this.sources.delete(this.sources.keys().next().value);
+    }
+}

package/dist/skills-ui.d.ts

@@ -0,0 +1,11 @@
+import type { SkillsSnapshot, SkillsView, skillTestResult } from "./project-skills.js";
+export declare const SKILLS_CSS = ".skills{max-width:780px;min-width:0;overflow-wrap:anywhere}.skills h2{font-size:1.1rem}.skills .card{padding:18px;margin:14px 0;min-width:0}.skills form,.skills label{display:grid;gap:10px}.skills input,.skills textarea,.skills select{box-sizing:border-box;width:100%;max-width:100%;min-width:0}.skills textarea{resize:vertical;min-height:130px}.skills button{justify-self:start;white-space:nowrap;min-height:44px}.skills summary{cursor:pointer;min-height:44px;display:flex;align-items:center;gap:10px;flex-wrap:wrap}.skills pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:360px;overflow:auto;font-size:.9rem}.skills .skill-heading{display:flex;align-items:baseline;justify-content:space-between;gap:12px}.skills .skill-heading h2{margin:0}.skills .skill-state{font-size:.85rem;flex-shrink:0}.skills .skill-source{font-size:.85rem}.skills .skill-controls{display:flex;gap:12px;flex-wrap:wrap}.skills .skill-controls form{margin:0}.skills details details{margin-top:10px}.skills [hidden]{display:none!important}.skills .skill-files{max-height:200px;overflow:auto}.skills .problem{padding:12px}@media(max-width:600px){.skills input,.skills textarea,.skills select{font-size:16px}.skills .card{padding:14px}.skills .skill-heading{align-items:flex-start}}";
+export declare function skillsHtml(view: SkillsView, csrf: string, canManage: boolean, options?: {
+    focus?: string;
+    error?: string;
+    draft?: Record<string, string>;
+    agent?: string;
+}): string;
+export declare function skillsSnapshotHtml(snapshot: SkillsSnapshot | null): string;
+export declare function skillsScript(): string;
+export declare function skillTestFeedbackHtml(test: NonNullable<ReturnType<typeof skillTestResult>>, csrf: string, canManage: boolean, error?: string, draft?: string): string;