pi2web 0.2.0 → 0.2.6

package/dist/collab/types.js

@@ -0,0 +1,137 @@
+/** Shared contracts for the multi-agent collaboration hub. Everything crossing the HTTP boundary is defined here. */
+export const REVIEW_PHASES = [
+    'draft',
+    'implementing',
+    'collecting',
+    'consolidating',
+    'validating',
+    'merge_voting',
+    'issue_discussing',
+    'issue_reconsidering',
+    'awaiting_human',
+    'finished'
+];
+export const SCORING_PHASES = [
+    'nominating',
+    'consolidating',
+    'voting',
+    'rubric_locked',
+    'scoring',
+    'analysis',
+    'debating',
+    'rescoring',
+    'awaiting_human',
+    'finalized'
+];
+export const ROLES = ['implementer', 'reviewer', 'moderator', 'human'];
+/**
+ * Roles a *seat* may be registered with. `human` is deliberately excluded: a human acts with the pairing
+ * code, and a `human`-role participant token would hold nominate/vote/score capabilities while
+ * `scoringPanel()` never waits for it — its submissions would move a tally nobody is waiting on.
+ */
+export const REGISTRABLE_ROLES = ['implementer', 'reviewer'];
+export const CAPABILITIES = {
+    implementer: ['file_finding', 'ready', 'withdraw', 'clarify', 'escalate'],
+    reviewer: [
+        'file_finding',
+        'withdraw',
+        'nominate',
+        'vote',
+        'score',
+        'debate',
+        'clarify',
+        'merge',
+        'escalate'
+    ],
+    moderator: ['file_finding', 'withdraw', 'merge', 'clarify', 'escalate'],
+    human: [
+        'file_finding',
+        'ready',
+        'withdraw',
+        'nominate',
+        'vote',
+        'score',
+        'debate',
+        'clarify',
+        'merge',
+        'escalate'
+    ]
+};
+export const can = (role, capability) => CAPABILITIES[role]?.includes(capability) ?? false;
+export const SEVERITIES = ['blocker', 'critical', 'major', 'minor', 'nit'];
+export const CATEGORIES = [
+    'security',
+    'correctness',
+    'performance',
+    'maintainability',
+    'style',
+    'test',
+    'docs',
+    'process'
+];
+export const REQUIRED_ACTIONS = ['must_fix', 'should_fix', 'discuss', 'fyi'];
+export const ISSUE_STATUSES = [
+    'open',
+    'confirmed',
+    'answered',
+    'resolved',
+    'escalated',
+    'human_ruled',
+    'wontfix',
+    'closed',
+    'duplicate',
+    'withdrawn'
+];
+/** Statuses that still block the session from finishing. */
+export const OPEN_ISSUE_STATUSES = ['open', 'answered', 'escalated'];
+export const ESCALATION_KINDS = [
+    'issue_dispute',
+    'rubric_dispute',
+    'score_dispute',
+    'budget_exhausted',
+    'other'
+];
+export const VOTE_STANCES = ['approve', 'reject', 'abstain'];
+export const DEBATE_STANCES = ['raise', 'lower', 'hold', 'clarify'];
+/** approvalThreshold is "two thirds" with a little headroom, so an exact 2-of-3 vote passes. */
+export const DEFAULT_POLICY = {
+    maxIssueRounds: 3,
+    maxTotalRounds: 6,
+    overdueWarningSec: 1800,
+    autoEscalateOnDeadlock: true,
+    blindFindings: true,
+    consensusReview: false,
+    maxConsensusRounds: 3,
+    implementationFirst: false,
+    tokenBudgetPerParticipant: 600_000,
+    scoring: {
+        minCriteria: 4,
+        maxCriteria: 8,
+        approvalThreshold: 0.66,
+        maxVotingRounds: 3,
+        scale: { min: 0, max: 10, step: 0.5 },
+        convergenceRange: 2,
+        maxDebateRounds: 2,
+        blindScoring: true
+    }
+};
+/** Error codes returned to agents. Keep them stable: agents branch on these strings. */
+export const COLLAB_ERRORS = {
+    validationFailed: 'VALIDATION_FAILED',
+    evidenceRequired: 'EVIDENCE_REQUIRED',
+    sessionNotFound: 'COLLAB_SESSION_NOT_FOUND',
+    participantNotFound: 'COLLAB_PARTICIPANT_NOT_FOUND',
+    issueNotFound: 'COLLAB_ISSUE_NOT_FOUND',
+    escalationNotFound: 'COLLAB_ESCALATION_NOT_FOUND',
+    forbidden: 'COLLAB_FORBIDDEN',
+    humanOnly: 'COLLAB_HUMAN_ONLY',
+    wrongPhase: 'COLLAB_WRONG_PHASE',
+    conflict: 'COLLAB_CONFLICT',
+    staleBaseline: 'STALE_BASELINE',
+    noCodeChange: 'NO_CODE_CHANGE',
+    budgetExhausted: 'TOKEN_BUDGET_EXHAUSTED',
+    humanRulingFinal: 'HUMAN_RULING_FINAL',
+    scoresSealed: 'SCORES_SEALED',
+    criterionNotFound: 'COLLAB_CRITERION_NOT_FOUND',
+    debateNotFound: 'COLLAB_DEBATE_NOT_FOUND'
+};

package/dist/collab/validate.js

@@ -0,0 +1,185 @@
+export class ValidationError extends Error {
+    fieldErrors;
+    code = 'VALIDATION_FAILED';
+    constructor(fieldErrors) {
+        super(`Invalid request: ${fieldErrors.map(e => `${e.path} ${e.code}`).join(', ')}`);
+        this.fieldErrors = fieldErrors;
+    }
+}
+const fail = (ctx, code, message, expected) => {
+    ctx.errors.push({ path: ctx.path || '(root)', code, message, ...(expected ? { expected } : {}) });
+};
+const child = (ctx, key) => ({
+    path: typeof key === 'number' ? `${ctx.path}[${key}]` : ctx.path ? `${ctx.path}.${key}` : key,
+    errors: ctx.errors
+});
+export const str = (options = {}) => ({
+    parse(value, ctx) {
+        if (typeof value !== 'string') {
+            fail(ctx, 'NOT_A_STRING', 'Expected a string', 'string');
+            return '';
+        }
+        const text = options.trim === false ? value : value.trim();
+        const min = options.min ?? 1, max = options.max ?? 4000;
+        if (text.length < min)
+            fail(ctx, 'TOO_SHORT', `Expected at least ${min} characters, received ${text.length}`, `length >= ${min}`);
+        if (text.length > max)
+            fail(ctx, 'TOO_LONG', `Expected at most ${max} characters, received ${text.length}`, `length <= ${max}`);
+        if (options.pattern && !options.pattern.test(text))
+            fail(ctx, 'PATTERN_MISMATCH', `Expected a value matching ${options.pattern}`, String(options.pattern));
+        return text;
+    }
+});
+export const num = (options = {}) => ({
+    parse(value, ctx) {
+        const parsed = typeof value === 'number'
+            ? value
+            : typeof value === 'string' && value.trim() !== ''
+                ? Number(value)
+                : NaN;
+        if (!Number.isFinite(parsed)) {
+            fail(ctx, 'NOT_A_NUMBER', 'Expected a finite number', 'number');
+            return 0;
+        }
+        if (options.integer && !Number.isInteger(parsed))
+            fail(ctx, 'NOT_AN_INTEGER', 'Expected an integer', 'integer');
+        if (options.min !== undefined && parsed < options.min)
+            fail(ctx, 'TOO_SMALL', `Expected a value >= ${options.min}`, `>= ${options.min}`);
+        if (options.max !== undefined && parsed > options.max)
+            fail(ctx, 'TOO_LARGE', `Expected a value <= ${options.max}`, `<= ${options.max}`);
+        // Floating point: 6.5 / 0.5 must be treated as an exact multiple, so compare against a rounded quotient.
+        if (options.step) {
+            const quotient = parsed / options.step;
+            if (Math.abs(quotient - Math.round(quotient)) > 1e-9)
+                fail(ctx, 'NOT_A_MULTIPLE', `Expected a multiple of ${options.step}`, `multiple of ${options.step}`);
+        }
+        return parsed;
+    }
+});
+export const bool = () => ({
+    parse(value, ctx) {
+        if (typeof value !== 'boolean') {
+            fail(ctx, 'NOT_A_BOOLEAN', 'Expected true or false', 'boolean');
+            return false;
+        }
+        return value;
+    }
+});
+export const oneOf = (values) => ({
+    parse(value, ctx) {
+        if (typeof value !== 'string' || !values.includes(value)) {
+            fail(ctx, 'NOT_ALLOWED', `Expected one of: ${values.join(', ')}`, values.join('|'));
+            return values[0];
+        }
+        return value;
+    }
+});
+export const arr = (item, options = {}) => ({
+    parse(value, ctx) {
+        if (!Array.isArray(value)) {
+            fail(ctx, 'NOT_AN_ARRAY', 'Expected an array', 'array');
+            return [];
+        }
+        const min = options.min ?? 0, max = options.max ?? 200;
+        if (value.length < min)
+            fail(ctx, 'TOO_FEW_ITEMS', `Expected at least ${min} items, received ${value.length}`, `length >= ${min}`);
+        if (value.length > max) {
+            fail(ctx, 'TOO_MANY_ITEMS', `Expected at most ${max} items, received ${value.length}`, `length <= ${max}`);
+            return [];
+        }
+        return value.map((entry, index) => item.parse(entry, child(ctx, index)));
+    }
+});
+/**
+ * A map whose keys are data, not schema - rubric anchors are `{"0":"...","10":"..."}`. `obj()` cannot express
+ * this: it only ever copies the fields its shape declares, so an empty shape silently parses to `{}`.
+ */
+export const record = (value, limits = {}) => ({
+    parse(input, ctx) {
+        if (!input || typeof input !== 'object' || Array.isArray(input)) {
+            fail(ctx, 'NOT_AN_OBJECT', 'Expected an object', 'object');
+            return {};
+        }
+        const source = input, keys = Object.keys(source), result = {};
+        if (limits.maxKeys !== undefined && keys.length > limits.maxKeys)
+            fail(ctx, 'TOO_LONG', `At most ${limits.maxKeys} entries are accepted`, `<= ${limits.maxKeys} entries`);
+        for (const key of keys) {
+            if (limits.maxKeyLength !== undefined && key.length > limits.maxKeyLength)
+                fail(child(ctx, key), 'TOO_LONG', `A key may be at most ${limits.maxKeyLength} characters`);
+            result[key] = value.parse(source[key], child(ctx, key));
+        }
+        return result;
+    }
+});
+export const obj = (shape) => ({
+    parse(value, ctx) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            fail(ctx, 'NOT_AN_OBJECT', 'Expected an object', 'object');
+            return {};
+        }
+        const source = value, result = {};
+        for (const [key, validator] of Object.entries(shape)) {
+            const entry = source[key];
+            if (entry === undefined || entry === null) {
+                if (validator.optional) {
+                    if (validator.fallback)
+                        result[key] = validator.fallback();
+                    continue;
+                }
+                fail(child(ctx, key), 'REQUIRED', 'This field is required');
+                continue;
+            }
+            result[key] = validator.parse(entry, child(ctx, key));
+        }
+        for (const key of Object.keys(source))
+            if (!(key in shape))
+                fail(child(ctx, key), 'UNKNOWN_FIELD', `Unknown field. Allowed fields: ${Object.keys(shape).join(', ')}`);
+        return result;
+    }
+});
+/**
+ * Cross-field rule on top of a structurally valid value. Field-by-field checks cannot catch
+ * `{min:10,max:1}`: every field is in range, yet the combination is unusable.
+ * The check only runs when the inner validator produced no errors, so it never reports on garbage.
+ */
+export const refine = (inner, check) => ({
+    parse(value, ctx) {
+        const before = ctx.errors.length, result = inner.parse(value, ctx);
+        if (ctx.errors.length > before)
+            return result;
+        for (const error of check(result) ?? [])
+            ctx.errors.push({ ...error, path: ctx.path ? `${ctx.path}.${error.path}` : error.path });
+        return result;
+    }
+});
+export const optional = (inner) => ({
+    parse: (value, ctx) => inner.parse(value, ctx),
+    optional: true
+});
+export const withDefault = (inner, fallback) => ({
+    parse: (value, ctx) => inner.parse(value, ctx),
+    optional: true,
+    fallback
+});
+/** Accepts any JSON value. Used for opaque payloads the hub stores but never interprets. */
+export const anyJson = (maxBytes = 64 * 1024) => ({
+    parse(value, ctx) {
+        let size = 0;
+        try {
+            size = JSON.stringify(value)?.length ?? 0;
+        }
+        catch {
+            fail(ctx, 'NOT_SERIALIZABLE', 'Expected JSON-serializable data');
+            return null;
+        }
+        if (size > maxBytes)
+            fail(ctx, 'TOO_LARGE', `Expected at most ${maxBytes} serialized bytes, received ${size}`);
+        return value;
+    }
+});
+export function parse(validator, value) {
+    const errors = [], result = validator.parse(value, { path: '', errors });
+    if (errors.length)
+        throw new ValidationError(errors.slice(0, 50));
+    return result;
+}

package/dist/drafts.js

@@ -0,0 +1,50 @@
+import { randomUUID } from 'node:crypto';
+export class DraftHub {
+    pending = [];
+    listeners = new Set();
+    max = 50;
+    ttlMs = 60 * 60_000;
+    /** Returns the stored draft and how many Web UIs were reached right now. */
+    add(input) {
+        this.expire();
+        const draft = {
+            id: `draft-${randomUUID()}`,
+            text: input.text,
+            mode: input.mode ?? 'append',
+            source: input.source,
+            createdAt: new Date().toISOString()
+        };
+        this.pending.push(draft);
+        while (this.pending.length > this.max)
+            this.pending.shift();
+        const delivered = this.listeners.size;
+        for (const listener of [...this.listeners])
+            listener(draft, false);
+        return { draft, delivered };
+    }
+    /** First acknowledgement wins: other tabs that already received it simply keep their copy. */
+    ack(id) {
+        const before = this.pending.length;
+        this.pending = this.pending.filter(d => d.id !== id);
+        return this.pending.length < before;
+    }
+    list() {
+        this.expire();
+        return [...this.pending];
+    }
+    subscriberCount() {
+        return this.listeners.size;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        for (const draft of this.list())
+            listener(draft, true);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    expire() {
+        const cutoff = Date.now() - this.ttlMs;
+        this.pending = this.pending.filter(d => Date.parse(d.createdAt) >= cutoff);
+    }
+}

package/dist/http/agent-routes.js

@@ -0,0 +1,196 @@
+import { listMcpServers, setMcpServerEnabled } from '../mcp.js';
+import { json } from './utils.js';
+/** Handles `/api/v1/agents/**`. Returns undefined when the request is not an Agent route. */
+export async function handleAgentRoutes(ctx, req, res, u, parts) {
+    const send = (status, data) => {
+        json(res, status, data);
+        return true;
+    };
+    if (req.method === 'GET' && u.pathname === '/api/v1/agents/models') {
+        const workspaceId = u.searchParams.get('workspaceId') ?? '', relativeCwd = u.searchParams.get('relativeCwd') ?? '.';
+        return send(200, { data: await ctx.agents.capabilityPreview(workspaceId, relativeCwd) });
+    }
+    // The list carries which template an Agent uses but not its text; GET /agents/:id/system-prompt has the full prompt.
+    if (req.method === 'GET' && u.pathname === '/api/v1/agents')
+        return send(200, {
+            data: ctx.agents
+                .list()
+                .map(({ template, ...record }) => template
+                ? { ...record, template: { id: template.id, name: template.name, mode: template.mode } }
+                : record)
+        });
+    if (req.method === 'POST' && u.pathname === '/api/v1/agents') {
+        const b = await ctx.body(), profile = b.profile === undefined ? 'default' : b.profile;
+        if (profile !== 'default' && profile !== 'collab')
+            throw Object.assign(new Error('profile must be default or collab'), { code: 'INVALID_REQUEST' });
+        let sessionFile;
+        if (b.sessionFile) {
+            const workspace = ctx.workspaces.get(b.workspaceId);
+            if (!workspace)
+                throw Object.assign(new Error('Workspace not found'), { code: 'WORKSPACE_NOT_FOUND' });
+            const cwd = await ctx.workspaces.resolve(workspace, b.relativeCwd ?? '.');
+            await ctx.ensureSessionIndex(workspace, cwd);
+            if (!ctx.metadata.hasSession(cwd, b.sessionFile))
+                throw Object.assign(new Error('Session is not valid for cwd'), { code: 'SESSION_NOT_FOUND' });
+            sessionFile = b.sessionFile;
+        }
+        if (b.templateId !== undefined && b.templateId !== null && typeof b.templateId !== 'string')
+            throw Object.assign(new Error('templateId must be a string'), { code: 'INVALID_REQUEST' });
+        // The template is copied now; later edits to the template file do not affect this Agent.
+        const template = b.templateId ? ctx.templates.snapshot(b.templateId) : undefined;
+        const agent = await ctx.agents.create(b.workspaceId, b.relativeCwd ?? '.', sessionFile, profile, template);
+        try {
+            if (b.model !== undefined) {
+                if (!b.model || typeof b.model.provider !== 'string' || typeof b.model.modelId !== 'string')
+                    throw Object.assign(new Error('model.provider and model.modelId are required'), {
+                        code: 'INVALID_REQUEST'
+                    });
+                await ctx.agents.setModel(agent.agentId, b.model.provider, b.model.modelId);
+            }
+            if (b.sessionName !== undefined) {
+                if (typeof b.sessionName !== 'string')
+                    throw Object.assign(new Error('sessionName must be a string'), { code: 'INVALID_REQUEST' });
+                await ctx.agents.setSessionName(agent.agentId, b.sessionName);
+            }
+            const configured = ctx.agents.get(agent.agentId).record;
+            ctx.metadata.saveAgent(configured);
+            return send(201, { data: { ...configured } });
+        }
+        catch (error) {
+            await ctx.agents.remove(agent.agentId).catch(() => { });
+            throw error;
+        }
+    }
+    if (parts[2] === 'agents') {
+        const id = parts[3];
+        if (req.method === 'GET' && parts.length === 4)
+            return send(200, { data: ctx.agents.get(id).record });
+        if (req.method === 'DELETE' && parts.length === 4) {
+            await ctx.agents.dispose(id);
+            ctx.metadata.saveAgent(ctx.agents.get(id).record);
+            return send(200, { data: { stopped: true } });
+        }
+        if (req.method === 'POST' && parts[4] === 'archive') {
+            const record = await ctx.agents.archive(id);
+            ctx.metadata.archiveAgent(record);
+            return send(200, { data: { archived: true } });
+        }
+        if (req.method === 'GET' && parts[4] === 'state')
+            return send(200, { data: await ctx.agents.state(id) });
+        if (req.method === 'GET' && parts[4] === 'timeline' && parts.length === 5)
+            return send(200, {
+                data: await ctx.agents.timeline(id, Number(u.searchParams.get('limit') ?? 50), u.searchParams.get('before') ?? undefined)
+            });
+        // /agents/:id/sessions/:sessionId/items/:itemId — items never change, and the session is part of the
+        // URL so a cached body is never served for another one: let the browser keep it for good.
+        if (req.method === 'GET' && parts[4] === 'sessions' && parts[6] === 'items' && parts.length === 8) {
+            const detail = await ctx.agents.item(id, decodeURIComponent(parts[5]), decodeURIComponent(parts[7]));
+            res.setHeader('cache-control', 'private, max-age=31536000, immutable');
+            return send(200, { data: detail });
+        }
+        if (req.method === 'GET' && parts[4] === 'system-prompt')
+            return send(200, { data: await ctx.agents.systemPrompt(id) });
+        if (req.method === 'GET' && parts[4] === 'capabilities')
+            return send(200, { data: await ctx.agents.capabilities(id) });
+        if (req.method === 'GET' && parts[4] === 'session')
+            return send(200, {
+                data: u.searchParams.get('summary') === 'true'
+                    ? await ctx.agents.sessionInfo(id)
+                    : await ctx.agents.session(id)
+            });
+        if (req.method === 'POST' && parts[4] === 'compact') {
+            const b = await ctx.body();
+            return send(200, { data: await ctx.agents.compact(id, b.instructions) });
+        }
+        if (req.method === 'POST' && parts[4] === 'model') {
+            const b = await ctx.body();
+            await ctx.agents.setModel(id, b.provider, b.modelId);
+            return send(200, { data: await ctx.agents.capabilities(id) });
+        }
+        if (req.method === 'POST' && parts[4] === 'thinking') {
+            const b = await ctx.body();
+            await ctx.agents.setThinkingLevel(id, b.level);
+            return send(200, { data: await ctx.agents.capabilities(id) });
+        }
+        if (req.method === 'POST' && parts[4] === 'session-name') {
+            const b = await ctx.body();
+            await ctx.agents.setSessionName(id, b.name);
+            const summary = await ctx.agents.sessionInfo(id), record = ctx.agents.get(id).record;
+            ctx.metadata.saveAgent(record);
+            ctx.metadata.upsertSessionFromAgent(record, summary);
+            return send(200, { data: summary });
+        }
+        if (req.method === 'POST' && parts[4] === 'navigate') {
+            const b = await ctx.body();
+            return send(200, { data: await ctx.agents.navigate(id, b.entryId) });
+        }
+        if (req.method === 'POST' && parts[4] === 'fork') {
+            const b = await ctx.body();
+            const agent = await ctx.agents.fork(id, b.entryId);
+            ctx.metadata.saveAgent(agent.agent);
+            return send(201, { data: agent });
+        }
+        if (req.method === 'GET' && parts[4] === 'commands')
+            return send(200, { data: await ctx.agents.listCommands(id) });
+        if (req.method === 'POST' && parts[4] === 'bash') {
+            const b = await ctx.body();
+            if (typeof b.command !== 'string')
+                throw Object.assign(new Error('command must be a string'), { code: 'INVALID_REQUEST' });
+            const command = b.command.trim();
+            if (!command)
+                throw Object.assign(new Error('command is required'), { code: 'INVALID_REQUEST' });
+            if (command.length > 8000)
+                throw Object.assign(new Error('command is too long'), { code: 'INVALID_REQUEST' });
+            const result = await ctx.agents.runBash(id, command, b.excludeFromContext === true);
+            ctx.metadata.scheduleAgent(ctx.agents.get(id).record);
+            return send(200, { data: result });
+        }
+        if (req.method === 'POST' && parts[4] === 'bash-abort') {
+            await ctx.agents.abortBash(id);
+            return send(200, { data: { aborted: true } });
+        }
+        if (parts[4] === 'queue') {
+            if (req.method === 'GET')
+                return send(200, { data: await ctx.agents.queue(id) });
+            if (req.method === 'DELETE')
+                return send(200, { data: await ctx.agents.clearQueue(id) });
+        }
+        if (parts[4] === 'mcp') {
+            const cwd = ctx.agents.get(id).record.cwd;
+            if (req.method === 'GET')
+                return send(200, { data: listMcpServers(cwd) });
+            if (req.method === 'POST') {
+                const b = await ctx.body();
+                if (typeof b.name !== 'string' || typeof b.enabled !== 'boolean')
+                    throw Object.assign(new Error('name and enabled are required'), { code: 'INVALID_MCP_REQUEST' });
+                return send(200, { data: setMcpServerEnabled(cwd, b.name, b.enabled) });
+            }
+        }
+        if (req.method === 'POST' && parts[4] === 'extension-response') {
+            const b = await ctx.body();
+            await ctx.agents.extensionResponse(id, b.requestId, b.value);
+            return send(200, { data: { success: true } });
+        }
+        if (req.method === 'POST' && parts[4] === 'transcribe') {
+            if (!ctx.voice)
+                throw Object.assign(new Error('Voice service is disabled'), { code: 'VOICE_DISABLED' });
+            ctx.agents.get(id);
+            const audio = await ctx.binaryBody(), mime = String(req.headers['content-type'] ?? 'audio/webm').split(';')[0], filename = String(req.headers['x-audio-filename'] ?? 'recording.webm');
+            return send(200, { data: await ctx.voice.transcribe(audio, mime, filename) });
+        }
+        if (req.method === 'POST' && ['prompt', 'steer', 'follow-up', 'abort'].includes(parts[4])) {
+            const b = await ctx.body();
+            if (parts[4] !== 'abort') {
+                ctx.voice?.recordUserPrompt(id, String(b.message ?? ''));
+                ctx.sessionNamer?.recordUserPrompt(id, String(b.message ?? ''));
+            }
+            const disposition = await ctx.agents.command(id, parts[4], b.message ?? '');
+            const record = ctx.agents.get(id).record;
+            ctx.metadata.scheduleAgent(record);
+            if (parts[4] === 'prompt')
+                void ctx.indexAgentSession(id);
+            return send(200, { data: { success: true, disposition } });
+        }
+    }
+    return false;
+}

package/dist/http/login-limiter.js

@@ -0,0 +1,53 @@
+/**
+ * Rate limits pairing attempts per source address, with an escalating lock after repeated failures.
+ * Reverse proxies and tunnels share one bucket by design.
+ */
+export class LoginLimiter {
+    failures = new Map();
+    windowMs = 60_000;
+    maxFailures = 10;
+    lockMs = 60_000;
+    maxLockMs = 15 * 60_000;
+    /** Milliseconds until `key` may try again; 0 when it is not locked. */
+    retryAfterMs(key) {
+        const entry = this.failures.get(key);
+        if (!entry)
+            return 0;
+        const now = Date.now();
+        if (entry.lockedUntil > now)
+            return entry.lockedUntil - now;
+        if (entry.expiresAt <= now)
+            this.failures.delete(key);
+        return 0;
+    }
+    /** Records a failed attempt and returns the lock duration it triggered, or 0. */
+    recordFailure(key) {
+        const now = Date.now();
+        if (this.failures.size > 1000)
+            for (const [id, value] of this.failures)
+                if (value.expiresAt <= now && value.lockedUntil <= now)
+                    this.failures.delete(id);
+        const entry = this.failures.get(key);
+        if (!entry || (entry.expiresAt <= now && entry.lockedUntil <= now)) {
+            this.failures.set(key, { count: 1, expiresAt: now + this.windowMs, lockedUntil: 0, lockLevel: 0 });
+            return 0;
+        }
+        entry.count += 1;
+        entry.expiresAt = now + this.windowMs;
+        if (entry.count < this.maxFailures)
+            return 0;
+        entry.count = 0;
+        entry.lockLevel = Math.min(entry.lockLevel + 1, 5);
+        entry.lockedUntil = now + Math.min(this.lockMs * 2 ** (entry.lockLevel - 1), this.maxLockMs);
+        entry.expiresAt = entry.lockedUntil + this.windowMs;
+        return entry.lockedUntil - now;
+    }
+    /** A successful login clears the address's failure history. */
+    clear(key) {
+        this.failures.delete(key);
+    }
+    /** Forgets every address. */
+    reset() {
+        this.failures.clear();
+    }
+}

package/dist/http/mail-settings-routes.js

@@ -0,0 +1,53 @@
+import { json, readJsonBody } from './utils.js';
+/** Handles `/api/v1/mail-notifications`. Returns false when the request is not a mail settings route. */
+export async function handleMailSettingsRoutes(ctx, req, res, u) {
+    const send = (status, data) => {
+        json(res, status, data);
+        return true;
+    };
+    if (req.method === 'GET' && u.pathname === '/api/v1/mail-notifications')
+        return send(200, {
+            data: { available: !!ctx.mailNotifier, settings: ctx.mailNotifier?.getSettings() ?? null }
+        });
+    if (req.method === 'POST' && u.pathname === '/api/v1/mail-notifications') {
+        if (!ctx.mailNotifier)
+            throw Object.assign(new Error('MailDispatch is not configured at server startup'), {
+                code: 'MAIL_NOTIFICATIONS_DISABLED'
+            });
+        const b = await readJsonBody(req), patch = {};
+        if ('enabled' in b) {
+            if (typeof b.enabled !== 'boolean')
+                throw Object.assign(new Error('enabled must be a boolean'), {
+                    code: 'INVALID_MAIL_NOTIFICATION_SETTINGS'
+                });
+            patch.enabled = b.enabled;
+        }
+        if ('aggregationDelaySeconds' in b)
+            patch.aggregationDelaySeconds = Number(b.aggregationDelaySeconds);
+        if ('includeResponse' in b) {
+            if (typeof b.includeResponse !== 'boolean')
+                throw Object.assign(new Error('includeResponse must be a boolean'), {
+                    code: 'INVALID_MAIL_NOTIFICATION_SETTINGS'
+                });
+            patch.includeResponse = b.includeResponse;
+        }
+        if ('includeSessionDetails' in b) {
+            if (typeof b.includeSessionDetails !== 'boolean')
+                throw Object.assign(new Error('includeSessionDetails must be a boolean'), {
+                    code: 'INVALID_MAIL_NOTIFICATION_SETTINGS'
+                });
+            patch.includeSessionDetails = b.includeSessionDetails;
+        }
+        if ('collabEscalations' in b) {
+            if (typeof b.collabEscalations !== 'boolean')
+                throw Object.assign(new Error('collabEscalations must be a boolean'), {
+                    code: 'INVALID_MAIL_NOTIFICATION_SETTINGS'
+                });
+            patch.collabEscalations = b.collabEscalations;
+        }
+        const settings = ctx.mailNotifier.updateSettings(patch);
+        ctx.metadata.setSetting('mailNotifications', settings);
+        return send(200, { data: { available: true, settings } });
+    }
+    return false;
+}