@opengeni/core 0.21.2 → 0.24.1

package/src/application/session-commands.ts

@@ -16,7 +16,11 @@ import type {
   WorkspaceInferenceControlRequest,
   WorkspaceInferenceControlResponse,
 } from "@opengeni/contracts";
-import { latencyModeForMetadata, reasoningEffortForMetadata } from "@opengeni/contracts";
+import {
+  DraftTimelineAnnotations,
+  latencyModeForMetadata,
+  reasoningEffortForMetadata,
+} from "@opengeni/contracts";
 import {
   deleteSessionQueueItemInTransaction,
   editQueuedTurnInTransaction,
@@ -36,8 +40,11 @@ import {
   steerAgentSessionInTransaction,
   steerQueuedTurnInTransaction,
   withWorkspaceRls,
+  withWorkspaceSessionActivityRls,
   withWorkspaceSubjectRls,
+  withWorkspaceSubjectSessionActivityRls,
   type Database,
+  type SessionActivityDatabase,
   type SessionCommandReceiptRow,
 } from "@opengeni/db";
 import {
@@ -46,6 +53,8 @@ import {
   type EventBus,
 } from "@opengeni/events";
 import type { SessionWorkflowClient } from "../dependencies";
+import { normalizeResources } from "../domain/resources";
+import { validateDraftTimelineAnnotations } from "../domain/timeline-annotations";
 import {
   requireSessionAuthorization,
   type ResolvedSessionAuthorization,
@@ -142,17 +151,18 @@ function agentActor(context: AgentSessionCommandContext) {
 }
 
 /**
- * Retry only one operation-keyed Agent command transaction. The caller keeps
+ * Retry only one operation-keyed session command transaction. Callers keep
  * event publication and Temporal wake delivery after this returns, so a
- * deadlock/serialization retry can never replay an external effect.
+ * deadlock/serialization retry can never replay an external effect. Human
+ * draft ownership is applied inside every retry attempt when required.
  */
-async function runAgentCommandPersistenceTransaction<T>(
+async function runSessionCommandPersistenceTransaction<T>(
   deps: { db: Database },
-  context: AgentSessionCommandContext,
+  scope: { workspaceId: string; subjectId?: string },
   input: {
     stage: string;
     eventTypes: string[];
-    transaction: (tx: Database) => Promise<T>;
+    transaction: (tx: SessionActivityDatabase) => Promise<T>;
   },
 ): Promise<T> {
   return await runIdempotentPersistenceTransaction(
@@ -161,10 +171,17 @@ async function runAgentCommandPersistenceTransaction<T>(
       eventTypes: input.eventTypes,
       maxAttempts: 3,
     },
-    async () =>
-      await withWorkspaceRls(deps.db, context.workspaceId, async (scoped) =>
-        scoped.transaction(async (tx) => await input.transaction(tx as unknown as Database)),
-      ),
+    async () => {
+      const run = async (scoped: SessionActivityDatabase) => await input.transaction(scoped);
+      return scope.subjectId === undefined
+        ? await withWorkspaceSessionActivityRls(deps.db, scope.workspaceId, run)
+        : await withWorkspaceSubjectSessionActivityRls(
+            deps.db,
+            scope.workspaceId,
+            scope.subjectId,
+            run,
+          );
+    },
   );
 }
 
@@ -200,10 +217,14 @@ async function publishAndWakeAgentCommand(
         ? { interruptionRequested: true }
         : {}),
     });
-  } catch (error) {
+  } catch {
     console.warn(
-      `[session-commands] immediate Agent command wake failed for ${input.workspaceId}/${input.sessionId}; durable outbox will retry`,
-      error,
+      "[session-commands] immediate Agent command wake failed; durable outbox will retry",
+      {
+        errorClass: "WorkflowWakeOperationError",
+        errorCode: "agent_command_wake_failed",
+        origin: "core",
+      },
     );
   }
 }
@@ -222,10 +243,15 @@ async function requestControlWakeDispatch(
   if (wakeCount === 0) return;
   try {
     await deps.workflowClient.requestSessionWorkflowWakeDispatch();
-  } catch (error) {
+  } catch {
     console.warn(
-      `[session-commands] immediate control wake dispatch failed for ${wakeCount} committed revisions; durable outbox will retry`,
-      error,
+      "[session-commands] immediate control wake dispatch failed; durable outbox will retry",
+      {
+        errorClass: "WorkflowWakeOperationError",
+        errorCode: "control_wake_dispatch_failed",
+        origin: "core",
+        wakeCount,
+      },
     );
   }
 }
@@ -272,19 +298,23 @@ export async function sendAgentSessionMessage(
   input: { targetSessionId: string; text: string; idempotencyKey: string },
 ) {
   await authorizeAgentSessionCommand(deps, context, input.targetSessionId, "session.append");
-  const result = await runAgentCommandPersistenceTransaction(deps, context, {
-    stage: "session_commands.agent_message",
-    eventTypes: ["system.update.pending"],
-    transaction: async (tx) =>
-      await sendAgentMessageInTransaction(tx, {
-        accountId: context.accountId,
-        workspaceId: context.workspaceId,
-        targetSessionId: input.targetSessionId,
-        actor: agentActor(context),
-        operationKey: input.idempotencyKey,
-        text: input.text,
-      }),
-  });
+  const result = await runSessionCommandPersistenceTransaction(
+    deps,
+    { workspaceId: context.workspaceId },
+    {
+      stage: "session_commands.agent_message",
+      eventTypes: ["system.update.pending"],
+      transaction: async (tx) =>
+        await sendAgentMessageInTransaction(tx, {
+          accountId: context.accountId,
+          workspaceId: context.workspaceId,
+          targetSessionId: input.targetSessionId,
+          actor: agentActor(context),
+          operationKey: input.idempotencyKey,
+          text: input.text,
+        }),
+    },
+  );
   await publishAndWakeAgentCommand(deps, {
     accountId: context.accountId,
     workspaceId: context.workspaceId,
@@ -307,22 +337,30 @@ export async function steerAgentSession(
     sessionAuthorization?: SessionAuthorizationPort | null;
   },
   context: AgentSessionCommandContext,
-  input: { targetSessionId: string; instruction: string; idempotencyKey: string },
+  input: {
+    targetSessionId: string;
+    instruction: string;
+    idempotencyKey: string;
+  },
 ) {
   await authorizeAgentSessionCommand(deps, context, input.targetSessionId, "session.steer");
-  const result = await runAgentCommandPersistenceTransaction(deps, context, {
-    stage: "session_commands.agent_steer",
-    eventTypes: ["session.control.steer_requested", "system.update.pending", "turn.superseded"],
-    transaction: async (tx) =>
-      await steerAgentSessionInTransaction(tx, {
-        accountId: context.accountId,
-        workspaceId: context.workspaceId,
-        targetSessionId: input.targetSessionId,
-        actor: agentActor(context),
-        operationKey: input.idempotencyKey,
-        instruction: input.instruction,
-      }),
-  });
+  const result = await runSessionCommandPersistenceTransaction(
+    deps,
+    { workspaceId: context.workspaceId },
+    {
+      stage: "session_commands.agent_steer",
+      eventTypes: ["session.control.steer_requested", "system.update.pending", "turn.superseded"],
+      transaction: async (tx) =>
+        await steerAgentSessionInTransaction(tx, {
+          accountId: context.accountId,
+          workspaceId: context.workspaceId,
+          targetSessionId: input.targetSessionId,
+          actor: agentActor(context),
+          operationKey: input.idempotencyKey,
+          instruction: input.instruction,
+        }),
+    },
+  );
   await publishAndWakeAgentCommand(deps, {
     accountId: context.accountId,
     workspaceId: context.workspaceId,
@@ -359,18 +397,23 @@ export async function controlAgentSessionWorkstream(
     input.targetSessionId,
     "session.control",
   );
-  const result = await withWorkspaceRls(deps.db, context.workspaceId, (scoped) =>
-    scoped.transaction((tx) =>
-      mutateSessionControlInTransaction(tx as unknown as Database, {
-        accountId: context.accountId,
-        workspaceId: context.workspaceId,
-        sessionId: input.targetSessionId,
-        actor: agentActor(context),
-        operationKey: input.idempotencyKey,
-        action: input.action,
-        reason: input.reason ?? null,
-      }),
-    ),
+  const result = await runSessionCommandPersistenceTransaction(
+    deps,
+    { workspaceId: context.workspaceId },
+    {
+      stage: "session_commands.agent_control",
+      eventTypes: [input.action === "pause" ? "session.control.paused" : "session.control.resumed"],
+      transaction: async (tx) =>
+        await mutateSessionControlInTransaction(tx, {
+          accountId: context.accountId,
+          workspaceId: context.workspaceId,
+          sessionId: input.targetSessionId,
+          actor: agentActor(context),
+          operationKey: input.idempotencyKey,
+          action: input.action,
+          reason: input.reason ?? null,
+        }),
+    },
   );
   await publishSessionEventIds(deps, context.workspaceId, input.targetSessionId, [
     result.sessionControlEventId,
@@ -402,6 +445,7 @@ function composerDraft(
   return {
     revision: row.revision,
     text: row.text,
+    annotations: DraftTimelineAnnotations.parse(row.annotations),
     resources: row.resources as ComposerDraft["resources"],
     model: row.model,
     reasoningEffort: row.reasoningEffort as ComposerDraft["reasoningEffort"],
@@ -431,23 +475,32 @@ async function authoritativeQueue(
 }
 
 export async function moveHumanQueuePrompt(
-  deps: { db: Database; bus: EventBus; sessionAuthorization?: SessionAuthorizationPort | null },
+  deps: {
+    db: Database;
+    bus: EventBus;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+  },
   context: HumanSessionCommandContext,
   turnId: string,
   input: MoveSessionQueueItemRequest,
 ): Promise<SessionQueueMutationResponse> {
   const authorization = await authorizeHumanSessionCommand(deps, context, "session.queue.control");
-  const result = await withWorkspaceRls(deps.db, context.workspaceId, (scoped) =>
-    scoped.transaction((tx) =>
-      moveQueuedTurnInTransaction(tx as unknown as Database, {
-        ...context,
-        turnId,
-        beforeTurnId: input.beforeTurnId,
-        expectedQueueVersion: input.expectedQueueVersion,
-        actor: { type: "human", subjectId: context.subjectId },
-        operationKey: input.clientEventId,
-      }),
-    ),
+  const result = await runSessionCommandPersistenceTransaction(
+    deps,
+    { workspaceId: context.workspaceId },
+    {
+      stage: "session_commands.human_queue_move",
+      eventTypes: ["session.queue.changed"],
+      transaction: async (tx) =>
+        await moveQueuedTurnInTransaction(tx, {
+          ...context,
+          turnId,
+          beforeTurnId: input.beforeTurnId,
+          expectedQueueVersion: input.expectedQueueVersion,
+          actor: { type: "human", subjectId: context.subjectId },
+          operationKey: input.clientEventId,
+        }),
+    },
   );
   const response = {
     receipt: receipt(result.receipt),
@@ -463,23 +516,32 @@ export async function moveHumanQueuePrompt(
 }
 
 export async function deleteHumanQueuePrompt(
-  deps: { db: Database; bus: EventBus; sessionAuthorization?: SessionAuthorizationPort | null },
+  deps: {
+    db: Database;
+    bus: EventBus;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+  },
   context: HumanSessionCommandContext,
   turnId: string,
   input: DeleteSessionQueueItemRequest,
 ): Promise<SessionQueueMutationResponse> {
   const authorization = await authorizeHumanSessionCommand(deps, context, "session.queue.control");
-  const result = await withWorkspaceRls(deps.db, context.workspaceId, (scoped) =>
-    scoped.transaction((tx) =>
-      deleteSessionQueueItemInTransaction(tx as unknown as Database, {
-        ...context,
-        turnId,
-        expectedTurnVersion: input.expectedTurnVersion,
-        actor: { type: "human", subjectId: context.subjectId },
-        operationKey: input.clientEventId,
-        reason: input.reason ?? null,
-      }),
-    ),
+  const result = await runSessionCommandPersistenceTransaction(
+    deps,
+    { workspaceId: context.workspaceId },
+    {
+      stage: "session_commands.human_queue_delete",
+      eventTypes: ["session.queue.changed"],
+      transaction: async (tx) =>
+        await deleteSessionQueueItemInTransaction(tx, {
+          ...context,
+          turnId,
+          expectedTurnVersion: input.expectedTurnVersion,
+          actor: { type: "human", subjectId: context.subjectId },
+          operationKey: input.clientEventId,
+          reason: input.reason ?? null,
+        }),
+    },
   );
   const response = {
     receipt: receipt(result.receipt),
@@ -495,19 +557,24 @@ export async function deleteHumanQueuePrompt(
 }
 
 export async function editHumanQueuePrompt(
-  deps: { db: Database; bus: EventBus; sessionAuthorization?: SessionAuthorizationPort | null },
+  deps: {
+    db: Database;
+    bus: EventBus;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+  },
   context: HumanSessionCommandContext,
   turnId: string,
   input: EditSessionQueueItemRequest,
 ): Promise<SessionQueueMutationResponse> {
   const authorization = await authorizeHumanSessionCommand(deps, context, "session.queue.control");
-  const result = await withWorkspaceSubjectRls(
-    deps.db,
-    context.workspaceId,
-    context.subjectId,
-    (scoped) =>
-      scoped.transaction((tx) =>
-        editQueuedTurnInTransaction(tx as unknown as Database, {
+  const result = await runSessionCommandPersistenceTransaction(
+    deps,
+    { workspaceId: context.workspaceId, subjectId: context.subjectId },
+    {
+      stage: "session_commands.human_queue_edit",
+      eventTypes: ["session.queue.changed"],
+      transaction: async (tx) =>
+        await editQueuedTurnInTransaction(tx, {
           ...context,
           turnId,
           expectedTurnVersion: input.expectedTurnVersion,
@@ -516,7 +583,7 @@ export async function editHumanQueuePrompt(
           actor: { type: "human", subjectId: context.subjectId },
           operationKey: input.clientEventId,
         }),
-      ),
+    },
   );
   const response = {
     receipt: receipt(result.receipt),
@@ -533,23 +600,32 @@ export async function editHumanQueuePrompt(
 }
 
 export async function steerHumanQueuePrompt(
-  deps: { db: Database; bus: EventBus; sessionAuthorization?: SessionAuthorizationPort | null },
+  deps: {
+    db: Database;
+    bus: EventBus;
+    sessionAuthorization?: SessionAuthorizationPort | null;
+  },
   context: HumanSessionCommandContext,
   turnId: string,
   input: SteerSessionQueueItemRequest,
 ): Promise<SessionQueueMutationResponse> {
   const authorization = await authorizeHumanSessionCommand(deps, context, "session.queue.control");
-  const result = await withWorkspaceRls(deps.db, context.workspaceId, (scoped) =>
-    scoped.transaction((tx) =>
-      steerQueuedTurnInTransaction(tx as unknown as Database, {
-        ...context,
-        turnId,
-        expectedTurnVersion: input.expectedTurnVersion,
-        controlEtag: input.controlEtag ?? null,
-        actor: { type: "human", subjectId: context.subjectId },
-        operationKey: input.clientEventId,
-      }),
-    ),
+  const result = await runSessionCommandPersistenceTransaction(
+    deps,
+    { workspaceId: context.workspaceId },
+    {
+      stage: "session_commands.human_queue_steer",
+      eventTypes: ["session.control.steer_requested", "session.queue.changed", "turn.superseded"],
+      transaction: async (tx) =>
+        await steerQueuedTurnInTransaction(tx, {
+          ...context,
+          turnId,
+          expectedTurnVersion: input.expectedTurnVersion,
+          controlEtag: input.controlEtag ?? null,
+          actor: { type: "human", subjectId: context.subjectId },
+          operationKey: input.clientEventId,
+        }),
+    },
   );
   const response = {
     receipt: receipt(result.receipt),
@@ -565,7 +641,7 @@ export async function steerHumanQueuePrompt(
   return response;
 }
 
-export async function controlHumanSessionWorkstream(
+export async function controlHumanSessionWorkstreamWithOutcome(
   deps: {
     db: Database;
     bus: EventBus;
@@ -574,21 +650,28 @@ export async function controlHumanSessionWorkstream(
   },
   context: HumanSessionCommandContext,
   input: SessionControlRequest,
-): Promise<SessionControlResponse> {
+): Promise<{ response: SessionControlResponse; replay: boolean }> {
   const authorization = await authorizeHumanSessionCommand(deps, context, "session.control");
-  const result = await withWorkspaceRls(deps.db, context.workspaceId, (scoped) =>
-    scoped.transaction((tx) =>
-      mutateSessionControlInTransaction(tx as unknown as Database, {
-        accountId: context.accountId,
-        workspaceId: context.workspaceId,
-        sessionId: context.sessionId,
-        actor: { type: "human", subjectId: context.subjectId },
-        operationKey: input.clientEventId,
-        action: input.action,
-        reason: input.reason ?? null,
-        expectedControlEtag: input.expectedControlEtag ?? null,
-      }),
-    ),
+  const result = await runSessionCommandPersistenceTransaction(
+    deps,
+    { workspaceId: context.workspaceId },
+    {
+      stage: "session_commands.human_control",
+      eventTypes: [
+        input.action === "resume" ? "session.control.resumed" : "session.control.paused",
+      ],
+      transaction: async (tx) =>
+        await mutateSessionControlInTransaction(tx, {
+          accountId: context.accountId,
+          workspaceId: context.workspaceId,
+          sessionId: context.sessionId,
+          actor: { type: "human", subjectId: context.subjectId },
+          operationKey: input.clientEventId,
+          action: input.action,
+          reason: input.reason ?? null,
+          expectedControlEtag: input.expectedControlEtag ?? null,
+        }),
+    },
   );
   const response = {
     receipt: receipt(result.receipt),
@@ -607,7 +690,16 @@ export async function controlHumanSessionWorkstream(
   }
   await publishWorkspaceControlEvent(deps, context.workspaceId, result.workspaceControlEventId);
   await requestControlWakeDispatch(deps, result.wakeCount);
-  return response;
+  return { response, replay: result.replay };
+}
+
+/** Backward-compatible response path used by the REST control route. */
+export async function controlHumanSessionWorkstream(
+  deps: Parameters<typeof controlHumanSessionWorkstreamWithOutcome>[0],
+  context: Parameters<typeof controlHumanSessionWorkstreamWithOutcome>[1],
+  input: Parameters<typeof controlHumanSessionWorkstreamWithOutcome>[2],
+): Promise<SessionControlResponse> {
+  return (await controlHumanSessionWorkstreamWithOutcome(deps, context, input)).response;
 }
 
 export async function controlHumanWorkspace(
@@ -667,6 +759,7 @@ export async function getHumanComposerDraft(
   return {
     revision: 0,
     text: "",
+    annotations: [],
     resources: [],
     model: session.model,
     reasoningEffort: reasoningEffortForMetadata(session.metadata, "medium"),
@@ -683,6 +776,12 @@ export async function saveHumanComposerDraft(
   input: SaveComposerDraftRequest,
 ): Promise<ComposerDraft> {
   await authorizeHumanSessionCommand(deps, context, "session.composer.write");
+  const annotations = await validateDraftTimelineAnnotations(
+    deps.db,
+    context.workspaceId,
+    context.sessionId,
+    input.annotations ?? [],
+  );
   const row = await withWorkspaceSubjectRls(
     deps.db,
     context.workspaceId,
@@ -692,6 +791,8 @@ export async function saveHumanComposerDraft(
         saveComposerDraftInTransaction(tx as unknown as Database, {
           ...context,
           ...input,
+          annotations,
+          resources: normalizeResources(input.resources),
           subjectId: context.subjectId,
         }),
       ),

package/src/dependencies.ts

@@ -5,6 +5,7 @@ import type {
   DocumentAuthorityKind,
   GitHubAppApiPort,
   ScheduledTask,
+  ScheduledTaskTriggerType,
   SessionAuthorizationPort,
   TurnInitiator,
 } from "@opengeni/contracts";
@@ -16,6 +17,12 @@ import type { createObjectStorage } from "@opengeni/storage";
 import type { ManagedAuth } from "./managed-auth-type";
 import type { ApiSandboxClient, ResumeBoxByIdInput, ResumedSandboxSession } from "./sandbox-types";
 import type { TranscriptionSegmenter, TranscriptionService } from "./transcription";
+import type { EditableArtifactApplicationPort } from "./editable-artifact-live";
+import type {
+  EditableArtifactAgentApplication,
+  EditableArtifactDurableExportService,
+  EditableArtifactOfficeImportPort,
+} from "./editable-artifacts";
 
 export type SessionWorkflowClient = {
   signalUserMessage: (input: {
@@ -59,6 +66,10 @@ export type SessionWorkflowClient = {
     agentRunUsageIdempotencyKey: string;
     triggerWorkflowId: string;
     initiator: TurnInitiator;
+    triggerType?: Extract<
+      ScheduledTaskTriggerType,
+      "manual" | "initial" | "provider_event" | "retry" | "repair"
+    >;
   }) => Promise<void>;
   startRigVerification: (input: {
     workspaceId: string;
@@ -83,8 +94,22 @@ export type DocumentIndexClient = {
 export type AppDependencies = {
   settings: Settings;
   db: Database;
+  /**
+   * Host-composed editable artifact engine. Standalone startup binds the same
+   * native kernel/DB/object-store implementation; embedded hosts may inject an
+   * equivalent deployment-scoped composition.
+   */
+  editableArtifacts?: EditableArtifactApplicationPort;
+  /** Durable immutable version/materialization API paired with editableArtifacts. */
+  editableArtifactExports?: EditableArtifactDurableExportService;
+  /** Canonical agent-facing artifact use cases shared by MCP and Codemode. */
+  editableArtifactAgent?: EditableArtifactAgentApplication;
+  /** Trusted Office-file to canonical sequence-zero import boundary. */
+  editableArtifactOfficeImports?: EditableArtifactOfficeImportPort;
   bus: EventBus;
   workflowClient: SessionWorkflowClient;
+  /** Injectable structural seam for replayable prompt fanout and wake work. */
+  schedulePromptPostCommit?: (task: () => Promise<void>) => void;
   /** Optional provider override for deterministic API/object-storage tests. */
   objectStorage?: ObjectStorageDependency;
   documentIndexer?: DocumentIndexClient;
@@ -100,7 +125,7 @@ export type AppDependencies = {
   githubAppApi?: GitHubAppApiPort;
   /**
    * Optional host-owned connection credential seam. API-side consumers use
-   * the MCP leg for Toolspace/Code Mode; worker consumers bind the same port
+   * the MCP leg for Codemode/Code Mode; worker consumers bind the same port
    * for model MCP, Git, and sandbox-secret resolution.
    */
   connectionCredentials?: ConnectionCredentialsPort | null;
@@ -117,6 +142,9 @@ export type AppDependencies = {
   slackFetch?: typeof fetch;
   /** Injectable Google OAuth/Drive transport for deterministic connector tests. */
   googleDriveFetch?: typeof fetch;
+  /** Injectable provider-preset OAuth/API transport for deterministic integration tests. */
+  apiIntegrationOAuthFetch?: typeof fetch;
+  atlassianFetch?: typeof fetch;
   /** Injectable MCP OAuth setup deadline for deterministic stalled-provider tests. */
   oauthStartDeadlineMs?: number;
   /** Injectable MCP OAuth callback deadline for deterministic stalled-provider tests. */
@@ -163,7 +191,7 @@ export type ApiRouteDeps = AppDependencies & {
  */
 export type AcceptSessionUserMessageDependencies = Pick<
   AppDependencies,
-  "settings" | "db" | "bus" | "sessionAuthorization"
+  "settings" | "db" | "bus" | "sessionAuthorization" | "schedulePromptPostCommit"
 > & {
   workflowClient: Pick<SessionWorkflowClient, "wakeSessionWorkflow">;
   objectStorage: ObjectStorageDependency;