@olares/lares-core 0.15.7 → 0.15.10

package/router/sref.js

@@ -0,0 +1,126 @@
+import { createHash, createHmac, randomBytes } from "node:crypto";
+
+/**
+ * Encrypted end-user credential for FlowStudio generations.
+ *
+ * Router forwards none of Lares' request headers to FlowStudio, so FlowStudio
+ * only ever sees "the caller is Router". Router does carry request-body fields
+ * it does not know into `params`, so the logged-in user rides there as an
+ * encrypted `sref` and FlowStudio decrypts it (server/app/model_console/sref.py).
+ * Both sides must stay byte-for-byte identical.
+ *
+ * Format: `1.<base64url(nonce[16] || ciphertext || tag[16])>`
+ * - keys: SHA-256(SREF_KEY), split by HMAC into an encryption and a MAC key;
+ * - cipher: keystream HMAC-SHA256(enc, nonce || counter) XOR plaintext;
+ * - tag: HMAC-SHA256(mac, "sref/v1" || nonce || ciphertext) truncated to 16 bytes;
+ * - plaintext: {"u": username, "t": unix seconds}; FlowStudio rejects it after 5 minutes.
+ */
+export const SREF_FIELD = "sref";
+export const DEFAULT_SREF_KEY = "gBH4rLCE9by5QfqvIr9Jm2pFtJDxwE5kxlvaJ/0goeg=";
+
+const NONCE_BYTES = 16;
+const TAG_BYTES = 16;
+
+function keys(secret) {
+  const root = createHash("sha256").update(secret, "utf8").digest();
+  return {
+    enc: createHmac("sha256", root).update("sref/enc").digest(),
+    mac: createHmac("sha256", root).update("sref/mac").digest(),
+  };
+}
+
+function keystream(encKey, nonce, length) {
+  const blocks = [];
+  let size = 0;
+  for (let counter = 0; size < length; counter += 1) {
+    const index = Buffer.alloc(4);
+    index.writeUInt32BE(counter);
+    const block = createHmac("sha256", encKey).update(Buffer.concat([nonce, index])).digest();
+    blocks.push(block);
+    size += block.length;
+  }
+  return Buffer.concat(blocks).subarray(0, length);
+}
+
+/**
+ * @param {string} user
+ * @param {string} secret
+ * @param {{ now?: number, nonce?: Buffer }} [options] now in milliseconds
+ */
+export function encodeSref(user, secret, options = {}) {
+  const { enc, mac } = keys(secret);
+  const issued = Math.floor((options.now ?? Date.now()) / 1000);
+  const plain = Buffer.from(JSON.stringify({ u: user, t: issued }), "utf8");
+  const nonce = options.nonce ?? randomBytes(NONCE_BYTES);
+  const stream = keystream(enc, nonce, plain.length);
+  const cipher = Buffer.alloc(plain.length);
+  for (let i = 0; i < plain.length; i += 1) cipher[i] = plain[i] ^ stream[i];
+  const tag = createHmac("sha256", mac)
+    .update(Buffer.concat([Buffer.from("sref/v1"), nonce, cipher]))
+    .digest()
+    .subarray(0, TAG_BYTES);
+  return `1.${Buffer.concat([nonce, cipher, tag]).toString("base64url")}`;
+}
+
+export function srefKey(env = process.env) {
+  const configured = env.SREF_KEY;
+  if (configured === undefined) return DEFAULT_SREF_KEY;
+  return configured.trim();
+}
+
+/** A FlowStudio workflow in the Router catalog: `Olares/<workflow uuid>`. */
+export function isFlowstudioModel(model) {
+  return /^Olares\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+    String(model ?? "").trim(),
+  );
+}
+
+const CREATE_ROUTES = /^(images\/generations|images\/edits|videos|music\/generations|generations)\/?$/;
+
+/** Whether a POST on this Router suffix creates a media generation. */
+export function isGenerationCreateRoute(suffix) {
+  return CREATE_ROUTES.test(String(suffix ?? "").replace(/^\/+/, ""));
+}
+
+/**
+ * Stamp the encrypted user onto a FlowStudio generation request body.
+ * Other providers, or no user / no key, get the body back untouched. A `sref`
+ * the caller put there itself is always replaced, so it cannot name someone else.
+ *
+ * It rides in `flowstudio.params`, which Router forwards to FlowStudio as
+ * `params` on every creation route. A top-level field would not survive:
+ * Router's canonical `/generations` refuses unknown top-level fields
+ * (`json: unknown field "sref"`). FlowStudio pops it before the workflow runs.
+ *
+ * @param {Record<string, any>} body
+ * @param {string} user
+ * @param {{ now?: number, nonce?: Buffer }} [options]
+ */
+export function withSref(body, user, env = process.env, options = {}) {
+  if (body == null || typeof body !== "object" || Array.isArray(body)) return body;
+  if (!isFlowstudioModel(body.model)) return body;
+  const secret = srefKey(env);
+  const name = String(user ?? "").trim();
+  if (!secret || !name) return body;
+  const token = encodeSref(name, secret, options);
+  const { [SREF_FIELD]: _dropped, ...rest } = body;
+  const flowstudio = rest.flowstudio && typeof rest.flowstudio === "object" && !Array.isArray(rest.flowstudio)
+    ? rest.flowstudio
+    : {};
+  const params = flowstudio.params && typeof flowstudio.params === "object" && !Array.isArray(flowstudio.params)
+    ? flowstudio.params
+    : {};
+  return { ...rest, flowstudio: { ...flowstudio, params: { ...params, [SREF_FIELD]: token } } };
+}
+
+/** Same as `withSref` for a raw JSON request body; non-JSON is returned as is. */
+export function withSrefBuffer(buffer, user, env = process.env, options = {}) {
+  let parsed;
+  try {
+    parsed = JSON.parse(buffer.toString("utf8"));
+  } catch {
+    return buffer;
+  }
+  const stamped = withSref(parsed, user, env, options);
+  return stamped === parsed ? buffer : Buffer.from(JSON.stringify(stamped), "utf8");
+}

package/router/stt.js

@@ -22,17 +22,36 @@ export class VoiceError extends Error {
   }
 }
 
+export function isSttModel(model) {
+  if (model?.supportsStt) return true;
+  return model?.mode === "audio" && STT_HINTS.test(model?.id ?? "");
+}
+
+export function isTtsModel(model) {
+  if (model?.supportsTts) return true;
+  return model?.mode === "tts";
+}
+
 export function sttModelIds(models) {
-  return models
-    .filter((model) => model.mode === "audio" && STT_HINTS.test(model.id))
-    .map((model) => model.id);
+  return models.filter(isSttModel).map((model) => model.id);
 }
 
-export function pickSttModelId(models, preferred) {
-  const stt = sttModelIds(models);
+export function ttsModelIds(models) {
+  return models.filter(isTtsModel).map((model) => model.id);
+}
+
+export function pickListedModelId(ids, preferred) {
   const want = (preferred ?? "").trim();
-  if (want && stt.includes(want)) return want;
-  return stt[0] ?? null;
+  if (want && ids.includes(want)) return want;
+  return ids[0] ?? null;
+}
+
+export function pickSttModelId(models, preferred) {
+  return pickListedModelId(sttModelIds(models), preferred);
+}
+
+export function pickTtsModelId(models, preferred) {
+  return pickListedModelId(ttsModelIds(models), preferred);
 }
 
 export function classifyFailure(status, body) {
@@ -72,9 +91,13 @@ const RESOLVED_TTL_MS = 120_000;
 /** @returns {Promise<{ id: string, mode: string | null }[]>} */
 export async function listModels(options) {
   try {
-    if (options?.refresh) catalogCache.invalidate();
-    const { rows } = await catalogCache.get();
-    return rows.map(({ id, mode }) => ({ id, mode }));
+    const { rows } = await catalogCache.get({ refresh: options?.refresh });
+    return rows.map(({ id, mode, supportsStt, supportsTts }) => ({
+      id,
+      mode,
+      supportsStt: Boolean(supportsStt),
+      supportsTts: Boolean(supportsTts),
+    }));
   } catch (err) {
     const status = err && typeof err === "object" && "status" in err ? Number(err.status) : 503;
     throw new VoiceError(
@@ -152,6 +175,8 @@ async function readTranscript(res) {
  */
 export async function transcribe(take) {
   let model = take.model;
+  const timeoutMs = Number(take.timeoutMs) > 0 ? Number(take.timeoutMs) : REQUEST_TIMEOUT_MS;
+  const retries = take.once ? 0 : RETRY_BACKOFF_MS.length;
   for (let attempt = 0; ; attempt += 1) {
     const fields = { model };
     if (take.language) fields.language = take.language;
@@ -165,11 +190,13 @@ export async function transcribe(take) {
     /** @type {VoiceError} */
     let failure;
     try {
+      const timeout = AbortSignal.timeout(timeoutMs);
+      const signal = take.signal ? AbortSignal.any([take.signal, timeout]) : timeout;
       const res = await fetch(`${routerShimBaseUrl()}/audio/transcriptions`, {
         method: "POST",
         headers: { "content-type": `multipart/form-data; boundary=${boundary}` },
         body,
-        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        signal,
       });
       if (res.ok) return await readTranscript(res);
       const text = await res.text();
@@ -177,13 +204,17 @@ export async function transcribe(take) {
       if (!retryable(res.status)) throw failure;
     } catch (err) {
       if (err instanceof VoiceError) throw err;
+      if (take.signal?.aborted) {
+        throw new VoiceError("voice_cancelled", 499, "transcription cancelled");
+      }
       const timedOut = err?.name === "TimeoutError" || err?.name === "AbortError";
       failure = timedOut
         ? new VoiceError("voice_timeout", 504, "transcription timed out")
         : new VoiceError("voice_failed", 502, `router unreachable: ${err?.message ?? err}`);
     }
 
-    if (attempt >= RETRY_BACKOFF_MS.length) throw failure;
+    if (take.signal?.aborted) throw new VoiceError("voice_cancelled", 499, "transcription cancelled");
+    if (attempt >= retries) throw failure;
     await new Promise((resolve) => setTimeout(resolve, RETRY_BACKOFF_MS[attempt]));
     const refreshed = await resolveSttModel(take.preferred, { refresh: true }).catch(() => null);
     if (refreshed) model = refreshed;

package/router/tts.js

@@ -0,0 +1,118 @@
+import { VoiceError } from "./stt.js";
+import { routerShimBaseUrl } from "./gateway.js";
+
+const REQUEST_TIMEOUT_MS = 180_000;
+
+const PCM_RATE = 24000;
+
+/** Kokoro concatenates chunks with no gap. This is the silence we insert between sentences. */
+export function silencePcm(ms, sampleRate = PCM_RATE) {
+  const samples = Math.max(0, Math.round((sampleRate * ms) / 1000));
+  return Buffer.alloc(samples * 2);
+}
+
+/** Wrap 24 kHz mono s16le in a WAV header for a browser that has no host speaker. */
+export function pcmToWav(pcm, sampleRate = PCM_RATE) {
+  const body = Buffer.from(pcm);
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + body.length, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(1, 22);
+  header.writeUInt32LE(sampleRate, 24);
+  header.writeUInt32LE(sampleRate * 2, 28);
+  header.writeUInt16LE(2, 32);
+  header.writeUInt16LE(16, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(body.length, 40);
+  return Buffer.concat([header, body]);
+}
+
+/**
+ * @param {{ text: string, model: string }} request
+ * @returns {Promise<Buffer>}
+ */
+export async function synthesize(request) {
+  const text = request.text.trim();
+  if (!text) throw new VoiceError("voice_config_invalid", 400, "nothing to speak");
+  let res;
+  try {
+    res = await fetch(`${routerShimBaseUrl()}/audio/speech`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "audio/wav,application/octet-stream" },
+      body: JSON.stringify({
+        model: request.model,
+        input: text,
+        response_format: "wav",
+      }),
+      signal: AbortSignal.timeout(request.timeoutMs ?? REQUEST_TIMEOUT_MS),
+    });
+  } catch (err) {
+    const timedOut = err?.name === "TimeoutError" || err?.name === "AbortError";
+    throw new VoiceError(
+      timedOut ? "voice_timeout" : "voice_failed",
+      timedOut ? 504 : 502,
+      timedOut ? "speech timed out" : `router unreachable: ${err?.message ?? err}`,
+    );
+  }
+  if (!res.ok) {
+    const detail = (await res.text()).slice(0, 400);
+    throw new VoiceError(res.status === 404 ? "voice_tts_unavailable" : "voice_failed", res.status, detail);
+  }
+  return Buffer.from(await res.arrayBuffer());
+}
+
+/**
+ * Deliver each PCM sentence as Kokoro yields it.
+ * A non-stream response comes back as `{ streamed: false, audio }` instead.
+ *
+ * @param {{ text: string, model: string, signal?: AbortSignal }} request
+ * @param {(chunk: Buffer) => Promise<void> | void} onChunk
+ */
+export async function synthesizeStream(request, onChunk) {
+  const text = request.text.trim();
+  if (!text) throw new VoiceError("voice_config_invalid", 400, "nothing to speak");
+  let res;
+  try {
+    const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS);
+    const signal = request.signal
+      ? AbortSignal.any([request.signal, timeout])
+      : timeout;
+    res = await fetch(`${routerShimBaseUrl()}/audio/speech`, {
+      method: "POST",
+      headers: { "content-type": "application/json", accept: "audio/l16,audio/wav" },
+      body: JSON.stringify({
+        model: request.model,
+        input: text,
+        response_format: "pcm",
+        stream: true,
+      }),
+      signal,
+    });
+  } catch (err) {
+    const timedOut = err?.name === "TimeoutError" || err?.name === "AbortError";
+    throw new VoiceError(
+      timedOut ? "voice_timeout" : "voice_failed",
+      timedOut ? 504 : 502,
+      timedOut ? "speech timed out" : `router unreachable: ${err?.message ?? err}`,
+    );
+  }
+  if (!res.ok) {
+    const detail = (await res.text()).slice(0, 400);
+    throw new VoiceError(res.status === 404 ? "voice_tts_unavailable" : "voice_failed", res.status, detail);
+  }
+  const type = (res.headers.get("content-type") || "").toLowerCase();
+  if (!type.includes("audio/l16")) {
+    return { streamed: false, audio: Buffer.from(await res.arrayBuffer()) };
+  }
+  const reader = res.body.getReader();
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value?.byteLength) await onChunk(Buffer.from(value));
+  }
+  return { streamed: true };
+}

package/search/client.js

@@ -9,11 +9,13 @@ export function rememberedSearchSettings() {
 }
 
 export async function loadSearchSettings(options = {}) {
-  return settings.load(() => getJson("/config"), options);
+  const query = options.force ? "?refresh=1" : "";
+  return settings.load(() => getJson(`/config${query}`), options);
 }
 
-export async function saveSearchDefault(id) {
-  return settings.remember(await postJson("/config/default", { defaultSearchModel: id }));
+/** @param {{ defaultSearchModel: string | null, searchOff: boolean }} selection */
+export async function saveSearchDefault(selection) {
+  return settings.remember(await postJson("/config/default", selection));
 }
 
 export async function getJson(path) {

package/search/config.js

@@ -3,26 +3,36 @@ import { HttpError } from "../tools/http.js";
 import { dshPluginConfigPath } from "../workspace/home.js";
 import { fetchRouterSearchModels } from "../router/search.js";
 
-/** @typedef {{ defaultSearchModel: string | null }} WebSearchConfig */
+/**
+ * Three states, because "nobody chose yet" and "the user turned search off"
+ * must not collapse into one value: an unset default follows Router, and an
+ * automatic default must never reopen search the user closed.
+ * @typedef {{ defaultSearchModel: string | null, searchOff: boolean }} WebSearchConfig
+ */
 
 /** @returns {WebSearchConfig} */
 function defaults() {
-  return { defaultSearchModel: null };
+  return { defaultSearchModel: null, searchOff: false };
 }
 
 function configPath() {
   return dshPluginConfigPath("web-search");
 }
 
+/** @param {unknown} value */
+function modelId(value) {
+  const id = typeof value === "string" ? value.trim() : "";
+  if (!id || id.length > 512 || /[\u0000-\u001f\u007f]/.test(id)) return null;
+  return id;
+}
+
 /** @param {unknown} raw @returns {WebSearchConfig} */
 function normalize(raw) {
   if (!raw || typeof raw !== "object") return defaults();
   const body = /** @type {Record<string, unknown>} */ (raw);
-  const value = typeof body.defaultSearchModel === "string" ? body.defaultSearchModel.trim() : "";
   return {
-    defaultSearchModel: value && value.length <= 512 && !/[\u0000-\u001f\u007f]/.test(value)
-      ? value
-      : null,
+    defaultSearchModel: modelId(body.defaultSearchModel),
+    searchOff: body.searchOff === true,
   };
 }
 
@@ -43,56 +53,60 @@ function persist(config) {
 }
 
 /**
- * @param {string | null} id
+ * @param {WebSearchConfig} selection
  * @param {{ id: string }[]} available
  */
-export function setDefaultSearchModel(id, available) {
-  if (id === null) {
-    return persist({ defaultSearchModel: null });
-  }
-  const model = typeof id === "string" ? id.trim() : "";
-  if (
-    !model
-    || model.length > 512
-    || /[\u0000-\u001f\u007f]/.test(model)
-    || !available.some((item) => item.id === model)
-  ) {
+export function setSearchSelection(selection, available) {
+  if (selection.searchOff) return persist({ defaultSearchModel: null, searchOff: true });
+  if (selection.defaultSearchModel === null) return persist(defaults());
+  const model = modelId(selection.defaultSearchModel);
+  if (!model || !available.some((item) => item.id === model)) {
     throw new HttpError("not_available", 400, "search service is not available from Router");
   }
-  return persist({ defaultSearchModel: model });
+  return persist({ defaultSearchModel: model, searchOff: false });
 }
 
-export async function currentSearchConfig() {
-  const searchModels = await fetchRouterSearchModels();
-  return {
-    defaultSearchModel: readConfig().defaultSearchModel,
-    searchModels,
-  };
+/** @param {{ refresh?: boolean }} [options] */
+export async function currentSearchConfig(options = {}) {
+  const searchModels = await fetchRouterSearchModels(options);
+  return { ...readConfig(), searchModels };
 }
 
 export const LARES_PROVIDER_ID = "lares";
-export { SEARCH_NONE, searchDefaultReady, searchMenuValue, searchValueFromMenu } from "./menu.js";
+export {
+  SEARCH_OFF,
+  SEARCH_ROUTER_DEFAULT,
+  searchDefaultReady,
+  searchMenuValue,
+  searchStatus,
+  searchValueFromMenu,
+} from "./menu.js";
 
+/** The model to send, or null to follow Router's own default-search category. */
 export function configuredSearchModel() {
   return readConfig().defaultSearchModel;
 }
 
-export function defaultSearchModelFromBody(body) {
-  const id = body?.defaultSearchModel === null ? null : body?.defaultSearchModel;
-  if (id !== null && typeof id !== "string") {
-    throw new HttpError("bad_model", 400, "invalid defaultSearchModel");
-  }
-  return id;
+export function searchDisabled() {
+  return readConfig().searchOff;
 }
 
-export async function setDefaultSearchFromRequest(id) {
-  if (id !== null && typeof id !== "string") {
+/** @param {unknown} body @returns {WebSearchConfig} */
+export function searchSelectionFromBody(body) {
+  const raw = body && typeof body === "object" ? /** @type {Record<string, unknown>} */ (body) : null;
+  if (!raw) throw new HttpError("bad_model", 400, "invalid search selection");
+  const asked = raw.defaultSearchModel;
+  if (asked !== null && asked !== undefined && typeof asked !== "string") {
     throw new HttpError("bad_model", 400, "invalid defaultSearchModel");
   }
+  if (raw.searchOff !== undefined && typeof raw.searchOff !== "boolean") {
+    throw new HttpError("bad_model", 400, "invalid searchOff");
+  }
+  return { defaultSearchModel: typeof asked === "string" ? asked : null, searchOff: raw.searchOff === true };
+}
+
+/** @param {WebSearchConfig} selection */
+export async function setSearchSelectionFromRequest(selection) {
   const searchModels = await fetchRouterSearchModels();
-  const saved = setDefaultSearchModel(id, searchModels);
-  return {
-    defaultSearchModel: saved.defaultSearchModel,
-    searchModels,
-  };
+  return { ...setSearchSelection(selection, searchModels), searchModels };
 }

package/search/menu.js

@@ -1,22 +1,57 @@
-export const SEARCH_NONE = "none";
+export const SEARCH_ROUTER_DEFAULT = "router-default";
+export const SEARCH_OFF = "off";
 
-export function searchDefaultReady(models, defaultSearchModel) {
-  return Array.isArray(models) && models.some((model) => model.id === defaultSearchModel);
+/** @param {{ defaultSearchModel?: string | null, searchOff?: boolean } | null} [config] */
+export function searchMenuValue(config) {
+  if (config?.searchOff) return SEARCH_OFF;
+  return config?.defaultSearchModel ?? SEARCH_ROUTER_DEFAULT;
 }
 
-export function searchMenuValue(defaultSearchModel) {
-  return defaultSearchModel ?? SEARCH_NONE;
+/** @param {string} id */
+export function searchValueFromMenu(id) {
+  if (id === SEARCH_OFF) return { defaultSearchModel: null, searchOff: true };
+  if (id === SEARCH_ROUTER_DEFAULT) return { defaultSearchModel: null, searchOff: false };
+  return { defaultSearchModel: id, searchOff: false };
 }
 
-export function searchValueFromMenu(id) {
-  return id === SEARCH_NONE ? null : id;
+export function searchDefaultReady(models, config) {
+  return searchStatus(models, config).ready;
+}
+
+/**
+ * What the settings panel says about web search, decided once for every
+ * surface. Following Router is ready as soon as Router serves any search
+ * model; a named model is ready only while the catalog still lists it.
+ * @param {{ id: string }[]} models
+ * @param {{ defaultSearchModel?: string | null, searchOff?: boolean } | null} [config]
+ * @returns {{ ready: boolean, key: string, model?: string }}
+ */
+export function searchStatus(models, config) {
+  if (config?.searchOff) return { ready: false, key: "settings.status.off" };
+  const listed = Array.isArray(models) ? models : [];
+  const model = config?.defaultSearchModel ?? null;
+  if (model === null) {
+    return listed.length > 0
+      ? { ready: true, key: "settings.status.router" }
+      : { ready: false, key: "settings.status.empty" };
+  }
+  return listed.some((entry) => entry.id === model)
+    ? { ready: true, key: "settings.status.ready", model }
+    : { ready: false, key: "settings.status.notReady", model };
 }
 
 export function searchModelLabel(model) {
   return model.name || model.id;
 }
 
-export function searchSelectorItems(models, { none, empty }) {
-  if (models.length === 0) return [{ id: SEARCH_NONE, label: empty }];
-  return [{ id: SEARCH_NONE, label: none }, ...models.map((model) => ({ id: model.id, label: searchModelLabel(model) }))];
+/**
+ * Follow-Router first, then what Router serves, with off last. Router serving
+ * nothing is reported by the status line, not by hiding the choice.
+ */
+export function searchSelectorItems(models, { routerDefault, off }) {
+  return [
+    { id: SEARCH_ROUTER_DEFAULT, label: routerDefault },
+    ...models.map((model) => ({ id: model.id, label: searchModelLabel(model) })),
+    { id: SEARCH_OFF, label: off },
+  ];
 }

package/skills/client.js

@@ -0,0 +1,42 @@
+import { createSnapshotStore } from "../tools/async.js";
+
+export const API = "/api/lares/skills";
+
+const settings = createSnapshotStore();
+
+async function readPayload(res, path) {
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(payload?.error?.message ?? payload?.error?.code ?? `${path} → ${res.status}`);
+  }
+  return payload;
+}
+
+async function postAction(path, id) {
+  const res = await fetch(`${API}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ id }),
+  });
+  return settings.remember(await readPayload(res, path));
+}
+
+export function rememberedSkillPacks() {
+  return settings.peek();
+}
+
+export async function loadSkillPacks(options = {}) {
+  return settings.load(async () => readPayload(await fetch(API), "/"), options);
+}
+
+export function downloadSkillPack(id) {
+  return postAction("/download", id);
+}
+
+export function enableSkillPack(id) {
+  return postAction("/enable", id);
+}
+
+export function disableSkillPack(id) {
+  return postAction("/disable", id);
+}

package/skills/packs.js

@@ -0,0 +1,40 @@
+/** Official optional skill packs. Always-on prefixes are seeded every boot from the image catalog. */
+
+export const ALWAYS_ON_PREFIXES = ["olares-", "lares-"];
+
+export const OFFICIAL_PACKS = [
+  {
+    id: "ha",
+    prefix: "ha-",
+    optional: true,
+    cli: {
+      package: "@olares/hass-cli",
+      version: "0.0.1",
+      bin: "hass-cli",
+      listArgs: ["skill", "list"],
+      showArgs: (name) => ["skill", "show", name],
+    },
+  },
+];
+
+export function packById(id) {
+  return OFFICIAL_PACKS.find((pack) => pack.id === id) ?? null;
+}
+
+export function packForSkillDir(name) {
+  return OFFICIAL_PACKS.find((pack) => name.startsWith(pack.prefix)) ?? null;
+}
+
+export function isAlwaysOnSkillDir(name) {
+  return ALWAYS_ON_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+
+/** First column of `hass-cli skill list` (name, then tab/spaces, then description). */
+export function parseSkillNames(listOutput) {
+  return String(listOutput ?? "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => line.split(/[\t ]+/, 1)[0])
+    .filter((name) => name && !name.startsWith("NAME"));
+}

package/skills/state.d.ts

@@ -0,0 +1,22 @@
+export function packsStatePath(dataDir: string): string;
+export function runtimeSkillsDir(dataDir: string): string;
+export function packCacheDir(dataDir: string, packId: string): string;
+export function defaultCatalogRoot(): string;
+export function readEnabledPacks(dataDir: string): string[];
+export function writeEnabledPacks(dataDir: string, enabled: string[]): void;
+export function cachedSkillDirs(dataDir: string, pack: { id: string; prefix: string }): string[];
+export function packDownloaded(dataDir: string, pack: { id: string; prefix: string }): boolean;
+export function syncRuntimeSkills(catalogRoot: string, dataDir: string): string;
+export function writeExportedSkills(cacheDir: string, files: Array<{ name?: string; body?: string }>): void;
+export function listOfficialPacks(dataDir: string, cliReady?: Record<string, boolean>): Array<{
+  id: string;
+  official: boolean;
+  optional: boolean;
+  downloaded: boolean;
+  enabled: boolean;
+  skillCount: number;
+  cliBin: string | null;
+  cliReady: boolean;
+}>;
+export function enableOfficialPack(catalogRoot: string, dataDir: string, id: string): { id: string };
+export function disableOfficialPack(catalogRoot: string, dataDir: string, id: string): { id: string };