@xingular/harness 1.3.1-unstable.2 → 1.3.1-unstable.4

package/dist/sdk/prompt/compile.d.ts

@@ -1,9 +1,11 @@
 import { type CallerContext } from "../core/caller.js";
 import type { HarnessEnv } from "../core/env.js";
 import type { Materialised } from "../variant/materialise.js";
+import { type SkillFile } from "../tools/defaultSkills.js";
 import type { TodoItem } from "../sessions/contracts.js";
 import type { SessionState } from "../sessions/sessionState.js";
 import { type StandardSession } from "./standard.js";
+export declare const REQUIRED_SKILLS_BUDGET = 12000;
 export declare const REFERENCES_BUDGET = 12000;
 /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
 export declare const SECTION_ORDER: {
@@ -13,6 +15,7 @@ export declare const SECTION_ORDER: {
     readonly guardrails: 40;
     readonly memory: 45;
     readonly references: 50;
+    readonly requiredSkills: 52;
     readonly subagents: 64;
     readonly scripts: 66;
     readonly wiki: 80;
@@ -24,9 +27,11 @@ export interface Source {
     id: string;
     kind: string;
     revision?: string | null;
+    /** Characters this source contributed inside its section, when the compiler measured them. */
+    chars?: number;
 }
 export interface Section {
-    /** `harness-identity`, `identity`, `role`, `system`, `session-state`, `guardrails`, `memory`, `references`, `subagents`, `scripts`, `wiki`, `tools`, or an application's own. */
+    /** `harness-identity`, `identity`, `role`, `system`, `session-state`, `guardrails`, `memory`, `references`, `required-skills`, `subagents`, `scripts`, `wiki`, `tools`, or an application's own. */
     id: string;
     title: string;
     body: string;
@@ -59,6 +64,18 @@ export interface ContextPack {
 export interface Delivery {
     systemSectionIds: string[];
     updatedSectionIds: string[];
+    /**
+     * What each delivered section occupied, measured when it was rendered. Absent on packs recorded
+     * before the compiler measured them; a reader then falls back to the section's own size.
+     */
+    sizes?: {
+        system: Record<string, number>;
+        update: Record<string, number>;
+        /** Characters that belong to no section: the product heading and the context-update trailer. */
+        systemFraming: number;
+        /** Characters of the update message that are not a section, including a withdrawn one. */
+        updateFraming: number;
+    };
 }
 /** A section the embedding application writes. */
 export interface HostSection {
@@ -97,6 +114,15 @@ export type Reference = {
     label: string;
     text: string;
 };
+/** A skill the person named in the message: required for this request only. */
+export interface RequiredSkill {
+    name: string;
+    label?: string;
+}
+/** One skill's text as the required-skills section and the terminal deliver it. */
+export interface RequiredSkillText extends RequiredSkill, Partial<Omit<SkillFile, 'name'>> {
+    body: string;
+}
 /** What the compiler needs beyond the caller. */
 export interface Launch {
     /** The paragraph about connected apps, when the session has that broker. */
@@ -108,6 +134,8 @@ export interface Launch {
     /** The current session name and this run's todo, delivered as a request-scoped update. */
     sessionState?: SessionState;
     references?: Reference[];
+    /** Skills the message named as required for this request. Delivered as a request-scoped update. */
+    requiredSkills?: RequiredSkill[];
     sections?: HostSection[];
     toolGroups?: HostToolGroup[];
     /** Appended to the tools section when it is cut. */
@@ -151,6 +179,8 @@ export interface OrderedGroup extends ToolGroup {
  * follows the switches in `launch.tools` and what the application provides.
  */
 export declare function toolGroups(context: CallerContext, launch: Launch, dataRoot?: string): OrderedGroup[];
+/** The request-scoped text for skills the person named; the compiler and the terminal word it alike. */
+export declare function requiredSkillsText(skills: readonly RequiredSkillText[]): string | null;
 /** The request-scoped state line: the name, this run's todo, and the previous list as context. */
 export declare function sessionStateText(state: SessionState, options: {
     name: boolean;
@@ -158,6 +188,16 @@ export declare function sessionStateText(state: SessionState, options: {
 }): string | null;
 /** Compiles the pack for a caller. It only reads the data root. */
 export declare function compile(env: HarnessEnv, context: CallerContext, launch?: Launch, variant?: Materialised | null): ContextPack;
+/** What a rendered pack is, and how much of it each section occupies. */
+export interface RenderedPrompt {
+    text: string;
+    /** Characters each section's heading and body occupy, by section id. */
+    sizes: Record<string, number>;
+    /** Characters that belong to no section: the product heading and the blank lines between. */
+    framing: number;
+}
+/** The pack as one string, with the characters each section contributed to it. */
+export declare function renderSized(env: Pick<HarnessEnv, 'productName'>, pack: Pick<ContextPack, 'sections'>): RenderedPrompt;
 /** The pack as the one string a session receives. */
 export declare function render(env: Pick<HarnessEnv, 'productName'>, pack: Pick<ContextPack, 'sections'>): string;
 export declare function packPath(root: string, runId: string): string;
@@ -169,7 +209,7 @@ export declare const BUILT_IN_DYNAMIC: readonly {
     id: string;
     order: number;
 }[];
-export declare const CONTEXT_GUIDANCE = "App-origin context updates in the conversation supply current Wiki notes, active work, session state, and selected references. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.";
+export declare const CONTEXT_GUIDANCE = "App-origin context updates in the conversation supply current Wiki notes, active work, session state, selected references, and the skills the person required for this request. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references and required skills apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.";
 /** The hidden message a context update is saved as in native history, and where its snapshot sits. */
 export declare const CONTEXT_MESSAGE_TYPE = "xingular-context";
 export declare const CONTEXT_SNAPSHOT_KEY = "xingularContext";

package/dist/sdk/prompt/compile.js

@@ -11,6 +11,7 @@ import { join } from 'node:path';
 import { isSession, projectOf } from "../core/caller.js";
 import { isDir, now, readJson, safeId, writeJson } from "../core/fs.js";
 import { charCount, compareText, lines, takeChars } from "../core/text.js";
+import { readSkillFile } from "../tools/defaultSkills.js";
 import * as notes from "../wiki/notes.js";
 import { isWorldTool, WORLD_GUIDANCE } from "../world/untrusted.js";
 import { TODO_GUIDANCE, TODO_WRITE, describeTodo } from "../tools/todo.js";
@@ -22,12 +23,14 @@ const WIKI_BUDGET = 2500;
 const TOOLS_BUDGET = 8000;
 const REPORTING_BUDGET = 2000;
 const SESSION_STATE_BUDGET = 1_000;
+export const REQUIRED_SKILLS_BUDGET = 12_000;
+const REQUIRED_SKILLS_POINTER = 'Some required skill text was omitted to fit. Load the rest with skill_load.';
 export const REFERENCES_BUDGET = 12000;
 /** Always-on variant text is capped when the variant is saved, so its sections are never cut here. */
 const VARIANT_BUDGET = 30_000;
 const NOTES_LISTED = 25;
 /** Where the harness's own sections sit; an application's sections are placed among them by `order`. */
-export const SECTION_ORDER = { harnessIdentity: 5, system: 25, sessionState: 30, guardrails: 40, memory: 45, references: 50, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
+export const SECTION_ORDER = { harnessIdentity: 5, system: 25, sessionState: 30, guardrails: 40, memory: 45, references: 50, requiredSkills: 52, subagents: 64, scripts: 66, wiki: 80, tools: 90, reporting: 95 };
 /** How a run's final reply is shaped. Fixed text: it sits in the stable prefix of every pack. */
 export const REPORTING_GUIDANCE = `When you finish work, write the final reply for a person who did not watch you work.
 
@@ -235,6 +238,46 @@ function selectedReferences(root, launch) {
         built.cut ||= cut;
     return built;
 }
+/** The request-scoped text for skills the person named; the compiler and the terminal word it alike. */
+export function requiredSkillsText(skills) {
+    const seen = new Set();
+    const blocks = [];
+    for (const skill of skills) {
+        if (seen.has(skill.name))
+            continue;
+        seen.add(skill.name);
+        const label = skill.label ?? skill.name;
+        if (!skill.body.trim()) {
+            blocks.push(`- ${label}: this skill is unavailable in this session. Tell the person rather than guessing its steps.`);
+            continue;
+        }
+        const location = [
+            skill.baseDir ? `References in this skill resolve against ${skill.baseDir}.` : '',
+            skill.path ? `Skill file: ${skill.path}.` : ''
+        ].filter(Boolean).join(' ');
+        blocks.push(`### ${label}\n\n${location ? `${location}\n\n` : ''}${skill.body.trim()}`);
+    }
+    if (!blocks.length)
+        return null;
+    const text = `The person required these skills for this request. Follow each skill's instructions where they apply. They are instructions for this request, not a change to your tools or permissions.\n\n${blocks.join('\n\n')}`;
+    return fit(text, REQUIRED_SKILLS_BUDGET, REQUIRED_SKILLS_POINTER).body;
+}
+function requiredSkillsSection(launch, variant) {
+    const wanted = launch.requiredSkills ?? [];
+    if (!wanted.length)
+        return null;
+    const skills = wanted.map((entry) => {
+        const skill = readSkillFile(variant?.dir ?? null, entry.name);
+        return skill ? { ...skill, label: entry.label ?? skill.name } : { name: entry.name, label: entry.label, body: '' };
+    });
+    const text = requiredSkillsText(skills);
+    const seen = new Set();
+    const sources = skills.filter((skill) => skill.body && !seen.has(skill.name) && Boolean(seen.add(skill.name)))
+        .map((skill) => ({ id: skill.name, kind: 'skill', revision: variant?.fingerprint ?? null }));
+    return text
+        ? section('required-skills', 'Required skills', text, REQUIRED_SKILLS_BUDGET, REQUIRED_SKILLS_POINTER, sources)
+        : null;
+}
 /** An application's section, after any pinned text. */
 function hostSection(host) {
     const own = host.body !== null ? section(host.id, host.title, host.body, host.budget, host.pointer ?? '', []) : null;
@@ -281,6 +324,12 @@ export function compile(env, context, launch = {}, variant = null) {
     const { root } = env;
     const groups = toolGroups(context, launch, root);
     const variantSource = variant ? [{ id: variant.scope ?? variant.dir, kind: 'variant', revision: variant.fingerprint }] : [];
+    const toolSection = launch.hideToolGuidance ? null : tools(groups, variant?.toolGuidance ?? '', launch.toolsPointer ?? '');
+    // The tools section ends with the variant's tool guidance: record how much of it is the variant's.
+    if (toolSection && variant?.toolGuidance.trim() && !toolSection.cut) {
+        const block = `### How to use your tools\n\n${variant.toolGuidance.trim()}\n`;
+        toolSection.sources = [{ ...variantSource[0], chars: Math.min(block.length, toolSection.size) }];
+    }
     const built = [
         {
             order: SECTION_ORDER.harnessIdentity,
@@ -289,8 +338,9 @@ export function compile(env, context, launch = {}, variant = null) {
         ...(variant?.sections ?? []).map((entry) => ({ order: entry.order, section: section(entry.id, entry.title, entry.body, VARIANT_BUDGET, '', variantSource) })),
         { order: SECTION_ORDER.sessionState, section: sessionStateSection(launch.sessionState, launch.tools ?? []) },
         { order: SECTION_ORDER.references, section: selectedReferences(root, launch) },
+        { order: SECTION_ORDER.requiredSkills, section: requiredSkillsSection(launch, variant) },
         { order: SECTION_ORDER.wiki, section: wiki(root, context) },
-        { order: SECTION_ORDER.tools, section: launch.hideToolGuidance ? null : tools(groups, variant?.toolGuidance ?? '', launch.toolsPointer ?? '') },
+        { order: SECTION_ORDER.tools, section: toolSection },
         { order: SECTION_ORDER.reporting, section: section('reporting', 'Reporting your work', REPORTING_GUIDANCE, REPORTING_BUDGET, '', []) },
         ...(launch.standard ? standardSections({ ...launch.standard, project: launch.standard.project ?? projectName(root, context) }, launch.tools ?? []).filter((own) => !(launch.sections ?? []).some((host) => host.id === own.id)) : []).map((own) => ({ order: own.order, section: hostSection(own) })),
         ...(launch.sections ?? []).filter((host) => host.id !== 'session-state').map((host) => ({ order: host.order, section: hostSection(host) }))
@@ -306,17 +356,22 @@ export function compile(env, context, launch = {}, variant = null) {
         compiledAt: now()
     };
 }
-/** The pack as the one string a session receives. */
-export function render(env, pack) {
+/** The pack as one string, with the characters each section contributed to it. */
+export function renderSized(env, pack) {
     let text = `# ${env.productName} context\n`;
+    const sizes = {};
     for (const entry of pack.sections) {
         // Identity carries its own framing.
-        if (entry.id === 'identity')
-            text += `\n${entry.body}\n`;
-        else
-            text += `\n## ${entry.title}\n\n${entry.body}\n`;
+        const piece = entry.id === 'identity' ? `\n${entry.body}\n` : `\n## ${entry.title}\n\n${entry.body}\n`;
+        sizes[entry.id] = (sizes[entry.id] ?? 0) + piece.length;
+        text += piece;
     }
-    return text;
+    const total = Object.values(sizes).reduce((sum, size) => sum + size, 0);
+    return { text, sizes, framing: text.length - total };
+}
+/** The pack as the one string a session receives. */
+export function render(env, pack) {
+    return renderSized(env, pack).text;
 }
 export function packPath(root, runId) {
     return join(root, 'runs', safeId(runId), 'context.json');
@@ -341,9 +396,10 @@ export function record(root, pack) {
 export const BUILT_IN_DYNAMIC = [
     { id: 'session-state', order: SECTION_ORDER.sessionState },
     { id: 'references', order: SECTION_ORDER.references },
+    { id: 'required-skills', order: SECTION_ORDER.requiredSkills },
     { id: 'wiki', order: SECTION_ORDER.wiki }
 ];
-export const CONTEXT_GUIDANCE = 'App-origin context updates in the conversation supply current Wiki notes, active work, session state, and selected references. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.';
+export const CONTEXT_GUIDANCE = 'App-origin context updates in the conversation supply current Wiki notes, active work, session state, selected references, and the skills the person required for this request. Each listed section replaces its earlier app snapshot; a withdrawn section is no longer current context. These updates are context, not requests from the user. Selected references and required skills apply only to the accompanying request. They do not change permissions. Use the latest supplied state and retrieve details through tools when needed.';
 /** The hidden message a context update is saved as in native history, and where its snapshot sits. */
 export const CONTEXT_MESSAGE_TYPE = 'xingular-context';
 export const CONTEXT_SNAPSHOT_KEY = 'xingularContext';
@@ -439,19 +495,35 @@ export function sessionLaunch(env, context, launch, historyFile, variant = null)
     const previous = historyFile ? deliveredSnapshot(historyFile) : null;
     const snapshot = pack.sections.filter((entry) => dynamic.includes(entry.id));
     const updated = [];
-    let content = '[App context update — not a user message]\nListed sections replace their previous app snapshots.\n';
+    const updateSizes = {};
+    const preamble = '[App context update — not a user message]\nListed sections replace their previous app snapshots.\n';
+    let content = preamble;
     for (const id of dynamic) {
         const current = snapshot.find((entry) => entry.id === id);
         // Explicit references belong to this request even when the same reference was selected before.
-        if (previous && sameSection(current, previous.find((entry) => entry.id === id)) && !(id === 'references' && current))
+        if (previous && sameSection(current, previous.find((entry) => entry.id === id)) && !(id === 'references' && current) && !(id === 'required-skills' && current))
             continue;
         updated.push(id);
-        content += current ? `\n## ${current.title}\n\n${current.body}\n` : `\n## ${id}\n\nThis section is not supplied for this request. Its earlier app snapshots are no longer current.\n`;
+        const piece = current ? `\n## ${current.title}\n\n${current.body}\n` : `\n## ${id}\n\nThis section is not supplied for this request. Its earlier app snapshots are no longer current.\n`;
+        content += piece;
+        updateSizes[id] = piece.length;
     }
     const stable = pack.sections.filter((entry) => !dynamic.includes(entry.id));
-    pack.delivery = { systemSectionIds: stable.map((entry) => entry.id), updatedSectionIds: updated };
+    const rendered = renderSized(env, { sections: stable });
+    const system = `${rendered.text}\n## Context updates\n\n${CONTEXT_GUIDANCE}\n`;
+    const total = (sizes) => Object.values(sizes).reduce((sum, size) => sum + size, 0);
+    pack.delivery = {
+        systemSectionIds: stable.map((entry) => entry.id),
+        updatedSectionIds: updated,
+        sizes: {
+            system: rendered.sizes,
+            update: updated.length ? updateSizes : {},
+            systemFraming: system.length - total(rendered.sizes),
+            updateFraming: updated.length ? content.length - total(updateSizes) : 0
+        }
+    };
     record(env.root, pack);
-    return { system: `${render(env, { sections: stable })}\n## Context updates\n\n${CONTEXT_GUIDANCE}\n`, update: updated.length ? { content, snapshot } : null, pack };
+    return { system, update: updated.length ? { content, snapshot } : null, pack };
 }
 // ---- Sessions that keep the instructions they started with ---------------------------------
 /** A terminal session keeps the pack it started with; each of its runs records a copy. */

package/dist/sdk/remote/addresses.d.ts

@@ -0,0 +1,19 @@
+import { type NetworkInterfaceInfo } from 'node:os';
+export type RemoteAddressKind = 'tailscale' | 'lan';
+export type RemoteInterfaceChoice = 'auto' | RemoteAddressKind;
+export interface RemoteAddress {
+    kind: RemoteAddressKind;
+    address: string;
+    family: 'IPv4' | 'IPv6';
+    interface: string;
+}
+/** Tailscale hands out 100.64.0.0/10 and fd7a:115c:a1e0::/48. */
+export declare function isTailscale(address: string): boolean;
+/** RFC 1918 private IPv4 ranges. */
+export declare function isPrivateLan(address: string): boolean;
+/** Every address remote control may bind, Tailscale first. */
+export declare function remoteAddresses(interfaces?: NodeJS.Dict<NetworkInterfaceInfo[]>): RemoteAddress[];
+/** The one address to listen on for a choice, or a clear error when there is none. */
+export declare function pickRemoteAddress(choice: RemoteInterfaceChoice, candidates: readonly RemoteAddress[]): RemoteAddress;
+/** How a URL names the address. */
+export declare function hostPart(address: RemoteAddress): string;

package/dist/sdk/remote/addresses.js

@@ -0,0 +1,52 @@
+// Where remote control may listen: a Tailscale address or a private LAN address, never a public
+// one, never every interface (INV-RC-1).
+import { networkInterfaces } from 'node:os';
+import { HarnessError } from "../core/errors.js";
+const octets = (address) => address.split('.').map(Number);
+/** Tailscale hands out 100.64.0.0/10 and fd7a:115c:a1e0::/48. */
+export function isTailscale(address) {
+    if (address.includes(':'))
+        return address.toLowerCase().startsWith('fd7a:115c:a1e0:');
+    const [a, b] = octets(address);
+    return a === 100 && b >= 64 && b <= 127;
+}
+/** RFC 1918 private IPv4 ranges. */
+export function isPrivateLan(address) {
+    if (address.includes(':'))
+        return false;
+    const [a, b] = octets(address);
+    return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+}
+/** Every address remote control may bind, Tailscale first. */
+export function remoteAddresses(interfaces = networkInterfaces()) {
+    const found = [];
+    for (const [name, entries] of Object.entries(interfaces)) {
+        for (const entry of entries ?? []) {
+            if (entry.internal)
+                continue;
+            const family = entry.family === 'IPv6' ? 'IPv6' : 'IPv4';
+            if (isTailscale(entry.address))
+                found.push({ kind: 'tailscale', address: entry.address, family, interface: name });
+            else if (isPrivateLan(entry.address))
+                found.push({ kind: 'lan', address: entry.address, family, interface: name });
+        }
+    }
+    // IPv4 first within a kind: it is what a person can type and what every phone resolves.
+    const rank = (address) => (address.kind === 'tailscale' ? 0 : 2) + (address.family === 'IPv4' ? 0 : 1);
+    return found.sort((a, b) => rank(a) - rank(b));
+}
+/** The one address to listen on for a choice, or a clear error when there is none. */
+export function pickRemoteAddress(choice, candidates) {
+    const pick = choice === 'auto' ? candidates[0] : candidates.find((candidate) => candidate.kind === choice);
+    if (pick)
+        return pick;
+    if (choice === 'tailscale')
+        throw new HarnessError('remote_unavailable', 'No Tailscale address found. Start Tailscale on this computer, or use the Wi-Fi address instead.');
+    if (choice === 'lan')
+        throw new HarnessError('remote_unavailable', 'No private Wi-Fi or LAN address found. Join a network, or use Tailscale instead.');
+    throw new HarnessError('remote_unavailable', 'No Tailscale or private network address found. Join a Wi-Fi network or start Tailscale, then try /remote-control again.');
+}
+/** How a URL names the address. */
+export function hostPart(address) {
+    return address.family === 'IPv6' ? `[${address.address}]` : address.address;
+}

package/dist/sdk/remote/pairing.d.ts

@@ -0,0 +1,59 @@
+import { ReplayGuard } from "./seal.js";
+export declare const MAX_DEVICES = 3;
+/** Under a minute: a phone's browser gives up on a request it waits on much longer. */
+export declare const CONFIRM_MS = 50000;
+export interface RemoteDevice {
+    id: string;
+    label: string;
+    key: Uint8Array;
+    pairedAt: number;
+    lastSeen: number;
+    /** The counters this device has sent. */
+    replay: ReplayGuard;
+    /** The counter of the last frame sent to it. */
+    lastOut: number;
+}
+export interface PairRequest {
+    id: string;
+    label: string;
+    at: number;
+}
+/** A short, printable name for a browser from its user agent. Nothing from the phone is trusted. */
+export declare function deviceLabel(userAgent: unknown): string;
+export declare class Pairing {
+    private readonly changed;
+    private readonly clock;
+    private link;
+    private linkReplay;
+    private pending;
+    private readonly devices;
+    private hellos;
+    private failures;
+    private notice;
+    constructor(changed?: () => void, clock?: () => number);
+    private newLink;
+    /** What follows `#` in the pairing URL. */
+    get fragment(): string;
+    get request(): PairRequest | null;
+    /** A warning for the terminal page, such as a link replaced after repeated bad attempts. */
+    get warning(): string | null;
+    list(): RemoteDevice[];
+    device(deviceId: string): RemoteDevice | null;
+    /** A new link; every paired device is dropped and a waiting request denied. */
+    rotate(): void;
+    forget(deviceId: string): void;
+    /** The person at the terminal allowed or refused a waiting request. */
+    confirm(requestId: string, allow: boolean): void;
+    private fail;
+    /**
+     * A phone opened the pairing link. Waits until the person at the terminal decides, then returns
+     * the device's id and key, sealed with the link key.
+     */
+    hello(pairingId: unknown, frame: unknown, confirmMs?: number): Promise<string>;
+    /** Opens a paired device's frame, enforcing its counter. */
+    openFrom<T = unknown>(deviceId: unknown, frame: unknown): {
+        device: RemoteDevice;
+        body: T;
+    };
+    sealFor(device: RemoteDevice, body: unknown): string;
+}

package/dist/sdk/remote/pairing.js

@@ -0,0 +1,160 @@
+// Pairing for remote control. The QR code carries a pairing link: an id and a key, in the URL's
+// fragment. A phone that opens it says hello, sealed with that key; the person at the terminal
+// confirms; the phone receives its own device key. A link pairs one device and is then replaced,
+// so the QR on screen always pairs the next one. Every key lives in memory only (INV-RC-2).
+import { randomBytes } from 'node:crypto';
+import { HarnessError } from "../core/errors.js";
+import { encode, newKey, open, ReplayGuard, sameSecret, seal } from "./seal.js";
+export const MAX_DEVICES = 3;
+const HELLO_WINDOW_MS = 60_000;
+const MAX_HELLOS = 10;
+const MAX_FAILURES = 20;
+/** Under a minute: a phone's browser gives up on a request it waits on much longer. */
+export const CONFIRM_MS = 50_000;
+/** A short, printable name for a browser from its user agent. Nothing from the phone is trusted. */
+export function deviceLabel(userAgent) {
+    const ua = typeof userAgent === 'string' ? userAgent.slice(0, 400) : '';
+    const device = /iPad/.test(ua) ? 'iPad'
+        : /iPhone/.test(ua) ? 'iPhone'
+            : /Android/.test(ua) ? 'Android'
+                : /Macintosh|Mac OS X/.test(ua) ? (/Mobile/.test(ua) ? 'iPad' : 'Mac')
+                    : /Windows/.test(ua) ? 'Windows'
+                        : /Linux/.test(ua) ? 'Linux' : 'Browser';
+    const browser = /EdgiOS|EdgA|Edg\//.test(ua) ? 'Edge'
+        : /CriOS|Chrome\//.test(ua) ? 'Chrome'
+            : /FxiOS|Firefox\//.test(ua) ? 'Firefox'
+                : /Safari\//.test(ua) ? 'Safari' : '';
+    return browser ? `${device} · ${browser}` : device;
+}
+const id = () => randomBytes(12).toString('base64url');
+export class Pairing {
+    changed;
+    clock;
+    link = { id: id(), key: newKey() };
+    linkReplay = new ReplayGuard();
+    pending = null;
+    devices = new Map();
+    hellos = [];
+    failures = 0;
+    notice = null;
+    constructor(changed = () => { }, clock = Date.now) {
+        this.changed = changed;
+        this.clock = clock;
+    }
+    newLink() {
+        this.link = { id: id(), key: newKey() };
+        this.linkReplay = new ReplayGuard();
+    }
+    /** What follows `#` in the pairing URL. */
+    get fragment() {
+        return `${this.link.id}.${encode(this.link.key)}`;
+    }
+    get request() {
+        return this.pending ? { id: this.pending.id, label: this.pending.label, at: this.pending.at } : null;
+    }
+    /** A warning for the terminal page, such as a link replaced after repeated bad attempts. */
+    get warning() {
+        return this.notice;
+    }
+    list() {
+        return [...this.devices.values()];
+    }
+    device(deviceId) {
+        for (const [known, device] of this.devices)
+            if (sameSecret(known, deviceId))
+                return device;
+        return null;
+    }
+    /** A new link; every paired device is dropped and a waiting request denied. */
+    rotate() {
+        this.newLink();
+        this.pending?.decide(false);
+        this.pending = null;
+        this.devices.clear();
+        this.failures = 0;
+        this.notice = null;
+        this.changed();
+    }
+    forget(deviceId) {
+        const device = this.device(deviceId);
+        if (device && this.devices.delete(device.id))
+            this.changed();
+    }
+    /** The person at the terminal allowed or refused a waiting request. */
+    confirm(requestId, allow) {
+        if (!this.pending || this.pending.id !== requestId)
+            throw new HarnessError('invalid_request', 'This pairing request is no longer waiting.');
+        this.pending.decide(allow);
+    }
+    fail() {
+        this.failures += 1;
+        if (this.failures >= MAX_FAILURES) {
+            this.newLink();
+            this.failures = 0;
+            this.notice = 'Too many failed pairing attempts. The link was replaced; scan the new QR code.';
+            this.changed();
+        }
+        return new HarnessError('unauthorized', 'This pairing link is not valid. Scan the QR code in the terminal again.');
+    }
+    /**
+     * A phone opened the pairing link. Waits until the person at the terminal decides, then returns
+     * the device's id and key, sealed with the link key.
+     */
+    async hello(pairingId, frame, confirmMs = CONFIRM_MS) {
+        const at = this.clock();
+        this.hellos = this.hellos.filter((time) => at - time < HELLO_WINDOW_MS);
+        if (this.hellos.length >= MAX_HELLOS)
+            throw new HarnessError('rate_limited', 'Too many pairing attempts. Wait a minute and try again.');
+        this.hellos.push(at);
+        if (typeof pairingId !== 'string' || typeof frame !== 'string' || !sameSecret(pairingId, this.link.id))
+            throw this.fail();
+        const link = this.link;
+        let body;
+        try {
+            body = open(link.key, frame, (n) => this.linkReplay.accept(n)).body ?? {};
+        }
+        catch {
+            throw this.fail();
+        }
+        if (this.pending)
+            throw new HarnessError('remote_busy', 'Another device is waiting for approval in the terminal.');
+        if (this.devices.size >= MAX_DEVICES)
+            throw new HarnessError('remote_full', `At most ${MAX_DEVICES} devices can control a session. Press n in /remote-control to start over.`);
+        const label = deviceLabel(body.userAgent);
+        const allowed = await new Promise((resolve) => {
+            const timer = setTimeout(() => decide(false), confirmMs);
+            timer.unref?.();
+            const decide = (allow) => {
+                clearTimeout(timer);
+                if (this.pending?.decide === decide)
+                    this.pending = null;
+                resolve(allow);
+                this.changed();
+            };
+            this.pending = { id: id(), label, at, decide };
+            this.changed();
+        });
+        // A rotation while the phone waited replaced this link; its request is void.
+        if (!allowed || this.link !== link)
+            throw new HarnessError('remote_denied', 'Pairing was not allowed at the terminal.');
+        const device = { id: id(), label, key: newKey(), pairedAt: this.clock(), lastSeen: this.clock(), replay: new ReplayGuard(), lastOut: 0 };
+        this.devices.set(device.id, device);
+        // The link paired its device; the QR on screen now pairs the next one.
+        this.newLink();
+        this.changed();
+        return seal(link.key, 1, { deviceId: device.id, deviceKey: encode(device.key), label });
+    }
+    /** Opens a paired device's frame, enforcing its counter. */
+    openFrom(deviceId, frame) {
+        const device = typeof deviceId === 'string' ? this.device(deviceId) : null;
+        if (!device || typeof frame !== 'string')
+            throw new HarnessError('unauthorized', 'This device is not paired with the session. Scan the QR code in the terminal again.');
+        const opened = open(device.key, frame, (n) => device.replay.accept(n));
+        device.lastSeen = this.clock();
+        return { device, body: opened.body };
+    }
+    sealFor(device, body) {
+        device.lastOut += 1;
+        return seal(device.key, device.lastOut, body);
+    }
+}

package/dist/sdk/remote/seal.d.ts

@@ -0,0 +1,28 @@
+export declare const KEY_BYTES: number;
+/** How far behind the highest counter a frame may arrive, for requests a phone sent at once. */
+export declare const REPLAY_WINDOW = 256;
+export interface Opened<T> {
+    n: number;
+    body: T;
+}
+export declare function newKey(): Uint8Array;
+/** URL-safe base64 without padding: it travels in fragments, query strings and SSE lines. */
+export declare function encode(bytes: Uint8Array): string;
+export declare function decode(text: string): Uint8Array;
+export declare function seal(key: Uint8Array, n: number, body: unknown): string;
+/**
+ * Opens a frame and asks `fresh` whether its counter is new. A frame that fails here is a wrong
+ * key, a tampered body, or a replay; callers answer all three the same way.
+ */
+export declare function open<T = unknown>(key: Uint8Array, frame: string, fresh: (n: number) => boolean): Opened<T>;
+/**
+ * Remembers the counters a sender used: a counter is fresh when it is above the highest seen, or
+ * within the window below it and not seen before.
+ */
+export declare class ReplayGuard {
+    private highest;
+    private readonly recent;
+    accept(n: number): boolean;
+}
+/** Compares two identifiers without leaking how much of them matched. */
+export declare function sameSecret(a: string, b: string): boolean;