@opengeni/core 0.4.9 → 0.8.0

package/dist/index.js

@@ -566,7 +566,9 @@ async function delegatedAccessContext(c, deps, mode, token = bearerToken(c)) {
           ...payload.turnId ? { turnId: payload.turnId } : {},
           ...payload.attemptId ? { attemptId: payload.attemptId } : {},
           ...payload.executionGeneration ? { executionGeneration: payload.executionGeneration } : {}
-        }
+        },
+        ...payload.serviceInitiator ? { serviceInitiator: payload.serviceInitiator } : {},
+        ...payload.serviceInitiatorContext ? { serviceInitiatorContext: payload.serviceInitiatorContext } : {}
       }
     ],
     defaultAccountId: payload.accountId,
@@ -586,6 +588,146 @@ async function sha256Hex(value) {
   return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
 }
 
+// src/session-authorization.ts
+import {
+  SessionAuthorizationActor,
+  SessionAuthorizationDecision,
+  SessionAuthorizationListScope
+} from "@opengeni/contracts";
+import {
+  getSession,
+  getSessionRootId,
+  getSessionTurnForAttempt
+} from "@opengeni/db";
+var SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS = 15e3;
+var SessionAuthorizationDeniedError = class extends Error {
+  constructor(reason) {
+    super("Session not found or access denied");
+    this.reason = reason;
+    this.name = "SessionAuthorizationDeniedError";
+  }
+  code = "SESSION_NOT_FOUND_OR_DENIED";
+};
+var SessionAuthorizationUnavailableError = class extends Error {
+  code = "SESSION_AUTHORIZATION_UNAVAILABLE";
+  constructor(options) {
+    super("Session authorization is unavailable", options);
+    this.name = "SessionAuthorizationUnavailableError";
+  }
+};
+async function requireSessionAuthorization(deps, grant, input) {
+  const port = deps.sessionAuthorization;
+  if (!port) return null;
+  const [actor, target] = await Promise.all([
+    resolveSessionAuthorizationActor(deps.db, grant),
+    resolveSessionAuthorizationTarget(deps.db, grant, input.sessionId)
+  ]);
+  let rawDecision;
+  try {
+    rawDecision = await port.authorizeSession({
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor,
+      target,
+      operation: input.operation,
+      surface: input.surface
+    });
+  } catch (error) {
+    throw new SessionAuthorizationUnavailableError({ cause: error });
+  }
+  const parsed = SessionAuthorizationDecision.safeParse(rawDecision);
+  if (!parsed.success) {
+    throw new SessionAuthorizationUnavailableError({ cause: parsed.error });
+  }
+  if (!parsed.data.allowed) {
+    throw new SessionAuthorizationDeniedError(parsed.data.reason);
+  }
+  return {
+    actor,
+    target,
+    relatedSessionAccess: parsed.data.relatedSessionAccess ?? "target",
+    reauthorizeAfterMs: parsed.data.reauthorizeAfterMs ?? null
+  };
+}
+async function requireSessionAuthorizationListScope(deps, grant, surface) {
+  const port = deps.sessionAuthorization;
+  if (!port) return null;
+  const actor = await resolveSessionAuthorizationActor(deps.db, grant);
+  let rawScope;
+  try {
+    rawScope = await port.resolveListScope({
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      actor,
+      surface
+    });
+  } catch (error) {
+    throw new SessionAuthorizationUnavailableError({ cause: error });
+  }
+  const parsed = SessionAuthorizationListScope.safeParse(rawScope);
+  if (!parsed.success) {
+    throw new SessionAuthorizationUnavailableError({ cause: parsed.error });
+  }
+  if (parsed.data.kind === "all") return parsed.data;
+  return {
+    kind: "scoped",
+    rootSessionIds: [...new Set(parsed.data.rootSessionIds)],
+    sessionIds: [...new Set(parsed.data.sessionIds)]
+  };
+}
+async function resolveSessionAuthorizationTarget(db, grant, sessionId) {
+  const session = await getSession(db, grant.workspaceId, sessionId);
+  if (!session || session.accountId !== grant.accountId) {
+    throw new SessionAuthorizationDeniedError("not_found");
+  }
+  let rootSessionId;
+  try {
+    rootSessionId = await getSessionRootId(db, grant.workspaceId, session.id);
+  } catch (error) {
+    throw new SessionAuthorizationUnavailableError({ cause: error });
+  }
+  if (!rootSessionId) {
+    throw new SessionAuthorizationDeniedError("not_found");
+  }
+  return { sessionId: session.id, rootSessionId };
+}
+async function resolveSessionAuthorizationActor(db, grant) {
+  const callerSessionId = grant.metadata?.["sessionId"];
+  const turnId = grant.metadata?.["turnId"];
+  const attemptId = grant.metadata?.["attemptId"];
+  const executionGeneration = grant.metadata?.["executionGeneration"];
+  const hasAttemptClaim = turnId !== void 0 || attemptId !== void 0 || executionGeneration !== void 0;
+  if (!hasAttemptClaim) {
+    return SessionAuthorizationActor.parse({
+      kind: "subject",
+      subjectId: grant.subjectId,
+      ...grant.subjectLabel ? { subjectLabel: grant.subjectLabel } : {}
+    });
+  }
+  if (typeof callerSessionId !== "string" || typeof turnId !== "string" || typeof attemptId !== "string" || typeof executionGeneration !== "number" || !Number.isSafeInteger(executionGeneration) || executionGeneration < 1) {
+    throw new SessionAuthorizationDeniedError("caller_stale");
+  }
+  const [callerSession, turn, callerRootSessionId] = await Promise.all([
+    getSession(db, grant.workspaceId, callerSessionId),
+    getSessionTurnForAttempt(db, grant.workspaceId, callerSessionId, attemptId),
+    getSessionRootId(db, grant.workspaceId, callerSessionId).catch(() => null)
+  ]);
+  if (!callerSession || callerSession.accountId !== grant.accountId || !turn || turn.id !== turnId || turn.executionGeneration !== executionGeneration || callerSession.activeTurnId !== turn.id || !callerRootSessionId) {
+    throw new SessionAuthorizationDeniedError("caller_stale");
+  }
+  return SessionAuthorizationActor.parse({
+    kind: "agent_attempt",
+    subjectId: grant.subjectId,
+    callerSessionId,
+    callerRootSessionId,
+    turnId,
+    attemptId,
+    executionGeneration,
+    initiator: turn.initiator,
+    initiatorContext: turn.initiatorContext
+  });
+}
+
 // src/billing/limits.ts
 import { configuredStaticUsageLimits } from "@opengeni/config";
 import {
@@ -748,6 +890,12 @@ async function recordWorkspaceUsage(deps, input) {
     unit: input.unit,
     sourceResourceType: input.sourceResourceType,
     sourceResourceId: input.sourceResourceId,
+    sessionId: input.sessionId ?? null,
+    turnId: input.turnId ?? null,
+    turnAttemptId: input.turnAttemptId ?? null,
+    initiator: input.initiator ?? (input.subjectId ? { kind: "subject", subjectId: input.subjectId } : null),
+    ...input.initiatorContext ? { initiatorContext: input.initiatorContext } : {},
+    origin: input.origin ?? null,
     idempotencyKey: input.idempotencyKey
   });
 }
@@ -795,6 +943,10 @@ import {
   upsertCapabilityCatalogItem
 } from "@opengeni/db";
 import { HTTPException as HTTPException6 } from "hono/http-exception";
+import {
+  getSkillLibraryEntry,
+  listSkillLibraryEntries
+} from "@opengeni/runtime/skill-library";
 
 // src/domain/environments.ts
 import { environmentsEncryptionKeyBytes } from "@opengeni/config";
@@ -1117,13 +1269,15 @@ async function buildCapabilityCatalog(input) {
     capabilityInstallations,
     packInstallations,
     workspacePacks,
-    bundledSkills
+    bundledSkills,
+    curatedLibrarySkills
   ] = await Promise.all([
     listCapabilityCatalogItems(input.db, input.workspaceId),
     listCapabilityInstallations(input.db, input.workspaceId),
     listPackInstallations2(input.db, input.workspaceId),
     listWorkspaceCapabilityPacks(input.db, input.workspaceId),
-    discoverBundledSkills()
+    discoverBundledSkills(),
+    discoverCuratedSkillLibraryItems()
   ]);
   const capabilityInstallationById = new Map(
     capabilityInstallations.map((installation) => [installation.capabilityId, installation])
@@ -1138,7 +1292,8 @@ async function buildCapabilityCatalog(input) {
     ),
     ...configuredMcpCatalogItems(input.settings),
     ...platformApiCatalogItems(),
-    ...bundledSkills
+    ...bundledSkills,
+    ...curatedLibrarySkills
   ];
   const items = dedupeCatalogItems([...builtIns, ...persistedItems]).map(
     (item) => applyCapabilityEnablement(item, capabilityInstallationById.get(item.id), activePackIds)
@@ -1155,7 +1310,12 @@ async function createCatalogItem(input) {
       message: "packs are managed by OpenGeni and cannot be manually created"
     });
   }
-  const source = input.payload.source === "built_in" || input.payload.source === "configured" || input.payload.source === "registry" ? "manual" : input.payload.source;
+  if (id.startsWith("skill:")) {
+    throw new HTTPException6(422, {
+      message: "skill ids are managed by the OpenGeni skill library or runtime adapters"
+    });
+  }
+  const source = input.payload.source === "built_in" || input.payload.source === "library" || input.payload.source === "configured" || input.payload.source === "registry" ? "manual" : input.payload.source;
   const metadata = {
     ...input.payload.metadata,
     ...input.payload.kind === "mcp" && input.payload.endpointUrl && !input.payload.metadata.mcpServerId ? { mcpServerId: mcpServerIdForCapability(id, input.payload.metadata) } : {}
@@ -1190,11 +1350,46 @@ async function enableCapability(input) {
     });
   }
   let installationMetadata = input.payload.metadata;
-  const installationConfig = { ...input.payload.config };
+  let installationConfig = { ...input.payload.config };
   delete installationConfig.headers;
   delete installationConfig.headersEncrypted;
   delete installationConfig.headerNames;
   delete installationConfig.connectionRef;
+  if (item.kind === "skill" && item.source === "library") {
+    const libraryId = stringMetadata(item.metadata.libraryId);
+    const catalogVersion = stringMetadata(item.metadata.version);
+    if (!libraryId || !catalogVersion) {
+      throw new HTTPException6(422, {
+        message: `skill library metadata is incomplete for ${item.id}`
+      });
+    }
+    const requestedVersion = input.payload.config.version;
+    if (requestedVersion !== void 0 && typeof requestedVersion !== "string") {
+      throw new HTTPException6(422, {
+        message: "skill activation config.version must be a string"
+      });
+    }
+    const normalizedVersion = requestedVersion?.trim() || catalogVersion;
+    if (normalizedVersion !== catalogVersion) {
+      throw new HTTPException6(422, {
+        message: `skill ${libraryId} only supports immutable version ${catalogVersion}`
+      });
+    }
+    const entry = getSkillLibraryEntry(libraryId, normalizedVersion);
+    if (!entry) {
+      throw new HTTPException6(422, {
+        message: `skill library entry is unavailable: ${libraryId}@${normalizedVersion}`
+      });
+    }
+    installationConfig = { version: entry.version };
+    installationMetadata = {
+      libraryId: entry.id,
+      libraryVersion: entry.version,
+      contentSha256: entry.contentSha256,
+      sourceCommit: entry.sourceCommit,
+      provenance: entry.provenance
+    };
+  }
   if (item.kind === "mcp") {
     const headers = await resolveMcpCredentialHeaders(input, item);
     const connectionRef = input.payload.connectionRef ? await validateMcpCapabilityConnectionRef(input, item, input.payload.connectionRef) : null;
@@ -1353,9 +1548,11 @@ async function validateMcpCapabilityConnectionRef(input, item, ref) {
     providerDomain: ref.providerDomain.trim(),
     subjectScope: "workspace",
     ...ref.connectionId ? { connectionId: ref.connectionId } : {},
+    ...ref.provider ? { provider: ref.provider.trim() } : {},
     ...ref.kind ? { kind: ref.kind } : {},
     ...ref.scopes ? { scopes: uniqueStrings(ref.scopes) } : {},
-    ...ref.resource ? { resource: ref.resource } : {}
+    ...ref.resource ? { resource: ref.resource } : {},
+    ...ref.selectedResources ? { selectedResources: ref.selectedResources.map((resource) => ({ ...resource })) } : {}
   };
   if (!normalized.providerDomain) {
     throw new HTTPException6(422, { message: "connectionRef.providerDomain is required" });
@@ -1504,12 +1701,20 @@ async function probeStreamableHttpMcpServer(input) {
 function mcpProbeErrorMessage(error, endpointUrl) {
   const message = error instanceof Error ? error.message : String(error);
   const normalized = message.replace(/\s+/g, " ").trim();
+  const endpoint = safeEndpointLabel(endpointUrl);
   if (/404|405|not found|unexpected token|not valid json|invalid json|failed to parse|streamable http error|unable to connect|fetch failed|econnrefused|enotfound|timeout|aborted/i.test(
     normalized
   )) {
-    return `OpenGeni could not reach a valid Streamable HTTP MCP server at ${endpointUrl}. Check the endpoint URL or choose a different catalog entry.`;
+    return `OpenGeni could not reach a valid Streamable HTTP MCP server at ${endpoint}. Check the endpoint URL or choose a different catalog entry.`;
+  }
+  return `OpenGeni could not initialize ${endpoint}. Check the endpoint configuration or try again.`;
+}
+function safeEndpointLabel(endpointUrl) {
+  try {
+    return new URL(endpointUrl).hostname || "the configured endpoint";
+  } catch {
+    return "the configured endpoint";
   }
-  return `OpenGeni could not initialize ${endpointUrl}: ${normalized.slice(0, 500) || "unknown error"}`;
 }
 async function disableCapability(input) {
   const item = await requireCatalogItem(
@@ -1799,6 +2004,43 @@ async function discoverBundledSkills() {
     return [];
   }
 }
+async function discoverCuratedSkillLibraryItems() {
+  return listSkillLibraryEntries().map((entry) => curatedSkillCatalogItem(entry));
+}
+function curatedSkillCatalogItem(entry) {
+  return CapabilityCatalogItem.parse({
+    id: `skill:${entry.id}`,
+    kind: "skill",
+    source: "library",
+    name: entry.name,
+    description: entry.description,
+    category: entry.category,
+    tags: [...entry.tags],
+    homepageUrl: entry.sourceUrl,
+    provenance: entry.provenance,
+    tier: "verified",
+    runtime: {
+      available: true,
+      notes: "Available as an explicit immutable opt-in skill selection."
+    },
+    metadata: {
+      libraryId: entry.id,
+      version: entry.version,
+      contentSha256: entry.contentSha256,
+      sourceCommit: entry.sourceCommit,
+      sourceUrl: entry.sourceUrl,
+      provenance: entry.provenance,
+      license: entry.license,
+      documentationUrl: entry.documentationUrl,
+      compatibility: entry.compatibility,
+      upgrade: entry.upgrade,
+      artifactPath: entry.relativePath
+    }
+  });
+}
+function stringMetadata(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
 async function readSkillMetadata(url, fallbackName) {
   const content = await readFile(url, "utf8");
   const frontMatter = content.match(/^---\n([\s\S]*?)\n---/);
@@ -1827,6 +2069,15 @@ function applyCapabilityEnablement(item, installation, activePackIds) {
       enabledReason: item.source === "configured" ? "configured" : "built in"
     };
   }
+  if (item.source === "library") {
+    const enabled2 = installation?.status === "active" && skillLibraryInstallationRuntimeReady(item, installation);
+    return {
+      ...item,
+      enabled: enabled2,
+      enabledReason: enabled2 ? "explicitly selected" : null,
+      connectionRef: null
+    };
+  }
   const activeInstallation = installation?.status === "active";
   const enabled = !!activeInstallation && capabilityInstallationRuntimeReady(item, installation);
   return {
@@ -1836,6 +2087,24 @@ function applyCapabilityEnablement(item, installation, activePackIds) {
     connectionRef: enabled && installation ? installationConnectionRef(installation.config) : null
   };
 }
+function skillLibraryInstallationRuntimeReady(item, installation) {
+  if (item.kind !== "skill" || item.source !== "library" || installation.kind !== "skill") {
+    return false;
+  }
+  const libraryId = stringMetadata(item.metadata.libraryId);
+  const version = stringMetadata(item.metadata.version);
+  const contentSha256 = stringMetadata(item.metadata.contentSha256);
+  const sourceCommit = stringMetadata(item.metadata.sourceCommit);
+  const provenance = stringMetadata(item.metadata.provenance);
+  if (!libraryId || !version || !contentSha256 || !sourceCommit || !provenance) {
+    return false;
+  }
+  const entry = getSkillLibraryEntry(libraryId, version);
+  if (!entry || item.id !== `skill:${entry.id}` || installation.capabilityId !== `skill:${entry.id}` || contentSha256 !== entry.contentSha256 || sourceCommit !== entry.sourceCommit || provenance !== entry.provenance) {
+    return false;
+  }
+  return installation.config.version === entry.version && stringMetadata(installation.metadata.libraryId) === entry.id && stringMetadata(installation.metadata.libraryVersion) === entry.version && stringMetadata(installation.metadata.contentSha256) === entry.contentSha256 && stringMetadata(installation.metadata.sourceCommit) === entry.sourceCommit && stringMetadata(installation.metadata.provenance) === entry.provenance;
+}
 function installationConnectionRef(config) {
   const ref = config.connectionRef;
   if (!ref || typeof ref !== "object") {
@@ -1850,6 +2119,14 @@ function installationConnectionRef(config) {
 function dedupeCatalogItems(items) {
   const byId = /* @__PURE__ */ new Map();
   for (const item of items) {
+    if (item.kind === "skill" && item.source === "library" && byId.has(item.id)) {
+      byId.set(item.id, item);
+      continue;
+    }
+    const existing = byId.get(item.id);
+    if (existing?.kind === "skill" && existing.source === "library") {
+      continue;
+    }
     byId.set(item.id, item);
   }
   return [...byId.values()];
@@ -2377,13 +2654,20 @@ async function listRigChangesForApi(deps, workspaceId, rigId, limit) {
 
 // src/domain/resources.ts
 import {
+  gitCredentialBindingIdForRepository,
+  gitCredentialProviderForRepository,
+  defaultRepositoryMountPath,
   mergeResourceRefs as mergeContractResourceRefs,
   mergeToolRefs,
+  normalizeRepositorySubpath,
+  normalizeResourceMountPath,
   resourceIdentityKey,
+  resourceMountPathCollisionKey,
   ResourceRefConflictError,
+  ResourceMountPathError,
   stableJson
 } from "@opengeni/contracts";
-import { listGitHubInstallationIdsForWorkspace, requireFile } from "@opengeni/db";
+import { areGitHubRepositoriesAllowedForWorkspace, requireFile } from "@opengeni/db";
 import { HTTPException as HTTPException8 } from "hono/http-exception";
 function validateToolRefs(tools, settings) {
   const mcpServerIds = new Set(settings.mcpServers.map((server) => server.id));
@@ -2417,6 +2701,7 @@ function withDefaultEnabledCapabilityMcpTools(tools, settings, runtimeSettings)
 function normalizeResources(resources) {
   const mountPaths = /* @__PURE__ */ new Map();
   const identities = /* @__PURE__ */ new Map();
+  const credentialBindingProviders = /* @__PURE__ */ new Map();
   const seenResources = /* @__PURE__ */ new Set();
   const out = [];
   for (const resource of resources) {
@@ -2439,14 +2724,35 @@ function normalizeResources(resources) {
         throw new HTTPException8(422, { message: "repository URL must include owner and repo" });
       }
       const repo = parts.join("/");
-      const mountPath = normalizeMountPath(resource.mountPath ?? `repos/${repo}`);
+      const normalizedUri = `https://${url.host.toLowerCase()}/${repo}.git`;
+      const mountPath = normalizeMountPath(
+        resource.mountPath ?? defaultRepositoryMountPath(normalizedUri)
+      );
+      const credentialProvider = gitCredentialProviderForRepository(resource);
+      const credentialBindingId = gitCredentialBindingIdForRepository(resource, credentialProvider);
+      if ((resource.credentialBindingId || resource.connectionId || resource.access) && !credentialProvider) {
+        throw new HTTPException8(422, {
+          message: "repository credential bindings and access intent require a Git provider"
+        });
+      }
+      if (credentialProvider && credentialBindingId) {
+        const boundProvider = credentialBindingProviders.get(credentialBindingId);
+        if (boundProvider && boundProvider !== credentialProvider) {
+          throw new HTTPException8(422, {
+            message: `credential binding ${credentialBindingId} is assigned to multiple Git providers`
+          });
+        }
+        credentialBindingProviders.set(credentialBindingId, credentialProvider);
+      }
       normalized = {
         kind: "repository",
-        uri: `https://${url.hostname.toLowerCase()}/${repo}.git`,
+        uri: normalizedUri,
         ref: resource.ref.trim(),
         mountPath,
-        ...resource.subpath ? { subpath: normalizeMountPath(resource.subpath) } : {},
+        ...resource.subpath ? { subpath: normalizeRepositorySubpath(resource.subpath) } : {},
         ...resource.provider ? { provider: resource.provider } : {},
+        ...resource.credentialBindingId ? { credentialBindingId: resource.credentialBindingId } : {},
+        ...resource.access ? { access: resource.access } : {},
         ...resource.repositoryId !== void 0 ? { repositoryId: resource.repositoryId } : {},
         ...resource.installationId !== void 0 ? { installationId: resource.installationId } : {},
         ...resource.projectId !== void 0 ? { projectId: resource.projectId } : {},
@@ -2456,14 +2762,15 @@ function normalizeResources(resources) {
       };
     }
     const key = stableJson(normalized);
-    const mounted = normalized.mountPath ? mountPaths.get(normalized.mountPath) : void 0;
+    const mountCollisionKey = normalized.mountPath ? resourceMountPathCollisionKey(normalized.mountPath) : void 0;
+    const mounted = mountCollisionKey ? mountPaths.get(mountCollisionKey) : void 0;
     if (mounted && mounted !== key) {
       throw new HTTPException8(422, {
         message: `duplicate resource mount path: ${normalized.mountPath}`
       });
     }
     if (normalized.mountPath) {
-      mountPaths.set(normalized.mountPath, key);
+      mountPaths.set(mountCollisionKey, key);
     }
     const identity = resourceIdentityKey(normalized);
     const seenIdentity = identities.get(identity);
@@ -2490,8 +2797,24 @@ function mergeResourceRefs(existing, additions) {
     throw error;
   }
 }
+function validateGitHubRepositorySelectionShapes(resources) {
+  const selected = gitHubRepositorySelections(resources);
+  if (selected.length === 0) {
+    return [];
+  }
+  return [...new Set(selected.map((item) => item.installationId))];
+}
 function validateGitHubRepositorySelectionShape(resources) {
-  const selected = resources.flatMap((resource) => {
+  const installationIds = validateGitHubRepositorySelectionShapes(resources);
+  if (installationIds.length > 1) {
+    throw new HTTPException8(422, {
+      message: "GitHub App repository resources must belong to one installation"
+    });
+  }
+  return installationIds[0] ?? null;
+}
+function gitHubRepositorySelections(resources) {
+  return resources.flatMap((resource) => {
     if (resource.kind !== "repository") {
       return [];
     }
@@ -2503,38 +2826,34 @@ function validateGitHubRepositorySelectionShape(resources) {
     if (installationRaw === void 0 && repositoryRaw === void 0) {
       return [];
     }
-    const installationId2 = positiveInteger(installationRaw);
+    const installationId = positiveInteger(installationRaw);
     const repositoryId = positiveInteger(repositoryRaw);
-    if (!installationId2 || !repositoryId) {
+    if (!installationId || !repositoryId) {
       throw new HTTPException8(422, {
         message: "GitHub App repository resources require positive github_installation_id and github_repository_id"
       });
     }
-    return [{ installationId: installationId2, repositoryId }];
+    return [{ installationId, repositoryId }];
   });
-  if (selected.length === 0) {
-    return null;
-  }
-  const installationId = selected[0].installationId;
-  if (selected.some((item) => item.installationId !== installationId)) {
-    throw new HTTPException8(422, {
-      message: "GitHub App repository resources must belong to one installation"
-    });
-  }
-  return installationId;
 }
 async function validateGitHubRepositorySelection(db, workspaceId, resources) {
-  const installationId = validateGitHubRepositorySelectionShape(resources);
-  if (installationId === null) {
+  const installationIds = validateGitHubRepositorySelectionShapes(resources);
+  if (installationIds.length === 0) {
     return;
   }
-  const linkedInstallationIds = new Set(
-    await listGitHubInstallationIdsForWorkspace(db, workspaceId)
-  );
-  if (!linkedInstallationIds.has(installationId)) {
-    throw new HTTPException8(422, {
-      message: "GitHub App repository resources must belong to a GitHub App installation linked to this workspace"
-    });
+  const selections = gitHubRepositorySelections(resources);
+  for (const installationId of installationIds) {
+    const repositoryIds = selections.filter((selection) => selection.installationId === installationId).map((selection) => selection.repositoryId);
+    if (!await areGitHubRepositoriesAllowedForWorkspace(
+      db,
+      workspaceId,
+      installationId,
+      repositoryIds
+    )) {
+      throw new HTTPException8(422, {
+        message: "GitHub App repository resources must be authorized for a GitHub App installation linked to this workspace"
+      });
+    }
   }
 }
 async function validateFileResources(db, workspaceId, resources) {
@@ -2559,11 +2878,12 @@ async function validateFileResources(db, workspaceId, resources) {
   }
 }
 function normalizeMountPath(path) {
-  const normalized = path.trim().replace(/^\/+|\/+$/g, "");
-  if (!normalized || normalized.includes("..")) {
+  try {
+    return normalizeResourceMountPath(path);
+  } catch (error) {
+    if (!(error instanceof ResourceMountPathError)) throw error;
     throw new HTTPException8(422, { message: `invalid resource mount path: ${path}` });
   }
-  return normalized;
 }
 function parseResourceUrl(uri) {
   try {
@@ -2597,6 +2917,8 @@ import { CODEX_MODEL_ID_PREFIX } from "@opengeni/codex";
 import { configuredAllowedModels, policyProviderIdForModel } from "@opengeni/config";
 import {
   CreateSessionRequest,
+  ServiceTurnInitiator,
+  ServiceTurnInitiatorContext,
   evaluateWorkspaceModelPolicy,
   reasoningEffortForMetadata
 } from "@opengeni/contracts";
@@ -2611,7 +2933,8 @@ import {
   listDistinctVariableSetIdsInGroup,
   listDistinctRigVersionIdsInGroup,
   getSandbox as getSandbox3,
-  getSession,
+  getSession as getSession2,
+  SessionIdConflictError,
   getSessionByCreateIdempotencyKey,
   getSessionEvent,
   getWorkspaceControlEvent,
@@ -2619,11 +2942,14 @@ import {
   getSessionTurn,
   getWorkspaceModelPolicy,
   initializeSessionStartAtomically,
+  listSessionTurns,
+  listSessionMcpServersForChildInheritance,
   requireSession as requireSession2,
   submitHumanPromptInTransaction,
   updateSessionTitle as updateSessionTitleRow,
   withWorkspaceSubjectRls,
   QueueCommandConflictError,
+  AgentCommandAuthorityError,
   SessionControlConflictError
 } from "@opengeni/db";
 import {
@@ -2636,6 +2962,72 @@ var reservedSessionMcpServerIds = /* @__PURE__ */ new Set(["opengeni", "files",
 var maxSessionMcpCredentialHeaders = 16;
 var maxSessionMcpCredentialHeaderValueLength = 4096;
 var sessionMcpCredentialHeaderName = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+function serviceInitiatorForGrant(grant) {
+  if (!grant.serviceInitiator) {
+    if (grant.serviceInitiatorContext) {
+      throw new HTTPException9(403, {
+        message: "service initiator context requires a signed service initiator"
+      });
+    }
+    return null;
+  }
+  const initiator = ServiceTurnInitiator.safeParse(grant.serviceInitiator);
+  if (!initiator.success) {
+    throw new HTTPException9(403, {
+      message: "a delegated command initiator must be a bounded service principal"
+    });
+  }
+  const context = ServiceTurnInitiatorContext.safeParse(grant.serviceInitiatorContext ?? {});
+  if (!context.success) {
+    throw new HTTPException9(403, {
+      message: "delegated service initiator context is invalid or reserved"
+    });
+  }
+  const callerTurnId = grant.metadata?.["turnId"];
+  const callerAttemptId = grant.metadata?.["attemptId"];
+  const callerExecutionGeneration = grant.metadata?.["executionGeneration"];
+  if (callerTurnId !== void 0 || callerAttemptId !== void 0 || callerExecutionGeneration !== void 0) {
+    throw new HTTPException9(403, {
+      message: "a service initiator cannot replace an exact agent-attempt initiator"
+    });
+  }
+  return {
+    initiator: initiator.data,
+    context: context.data
+  };
+}
+function creationInitiatorForGrant(grant) {
+  const serviceInitiator = serviceInitiatorForGrant(grant);
+  const callerSessionId = grant.metadata?.["sessionId"];
+  const callerTurnId = grant.metadata?.["turnId"];
+  const callerAttemptId = grant.metadata?.["attemptId"];
+  const callerExecutionGeneration = grant.metadata?.["executionGeneration"];
+  const hasCallerTurnClaim = callerTurnId !== void 0 || callerAttemptId !== void 0 || callerExecutionGeneration !== void 0;
+  if (hasCallerTurnClaim) {
+    if (typeof callerSessionId !== "string" || typeof callerTurnId !== "string" || typeof callerAttemptId !== "string" || typeof callerExecutionGeneration !== "number" || !Number.isSafeInteger(callerExecutionGeneration) || callerExecutionGeneration < 1) {
+      throw new HTTPException9(403, { message: "caller attempt claims are incomplete" });
+    }
+    const actor = {
+      type: "agent_attempt",
+      sessionId: callerSessionId,
+      turnId: callerTurnId,
+      attemptId: callerAttemptId,
+      executionGeneration: callerExecutionGeneration
+    };
+    return { actor };
+  }
+  if (serviceInitiator) {
+    return serviceInitiator;
+  }
+  return {
+    initiator: {
+      kind: "subject",
+      subjectId: grant.subjectId,
+      ...grant.subjectLabel ? { label: grant.subjectLabel } : {}
+    },
+    context: {}
+  };
+}
 function normalizedSessionMcpCredentialHeaders(headers) {
   if (!headers) {
     return {};
@@ -2677,7 +3069,20 @@ function mcpServerConfigFromInput(server) {
     ...server.allowedTools ? { allowedTools: server.allowedTools } : {},
     ...server.timeoutMs ? { timeoutMs: server.timeoutMs } : {},
     cacheToolsList: server.cacheToolsList ?? false,
-    ...server.requireApproval !== void 0 ? { requireApproval: server.requireApproval } : {}
+    ...server.requireApproval !== void 0 ? { requireApproval: server.requireApproval } : {},
+    ...server.connectionRef ? { connectionRef: server.connectionRef } : {}
+  };
+}
+function mcpServerConfigFromStoredInput(server) {
+  return {
+    id: server.id,
+    ...server.name ? { name: server.name } : {},
+    url: server.url,
+    ...server.allowedTools ? { allowedTools: server.allowedTools } : {},
+    ...server.timeoutMs ? { timeoutMs: server.timeoutMs } : {},
+    cacheToolsList: server.cacheToolsList ?? false,
+    ...server.requireApproval != null ? { requireApproval: server.requireApproval } : {},
+    ...server.connectionRef ? { connectionRef: server.connectionRef } : {}
   };
 }
 function mcpServerConfigFromMetadata(server) {
@@ -2685,7 +3090,8 @@ function mcpServerConfigFromMetadata(server) {
     id: server.id,
     ...server.name ? { name: server.name } : {},
     url: server.url,
-    cacheToolsList: false
+    cacheToolsList: false,
+    ...server.connectionRef ? { connectionRef: server.connectionRef } : {}
   };
 }
 function settingsWithSessionMcpServerConfigs(settings, servers) {
@@ -2706,7 +3112,7 @@ function validateSessionMcpServersForCreate(settings, grant, servers) {
     return { runtimeServers: [], dbServers: [], metadata: [] };
   }
   requirePermission(grant, "mcp_servers:attach");
-  const encryptionKey = requireVariableSetEncryption(settings);
+  const encryptionKey = servers.some((server) => Object.keys(server.headers ?? {}).length > 0) ? requireVariableSetEncryption(settings) : null;
   const existingIds = new Set(settings.mcpServers.map((server) => server.id));
   const seenIds = /* @__PURE__ */ new Set();
   const runtimeServers = [];
@@ -2736,6 +3142,7 @@ function validateSessionMcpServersForCreate(settings, grant, servers) {
       timeoutMs: server.timeoutMs ?? null,
       cacheToolsList: server.cacheToolsList ?? false,
       requireApproval: server.requireApproval ?? null,
+      connectionRef: server.connectionRef ?? null,
       headersEncrypted
     });
     metadata.push({
@@ -2743,11 +3150,46 @@ function validateSessionMcpServersForCreate(settings, grant, servers) {
       name: server.name ?? null,
       url: server.url,
       headerNames: Object.keys(headersEncrypted).sort(),
-      credentialVersion: 1
+      credentialVersion: 1,
+      connectionRef: server.connectionRef ?? null
     });
   }
   return { runtimeServers, dbServers, metadata };
 }
+function validateInheritedSessionMcpServersForCreate(servers) {
+  if (servers.length === 0) {
+    return { runtimeServers: [], dbServers: [], metadata: [] };
+  }
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const server of servers) {
+    if (seenIds.has(server.id)) {
+      throw new HTTPException9(422, {
+        message: `duplicate inherited session MCP server id: ${server.id}`
+      });
+    }
+    seenIds.add(server.id);
+    if (reservedSessionMcpServerIds.has(server.id)) {
+      throw new HTTPException9(422, {
+        message: `reserved inherited session MCP server id: ${server.id}`
+      });
+    }
+  }
+  return {
+    runtimeServers: servers.map(mcpServerConfigFromStoredInput),
+    dbServers: servers.map((server) => ({
+      ...server,
+      headersEncrypted: { ...server.headersEncrypted ?? {} }
+    })),
+    metadata: servers.map((server) => ({
+      id: server.id,
+      name: server.name ?? null,
+      url: server.url,
+      headerNames: Object.keys(server.headersEncrypted ?? {}).sort(),
+      credentialVersion: 1,
+      connectionRef: server.connectionRef ?? null
+    }))
+  };
+}
 function validateSessionMcpCredentialUpdates(input) {
   if (input.updates.length === 0) {
     return [];
@@ -2792,18 +3234,26 @@ async function createAndStartSession(input) {
       input.createIdempotencyKey
     );
     if (existing) {
+      if (input.requestedSessionId && existing.id !== input.requestedSessionId) {
+        throw new SessionIdConflictError(input.requestedSessionId);
+      }
       return await finishStartSession(
         existing.temporalWorkflowId ? { ...input, seedTargetSandbox: null } : input,
         existing
       );
     }
     const { session: keyed, created } = await createSessionWithIdempotencyKey(input.db, {
+      ...input.requestedSessionId ? { requestedSessionId: input.requestedSessionId } : {},
       accountId: input.accountId,
       workspaceId: input.workspaceId,
       initialMessage: input.initialMessage,
+      initialTurnInstructions: input.turnInstructions ?? null,
       resources: input.resources,
       tools: input.tools,
       metadata: sessionMetadata,
+      ...input.createdBy ? { createdBy: input.createdBy } : {},
+      ...input.createdByContext ? { createdByContext: input.createdByContext } : {},
+      createdByActor: input.createdByActor ?? null,
       model: input.model,
       sandboxBackend: input.sandboxBackend,
       variableSetId: input.variableSet?.id ?? null,
@@ -2826,12 +3276,17 @@ async function createAndStartSession(input) {
     return await finishStartSession(input, keyed);
   }
   const session = await createSession(input.db, {
+    ...input.requestedSessionId ? { requestedSessionId: input.requestedSessionId } : {},
     accountId: input.accountId,
     workspaceId: input.workspaceId,
     initialMessage: input.initialMessage,
+    initialTurnInstructions: input.turnInstructions ?? null,
     resources: input.resources,
     tools: input.tools,
     metadata: sessionMetadata,
+    ...input.createdBy ? { createdBy: input.createdBy } : {},
+    ...input.createdByContext ? { createdByContext: input.createdByContext } : {},
+    createdByActor: input.createdByActor ?? null,
     model: input.model,
     sandboxBackend: input.sandboxBackend,
     variableSetId: input.variableSet?.id ?? null,
@@ -2900,7 +3355,9 @@ async function finishStartSession(input, session) {
       wakeRevision: started.workflowWakeRevision
     });
   }
-  return await requireSession2(input.db, session.workspaceId, session.id);
+  const persisted = await requireSession2(input.db, session.workspaceId, session.id);
+  const initialTurnId = started.turn?.id ?? (await listSessionTurns(input.db, session.workspaceId, session.id, 1))[0]?.id ?? null;
+  return { ...persisted, initialTurnId };
 }
 function workflowIdForSession(sessionId) {
   return `session-${sessionId}`;
@@ -2967,12 +3424,17 @@ async function postUserMessageTurn(input) {
           workspaceId,
           sessionId,
           subjectId: input.actor ?? accountId,
-          actor: { type: "human", subjectId: input.actor ?? accountId },
+          ...input.actorLabel ? { subjectLabel: input.actorLabel } : {},
+          actor: input.commandActor ?? {
+            type: "human",
+            subjectId: input.actor ?? accountId
+          },
           operationKey,
           delivery: input.delivery ?? "send",
           controlEtag: input.controlEtag ?? null,
           expectedDraftRevision: input.expectedDraftRevision ?? null,
           text: input.text,
+          turnInstructions: input.turnInstructions ?? null,
           resources: input.resources,
           tools: input.tools,
           model: requestedModel,
@@ -3044,23 +3506,40 @@ async function postUserMessageTurn(input) {
 async function createSessionForRequest(deps, grant, workspaceId, rawPayload) {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   const payload = CreateSessionRequest.parse(rawPayload);
+  const parentSessionId = typeof grant.metadata?.["sessionId"] === "string" ? grant.metadata["sessionId"] : null;
+  if (parentSessionId) {
+    await requireSessionAuthorization(deps, grant, {
+      sessionId: parentSessionId,
+      operation: "session.child.create",
+      surface: "core"
+    });
+  }
+  const parentSession = parentSessionId ? await getSession2(db, workspaceId, parentSessionId) : null;
+  if (parentSessionId && !parentSession) {
+    throw new HTTPException9(404, {
+      message: `parent session not found in workspace: ${parentSessionId}`
+    });
+  }
   const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(
     db,
     workspaceId,
     settings
   );
-  const sessionMcpServers = validateSessionMcpServersForCreate(
-    capabilityRuntimeSettings,
-    grant,
-    payload.mcpServers
-  );
+  const sessionMcpServers = hasOwnProperty(rawPayload, "mcpServers") ? validateSessionMcpServersForCreate(capabilityRuntimeSettings, grant, payload.mcpServers) : parentSession ? validateInheritedSessionMcpServersForCreate(
+    await listSessionMcpServersForChildInheritance(db, workspaceId, parentSession.id)
+  ) : validateSessionMcpServersForCreate(capabilityRuntimeSettings, grant, payload.mcpServers);
   const runtimeSettings = settingsWithSessionMcpServerConfigs(
     capabilityRuntimeSettings,
     sessionMcpServers.runtimeServers
   );
-  const resources = normalizeResources(payload.resources);
-  const requestedTools = validateToolRefs(payload.tools, runtimeSettings);
-  const defaultedTools = hasOwnProperty(rawPayload, "tools") ? requestedTools : withDefaultEnabledCapabilityMcpTools(requestedTools, settings, capabilityRuntimeSettings);
+  const resources = normalizeResources(
+    hasOwnProperty(rawPayload, "resources") ? payload.resources : parentSession?.resources ?? payload.resources
+  );
+  const requestedTools = validateToolRefs(
+    hasOwnProperty(rawPayload, "tools") ? payload.tools : parentSession?.tools ?? payload.tools,
+    runtimeSettings
+  );
+  const defaultedTools = hasOwnProperty(rawPayload, "tools") || parentSession ? requestedTools : withDefaultEnabledCapabilityMcpTools(requestedTools, settings, capabilityRuntimeSettings);
   const tools = withFirstPartyTools(defaultedTools, runtimeSettings);
   await validateGitHubRepositorySelection(db, workspaceId, resources);
   if (resources.some((resource) => resource.kind === "file") && !objectStorage) {
@@ -3098,7 +3577,7 @@ async function createSessionForRequest(deps, grant, workspaceId, rawPayload) {
   );
   const model = payload.model ?? settings.openaiModel;
   const reasoningEffort = payload.reasoningEffort ?? settings.openaiReasoningEffort;
-  let firstPartyMcpPermissions = payload.firstPartyMcpPermissions ?? null;
+  let firstPartyMcpPermissions = payload.firstPartyMcpPermissions ?? (parentSessionId ? [...new Set(grant.permissions)] : null);
   if (firstPartyMcpPermissions && firstPartyMcpPermissions.length === 0) {
     throw new HTTPException9(422, {
       message: "firstPartyMcpPermissions must not be empty; omit it for the default worker permission set"
@@ -3112,9 +3591,10 @@ async function createSessionForRequest(deps, grant, workspaceId, rawPayload) {
     }
   }
   if (payload.goal && firstPartyMcpPermissions && !firstPartyMcpPermissions.includes("goals:manage")) {
-    firstPartyMcpPermissions = [...firstPartyMcpPermissions, "goals:manage"];
+    throw new HTTPException9(422, {
+      message: "goal-bearing sessions require goals:manage in the resulting first-party MCP permission set"
+    });
   }
-  const parentSessionId = typeof grant.metadata?.["sessionId"] === "string" ? grant.metadata["sessionId"] : null;
   const sandboxChoice = payload.sandbox ?? (parentSessionId ? "shared" : "new");
   let sandboxGroupId = null;
   let inheritedBackend;
@@ -3127,12 +3607,10 @@ async function createSessionForRequest(deps, grant, workspaceId, rawPayload) {
         message: "sandbox:'shared' requires a parent session (spawn from inside a session); use 'new' for a top-level create."
       });
     }
-    const parent = await getSession(db, workspaceId, parentSessionId);
-    if (!parent) {
-      throw new HTTPException9(404, {
-        message: `parent session not found in workspace: ${parentSessionId}`
-      });
+    if (!parentSession) {
+      throw new Error("trusted parent session was not resolved");
     }
+    const parent = parentSession;
     const parentBoxed = parent.sandboxBackend !== "none";
     const variableSetMismatch = parentBoxed && !variableSetMatchesGroup(parent.variableSetId ?? null);
     let rigMismatch = parentBoxed && !rigVersionMatchesGroup(parent.rigVersionId ?? null);
@@ -3218,50 +3696,69 @@ async function createSessionForRequest(deps, grant, workspaceId, rawPayload) {
     quantity: 1,
     model
   });
-  const session = await createAndStartSession({
-    db,
-    bus,
-    workflowClient,
-    accountId: grant.accountId,
-    workspaceId,
-    initialMessage: payload.initialMessage,
-    resources,
-    tools,
-    ...payload.clientEventId ? { clientEventId: payload.clientEventId } : {},
-    model,
-    reasoningEffort,
-    // A shared spawn inherits the box's backend; a caller-supplied
-    // sandboxBackend on a shared spawn is ignored (it is the same box). A
-    // machine-targeted top-level create labels the home "selfhosted"
-    // (machineHomeBackend), overriding the caller/deployment default so the row
-    // matches where the session actually runs.
-    sandboxBackend: inheritedBackend ?? machineHomeBackend ?? payload.sandboxBackend ?? settings.sandboxBackend,
-    // Mirror the backend relabel on the OS axis: only a machine-targeted
-    // top-level create carries a derived OS; everything else is omitted and the
-    // "linux" default holds (shared spawns keep the parent-box behavior).
-    ...machineHomeOs ? { sandboxOs: machineHomeOs } : {},
-    sandboxGroupId,
-    metadata: payload.metadata,
-    variableSet: variableSet ? { id: variableSet.id, name: variableSet.name } : null,
-    // Frozen rig binding (M3): both null for a rig-less session (today's path).
-    rigId: frozenRigId,
-    rigVersionId: frozenRigVersionId,
-    goal: payload.goal ?? null,
-    // Per-session persona instructions (already trimmed/validated by the
-    // contracts schema). Persisted on the row; composed system-level at turn
-    // time. Not surfaced as an event.
-    instructions: payload.instructions ?? null,
-    firstPartyMcpPermissions,
-    mcpServers: sessionMcpServers.dbServers,
-    sessionMcpServers: sessionMcpServers.metadata,
-    parentSessionId,
-    createIdempotencyKey: payload.idempotencyKey ?? null,
-    // Create-time machine targeting (A-2a): when a target sandbox is named, the
-    // active-sandbox pointer is seeded race-free inside createAndStartSession
-    // (after the row exists, before the first turn dispatches). Validation
-    // (ownership/liveness) lives in swapActiveSandbox; an invalid target 422s.
-    seedTargetSandbox: payload.targetSandboxId ? { sandboxId: payload.targetSandboxId, settings, workingDir: payload.workingDir ?? null } : null
-  });
+  const creationInitiator = creationInitiatorForGrant(grant);
+  let session;
+  try {
+    session = await createAndStartSession({
+      ...payload.requestedSessionId ? { requestedSessionId: payload.requestedSessionId } : {},
+      db,
+      bus,
+      workflowClient,
+      accountId: grant.accountId,
+      workspaceId,
+      initialMessage: payload.initialMessage,
+      turnInstructions: payload.turnInstructions ?? null,
+      resources,
+      tools,
+      ...payload.clientEventId ? { clientEventId: payload.clientEventId } : {},
+      model,
+      reasoningEffort,
+      // A shared spawn inherits the box's backend; a caller-supplied
+      // sandboxBackend on a shared spawn is ignored (it is the same box). A
+      // machine-targeted top-level create labels the home "selfhosted"
+      // (machineHomeBackend), overriding the caller/deployment default so the row
+      // matches where the session actually runs.
+      sandboxBackend: inheritedBackend ?? machineHomeBackend ?? payload.sandboxBackend ?? settings.sandboxBackend,
+      // Mirror the backend relabel on the OS axis: only a machine-targeted
+      // top-level create carries a derived OS; everything else is omitted and the
+      // "linux" default holds (shared spawns keep the parent-box behavior).
+      ...machineHomeOs ? { sandboxOs: machineHomeOs } : {},
+      sandboxGroupId,
+      metadata: payload.metadata,
+      ...creationInitiator.initiator ? { createdBy: creationInitiator.initiator } : {},
+      ...creationInitiator.context ? { createdByContext: creationInitiator.context } : {},
+      createdByActor: creationInitiator.actor ?? null,
+      variableSet: variableSet ? { id: variableSet.id, name: variableSet.name } : null,
+      // Frozen rig binding (M3): both null for a rig-less session (today's path).
+      rigId: frozenRigId,
+      rigVersionId: frozenRigVersionId,
+      goal: payload.goal ?? null,
+      // Per-session persona instructions (already trimmed/validated by the
+      // contracts schema). Persisted on the row; composed system-level at turn
+      // time. Not surfaced as an event.
+      instructions: payload.instructions ?? null,
+      firstPartyMcpPermissions,
+      mcpServers: sessionMcpServers.dbServers,
+      sessionMcpServers: sessionMcpServers.metadata,
+      parentSessionId,
+      createIdempotencyKey: payload.idempotencyKey ?? null,
+      // Create-time machine targeting (A-2a): when a target sandbox is named, the
+      // active-sandbox pointer is seeded race-free inside createAndStartSession
+      // (after the row exists, before the first turn dispatches). Validation
+      // (ownership/liveness) lives in swapActiveSandbox; an invalid target 422s.
+      seedTargetSandbox: payload.targetSandboxId ? { sandboxId: payload.targetSandboxId, settings, workingDir: payload.workingDir ?? null } : null
+    });
+  } catch (error) {
+    if (error instanceof AgentCommandAuthorityError) {
+      throw new HTTPException9(403, { message: error.message });
+    }
+    if (error instanceof SessionIdConflictError) {
+      throw new HTTPException9(409, {
+        message: "requested session id is already in use"
+      });
+    }
+    throw error;
+  }
   await recordWorkspaceUsage(deps, {
     accountId: grant.accountId,
     workspaceId,
@@ -3271,12 +3768,21 @@ async function createSessionForRequest(deps, grant, workspaceId, rawPayload) {
     unit: "run",
     sourceResourceType: "session",
     sourceResourceId: session.id,
+    sessionId: session.id,
+    initiator: session.createdBy,
+    initiatorContext: session.createdByContext,
+    origin: creationInitiator.actor ? "system" : "user",
     idempotencyKey: `agent_run.created:${workspaceId}:${session.id}`
   });
   return session;
 }
 async function acceptSessionUserMessage(deps, grant, workspaceId, sessionId, input) {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
+  await requireSessionAuthorization(deps, grant, {
+    sessionId,
+    operation: input.delivery === "steer" ? "session.steer" : "session.append",
+    surface: "core"
+  });
   const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(
     db,
     workspaceId,
@@ -3311,6 +3817,7 @@ async function acceptSessionUserMessage(deps, grant, workspaceId, sessionId, inp
     session: existingSession,
     updates: input.mcpCredentialUpdates ?? []
   });
+  const delegatedServiceInitiator = serviceInitiatorForGrant(grant);
   const { accepted, turn } = await postUserMessageTurn({
     db,
     bus,
@@ -3320,14 +3827,24 @@ async function acceptSessionUserMessage(deps, grant, workspaceId, sessionId, inp
     workspaceId,
     sessionId,
     text: input.text,
+    turnInstructions: input.turnInstructions ?? null,
     resources: requestedResources,
     tools: requestedTools,
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
     mcpCredentialUpdates,
     delivery: input.delivery ?? "send",
-    origin: input.origin ?? "human",
+    origin: delegatedServiceInitiator ? "operator" : input.origin ?? "human",
     actor: grant.subjectId,
+    ...grant.subjectLabel ? { actorLabel: grant.subjectLabel } : {},
+    ...delegatedServiceInitiator ? {
+      commandActor: {
+        type: "service",
+        subjectId: delegatedServiceInitiator.initiator.subjectId,
+        ...delegatedServiceInitiator.initiator.label ? { subjectLabel: delegatedServiceInitiator.initiator.label } : {},
+        context: delegatedServiceInitiator.context
+      }
+    } : {},
     ...input.controlEtag !== void 0 ? { controlEtag: input.controlEtag } : {},
     ...input.expectedDraftRevision !== void 0 ? { expectedDraftRevision: input.expectedDraftRevision } : {},
     ...input.clientEventId ? { clientEventId: input.clientEventId } : {}
@@ -3341,12 +3858,23 @@ async function acceptSessionUserMessage(deps, grant, workspaceId, sessionId, inp
     unit: "run",
     sourceResourceType: "session_turn",
     sourceResourceId: turn.id,
+    sessionId,
+    turnId: turn.id,
+    initiator: turn.initiator,
+    initiatorContext: turn.initiatorContext,
+    origin: turn.source,
     idempotencyKey: `agent_run.created:${workspaceId}:${turn.id}`
   });
   return { accepted, turn };
 }
-async function updateSessionTitle(deps, workspaceId, sessionId, title, source) {
+async function updateSessionTitle(deps, grant, sessionId, title, source) {
   const { db, bus } = deps;
+  const authorization = await requireSessionAuthorization(deps, grant, {
+    sessionId,
+    operation: "session.title.write",
+    surface: "core"
+  });
+  const workspaceId = grant.workspaceId;
   const result = await updateSessionTitleRow(db, { workspaceId, sessionId, title, source });
   if (result.updated) {
     await appendAndPublishEvents(db, bus, workspaceId, sessionId, [
@@ -3359,10 +3887,25 @@ async function updateSessionTitle(deps, workspaceId, sessionId, title, source) {
       }
     ]);
   }
-  return result;
+  return {
+    ...result,
+    relatedSessionAccess: authorization?.relatedSessionAccess ?? "root"
+  };
 }
-async function readSessionLineage(db, workspaceId, sessionId) {
-  const lineage = await getSessionLineage(db, workspaceId, sessionId);
+async function readSessionLineage(deps, grant, sessionId) {
+  const authorization = await requireSessionAuthorization(deps, grant, {
+    sessionId,
+    operation: "session.lineage.read",
+    surface: "core"
+  });
+  if (authorization?.relatedSessionAccess === "target") {
+    const session = await getSession2(deps.db, grant.workspaceId, sessionId);
+    if (!session) {
+      throw new HTTPException9(404, { message: "session not found" });
+    }
+    return { ancestors: [], children: [], truncated: false };
+  }
+  const lineage = await getSessionLineage(deps.db, grant.workspaceId, sessionId);
   if (!lineage) {
     throw new HTTPException9(404, { message: "session not found" });
   }
@@ -3651,13 +4194,15 @@ import {
   deleteSessionQueueItemInTransaction,
   editQueuedTurnInTransaction,
   getComposerDraftInTransaction,
-  getSession as getSession2,
+  getSession as getSession3,
   getSessionEvent as getSessionEvent2,
   getWorkspaceControlEvent as getWorkspaceControlEvent2,
   getSessionQueueSnapshot,
   moveQueuedTurnInTransaction,
   mutateSessionControlInTransaction,
   mutateWorkspaceControlInTransaction,
+  projectEffectiveControlForRelatedAccess,
+  runIdempotentPersistenceTransaction,
   saveComposerDraftInTransaction,
   sendAgentMessageInTransaction,
   serializeEffectiveSessionControl,
@@ -3670,6 +4215,42 @@ import {
   publishDurableSessionEvents as publishDurableSessionEvents2,
   publishDurableWorkspaceControlEvent as publishDurableWorkspaceControlEvent2
 } from "@opengeni/events";
+function humanAccessGrant(context) {
+  return {
+    accountId: context.accountId,
+    workspaceId: context.workspaceId,
+    subjectId: context.subjectId,
+    permissions: []
+  };
+}
+function agentAccessGrant(context) {
+  return {
+    accountId: context.accountId,
+    workspaceId: context.workspaceId,
+    subjectId: context.subjectId,
+    permissions: [],
+    metadata: {
+      sessionId: context.callerSessionId,
+      turnId: context.callerTurnId,
+      attemptId: context.callerAttemptId,
+      executionGeneration: context.callerExecutionGeneration
+    }
+  };
+}
+async function authorizeHumanSessionCommand(deps, context, operation) {
+  return await requireSessionAuthorization(deps, humanAccessGrant(context), {
+    sessionId: context.sessionId,
+    operation,
+    surface: "core"
+  });
+}
+async function authorizeAgentSessionCommand(deps, context, targetSessionId, operation) {
+  return await requireSessionAuthorization(deps, agentAccessGrant(context), {
+    sessionId: targetSessionId,
+    operation,
+    surface: "core"
+  });
+}
 function agentActor(context) {
   return {
     type: "agent_attempt",
@@ -3679,6 +4260,20 @@ function agentActor(context) {
     executionGeneration: context.callerExecutionGeneration
   };
 }
+async function runAgentCommandPersistenceTransaction(deps, context, input) {
+  return await runIdempotentPersistenceTransaction(
+    {
+      stage: input.stage,
+      eventTypes: input.eventTypes,
+      maxAttempts: 3
+    },
+    async () => await withWorkspaceRls(
+      deps.db,
+      context.workspaceId,
+      async (scoped) => scoped.transaction(async (tx) => await input.transaction(tx))
+    )
+  );
+}
 async function publishAndWakeAgentCommand(deps, input) {
   await publishSessionEventIds(deps, input.workspaceId, input.sessionId, input.eventIds);
   if (!input.shouldSignal || input.wakeRevision === null) return;
@@ -3730,20 +4325,19 @@ async function publishWorkspaceControlEvent(deps, workspaceId, eventId) {
   await publishDurableWorkspaceControlEvent2(deps.bus, workspaceId, event);
 }
 async function sendAgentSessionMessage(deps, context, input) {
-  const result = await withWorkspaceRls(
-    deps.db,
-    context.workspaceId,
-    (scoped) => scoped.transaction(
-      (tx) => sendAgentMessageInTransaction(tx, {
-        accountId: context.accountId,
-        workspaceId: context.workspaceId,
-        targetSessionId: input.targetSessionId,
-        actor: agentActor(context),
-        operationKey: input.idempotencyKey,
-        text: input.text
-      })
-    )
-  );
+  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
+    })
+  });
   await publishAndWakeAgentCommand(deps, {
     accountId: context.accountId,
     workspaceId: context.workspaceId,
@@ -3758,20 +4352,19 @@ async function sendAgentSessionMessage(deps, context, input) {
   return result;
 }
 async function steerAgentSession(deps, context, input) {
-  const result = await withWorkspaceRls(
-    deps.db,
-    context.workspaceId,
-    (scoped) => scoped.transaction(
-      (tx) => steerAgentSessionInTransaction(tx, {
-        accountId: context.accountId,
-        workspaceId: context.workspaceId,
-        targetSessionId: input.targetSessionId,
-        actor: agentActor(context),
-        operationKey: input.idempotencyKey,
-        instruction: input.instruction
-      })
-    )
-  );
+  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
+    })
+  });
   await publishAndWakeAgentCommand(deps, {
     accountId: context.accountId,
     workspaceId: context.workspaceId,
@@ -3786,6 +4379,7 @@ async function steerAgentSession(deps, context, input) {
   return result;
 }
 async function controlAgentSessionWorkstream(deps, context, input) {
+  await authorizeAgentSessionCommand(deps, context, input.targetSessionId, "session.control");
   const result = await withWorkspaceRls(
     deps.db,
     context.workspaceId,
@@ -3836,12 +4430,20 @@ function composerDraft(row) {
     updatedAt: row.updatedAt.toISOString()
   };
 }
-async function authoritativeQueue(db, workspaceId, sessionId) {
+async function authoritativeQueue(db, workspaceId, sessionId, relatedSessionAccess) {
   const snapshot = await getSessionQueueSnapshot(db, workspaceId, sessionId);
   if (!snapshot) throw new Error(`Session not found: ${sessionId}`);
-  return snapshot;
+  return {
+    ...snapshot,
+    effectiveControl: projectEffectiveControlForRelatedAccess(
+      snapshot.effectiveControl,
+      sessionId,
+      relatedSessionAccess
+    )
+  };
 }
 async function moveHumanQueuePrompt(deps, context, turnId, input) {
+  const authorization = await authorizeHumanSessionCommand(deps, context, "session.queue.control");
   const result = await withWorkspaceRls(
     deps.db,
     context.workspaceId,
@@ -3858,12 +4460,18 @@ async function moveHumanQueuePrompt(deps, context, turnId, input) {
   );
   const response = {
     receipt: receipt(result.receipt),
-    snapshot: await authoritativeQueue(deps.db, context.workspaceId, context.sessionId)
+    snapshot: await authoritativeQueue(
+      deps.db,
+      context.workspaceId,
+      context.sessionId,
+      authorization?.relatedSessionAccess ?? "root"
+    )
   };
   await publishSessionEventIds(deps, context.workspaceId, context.sessionId, result.eventIds);
   return response;
 }
 async function deleteHumanQueuePrompt(deps, context, turnId, input) {
+  const authorization = await authorizeHumanSessionCommand(deps, context, "session.queue.control");
   const result = await withWorkspaceRls(
     deps.db,
     context.workspaceId,
@@ -3880,12 +4488,18 @@ async function deleteHumanQueuePrompt(deps, context, turnId, input) {
   );
   const response = {
     receipt: receipt(result.receipt),
-    snapshot: await authoritativeQueue(deps.db, context.workspaceId, context.sessionId)
+    snapshot: await authoritativeQueue(
+      deps.db,
+      context.workspaceId,
+      context.sessionId,
+      authorization?.relatedSessionAccess ?? "root"
+    )
   };
   await publishSessionEventIds(deps, context.workspaceId, context.sessionId, result.eventIds);
   return response;
 }
 async function editHumanQueuePrompt(deps, context, turnId, input) {
+  const authorization = await authorizeHumanSessionCommand(deps, context, "session.queue.control");
   const result = await withWorkspaceSubjectRls2(
     deps.db,
     context.workspaceId,
@@ -3904,13 +4518,19 @@ async function editHumanQueuePrompt(deps, context, turnId, input) {
   );
   const response = {
     receipt: receipt(result.receipt),
-    snapshot: await authoritativeQueue(deps.db, context.workspaceId, context.sessionId),
+    snapshot: await authoritativeQueue(
+      deps.db,
+      context.workspaceId,
+      context.sessionId,
+      authorization?.relatedSessionAccess ?? "root"
+    ),
     draft: composerDraft(result.draft)
   };
   await publishSessionEventIds(deps, context.workspaceId, context.sessionId, result.eventIds);
   return response;
 }
 async function steerHumanQueuePrompt(deps, context, turnId, input) {
+  const authorization = await authorizeHumanSessionCommand(deps, context, "session.queue.control");
   const result = await withWorkspaceRls(
     deps.db,
     context.workspaceId,
@@ -3927,13 +4547,19 @@ async function steerHumanQueuePrompt(deps, context, turnId, input) {
   );
   const response = {
     receipt: receipt(result.receipt),
-    snapshot: await authoritativeQueue(deps.db, context.workspaceId, context.sessionId)
+    snapshot: await authoritativeQueue(
+      deps.db,
+      context.workspaceId,
+      context.sessionId,
+      authorization?.relatedSessionAccess ?? "root"
+    )
   };
   await publishSessionEventIds(deps, context.workspaceId, context.sessionId, result.eventIds);
   await publishWorkspaceControlEvent(deps, context.workspaceId, result.workspaceControlEventId);
   return response;
 }
 async function controlHumanSessionWorkstream(deps, context, input) {
+  const authorization = await authorizeHumanSessionCommand(deps, context, "session.control");
   const result = await withWorkspaceRls(
     deps.db,
     context.workspaceId,
@@ -3952,7 +4578,11 @@ async function controlHumanSessionWorkstream(deps, context, input) {
   );
   const response = {
     receipt: receipt(result.receipt),
-    effectiveControl: serializeEffectiveSessionControl(result.control),
+    effectiveControl: projectEffectiveControlForRelatedAccess(
+      serializeEffectiveSessionControl(result.control),
+      context.sessionId,
+      authorization?.relatedSessionAccess ?? "root"
+    ),
     interruptionCount: result.interruptionCount,
     wakeCount: result.wakeCount
   };
@@ -3990,9 +4620,10 @@ async function controlHumanWorkspace(deps, context, input) {
   await requestControlWakeDispatch(deps, result.wakeCount);
   return response;
 }
-async function getHumanComposerDraft(db, context) {
+async function getHumanComposerDraft(deps, context) {
+  await authorizeHumanSessionCommand(deps, context, "session.composer.read");
   const row = await withWorkspaceSubjectRls2(
-    db,
+    deps.db,
     context.workspaceId,
     context.subjectId,
     (scoped) => getComposerDraftInTransaction(scoped, {
@@ -4003,7 +4634,7 @@ async function getHumanComposerDraft(db, context) {
   );
   const mapped = composerDraft(row);
   if (mapped) return mapped;
-  const session = await getSession2(db, context.workspaceId, context.sessionId);
+  const session = await getSession3(deps.db, context.workspaceId, context.sessionId);
   if (!session) throw new Error(`Session not found: ${context.sessionId}`);
   return {
     revision: 0,
@@ -4017,9 +4648,10 @@ async function getHumanComposerDraft(db, context) {
     updatedAt: null
   };
 }
-async function saveHumanComposerDraft(db, context, input) {
+async function saveHumanComposerDraft(deps, context, input) {
+  await authorizeHumanSessionCommand(deps, context, "session.composer.write");
   const row = await withWorkspaceSubjectRls2(
-    db,
+    deps.db,
     context.workspaceId,
     context.subjectId,
     (scoped) => scoped.transaction(
@@ -4040,9 +4672,12 @@ export {
   MAX_ENVIRONMENTS_PER_WORKSPACE,
   MAX_RIGS_PER_WORKSPACE,
   MAX_VARIABLES_PER_ENVIRONMENT,
+  SESSION_AUTHORIZATION_DEFAULT_REAUTHORIZE_MS,
   SESSION_WORKFLOW_WAKE_DISPATCHER_PERIOD_MS,
   SESSION_WORKFLOW_WAKE_DISPATCHER_SCHEDULE_ID,
   SESSION_WORKFLOW_WAKE_DISPATCHER_WORKFLOW_TYPE,
+  SessionAuthorizationDeniedError,
+  SessionAuthorizationUnavailableError,
   acceptSessionUserMessage,
   activateRigVersionForApi,
   appendRigSetupCommand,
@@ -4114,6 +4749,8 @@ export {
   requireRigChangeForApi,
   requireRigForApi,
   requireScheduledTaskForApi,
+  requireSessionAuthorization,
+  requireSessionAuthorizationListScope,
   requireVariableSetEncryption,
   requireVariableSetForApi,
   resolveCapabilityPack,
@@ -4141,6 +4778,7 @@ export {
   validateFileResources,
   validateGitHubRepositorySelection,
   validateGitHubRepositorySelectionShape,
+  validateGitHubRepositorySelectionShapes,
   validateMcpCapabilityConnection,
   validateToolRefs,
   validateVariableSetAttachment,