@larc-iu/plaid-client 0.2.0-alpha.2 → 0.2.0-alpha.4

package/src/provenance.js

@@ -43,6 +43,17 @@
  * human edits (history is valuable), so a consumer must not present
  * provProb as confidence in the CURRENT value once the entity is verified
  * (provConfirmed is exactly the flag to check).
+ *
+ * Recommended provDetail keys, so consumers (review dashboards, ranked
+ * alternatives) can read any producer's output:
+ *   - value (spans) / form (morpheme tokens): the value the producer
+ *     wrote, mirroring the entity's own field. The entity may be edited
+ *     later; this copy is what makes "accepted as-is" vs "corrected"
+ *     answerable once the entity is verified.
+ *   - valueProbs / formProbs: a top-k {label: probability} map over the
+ *     alternatives the producer considered, the chosen label included
+ *     (provProb, when given, is that label's entry duplicated flat).
+ *   - model, and anything else (language, adapter, raw scores).
  */
 
 /** The flat metadata keys of the provenance convention. */

package/src/serviceSchema.js

@@ -43,13 +43,17 @@
  * without an explicit `overwrite` parameter. See the manual, "Provenance".
  */
 export const TASKS = Object.freeze({
-  TOKENIZE: 'tokenize',
-  PARSE: 'parse',
-  TRANSCRIBE: 'transcribe',
+  TOKENIZE: "tokenize",
+  PARSE: "parse",
+  TRANSCRIBE: "transcribe",
   /** Create vocab links for unlinked tokens. */
-  LINK_VOCAB: 'link-vocab',
+  LINK_VOCAB: "link-vocab",
   /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
-  ANALYZE: 'analyze',
+  ANALYZE: "analyze",
+  /** Propose a free translation for each sentence. */
+  TRANSLATE: "translate",
+  /** A conversational assistant over a project (chat turns; see plaid-igt-agent). */
+  ASSIST: "assist",
 });
 
 /**
@@ -57,8 +61,8 @@ export const TASKS = Object.freeze({
  * declared `tasks` array. Drop once all services advertise `tasks`.
  */
 const LEGACY_TASK_PREFIXES = Object.freeze({
-  [TASKS.TOKENIZE]: 'tok:',
-  [TASKS.TRANSCRIBE]: 'asr:',
+  [TASKS.TOKENIZE]: "tok:",
+  [TASKS.TRANSCRIBE]: "asr:",
 });
 
 /**
@@ -74,7 +78,11 @@ export function servesTask(service, task) {
     return declared.includes(task);
   }
   const prefix = LEGACY_TASK_PREFIXES[task];
-  return !!prefix && typeof service?.serviceId === 'string' && service.serviceId.startsWith(prefix);
+  return (
+    !!prefix &&
+    typeof service?.serviceId === "string" &&
+    service.serviceId.startsWith(prefix)
+  );
 }
 
 /**
@@ -104,7 +112,7 @@ export function getParamSchema(service) {
  * @returns {string}
  */
 export function getServiceSummary(service) {
-  return service?.extras?.summary || service?.description || '';
+  return service?.extras?.summary || service?.description || "";
 }
 
 /** Valid option values for an enum/multiselect param. */
@@ -119,20 +127,25 @@ function optionValues(param) {
  */
 function defaultForParam(param) {
   const opts = optionValues(param);
-  if (param.type === 'enum') {
-    if (param.default != null && opts.includes(param.default)) return param.default;
-    return opts[0] ?? '';
+  if (param.type === "enum") {
+    if (param.default != null && opts.includes(param.default))
+      return param.default;
+    return opts[0] ?? "";
   }
-  if (param.type === 'multiselect') {
+  if (param.type === "multiselect") {
     const arr = Array.isArray(param.default) ? param.default : [];
     return opts.length ? arr.filter((x) => opts.includes(x)) : arr;
   }
-  if (param.default !== undefined && param.default !== null) return param.default;
+  if (param.default !== undefined && param.default !== null)
+    return param.default;
   switch (param.type) {
-    case 'number': return typeof param.min === 'number' ? param.min : 0;
-    case 'boolean': return false;
-    case 'string':
-    default: return '';
+    case "number":
+      return typeof param.min === "number" ? param.min : 0;
+    case "boolean":
+      return false;
+    case "string":
+    default:
+      return "";
   }
 }
 
@@ -169,43 +182,48 @@ export function coerceParamValues(schema, raw) {
     if (v === undefined) v = defaultForParam(param);
 
     switch (param.type) {
-      case 'number': {
+      case "number": {
         // Blank / nullish counts as "missing" → the param's default (matches the
         // Python client, where float('') raises and falls back to the default).
         let n;
-        if (v === '' || v == null || (typeof v === 'string' && v.trim() === '')) {
+        if (
+          v === "" ||
+          v == null ||
+          (typeof v === "string" && v.trim() === "")
+        ) {
           n = defaultForParam(param);
         } else {
-          n = typeof v === 'number' ? v : Number(v);
+          n = typeof v === "number" ? v : Number(v);
           if (Number.isNaN(n)) n = defaultForParam(param);
         }
-        if (typeof param.min === 'number') n = Math.max(param.min, n);
-        if (typeof param.max === 'number') n = Math.min(param.max, n);
+        if (typeof param.min === "number") n = Math.max(param.min, n);
+        if (typeof param.max === "number") n = Math.min(param.max, n);
         v = n;
         break;
       }
-      case 'boolean':
-        v = v === true || v === 'true';
+      case "boolean":
+        v = v === true || v === "true";
         break;
-      case 'enum': {
+      case "enum": {
         const opts = optionValues(param);
         if (opts.length && !opts.includes(v)) v = defaultForParam(param);
         break;
       }
-      case 'multiselect': {
+      case "multiselect": {
         const opts = optionValues(param);
-        const arr = Array.isArray(v) ? v : (v == null || v === '' ? [] : [v]);
+        const arr = Array.isArray(v) ? v : v == null || v === "" ? [] : [v];
         v = opts.length ? arr.filter((x) => opts.includes(x)) : arr;
         break;
       }
-      case 'string':
+      case "string":
       default:
-        v = v == null ? '' : String(v);
+        v = v == null ? "" : String(v);
         break;
     }
 
     if (param.required) {
-      const empty = v === '' || v == null || (Array.isArray(v) && v.length === 0);
+      const empty =
+        v === "" || v == null || (Array.isArray(v) && v.length === 0);
       if (empty) errors[k] = `${param.label || k} is required`;
     }
     values[k] = v;

package/src/services.js

@@ -52,13 +52,38 @@ export function discardService(client, projectId, serviceId) {
  * @param {Object} serviceInfo - {serviceId, serviceName, description}
  * @param {function} onServiceRequest - Handler callback (data, responseHelper)
  * @param {Object} extras - Optional additional metadata
- * @returns {Object} ServiceRegistration with .stop(), .isRunning(), .serviceInfo
+ * @param {function} [onStatus] - Optional callback (event, projectId, detail) for
+ *   connection-state transitions: 'registered', 'reconnected', 'disconnected'.
+ *   Called once per transition, not once per retry.
+ * @returns {Object} ServiceRegistration with .stop(), .isRunning(), .isConnected(),
+ *   .serviceInfo
  */
-export function serve(client, projectId, serviceInfo, onServiceRequest, extras = {}) {
+export function serve(client, projectId, serviceInfo, onServiceRequest, extras = {}, onStatus = null) {
   const { serviceId, serviceName, description = '' } = serviceInfo;
   let connection = null;
   let isRunning = true;
   let reconnectTimer = null;
+  // Last state REPORTED, so an outage produces one "lost" line and one "back"
+  // line however many retries it took.
+  let isConnected = false;
+  let everConnected = false;
+
+  const report = (event, detail) => {
+    if (!onStatus) return;
+    try { onStatus(event, projectId, detail); } catch (_) { /* never disturb the loop */ }
+  };
+  const noteConnected = () => {
+    if (isConnected) return;
+    const first = !everConnected;
+    isConnected = true;
+    everConnected = true;
+    report(first ? 'registered' : 'reconnected');
+  };
+  const noteDisconnected = () => {
+    if (!isConnected) return;
+    isConnected = false;
+    report('disconnected');
+  };
 
   const reportEvent = (requestId, body) =>
     client
@@ -76,6 +101,10 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
       if (connection) connection.close();
     },
     isRunning: () => isRunning,
+    // Whether the request channel is open RIGHT NOW, i.e. whether the server
+    // currently sees this service as online. A registration that is retrying
+    // through a server restart is still running but not connected.
+    isConnected: () => isRunning && !!connection && connection.readyState === 1,
     serviceInfo: { serviceId, serviceName, description, extras },
   };
 
@@ -118,12 +147,17 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
     throw new Error(`Failed to start service: ${error.message}`);
   }
 
-  // Reopen the channel if it drops (e.g. the server restarted). Reopening
-  // re-registers the service server-side, so presence and reachability come
-  // back together.
+  // Reopen the channel whenever it drops (e.g. the server restarted), for as
+  // long as the service runs. Reopening re-registers the service server-side,
+  // so presence and reachability come back together, and a server restart never
+  // means a service restart. A reopened channel counts as connected only once
+  // the server has actually answered it (readyState OPEN), not merely because
+  // the attempt was made.
   reconnectTimer = setInterval(() => {
-    if (!isRunning) return;
-    if (connection && connection.readyState === 2) { // CLOSED (dropped)
+    if (!isRunning || !connection) return;
+    if (connection.readyState === 1) { noteConnected(); return; }
+    if (connection.readyState === 2) { // CLOSED (dropped or failed)
+      noteDisconnected();
       try { connection = openChannel(); } catch (_) { /* retry next tick */ }
     }
   }, 3000);
@@ -144,9 +178,10 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * @param {any} data - Request payload
  * @param {number} [timeout=10000] - Timeout in ms
  * @param {function} [onProgress] - Called with each progress payload {percent, message}
+ * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
  * @returns {Promise<any>} The service's result
  */
-export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress) {
+export function requestService(client, projectId, serviceId, data, timeout = 10000, onProgress, signal) {
   // Propagate an open logical operation (client.beginOperation) to the
   // service: its writes then fold under the requester's audit-log entry
   // (the Python BaseService adopts the id around process_request). Only for a
@@ -172,6 +207,23 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
       timeout,
     );
 
+    // An external signal stops waiting on a long request (a UI's Stop button).
+    // Reject with an AbortError so a caller can tell a deliberate stop from a
+    // failure. The service is not told: it finishes its work and its reply
+    // goes nowhere, which is safe because it has already been asked for.
+    const stop = () => {
+      const err = new Error('The service request was stopped');
+      err.name = 'AbortError';
+      finish(reject, err);
+    };
+    if (signal) {
+      if (signal.aborted) {
+        stop();
+        return;
+      }
+      signal.addEventListener('abort', stop, { once: true });
+    }
+
     (async () => {
       let response;
       try {

package/src/sse.js

@@ -1,5 +1,17 @@
 import { transformResponse } from './transforms.js';
 
+// A live SSE stream is never silent for long: the server sends a keepalive
+// comment on service channels (every 25s) and a heartbeat event on the /listen
+// bus (every 30s). So if NOTHING arrives for longer than this, the connection is
+// dead: the server was killed without closing the socket, the network dropped
+// it, or a reconnect caught the server mid-restart (port accepting, app not yet
+// streaming). We must surface that as a drop so the registration supervisor in
+// serve() can reopen it. Without the watchdog such a silent drop
+// leaves `reader.read()` pending forever: readyState never reaches CLOSED, so
+// nothing reconnects and the service never heals. Comfortably above both server
+// cadences, so a healthy idle stream never trips it.
+export const SSE_IDLE_TIMEOUT_MS = 60000;
+
 /**
  * Project a parsed SSE `data:` object onto what a listener callback sees.
  *
@@ -59,6 +71,21 @@ export function createSSEConnection(client, projectId, onEvent, path) {
     }
   };
 
+  // Watchdog: abort the fetch if the stream goes silent for longer than the
+  // server's keepalive cadence, so a silently-dropped connection lands in the
+  // catch below (readyState CLOSED) instead of blocking on a read that will
+  // never resolve.
+  let idleTimer = null;
+  const clearIdleTimer = () => {
+    if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+  };
+  const armIdleTimer = () => {
+    clearIdleTimer();
+    idleTimer = setTimeout(() => {
+      if (!isClosed) abortController.abort(new Error('SSE stream went silent'));
+    }, SSE_IDLE_TIMEOUT_MS);
+  };
+
   const sseConnection = {
     readyState: 0, // CONNECTING
     close: () => {
@@ -66,6 +93,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
         isClosed = true;
         isConnected = false;
         sseConnection.readyState = 2; // CLOSED
+        clearIdleTimer();
         abortController.abort();
       }
     },
@@ -83,6 +111,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
   (async () => {
     try {
       const url = `${client.baseUrl}${streamPath}`;
+      armIdleTimer();
       const response = await fetch(url, {
         method: 'GET',
         headers: {
@@ -120,6 +149,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
       while (true) {
         const { done, value } = await reader.read();
         if (done || isClosed) break;
+        armIdleTimer();
 
         buffer += decoder.decode(value, { stream: true });
         const lines = buffer.split('\n');
@@ -163,6 +193,7 @@ export function createSSEConnection(client, projectId, onEvent, path) {
         console.warn('SSE connection error:', error);
       }
     } finally {
+      clearIdleTimer();
       isConnected = false;
       isClosed = true;
       sseConnection.readyState = 2; // CLOSED