@jskit-ai/assistant-core 0.1.1

package/src/shared/assistantResource.js

@@ -0,0 +1,309 @@
+import { Type } from "typebox";
+import {
+  normalizeObjectInput,
+  createCursorListValidator
+} from "@jskit-ai/kernel/shared/validators";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeConversationStatus } from "./support/conversationStatus.js";
+import { toPositiveInteger } from "./support/positiveInteger.js";
+
+const MAX_INPUT_CHARS = 8000;
+const MAX_HISTORY_MESSAGES = 20;
+const MAX_PAGE_SIZE = 200;
+const MAX_MESSAGE_PAGE_SIZE = 500;
+
+function normalizePaginationValue(value, fallback, max) {
+  const parsed = toPositiveInteger(value, fallback);
+  return Math.max(1, Math.min(max, parsed));
+}
+
+function normalizeChatStreamBody(payload = {}) {
+  const source = normalizeObjectInput(payload);
+  const normalized = {
+    messageId: normalizeText(source.messageId),
+    input: normalizeText(source.input)
+  };
+
+  const conversationId = toPositiveInteger(source.conversationId, 0);
+  if (conversationId > 0) {
+    normalized.conversationId = conversationId;
+  }
+
+  const history = Array.isArray(source.history) ? source.history : [];
+  normalized.history = history
+    .slice(0, MAX_HISTORY_MESSAGES)
+    .map((entry) => {
+      const item = normalizeObjectInput(entry);
+      const role = normalizeText(item.role).toLowerCase();
+      if (role !== "user" && role !== "assistant") {
+        return null;
+      }
+
+      const content = normalizeText(item.content);
+      if (!content) {
+        return null;
+      }
+
+      return {
+        role,
+        content: content.slice(0, MAX_INPUT_CHARS)
+      };
+    })
+    .filter(Boolean);
+
+  const clientContext = normalizeObjectInput(source.clientContext);
+  if (Object.keys(clientContext).length > 0) {
+    normalized.clientContext = {
+      locale: normalizeText(clientContext.locale),
+      timezone: normalizeText(clientContext.timezone)
+    };
+  }
+
+  return normalized;
+}
+
+function normalizeConversationsListQuery(payload = {}) {
+  const source = normalizeObjectInput(payload);
+  const status = normalizeConversationStatus(source.status, {
+    fallback: ""
+  });
+  const normalized = {};
+
+  if (Object.hasOwn(source, "cursor")) {
+    normalized.cursor = toPositiveInteger(source.cursor, 0);
+  }
+  if (Object.hasOwn(source, "limit")) {
+    normalized.limit = toPositiveInteger(source.limit, 0);
+  }
+  if (status) {
+    normalized.status = status;
+  }
+
+  return normalized;
+}
+
+function normalizeConversationMessagesQuery(payload = {}) {
+  const source = normalizeObjectInput(payload);
+
+  return {
+    page: normalizePaginationValue(source.page, 1, MAX_MESSAGE_PAGE_SIZE),
+    pageSize: normalizePaginationValue(source.pageSize, 200, MAX_MESSAGE_PAGE_SIZE)
+  };
+}
+
+function normalizeConversationMessagesParams(payload = {}) {
+  const source = normalizeObjectInput(payload);
+  return {
+    conversationId: toPositiveInteger(source.conversationId, 0)
+  };
+}
+
+function createOptionalPositiveIntegerQuerySchema(max = null) {
+  const numericSchema = max == null
+    ? Type.Integer({ minimum: 1 })
+    : Type.Integer({ minimum: 1, maximum: max });
+
+  return Type.Optional(
+    Type.Union([
+      numericSchema,
+      Type.String({ pattern: "^[1-9][0-9]*$" })
+    ])
+  );
+}
+
+function normalizeConversationRecord(payload = {}) {
+  const source = normalizeObjectInput(payload);
+
+  return {
+    id: toPositiveInteger(source.id, 0),
+    workspaceId: toPositiveInteger(source.workspaceId, 0) || null,
+    title: normalizeText(source.title),
+    createdByUserId: toPositiveInteger(source.createdByUserId, 0) || null,
+    status: normalizeText(source.status),
+    provider: normalizeText(source.provider),
+    model: normalizeText(source.model),
+    surfaceId: normalizeText(source.surfaceId || source.surfaceSid).toLowerCase(),
+    startedAt: normalizeText(source.startedAt),
+    endedAt: normalizeText(source.endedAt) || null,
+    messageCount: Math.max(0, Number(source.messageCount || 0)),
+    metadata: normalizeObjectInput(source.metadata),
+    createdAt: normalizeText(source.createdAt),
+    updatedAt: normalizeText(source.updatedAt)
+  };
+}
+
+function normalizeConversationMessageRecord(payload = {}) {
+  const source = normalizeObjectInput(payload);
+
+  return {
+    id: toPositiveInteger(source.id, 0),
+    conversationId: toPositiveInteger(source.conversationId, 0),
+    workspaceId: toPositiveInteger(source.workspaceId, 0) || null,
+    seq: toPositiveInteger(source.seq, 0),
+    role: normalizeText(source.role),
+    kind: normalizeText(source.kind),
+    clientMessageSid: normalizeText(source.clientMessageSid),
+    actorUserId: toPositiveInteger(source.actorUserId, 0) || null,
+    contentText: source.contentText == null ? null : String(source.contentText),
+    metadata: normalizeObjectInput(source.metadata),
+    createdAt: normalizeText(source.createdAt)
+  };
+}
+
+const historyMessageSchema = Type.Object(
+  {
+    role: Type.Union([Type.Literal("user"), Type.Literal("assistant")]),
+    content: Type.String({ minLength: 1, maxLength: MAX_INPUT_CHARS })
+  },
+  { additionalProperties: false }
+);
+
+const chatStreamBodySchema = Type.Object(
+  {
+    messageId: Type.String({ minLength: 1, maxLength: 128 }),
+    conversationId: Type.Optional(Type.Integer({ minimum: 1 })),
+    input: Type.String({ minLength: 1, maxLength: MAX_INPUT_CHARS }),
+    history: Type.Optional(Type.Array(historyMessageSchema, { maxItems: MAX_HISTORY_MESSAGES })),
+    clientContext: Type.Optional(
+      Type.Object(
+        {
+          locale: Type.Optional(Type.String({ maxLength: 64 })),
+          timezone: Type.Optional(Type.String({ maxLength: 64 }))
+        },
+        { additionalProperties: false }
+      )
+    )
+  },
+  {
+    additionalProperties: false
+  }
+);
+
+const conversationRecordSchema = Type.Object(
+  {
+    id: Type.Integer({ minimum: 1 }),
+    workspaceId: Type.Union([Type.Integer({ minimum: 1 }), Type.Null()]),
+    title: Type.String(),
+    createdByUserId: Type.Union([Type.Integer({ minimum: 1 }), Type.Null()]),
+    status: Type.String(),
+    provider: Type.String(),
+    model: Type.String(),
+    surfaceId: Type.String(),
+    startedAt: Type.String({ minLength: 1 }),
+    endedAt: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
+    messageCount: Type.Integer({ minimum: 0 }),
+    metadata: Type.Record(Type.String(), Type.Unknown()),
+    createdAt: Type.String({ minLength: 1 }),
+    updatedAt: Type.String({ minLength: 1 })
+  },
+  { additionalProperties: false }
+);
+
+const conversationRecordValidator = Object.freeze({
+  schema: conversationRecordSchema,
+  normalize: normalizeConversationRecord
+});
+
+const messageRecordSchema = Type.Object(
+  {
+    id: Type.Integer({ minimum: 1 }),
+    conversationId: Type.Integer({ minimum: 1 }),
+    workspaceId: Type.Union([Type.Integer({ minimum: 1 }), Type.Null()]),
+    seq: Type.Integer({ minimum: 1 }),
+    role: Type.String({ minLength: 1 }),
+    kind: Type.String({ minLength: 1 }),
+    clientMessageSid: Type.String(),
+    actorUserId: Type.Union([Type.Integer({ minimum: 1 }), Type.Null()]),
+    contentText: Type.Union([Type.String(), Type.Null()]),
+    metadata: Type.Record(Type.String(), Type.Unknown()),
+    createdAt: Type.String({ minLength: 1 })
+  },
+  { additionalProperties: false }
+);
+
+const paginationProperties = Object.freeze({
+  page: Type.Integer({ minimum: 1 }),
+  pageSize: Type.Integer({ minimum: 1 }),
+  total: Type.Integer({ minimum: 0 }),
+  totalPages: Type.Integer({ minimum: 1 })
+});
+
+const assistantResource = Object.freeze({
+  resource: "assistant",
+  operations: {
+    chatStream: {
+      method: "POST",
+      bodyValidator: Object.freeze({
+        schema: chatStreamBodySchema,
+        normalize: normalizeChatStreamBody
+      })
+    },
+    conversationsList: {
+      method: "GET",
+      queryValidator: Object.freeze({
+        schema: Type.Object(
+          {
+            cursor: createOptionalPositiveIntegerQuerySchema(),
+            limit: createOptionalPositiveIntegerQuerySchema(MAX_PAGE_SIZE),
+            status: Type.Optional(Type.String({ minLength: 1, maxLength: 32 }))
+          },
+          { additionalProperties: false }
+        ),
+        normalize: normalizeConversationsListQuery
+      }),
+      outputValidator: createCursorListValidator(conversationRecordValidator)
+    },
+    conversationMessagesList: {
+      method: "GET",
+      paramsValidator: Object.freeze({
+        schema: Type.Object(
+          {
+            conversationId: Type.Union([
+              Type.Integer({ minimum: 1 }),
+              Type.String({ pattern: "^[1-9][0-9]*$" })
+            ])
+          },
+          { additionalProperties: false }
+        ),
+        normalize: normalizeConversationMessagesParams
+      }),
+      queryValidator: Object.freeze({
+        schema: Type.Object(
+          {
+            page: createOptionalPositiveIntegerQuerySchema(),
+            pageSize: createOptionalPositiveIntegerQuerySchema(MAX_MESSAGE_PAGE_SIZE)
+          },
+          { additionalProperties: false }
+        ),
+        normalize: normalizeConversationMessagesQuery
+      }),
+      outputValidator: Object.freeze({
+        schema: Type.Object(
+          {
+            ...paginationProperties,
+            conversation: conversationRecordSchema,
+            entries: Type.Array(messageRecordSchema)
+          },
+          { additionalProperties: false }
+        ),
+        normalize(payload = {}) {
+          const source = normalizeObjectInput(payload);
+          return {
+            conversation: normalizeConversationRecord(source.conversation),
+            entries: (Array.isArray(source.entries) ? source.entries : []).map(normalizeConversationMessageRecord),
+            page: normalizePaginationValue(source.page, 1, MAX_MESSAGE_PAGE_SIZE),
+            pageSize: normalizePaginationValue(source.pageSize, 200, MAX_MESSAGE_PAGE_SIZE),
+            total: Math.max(0, Number(source.total || 0)),
+            totalPages: Math.max(1, Number(source.totalPages || 1))
+          };
+        }
+      })
+    }
+  }
+});
+
+export {
+  MAX_INPUT_CHARS,
+  MAX_HISTORY_MESSAGES,
+  assistantResource
+};

package/src/shared/assistantSettingsResource.js

@@ -0,0 +1,90 @@
+import { Type } from "typebox";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators";
+import { toPositiveInteger } from "./support/positiveInteger.js";
+
+const MAX_SYSTEM_PROMPT_CHARS = 12_000;
+
+const assistantConfigRecordSchema = Type.Object(
+  {
+    targetSurfaceId: Type.String({ minLength: 1, maxLength: 64 }),
+    scopeKey: Type.String({ minLength: 1, maxLength: 160 }),
+    workspaceId: Type.Union([Type.Integer({ minimum: 1 }), Type.Null()]),
+    settings: Type.Object(
+      {
+        systemPrompt: Type.String({ maxLength: MAX_SYSTEM_PROMPT_CHARS })
+      },
+      { additionalProperties: false }
+    )
+  },
+  { additionalProperties: false }
+);
+
+const assistantConfigPatchSchema = Type.Object(
+  {
+    systemPrompt: Type.Optional(
+      Type.String({
+        maxLength: MAX_SYSTEM_PROMPT_CHARS,
+        messages: {
+          maxLength: `Assistant system prompt must be at most ${MAX_SYSTEM_PROMPT_CHARS} characters.`,
+          default: "Assistant system prompt must be valid text."
+        }
+      })
+    )
+  },
+  { additionalProperties: false }
+);
+
+function normalizeConfigPatch(payload = {}) {
+  const source = normalizeObjectInput(payload);
+  const normalized = {};
+
+  if (Object.hasOwn(source, "systemPrompt")) {
+    normalized.systemPrompt = String(source.systemPrompt || "");
+  }
+
+  return normalized;
+}
+
+function normalizeConfigRecord(payload = {}) {
+  const source = normalizeObjectInput(payload);
+  const settings = normalizeObjectInput(source.settings);
+
+  return {
+    targetSurfaceId: normalizeText(source.targetSurfaceId).toLowerCase(),
+    scopeKey: normalizeText(source.scopeKey),
+    workspaceId: toPositiveInteger(source.workspaceId, 0) || null,
+    settings: {
+      systemPrompt: String(settings.systemPrompt || "")
+    }
+  };
+}
+
+const assistantConfigResource = Object.freeze({
+  resource: "assistantConfig",
+  operations: Object.freeze({
+    view: Object.freeze({
+      method: "GET",
+      outputValidator: Object.freeze({
+        schema: assistantConfigRecordSchema,
+        normalize: normalizeConfigRecord
+      })
+    }),
+    patch: Object.freeze({
+      method: "PATCH",
+      bodyValidator: Object.freeze({
+        schema: assistantConfigPatchSchema,
+        normalize: normalizeConfigPatch
+      }),
+      outputValidator: Object.freeze({
+        schema: assistantConfigRecordSchema,
+        normalize: normalizeConfigRecord
+      })
+    })
+  })
+});
+
+export {
+  MAX_SYSTEM_PROMPT_CHARS,
+  assistantConfigResource
+};

package/src/shared/index.js

@@ -0,0 +1,47 @@
+export {
+  ASSISTANT_API_RELATIVE_PATH,
+  ASSISTANT_SETTINGS_API_RELATIVE_PATH,
+  ASSISTANT_WORKSPACE_API_BASE_PATH_TEMPLATE,
+  ASSISTANT_PUBLIC_API_BASE_PATH,
+  ASSISTANT_WORKSPACE_SETTINGS_API_PATH_TEMPLATE,
+  ASSISTANT_PUBLIC_SETTINGS_API_PATH,
+  resolveAssistantApiBasePath,
+  resolveAssistantSettingsApiPath,
+  buildAssistantApiPath,
+  buildAssistantSettingsApiPath
+} from "./assistantPaths.js";
+
+export {
+  ASSISTANT_QUERY_KEY_PREFIX,
+  assistantRootQueryKey,
+  assistantScopeQueryKey,
+  assistantSettingsQueryKey,
+  assistantConversationsListQueryKey,
+  assistantConversationMessagesQueryKey
+} from "./queryKeys.js";
+
+export {
+  ASSISTANT_STREAM_EVENT_TYPES,
+  normalizeAssistantStreamEventType
+} from "./streamEvents.js";
+
+export {
+  MAX_INPUT_CHARS,
+  MAX_HISTORY_MESSAGES,
+  assistantResource
+} from "./assistantResource.js";
+
+export {
+  MAX_SYSTEM_PROMPT_CHARS,
+  assistantConfigResource
+} from "./assistantSettingsResource.js";
+
+export { assistantSettingsEvents } from "./settingsEvents.js";
+
+export {
+  ASSISTANT_CONVERSATION_STATUSES,
+  normalizeConversationStatus
+} from "./support/conversationStatus.js";
+
+export { parseJsonObject } from "./support/jsonObject.js";
+export { toPositiveInteger } from "./support/positiveInteger.js";

package/src/shared/queryKeys.js

@@ -0,0 +1,84 @@
+const ASSISTANT_QUERY_KEY_PREFIX = Object.freeze(["assistant"]);
+
+function normalizeSurfaceId(value) {
+  return String(value || "").trim().toLowerCase() || "none";
+}
+
+function normalizeWorkspaceSlug(value) {
+  return String(value || "").trim() || "none";
+}
+
+function normalizePositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    return fallback;
+  }
+
+  return parsed;
+}
+
+function normalizeScopeKey({ targetSurfaceId = "", workspaceSlug = "", workspaceId = 0 } = {}) {
+  const normalizedWorkspaceId = normalizePositiveInteger(workspaceId, 0);
+  const normalizedSurfaceId = normalizeSurfaceId(targetSurfaceId);
+  if (normalizedWorkspaceId > 0) {
+    return `${normalizedSurfaceId}:workspace:${normalizedWorkspaceId}`;
+  }
+
+  const normalizedWorkspaceSlug = normalizeWorkspaceSlug(workspaceSlug);
+  if (normalizedWorkspaceSlug !== "none") {
+    return `${normalizedSurfaceId}:slug:${normalizedWorkspaceSlug}`;
+  }
+
+  return `${normalizedSurfaceId}:global`;
+}
+
+function normalizeStatus(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  return normalized || "all";
+}
+
+function normalizeConversationId(value) {
+  return String(normalizePositiveInteger(value, 0) || "none");
+}
+
+function assistantRootQueryKey() {
+  return [...ASSISTANT_QUERY_KEY_PREFIX];
+}
+
+function assistantScopeQueryKey(scope = {}) {
+  return [...assistantRootQueryKey(), normalizeScopeKey(scope)];
+}
+
+function assistantSettingsQueryKey(scope = {}) {
+  return [...assistantScopeQueryKey(scope), "settings"];
+}
+
+function assistantConversationsListQueryKey(scope = {}, { limit = 20, status = "" } = {}) {
+  return [
+    ...assistantScopeQueryKey(scope),
+    "conversations",
+    "list",
+    normalizePositiveInteger(limit, 20),
+    normalizeStatus(status)
+  ];
+}
+
+function assistantConversationMessagesQueryKey(scope = {}, conversationId, { page = 1, pageSize = 200 } = {}) {
+  return [
+    ...assistantScopeQueryKey(scope),
+    "conversations",
+    normalizeConversationId(conversationId),
+    "messages",
+    normalizePositiveInteger(page, 1),
+    normalizePositiveInteger(pageSize, 200)
+  ];
+}
+
+export {
+  ASSISTANT_QUERY_KEY_PREFIX,
+  assistantRootQueryKey,
+  assistantScopeQueryKey,
+  assistantSettingsQueryKey,
+  assistantConversationsListQueryKey,
+  assistantConversationMessagesQueryKey
+};

package/src/shared/settingsEvents.js

@@ -0,0 +1,5 @@
+const assistantSettingsEvents = Object.freeze({
+  settingsChanged: "assistant.settings.changed"
+});
+
+export { assistantSettingsEvents };

package/src/shared/streamEvents.js

@@ -0,0 +1,29 @@
+const ASSISTANT_STREAM_EVENT_TYPES = Object.freeze({
+  META: "meta",
+  ASSISTANT_DELTA: "assistant_delta",
+  ASSISTANT_MESSAGE: "assistant_message",
+  TOOL_CALL: "tool_call",
+  TOOL_RESULT: "tool_result",
+  ERROR: "error",
+  DONE: "done"
+});
+
+const STREAM_EVENT_TYPE_SET = new Set(Object.values(ASSISTANT_STREAM_EVENT_TYPES));
+
+function normalizeAssistantStreamEventType(value, fallback = "") {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+
+  if (!STREAM_EVENT_TYPE_SET.has(normalized)) {
+    return fallback;
+  }
+
+  return normalized;
+}
+
+export {
+  ASSISTANT_STREAM_EVENT_TYPES,
+  normalizeAssistantStreamEventType
+};

package/src/shared/support/conversationStatus.js

@@ -0,0 +1,18 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+const ASSISTANT_CONVERSATION_STATUSES = Object.freeze(["active", "completed", "failed", "aborted"]);
+const ASSISTANT_CONVERSATION_STATUS_SET = new Set(ASSISTANT_CONVERSATION_STATUSES);
+
+function normalizeConversationStatus(value, { fallback = "" } = {}) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (ASSISTANT_CONVERSATION_STATUS_SET.has(normalized)) {
+    return normalized;
+  }
+
+  return normalizeText(fallback).toLowerCase();
+}
+
+export {
+  ASSISTANT_CONVERSATION_STATUSES,
+  normalizeConversationStatus
+};

package/src/shared/support/jsonObject.js

@@ -0,0 +1,18 @@
+function parseJsonObject(value) {
+  if (value == null) {
+    return {};
+  }
+
+  try {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+export { parseJsonObject };

package/src/shared/support/positiveInteger.js

@@ -0,0 +1,9 @@
+import { normalizePositiveInteger } from "@jskit-ai/kernel/shared/support/normalize";
+
+function toPositiveInteger(value, fallback = 0) {
+  return normalizePositiveInteger(value, {
+    fallback
+  });
+}
+
+export { toPositiveInteger };

package/test/aiConfigValidation.test.js

@@ -0,0 +1,15 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { normalizeOptionalHttpUrl } from "../src/server/lib/providers/common.js";
+
+test("normalizeOptionalHttpUrl accepts empty values", () => {
+  assert.equal(normalizeOptionalHttpUrl(""), "");
+  assert.equal(normalizeOptionalHttpUrl("   "), "");
+});
+
+test("normalizeOptionalHttpUrl rejects non-http absolute values", () => {
+  assert.throws(
+    () => normalizeOptionalHttpUrl("cd ../89", { context: "assistant AI_BASE_URL" }),
+    /assistant AI_BASE_URL must be an absolute http\(s\) URL\./
+  );
+});

package/test/assistantApiSurfaceHeader.test.js

@@ -0,0 +1,66 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createAssistantApi } from "../src/client/lib/assistantApi.js";
+
+test("assistant api forwards normalized surface header on requests", async () => {
+  const observed = {
+    stream: null,
+    list: null,
+    messages: null
+  };
+
+  const api = createAssistantApi({
+    resolveBasePath: () => "/api/assistant",
+    resolveSurfaceId: () => "AdMiN",
+    async request(url, options = {}) {
+      if (url.includes("/messages")) {
+        observed.messages = { url, options };
+      } else {
+        observed.list = { url, options };
+      }
+      return {};
+    },
+    async requestStream(url, options = {}) {
+      observed.stream = { url, options };
+      return null;
+    }
+  });
+
+  await api.streamChat({
+    messageId: "msg_1",
+    input: "Hello"
+  });
+  await api.listConversations({
+    limit: 5
+  });
+  await api.getConversationMessages(99, {
+    page: 1,
+    pageSize: 5
+  });
+
+  assert.equal(observed.stream?.options?.headers?.["x-jskit-surface"], "admin");
+  assert.equal(observed.list?.options?.headers?.["x-jskit-surface"], "admin");
+  assert.equal(observed.messages?.options?.headers?.["x-jskit-surface"], "admin");
+});
+
+test("assistant api omits surface header when surface id is empty", async () => {
+  const observed = [];
+  const api = createAssistantApi({
+    resolveBasePath: () => "/api/assistant",
+    resolveSurfaceId: () => "",
+    async request(url, options = {}) {
+      observed.push({
+        url,
+        options
+      });
+      return {};
+    },
+    async requestStream(_url, _options = {}) {
+      return null;
+    }
+  });
+
+  await api.listConversations();
+  assert.equal(observed.length, 1);
+  assert.equal(Object.hasOwn(observed[0].options || {}, "headers"), false);
+});