@jskit-ai/assistant 0.1.4

package/src/shared/assistantSettingsResource.js

@@ -0,0 +1,214 @@
+import { Type } from "typebox";
+import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators";
+import { normalizeText } from "@jskit-ai/kernel/shared/actions/textNormalization";
+
+const MAX_SYSTEM_PROMPT_CHARS = 12_000;
+
+function createPromptSchema(promptLabel) {
+  return Type.String({
+    maxLength: MAX_SYSTEM_PROMPT_CHARS,
+    messages: {
+      maxLength: `${promptLabel} must be at most ${MAX_SYSTEM_PROMPT_CHARS} characters.`,
+      default: `${promptLabel} must be valid text.`
+    }
+  });
+}
+
+function createPromptSettingsResource({
+  resourceId = "",
+  fields = [],
+  validationMessage = "Fix invalid values and try again.",
+  saveSuccessMessage = "Saved.",
+  saveErrorMessage = "Unable to save settings."
+} = {}) {
+  const settingsOutputProperties = {};
+  const settingsCreateProperties = {};
+  for (const field of fields) {
+    settingsOutputProperties[field.key] = field.outputSchema;
+    settingsCreateProperties[field.key] =
+      field.required === false ? Type.Optional(field.inputSchema) : field.inputSchema;
+  }
+
+  const settingsOutputSchema = Type.Object(settingsOutputProperties, { additionalProperties: false });
+  const settingsCreateSchema = Type.Object(settingsCreateProperties, { additionalProperties: false });
+  const settingsPatchSchema = Type.Partial(settingsCreateSchema, {
+    additionalProperties: false
+  });
+  const recordSchema = Type.Object(
+    {
+      settings: settingsOutputSchema
+    },
+    { additionalProperties: false }
+  );
+
+  function normalizeInput(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const normalized = {};
+    for (const field of fields) {
+      if (!Object.hasOwn(source, field.key)) {
+        continue;
+      }
+      normalized[field.key] = field.normalizeInput(source[field.key], {
+        payload: source
+      });
+    }
+    return normalized;
+  }
+
+  function normalizeOutput(payload = {}) {
+    const source = normalizeObjectInput(payload);
+    const settingsSource = normalizeObjectInput(source.settings);
+    const settings = {};
+    for (const field of fields) {
+      const rawValue = Object.hasOwn(settingsSource, field.key)
+        ? settingsSource[field.key]
+        : field.resolveDefault({
+            settings: settingsSource
+          });
+      settings[field.key] = field.normalizeOutput(rawValue, {
+        settings: settingsSource
+      });
+    }
+    return {
+      settings
+    };
+  }
+
+  const outputValidator = Object.freeze({
+    schema: recordSchema,
+    normalize: normalizeOutput
+  });
+
+  return Object.freeze({
+    resource: resourceId,
+    messages: {
+      validation: validationMessage,
+      saveSuccess: saveSuccessMessage,
+      saveError: saveErrorMessage
+    },
+    operations: Object.freeze({
+      view: Object.freeze({
+        method: "GET",
+        outputValidator
+      }),
+      create: Object.freeze({
+        method: "POST",
+        bodyValidator: Object.freeze({
+          schema: settingsCreateSchema,
+          normalize: normalizeInput
+        }),
+        outputValidator
+      }),
+      replace: Object.freeze({
+        method: "PUT",
+        bodyValidator: Object.freeze({
+          schema: settingsCreateSchema,
+          normalize: normalizeInput
+        }),
+        outputValidator
+      }),
+      patch: Object.freeze({
+        method: "PATCH",
+        bodyValidator: Object.freeze({
+          schema: settingsPatchSchema,
+          normalize: normalizeInput
+        }),
+        outputValidator
+      })
+    })
+  });
+}
+
+function createFieldRegistry(scopeLabel) {
+  const fields = [];
+
+  function defineField(field = {}) {
+    const key = normalizeText(field.key);
+    if (!key) {
+      throw new TypeError(`${scopeLabel}.defineField requires field.key.`);
+    }
+    if (fields.some((entry) => entry.key === key)) {
+      throw new Error(`${scopeLabel}.defineField duplicate key: ${key}`);
+    }
+    if (!field.inputSchema || typeof field.inputSchema !== "object") {
+      throw new TypeError(`${scopeLabel}.defineField("${key}") requires inputSchema.`);
+    }
+    if (!field.outputSchema || typeof field.outputSchema !== "object") {
+      throw new TypeError(`${scopeLabel}.defineField("${key}") requires outputSchema.`);
+    }
+    if (typeof field.normalizeInput !== "function") {
+      throw new TypeError(`${scopeLabel}.defineField("${key}") requires normalizeInput.`);
+    }
+    if (typeof field.normalizeOutput !== "function") {
+      throw new TypeError(`${scopeLabel}.defineField("${key}") requires normalizeOutput.`);
+    }
+    if (typeof field.resolveDefault !== "function") {
+      throw new TypeError(`${scopeLabel}.defineField("${key}") requires resolveDefault.`);
+    }
+
+    fields.push({
+      key,
+      required: field.required !== false,
+      inputSchema: field.inputSchema,
+      outputSchema: field.outputSchema,
+      normalizeInput: field.normalizeInput,
+      normalizeOutput: field.normalizeOutput,
+      resolveDefault: field.resolveDefault
+    });
+  }
+
+  return {
+    fields,
+    defineField
+  };
+}
+
+const assistantConsoleSettingsFields = (() => {
+  const registry = createFieldRegistry("assistantConsoleSettingsFields");
+  const { fields, defineField } = registry;
+  defineField({
+    key: "workspaceSurfacePrompt",
+    required: true,
+    inputSchema: createPromptSchema("Workspace surface system prompt"),
+    outputSchema: Type.String({ maxLength: MAX_SYSTEM_PROMPT_CHARS }),
+    normalizeInput: (value) => String(value || ""),
+    normalizeOutput: (value) => String(value || ""),
+    resolveDefault: () => ""
+  });
+  return fields;
+})();
+
+const assistantWorkspaceSettingsFields = (() => {
+  const registry = createFieldRegistry("assistantWorkspaceSettingsFields");
+  const { fields, defineField } = registry;
+  defineField({
+    key: "appSurfacePrompt",
+    required: true,
+    inputSchema: createPromptSchema("App surface system prompt"),
+    outputSchema: Type.String({ maxLength: MAX_SYSTEM_PROMPT_CHARS }),
+    normalizeInput: (value) => String(value || ""),
+    normalizeOutput: (value) => String(value || ""),
+    resolveDefault: () => ""
+  });
+  return fields;
+})();
+
+const assistantConsoleSettingsResource = createPromptSettingsResource({
+  resourceId: "assistantConsoleSettings",
+  fields: assistantConsoleSettingsFields,
+  saveSuccessMessage: "Assistant console settings updated.",
+  saveErrorMessage: "Unable to update assistant console settings."
+});
+
+const assistantWorkspaceSettingsResource = createPromptSettingsResource({
+  resourceId: "assistantWorkspaceSettings",
+  fields: assistantWorkspaceSettingsFields,
+  saveSuccessMessage: "Assistant workspace settings updated.",
+  saveErrorMessage: "Unable to update assistant workspace settings."
+});
+
+export {
+  MAX_SYSTEM_PROMPT_CHARS,
+  assistantConsoleSettingsResource,
+  assistantWorkspaceSettingsResource
+};

package/src/shared/index.js

@@ -0,0 +1,39 @@
+export {
+  ASSISTANT_API_RELATIVE_PATH,
+  resolveAssistantApiBasePath,
+  resolveAssistantWorkspaceApiBasePath,
+  buildAssistantWorkspaceApiPath
+} from "./assistantPaths.js";
+
+export {
+  ASSISTANT_QUERY_KEY_PREFIX,
+  assistantRootQueryKey,
+  assistantWorkspaceScopeQueryKey,
+  assistantConversationsListQueryKey,
+  assistantConversationMessagesQueryKey
+} from "./queryKeys.js";
+
+export {
+  ASSISTANT_STREAM_EVENT_TYPES,
+  ASSISTANT_TRANSCRIPT_CHANGED_EVENT,
+  normalizeAssistantStreamEventType
+} from "./streamEvents.js";
+
+export {
+  MAX_INPUT_CHARS,
+  MAX_HISTORY_MESSAGES,
+  assistantResource
+} from "./assistantResource.js";
+
+export {
+  MAX_SYSTEM_PROMPT_CHARS,
+  assistantConsoleSettingsResource,
+  assistantWorkspaceSettingsResource
+} from "./assistantSettingsResource.js";
+
+export {
+  ASSISTANT_CONSOLE_SETTINGS_CHANGED_EVENT,
+  ASSISTANT_WORKSPACE_SETTINGS_CHANGED_EVENT
+} from "./settingsEvents.js";
+
+export { toPositiveInteger } from "./support/positiveInteger.js";

package/src/shared/queryKeys.js

@@ -0,0 +1,69 @@
+const ASSISTANT_QUERY_KEY_PREFIX = Object.freeze(["assistant"]);
+
+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 normalizeWorkspaceScope({ workspaceSlug = "", workspaceId = 0 } = {}) {
+  const normalizedWorkspaceId = normalizePositiveInteger(workspaceId, 0);
+  if (normalizedWorkspaceId > 0) {
+    return `id:${normalizedWorkspaceId}`;
+  }
+
+  return `slug:${normalizeWorkspaceSlug(workspaceSlug)}`;
+}
+
+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 assistantWorkspaceScopeQueryKey(workspaceScope = {}) {
+  return [...assistantRootQueryKey(), normalizeWorkspaceScope(workspaceScope)];
+}
+
+function assistantConversationsListQueryKey(workspaceScope = {}, { limit = 20, status = "" } = {}) {
+  return [
+    ...assistantWorkspaceScopeQueryKey(workspaceScope),
+    "conversations",
+    "list",
+    normalizePositiveInteger(limit, 20),
+    normalizeStatus(status)
+  ];
+}
+
+function assistantConversationMessagesQueryKey(workspaceScope = {}, conversationId, { page = 1, pageSize = 200 } = {}) {
+  return [
+    ...assistantWorkspaceScopeQueryKey(workspaceScope),
+    "conversations",
+    normalizeConversationId(conversationId),
+    "messages",
+    normalizePositiveInteger(page, 1),
+    normalizePositiveInteger(pageSize, 200)
+  ];
+}
+
+export {
+  ASSISTANT_QUERY_KEY_PREFIX,
+  assistantRootQueryKey,
+  assistantWorkspaceScopeQueryKey,
+  assistantConversationsListQueryKey,
+  assistantConversationMessagesQueryKey
+};

package/src/shared/settingsEvents.js

@@ -0,0 +1,7 @@
+const ASSISTANT_CONSOLE_SETTINGS_CHANGED_EVENT = "assistant.console.settings.changed";
+const ASSISTANT_WORKSPACE_SETTINGS_CHANGED_EVENT = "assistant.workspace.settings.changed";
+
+export {
+  ASSISTANT_CONSOLE_SETTINGS_CHANGED_EVENT,
+  ASSISTANT_WORKSPACE_SETTINGS_CHANGED_EVENT
+};

package/src/shared/streamEvents.js

@@ -0,0 +1,31 @@
+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 ASSISTANT_TRANSCRIPT_CHANGED_EVENT = "assistant.transcript.changed";
+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,
+  ASSISTANT_TRANSCRIPT_CHANGED_EVENT,
+  normalizeAssistantStreamEventType
+};

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/templates/migrations/assistant_settings_initial.cjs

@@ -0,0 +1,39 @@
+// JSKIT_MIGRATION_ID: assistant-settings-initial-schema
+
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.up = async function up(knex) {
+  const hasConsolePromptColumn = await knex.schema.hasColumn("console_settings", "assistant_workspace_surface_prompt");
+  if (!hasConsolePromptColumn) {
+    await knex.schema.alterTable("console_settings", (table) => {
+      table.text("assistant_workspace_surface_prompt").notNullable().defaultTo("");
+    });
+  }
+
+  const hasWorkspacePromptColumn = await knex.schema.hasColumn("workspace_settings", "assistant_app_surface_prompt");
+  if (!hasWorkspacePromptColumn) {
+    await knex.schema.alterTable("workspace_settings", (table) => {
+      table.text("assistant_app_surface_prompt").notNullable().defaultTo("");
+    });
+  }
+};
+
+/**
+ * @param {import('knex').Knex} knex
+ */
+exports.down = async function down(knex) {
+  const hasWorkspacePromptColumn = await knex.schema.hasColumn("workspace_settings", "assistant_app_surface_prompt");
+  if (hasWorkspacePromptColumn) {
+    await knex.schema.alterTable("workspace_settings", (table) => {
+      table.dropColumn("assistant_app_surface_prompt");
+    });
+  }
+
+  const hasConsolePromptColumn = await knex.schema.hasColumn("console_settings", "assistant_workspace_surface_prompt");
+  if (hasConsolePromptColumn) {
+    await knex.schema.alterTable("console_settings", (table) => {
+      table.dropColumn("assistant_workspace_surface_prompt");
+    });
+  }
+};

package/templates/migrations/assistant_transcripts_initial.cjs

@@ -0,0 +1,51 @@
+// JSKIT_MIGRATION_ID: assistant_transcripts_initial
+
+exports.up = async function up(knex) {
+  const hasConversationsTable = await knex.schema.hasTable("ai_conversations");
+  if (!hasConversationsTable) {
+    await knex.schema.createTable("ai_conversations", (table) => {
+      table.increments("id").unsigned().primary();
+      table.integer("workspace_id").unsigned().notNullable().index();
+      table.integer("created_by_user_id").unsigned().nullable().index();
+      table.string("title", 160).notNullable().defaultTo("New conversation");
+      table.string("status", 32).notNullable().defaultTo("active");
+      table.string("provider", 64).notNullable().defaultTo("");
+      table.string("model", 128).notNullable().defaultTo("");
+      table.string("surface_id", 32).notNullable().defaultTo("admin");
+      table.integer("message_count").unsigned().notNullable().defaultTo(0);
+      table.text("metadata_json").nullable();
+      table.timestamp("started_at").notNullable().defaultTo(knex.fn.now());
+      table.timestamp("ended_at").nullable();
+      table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+      table.timestamp("updated_at").notNullable().defaultTo(knex.fn.now());
+
+      table.index(["workspace_id", "started_at"], "idx_ai_conversations_workspace_started_at");
+      table.index(["workspace_id", "created_by_user_id"], "idx_ai_conversations_workspace_creator");
+    });
+  }
+
+  const hasMessagesTable = await knex.schema.hasTable("ai_messages");
+  if (!hasMessagesTable) {
+    await knex.schema.createTable("ai_messages", (table) => {
+      table.increments("id").unsigned().primary();
+      table.integer("conversation_id").unsigned().notNullable().references("id").inTable("ai_conversations").onDelete("CASCADE");
+      table.integer("workspace_id").unsigned().notNullable().index();
+      table.integer("seq").unsigned().notNullable();
+      table.string("role", 32).notNullable();
+      table.string("kind", 32).notNullable().defaultTo("chat");
+      table.string("client_message_id", 128).notNullable().defaultTo("");
+      table.integer("actor_user_id").unsigned().nullable().index();
+      table.text("content_text").nullable();
+      table.text("metadata_json").nullable();
+      table.timestamp("created_at").notNullable().defaultTo(knex.fn.now());
+
+      table.unique(["conversation_id", "seq"], "uq_ai_messages_conversation_seq");
+      table.index(["conversation_id", "created_at"], "idx_ai_messages_conversation_created_at");
+    });
+  }
+};
+
+exports.down = async function down(knex) {
+  await knex.schema.dropTableIfExists("ai_messages");
+  await knex.schema.dropTableIfExists("ai_conversations");
+};

package/templates/src/pages/admin/workspace/assistant/index.vue

@@ -0,0 +1,7 @@
+<template>
+  <AssistantWorkspaceClientElement />
+</template>
+
+<script setup>
+import { AssistantWorkspaceClientElement } from "@jskit-ai/assistant/client";
+</script>

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,64 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createAssistantWorkspaceApi } from "../src/client/lib/assistantApi.js";
+
+test("assistant workspace api forwards normalized surface header on requests", async () => {
+  const observed = {
+    stream: null,
+    list: null,
+    messages: null
+  };
+
+  const api = createAssistantWorkspaceApi({
+    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("acme", {
+    messageId: "msg_1",
+    input: "Hello"
+  });
+  await api.listConversations("acme", {
+    limit: 5
+  });
+  await api.getConversationMessages("acme", 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 workspace api omits surface header when surface id is empty", async () => {
+  const observed = [];
+  const api = createAssistantWorkspaceApi({
+    resolveSurfaceId: () => "",
+    async request(url, options = {}) {
+      observed.push({
+        url,
+        options
+      });
+      return {};
+    },
+    async requestStream(_url, _options = {}) {
+      return null;
+    }
+  });
+
+  await api.listConversations("acme");
+  assert.equal(observed.length, 1);
+  assert.equal(Object.hasOwn(observed[0].options || {}, "headers"), false);
+});

package/test/assistantResource.test.js

@@ -0,0 +1,53 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Check } from "typebox/value";
+import { assistantResource } from "../src/shared/assistantResource.js";
+
+test("assistant output schemas accept normalized paginated payloads", () => {
+  const conversationsListSchema = assistantResource.operations.conversationsList.outputValidator.schema;
+  const conversationMessagesSchema = assistantResource.operations.conversationMessagesList.outputValidator.schema;
+
+  const conversationsPayload = {
+    items: [],
+    nextCursor: null
+  };
+
+  const messagesPayload = {
+    conversation: {
+      id: 1,
+      workspaceId: 10,
+      workspaceSlug: "acme",
+      workspaceName: "Acme",
+      title: "Conversation",
+      createdByUserId: 7,
+      createdByUserDisplayName: "Merc",
+      createdByUserEmail: "merc@example.com",
+      status: "active",
+      provider: "openai",
+      model: "gpt-4.1",
+      surfaceId: "admin",
+      startedAt: "2026-03-16T10:00:00.000Z",
+      endedAt: null,
+      messageCount: 2,
+      metadata: {},
+      createdAt: "2026-03-16T10:00:00.000Z",
+      updatedAt: "2026-03-16T10:01:00.000Z"
+    },
+    entries: [],
+    page: 1,
+    pageSize: 200,
+    total: 0,
+    totalPages: 1
+  };
+
+  assert.equal(Check(conversationsListSchema, conversationsPayload), true);
+  assert.equal(Check(conversationMessagesSchema, messagesPayload), true);
+});
+
+test("assistant conversation message params accept numeric path strings and normalize to integer", () => {
+  const paramsValidator = assistantResource.operations.conversationMessagesList.paramsValidator;
+  assert.equal(Check(paramsValidator.schema, { conversationId: "2" }), true);
+  assert.deepEqual(paramsValidator.normalize({ conversationId: "2" }), {
+    conversationId: 2
+  });
+});

package/test/assistantSettingsResource.test.js

@@ -0,0 +1,48 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Check } from "typebox/value";
+import { validateOperationSection } from "@jskit-ai/http-runtime/shared/validators/operationValidation";
+import {
+  assistantConsoleSettingsResource,
+  assistantWorkspaceSettingsResource
+} from "../src/shared/assistantSettingsResource.js";
+
+test("assistant settings resources expose valid output schemas", () => {
+  const consoleSchema = assistantConsoleSettingsResource.operations.view.outputValidator.schema;
+  const workspaceSchema = assistantWorkspaceSettingsResource.operations.view.outputValidator.schema;
+
+  assert.equal(
+    Check(consoleSchema, {
+      settings: {
+        workspaceSurfacePrompt: ""
+      }
+    }),
+    true
+  );
+  assert.equal(
+    Check(workspaceSchema, {
+      settings: {
+        appSurfacePrompt: ""
+      }
+    }),
+    true
+  );
+});
+
+test("assistant settings patch normalizer preserves omitted fields", () => {
+  const consolePatch = validateOperationSection({
+    operation: assistantConsoleSettingsResource.operations.patch,
+    section: "bodyValidator",
+    value: {}
+  });
+  const workspacePatch = validateOperationSection({
+    operation: assistantWorkspaceSettingsResource.operations.patch,
+    section: "bodyValidator",
+    value: {}
+  });
+
+  assert.equal(consolePatch.ok, true);
+  assert.equal(workspacePatch.ok, true);
+  assert.deepEqual(consolePatch.value, {});
+  assert.deepEqual(workspacePatch.value, {});
+});