pi2web 0.2.1 → 0.2.8

package/dist/collab/types.js

@@ -1,6 +1,28 @@
 /** 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 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
@@ -10,26 +32,88 @@ export const ROLES = ['implementer', 'reviewer', 'moderator', 'human'];
 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'],
+    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']
+    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 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'];
+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 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,
+    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 }
+    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 = {

package/dist/collab/validate.js

@@ -6,9 +6,15 @@ export class ValidationError extends Error {
         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) {
+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 '';
@@ -22,9 +28,15 @@ export const str = (options = {}) => ({ parse(value, ctx) {
         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;
+    }
+});
+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;
@@ -42,19 +54,28 @@ export const num = (options = {}) => ({ parse(value, ctx) {
                 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) {
+    }
+});
+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) {
+    }
+});
+export const arr = (item, options = {}) => ({
+    parse(value, ctx) {
         if (!Array.isArray(value)) {
             fail(ctx, 'NOT_AN_ARRAY', 'Expected an array', 'array');
             return [];
@@ -67,12 +88,14 @@ export const arr = (item, options = {}) => ({ parse(value, ctx) {
             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) {
+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 {};
@@ -86,8 +109,10 @@ export const record = (value, limits = {}) => ({ parse(input, ctx) {
             result[key] = value.parse(source[key], child(ctx, key));
         }
         return result;
-    } });
-export const obj = (shape) => ({ parse(value, ctx) {
+    }
+});
+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 {};
@@ -110,24 +135,35 @@ export const obj = (shape) => ({ parse(value, ctx) {
             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) {
+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 });
+    }
+});
+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) {
+export const anyJson = (maxBytes = 64 * 1024) => ({
+    parse(value, ctx) {
         let size = 0;
         try {
             size = JSON.stringify(value)?.length ?? 0;
@@ -139,7 +175,8 @@ export const anyJson = (maxBytes = 64 * 1024) => ({ parse(value, ctx) {
         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)

package/dist/drafts.js

@@ -7,7 +7,13 @@ export class DraftHub {
     /** 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() };
+        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();
@@ -17,14 +23,28 @@ export class DraftHub {
         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; }
+    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); };
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    expire() {
+        const cutoff = Date.now() - this.ttlMs;
+        this.pending = this.pending.filter(d => Date.parse(d.createdAt) >= cutoff);
     }
-    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,222 @@
+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)
+            });
+        if (req.method === 'GET' && parts[4] === 'performance' && parts.length === 5)
+            return send(200, { data: await ctx.agents.performance(id) });
+        // /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 === 'POST' && parts[4] === 'system-prompt') {
+            const b = await ctx.body();
+            if (b.templateId !== undefined && typeof b.templateId !== 'string')
+                throw Object.assign(new Error('templateId must be a string'), { code: 'INVALID_REQUEST' });
+            const template = b.templateId ? ctx.templates.snapshot(b.templateId) : undefined;
+            const record = await ctx.agents.setTemplate(id, template, candidate => ctx.metadata.commitAgentTemplate(candidate));
+            return send(200, { data: { template: record.template ?? null } });
+        }
+        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 (req.method === 'POST' && parts[5] === 'move') {
+                const { from, index, expected } = await ctx.body();
+                if ((from !== 'steering' && from !== 'followUp') ||
+                    !Number.isSafeInteger(index) ||
+                    index < 0 ||
+                    typeof expected !== 'string')
+                    throw Object.assign(new Error('from, index and expected are required'), { code: 'INVALID_REQUEST' });
+                return send(200, { data: await ctx.agents.moveQueue(id, from, index, expected) });
+            }
+        }
+        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') {
+            ctx.agents.get(id);
+            const mime = String(req.headers['content-type'] ?? 'audio/webm').split(';')[0];
+            if (ctx.sottoStt.getSettings().enabled) {
+                if (mime !== 'application/octet-stream')
+                    throw Object.assign(new Error('Sotto requires 16 kHz float32 PCM'), { code: 'INVALID_REQUEST' });
+                const audio = await ctx.binaryBody();
+                return send(200, { data: await ctx.sottoStt.transcribe(audio) });
+            }
+            if (!ctx.voice)
+                throw Object.assign(new Error('Voice service is disabled'), { code: 'VOICE_DISABLED' });
+            const audio = await ctx.binaryBody(), 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;
+}