@kehto/shell 0.24.5 → 0.26.0

package/README.md

@@ -305,6 +305,10 @@ for outer URL encoding, review, routing, and verified launcher behavior.
 
 This non-normative guidance defers to the living [NAP-GAMEPAD](https://github.com/napplet/naps/pull/108). Services export `createGamepadService` and `browserGamepadOptions`; shell exports `denyNappletControllerAccess`. Paja and the playground register one host reader and deny native gamepad/HID/USB paths before frame execution. Source-bound subscriptions receive immediate full snapshots; only the visible host's input owner gets live controls. Focus loss supplies neutral controls and timestamp zero; unsubscribe, window destruction, and service removal release polling. Non-browser or denied native readers report the proposal's unavailable reasons. See [Controller input](https://github.com/kehto/web/blob/main/docs/gamepad.md).
 
+## LLM integration
+
+This non-normative guidance defers to the living [NAP-LLM](https://github.com/napplet/naps/pull/134) (checked at `3e10939`). Services export `createLlmService`, `LlmServiceError`, the provider mappers and `LLM_PROVIDER_PRESETS`; shell exports `getShellDomainState` and the `LlmHooks` adapter field; acl exports `llm:generate`. The runtime routes `llm.*` to one registered service and answers every sanctioned request with exactly one `llm.<op>.result`, shaping missing-service and ACL failures as `{ code: 'unsupported' }`. Hosts implement `LlmConnectionHost`; the service enforces schema, handle ownership, consent before submission, duplicate ids, cancellation and deadline races, ordered deltas and safe errors. Advertisement stays binary on the wire while hosts report a third `unconfigured` state until the user adds a connection. See [Language models](https://github.com/kehto/web/blob/main/docs/llm.md).
+
 ## UUID support on HTTP origins
 
 Shell event injection, cache queries, and source-session registration use native

package/dist/index.d.ts

@@ -243,6 +243,30 @@ interface WebrtcHooks {
     /** True when the host has shell-mediated WebRTC sessions wired. */
     isAvailable(): boolean;
 }
+/**
+ * Host wiring behind the NAP-LLM `llm` domain.
+ *
+ * NAP-LLM support is not binary: a host may have the runtime and service wired
+ * while the user has not yet configured any model connection. `isAvailable()`
+ * decides whether the domain is advertised at all; `isConfigured()` reports
+ * whether a connection exists so host UIs can show an "unconfigured" state and
+ * prompt for setup when a napplet first calls `llm.select`.
+ */
+interface LlmHooks {
+    /** True when the host can route `llm.*` to a registered service. */
+    isAvailable(): boolean;
+    /** True when at least one model connection is configured. Omitted means configured. */
+    isConfigured?(): boolean;
+}
+/**
+ * Host-facing advertisement state of one NAP domain.
+ *
+ * - `supported`: advertised to napplets and ready to serve requests.
+ * - `unconfigured`: advertised, but the host still needs user configuration
+ *   (for example an LLM connection); the first request prompts for setup.
+ * - `disabled`: not advertised; the host disabled it or its backend is not live.
+ */
+type ShellDomainState = 'supported' | 'unconfigured' | 'disabled';
 /**
  * Optional host override for the static shell.init capability handshake.
  *
@@ -417,6 +441,12 @@ interface ShellAdapter {
      * registers the concrete service via `registerService('webrtc')`.
      */
     webrtc?: WebrtcHooks;
+    /**
+     * Optional NAP-LLM wiring state. When omitted, a registered `llm` service is
+     * advertised as supported; when present, `isAvailable()` gates advertisement
+     * and `isConfigured()` feeds the host's unconfigured indicator.
+     */
+    llm?: LlmHooks;
     /**
      * Optional capability advertisement override. Omitted by production hosts.
      */
@@ -982,6 +1012,24 @@ declare function buildShellCapabilities(hooks: ShellAdapter): ShellCapabilities;
  * @returns A fresh immutable environment whose entries are exact live subsets.
  */
 declare function resolveShellEnvironment(hooks: ShellAdapter, identity: OriginIdentity): ShellEnvironment;
+/**
+ * Report the host-facing advertisement state of one bare NAP domain.
+ *
+ * Advertisement itself stays binary on the wire (NIP-5D domain presence), but a
+ * host UI needs the third state: the domain is advertised while the user has not
+ * configured its backend yet. Only hooks that expose `isConfigured()` (today
+ * `llm`) can report `unconfigured`; every other advertised domain is
+ * `supported`, and anything not advertised is `disabled`.
+ *
+ * @param hooks - The ShellAdapter provided by the host app.
+ * @param domain - Bare NAP domain name such as `llm`.
+ * @returns `supported`, `unconfigured` or `disabled`.
+ * @example
+ * ```ts
+ * getShellDomainState(hooks, 'llm'); // 'unconfigured' until a connection is saved
+ * ```
+ */
+declare function getShellDomainState(hooks: ShellAdapter, domain: string): ShellDomainState;
 
 /**
  * identity-proxy.ts — Shell-side per-domain proxy for identity.* envelopes.
@@ -1568,4 +1616,4 @@ type ResourceInbound = ResourceInfoRequest | ResourceBytesRequest | ResourceByte
  */
 type ResourceOutbound = ResourceInfoResult | ResourceInfoError | ResourceBytesResult | ResourceBytesError | ResourceBytesManyResult | ResourceBytesManyError;
 
-export { type AclCheckEvent, type AclEntry, type AclStore, type AudioManager, type AudioSource, type AuthHooks, type BleHooks, type BrowserDeps, type CapabilityHooks, type CommonHooks, type ConfigHooks, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type IntentHooks, type KeysProxy, type KeysProxyDeps, type LinkHooks, type ListsHooks, type ManifestCache, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NappletCspDirective, type NappletCspDirectives, type NappletCspOptions, type NappletNamespacePreludeOptions, type NappletSrcdocOptions, type NormalizedIntentUri, type NotifyProxy, type NotifyProxyDeps, type OriginIdentity, type OriginRegistry, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type ResourceBytesError, type ResourceBytesManyError, type ResourceBytesManyItem, type ResourceBytesManyRequest, type ResourceBytesManyResult, type ResourceBytesRequest, type ResourceBytesResult, type ResourceCancelRequest, type ResourceErrorCode, type ResourceInbound, type ResourceInfoError, type ResourceInfoRequest, type ResourceInfoResult, type ResourceOutbound, type ResourceRequestId, type SerialHooks, type SessionRegistry, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ShellEnvironment, type ThemeProxy, type ThemeProxyDeps, type UnroutedMessageInfo, type UploadBackendLike, type UploadHooks, type WebrtcHooks, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildNappletCsp, buildShellCapabilities, createIdentityProxy, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, denyNappletControllerAccess, injectNappletCsp, injectNappletNamespacePrelude, manifestCache, nappKeyRegistry, normalizeIntentUri, originRegistry, prepareNappletSrcdoc, renderNappletCspMeta, renderNappletNamespacePrelude, resolveShellEnvironment, sessionRegistry };
+export { type AclCheckEvent, type AclEntry, type AclStore, type AudioManager, type AudioSource, type AuthHooks, type BleHooks, type BrowserDeps, type CapabilityHooks, type CommonHooks, type ConfigHooks, type CryptoHooks, type DmHooks, type HotkeyHooks, type IdentityProxy, type IdentityProxyDeps, type IntentHooks, type KeysProxy, type KeysProxyDeps, type LinkHooks, type ListsHooks, type LlmHooks, type ManifestCache, type ManifestCacheEntry, type MediaProxy, type MediaProxyDeps, type NappletCspDirective, type NappletCspDirectives, type NappletCspOptions, type NappletNamespacePreludeOptions, type NappletSrcdocOptions, type NormalizedIntentUri, type NotifyProxy, type NotifyProxyDeps, type OriginIdentity, type OriginRegistry, type ProxyOriginRegistry, type RelayConfigHooks, type RelayPoolHooks, type RelayPoolLike, type ResourceBytesError, type ResourceBytesManyError, type ResourceBytesManyItem, type ResourceBytesManyRequest, type ResourceBytesManyResult, type ResourceBytesRequest, type ResourceBytesResult, type ResourceCancelRequest, type ResourceErrorCode, type ResourceInbound, type ResourceInfoError, type ResourceInfoRequest, type ResourceInfoResult, type ResourceOutbound, type ResourceRequestId, type SerialHooks, type SessionRegistry, type ShellAdapter, type ShellBridge, type ShellCapabilities, type ShellDomainState, type ShellEnvironment, type ThemeProxy, type ThemeProxyDeps, type UnroutedMessageInfo, type UploadBackendLike, type UploadHooks, type WebrtcHooks, type WindowManagerHooks, type WorkerRelayHooks, type WorkerRelayLike, adaptHooks, audioManager, buildNappletCsp, buildShellCapabilities, createIdentityProxy, createKeysProxy, createMediaProxy, createNotifyProxy, createShellBridge, createThemeProxy, denyNappletControllerAccess, getShellDomainState, injectNappletCsp, injectNappletNamespacePrelude, manifestCache, nappKeyRegistry, normalizeIntentUri, originRegistry, prepareNappletSrcdoc, renderNappletCspMeta, renderNappletNamespacePrelude, resolveShellEnvironment, sessionRegistry };

package/dist/index.js

@@ -1013,7 +1013,8 @@ var SERVICE_ONLY_DOMAINS = [
   "dm",
   "count",
   "fs",
-  "gamepad"
+  "gamepad",
+  "llm"
 ];
 function buildShellCapabilities(hooks) {
   const disabled = new Set(hooks.capabilities?.disabledDomains ?? []);
@@ -1060,10 +1061,18 @@ function isServiceDomainLive(hooks, domain) {
       return hooks.ble?.isAvailable() === true;
     case "webrtc":
       return hooks.webrtc?.isAvailable() === true;
+    case "llm":
+      return hooks.llm ? hooks.llm.isAvailable() : true;
     default:
       return true;
   }
 }
+function getShellDomainState(hooks, domain) {
+  if (!buildShellCapabilities(hooks).domains.includes(domain)) return "disabled";
+  const configurable = Reflect.get(hooks, domain);
+  const isConfigured = configurable && typeof configurable === "object" ? configurable.isConfigured : void 0;
+  return typeof isConfigured === "function" && !isConfigured.call(configurable) ? "unconfigured" : "supported";
+}
 function getLiveServices(hooks, domains, disabled) {
   const liveDomains = new Set(domains);
   return Object.keys(hooks.services ?? {}).filter((name) => {
@@ -2210,36 +2219,90 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
     };
   }
   function makeMedia() {
+    const sessions = /* @__PURE__ */ new Set();
+    const ended = /* @__PURE__ */ new Map();
+    const retained = /* @__PURE__ */ new Map();
+    const callbacks = /* @__PURE__ */ new Map();
+    const warnings = /* @__PURE__ */ new Set();
+    const warn = (name, replacement) => {
+      if (warnings.has(name)) return;
+      warnings.add(name);
+      console.warn(`[KEHTO-MEDIA-${name}] Deprecated media API; use ${replacement}. Warned once per endpoint.`);
+    };
+    listen((event) => {
+      if (!isParentMessage(event)) return;
+      const msg = event.data;
+      if (!msg || typeof msg !== "object" || typeof msg.sessionId !== "string") return;
+      const sessionId = msg.sessionId;
+      if (msg.type === "media.session.create.result" && !msg.error) {
+        if (!ended.has(sessionId)) sessions.add(sessionId);
+        return;
+      }
+      if (!sessions.has(sessionId) || ended.has(sessionId)) return;
+      if (msg.type === "media.session.ended") {
+        ended.set(sessionId, msg);
+        retained.delete(sessionId);
+        sessions.delete(sessionId);
+      } else if (["media.state", "media.capabilities", "media.controls"].includes(msg.type)) {
+        const cache2 = retained.get(sessionId) ?? /* @__PURE__ */ new Map();
+        cache2.set(msg.type, msg);
+        retained.set(sessionId, cache2);
+      } else if (msg.type !== "media.command") return;
+      const delivery = Array.from(callbacks.get(sessionId)?.get(msg.type) ?? []);
+      for (const callback of delivery) callback(msg);
+      if (ended.has(sessionId)) callbacks.delete(sessionId);
+    });
     const on = (type, sessionId, callback) => {
-      const off = listen((event) => {
-        if (!isParentMessage(event)) return;
-        const msg = event.data;
-        if (typeof msg === "object" && msg !== null && msg.type === type && msg.sessionId === sessionId) callback(msg);
+      const terminal = ended.get(sessionId);
+      if (terminal) {
+        if (type === "media.session.ended") callback(terminal);
+        return subscriptionHandle(() => {
+        });
+      }
+      const byType = callbacks.get(sessionId) ?? /* @__PURE__ */ new Map();
+      const handlers = byType.get(type) ?? /* @__PURE__ */ new Set();
+      handlers.add(callback);
+      byType.set(type, handlers);
+      callbacks.set(sessionId, byType);
+      const cached = retained.get(sessionId)?.get(type);
+      if (cached) callback(cached);
+      return subscriptionHandle(() => {
+        handlers.delete(callback);
       });
-      return subscriptionHandle(off);
     };
-    return {
+    const command = (sessionId, value) => {
+      if (ended.has(sessionId)) return;
+      fire({ ...value && typeof value === "object" ? value : {}, type: "media.command", sessionId });
+    };
+    return Object.freeze({
       createSession: (options) => request(
-        { type: "media.session.create", ...options && typeof options === "object" ? options : {} },
+        { ...options && typeof options === "object" ? options : {}, type: "media.session.create" },
         "media.session.create.result",
         withoutEnvelope,
         { rejectOnError: false }
       ),
       updateSession: (sessionId, metadata) => fire({ type: "media.session.update", sessionId, metadata }),
       destroySession: (sessionId) => fire({ type: "media.session.destroy", sessionId }),
-      reportState: (sessionId, state) => fire({ type: "media.state", sessionId, ...state && typeof state === "object" ? state : {} }),
+      reportState: (sessionId, state) => fire({ ...state && typeof state === "object" ? state : {}, type: "media.state", sessionId }),
       reportCapabilities: (sessionId, actions) => fire({ type: "media.capabilities", sessionId, actions }),
-      sendCommand: (sessionId, action, value) => fire({ type: "media.command", sessionId, action, ...value === void 0 ? {} : { value } }),
-      onCommand: (sessionId, callback) => on("media.command", sessionId, (msg) => callback(msg.action, msg.value)),
-      onState: (sessionId, callback) => on("media.state", sessionId, (msg) => callback({
-        status: msg.status,
-        position: msg.position,
-        duration: msg.duration,
-        volume: msg.volume
-      })),
+      command,
+      sendCommand: (sessionId, action, value) => {
+        warn("SEND-COMMAND", "media.command(sessionId, { action, value })");
+        command(sessionId, { action, ...value === void 0 ? {} : { value } });
+      },
+      onCommand: (sessionId, callback) => {
+        const legacy = callback.length >= 2;
+        if (legacy) warn("COMMAND-CALLBACK", "media.onCommand(sessionId, command => ...)");
+        return on("media.command", sessionId, (msg) => legacy ? callback(msg.action, msg.value) : callback({ action: msg.action, ...msg.value === void 0 ? {} : { value: msg.value }, ...msg.reason === void 0 ? {} : { reason: msg.reason } }));
+      },
+      onState: (sessionId, callback) => on("media.state", sessionId, (msg) => {
+        const { type: _type, sessionId: _sessionId, ...state } = msg;
+        callback(state);
+      }),
       onCapabilities: (sessionId, callback) => on("media.capabilities", sessionId, (msg) => callback(msg.actions)),
-      onControls: (sessionId, callback) => on("media.controls", sessionId, (msg) => callback(msg.controls))
-    };
+      onControls: (sessionId, callback) => on("media.controls", sessionId, (msg) => callback(msg.controls)),
+      onEnded: (sessionId, callback) => on("media.session.ended", sessionId, (msg) => callback({ sessionId: msg.sessionId, reason: msg.reason }))
+    });
   }
   function makeNotify() {
     const on = (type, callback) => {
@@ -2853,6 +2916,57 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
       onChanged: (callback) => domainEventHandle("fs.changed", callback, (msg) => msg.change)
     };
   }
+  function makeLlm() {
+    const asFailure = (value) => {
+      if (!value || typeof value !== "object") return null;
+      const { code, message } = value;
+      return typeof code === "string" && typeof message === "string" ? { code, message } : null;
+    };
+    const failure = (entry) => Object.assign(new Error(entry.message), { code: entry.code });
+    function call(type, payload, field, options = {}) {
+      const requestId = id();
+      const promise = new Promise((resolve, reject) => {
+        let nextSequence = 0;
+        const onAbort = () => {
+          post({ type: "llm.cancel", id: id(), requestId });
+        };
+        const off = listen((event) => {
+          if (!isParentMessage(event)) return;
+          const msg = event.data;
+          if (typeof msg !== "object" || msg === null) return;
+          if (type === "llm.generate" && msg.type === "llm.delta" && msg.requestId === requestId) {
+            if (msg.sequence !== nextSequence || typeof msg.text !== "string") return;
+            nextSequence += 1;
+            options.onDelta?.({ requestId, sequence: msg.sequence, text: msg.text });
+            return;
+          }
+          if (msg.type !== `${type}.result` || msg.id !== requestId) return;
+          off();
+          options.signal?.removeEventListener("abort", onAbort);
+          const error = asFailure(msg.error);
+          if (error) {
+            reject(failure(error));
+            return;
+          }
+          if (!Object.prototype.hasOwnProperty.call(msg, field)) {
+            reject(failure({ code: "provider-error", message: `${type}.result missing ${field}` }));
+            return;
+          }
+          resolve(msg[field]);
+        });
+        post({ type, id: requestId, ...payload });
+        if (options.signal?.aborted) onAbort();
+        else options.signal?.addEventListener("abort", onAbort, { once: true });
+      });
+      return Object.assign(promise, { requestId });
+    }
+    return {
+      select: (requirements) => call("llm.select", requirements === void 0 ? {} : { requirements }, "model"),
+      describe: (handle) => call("llm.describe", { handle }, "model"),
+      generate: (request2, options) => call("llm.generate", { request: request2 }, "result", options ?? {}),
+      cancel: (requestId) => call("llm.cancel", { requestId }, "cancelled")
+    };
+  }
   const intentDelivery = allowed.has("intent") ? makeIntentDelivery() : void 0;
   const shell = allowed.has("shell") ? makeShell() : void 0;
   let gamepad;
@@ -2877,10 +2991,12 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
     intent ??= Object.freeze(makeIntent());
     return intent;
   }
+  let media;
   function isProtectedDomain(domain) {
-    return domain === "gamepad" || domain === "shell" || domain === "inc" || domain === "identity" || domain === "theme" || domain === "intent";
+    return domain === "media" || domain === "gamepad" || domain === "shell" || domain === "inc" || domain === "identity" || domain === "theme" || domain === "intent";
   }
   function makeDomain(domain, existing) {
+    if (domain === "media") return media ??= makeMedia();
     if (domain === "gamepad") return gamepad ??= makeGamepad();
     if (domain === "shell") return shell;
     if (domain === "inc") return makeProtectedInc(existing);
@@ -2895,8 +3011,6 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
         return makeStorage();
       case "keys":
         return makeKeys();
-      case "media":
-        return makeMedia();
       case "notify":
         return makeNotify();
       case "config":
@@ -2927,6 +3041,8 @@ function nappletNamespacePrelude(domains, normalizeIntentUri2) {
         return makeDm();
       case "fs":
         return makeFs();
+      case "llm":
+        return makeLlm();
       default:
         return {};
     }
@@ -3197,6 +3313,7 @@ export {
   createThemeProxy,
   denyNappletControllerAccess,
   formatDenialReason,
+  getShellDomainState,
   injectNappletCsp,
   injectNappletNamespacePrelude,
   manifestCache,