@jskit-ai/assistant-runtime 0.1.193 → 0.1.194

package/src/server/inputSchemas.js

@@ -1,5 +1,6 @@
 import { createSchema } from "json-rest-schema";
 import { deepFreeze } from "@jskit-ai/kernel/shared/support/deepFreeze";
+import { composeSchemaDefinitions } from "@jskit-ai/kernel/shared/validators";
 
 const assistantSurfaceRouteParamsSchema = createSchema({
   surfaceId: {
@@ -38,7 +39,96 @@ const assistantTargetSurfaceInputValidator = deepFreeze({
   mode: "patch"
 });
 
+const assistantConversationIdInputValidator = deepFreeze({
+  schema: createSchema({
+    conversationId: { type: "string", required: true, minLength: 1 }
+  }),
+  mode: "patch"
+});
+
+const assistantConversationMessageIdInputValidator = deepFreeze({
+  schema: createSchema({
+    messageId: { type: "string", required: true, minLength: 1, maxLength: 128 }
+  }),
+  mode: "patch"
+});
+
+const assistantConversationReadQueryValidator = deepFreeze({
+  schema: createSchema({
+    beforeTurnId: { type: "string", noTrim: false, required: false },
+    limit: { type: "string", noTrim: false, required: false }
+  }),
+  mode: "patch"
+});
+
+const assistantConversationSendBodyValidator = deepFreeze({
+  schema: createSchema({
+    messageId: { type: "string", required: true, minLength: 1, maxLength: 128 },
+    text: { type: "string", required: true },
+    attachmentIds: {
+      type: "array", required: false, maxItems: 10,
+      items: { type: "string", minLength: 1, maxLength: 256 }
+    },
+    steer: { type: "boolean", required: false }
+  }),
+  mode: "patch"
+});
+
+function conversationSendBodyValidator(conversationDataSchema = null) {
+  if (!conversationDataSchema) return assistantConversationSendBodyValidator;
+  return composeSchemaDefinitions([assistantConversationSendBodyValidator, {
+    schema: createSchema({ data: { type: "object", required: false, schema: conversationDataSchema } }),
+    mode: "patch"
+  }], { mode: "patch", context: "assistant-runtime declared conversation data" });
+}
+
+function conversationConfigureBodyValidator(configurationSchema) {
+  return deepFreeze({
+    schema: createSchema({ configuration: { type: "object", required: true, schema: configurationSchema } }),
+    mode: "replace"
+  });
+}
+
+function conversationSelectBodyValidator(selectionSchema) {
+  return deepFreeze({
+    schema: createSchema({ selection: { type: "object", required: true, schema: selectionSchema } }),
+    mode: "replace"
+  });
+}
+
+function conversationReplaceBodyValidator(replacementSchema) {
+  return deepFreeze({
+    schema: createSchema({ replacement: { type: "object", required: true, schema: replacementSchema } }),
+    mode: "replace"
+  });
+}
+
+const assistantConversationGoalBodyValidator = deepFreeze({
+  schema: createSchema({
+    action: { type: "string", required: true, enum: ["set", "resume", "pause", "cancel"] },
+    expectedSegmentId: { type: "string", required: true, nullable: true, minLength: 1, maxLength: 128 },
+    expectedGoalId: { type: "string", required: false, nullable: true, minLength: 1, maxLength: 256 },
+    messageId: { type: "string", required: false, minLength: 1, maxLength: 128 },
+    objective: { type: "string", required: false, minLength: 1, maxLength: 4000 },
+    tokenBudget: { type: "integer", required: false, nullable: true, min: 1, max: Number.MAX_SAFE_INTEGER },
+    attachmentIds: {
+      type: "array", required: false, maxItems: 10,
+      items: { type: "string", minLength: 1, maxLength: 256 }
+    }
+  }),
+  mode: "replace"
+});
+
 export {
+  assistantConversationIdInputValidator,
+  assistantConversationMessageIdInputValidator,
+  assistantConversationReadQueryValidator,
+  assistantConversationSendBodyValidator,
+  conversationSendBodyValidator,
+  conversationConfigureBodyValidator,
+  conversationSelectBodyValidator,
+  conversationReplaceBodyValidator,
+  assistantConversationGoalBodyValidator,
   assistantSurfaceRouteParamsValidator,
   assistantTargetSurfaceInputValidator
 };

package/src/server/registerConversationSubscriptions.js

@@ -0,0 +1,163 @@
+import { randomUUID } from "node:crypto";
+import { attachDirectRequestActionExecutor } from "@jskit-ai/kernel/server/http";
+import { AppError } from "@jskit-ai/kernel/server/runtime";
+import { actionIds } from "./actionIds.js";
+import { resolveRouteRequestState } from "./support/assistantRouteContext.js";
+import { resolveAssistantSurfaceConfig } from "../shared/assistantSurfaces.js";
+import {
+  ASSISTANT_CONVERSATION_EVENT,
+  ASSISTANT_CONVERSATION_SUBSCRIBE,
+  ASSISTANT_CONVERSATION_UNSUBSCRIBE
+} from "../shared/conversationRealtime.js";
+
+function requireSubscriptionId(input) {
+  if (typeof input?.subscriptionId !== "string" || !input.subscriptionId.trim() || input.subscriptionId.length > 128) {
+    throw new AppError(400, "A conversation subscription id is required.");
+  }
+  return input.subscriptionId;
+}
+
+function subscriptionError(error) {
+  const status = Number(error?.status || error?.statusCode || 500);
+  return {
+    ok: false,
+    error: status < 500 ? String(error.message || "Conversation subscription failed.") : "Conversation subscription failed.",
+    code: String(error?.code || "assistant_subscription_failed"),
+    status
+  };
+}
+
+// Register one conversation subscription owner per shared realtime runtime.
+// A host may select its fixed action/request policy at composition; clients
+// never choose either. The selected action remains the authorization boundary.
+function registerConversationSubscriptions({ realtime, events, actions, config = {}, workspaceScopeSupport = null,
+  subscribeActionId = actionIds.conversationSubscribe, requestPolicy = "authenticated" } = {}) {
+  if (typeof realtime?.onConnection !== "function" || typeof events?.publish !== "function") {
+    throw new TypeError("Conversation subscriptions require the shared realtime connection and event runtime.");
+  }
+  if (typeof actions?.execute !== "function" || typeof actions?.getDefinition !== "function") {
+    throw new TypeError("Conversation subscriptions require the assistant action catalogue.");
+  }
+  if (!["authenticated", "host"].includes(requestPolicy)) {
+    throw new TypeError("Conversation subscription requestPolicy must be authenticated or host.");
+  }
+  if (typeof subscribeActionId !== "string" || !subscribeActionId.trim() ||
+      (requestPolicy === "host" && subscribeActionId === actionIds.conversationSubscribe)) {
+    throw new TypeError("Host conversation subscriptions require an explicit product subscribeActionId.");
+  }
+
+  return realtime.onConnection(({ socket, authenticate, readRequest }) => {
+    const subscriptions = new Map();
+    let closed = false;
+
+    function release(subscriptionId) {
+      const subscription = subscriptions.get(subscriptionId);
+      if (!subscription) return;
+      subscriptions.delete(subscriptionId);
+      clearTimeout(subscription.timer);
+      subscription.pending.clear();
+      subscription.release?.();
+    }
+
+    async function subscribe(input, acknowledge) {
+      if (typeof acknowledge !== "function" || closed) return;
+      let subscription;
+      let subscriptionId;
+      try {
+        subscriptionId = requireSubscriptionId(input);
+        release(subscriptionId);
+        subscription = { pending: new Map(), revision: 0, epoch: randomUUID(), queue: Promise.resolve() };
+        subscriptions.set(subscriptionId, subscription);
+        const current = () => !closed && socket.connected && subscriptions.get(subscriptionId) === subscription;
+        const request = await (requestPolicy === "host" ? readRequest() : authenticate());
+        if (!current()) return;
+        const assistantSurface = resolveAssistantSurfaceConfig(config, input.targetSurfaceId);
+        if (!assistantSurface) throw new AppError(404, "Assistant not found.");
+        const requiresWorkspace = assistantSurface.runtimeSurfaceRequiresWorkspace;
+        request.headers = { ...request.headers, "x-jskit-surface": input.hostSurfaceId };
+        request.input = { params: {
+          surfaceId: input.targetSurfaceId,
+          ...(Object.hasOwn(input, "workspaceSlug") ? { workspaceSlug: input.workspaceSlug } : {})
+        } };
+        request.routeOptions = { config: { visibility: requiresWorkspace ? "workspace" : "public" } };
+        const routeState = resolveRouteRequestState(request, {
+          resolveCurrentAppConfig: () => config, requiresWorkspace, workspaceScopeSupport
+        });
+        attachDirectRequestActionExecutor({ actions, request });
+        const actorId = request.user?.id;
+
+        function publish(event, revision) {
+          subscription.queue = subscription.queue.then(async () => {
+            if (!current()) return;
+            await events.publish({
+              type: "entity.changed", source: "assistant", entity: "conversation", operation: "updated",
+              entityId: input.conversationId,
+              ...(actorId ? { actorId, scope: { kind: "user", id: actorId } } : {}),
+              realtime: {
+                audience: { room: socket.id },
+                event: ASSISTANT_CONVERSATION_EVENT,
+                payload: { subscriptionId, conversationId: input.conversationId,
+                  streamEpoch: subscription.epoch, streamRevision: revision, event }
+              }
+            });
+          }).catch(() => {}); // A notification failure cannot fail or repeat a model turn.
+        }
+        function flush() {
+          clearTimeout(subscription.timer);
+          subscription.timer = null;
+          for (const pending of [...subscription.pending.values()].sort((left, right) => left.revision - right.revision)) {
+            publish(pending.event, pending.revision);
+          }
+          subscription.pending.clear();
+        }
+        function onEvent(event) {
+          if (!current()) return;
+          const revision = ++subscription.revision;
+          // The Colleague publisher already coalesces transient full-text replies.
+          if (event.type === "message" && event.status === "inProgress") {
+            subscription.pending.set(event.messageId, { event, revision });
+            subscription.timer ||= setTimeout(flush, 25);
+          } else {
+            flush();
+            publish(event, revision);
+          }
+        }
+        const state = await request.executeAction({
+          actionId: subscribeActionId, channel: "internal", surface: routeState.hostSurfaceId,
+          input: { ...routeState.actionInput, conversationId: input.conversationId },
+          deps: {
+            onEvent,
+            onRelease(detach) {
+              if (!current()) detach();
+              else subscription.release = detach;
+            }
+          }
+        });
+        if (!current()) return;
+        acknowledge({ ok: true, subscriptionId, streamEpoch: subscription.epoch, state });
+      } catch (error) {
+        if (subscriptions.get(subscriptionId) === subscription) release(subscriptionId);
+        if (!closed && socket.connected) acknowledge(subscriptionError(error));
+      }
+    }
+
+    function unsubscribe(input, acknowledge) {
+      try {
+        release(requireSubscriptionId(input));
+        if (typeof acknowledge === "function") acknowledge({ ok: true });
+      } catch (error) {
+        if (typeof acknowledge === "function") acknowledge(subscriptionError(error));
+      }
+    }
+    socket.on(ASSISTANT_CONVERSATION_SUBSCRIBE, subscribe);
+    socket.on(ASSISTANT_CONVERSATION_UNSUBSCRIBE, unsubscribe);
+    return () => {
+      closed = true;
+      socket.off(ASSISTANT_CONVERSATION_SUBSCRIBE, subscribe);
+      socket.off(ASSISTANT_CONVERSATION_UNSUBSCRIBE, unsubscribe);
+      for (const subscriptionId of subscriptions.keys()) release(subscriptionId);
+    };
+  });
+}
+
+export { registerConversationSubscriptions };

package/src/server/registerFastifyConversations.js

@@ -0,0 +1,76 @@
+import { createActionProvider } from "@jskit-ai/kernel/server/actions";
+import { HttpProvider } from "@jskit-ai/kernel/server/http";
+import { AppError, BootstrapProvider, EventProvider } from "@jskit-ai/kernel/server/runtime";
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { AssistantFeature } from "./AssistantProvider.js";
+
+/**
+ * Configure the existing conversation feature in a plain Fastify application.
+ * The caller owns runtime creation/storage and authentication. This registration
+ * owns its HTTP/realtime hosting and shuts it down before Fastify closes.
+ * JSKIT applications register AssistantFeature on their existing host instead.
+ */
+async function registerFastifyConversations(app, {
+  runtime,
+  config,
+  authenticate,
+  bootstrap,
+  env = process.env
+} = {}) {
+  if (typeof runtime?.open !== "function" || typeof authenticate !== "function" ||
+      !config || typeof config !== "object" || Array.isArray(config)) {
+    throw new TypeError("Fastify conversations require runtime, config and authenticate(request).");
+  }
+  async function requestContext(request) {
+    const context = await authenticate(request);
+    if (!context || typeof context !== "object" || Array.isArray(context)) {
+      throw new AppError(401, "Authentication required.");
+    }
+    return context;
+  }
+  const AccessProvider = defineProvider({
+    id: "assistant.fastify.access",
+    requires: { http: "runtime.http", bootstrap: "runtime.bootstrap", actions: "runtime.actions" },
+    provides: { access: "assistant.conversation.access" },
+    setup({ http, bootstrap: bootstrapRuntime, actions }) {
+      actions.registerContextContributor({
+        id: "assistant.fastify.authentication",
+        contribute: ({ context }) => requestContext(context.requestMeta?.request)
+      });
+      bootstrapRuntime.register({
+        id: "assistant.fastify.application",
+        async contribute({ request }) {
+          const context = await requestContext(request);
+          return bootstrap ? bootstrap({ request, context }) : {};
+        }
+      });
+      return { access: {
+        router: { register(method, path, contract, handler) {
+          http.router.register(method, path, { ...contract, auth: "public" }, async (request, reply) => {
+            await requestContext(request);
+            return handler(request, reply);
+          });
+        } },
+        wrapAction(definition) {
+          return { ...definition, permission: { require: "none" } };
+        },
+        subscribeActionId: "assistant.fastify.conversation.subscribe",
+        requestPolicy: "host"
+      } };
+    }
+  });
+  // Realtime remains optional for consumers using the feature on their own host.
+  const { RealtimeProvider } = await import("@jskit-ai/realtime/server/RealtimeProvider");
+  const host = createCapabilityRuntime({
+    providers: [EventProvider, createActionProvider(), HttpProvider, BootstrapProvider,
+      RealtimeProvider, AccessProvider, AssistantFeature],
+    inputs: { "runtime.config": config, "runtime.env": env, "runtime.fastify": app,
+      "runtime.logger": app.log, "assistant.conversations": runtime }
+  });
+  app.addHook("preClose", async () => {
+    if (host.diagnostics().lifecycleState === "started") await host.shutdown();
+  });
+  await host.start();
+}
+
+export { registerFastifyConversations };