@jskit-ai/assistant-runtime 0.2.8 → 0.2.10

package/src/server/repositories/conversationsRepository.js

@@ -5,7 +5,6 @@ import {
   applyWorkspaceScope,
   normalizeDbWorkspaceId,
   normalizeInputRecordId,
-  normalizeWorkspaceId,
   parseJsonObject,
   resolveInsertedId,
   stringifyJsonObject,
@@ -58,10 +57,8 @@ function createConversationBaseQuery(client) {
   return client(`${assistantRuntimeConfig.conversationsTable} as c`).select("c.*");
 }
 
+/** @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} knex */
 function createRepository(knex) {
-  if (!knex || typeof knex !== "function") {
-    throw new Error("createConversationsRepository requires knex client.");
-  }
   const withTransaction = createWithTransaction(knex);
 
   async function findById(conversationId, options = {}) {
@@ -70,7 +67,7 @@ function createRepository(knex) {
       return null;
     }
 
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     if (options.forUpdate === true) {
       if (!options.trx) throw new TypeError("Locking a conversation requires its database transaction.");
       // Acquire the write reservation before reading, including SQLite where
@@ -96,7 +93,7 @@ function createRepository(knex) {
       return null;
     }
 
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     if (options.forUpdate === true) await findById(normalizedConversationId, options);
     const query = createConversationBaseQuery(client)
       .where("c.id", normalizedConversationId)
@@ -109,11 +106,11 @@ function createRepository(knex) {
   }
 
   async function create(payload = {}, options = {}) {
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const now = new Date();
     const surfaceId = normalizeRequiredSurfaceId(payload.surfaceId);
     const insertResult = await client(assistantRuntimeConfig.conversationsTable).insert({
-      workspace_id: normalizeWorkspaceId(payload.workspaceId),
+      workspace_id: normalizeInputRecordId(payload.workspaceId),
       created_by_user_id: normalizeInputRecordId(payload.createdByUserId),
       title: normalizeText(payload.title) || DEFAULT_CONVERSATION_TITLE,
       status: normalizeText(payload.status).toLowerCase() || "active",
@@ -143,7 +140,7 @@ function createRepository(knex) {
       return null;
     }
 
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const updatePatch = {};
 
     if (Object.hasOwn(patch, "title")) {
@@ -183,6 +180,32 @@ function createRepository(knex) {
     });
   }
 
+  // The transcript's own state stays out of conversation records, which reach the browser.
+  async function readTranscriptState(conversationId, options = {}) {
+    const id = normalizeInputRecordId(conversationId);
+    if (!id) return null;
+    const client = options.trx || knex;
+    const row = await client(assistantRuntimeConfig.conversationsTable).where({ id })
+      .first("summary_text", "summary_through_turn_id", "transcript_revision");
+    if (!row) return null;
+    return {
+      revision: row.transcript_revision || "",
+      summary: row.summary_text == null ? null
+        : { text: String(row.summary_text), throughTurnId: String(row.summary_through_turn_id || "") }
+    };
+  }
+
+  async function writeTranscriptState(conversationId, { revision, summary }, options = {}) {
+    const id = normalizeInputRecordId(conversationId);
+    if (!id) throw new TypeError("writeTranscriptState requires conversationId.");
+    const client = options.trx || knex;
+    await client(assistantRuntimeConfig.conversationsTable).where({ id }).update({
+      transcript_revision: revision,
+      summary_text: summary ? summary.text : null,
+      summary_through_turn_id: summary ? summary.throughTurnId : null
+    });
+  }
+
   async function listForActorScope(
     { workspaceId = null, actorUserId = null, surfaceId = "", pagination = {}, filters = {} } = {},
     options = {}
@@ -196,7 +219,7 @@ function createRepository(knex) {
       };
     }
 
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const { cursor, limit } = normalizeCursorPagination(pagination);
     let query = createConversationBaseQuery(client)
       .where("c.created_by_user_id", normalizedActorUserId)
@@ -239,6 +262,8 @@ function createRepository(knex) {
     create,
     updateById,
     listForActorScope,
+    readTranscriptState,
+    writeTranscriptState,
     transaction
   });
 }

package/src/server/repositories/messagesRepository.js

@@ -4,7 +4,6 @@ import {
   applyWorkspaceScope,
   normalizeDbWorkspaceId,
   normalizeInputRecordId,
-  normalizeWorkspaceId,
   parseJsonObject,
   resolveInsertedId,
   stringifyJsonObject,
@@ -55,10 +54,8 @@ async function resolveNextSequence(client, conversationId) {
   return maxSeq + 1;
 }
 
+/** @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} knex */
 function createRepository(knex) {
-  if (!knex || typeof knex !== "function") {
-    throw new Error("createMessagesRepository requires knex client.");
-  }
   const withTransaction = createWithTransaction(knex);
 
   async function findById(messageId, options = {}) {
@@ -67,7 +64,7 @@ function createRepository(knex) {
       return null;
     }
 
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const row = await client(assistantRuntimeConfig.messagesTable)
       .where({ id: normalizedMessageId })
       .first();
@@ -76,7 +73,7 @@ function createRepository(knex) {
   }
 
   async function create(payload = {}, options = {}) {
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const conversationId = normalizeInputRecordId(payload.conversationId);
     if (!conversationId) {
       throw new TypeError("messagesRepository.create requires conversationId.");
@@ -86,7 +83,7 @@ function createRepository(knex) {
     const seq = Number.isInteger(providedSeq) && providedSeq > 0 ? providedSeq : (await resolveNextSequence(client, conversationId));
     const insertResult = await client(assistantRuntimeConfig.messagesTable).insert({
       conversation_id: conversationId,
-      workspace_id: normalizeWorkspaceId(payload.workspaceId),
+      workspace_id: normalizeInputRecordId(payload.workspaceId),
       seq,
       role: normalizeText(payload.role).toLowerCase(),
       kind: normalizeText(payload.kind).toLowerCase() || "chat",
@@ -112,7 +109,7 @@ function createRepository(knex) {
       return 0;
     }
 
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const query = client(assistantRuntimeConfig.messagesTable).where({
       conversation_id: normalizedConversationId
     });
@@ -126,7 +123,7 @@ function createRepository(knex) {
   async function updateById(messageId, patch = {}, options = {}) {
     const id = normalizeInputRecordId(messageId);
     if (!id) return null;
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const update = {};
     if (Object.hasOwn(patch, "contentText")) update.content_text = patch.contentText == null ? null : String(patch.contentText);
     if (Object.hasOwn(patch, "metadata")) update.metadata_json = stringifyJsonObject(patch.metadata);
@@ -140,7 +137,7 @@ function createRepository(knex) {
       return [];
     }
 
-    const client = options?.trx || knex;
+    const client = options.trx || knex;
     const { page, pageSize } = normalizePagination(pagination);
     const offset = (page - 1) * pageSize;
 
@@ -157,6 +154,12 @@ function createRepository(knex) {
     return rows.map(mapMessageRow);
   }
 
+  async function lastSequence(conversationId, options = {}) {
+    const normalizedConversationId = normalizeInputRecordId(conversationId);
+    if (!normalizedConversationId) return 0;
+    return (await resolveNextSequence(options.trx || knex, normalizedConversationId)) - 1;
+  }
+
   async function transaction(callback) {
     return runInTransaction(knex, callback);
   }
@@ -168,6 +171,7 @@ function createRepository(knex) {
     updateById,
     countByConversationScope,
     listByConversationScope,
+    lastSequence,
     transaction
   });
 }

package/src/server/repositories/repositoryPersistenceUtils.js

@@ -3,10 +3,6 @@ import { normalizeDbRecordId } from "@jskit-ai/database-runtime/shared/repositor
 import { normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 import { parseJsonObject } from "@jskit-ai/assistant-core/shared";
 
-function normalizeWorkspaceId(value) {
-  return normalizeRecordId(value, { fallback: null });
-}
-
 function normalizeDbWorkspaceId(value) {
   return normalizeDbRecordId(value, { fallback: null });
 }
@@ -16,7 +12,7 @@ function normalizeInputRecordId(value) {
 }
 
 function applyWorkspaceScope(query, columnName, workspaceId) {
-  const normalizedWorkspaceId = normalizeWorkspaceId(workspaceId);
+  const normalizedWorkspaceId = normalizeInputRecordId(workspaceId);
   if (normalizedWorkspaceId) {
     return query.where(columnName, normalizedWorkspaceId);
   }
@@ -54,7 +50,6 @@ export {
   applyWorkspaceScope,
   normalizeDbWorkspaceId,
   normalizeInputRecordId,
-  normalizeWorkspaceId,
   parseJsonObject,
   stringifyJsonObject,
   toIso,

package/src/server/repositories/turnRequestsRepository.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { assistantRuntimeConfig } from "../../shared/assistantRuntimeConfig.js";
 
+/** @param {import("@jskit-ai/database-runtime/server/types").RuntimeKnex} knex */
 function createRepository(knex) {
   const table = assistantRuntimeConfig.turnRequestsTable;
 
@@ -29,7 +30,11 @@ function createRepository(knex) {
     if (!changed) throw new Error("Assistant request ownership was lost.");
   }
 
-  return Object.freeze({ find, claim, update });
+  return Object.freeze({
+    find,
+    claim,
+    update
+  });
 }
 
 export { createRepository };

package/src/server/services/assistantConfigService.js

@@ -2,22 +2,24 @@ import { AppError, requireAuth } from "@jskit-ai/kernel/server/runtime";
 import { normalizeObject, normalizeRecordId } from "@jskit-ai/kernel/shared/support/normalize";
 import { requireAssistantSurface } from "../support/assistantSurface.js";
 
+/** @typedef {import("../types.js").AssistantConfigRepository} AssistantConfigRepository */
+/** @typedef {import("../types.js").WorkspaceScopeSupport} WorkspaceScopeSupport */
+
+/**
+ * An assistant surface's saved settings: who may read and change them, and the
+ * system prompt they give the surface's conversations.
+ * @param {object} dependencies
+ * @param {AssistantConfigRepository} dependencies.assistantConfigRepository
+ * @param {import("@jskit-ai/console-core/server/types").ConsoleService | null} dependencies.consoleService The console access service, when the console is installed.
+ * @param {Record<string, any>} dependencies.appConfig
+ * @param {WorkspaceScopeSupport | null} dependencies.workspaceScopeSupport
+ */
 function createService({
   assistantConfigRepository,
-  consoleService = null,
-  appConfig = {},
-  workspaceScopeSupport = null
-} = {}) {
-  if (!assistantConfigRepository || typeof assistantConfigRepository.findByScope !== "function") {
-    throw new Error("assistantConfigService requires assistantConfigRepository.findByScope().");
-  }
-  if (typeof assistantConfigRepository.upsertByScope !== "function") {
-    throw new Error("assistantConfigService requires assistantConfigRepository.upsertByScope().");
-  }
-  if (typeof assistantConfigRepository.createDefaultRecord !== "function") {
-    throw new Error("assistantConfigService requires assistantConfigRepository.createDefaultRecord().");
-  }
-
+  consoleService,
+  appConfig,
+  workspaceScopeSupport
+}) {
   async function requireSettingsAccess(assistantSurface, context = {}, { mode = "read" } = {}) {
     requireAuth({ context }, {
       require: "authenticated"
@@ -43,7 +45,7 @@ function createService({
       return;
     }
 
-    if (!consoleService || typeof consoleService.requireConsoleOwner !== "function") {
+    if (!consoleService) {
       throw new Error("assistantConfigService requires consoleService.requireConsoleOwner() for console-owner settings surfaces.");
     }
 
@@ -55,7 +57,7 @@ function createService({
       return null;
     }
 
-    if (!workspaceScopeSupport || typeof workspaceScopeSupport.resolveWorkspace !== "function") {
+    if (!workspaceScopeSupport) {
       throw new Error("assistant.config.service requires workspace server scope support for workspace-scoped settings.");
     }
 
@@ -69,12 +71,12 @@ function createService({
   }
 
   async function getSettings(input = {}, options = {}) {
-    const assistantSurface = requireAssistantSurface(appConfig, input?.targetSurfaceId);
-    await requireSettingsAccess(assistantSurface, options?.context, {
+    const assistantSurface = requireAssistantSurface(appConfig, input.targetSurfaceId);
+    await requireSettingsAccess(assistantSurface, options.context, {
       mode: "read"
     });
 
-    const workspaceId = resolveConfigWorkspaceId(assistantSurface, null, input, options?.context);
+    const workspaceId = resolveConfigWorkspaceId(assistantSurface, null, input, options.context);
     const existing = await assistantConfigRepository.findByScope({
       targetSurfaceId: assistantSurface.targetSurfaceId,
       workspaceId
@@ -87,12 +89,12 @@ function createService({
   }
 
   async function updateSettings(input = {}, patch = {}, options = {}) {
-    const assistantSurface = requireAssistantSurface(appConfig, input?.targetSurfaceId);
-    await requireSettingsAccess(assistantSurface, options?.context, {
+    const assistantSurface = requireAssistantSurface(appConfig, input.targetSurfaceId);
+    await requireSettingsAccess(assistantSurface, options.context, {
       mode: "write"
     });
 
-    const workspaceId = resolveConfigWorkspaceId(assistantSurface, null, input, options?.context);
+    const workspaceId = resolveConfigWorkspaceId(assistantSurface, null, input, options.context);
     const normalizedPatch = normalizeObject(patch);
 
     return assistantConfigRepository.upsertByScope({
@@ -102,7 +104,7 @@ function createService({
     });
   }
 
-  async function resolveSystemPrompt(assistantSurface, workspace = null, _options = {}, serviceOptions = {}) {
+  async function resolveSystemPrompt(assistantSurface, workspace = null, _options = {}, serviceOptions) {
     const resolvedAssistantSurface = requireAssistantSurface(appConfig, assistantSurface?.targetSurfaceId);
     const workspaceId = resolveConfigWorkspaceId(
       resolvedAssistantSurface,

package/src/server/services/chatService.js

@@ -1,43 +1,14 @@
 import { isDeepStrictEqual } from "node:util";
+import { resolveActor } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { AppError, createValidationError } from "@jskit-ai/kernel/server/runtime";
 import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { resolveWorkspaceSlug } from "@jskit-ai/assistant-core/server";
 import { conversationAttachmentIds } from "@jskit-ai/assistant-core/server/conversation";
-import { ASSISTANT_STREAM_EVENT_TYPES, MAX_HISTORY_MESSAGES, MAX_INPUT_CHARS, isAssistantProgressOnlyText } from "@jskit-ai/assistant-core/shared";
+import { ASSISTANT_STREAM_EVENT_TYPES, MAX_INPUT_CHARS } from "@jskit-ai/assistant-core/shared";
 import { errorMessageFields, exposedAppErrorDetails, errorStatus } from "../support/assistantErrors.js";
 import { requireAssistantSurface } from "../support/assistantSurface.js";
-import { ASSISTANT_STREAM_WRITER_METHODS } from "../support/assistantStreamWriter.js";
 
-const CLOCK_INSTRUCTION = "For current or relative date and time questions, first use any available authoritative workspace clock action; never infer the current date or time from model knowledge.";
-
-function normalizeConversationId(value) {
-  return normalizeRecordId(value, { fallback: null });
-}
-
-function normalizeHistory(history = []) {
-  const source = Array.isArray(history) ? history : [];
-  return source
-    .slice(0, MAX_HISTORY_MESSAGES)
-    .map((entry) => {
-      const item = normalizeObject(entry);
-      const role = normalizeText(item.role).toLowerCase();
-      if (role !== "user" && role !== "assistant") {
-        return null;
-      }
-
-      const content = normalizeText(item.content).slice(0, MAX_INPUT_CHARS);
-      if (!content || (role === "assistant" && isAssistantProgressOnlyText(content))) {
-        return null;
-      }
-
-      return {
-        role,
-        content,
-        attachmentIds: role === "user" ? item.attachmentIds : []
-      };
-    })
-    .filter(Boolean);
-}
+const CLOCK_INSTRUCTION = "For current or relative date and time questions, use the current time in the system's state note, or an available authoritative workspace clock action for another time zone; never infer the current date or time from model knowledge.";
 
 function normalizeStreamInput(payload = {}) {
   const source = normalizeObject(payload);
@@ -56,17 +27,12 @@ function normalizeStreamInput(payload = {}) {
 
   return {
     messageId,
-    conversationId: normalizeConversationId(source.conversationId),
+    conversationId: normalizeRecordId(source.conversationId, { fallback: null }),
     input,
-    attachmentIds: source.attachmentIds,
-    history: normalizeHistory(source.history)
+    attachmentIds: source.attachmentIds
   };
 }
 
-function hasStreamWriter(streamWriter) {
-  return ASSISTANT_STREAM_WRITER_METHODS.every(name => typeof streamWriter?.[name] === "function");
-}
-
 // A saved failure keeps its translation fields, except where the kernel would
 // withhold them, so a replay shows the same message in the user's language.
 function savedMessageFields(error) {
@@ -110,7 +76,12 @@ function buildToolContractLine(toolDescriptor = {}) {
   return `${name}: input=${toCompactJson(inputSchema)} output=${toCompactJson(outputSchema, "null")}`;
 }
 
-function buildSystemPrompt({ targetSurfaceId = "", toolDescriptors = [], workspaceSlug = "", customSystemPrompt = "" } = {}) {
+/**
+ * The system prompt of a surface's turn: the surface, its workspace, the tools it
+ * offers and the surface's own instructions.
+ * @param {{ targetSurfaceId?: string, toolDescriptors: Array<{ name: string, parameters?: unknown, outputSchema?: unknown }>, workspaceSlug?: string, customSystemPrompt?: string }} prompt
+ */
+function buildSystemPrompt({ targetSurfaceId = "", toolDescriptors, workspaceSlug = "", customSystemPrompt = "" }) {
   const toolSummary = toolDescriptors.length > 0
     ? `Available tools: ${toolDescriptors.map((entry) => entry.name).join(", ")}.`
     : "No tools are currently available for this user/session.";
@@ -161,6 +132,29 @@ function buildAssistantActionContext(context = {}, assistantSurface = {}) {
   };
 }
 
+/** @typedef {import("../types.js").AssistantAiClientFactory} AssistantAiClientFactory */
+/** @typedef {import("../types.js").AssistantAttachments} AssistantAttachments */
+/** @typedef {import("../types.js").AssistantConfigService} AssistantConfigService */
+/** @typedef {import("../types.js").ConversationRuntime} ConversationRuntime */
+/** @typedef {import("../types.js").SurfaceAwareToolCatalog} SurfaceAwareToolCatalog */
+/** @typedef {import("../types.js").TranscriptService} TranscriptService */
+/** @typedef {import("../types.js").TurnRequestsRepository} TurnRequestsRepository */
+/** @typedef {import("../types.js").WorkspaceScopeSupport} WorkspaceScopeSupport */
+
+/**
+ * The chat stream and transcripts of the package's own tables. Each chat turn is
+ * recorded once per message id, so a repeated request replays its saved outcome.
+ * @param {object} dependencies
+ * @param {ConversationRuntime} dependencies.conversationRuntime
+ * @param {AssistantAiClientFactory} dependencies.aiClientFactory
+ * @param {TurnRequestsRepository} dependencies.turnRequests
+ * @param {AssistantAttachments | null} [dependencies.attachments]
+ * @param {TranscriptService} dependencies.transcriptService
+ * @param {SurfaceAwareToolCatalog} dependencies.serviceToolCatalog
+ * @param {AssistantConfigService} dependencies.assistantConfigService
+ * @param {Record<string, any>} dependencies.appConfig
+ * @param {WorkspaceScopeSupport | null} [dependencies.workspaceScopeSupport]
+ */
 function createChatService({
   conversationRuntime,
   aiClientFactory,
@@ -169,21 +163,15 @@ function createChatService({
   transcriptService,
   serviceToolCatalog,
   assistantConfigService,
-  appConfig = {},
-  workspaceScopeSupport = null
-} = {}) {
-  if (!aiClientFactory || typeof aiClientFactory.resolveClient !== "function" || !turnRequests || !transcriptService || !serviceToolCatalog || !assistantConfigService) {
-    throw new Error(
-      "createChatService requires aiClientFactory.resolveClient(), turnRequests, transcriptService, serviceToolCatalog, and assistantConfigService."
-    );
-  }
-
+  appConfig,
+  workspaceScopeSupport
+}) {
   function resolveRuntimeWorkspace(assistantSurface, context = {}, input = {}) {
     if (assistantSurface?.runtimeSurfaceRequiresWorkspace !== true) {
       return null;
     }
 
-    if (!workspaceScopeSupport || typeof workspaceScopeSupport.resolveWorkspace !== "function") {
+    if (!workspaceScopeSupport) {
       throw new Error("assistant.chat.service requires workspace server scope support for workspace-scoped assistant surfaces.");
     }
 
@@ -243,17 +231,23 @@ function createChatService({
     await turns.releasing;
   }
 
-  async function streamChat(payload = {}, options = {}) {
-    const assistantSurface = requireAssistantSurface(appConfig, payload?.targetSurfaceId);
+  /**
+   * Streams one chat turn through its writer, or replays the saved turn with the same message id.
+   * @param {object} payload The validated chat stream input.
+   * @param {{ context: object, streamWriter: import("../support/assistantStreamWriter.js").AssistantStreamWriter,
+   *   abortSignal?: AbortSignal }} options
+   */
+  async function streamChat(payload, options) {
+    const assistantSurface = requireAssistantSurface(appConfig, payload.targetSurfaceId);
     const context = normalizeObject(options.context);
     const assistantContext = buildAssistantActionContext(context, assistantSurface);
     const workspace = resolveRuntimeWorkspace(assistantSurface, assistantContext, payload);
     const source = normalizeStreamInput(payload);
-    const actor = context.actor;
+    const actor = resolveActor(context);
     const actorUserId = normalizeRecordId(actor?.id, { fallback: null });
     if (!actorUserId) throw new AppError(401, "Authentication required.", { code: "assistant.runtime.authenticationRequired" });
-    if (!hasStreamWriter(options.streamWriter)) throw new Error("assistant.chat.stream requires streamWriter methods.");
     const scope = { actorUserId, surfaceId: assistantSurface.targetSurfaceId,
+      // readable-check: allow no-dual-shape - data: the workspace scope resolves the workspace from the action input or context, which may carry the record or its id
       workspaceId: normalizeRecordId(workspace?.id || workspace, { fallback: null }) };
     const request = { ...source, integrationId: normalizeText(payload.integrationId) };
     const existing = await turnRequests.find(scope, source.messageId);
@@ -296,7 +290,6 @@ function createChatService({
     return result;
 
     async function executeTurn() {
-      if (typeof conversationRuntime?.open !== "function") throw new TypeError("Assistant streaming requires its common conversation runtime.");
       const conversationResult = await transcriptService.createConversationForTurn(
         assistantSurface,
         workspace,
@@ -329,13 +322,12 @@ function createChatService({
             code: "assistant.runtime.attachments.notConfigured"
           });
         }
-        // Preserve the facade's existing pre-admission authorization order.
+        // Attachments are authorized before admission, as the facade orders it.
         // Only these server-resolved materials reach the common file reader.
         const files = await attachments.resolve({ attachmentIds, context: assistantContext, workspace, conversation });
         resolvedAttachments.push({ attachmentIds: [...attachmentIds], files });
       }
       await prepareAttachments(source.attachmentIds);
-      for (const message of source.history) await prepareAttachments(message.attachmentIds);
       const toolSet = serviceToolCatalog.resolveToolSet(assistantContext);
       const customSystemPrompt = await assistantConfigService.resolveSystemPrompt(
         assistantSurface, workspace, { surface: assistantSurface.targetSurfaceId },
@@ -346,7 +338,7 @@ function createChatService({
         workspaceSlug: resolveWorkspaceSlug(assistantContext, payload), customSystemPrompt
       }), ...(request.integrationId ? { integrationId: request.integrationId } : {}) };
       const runtimeContext = { ...assistantContext, assistantRequest: {
-        conversation, workspace, history: source.history, resolvedAttachments
+        conversation, workspace, resolvedAttachments
       } };
       const handle = await openConversationTurn(conversationId, async () => {
         try { return await conversationRuntime.open({ id: conversationId, context: runtimeContext, configuration }); }
@@ -438,7 +430,7 @@ function createChatService({
   }
 
   async function listConversations(query = {}, options = {}) {
-    const assistantSurface = requireAssistantSurface(appConfig, options?.input?.targetSurfaceId);
+    const assistantSurface = requireAssistantSurface(appConfig, options.input?.targetSurfaceId);
     const context = normalizeObject(options.context);
     const assistantContext = buildAssistantActionContext(context, assistantSurface);
     const workspace = resolveRuntimeWorkspace(assistantSurface, assistantContext, options.input || {});
@@ -448,7 +440,7 @@ function createChatService({
   }
 
   async function getConversationMessages(conversationId, query = {}, options = {}) {
-    const assistantSurface = requireAssistantSurface(appConfig, options?.input?.targetSurfaceId);
+    const assistantSurface = requireAssistantSurface(appConfig, options.input?.targetSurfaceId);
     const context = normalizeObject(options.context);
     const assistantContext = buildAssistantActionContext(context, assistantSurface);
     const workspace = resolveRuntimeWorkspace(assistantSurface, assistantContext, options.input || {});
@@ -464,8 +456,12 @@ function createChatService({
     );
   }
 
+  function close() {
+    return conversationRuntime.close();
+  }
+
   return Object.freeze({
-    close: () => conversationRuntime?.close(),
+    close,
     streamChat,
     listConversations,
     getConversationMessages

package/src/server/services/transcriptService.js

@@ -1,3 +1,4 @@
+import { resolveActor } from "@jskit-ai/kernel/server/actions/actionContributorHelpers";
 import { AppError, createValidationError, parsePositiveInteger } from "@jskit-ai/kernel/server/runtime";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 import { normalizeObject, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
@@ -11,6 +12,7 @@ const MAX_MESSAGES_PAGE_SIZE = 500;
 const MAX_CONVERSATION_TITLE_LENGTH = 80;
 
 function resolveWorkspaceId(workspace, { required = false } = {}) {
+  // readable-check: allow no-dual-shape - data: the workspace scope resolves the workspace from the action input or context, which may carry the record or its id
   const workspaceId = normalizeRecordId(workspace?.id || workspace, { fallback: null });
   if (!workspaceId && required) {
     throw new AppError(409, "Workspace selection required.", { code: "assistant.runtime.workspace.selectionRequired" });
@@ -61,7 +63,7 @@ function isDefaultConversationTitle(value) {
   return normalizeText(value).toLowerCase() === DEFAULT_CONVERSATION_TITLE.toLowerCase();
 }
 
-function requireAssistantSurface(assistantSurface = {}) {
+function requireAssistantSurface(assistantSurface) {
   const targetSurfaceId = normalizeSurfaceId(assistantSurface?.targetSurfaceId);
   if (!targetSurfaceId) {
     throw new TypeError("assistant transcript service requires assistantSurface.targetSurfaceId.");
@@ -73,11 +75,17 @@ function requireAssistantSurface(assistantSurface = {}) {
   });
 }
 
-function createTranscriptService({ conversationsRepository, messagesRepository } = {}) {
-  if (!conversationsRepository || !messagesRepository) {
-    throw new Error("createTranscriptService requires conversationsRepository and messagesRepository.");
-  }
-
+/** @typedef {import("../types.js").ConversationsRepository} ConversationsRepository */
+/** @typedef {import("../types.js").MessagesRepository} MessagesRepository */
+
+/**
+ * A user's conversations on an assistant surface and their messages, in the
+ * package's own tables.
+ * @param {object} dependencies
+ * @param {ConversationsRepository} dependencies.conversationsRepository
+ * @param {MessagesRepository} dependencies.messagesRepository
+ */
+function createTranscriptService({ conversationsRepository, messagesRepository }) {
   function resolveExpectedWorkspaceId(assistantSurface, workspace) {
     const resolvedAssistantSurface = requireAssistantSurface(assistantSurface);
     return resolveWorkspaceId(workspace, {
@@ -150,7 +158,7 @@ function createTranscriptService({ conversationsRepository, messagesRepository }
 
     const source = normalizeObject(payload);
     const context = normalizeObject(options.context);
-    const actorUserId = resolveActorUserId(context.actor, {
+    const actorUserId = resolveActorUserId(resolveActor(context), {
       required: true
     });
     const workspaceId = resolveExpectedWorkspaceId(resolvedAssistantSurface, options.workspace || context.workspace);