yarramate 0.16.0 → 0.18.0

package/dist/adapters/visual/protocol-contract.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Every visual protocol declaration, and the limits they are measured against,
+ * with no runtime dependency of any kind.
+ *
+ * The validators that police these documents live in `./protocol.js`, which
+ * re-exports this module so a Node consumer still has one import for the whole
+ * protocol. The split exists because the browser application ships the same
+ * contract: it can import these declarations and limits without pulling Ajv,
+ * `node:path`, or the schema documents into its bundle.
+ */
+export declare const VISUAL_PROTOCOL_VERSION: 'yarramate/visual-protocol/v1';
+export declare const VISUAL_LIMITS: {
+    readonly messageBytes: number;
+    readonly modelBytes: number;
+    readonly transcriptBytes: number;
+    readonly pendingEvents: 32;
+    readonly reconnectMs: number;
+    readonly staleSessionMs: number;
+};
+export type VisualAuthority = 'canonical' | 'ad-hoc';
+export interface VisualDiagnostic {
+    readonly severity: 'error';
+    readonly code: string;
+    readonly message: string;
+    readonly path: string;
+    readonly pointer: string;
+    readonly line: number;
+    readonly column: number;
+}
+export interface VisualDiagnosticResult {
+    readonly format: 'yarramate/visual-diagnostic-result/v1';
+    readonly diagnostics: readonly VisualDiagnostic[];
+}
+export interface VisualCapabilities {
+    readonly chat: boolean;
+    readonly choices: boolean;
+    readonly navigation: boolean;
+    readonly modelReplacement: boolean;
+    readonly transcript: boolean;
+}
+export interface VisualModel {
+    readonly format: 'yarramate/visual-model/v1';
+    readonly authority: VisualAuthority;
+    readonly initialView: string;
+    readonly sourceDigests: Readonly<Record<string, string>>;
+    readonly files: Readonly<Record<string, string>>;
+}
+export interface VisualCompilerCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export interface VisualSessionRequest {
+    readonly format: 'yarramate/visual-session-request/v1';
+    readonly authority: VisualModel['authority'];
+    readonly title: string;
+    readonly description: string;
+    readonly chatEnabled: boolean;
+    readonly compiler: VisualCompilerCommand;
+    readonly initialModel: VisualModel;
+}
+export interface VisualSessionStarted {
+    readonly format: 'yarramate/visual-session-started/v1';
+    readonly protocolVersion: typeof VISUAL_PROTOCOL_VERSION;
+    readonly sessionId: string;
+    readonly authority: VisualAuthority;
+    readonly title: string;
+    readonly chatEnabled: boolean;
+    readonly browserUrl: string;
+    readonly webSocketUrl: string;
+    readonly origin: string;
+    readonly descriptorPath: string;
+    readonly sessionRoot: string;
+    readonly capabilities: VisualCapabilities;
+    readonly startedAt: string;
+}
+export interface VisualSessionDescriptor {
+    readonly format: 'yarramate/visual-session-descriptor/v1';
+    readonly protocolVersion: typeof VISUAL_PROTOCOL_VERSION;
+    readonly sessionId: string;
+    readonly origin: string;
+    readonly agentCapability: string;
+    readonly sessionRoot: string;
+    readonly journalPath: string;
+    readonly createdAt: string;
+}
+export interface VisualChatMessagePayload {
+    readonly text: string;
+}
+export interface VisualChoiceSelectedPayload {
+    readonly choiceId: string;
+    readonly optionId: string;
+}
+export interface VisualViewNavigatePayload {
+    readonly viewId: string;
+    readonly requiresAttention: boolean;
+}
+/**
+ * Terminal event payload. Every reason is the runtime's to choose: only it
+ * knows whether a session ended by request, by a failing child, by a browser
+ * that never came back, or by its own cancellation.
+ */
+export interface VisualSessionEndPayload {
+    readonly reason: VisualTerminationReason;
+}
+/** End as an untrusted browser may ask for it, and nothing more. */
+export interface VisualBrowserSessionEndPayload {
+    readonly reason: 'user-ended';
+}
+export interface VisualBrowserConnectedPayload {
+    readonly connectionId: string;
+}
+export interface VisualBrowserDisconnectedPayload {
+    readonly connectionId: string;
+    readonly code: number;
+}
+/**
+ * Untrusted browser message. The runtime owns session identifiers, sequence
+ * numbers, event identifiers, and timestamps, so the browser may send only a
+ * discriminant, the last sequence it saw acknowledged, and its payload.
+ *
+ * `lastAcknowledgedSequence` is the browser's own view of the journal, carried
+ * on every frame so a session that reconnected mid-turn can be told it is
+ * ahead of the journal it claims to have read. It is 0 before the first
+ * acknowledgement, and never authorises anything: admission still assigns the
+ * sequence and event identifier.
+ */
+export type VisualBrowserInput = {
+    readonly type: 'chat.message';
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualChatMessagePayload;
+} | {
+    readonly type: 'choice.selected';
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualChoiceSelectedPayload;
+} | {
+    readonly type: 'view.navigate';
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualViewNavigatePayload;
+} | {
+    readonly type: 'session.end';
+    readonly lastAcknowledgedSequence: number;
+    readonly payload: VisualBrowserSessionEndPayload;
+};
+interface VisualEventEnvelope<Type extends string, Payload> {
+    readonly format: 'yarramate/visual-event/v1';
+    readonly sessionId: string;
+    readonly sequence: number;
+    readonly eventId: string;
+    readonly type: Type;
+    readonly timestamp: string;
+    readonly payload: Payload;
+}
+export type VisualEvent = VisualEventEnvelope<'chat.message', VisualChatMessagePayload> | VisualEventEnvelope<'choice.selected', VisualChoiceSelectedPayload> | VisualEventEnvelope<'view.navigate', VisualViewNavigatePayload> | VisualEventEnvelope<'session.end', VisualSessionEndPayload> | VisualEventEnvelope<'browser.connected', VisualBrowserConnectedPayload> | VisualEventEnvelope<'browser.disconnected', VisualBrowserDisconnectedPayload>;
+export interface VisualChatResponsePayload {
+    readonly text: string;
+}
+export interface VisualAgentStatusPayload {
+    readonly state: 'thinking' | 'compiling' | 'waiting' | 'idle';
+    readonly detail?: string;
+}
+export interface VisualChoiceOption {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string;
+}
+export interface VisualChoicePresentPayload {
+    readonly choiceId: string;
+    readonly question: string;
+    readonly options: readonly VisualChoiceOption[];
+}
+export interface VisualModelReplacePayload {
+    readonly model: VisualModel;
+}
+export interface VisualHandoffSummary {
+    readonly summary: string;
+    readonly confirmedDecisions: readonly string[];
+    readonly requestedChanges: readonly string[];
+    readonly unresolvedQuestions: readonly string[];
+    readonly finalViews: readonly string[];
+}
+export interface VisualDiagnosticPayload {
+    readonly diagnostics: readonly VisualDiagnostic[];
+}
+interface VisualResponseEnvelope<Type extends string, Payload> {
+    readonly format: 'yarramate/visual-response/v1';
+    readonly sessionId: string;
+    readonly responseId: string;
+    readonly eventId: string;
+    readonly type: Type;
+    readonly timestamp: string;
+    readonly payload: Payload;
+}
+export type VisualResponse = VisualResponseEnvelope<'chat.response', VisualChatResponsePayload> | VisualResponseEnvelope<'agent.status', VisualAgentStatusPayload> | VisualResponseEnvelope<'choice.present', VisualChoicePresentPayload> | VisualResponseEnvelope<'model.replace', VisualModelReplacePayload> | VisualResponseEnvelope<'handoff.complete', VisualHandoffSummary> | VisualResponseEnvelope<'diagnostic', VisualDiagnosticPayload>;
+export type VisualHandoffDecision = 'completed' | 'cancelled' | 'failed';
+export type VisualTerminationReason = 'user-ended' | 'child-failed' | 'browser-timeout' | 'main-cancelled' | 'server-failed' | 'compiler-failed';
+export interface VisualHandoff extends VisualHandoffSummary {
+    readonly format: 'yarramate/visual-handoff/v1';
+    readonly sessionId: string;
+    readonly authority: VisualAuthority;
+    readonly decision: VisualHandoffDecision;
+    readonly terminationReason: VisualTerminationReason;
+    readonly lastSequence: number;
+    readonly transcriptPath: string;
+    readonly transcript?: readonly (VisualEvent | VisualResponse)[];
+    readonly completedAt: string;
+}
+export type VisualLifecycle = 'starting' | 'running' | 'draining' | 'stopped';
+export type VisualFreezeReason = 'message-bytes' | 'model-bytes' | 'transcript-bytes' | 'pending-events' | 'browser-disconnected' | 'terminal-event';
+export interface VisualStatus {
+    readonly format: 'yarramate/visual-status/v1';
+    readonly protocolVersion: typeof VISUAL_PROTOCOL_VERSION;
+    readonly sessionId: string;
+    readonly lifecycle: VisualLifecycle;
+    readonly alreadyStopped: boolean;
+    readonly server: {
+        readonly listening: boolean;
+        readonly origin: string;
+    };
+    readonly browser: {
+        readonly connected: boolean;
+        readonly connections: number;
+        readonly lastSeenAt?: string;
+        readonly graceExpiresAt?: string;
+    };
+    readonly agent: {
+        readonly attached: boolean;
+        readonly inFlightEventId: string | null;
+    };
+    readonly queue: {
+        readonly pendingEvents: number;
+        readonly lastSequence: number;
+        readonly frozen: boolean;
+        readonly frozenReason?: VisualFreezeReason;
+    };
+    readonly capabilities: VisualCapabilities;
+    readonly transcriptBytes: number;
+    readonly updatedAt: string;
+}
+export type ParseResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly VisualDiagnostic[];
+};
+export {};

package/dist/adapters/visual/protocol-contract.js

@@ -0,0 +1,19 @@
+/**
+ * Every visual protocol declaration, and the limits they are measured against,
+ * with no runtime dependency of any kind.
+ *
+ * The validators that police these documents live in `./protocol.js`, which
+ * re-exports this module so a Node consumer still has one import for the whole
+ * protocol. The split exists because the browser application ships the same
+ * contract: it can import these declarations and limits without pulling Ajv,
+ * `node:path`, or the schema documents into its bundle.
+ */
+export const VISUAL_PROTOCOL_VERSION = 'yarramate/visual-protocol/v1';
+export const VISUAL_LIMITS = {
+    messageBytes: 64 * 1024,
+    modelBytes: 5 * 1024 * 1024,
+    transcriptBytes: 5 * 1024 * 1024,
+    pendingEvents: 32,
+    reconnectMs: 5 * 60 * 1000,
+    staleSessionMs: 24 * 60 * 60 * 1000,
+};

package/dist/adapters/visual/protocol.d.ts

@@ -0,0 +1,13 @@
+import { type ParseResult, type VisualBrowserInput, type VisualDiagnosticResult, type VisualEvent, type VisualHandoff, type VisualModel, type VisualResponse, type VisualSessionDescriptor, type VisualSessionRequest, type VisualSessionStarted, type VisualStatus } from './protocol-contract.js';
+export * from './protocol-contract.js';
+export declare const isSafeVisualModelPath: (candidate: string) => boolean;
+export declare const parseVisualModel: (input: unknown) => ParseResult<VisualModel>;
+export declare const parseVisualSessionRequest: (input: unknown) => ParseResult<VisualSessionRequest>;
+export declare const parseVisualSessionStarted: (input: unknown) => ParseResult<VisualSessionStarted>;
+export declare const parseVisualSessionDescriptor: (input: unknown) => ParseResult<VisualSessionDescriptor>;
+export declare const parseVisualBrowserInput: (input: unknown) => ParseResult<VisualBrowserInput>;
+export declare const parseVisualEvent: (input: unknown) => ParseResult<VisualEvent>;
+export declare const parseVisualResponse: (input: unknown) => ParseResult<VisualResponse>;
+export declare const parseVisualHandoff: (input: unknown) => ParseResult<VisualHandoff>;
+export declare const parseVisualStatus: (input: unknown) => ParseResult<VisualStatus>;
+export declare const parseVisualDiagnosticResult: (input: unknown) => ParseResult<VisualDiagnosticResult>;

package/dist/adapters/visual/protocol.js

@@ -0,0 +1,258 @@
+import { posix } from 'node:path';
+import Ajv2020Module from 'ajv/dist/2020.js';
+import { describeSchemaViolation } from '../../source-document.js';
+import visualDiagnosticResultSchema from '../../../schema/yarramate-visual-diagnostic-result.schema.json' with { type: 'json'
+};
+import visualEventSchema from '../../../schema/yarramate-visual-event.schema.json' with { type: 'json'
+};
+import visualHandoffSchema from '../../../schema/yarramate-visual-handoff.schema.json' with { type: 'json'
+};
+import visualModelSchema from '../../../schema/yarramate-visual-model.schema.json' with { type: 'json'
+};
+import visualResponseSchema from '../../../schema/yarramate-visual-response.schema.json' with { type: 'json'
+};
+import visualSessionDescriptorSchema from '../../../schema/yarramate-visual-session-descriptor.schema.json' with { type: 'json'
+};
+import visualSessionRequestSchema from '../../../schema/yarramate-visual-session-request.schema.json' with { type: 'json'
+};
+import visualSessionStartedSchema from '../../../schema/yarramate-visual-session-started.schema.json' with { type: 'json'
+};
+import visualStatusSchema from '../../../schema/yarramate-visual-status.schema.json' with { type: 'json'
+};
+import { VISUAL_LIMITS, } from './protocol-contract.js';
+// One import site for the whole protocol: the declarations this module
+// validates travel with the validators.
+export * from './protocol-contract.js';
+const Ajv2020 = Ajv2020Module.default;
+const ajv = new Ajv2020({ allErrors: true });
+ajv.addSchema([
+    visualDiagnosticResultSchema,
+    visualModelSchema,
+    visualEventSchema,
+    visualResponseSchema,
+    visualSessionRequestSchema,
+    visualSessionStartedSchema,
+    visualSessionDescriptorSchema,
+    visualHandoffSchema,
+    visualStatusSchema,
+]);
+// Diagnostics report the document they came from rather than a source file,
+// because visual protocol documents arrive as parsed JSON over the wire.
+const documentPaths = new WeakMap();
+const visualValidator = (document, reference = `https://yarramate.org/schema/${document}`) => {
+    const compiled = ajv.getSchema(reference);
+    if (!compiled)
+        throw new Error(`Unknown visual schema reference: ${reference}`);
+    documentPaths.set(compiled, document);
+    return compiled;
+};
+const validateVisualModel = visualValidator('visual-model/v1');
+const validateVisualSessionRequest = visualValidator('visual-session-request/v1');
+const validateVisualSessionStarted = visualValidator('visual-session-started/v1');
+const validateVisualSessionDescriptor = visualValidator('visual-session-descriptor/v1');
+const validateVisualBrowserInput = visualValidator('visual-browser-input/v1', 'https://yarramate.org/schema/visual-event/v1#/$defs/browserInput');
+const validateVisualEvent = visualValidator('visual-event/v1');
+const validateVisualResponse = visualValidator('visual-response/v1');
+const validateVisualHandoff = visualValidator('visual-handoff/v1');
+const validateVisualStatus = visualValidator('visual-status/v1');
+const validateVisualDiagnosticResult = visualValidator('visual-diagnostic-result/v1');
+/**
+ * Reads an untrusted document's own fields. Semantic checks run beside schema
+ * validation on raw input, so anything that is not a plain object simply has
+ * no fields to inspect and the schema reports the type violation.
+ */
+const documentFields = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value
+    : {};
+const pointerSegment = (segment) => segment.replace(/~/g, '~0').replace(/\//g, '~1');
+const visualDiagnostic = (code, message, path, pointer) => ({
+    severity: 'error',
+    code,
+    message,
+    path,
+    pointer,
+    line: 1,
+    column: 1,
+});
+const visualDiagnosticOrder = (left, right) => left.pointer.localeCompare(right.pointer) ||
+    left.code.localeCompare(right.code) ||
+    left.message.localeCompare(right.message);
+const jsonBytes = (value) => {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        return 0;
+    return Buffer.byteLength(encoded, 'utf8');
+};
+const MODEL_ROOT_CONFIG = 'likec4.config.json';
+const MODEL_SOURCE_EXTENSIONS = ['.c4', '.likec4'];
+/**
+ * Relative POSIX path confined to the candidate root. Absolute paths, parent
+ * traversal, empty segments, dot-prefixed segments (how a staged symlink or
+ * metadata entry would be smuggled in), Windows separators, and NUL bytes are
+ * all rejected.
+ */
+const isConfinedRelativePath = (candidate) => {
+    if (candidate.length === 0 || candidate.length > 1024)
+        return false;
+    if (candidate.includes('\\') || candidate.includes('\u0000'))
+        return false;
+    if (posix.isAbsolute(candidate))
+        return false;
+    if (posix.normalize(candidate) !== candidate)
+        return false;
+    return candidate
+        .split('/')
+        .every((segment) => segment.length > 0 && !segment.startsWith('.'));
+};
+export const isSafeVisualModelPath = (candidate) => {
+    if (!isConfinedRelativePath(candidate))
+        return false;
+    if (candidate === MODEL_ROOT_CONFIG)
+        return true;
+    const extension = posix.extname(candidate);
+    return MODEL_SOURCE_EXTENSIONS.some((allowed) => allowed === extension);
+};
+const modelSemantics = (input, path, prefix) => {
+    const fields = documentFields(input);
+    const diagnostics = [];
+    const files = documentFields(fields.files);
+    const fileKeys = Object.keys(files);
+    if (fileKeys.length > 0) {
+        let sources = 0;
+        for (const key of fileKeys) {
+            if (!isSafeVisualModelPath(key)) {
+                diagnostics.push(visualDiagnostic('YMVS113', `Model file "${key}" escapes the candidate root or is not a LikeC4 source`, path, `${prefix}/files/${pointerSegment(key)}`));
+                continue;
+            }
+            if (key !== MODEL_ROOT_CONFIG)
+                sources += 1;
+        }
+        if (sources === 0) {
+            diagnostics.push(visualDiagnostic('YMVS114', 'A visual model requires at least one .c4 or .likec4 source file', path, `${prefix}/files`));
+        }
+    }
+    const digestKeys = Object.keys(documentFields(fields.sourceDigests));
+    for (const key of digestKeys) {
+        if (isConfinedRelativePath(key))
+            continue;
+        diagnostics.push(visualDiagnostic('YMVS113', `Source digest "${key}" escapes the candidate root`, path, `${prefix}/sourceDigests/${pointerSegment(key)}`));
+    }
+    if (fields.authority === 'canonical' && digestKeys.length === 0) {
+        diagnostics.push(visualDiagnostic('YMVS112', 'A canonical visual model must record the source digests it was derived from', path, `${prefix}/sourceDigests`));
+    }
+    if (fields.authority === 'ad-hoc' && digestKeys.length > 0) {
+        diagnostics.push(visualDiagnostic('YMVS112', 'An ad-hoc visual model must not claim canonical source digests', path, `${prefix}/sourceDigests`));
+    }
+    if (jsonBytes(input) > VISUAL_LIMITS.modelBytes) {
+        diagnostics.push(visualDiagnostic('YMVS115', `A visual model must not exceed ${VISUAL_LIMITS.modelBytes} bytes`, path, prefix === '' ? '/' : prefix));
+    }
+    return diagnostics;
+};
+const chatTextSemantics = (payload, path, prefix) => {
+    const text = documentFields(payload).text;
+    if (typeof text !== 'string' ||
+        Buffer.byteLength(text, 'utf8') <= VISUAL_LIMITS.messageBytes) {
+        return [];
+    }
+    return [
+        visualDiagnostic('YMVS115', `A chat message must not exceed ${VISUAL_LIMITS.messageBytes} bytes`, path, `${prefix}/text`),
+    ];
+};
+const sessionRequestSemantics = (input, path) => {
+    const fields = documentFields(input);
+    const modelAuthority = documentFields(fields.initialModel).authority;
+    const diagnostics = [
+        ...modelSemantics(fields.initialModel, path, '/initialModel'),
+    ];
+    if (typeof fields.authority === 'string' &&
+        typeof modelAuthority === 'string' &&
+        fields.authority !== modelAuthority) {
+        diagnostics.push(visualDiagnostic('YMVS111', `Session authority "${fields.authority}" does not match the initial model authority "${modelAuthority}"`, path, '/initialModel/authority'));
+    }
+    return diagnostics;
+};
+const chatCarryingSemantics = (input, path) => {
+    const fields = documentFields(input);
+    if (fields.type !== 'chat.message')
+        return [];
+    return chatTextSemantics(fields.payload, path, '/payload');
+};
+const responseSemantics = (input, path) => {
+    const fields = documentFields(input);
+    if (fields.type === 'chat.response') {
+        return chatTextSemantics(fields.payload, path, '/payload');
+    }
+    if (fields.type === 'model.replace') {
+        return modelSemantics(documentFields(fields.payload).model, path, '/payload/model');
+    }
+    return [];
+};
+/**
+ * A handoff is one session's record. The schema validates each transcript entry
+ * as a well-formed event or response but cannot relate it to the document that
+ * carries it, so the one cross-session check the nine documents would otherwise
+ * be missing is made here: every entry names the session the handoff does.
+ */
+const handoffSemantics = (input, path) => {
+    const fields = documentFields(input);
+    const transcript = fields.transcript;
+    if (transcript === undefined)
+        return [];
+    const diagnostics = [];
+    if (jsonBytes(transcript) > VISUAL_LIMITS.transcriptBytes) {
+        diagnostics.push(visualDiagnostic('YMVS115', `A raw transcript must not exceed ${VISUAL_LIMITS.transcriptBytes} bytes`, path, '/transcript'));
+    }
+    if (Array.isArray(transcript)) {
+        for (const [index, entry] of transcript.entries()) {
+            const owner = documentFields(entry).sessionId;
+            if (owner === fields.sessionId)
+                continue;
+            diagnostics.push(visualDiagnostic('YMVS116', `Transcript entry ${index} belongs to session "${String(owner)}", not "${String(fields.sessionId)}"`, path, `/transcript/${index}/sessionId`));
+        }
+    }
+    return diagnostics;
+};
+// Byte limits and path confinement are enforced here as well as in the schemas
+// so a schema regression cannot silently widen the untrusted input surface.
+const semanticsByDocument = {
+    'visual-model/v1': (input, path) => modelSemantics(input, path, ''),
+    'visual-session-request/v1': sessionRequestSemantics,
+    'visual-browser-input/v1': chatCarryingSemantics,
+    'visual-event/v1': chatCarryingSemantics,
+    'visual-response/v1': responseSemantics,
+    'visual-handoff/v1': handoffSemantics,
+};
+const schemaDiagnostics = (errors, code, path) => errors.map((error) => {
+    const property = error.keyword === 'additionalProperties'
+        ? String(error.params.additionalProperty)
+        : undefined;
+    const pointer = property
+        ? `${error.instancePath}/${pointerSegment(property)}`
+        : error.instancePath || '/';
+    return visualDiagnostic(code, property
+        ? `Property "${property}" is not allowed`
+        : `${path} schema violation: ${describeSchemaViolation(error)}`, path, pointer);
+});
+const parseWith = (validate, input, code) => {
+    const path = documentPaths.get(validate) ?? 'visual-document';
+    const semantics = semanticsByDocument[path];
+    const diagnostics = [
+        ...(validate(input)
+            ? []
+            : schemaDiagnostics(validate.errors ?? [], code, path)),
+        ...(semantics ? semantics(input, path) : []),
+    ].sort(visualDiagnosticOrder);
+    if (diagnostics.length > 0)
+        return { ok: false, diagnostics };
+    return { ok: true, value: input };
+};
+export const parseVisualModel = (input) => parseWith(validateVisualModel, input, 'YMVS106');
+export const parseVisualSessionRequest = (input) => parseWith(validateVisualSessionRequest, input, 'YMVS101');
+export const parseVisualSessionStarted = (input) => parseWith(validateVisualSessionStarted, input, 'YMVS102');
+export const parseVisualSessionDescriptor = (input) => parseWith(validateVisualSessionDescriptor, input, 'YMVS103');
+export const parseVisualBrowserInput = (input) => parseWith(validateVisualBrowserInput, input, 'YMVS109');
+export const parseVisualEvent = (input) => parseWith(validateVisualEvent, input, 'YMVS104');
+export const parseVisualResponse = (input) => parseWith(validateVisualResponse, input, 'YMVS105');
+export const parseVisualHandoff = (input) => parseWith(validateVisualHandoff, input, 'YMVS107');
+export const parseVisualStatus = (input) => parseWith(validateVisualStatus, input, 'YMVS108');
+export const parseVisualDiagnosticResult = (input) => parseWith(validateVisualDiagnosticResult, input, 'YMVS110');

package/dist/adapters/visual/session-server.d.ts

@@ -0,0 +1,130 @@
+import { type VisualDiagnostic, type VisualEvent, type VisualFreezeReason, type VisualHandoff, type VisualLifecycle, type VisualSessionRequest, type VisualSessionStarted, type VisualStatus, type VisualTerminationReason } from './protocol.js';
+import { type TerminalEventDependencies, type VisualSessionPaths } from './session-store.js';
+import type { VisualRenderedModel, VisualServerFrame, VisualSessionSnapshot, VisualTranscriptRecord } from './wire.js';
+export type { VisualRenderedModel, VisualServerFrame, VisualSessionSnapshot, VisualTranscriptRecord, };
+/**
+ * Document name reported by diagnostics the server itself raises — a refused
+ * frame, a frozen queue, or a transport violation that no protocol document
+ * owns.
+ */
+export declare const VISUAL_SERVER_DOCUMENT = "visual-session-server";
+/**
+ * Returned on every response. The policy admits no external origin at all, so
+ * neither a compromised model nor a hostile chat message can reach the network,
+ * and the page can be neither framed nor used as a base for relative fetches.
+ */
+export declare const VISUAL_BROWSER_HEADERS: {
+    readonly 'Referrer-Policy': 'no-referrer';
+    readonly 'X-Content-Type-Options': 'nosniff';
+    readonly 'Cache-Control': 'no-store';
+};
+/**
+ * This session's content policy. Every source stays `'self'`; the one addition
+ * is a per-session nonce for inline style, because the diagram renderer injects
+ * its own stylesheets at runtime. A nonce admits exactly the styles this
+ * application emits, where `'unsafe-inline'` would admit anyone's.
+ */
+export declare const visualContentSecurityPolicy: (styleNonce: string) => string;
+export declare const VISUAL_SERVER_LIMITS: {
+    /** WebSocket frame ceiling: one 64 KiB chat message plus its envelope. */
+    readonly browserFrameBytes: number;
+    /** Agent request body ceiling: one 5 MiB candidate model plus its envelope. */
+    readonly agentBodyBytes: number;
+    /** Agent stop requests carry a termination reason and nothing else. */
+    readonly agentControlBytes: 4096;
+    /** How long one agent long poll waits before answering "still idle". */
+    readonly agentPollMs: 30000;
+    /** Browser sockets one session serves at once. */
+    readonly browserConnections: 8;
+};
+export declare const VISUAL_SOCKET_PATH = "/socket";
+export type VisualEventDelivery = {
+    readonly waiting: false;
+    readonly event: VisualEvent;
+    readonly lastSequence: number;
+    readonly pendingEvents: number;
+} | {
+    readonly waiting: true;
+    readonly lastSequence: number;
+    readonly pendingEvents: number;
+};
+export type VisualResponseAcceptance = {
+    readonly accepted: true;
+    readonly duplicate: boolean;
+    readonly lastSequence: number;
+    readonly model?: VisualRenderedModel;
+    readonly diagnostics: readonly VisualDiagnostic[];
+} | {
+    readonly accepted: false;
+    readonly diagnostics: readonly VisualDiagnostic[];
+};
+export interface VisualServerClosed {
+    readonly reason: VisualTerminationReason;
+    readonly alreadyStopped: boolean;
+    readonly handoff: VisualHandoff | undefined;
+}
+export interface VisualServerOptions {
+    readonly request: VisualSessionRequest;
+    /** Directory that holds one directory per live session. */
+    readonly baseDir: string;
+    /** Root of the self-contained browser application. */
+    readonly assetRoot?: string;
+    readonly now?: () => Date;
+    readonly randomBytes?: (size: number) => Buffer;
+    readonly agentPollMs?: number;
+    /** Whether the handoff a stop returns carries the raw transcript. */
+    readonly includeTranscript?: boolean;
+    /**
+     * Arms the browser reconnect grace, and answers with the cancellation of the
+     * window it armed. Injected so the exact window a session waits is
+     * observable, and so it can elapse without waiting out five real minutes.
+     */
+    readonly schedule?: (task: () => Promise<void>, ms: number) => () => void;
+}
+export interface VisualServerHandle {
+    readonly started: VisualSessionStarted;
+    readonly closed: Promise<VisualServerClosed>;
+    status(): VisualStatus;
+    stop(reason: VisualTerminationReason): Promise<VisualServerClosed>;
+}
+/**
+ * The runtime half of one live session: everything the terminal transition
+ * mutates, and the hooks it needs to quiet the rest down first.
+ *
+ * `lifecycle` is the whole admission gate — only a `running` session takes a
+ * browser frame or an agent response — so freezing input is one assignment
+ * rather than a second flag that could disagree with it.
+ */
+export interface ActiveVisualSession {
+    readonly paths: VisualSessionPaths;
+    lifecycle: VisualLifecycle;
+    /** Cancels whatever the trusted compiler is doing for this session. */
+    readonly compilerAbort: AbortController;
+    /** Records why the browser stopped being able to speak. */
+    readonly freeze: (reason: VisualFreezeReason) => void;
+    /** Settles work already admitted, so recovery reads a quiet journal. */
+    readonly quiesce: () => Promise<void>;
+    readonly terminalEvent: TerminalEventDependencies;
+    /** The transition in flight, so concurrent causes converge on one run. */
+    terminating: Promise<VisualHandoff> | undefined;
+    /** What this session ended with, once it has ended. */
+    handoff: VisualHandoff | undefined;
+}
+/**
+ * Takes one session terminal, whatever caused it: a reviewer's End, a child
+ * that failed, a browser that never came back, a cancelling main agent, or a
+ * runtime shutting itself down.
+ *
+ * The order is the invariant. Input freezes before anything is read; the
+ * compiler is cancelled rather than waited out; work already admitted is still
+ * allowed to finish; exactly one terminal event is journaled; and the handoff
+ * is recovered without deleting anything, so `stop` — and only `stop` — is what
+ * removes the session directory.
+ */
+export declare const terminateVisualSession: (session: ActiveVisualSession, reason: VisualTerminationReason) => Promise<VisualHandoff>;
+/**
+ * Serves one authenticated visual session over loopback. The handle owns the
+ * session directory it created: `stop` recovers the handoff before deleting it,
+ * and answers every later call with that same outcome.
+ */
+export declare const startVisualServer: (options: VisualServerOptions) => Promise<VisualServerHandle>;