@camstack/addon-ai 0.4.2 → 0.4.3

package/dist/addon.js

@@ -7,6 +7,7 @@ let node_path = require("node:path");
 let node_path$1 = require_chunk.__toESM(node_path, 1);
 node_path = require_chunk.__toESM(node_path);
 let node_crypto = require("node:crypto");
+let node_net = require("node:net");
 let node_util = require("node:util");
 let node_fs = require("node:fs");
 node_fs = require_chunk.__toESM(node_fs, 1);
@@ -14,7 +15,6 @@ let node_zlib = require("node:zlib");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = require_chunk.__toESM(node_fs_promises);
 let node_child_process = require("node:child_process");
-let node_net = require("node:net");
 //#region ../types/dist/event-category-Bxo5yJjt.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
@@ -12667,9 +12667,12 @@ var LlmProfileSchema = object({
 	systemPrompt: string().optional(),
 	/** Total generation bound — the only one a unary call has. */
 	timeoutMs: number$1().int().positive().default(6e4),
-	/** Wait for response headers only. */
+	/** The TCP handshake only — "is the port even open". NOT the wait for
+	*  response headers: on the LM Studio / llama-server wire those are written
+	*  once the model has finished loading, so they belong to the bound below. */
 	connectTimeoutMs: number$1().int().positive().default(1e4),
-	/** Accepted, but no output yet — a cold GPU load lives here. */
+	/** Accepted, but no output yet — response headers included, because a cold
+	*  GPU load is exactly what happens before them. */
 	firstTokenTimeoutMs: number$1().int().positive().default(12e4),
 	/** Output started then stopped. */
 	idleTimeoutMs: number$1().int().positive().default(6e4),
@@ -14702,13 +14705,81 @@ var NcRuleActionsSchema = object({
 	*/
 	buttons: array(NcRuleNotificationButtonSchema).max(8).optional()
 });
+/**
+* "This rule applies only while `deviceId` is in one of `states`."
+*
+* The states are the DEVICE's own vocabulary — `AlarmState` for a panel,
+* `on`/`off` for a switch — not a normalised set, because normalising would
+* make the condition lie about devices whose states have no equivalent.
+*
+* An unreadable state does NOT match: see the engine's fail-closed gate. A
+* condition that fired on "I could not read it" would be worse than no gate.
+*/
+var NcDeviceStateConditionSchema = object({
+	deviceId: number$1().int(),
+	/** Any of these matches. */
+	states: array(string().min(1)).min(1)
+});
+/**
+* "This rule applies only while scene `sceneId` is `matched` / `diverged`."
+*
+* A GATE, not a trigger. `occupancy` and `audio` each DISCRIMINATE their rule —
+* carrying one makes the rule fire on that subject and nothing else. Scene is
+* the other shape entirely, the `deviceState` shape: it narrows a rule that
+* already has a trigger ("tell me about a person at the front door, but only
+* while the bin is still out"). That is why it composes with every delivery
+* instead of owning one, and why no new `NcDelivery` member and no new subject
+* kind exist for it — see D159.
+*
+* ── Identity ───────────────────────────────────────────────────────────────
+* `sceneId` is `SceneMonitor.id`, a `randomUUID()` minted by `createScene` —
+* globally unique, so it needs no device to disambiguate it. `deviceId` is
+* carried as a HINT for the editor and for the log line, never as part of the
+* lookup key: a rule whose hint drifted must still gate correctly.
+*
+* ── Which boolean ──────────────────────────────────────────────────────────
+* `latched` ABSENT means "whatever the scene itself says" — `SceneMonitor.emit`
+* already declares which boolean drives notification rules, and a second knob
+* that could disagree with it is exactly the D62 failure. Set it only to
+* override one rule against the scene's own default.
+*
+*  - LIVE reading (`emit`/`latched` resolve to live): passes iff
+*    `verdict === requiredState`. `unknown` — no reference for this light, view
+*    shifted, no snapshot — passes NEITHER. A scene that cannot judge is not
+*    evidence, in either direction.
+*  - LATCHED reading: passes iff `latched === (requiredState === 'diverged')`.
+*    The latch is a durable fact about the past ("it has diverged since I armed
+*    it"), so a camera that has gone dark does not clear it — that is the whole
+*    reason the operator asked for a latch.
+*
+* The gate reads an in-memory mirror (`NcSceneStateCache`) refreshed OFF the
+* event path, never the cap: D49. A mirror that has never loaded, or a scene it
+* does not carry, reads absent and the rule does NOT fire — fail closed, and
+* said out loud in the log rather than dropped in silence.
+*/
+var NcSceneConditionSchema = object({
+	/** `SceneMonitor.id` — the uuid the cap mints. The whole lookup key. */
+	sceneId: string().min(1),
+	/** The camera the scene lives on. A hint for the editor and the log line. */
+	deviceId: number$1().int().optional(),
+	/** The state the scene must be in for the rule to fire. */
+	requiredState: _enum(["matched", "diverged"]),
+	/**
+	* Read the LATCH (`true`) or the LIVE verdict (`false`). Absent = follow the
+	* scene's own `emit` field, which is the only place that decision belongs.
+	*/
+	latched: boolean().optional()
+});
 var NcConditionsSchema = object({
 	/** Gate on ANOTHER device's current state (the alarm armed, a switch on). */
-	deviceState: object({
-		deviceId: number$1().int(),
-		/** Any of these matches. */
-		states: array(string().min(1)).min(1)
-	}).optional(),
+	deviceState: NcDeviceStateConditionSchema.optional(),
+	/**
+	* Gate on a SCENE's state — "only while the bin is still out". Composes with
+	* every trigger (detection, occupancy, audio, sensor, package, track-end);
+	* unlike `occupancy`/`audio` it discriminates nothing. See
+	* {@link NcSceneCondition} and D159.
+	*/
+	scene: NcSceneConditionSchema.optional(),
 	/** Device scope — absent = all devices. */
 	devices: array(number$1()).optional(),
 	/** Detector class names (any overlap with the record's class set). */
@@ -15346,6 +15417,7 @@ var NcConditionDescriptorSchema = object({
 		"occupancy",
 		"audio",
 		"deviceState",
+		"scene",
 		"systemEvent"
 	]),
 	operator: _enum([
@@ -24546,6 +24618,33 @@ method(object({
 *  as `unknown`, never guessed. A day reference scored against an IR frame
 *  collapses the cosine and would latch a false alarm every single night. */
 var SceneConditionSchema = string();
+/**
+* What a scene does when the CURRENT light has no reference of its own.
+*
+* The lighting variants are not equally likely to exist. Almost every operator
+* captures daylight and then never stands outside at 22:00 to capture IR, and a
+* scene that is only ever going to be asked about a daytime question ("is the
+* bin still on the kerb at 08:00") does not need a night reference at all. The
+* night half must therefore be OPTIONAL, and optional means the scene keeps
+* working without it rather than degrading into a permanent complaint.
+*
+* - `skip` (default) — the check in that light is not made. Not a verdict, not
+*   an alarm, not even an `unknown`: the live state simply stays whatever the
+*   last covered light left it at, the latch is untouched, and the hysteresis
+*   run is neither spent nor cleared. The scene resumes by itself at first
+*   light. This is the only behaviour under which "I never captured IR" is a
+*   configuration choice instead of a nightly fault.
+* - `judge-anyway` — score against the OTHER conditions' references. Available
+*   for cameras whose IR frame is close enough to daylight (a floodlit
+*   driveway, an always-white-light doorbell), and wrong for everything else:
+*   cross-condition cosines are not comparable, so a day reference against a
+*   true IR frame collapses and the scene reports a theft at 21:40.
+*
+* Never applies when the scene has NO comparable reference at all — that is
+* "not armed yet", it is reported as `no-reference-for-condition`, and silence
+* there would hide a scene the operator never finished setting up.
+*/
+var SceneUncoveredPolicySchema = _enum(["skip", "judge-anyway"]);
 /** `matched` = the baseline is what we see; `diverged` = it demonstrably is not;
 *  `unknown` = we cannot judge (no reference for this condition, encoder model
 *  changed, view shifted, no snapshot). `unknown` is a real value, not a null,
@@ -24601,6 +24700,9 @@ var SceneCheckSchema = discriminatedUnion("mode", [object({
 	hysteresisCount: number$1().int().positive()
 })]);
 var SCENE_DEFAULT_ANCHOR_THRESHOLD = .85;
+/** Night is OPTIONAL. A scene with only a daylight reference sits the IR hours
+*  out in silence rather than reporting a fault every night. */
+var SCENE_DEFAULT_UNCOVERED_POLICY = "skip";
 /**
 * Vision-model adjudication of a candidate flip. Field names deliberately
 * mirror `NcConfirmSchema` so an operator meets one vocabulary, not two.
@@ -24667,6 +24769,21 @@ var SceneMonitorSchema = object({
 	*  automation can react to the bin coming back without the operator's own
 	*  alarm silently clearing itself. */
 	autoRestore: boolean().default(false),
+	/** What to do when the current light has no reference of its own. See
+	*  {@link SceneUncoveredPolicySchema} — the default makes night OPTIONAL. */
+	onUncoveredCondition: SceneUncoveredPolicySchema.default(SCENE_DEFAULT_UNCOVERED_POLICY),
+	/**
+	* The light whose checks are currently being SAT OUT under
+	* `onUncoveredCondition: 'skip'` — `null` when the scene is checking normally.
+	*
+	* Engine-reported and advisory only: it moves no verdict, no latch and no
+	* hysteresis. It exists so the card can say *"night (IR) — checks paused,
+	* nothing captured in this light"* in the same calm voice as the coverage
+	* line, because the alternative is a scene that silently stops answering
+	* after sunset with nothing anywhere saying why. A skipped check must never
+	* read as a broken one.
+	*/
+	suspendedCondition: SceneConditionSchema.nullable().default(null),
 	/** Named cause when `verdict === 'unknown'`. */
 	unavailable: SceneUnavailableSchema.nullable(),
 	/** Conditions that have at least one comparable reference — the coverage line
@@ -24710,6 +24827,7 @@ DeviceType.Camera, method(object({ deviceId: number$1() }), SceneMonitorStatusSc
 		minObservationSpacingSec: number$1().int().min(0).max(3600).optional(),
 		anchorThreshold: number$1().min(0).max(1).optional(),
 		autoRestore: boolean().optional(),
+		onUncoveredCondition: SceneUncoveredPolicySchema.optional(),
 		/** `null` clears the vision-model adjudicator. */
 		confirm: SceneConfirmSchema.nullable().optional()
 	})
@@ -68757,6 +68875,108 @@ createIdGenerator({
 	size: 24
 });
 //#endregion
+//#region src/client/connect-probe.ts
+/**
+* "Is this endpoint accepting connections?" — and deliberately nothing else.
+*
+* ## Why this exists as its own step
+*
+* The `llm` taxonomy has always claimed a CONNECT bound distinct from the
+* FIRST-TOKEN one, on the grounds that they are different faults with different
+* remedies. The implementation did not honour that: it armed the 10 s connect
+* timer around the wait for HTTP RESPONSE HEADERS. On the wire this repo talks
+* to most — LM Studio / llama-server — the headers are the LAST thing that
+* happens before the first token: the server accepts the socket, reads the
+* request, loads the model into the GPU (minutes for qwen3-vl), and only then
+* writes a status line. So a cold load was reported as
+* `unavailable: the endpoint did not accept the connection within 10s`, and the
+* operator was sent to check a base URL that was correct. It cost two live
+* debugging sessions.
+*
+* A TCP handshake is the only thing that answers the connect question without
+* ambiguity, so that is what this probes: a closed port fails at once with
+* `ECONNREFUSED`, a black-holed address burns the whole bound, and a listening
+* endpoint says yes in a millisecond on a LAN — whatever it plans to do next.
+*
+* The socket is closed immediately. This is a probe, not the request; the real
+* call dials its own connection through the library's `fetch` a moment later.
+* That gap is a theoretical race (the port could shut in between) and a real
+* one would surface as the ordinary network error it is.
+*/
+var defaultConnectImpl = (endpoint) => (0, node_net.connect)({
+	host: endpoint.host,
+	port: endpoint.port
+});
+/**
+* The TCP endpoint a base URL points at, or `null` when there is not one.
+*
+* `null` is "do not probe", never "the endpoint is down": a profile whose URL
+* this cannot parse must fail on the real request with the real reason, not on
+* a guess made here.
+*/
+function tcpEndpointOf(baseUrl) {
+	let url;
+	try {
+		url = new URL(baseUrl);
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+	const port = url.port === "" ? url.protocol === "https:" ? 443 : 80 : Number(url.port);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+	const host = url.hostname.startsWith("[") && url.hostname.endsWith("]") ? url.hostname.slice(1, -1) : url.hostname;
+	return host.length === 0 ? null : {
+		host,
+		port
+	};
+}
+/**
+* Dial, and report which of the three things happened.
+*
+* Never rejects — the caller is `LlmClient`, which owes its own callers a
+* RESULT rather than a throw. `signal` is honoured so that an operator who
+* closes the page does not leave a socket dialling for the rest of the bound.
+*/
+function probeTcpConnect(endpoint, timeoutMs, signal, connectImpl = defaultConnectImpl) {
+	return new Promise((resolve) => {
+		let settled = false;
+		let socket = null;
+		const settle = (outcome) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+			socket?.destroy();
+			resolve(outcome);
+		};
+		const timer = setTimeout(() => settle({ kind: "timeout" }), timeoutMs);
+		timer.unref?.();
+		const onAbort = () => settle({
+			kind: "error",
+			message: "the connection attempt was cancelled"
+		});
+		signal.addEventListener("abort", onAbort, { once: true });
+		if (signal.aborted) {
+			onAbort();
+			return;
+		}
+		try {
+			socket = connectImpl(endpoint);
+		} catch (error) {
+			settle({
+				kind: "error",
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return;
+		}
+		socket.once("connect", () => settle({ kind: "connected" }));
+		socket.once("error", (error) => settle({
+			kind: "error",
+			message: error.message
+		}));
+	});
+}
+//#endregion
 //#region src/client/llm-client.ts
 /**
 * `LlmClient` — the ONE file in this repo allowed to import the LLM library.
@@ -68821,6 +69041,19 @@ function baseUrlFor$1(profile) {
 	return profile.kind === "openai" ? OPENAI_DEFAULT_BASE_URL$1 : null;
 }
 /**
+* Where to knock, for the connect probe.
+*
+* Wider than {@link baseUrlFor}: an Anthropic or Google profile with an
+* explicit `baseUrl` (a LAN proxy, a gateway) is just as probe-able as an
+* openai-compatible one. Only a profile that relies on a vendor's built-in
+* endpoint yields `null` — the client never learns that URL, and inventing one
+* to probe would be probing a different host from the one the call uses.
+*/
+function probeEndpointFor(profile) {
+	const baseUrl = profile.baseUrl !== void 0 && profile.baseUrl.length > 0 ? trimSlash(profile.baseUrl) : baseUrlFor$1(profile);
+	return baseUrl === null ? null : tcpEndpointOf(baseUrl);
+}
+/**
 * Build the provider instance for a profile.
 *
 * Returns `null` when the profile cannot be served — a missing base URL on an
@@ -69079,7 +69312,7 @@ function createLlmClient(deps = {}) {
 				if (isAbortLike(error) && !request.signal.aborted) return {
 					ok: false,
 					code: "timeout",
-					message: `timed out after ${String(timeoutMs)}ms`
+					message: `no answer within ${String(Math.round(timeoutMs / 1e3))}s — a cold model can take minutes to load; warm it or raise the profile's total timeout`
 				};
 				const mapped = mapLibraryError(error);
 				return {
@@ -69093,41 +69326,91 @@ function createLlmClient(deps = {}) {
 			if (!SUPPORTED_KINDS.has(request.profile.kind)) return { kind: "unsupported" };
 			const model = modelFor(request.profile);
 			if (model === null) return { kind: "unsupported" };
-			const connect = new AbortController();
-			const onOuterAbort = () => connect.abort();
+			const endpoint = probeEndpointFor(request.profile);
+			if (endpoint !== null) {
+				const probe = await probeTcpConnect(endpoint, opts.connectTimeoutMs, request.signal, deps.connectImpl ?? defaultConnectImpl);
+				if (probe.kind === "timeout") return {
+					kind: "connect-timeout",
+					timeoutMs: opts.connectTimeoutMs
+				};
+				if (probe.kind === "error") return {
+					kind: "network",
+					message: request.signal.aborted ? "the call was cancelled" : probe.message
+				};
+				opts.onConnected?.();
+			}
+			const firstChunkBound = new AbortController();
+			const onOuterAbort = () => firstChunkBound.abort();
 			request.signal.addEventListener("abort", onOuterAbort, { once: true });
-			const connectTimer = setTimeout(() => connect.abort(), opts.connectTimeoutMs);
-			connectTimer.unref?.();
+			const firstChunkTimer = setTimeout(() => firstChunkBound.abort(), opts.firstTokenTimeoutMs);
+			firstChunkTimer.unref?.();
+			let streamFailure;
 			try {
-				const stream = streamText({
+				const iterator = chunksFrom(streamText({
 					model,
 					messages: messagesFor(request),
 					...instructionsFor(request),
 					...callSettingsFor(request),
 					...structuredOutputFor(request),
-					abortSignal: AbortSignal.any([request.signal, connect.signal])
-				});
-				await stream.response;
+					abortSignal: AbortSignal.any([request.signal, firstChunkBound.signal]),
+					onError: ({ error }) => {
+						streamFailure = error;
+					}
+				}))[Symbol.asyncIterator]();
+				const first = await iterator.next();
+				if (streamFailure !== void 0) {
+					const mapped = mapLibraryError(streamFailure);
+					return {
+						kind: "provider-error",
+						code: mapped.code,
+						message: mapped.message
+					};
+				}
+				if (firstChunkBound.signal.aborted) return request.signal.aborted ? {
+					kind: "network",
+					message: "the call was cancelled"
+				} : {
+					kind: "first-token-timeout",
+					timeoutMs: opts.firstTokenTimeoutMs
+				};
 				return {
 					kind: "open",
-					chunks: chunksFrom(stream)
+					chunks: resumeFrom(first, iterator)
 				};
 			} catch (error) {
 				if (isAbortLike(error) && !request.signal.aborted) return {
-					kind: "connect-timeout",
-					timeoutMs: opts.connectTimeoutMs
+					kind: "first-token-timeout",
+					timeoutMs: opts.firstTokenTimeoutMs
 				};
+				const mapped = mapLibraryError(error);
 				return {
-					kind: "network",
-					message: mapLibraryError(error).message
+					kind: "provider-error",
+					code: mapped.code,
+					message: mapped.message
 				};
 			} finally {
-				clearTimeout(connectTimer);
+				clearTimeout(firstChunkTimer);
 				request.signal.removeEventListener("abort", onOuterAbort);
 			}
 		}
 	};
 }
+/**
+* Hand back a stream whose first chunk has already been pulled.
+*
+* `openStream` has to consume one chunk to know the model started — that is
+* what its bound measures — and the caller must still receive it. Replaying it
+* here is what keeps "the first token is the load signal" true for the reader.
+*/
+async function* resumeFrom(first, iterator) {
+	if (first.done === true) return;
+	yield first.value;
+	for (;;) {
+		const next = await iterator.next();
+		if (next.done === true) return;
+		yield next.value;
+	}
+}
 async function* chunksFrom(stream) {
 	for await (const text of stream.textStream) if (text.length > 0) yield {
 		kind: "token",
@@ -69473,7 +69756,7 @@ function httpProfileConfigSchema(opts) {
 					min: 500,
 					default: 1e4,
 					unit: "ms",
-					description: "Waiting for response headers — i.e. \"is the port even open\"."
+					description: "The TCP handshake — i.e. \"is the port even open\". A closed port fails at once; only a black hole spends the whole bound."
 				},
 				{
 					type: "number",
@@ -69482,7 +69765,7 @@ function httpProfileConfigSchema(opts) {
 					min: 1e3,
 					default: 12e4,
 					unit: "ms",
-					description: "Accepted but silent. A cold GPU load lives here and can take minutes."
+					description: "Accepted but silent — response headers included, since a model writes them once it has loaded. A cold GPU load lives here and can take minutes. The test chat waits exactly this long."
 				},
 				{
 					type: "number",
@@ -71556,10 +71839,27 @@ async function runTestChatStream(deps, request, emit, signal) {
 		kind: "status",
 		phase: "connecting"
 	});
+	let modelWaitStartedAt = null;
 	const opened = await deps.openStream(streamRequest, {
 		signal,
-		connectTimeoutMs: TEST_CHAT_CONNECT_TIMEOUT_MS
+		connectTimeoutMs: TEST_CHAT_CONNECT_TIMEOUT_MS,
+		firstTokenTimeoutMs: request.firstTokenTimeoutMs,
+		onConnected: () => {
+			modelWaitStartedAt = deps.now();
+			emit({
+				kind: "status",
+				phase: "first-token-wait"
+			});
+		}
 	});
+	/**
+	* What is LEFT of the first-token budget.
+	*
+	* The response headers and the first token are one wait spent two ways, so
+	* they draw on one budget: the page says "up to Ns" and that has to be the
+	* whole truth, not N per stage.
+	*/
+	const remainingFirstTokenMs = () => modelWaitStartedAt === null ? request.firstTokenTimeoutMs : Math.max(1, request.firstTokenTimeoutMs - (deps.now() - modelWaitStartedAt));
 	if (opened.kind === "connect-timeout") {
 		await fail({
 			code: "unavailable",
@@ -71580,6 +71880,20 @@ async function runTestChatStream(deps, request, emit, signal) {
 		});
 		return;
 	}
+	if (opened.kind === "provider-error") {
+		await fail({
+			code: opened.code,
+			message: opened.message
+		}, "ai test chat: provider refused the request — turn dropped", {
+			code: opened.code,
+			error: opened.message
+		});
+		return;
+	}
+	if (opened.kind === "first-token-timeout") {
+		await failFirstToken();
+		return;
+	}
 	const streamed = opened.kind === "open";
 	emit({
 		kind: "meta",
@@ -71605,7 +71919,7 @@ async function runTestChatStream(deps, request, emit, signal) {
 			kind: "status",
 			phase: "first-token-wait"
 		});
-		const raced = await withDeadline(deps.generateOnce(streamRequest), request.firstTokenTimeoutMs);
+		const raced = await withDeadline(deps.generateOnce(streamRequest), remainingFirstTokenMs());
 		if (signal.aborted) {
 			deps.logger.info("ai test chat: client aborted mid-generation", withTags({}));
 			return;
@@ -71663,7 +71977,7 @@ async function runTestChatStream(deps, request, emit, signal) {
 			deps.logger.info("ai test chat: client aborted mid-stream — provider call torn down", { ...withTags({ sawFirstToken }) });
 			return;
 		}
-		const next = await nextChunk(iterator, sawFirstToken ? TEST_CHAT_IDLE_TIMEOUT_MS : request.firstTokenTimeoutMs);
+		const next = await nextChunk(iterator, sawFirstToken ? TEST_CHAT_IDLE_TIMEOUT_MS : remainingFirstTokenMs());
 		if (next.kind === "timeout") {
 			if (!sawFirstToken) {
 				await failFirstToken();
@@ -71923,7 +72237,11 @@ var AiAddon = class extends BaseAddon {
 				...request.maxTokens !== void 0 ? { maxTokens: request.maxTokens } : {},
 				...request.temperature !== void 0 ? { temperature: request.temperature } : {},
 				signal: opts.signal
-			}, { connectTimeoutMs: opts.connectTimeoutMs }),
+			}, {
+				connectTimeoutMs: opts.connectTimeoutMs,
+				firstTokenTimeoutMs: opts.firstTokenTimeoutMs,
+				onConnected: opts.onConnected
+			}),
 			generateOnce: async (request) => {
 				const base = {
 					profileId: request.profile.id,

package/dist/addon.mjs

@@ -1,13 +1,13 @@
 import { createRequire } from "node:module";
 import * as path$1 from "node:path";
 import { createHash } from "node:crypto";
+import { connect, createServer } from "node:net";
 import { promisify } from "node:util";
 import * as fs from "node:fs";
 import { createReadStream } from "node:fs";
 import { brotliCompress, gzip } from "node:zlib";
 import * as fsp from "node:fs/promises";
 import { spawn } from "node:child_process";
-import { createServer } from "node:net";
 //#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp$1 = Object.defineProperty;
@@ -12693,9 +12693,12 @@ var LlmProfileSchema = object({
 	systemPrompt: string().optional(),
 	/** Total generation bound — the only one a unary call has. */
 	timeoutMs: number$1().int().positive().default(6e4),
-	/** Wait for response headers only. */
+	/** The TCP handshake only — "is the port even open". NOT the wait for
+	*  response headers: on the LM Studio / llama-server wire those are written
+	*  once the model has finished loading, so they belong to the bound below. */
 	connectTimeoutMs: number$1().int().positive().default(1e4),
-	/** Accepted, but no output yet — a cold GPU load lives here. */
+	/** Accepted, but no output yet — response headers included, because a cold
+	*  GPU load is exactly what happens before them. */
 	firstTokenTimeoutMs: number$1().int().positive().default(12e4),
 	/** Output started then stopped. */
 	idleTimeoutMs: number$1().int().positive().default(6e4),
@@ -14728,13 +14731,81 @@ var NcRuleActionsSchema = object({
 	*/
 	buttons: array(NcRuleNotificationButtonSchema).max(8).optional()
 });
+/**
+* "This rule applies only while `deviceId` is in one of `states`."
+*
+* The states are the DEVICE's own vocabulary — `AlarmState` for a panel,
+* `on`/`off` for a switch — not a normalised set, because normalising would
+* make the condition lie about devices whose states have no equivalent.
+*
+* An unreadable state does NOT match: see the engine's fail-closed gate. A
+* condition that fired on "I could not read it" would be worse than no gate.
+*/
+var NcDeviceStateConditionSchema = object({
+	deviceId: number$1().int(),
+	/** Any of these matches. */
+	states: array(string().min(1)).min(1)
+});
+/**
+* "This rule applies only while scene `sceneId` is `matched` / `diverged`."
+*
+* A GATE, not a trigger. `occupancy` and `audio` each DISCRIMINATE their rule —
+* carrying one makes the rule fire on that subject and nothing else. Scene is
+* the other shape entirely, the `deviceState` shape: it narrows a rule that
+* already has a trigger ("tell me about a person at the front door, but only
+* while the bin is still out"). That is why it composes with every delivery
+* instead of owning one, and why no new `NcDelivery` member and no new subject
+* kind exist for it — see D159.
+*
+* ── Identity ───────────────────────────────────────────────────────────────
+* `sceneId` is `SceneMonitor.id`, a `randomUUID()` minted by `createScene` —
+* globally unique, so it needs no device to disambiguate it. `deviceId` is
+* carried as a HINT for the editor and for the log line, never as part of the
+* lookup key: a rule whose hint drifted must still gate correctly.
+*
+* ── Which boolean ──────────────────────────────────────────────────────────
+* `latched` ABSENT means "whatever the scene itself says" — `SceneMonitor.emit`
+* already declares which boolean drives notification rules, and a second knob
+* that could disagree with it is exactly the D62 failure. Set it only to
+* override one rule against the scene's own default.
+*
+*  - LIVE reading (`emit`/`latched` resolve to live): passes iff
+*    `verdict === requiredState`. `unknown` — no reference for this light, view
+*    shifted, no snapshot — passes NEITHER. A scene that cannot judge is not
+*    evidence, in either direction.
+*  - LATCHED reading: passes iff `latched === (requiredState === 'diverged')`.
+*    The latch is a durable fact about the past ("it has diverged since I armed
+*    it"), so a camera that has gone dark does not clear it — that is the whole
+*    reason the operator asked for a latch.
+*
+* The gate reads an in-memory mirror (`NcSceneStateCache`) refreshed OFF the
+* event path, never the cap: D49. A mirror that has never loaded, or a scene it
+* does not carry, reads absent and the rule does NOT fire — fail closed, and
+* said out loud in the log rather than dropped in silence.
+*/
+var NcSceneConditionSchema = object({
+	/** `SceneMonitor.id` — the uuid the cap mints. The whole lookup key. */
+	sceneId: string().min(1),
+	/** The camera the scene lives on. A hint for the editor and the log line. */
+	deviceId: number$1().int().optional(),
+	/** The state the scene must be in for the rule to fire. */
+	requiredState: _enum(["matched", "diverged"]),
+	/**
+	* Read the LATCH (`true`) or the LIVE verdict (`false`). Absent = follow the
+	* scene's own `emit` field, which is the only place that decision belongs.
+	*/
+	latched: boolean().optional()
+});
 var NcConditionsSchema = object({
 	/** Gate on ANOTHER device's current state (the alarm armed, a switch on). */
-	deviceState: object({
-		deviceId: number$1().int(),
-		/** Any of these matches. */
-		states: array(string().min(1)).min(1)
-	}).optional(),
+	deviceState: NcDeviceStateConditionSchema.optional(),
+	/**
+	* Gate on a SCENE's state — "only while the bin is still out". Composes with
+	* every trigger (detection, occupancy, audio, sensor, package, track-end);
+	* unlike `occupancy`/`audio` it discriminates nothing. See
+	* {@link NcSceneCondition} and D159.
+	*/
+	scene: NcSceneConditionSchema.optional(),
 	/** Device scope — absent = all devices. */
 	devices: array(number$1()).optional(),
 	/** Detector class names (any overlap with the record's class set). */
@@ -15372,6 +15443,7 @@ var NcConditionDescriptorSchema = object({
 		"occupancy",
 		"audio",
 		"deviceState",
+		"scene",
 		"systemEvent"
 	]),
 	operator: _enum([
@@ -24572,6 +24644,33 @@ method(object({
 *  as `unknown`, never guessed. A day reference scored against an IR frame
 *  collapses the cosine and would latch a false alarm every single night. */
 var SceneConditionSchema = string();
+/**
+* What a scene does when the CURRENT light has no reference of its own.
+*
+* The lighting variants are not equally likely to exist. Almost every operator
+* captures daylight and then never stands outside at 22:00 to capture IR, and a
+* scene that is only ever going to be asked about a daytime question ("is the
+* bin still on the kerb at 08:00") does not need a night reference at all. The
+* night half must therefore be OPTIONAL, and optional means the scene keeps
+* working without it rather than degrading into a permanent complaint.
+*
+* - `skip` (default) — the check in that light is not made. Not a verdict, not
+*   an alarm, not even an `unknown`: the live state simply stays whatever the
+*   last covered light left it at, the latch is untouched, and the hysteresis
+*   run is neither spent nor cleared. The scene resumes by itself at first
+*   light. This is the only behaviour under which "I never captured IR" is a
+*   configuration choice instead of a nightly fault.
+* - `judge-anyway` — score against the OTHER conditions' references. Available
+*   for cameras whose IR frame is close enough to daylight (a floodlit
+*   driveway, an always-white-light doorbell), and wrong for everything else:
+*   cross-condition cosines are not comparable, so a day reference against a
+*   true IR frame collapses and the scene reports a theft at 21:40.
+*
+* Never applies when the scene has NO comparable reference at all — that is
+* "not armed yet", it is reported as `no-reference-for-condition`, and silence
+* there would hide a scene the operator never finished setting up.
+*/
+var SceneUncoveredPolicySchema = _enum(["skip", "judge-anyway"]);
 /** `matched` = the baseline is what we see; `diverged` = it demonstrably is not;
 *  `unknown` = we cannot judge (no reference for this condition, encoder model
 *  changed, view shifted, no snapshot). `unknown` is a real value, not a null,
@@ -24627,6 +24726,9 @@ var SceneCheckSchema = discriminatedUnion("mode", [object({
 	hysteresisCount: number$1().int().positive()
 })]);
 var SCENE_DEFAULT_ANCHOR_THRESHOLD = .85;
+/** Night is OPTIONAL. A scene with only a daylight reference sits the IR hours
+*  out in silence rather than reporting a fault every night. */
+var SCENE_DEFAULT_UNCOVERED_POLICY = "skip";
 /**
 * Vision-model adjudication of a candidate flip. Field names deliberately
 * mirror `NcConfirmSchema` so an operator meets one vocabulary, not two.
@@ -24693,6 +24795,21 @@ var SceneMonitorSchema = object({
 	*  automation can react to the bin coming back without the operator's own
 	*  alarm silently clearing itself. */
 	autoRestore: boolean().default(false),
+	/** What to do when the current light has no reference of its own. See
+	*  {@link SceneUncoveredPolicySchema} — the default makes night OPTIONAL. */
+	onUncoveredCondition: SceneUncoveredPolicySchema.default(SCENE_DEFAULT_UNCOVERED_POLICY),
+	/**
+	* The light whose checks are currently being SAT OUT under
+	* `onUncoveredCondition: 'skip'` — `null` when the scene is checking normally.
+	*
+	* Engine-reported and advisory only: it moves no verdict, no latch and no
+	* hysteresis. It exists so the card can say *"night (IR) — checks paused,
+	* nothing captured in this light"* in the same calm voice as the coverage
+	* line, because the alternative is a scene that silently stops answering
+	* after sunset with nothing anywhere saying why. A skipped check must never
+	* read as a broken one.
+	*/
+	suspendedCondition: SceneConditionSchema.nullable().default(null),
 	/** Named cause when `verdict === 'unknown'`. */
 	unavailable: SceneUnavailableSchema.nullable(),
 	/** Conditions that have at least one comparable reference — the coverage line
@@ -24736,6 +24853,7 @@ DeviceType.Camera, method(object({ deviceId: number$1() }), SceneMonitorStatusSc
 		minObservationSpacingSec: number$1().int().min(0).max(3600).optional(),
 		anchorThreshold: number$1().min(0).max(1).optional(),
 		autoRestore: boolean().optional(),
+		onUncoveredCondition: SceneUncoveredPolicySchema.optional(),
 		/** `null` clears the vision-model adjudicator. */
 		confirm: SceneConfirmSchema.nullable().optional()
 	})
@@ -68783,6 +68901,108 @@ createIdGenerator({
 	size: 24
 });
 //#endregion
+//#region src/client/connect-probe.ts
+/**
+* "Is this endpoint accepting connections?" — and deliberately nothing else.
+*
+* ## Why this exists as its own step
+*
+* The `llm` taxonomy has always claimed a CONNECT bound distinct from the
+* FIRST-TOKEN one, on the grounds that they are different faults with different
+* remedies. The implementation did not honour that: it armed the 10 s connect
+* timer around the wait for HTTP RESPONSE HEADERS. On the wire this repo talks
+* to most — LM Studio / llama-server — the headers are the LAST thing that
+* happens before the first token: the server accepts the socket, reads the
+* request, loads the model into the GPU (minutes for qwen3-vl), and only then
+* writes a status line. So a cold load was reported as
+* `unavailable: the endpoint did not accept the connection within 10s`, and the
+* operator was sent to check a base URL that was correct. It cost two live
+* debugging sessions.
+*
+* A TCP handshake is the only thing that answers the connect question without
+* ambiguity, so that is what this probes: a closed port fails at once with
+* `ECONNREFUSED`, a black-holed address burns the whole bound, and a listening
+* endpoint says yes in a millisecond on a LAN — whatever it plans to do next.
+*
+* The socket is closed immediately. This is a probe, not the request; the real
+* call dials its own connection through the library's `fetch` a moment later.
+* That gap is a theoretical race (the port could shut in between) and a real
+* one would surface as the ordinary network error it is.
+*/
+var defaultConnectImpl = (endpoint) => connect({
+	host: endpoint.host,
+	port: endpoint.port
+});
+/**
+* The TCP endpoint a base URL points at, or `null` when there is not one.
+*
+* `null` is "do not probe", never "the endpoint is down": a profile whose URL
+* this cannot parse must fail on the real request with the real reason, not on
+* a guess made here.
+*/
+function tcpEndpointOf(baseUrl) {
+	let url;
+	try {
+		url = new URL(baseUrl);
+	} catch {
+		return null;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+	const port = url.port === "" ? url.protocol === "https:" ? 443 : 80 : Number(url.port);
+	if (!Number.isInteger(port) || port < 1 || port > 65535) return null;
+	const host = url.hostname.startsWith("[") && url.hostname.endsWith("]") ? url.hostname.slice(1, -1) : url.hostname;
+	return host.length === 0 ? null : {
+		host,
+		port
+	};
+}
+/**
+* Dial, and report which of the three things happened.
+*
+* Never rejects — the caller is `LlmClient`, which owes its own callers a
+* RESULT rather than a throw. `signal` is honoured so that an operator who
+* closes the page does not leave a socket dialling for the rest of the bound.
+*/
+function probeTcpConnect(endpoint, timeoutMs, signal, connectImpl = defaultConnectImpl) {
+	return new Promise((resolve) => {
+		let settled = false;
+		let socket = null;
+		const settle = (outcome) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal.removeEventListener("abort", onAbort);
+			socket?.destroy();
+			resolve(outcome);
+		};
+		const timer = setTimeout(() => settle({ kind: "timeout" }), timeoutMs);
+		timer.unref?.();
+		const onAbort = () => settle({
+			kind: "error",
+			message: "the connection attempt was cancelled"
+		});
+		signal.addEventListener("abort", onAbort, { once: true });
+		if (signal.aborted) {
+			onAbort();
+			return;
+		}
+		try {
+			socket = connectImpl(endpoint);
+		} catch (error) {
+			settle({
+				kind: "error",
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return;
+		}
+		socket.once("connect", () => settle({ kind: "connected" }));
+		socket.once("error", (error) => settle({
+			kind: "error",
+			message: error.message
+		}));
+	});
+}
+//#endregion
 //#region src/client/llm-client.ts
 /**
 * `LlmClient` — the ONE file in this repo allowed to import the LLM library.
@@ -68847,6 +69067,19 @@ function baseUrlFor$1(profile) {
 	return profile.kind === "openai" ? OPENAI_DEFAULT_BASE_URL$1 : null;
 }
 /**
+* Where to knock, for the connect probe.
+*
+* Wider than {@link baseUrlFor}: an Anthropic or Google profile with an
+* explicit `baseUrl` (a LAN proxy, a gateway) is just as probe-able as an
+* openai-compatible one. Only a profile that relies on a vendor's built-in
+* endpoint yields `null` — the client never learns that URL, and inventing one
+* to probe would be probing a different host from the one the call uses.
+*/
+function probeEndpointFor(profile) {
+	const baseUrl = profile.baseUrl !== void 0 && profile.baseUrl.length > 0 ? trimSlash(profile.baseUrl) : baseUrlFor$1(profile);
+	return baseUrl === null ? null : tcpEndpointOf(baseUrl);
+}
+/**
 * Build the provider instance for a profile.
 *
 * Returns `null` when the profile cannot be served — a missing base URL on an
@@ -69105,7 +69338,7 @@ function createLlmClient(deps = {}) {
 				if (isAbortLike(error) && !request.signal.aborted) return {
 					ok: false,
 					code: "timeout",
-					message: `timed out after ${String(timeoutMs)}ms`
+					message: `no answer within ${String(Math.round(timeoutMs / 1e3))}s — a cold model can take minutes to load; warm it or raise the profile's total timeout`
 				};
 				const mapped = mapLibraryError(error);
 				return {
@@ -69119,41 +69352,91 @@ function createLlmClient(deps = {}) {
 			if (!SUPPORTED_KINDS.has(request.profile.kind)) return { kind: "unsupported" };
 			const model = modelFor(request.profile);
 			if (model === null) return { kind: "unsupported" };
-			const connect = new AbortController();
-			const onOuterAbort = () => connect.abort();
+			const endpoint = probeEndpointFor(request.profile);
+			if (endpoint !== null) {
+				const probe = await probeTcpConnect(endpoint, opts.connectTimeoutMs, request.signal, deps.connectImpl ?? defaultConnectImpl);
+				if (probe.kind === "timeout") return {
+					kind: "connect-timeout",
+					timeoutMs: opts.connectTimeoutMs
+				};
+				if (probe.kind === "error") return {
+					kind: "network",
+					message: request.signal.aborted ? "the call was cancelled" : probe.message
+				};
+				opts.onConnected?.();
+			}
+			const firstChunkBound = new AbortController();
+			const onOuterAbort = () => firstChunkBound.abort();
 			request.signal.addEventListener("abort", onOuterAbort, { once: true });
-			const connectTimer = setTimeout(() => connect.abort(), opts.connectTimeoutMs);
-			connectTimer.unref?.();
+			const firstChunkTimer = setTimeout(() => firstChunkBound.abort(), opts.firstTokenTimeoutMs);
+			firstChunkTimer.unref?.();
+			let streamFailure;
 			try {
-				const stream = streamText({
+				const iterator = chunksFrom(streamText({
 					model,
 					messages: messagesFor(request),
 					...instructionsFor(request),
 					...callSettingsFor(request),
 					...structuredOutputFor(request),
-					abortSignal: AbortSignal.any([request.signal, connect.signal])
-				});
-				await stream.response;
+					abortSignal: AbortSignal.any([request.signal, firstChunkBound.signal]),
+					onError: ({ error }) => {
+						streamFailure = error;
+					}
+				}))[Symbol.asyncIterator]();
+				const first = await iterator.next();
+				if (streamFailure !== void 0) {
+					const mapped = mapLibraryError(streamFailure);
+					return {
+						kind: "provider-error",
+						code: mapped.code,
+						message: mapped.message
+					};
+				}
+				if (firstChunkBound.signal.aborted) return request.signal.aborted ? {
+					kind: "network",
+					message: "the call was cancelled"
+				} : {
+					kind: "first-token-timeout",
+					timeoutMs: opts.firstTokenTimeoutMs
+				};
 				return {
 					kind: "open",
-					chunks: chunksFrom(stream)
+					chunks: resumeFrom(first, iterator)
 				};
 			} catch (error) {
 				if (isAbortLike(error) && !request.signal.aborted) return {
-					kind: "connect-timeout",
-					timeoutMs: opts.connectTimeoutMs
+					kind: "first-token-timeout",
+					timeoutMs: opts.firstTokenTimeoutMs
 				};
+				const mapped = mapLibraryError(error);
 				return {
-					kind: "network",
-					message: mapLibraryError(error).message
+					kind: "provider-error",
+					code: mapped.code,
+					message: mapped.message
 				};
 			} finally {
-				clearTimeout(connectTimer);
+				clearTimeout(firstChunkTimer);
 				request.signal.removeEventListener("abort", onOuterAbort);
 			}
 		}
 	};
 }
+/**
+* Hand back a stream whose first chunk has already been pulled.
+*
+* `openStream` has to consume one chunk to know the model started — that is
+* what its bound measures — and the caller must still receive it. Replaying it
+* here is what keeps "the first token is the load signal" true for the reader.
+*/
+async function* resumeFrom(first, iterator) {
+	if (first.done === true) return;
+	yield first.value;
+	for (;;) {
+		const next = await iterator.next();
+		if (next.done === true) return;
+		yield next.value;
+	}
+}
 async function* chunksFrom(stream) {
 	for await (const text of stream.textStream) if (text.length > 0) yield {
 		kind: "token",
@@ -69499,7 +69782,7 @@ function httpProfileConfigSchema(opts) {
 					min: 500,
 					default: 1e4,
 					unit: "ms",
-					description: "Waiting for response headers — i.e. \"is the port even open\"."
+					description: "The TCP handshake — i.e. \"is the port even open\". A closed port fails at once; only a black hole spends the whole bound."
 				},
 				{
 					type: "number",
@@ -69508,7 +69791,7 @@ function httpProfileConfigSchema(opts) {
 					min: 1e3,
 					default: 12e4,
 					unit: "ms",
-					description: "Accepted but silent. A cold GPU load lives here and can take minutes."
+					description: "Accepted but silent — response headers included, since a model writes them once it has loaded. A cold GPU load lives here and can take minutes. The test chat waits exactly this long."
 				},
 				{
 					type: "number",
@@ -71582,10 +71865,27 @@ async function runTestChatStream(deps, request, emit, signal) {
 		kind: "status",
 		phase: "connecting"
 	});
+	let modelWaitStartedAt = null;
 	const opened = await deps.openStream(streamRequest, {
 		signal,
-		connectTimeoutMs: TEST_CHAT_CONNECT_TIMEOUT_MS
+		connectTimeoutMs: TEST_CHAT_CONNECT_TIMEOUT_MS,
+		firstTokenTimeoutMs: request.firstTokenTimeoutMs,
+		onConnected: () => {
+			modelWaitStartedAt = deps.now();
+			emit({
+				kind: "status",
+				phase: "first-token-wait"
+			});
+		}
 	});
+	/**
+	* What is LEFT of the first-token budget.
+	*
+	* The response headers and the first token are one wait spent two ways, so
+	* they draw on one budget: the page says "up to Ns" and that has to be the
+	* whole truth, not N per stage.
+	*/
+	const remainingFirstTokenMs = () => modelWaitStartedAt === null ? request.firstTokenTimeoutMs : Math.max(1, request.firstTokenTimeoutMs - (deps.now() - modelWaitStartedAt));
 	if (opened.kind === "connect-timeout") {
 		await fail({
 			code: "unavailable",
@@ -71606,6 +71906,20 @@ async function runTestChatStream(deps, request, emit, signal) {
 		});
 		return;
 	}
+	if (opened.kind === "provider-error") {
+		await fail({
+			code: opened.code,
+			message: opened.message
+		}, "ai test chat: provider refused the request — turn dropped", {
+			code: opened.code,
+			error: opened.message
+		});
+		return;
+	}
+	if (opened.kind === "first-token-timeout") {
+		await failFirstToken();
+		return;
+	}
 	const streamed = opened.kind === "open";
 	emit({
 		kind: "meta",
@@ -71631,7 +71945,7 @@ async function runTestChatStream(deps, request, emit, signal) {
 			kind: "status",
 			phase: "first-token-wait"
 		});
-		const raced = await withDeadline(deps.generateOnce(streamRequest), request.firstTokenTimeoutMs);
+		const raced = await withDeadline(deps.generateOnce(streamRequest), remainingFirstTokenMs());
 		if (signal.aborted) {
 			deps.logger.info("ai test chat: client aborted mid-generation", withTags({}));
 			return;
@@ -71689,7 +72003,7 @@ async function runTestChatStream(deps, request, emit, signal) {
 			deps.logger.info("ai test chat: client aborted mid-stream — provider call torn down", { ...withTags({ sawFirstToken }) });
 			return;
 		}
-		const next = await nextChunk(iterator, sawFirstToken ? TEST_CHAT_IDLE_TIMEOUT_MS : request.firstTokenTimeoutMs);
+		const next = await nextChunk(iterator, sawFirstToken ? TEST_CHAT_IDLE_TIMEOUT_MS : remainingFirstTokenMs());
 		if (next.kind === "timeout") {
 			if (!sawFirstToken) {
 				await failFirstToken();
@@ -71949,7 +72263,11 @@ var AiAddon = class extends BaseAddon {
 				...request.maxTokens !== void 0 ? { maxTokens: request.maxTokens } : {},
 				...request.temperature !== void 0 ? { temperature: request.temperature } : {},
 				signal: opts.signal
-			}, { connectTimeoutMs: opts.connectTimeoutMs }),
+			}, {
+				connectTimeoutMs: opts.connectTimeoutMs,
+				firstTokenTimeoutMs: opts.firstTokenTimeoutMs,
+				onConnected: opts.onConnected
+			}),
 			generateOnce: async (request) => {
 				const base = {
 					profileId: request.profile.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-ai",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "AI addon for CamStack — the `llm` collection provider (cloud, LAN, and camstack-managed local llama.cpp profiles) plus the per-node `llm-runtime` managed executor.",
   "keywords": [
     "camstack",