@opengeni/db 0.9.3 → 0.12.0

package/src/session-control.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import {
   boundWorkspaceControlEvent,
   workspaceControlUtf8Bytes,
+  type SessionMcpApprovalPolicy,
   type TurnInitiatorContext,
 } from "@opengeni/contracts";
 import { and, eq, inArray, sql } from "drizzle-orm";
@@ -10,7 +11,7 @@ import * as schema from "./schema";
 
 export const SESSION_ANCESTRY_LIMIT = 10_000;
 
-export type WorkspaceControlLockMode = "share" | "update";
+export type WorkspaceControlLockMode = "none" | "share" | "update";
 export type EffectiveControlState = "active" | "paused";
 export type SessionCommandActor =
   | { type: "human" | "operator"; subjectId: string }
@@ -201,9 +202,12 @@ export async function assertAgentCommandAuthorityInTransaction(
     workspaceId: string;
     actor: Extract<SessionCommandActor, { type: "agent_attempt" }>;
     targetSessionId: string;
-    action: "pause" | "resume" | "steer" | "message";
+    action: "pause" | "resume" | "steer" | "message" | "goal";
   },
 ): Promise<void> {
+  if (input.action === "goal" && input.targetSessionId !== input.actor.sessionId) {
+    throw new SessionControlInvariantError("An agent goal command must target its own session");
+  }
   // Every command caller establishes the control/workspace prefix first.
   // Reusing the event-write helper here keeps cross-session actor authority on
   // the same UUID-ordered session -> exact turn -> exact attempt suffix.
@@ -354,6 +358,7 @@ function controlEtag(value: unknown): string {
 }
 
 function lockClause(mode: WorkspaceControlLockMode) {
+  if (mode === "none") return sql.empty();
   return mode === "update" ? sql.raw("for update") : sql.raw("for share");
 }
 
@@ -512,6 +517,7 @@ export async function registerSessionTurnAttemptClaim(
     temporalWorkflowRunId: string;
     temporalActivityId: string;
     verifiedControlRevision: number;
+    mcpApprovalPolicies: Record<string, SessionMcpApprovalPolicy>;
   },
 ): Promise<typeof schema.sessionTurnAttempts.$inferSelect> {
   const [inserted] = await db
@@ -1343,26 +1349,32 @@ async function findCommandReceipt(
     targetSessionId: string | null;
     targetTurnId: string | null;
     operationKey: string;
+    identityScope: "actor" | "goal_operation";
   },
 ): Promise<SessionCommandReceiptRow | null> {
   const actorSubjectId = input.actor.type === "agent_attempt" ? null : input.actor.subjectId;
   const actorAttemptId = input.actor.type === "agent_attempt" ? input.actor.attemptId : null;
-  const rows = await db
-    .select()
-    .from(schema.sessionCommandReceipts)
-    .where(
-      and(
-        eq(schema.sessionCommandReceipts.workspaceId, input.workspaceId),
-        eq(schema.sessionCommandReceipts.actorType, input.actor.type),
-        sql`${schema.sessionCommandReceipts.actorSubjectId} is not distinct from ${actorSubjectId}`,
-        sql`${schema.sessionCommandReceipts.actorAttemptId} is not distinct from ${actorAttemptId}::uuid`,
-        eq(schema.sessionCommandReceipts.action, input.action),
-        sql`${schema.sessionCommandReceipts.targetSessionId} is not distinct from ${input.targetSessionId}::uuid`,
-        sql`${schema.sessionCommandReceipts.targetTurnId} is not distinct from ${input.targetTurnId}::uuid`,
-        eq(schema.sessionCommandReceipts.operationKey, input.operationKey),
-      ),
-    )
-    .for("update");
+  const identity =
+    input.identityScope === "goal_operation"
+      ? and(
+          eq(schema.sessionCommandReceipts.workspaceId, input.workspaceId),
+          eq(schema.sessionCommandReceipts.actorType, "agent_attempt"),
+          eq(schema.sessionCommandReceipts.action, input.action),
+          eq(schema.sessionCommandReceipts.targetSessionId, input.targetSessionId!),
+          sql`${schema.sessionCommandReceipts.targetTurnId} is null`,
+          eq(schema.sessionCommandReceipts.operationKey, input.operationKey),
+        )
+      : and(
+          eq(schema.sessionCommandReceipts.workspaceId, input.workspaceId),
+          eq(schema.sessionCommandReceipts.actorType, input.actor.type),
+          sql`${schema.sessionCommandReceipts.actorSubjectId} is not distinct from ${actorSubjectId}`,
+          sql`${schema.sessionCommandReceipts.actorAttemptId} is not distinct from ${actorAttemptId}::uuid`,
+          eq(schema.sessionCommandReceipts.action, input.action),
+          sql`${schema.sessionCommandReceipts.targetSessionId} is not distinct from ${input.targetSessionId}::uuid`,
+          sql`${schema.sessionCommandReceipts.targetTurnId} is not distinct from ${input.targetTurnId}::uuid`,
+          eq(schema.sessionCommandReceipts.operationKey, input.operationKey),
+        );
+  const rows = await db.select().from(schema.sessionCommandReceipts).where(identity).for("update");
   return rows[0] ?? null;
 }
 
@@ -1377,9 +1389,22 @@ export async function reserveSessionCommandReceipt(
     targetTurnId: string | null;
     operationKey: string;
     canonicalRequestHash: string;
+    identityScope?: "actor" | "goal_operation";
   },
 ): Promise<{ receipt: SessionCommandReceiptRow; replay: boolean }> {
   if (!input.operationKey.trim()) throw new Error("operationKey must not be empty");
+  const identityScope = input.identityScope ?? "actor";
+  if (
+    identityScope === "goal_operation" &&
+    (input.actor.type !== "agent_attempt" ||
+      input.action !== "goal.update" ||
+      input.targetSessionId === null ||
+      input.targetTurnId !== null)
+  ) {
+    throw new SessionControlInvariantError(
+      "Target-scoped receipt identity is reserved for agent goal.update commands",
+    );
+  }
   const actorSubjectId = input.actor.type === "agent_attempt" ? null : input.actor.subjectId;
   const actorAttemptId = input.actor.type === "agent_attempt" ? input.actor.attemptId : null;
   const [inserted] = await db
@@ -1407,6 +1432,7 @@ export async function reserveSessionCommandReceipt(
       targetSessionId: input.targetSessionId,
       targetTurnId: input.targetTurnId,
       operationKey: input.operationKey,
+      identityScope,
     }));
   if (!receipt) throw new SessionControlInvariantError("Command receipt conflict was not readable");
   if (receipt.canonicalRequestHash !== input.canonicalRequestHash) {

package/src/session-queue-commands.ts

@@ -1,9 +1,13 @@
 import {
+  metadataWithTurnExecutionPolicyV1,
   mergeResourceRefs,
   mergeToolRefs,
+  turnExecutionPolicyAuditMetadata,
   type ReasoningEffort,
   type ResourceRef,
+  type SessionToolPolicy,
   type ToolRef,
+  type TurnExecutionPolicyV1,
 } from "@opengeni/contracts";
 import { and, asc, eq, inArray, sql } from "drizzle-orm";
 import type { Database } from "./index";
@@ -39,7 +43,8 @@ export type QueueCommandConflictCode =
   | "QUEUE_ANCHOR_CHANGED"
   | "PROMPT_CHANGED"
   | "DRAFT_CHANGED"
-  | "DRAFT_NOT_EMPTY";
+  | "DRAFT_NOT_EMPTY"
+  | "EDIT_SOURCE_CHANGED";
 
 export class QueueCommandConflictError extends Error {
   readonly name = "QueueCommandConflictError";
@@ -377,6 +382,7 @@ function draftIsNonEmpty(draft: ComposerDraftRow): boolean {
     draft.text.length > 0 ||
     draft.resources.length > 0 ||
     draft.tools.length > 0 ||
+    draft.toolsProvided ||
     draft.sourceTurnId !== null
   );
 }
@@ -416,6 +422,7 @@ export async function saveComposerDraftInTransaction(
     text: string;
     resources: ResourceRef[];
     tools: ToolRef[];
+    toolsProvided: boolean;
     model: string;
     reasoningEffort: ReasoningEffort;
   },
@@ -447,6 +454,7 @@ export async function saveComposerDraftInTransaction(
     text: input.text,
     resources: input.resources,
     tools: input.tools,
+    toolsProvided: input.toolsProvided,
     model: input.model,
     reasoningEffort: input.reasoningEffort,
     // A queue edit is still the same accepted work item. Preserve its frozen
@@ -818,6 +826,7 @@ export async function editQueuedTurnInTransaction(
     text: turn.prompt,
     resources: turn.resources,
     tools: turn.tools,
+    toolsProvided: turn.toolsProvided,
     model: turn.model,
     reasoningEffort: turn.reasoningEffort,
     sourceTurnId: turn.id,
@@ -1134,9 +1143,12 @@ export async function submitHumanPromptInTransaction(
     turnInstructions?: string | null;
     resources: ResourceRef[];
     tools: ToolRef[];
+    toolsProvided?: boolean;
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
     reasoningEffortFallback: ReasoningEffort;
+    /** Trusted API/core admission snapshot. Omitted only by legacy low-level callers. */
+    turnExecutionPolicy?: TurnExecutionPolicyV1;
     source: "user" | "api";
     mcpCredentialUpdates?: Array<{
       id: string;
@@ -1163,6 +1175,7 @@ export async function submitHumanPromptInTransaction(
     turnInstructions: input.turnInstructions ?? null,
     resources: input.resources,
     tools: input.tools,
+    toolsProvided: input.toolsProvided === true,
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
     source: input.source,
@@ -1271,6 +1284,7 @@ export async function submitHumanPromptInTransaction(
         text: draft.text,
         resources: draft.resources,
         tools: draft.tools,
+        toolsProvided: draft.toolsProvided,
         model: draft.model,
         reasoningEffort: draft.reasoningEffort,
       }) !==
@@ -1278,6 +1292,7 @@ export async function submitHumanPromptInTransaction(
           text: input.text,
           resources: input.resources,
           tools: input.tools,
+          toolsProvided: input.toolsProvided === true,
           model: input.model ?? session.model,
           reasoningEffort: input.reasoningEffort ?? input.reasoningEffortFallback,
         })
@@ -1293,6 +1308,52 @@ export async function submitHumanPromptInTransaction(
     }
   }
 
+  let editedSourceTurn: QueuedTurnRow | undefined;
+  let editedSourceTurnInstructions: string | null | undefined;
+  if (draft?.sourceTurnId) {
+    const sourceLocks = await lockSessionEventWriteRows(db, {
+      workspaceId: input.workspaceId,
+      controlLock: "already_locked",
+      workspaceLock: "already_locked",
+      turnIds: [draft.sourceTurnId],
+    });
+    const sourceTurn = sourceLocks.turns[0];
+    const sourceTurnVersion = draft.sourceTurnVersion;
+    const sourceMetadata = sourceTurn?.metadata ?? {};
+    const sourceIsExactWithdrawnRevision =
+      sourceTurn !== undefined &&
+      sourceTurn.accountId === input.accountId &&
+      sourceTurn.workspaceId === input.workspaceId &&
+      sourceTurn.sessionId === input.sessionId &&
+      (sourceTurn.source === "user" || sourceTurn.source === "api") &&
+      sourceTurn.status === "withdrawn_for_edit" &&
+      sourceTurnVersion !== null &&
+      sourceTurn.version === sourceTurnVersion + 1 &&
+      sourceTurn.cancelledBy === input.subjectId &&
+      sourceTurn.cancelReason === "withdrawn_for_edit" &&
+      sourceTurn.activeAttemptId === null &&
+      sourceMetadata.delivery !== "steer";
+    if (!sourceIsExactWithdrawnRevision) {
+      throw new QueueCommandConflictError(
+        "EDIT_SOURCE_CHANGED",
+        "Edited prompt source changed or is no longer withdrawn for edit",
+        {
+          queueVersion: session.queueVersion,
+          draftRevision: draft.revision,
+          ...(sourceTurn ? { turnVersion: sourceTurn.version } : {}),
+        },
+      );
+    }
+    // This is the sole private-instruction source for an edited replacement.
+    // It is deliberately held separately from the public draft and event
+    // projections below. The public draft is expected to differ after editing;
+    // source identity is fenced by its exact withdrawn row version, not by
+    // comparing the replacement content with the old prompt. A client-supplied
+    // instruction value must never override the private source value.
+    editedSourceTurn = sourceTurn;
+    editedSourceTurnInstructions = sourceTurn.turnInstructions ?? null;
+  }
+
   for (const update of input.mcpCredentialUpdates ?? []) {
     const [server] = await db
       .update(schema.sessionMcpServers)
@@ -1315,22 +1376,7 @@ export async function submitHumanPromptInTransaction(
   const now = new Date();
   let frozenInitiator: FrozenTurnInitiator;
   if (input.delivery === "send" && draft?.sourceTurnId) {
-    const [sourceTurn] = await db
-      .select({
-        sessionId: schema.sessionTurns.sessionId,
-        initiatorKind: schema.sessionTurns.initiatorKind,
-        initiatorSubjectId: schema.sessionTurns.initiatorSubjectId,
-        initiatorContext: schema.sessionTurns.initiatorContext,
-      })
-      .from(schema.sessionTurns)
-      .where(
-        and(
-          eq(schema.sessionTurns.workspaceId, input.workspaceId),
-          eq(schema.sessionTurns.sessionId, input.sessionId),
-          eq(schema.sessionTurns.id, draft.sourceTurnId),
-        ),
-      )
-      .limit(1);
+    const sourceTurn = editedSourceTurn;
     if (!sourceTurn) {
       throw new SessionControlInvariantError("Edited prompt source turn is missing");
     }
@@ -1366,7 +1412,11 @@ export async function submitHumanPromptInTransaction(
       payload: sanitizeEventPayload({
         text: input.text,
         ...(input.resources.length ? { resources: input.resources } : {}),
-        ...(input.tools.length ? { tools: input.tools } : {}),
+        ...(input.toolsProvided === true
+          ? { tools: input.tools }
+          : input.tools.length
+            ? { tools: input.tools }
+            : {}),
         ...(input.model ? { model: input.model } : {}),
         ...(input.reasoningEffort ? { reasoningEffort: input.reasoningEffort } : {}),
         delivery: input.delivery,
@@ -1389,13 +1439,19 @@ export async function submitHumanPromptInTransaction(
       source: input.source,
       position: input.delivery === "steer" ? 0 : existingQueued.length + 1,
       prompt: input.text,
-      turnInstructions: input.turnInstructions ?? null,
+      turnInstructions:
+        editedSourceTurnInstructions !== undefined
+          ? editedSourceTurnInstructions
+          : (input.turnInstructions ?? null),
       resources: input.resources,
       tools: input.tools,
+      toolsProvided: input.toolsProvided === true,
       model: input.model ?? session.model,
       reasoningEffort: input.reasoningEffort ?? input.reasoningEffortFallback,
       sandboxBackend: session.sandboxBackend,
-      metadata: {},
+      metadata: input.turnExecutionPolicy
+        ? metadataWithTurnExecutionPolicyV1({}, input.turnExecutionPolicy)
+        : {},
       lineage: { actor: input.actor.type },
       ...initiatorColumns(frozenInitiator),
     })
@@ -1455,6 +1511,7 @@ export async function submitHumanPromptInTransaction(
       .update(schema.sessionTurns)
       .set({
         metadata: {
+          ...turn.metadata,
           delivery: "steer",
           replacedTurnId,
           replacedAttemptId,
@@ -1532,7 +1589,9 @@ export async function submitHumanPromptInTransaction(
     .update(schema.sessions)
     .set({
       resources: mergeResourceRefs(session.resources as ResourceRef[], input.resources),
-      tools: mergeToolRefs(session.tools as ToolRef[], input.tools),
+      tools: sessionToolPolicyIsFixed(session.toolPolicy)
+        ? session.tools
+        : mergeToolRefs(session.tools as ToolRef[], input.tools),
       activeTurnId: input.delivery === "steer" ? liveCurrentTurnId : session.activeTurnId,
       status: nextStatus,
       queueVersion,
@@ -1566,6 +1625,9 @@ export async function submitHumanPromptInTransaction(
       operationId: reserved.receipt.id,
       replacedTurnId,
       interruptionCount,
+      ...(input.turnExecutionPolicy
+        ? turnExecutionPolicyAuditMetadata(input.turnExecutionPolicy, turnId)
+        : {}),
     },
   });
   const eventIds = eventRows.map((event) => event.id);
@@ -1582,6 +1644,11 @@ export async function submitHumanPromptInTransaction(
       interruptionCount,
       replacedTurnId,
       workspaceControlEventId: resumed.workspaceControlEventId,
+      ...(input.turnExecutionPolicy
+        ? {
+            executionPolicy: turnExecutionPolicyAuditMetadata(input.turnExecutionPolicy, turnId),
+          }
+        : {}),
     },
   });
   return {
@@ -1597,6 +1664,12 @@ export async function submitHumanPromptInTransaction(
   };
 }
 
+function sessionToolPolicyIsFixed(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const mode = (value as Partial<SessionToolPolicy>).mode;
+  return mode === "workspace_default" || mode === "explicit" || mode === "inherited";
+}
+
 export async function sendAgentMessageInTransaction(
   db: Database,
   input: {

package/src/session-tool-call-settlement.ts

@@ -255,7 +255,12 @@ export async function closePendingSessionToolCallsInTransaction(
         sessionId: input.sessionId,
         turnId: input.turnId,
         position: nextPosition++,
-        item: sanitizeModelPayload(boundModelToolOutputItem(resolution.result)),
+        item: sanitizeModelPayload(
+          boundModelToolOutputItem(
+            resolution.result,
+            resolution.call.modelToolOutputTruncationTokens ?? undefined,
+          ),
+        ),
         active: true,
       });
     }