@opengeni/core 0.28.1 → 1.0.0

package/src/domain/company-profile-agent-admin.ts

@@ -0,0 +1,56 @@
+import {
+  CompanyProfileAgentAttempt,
+  CompanyProfileAgentConfirmRequest,
+  CompanyProfileAgentProposalRequest,
+  type CompanyProfileAgentConfirmationReceipt,
+  type CompanyProfileAgentProposalReceipt,
+} from "@opengeni/contracts";
+import {
+  confirmCompanyProfileForAgent,
+  proposeCompanyProfileForAgent,
+  type Database,
+} from "@opengeni/db";
+export { CompanyProfileAgentAdminError } from "@opengeni/db";
+
+export type CompanyProfileAgentAdminRouterOptions = {
+  db: Database;
+  propose?: typeof proposeCompanyProfileForAgent;
+  confirm?: typeof confirmCompanyProfileForAgent;
+};
+
+/**
+ * Explicit organization administration is intentionally separate from derived
+ * workspace learning. The database capabilities own exact-attempt admission,
+ * current organization-owner authority, the separate organization policy,
+ * canonical review when required, tenant isolation, CAS, and immutable
+ * receipts.
+ */
+export function createCompanyProfileAgentAdminRouter(
+  options: CompanyProfileAgentAdminRouterOptions,
+): {
+  propose: (input: {
+    attempt: unknown;
+    request: unknown;
+  }) => Promise<CompanyProfileAgentProposalReceipt>;
+  confirm: (input: {
+    attempt: unknown;
+    request: unknown;
+  }) => Promise<CompanyProfileAgentConfirmationReceipt>;
+} {
+  const propose = options.propose ?? proposeCompanyProfileForAgent;
+  const confirm = options.confirm ?? confirmCompanyProfileForAgent;
+  return {
+    async propose(input) {
+      return await propose(options.db, {
+        attempt: CompanyProfileAgentAttempt.parse(input.attempt),
+        request: CompanyProfileAgentProposalRequest.parse(input.request),
+      });
+    },
+    async confirm(input) {
+      return await confirm(options.db, {
+        attempt: CompanyProfileAgentAttempt.parse(input.attempt),
+        request: CompanyProfileAgentConfirmRequest.parse(input.request),
+      });
+    },
+  };
+}

package/src/domain/connection-account-selection-error.ts

@@ -0,0 +1,19 @@
+import { HTTPException } from "hono/http-exception";
+import { ConnectionAccountSelectionDiagnostic } from "@opengeni/contracts";
+
+/** An account choice needs attention; retrying the same work cannot fix it. */
+export class ConnectionAccountSelectionError extends HTTPException {
+  override name = "ConnectionAccountSelectionError";
+  readonly diagnostic: ConnectionAccountSelectionDiagnostic;
+  constructor(
+    message: string,
+    diagnostic: ConnectionAccountSelectionDiagnostic = {
+      version: 1,
+      reason: "selection_unavailable",
+      accounts: [],
+    },
+  ) {
+    super(422, { message });
+    this.diagnostic = ConnectionAccountSelectionDiagnostic.parse(diagnostic);
+  }
+}

package/src/domain/connector-tool-permissions.ts

@@ -0,0 +1,371 @@
+import { slackRestMcpToolsForScopes } from "@opengeni/contracts/slack-rest-mcp";
+import { createHash } from "node:crypto";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import {
+  boundMcpResponseBody,
+  MCP_MAX_RESPONSE_BYTES,
+  assertMcpToolListWithinBounds,
+} from "@opengeni/runtime/mcp-network";
+import { createPinnedIntegrationTransport } from "@opengeni/capabilities";
+import type { Settings } from "@opengeni/config";
+import type {
+  AccessGrant,
+  ConnectorToolPermission,
+  ConnectorToolPermissionEntry,
+  ConnectorToolPermissionsResponse,
+  UpdateConnectorToolPermissionsRequest,
+  ConnectionMetadata,
+  McpServerConnectionRef,
+} from "@opengeni/contracts";
+import {
+  buildConnectionTokenResolver,
+  getConnectionMetadata,
+  listConnectionsMetadata,
+  listEnabledMcpCapabilityServers,
+  listConnectorToolPermissionPolicies,
+  updateConnectorToolPermissionPolicies,
+  resolveConnectorActionPolicy,
+  type Database,
+} from "@opengeni/db";
+import { HTTPException } from "hono/http-exception";
+import {
+  GMAIL_REST_MCP_TOOLS,
+  gmailToolSupportsScopes,
+  isOfficialGmailMcpConfig,
+  isOfficialSlackMcpConfig,
+} from "@opengeni/runtime";
+import { hasPermission } from "../access";
+import { buildCapabilityCatalog, settingsWithMcpCapabilityServers } from "./capabilities";
+
+type Input = {
+  db: Database;
+  settings: Settings;
+  workspaceId: string;
+  grant: AccessGrant;
+  capabilityId: string;
+  personalOwnerVerified: boolean;
+};
+type ListedTool = {
+  name: string;
+  title?: string | undefined;
+  description?: string | undefined;
+  annotations?:
+    | {
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        title?: string | undefined;
+      }
+    | undefined;
+};
+
+export function connectorToolGroup(tool: ListedTool): "read" | "write" | "other" {
+  if (tool.annotations?.destructiveHint === true || tool.annotations?.readOnlyHint === false)
+    return "write";
+  if (tool.annotations?.readOnlyHint === true) return "read";
+  return "other";
+}
+
+/** A selector can supply discovery credentials only when one visible account
+ * matches. Never apply one account's approval choices to an arbitrary sibling. */
+export function unpinnedConnectorToolPermissionAccount<T extends ConnectionMetadata>(
+  ref: McpServerConnectionRef,
+  visible: T[],
+  subjectId: string,
+): T | null {
+  const matches = visible.filter(
+    (candidate) =>
+      candidate.subjectId === (ref.subjectScope === "subject" ? subjectId : null) &&
+      candidate.providerDomain === ref.providerDomain &&
+      (!ref.kind || candidate.kind === ref.kind) &&
+      candidate.status === "active",
+  );
+  if (matches.length > 1)
+    throw new HTTPException(409, {
+      message: "Choose one account to manage its tool permissions",
+    });
+  return matches[0] ?? null;
+}
+
+export function connectorToolPermissionReference(
+  ref: McpServerConnectionRef,
+  connectionId: string,
+): McpServerConnectionRef {
+  return { ...ref, accountSelection: undefined, connectionId };
+}
+
+async function resolveTarget(input: Input) {
+  if (input.capabilityId.startsWith("api:")) {
+    // API Integrations are not MCP connectors: their per-tool approval is part
+    // of the reviewed installation, not this connector policy surface.
+    throw new HTTPException(404, {
+      message:
+        "Connected MCP connector not found; API Integration tool approval is set with installApiIntegration autoApprovedTools",
+    });
+  }
+  const catalog = await buildCapabilityCatalog(input);
+  const item = catalog.items.find((candidate) => candidate.id === input.capabilityId);
+  if (
+    !item ||
+    !item.enabled ||
+    item.kind !== "mcp" ||
+    !item.runtime.mcpServerId ||
+    item.source === "built_in"
+  ) {
+    throw new HTTPException(404, { message: "Connected MCP connector not found" });
+  }
+  const enabled = await listEnabledMcpCapabilityServers(input.db, input.workspaceId);
+  const settings = settingsWithMcpCapabilityServers(input.settings, enabled);
+  const server = settings.mcpServers.find((candidate) => candidate.id === item.runtime.mcpServerId);
+  if (!server || server.url !== item.endpointUrl)
+    throw new HTTPException(409, { message: "Connector configuration is unavailable" });
+  const ref = server.connectionRef;
+  if (ref?.authoritySource === "host")
+    throw new HTTPException(409, {
+      message: "Tool permissions for this connection are managed by its host",
+    });
+  let connection = ref?.connectionId
+    ? await getConnectionMetadata(
+        input.db,
+        input.workspaceId,
+        ref.connectionId,
+        input.grant.subjectId,
+      )
+    : null;
+  if (
+    ref &&
+    !ref.connectionId &&
+    (ref.subjectScope === "subject" || ref.accountSelection === "all_eligible")
+  ) {
+    const visible = await listConnectionsMetadata(
+      input.db,
+      input.workspaceId,
+      input.grant.subjectId,
+    );
+    connection = unpinnedConnectorToolPermissionAccount(ref, visible, input.grant.subjectId);
+  }
+  if (
+    ref &&
+    (!connection ||
+      connection.providerDomain !== ref.providerDomain ||
+      (ref.kind && connection.kind !== ref.kind) ||
+      (ref.subjectScope === "subject"
+        ? connection.subjectId !== input.grant.subjectId
+        : connection.subjectId !== null))
+  ) {
+    throw new HTTPException(409, { message: "Reconnect this connector to manage its tools" });
+  }
+  if (connection?.subjectId && !input.personalOwnerVerified)
+    throw new HTTPException(403, {
+      message: "Only the authenticated connection owner may manage personal tool permissions",
+    });
+  // Same secret-free target identity used by runtime sessionMcpApprovalConnectionId.
+  const connectionId =
+    connection?.id ??
+    `session-mcp:${server.id}:${createHash("sha256").update(server.url, "utf8").digest("hex")}`;
+  return { server, connection, connectionId };
+}
+
+/** Use the same adapter-owned identities as execution for reviewed local catalogs. */
+export function reviewedConnectorToolCatalog(
+  server: Pick<Settings["mcpServers"][number], "url" | "connectionRef" | "allowedTools">,
+  grantedScopes: readonly string[],
+): ListedTool[] | null {
+  const tools = isOfficialGmailMcpConfig(server.url, server.connectionRef)
+    ? GMAIL_REST_MCP_TOOLS.filter((tool) => gmailToolSupportsScopes(tool.name, grantedScopes))
+    : isOfficialSlackMcpConfig(server.url, server.connectionRef)
+      ? slackRestMcpToolsForScopes(grantedScopes)
+      : null;
+  return (
+    tools?.filter((tool) => !server.allowedTools || server.allowedTools.includes(tool.name)) ?? null
+  );
+}
+
+async function listTools(
+  input: Input,
+  target: Awaited<ReturnType<typeof resolveTarget>>,
+): Promise<ListedTool[]> {
+  const reviewed = reviewedConnectorToolCatalog(
+    target.server,
+    target.connection?.grantedScopes ?? [],
+  );
+  if (reviewed !== null) return reviewed;
+  let headers = { ...target.server.headers };
+  if (target.server.connectionRef) {
+    const result = await buildConnectionTokenResolver(
+      input.db,
+      input.settings,
+    )({
+      workspaceId: input.workspaceId,
+      ...(target.connection?.subjectId ? { subjectId: input.grant.subjectId } : {}),
+      serverId: target.server.id,
+      toolName: "tools/list",
+      connectionRef: connectorToolPermissionReference(
+        target.server.connectionRef,
+        target.connectionId,
+      ),
+      destinationUrl: target.server.url,
+    });
+    if (result.status !== "ok") throw new Error("Reconnect this connector to load its tools.");
+    headers = { ...headers, ...result.headers };
+  }
+  const pinned = createPinnedIntegrationTransport({ network: input.settings });
+  const deadline = AbortSignal.timeout(15_000);
+  const client = new Client(
+    { name: "opengeni-tool-permissions", version: "0.1.0" },
+    { capabilities: {} },
+  );
+  try {
+    const transport = new StreamableHTTPClientTransport(new URL(target.server.url), {
+      requestInit: { headers },
+      fetch: async (url, init) =>
+        boundMcpResponseBody(
+          await pinned.fetch(url.toString(), {
+            ...init,
+            signal: init?.signal ? AbortSignal.any([deadline, init.signal]) : deadline,
+          }),
+          MCP_MAX_RESPONSE_BYTES,
+        ),
+    });
+    await client.connect(transport as unknown as Transport, {
+      timeout: 15_000,
+      maxTotalTimeout: 15_000,
+    });
+    const tools = await collectConnectorToolPages(client, deadline);
+    return tools.filter(
+      (tool) => !target.server.allowedTools || target.server.allowedTools.includes(tool.name),
+    );
+  } finally {
+    await client.close().catch(() => undefined);
+  }
+}
+
+/** Collect discovery pages without changing the caller's connection or authority. */
+export async function collectConnectorToolPages(
+  client: Pick<Client, "listTools">,
+  deadline: AbortSignal,
+): Promise<ListedTool[]> {
+  const tools: ListedTool[] = [];
+  const cursors = new Set<string>();
+  let cursor: string | undefined;
+  do {
+    const page = await client.listTools(cursor ? { cursor } : undefined, {
+      timeout: 15_000,
+      maxTotalTimeout: 15_000,
+      signal: deadline,
+    });
+    tools.push(...page.tools);
+    assertMcpToolListWithinBounds(tools);
+    if (new Set(tools.map((tool) => tool.name)).size !== tools.length)
+      throw new Error("The connector returned duplicate tool names.");
+    cursor = page.nextCursor;
+    if (cursor && cursors.has(cursor))
+      throw new Error("The connector returned an invalid or oversized tool catalog.");
+    if (cursor) cursors.add(cursor);
+  } while (cursor);
+  return tools;
+}
+
+export async function getConnectorToolPermissions(
+  input: Input,
+): Promise<ConnectorToolPermissionsResponse> {
+  const target = await resolveTarget(input);
+  const policies = await listConnectorToolPermissionPolicies(input.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.workspaceId,
+    connectionId: target.connectionId,
+  });
+  const permission = (
+    name: string,
+  ): { permission: ConnectorToolPermission; inherited: boolean } => {
+    const resolved = resolveConnectorActionPolicy(policies, {
+      connectionId: target.connectionId,
+      serverId: target.server.id,
+      toolName: name,
+      actionName: "*",
+    });
+    if (!resolved.managed) return { permission: "allow", inherited: true };
+    return {
+      permission: resolved.entry?.policy ?? "block",
+      inherited: resolved.entry?.toolName !== name,
+    };
+  };
+  const defaultPolicy = policies.find(
+    (row) => row.serverId === target.server.id && row.toolName === "*" && row.actionName === "*",
+  );
+  let tools: ListedTool[] = [];
+  let discoveryError: string | null = null;
+  try {
+    tools = await listTools(input, target);
+    if (tools.some((tool) => tool.name === "*" || tool.name !== tool.name.trim())) {
+      tools = tools.filter((tool) => tool.name !== "*" && tool.name === tool.name.trim());
+      discoveryError =
+        "The connector exposes a reserved or whitespace-padded tool name. Individual permissions for these names are unsupported, so they are omitted from tool groups. The connector default still applies.";
+    }
+  } catch {
+    discoveryError =
+      "Could not load the connector's tools. Try again or reconnect. Your saved permissions still apply.";
+  }
+  return {
+    connectionId: target.connectionId,
+    serverId: target.server.id,
+    defaultPermission: defaultPolicy?.policy ?? null,
+    tools: tools.map(
+      (tool): ConnectorToolPermissionEntry => ({
+        name: tool.name,
+        ...((tool.title ?? tool.annotations?.title)
+          ? { title: tool.title ?? tool.annotations?.title }
+          : {}),
+        ...(tool.description ? { description: tool.description } : {}),
+        group: connectorToolGroup(tool),
+        ...permission(tool.name),
+        approvalRequired:
+          target.server.requireApproval === true ||
+          (Array.isArray(target.server.requireApproval) &&
+            target.server.requireApproval.includes(tool.name)),
+      }),
+    ),
+    discoveryError,
+    canManage: canManageConnectorPermissions(input.grant),
+  };
+}
+
+function canManageConnectorPermissions(grant: AccessGrant): boolean {
+  return (
+    hasPermission(grant.permissions, "capabilities:manage") &&
+    grant.principalKind !== "agent_attempt" &&
+    grant.principalKind !== "service" &&
+    !grant.serviceInitiator &&
+    !grant.serviceInitiatorContext
+  );
+}
+
+export async function updateConnectorToolPermissions(
+  input: Input & { payload: UpdateConnectorToolPermissionsRequest },
+): Promise<void> {
+  if (!canManageConnectorPermissions(input.grant))
+    throw new HTTPException(403, { message: "Connector management permission required" });
+  if (
+    input.payload.target === "tools" &&
+    input.payload.toolNames.some((name) => name === "*" || name !== name.trim())
+  )
+    throw new HTTPException(400, {
+      message: "Tool names must be exact and cannot use the connector-default wildcard.",
+    });
+  const target = await resolveTarget(input);
+  // Prevent a reconnect while the sheet is open from applying old choices to a new account.
+  if (target.connectionId !== input.payload.connectionId)
+    throw new HTTPException(409, {
+      message: "The connector account changed. Reload its permissions.",
+    });
+  await updateConnectorToolPermissionPolicies(input.db, {
+    accountId: input.grant.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.grant.subjectId,
+    connectionId: target.connectionId,
+    serverId: target.server.id,
+    toolNames: input.payload.target === "default" ? ["*"] : input.payload.toolNames,
+    policy: input.payload.permission,
+  });
+}

package/src/domain/direct-model-provider.ts

@@ -0,0 +1,62 @@
+import { DirectModelProviderMetadata } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+
+/** Verify the customer's exact route without persisting their key or test response. */
+export async function verifyDirectModelAccess(
+  input: DirectModelProviderMetadata,
+  apiKey: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  const config = DirectModelProviderMetadata.parse(input);
+  const baseUrl = config.provider === "openai" ? "https://api.openai.com/v1" : config.endpoint!;
+  let response: Response;
+  try {
+    response = await fetchImpl(`${baseUrl}/responses`, {
+      method: "POST",
+      redirect: "error",
+      signal: AbortSignal.timeout(15_000),
+      headers: {
+        "content-type": "application/json",
+        ...(config.provider === "openai"
+          ? { authorization: `Bearer ${apiKey}` }
+          : { "api-key": apiKey }),
+      },
+      body: JSON.stringify({
+        model: config.model,
+        input: "Reply OK.",
+        max_output_tokens: 32,
+        store: false,
+      }),
+    });
+  } catch {
+    throw new HTTPException(502, {
+      message: "We couldn’t reach your model provider. Check the endpoint and try again.",
+    });
+  }
+  // Never reflect provider responses: they can include credentials or request details.
+  if (response.status === 401 || response.status === 403) {
+    throw new HTTPException(422, {
+      message: "Your provider didn’t accept this API key. Check the key and its permissions.",
+    });
+  }
+  if (response.status === 404 || response.status === 400) {
+    throw new HTTPException(422, {
+      message:
+        config.provider === "azure_openai"
+          ? "Azure couldn’t use this deployment. Check the endpoint and deployment name."
+          : "OpenAI couldn’t use this model. Check the model name and your account’s access.",
+    });
+  }
+  if (response.status === 429) {
+    throw new HTTPException(422, {
+      message:
+        "Your provider’s quota or rate limit blocked the check. Check your provider billing or try again shortly.",
+    });
+  }
+  const body = response.ok ? await response.json().catch(() => null) : null;
+  if (!body || !["completed", "incomplete"].includes(body.status)) {
+    throw new HTTPException(502, {
+      message: "Your provider couldn’t complete the connection check. Try again shortly.",
+    });
+  }
+}

package/src/domain/editable-artifacts/agent-application.ts

@@ -1,14 +1,12 @@
 import { createHash } from "node:crypto";
 
-import {
-  COMMITTED_TRANSACTION_PROTOCOL_VERSION,
-  EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,
-} from "@opengeni/contracts/editable-artifact-versions";
 import {
   DOCUMENT_ARTIFACT_COMMAND_VERSION,
+  EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION,
   EDITABLE_ARTIFACT_INTENT_VERSION,
   PRESENTATION_ARTIFACT_COMMAND_VERSION,
   SPREADSHEET_ARTIFACT_COMMAND_VERSION,
+  currentEditableArtifactCompatibility,
   decodeEditableArtifactMutationIntent,
   decodeDocumentArtifactQueryResponse,
   decodePresentationArtifactQueryResponse,
@@ -28,10 +26,10 @@ import {
   type SpreadsheetArtifactKernelQuery,
 } from "@opengeni/contracts/editable-artifacts";
 
-import type {
-  EditableArtifactDurableExportService,
-  EditableArtifactMaterializationFormat,
-  EditableArtifactMaterializationJob,
+import {
+  type EditableArtifactDurableExportService,
+  type EditableArtifactMaterializationFormat,
+  type EditableArtifactMaterializationJob,
 } from "./durable-export";
 import {
   EditableArtifactDomainError,
@@ -78,6 +76,7 @@ export type EditableArtifactAgentContext = Readonly<{
 
 export type EditableArtifactAgentMetadata = Readonly<{
   id: string;
+  artifactReference: string;
   modality: EditableArtifactModality;
   title: string;
   lifecycle: EditableArtifact["lifecycle"];
@@ -176,6 +175,14 @@ export type EditableArtifactAgentApplicationDependencies = Readonly<{
   exports: EditableArtifactDurableExportService;
   associations: EditableArtifactAgentAssociationPort;
   inspector: EditableArtifactAgentInspectionKernelPort;
+  /** Production persists proof only after a successful native query. */
+  recordInspection?: (
+    input: EditableArtifactAgentContext & {
+      artifact: EditableArtifactAgentMetadata;
+      queryHash: string;
+      queryKind: string;
+    },
+  ) => Promise<string>;
   officeImports: EditableArtifactOfficeImportPort;
   workspaceFiles: EditableArtifactAgentWorkspaceFilePort;
 }>;
@@ -185,6 +192,9 @@ export type EditableArtifactAgentApplicationDependencies = Readonly<{
  * not another artifact engine: every mutation terminates at EditableArtifactService.
  */
 export class EditableArtifactAgentApplication {
+  describeExportFormats(): string {
+    return this.dependencies.exports.describeFormats();
+  }
   constructor(private readonly dependencies: EditableArtifactAgentApplicationDependencies) {}
 
   async list(
@@ -293,7 +303,13 @@ export class EditableArtifactAgentApplication {
   async inspect(
     input: EditableArtifactAgentContext &
       Readonly<{ artifactId: EditableArtifactId; request: EditableArtifactAgentQuery }>,
-  ): Promise<Readonly<{ artifact: EditableArtifactAgentMetadata; projection: unknown }>> {
+  ): Promise<
+    Readonly<{
+      artifact: EditableArtifactAgentMetadata;
+      projection: unknown;
+      inspectionReceiptId?: string;
+    }>
+  > {
     const context = agentContext(input);
     const artifactId = editableArtifactId(input.artifactId);
     const state = await this.dependencies.domain.readCurrentKernelState({
@@ -306,8 +322,21 @@ export class EditableArtifactAgentApplication {
     const queryBytes = encodeQuery(input.request);
     const responseBytes = await this.dependencies.inspector.query({ state, queryBytes });
     const projection = decodeQueryResponse(input.request.modality, responseBytes);
+    const inspectionReceiptId =
+      state.modality === "document"
+        ? await this.dependencies.recordInspection?.({
+            ...context,
+            artifact: projectArtifact(state.artifact),
+            queryHash: createHash("sha256").update(queryBytes).digest("hex"),
+            queryKind: input.request.query.kind,
+          })
+        : undefined;
     await this.touch(context, artifactId);
-    return Object.freeze({ artifact: projectArtifact(state.artifact), projection });
+    return Object.freeze({
+      artifact: projectArtifact(state.artifact),
+      projection,
+      ...(inspectionReceiptId ? { inspectionReceiptId } : {}),
+    });
   }
 
   async apply(
@@ -364,8 +393,9 @@ export class EditableArtifactAgentApplication {
     }
     const authored = hashEditableArtifactMutationIntent({
       envelopeVersion: EDITABLE_ARTIFACT_INTENT_VERSION,
-      protocolVersion: COMMITTED_TRANSACTION_PROTOCOL_VERSION,
-      modelSchemaVersion: EDITABLE_ARTIFACT_MODEL_SCHEMA_VERSION,
+      protocolVersion: EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION,
+      modelSchemaVersion: currentEditableArtifactCompatibility(input.batch.modality)
+        .modelSchemaVersion,
       commandProtocolVersion: commandProtocolVersion(input.batch.modality),
       artifactId,
       clientTransactionId,
@@ -446,6 +476,12 @@ export class EditableArtifactAgentApplication {
       actor: context.actor,
       artifactId,
     });
+    // Refuse before pinning a version: the agent learns what does exist.
+    await this.dependencies.exports.preflight({
+      modality: artifact.modality,
+      format: input.format,
+      ...(input.options ? { options: input.options } : {}),
+    });
     const version = await this.dependencies.exports.pinVersion({
       scope: context.scope,
       actor: context.actor,
@@ -564,12 +600,21 @@ function agentContext(input: EditableArtifactAgentContext): EditableArtifactAgen
 
 function encodeCommands(batch: EditableArtifactAgentCommandBatch): Uint8Array {
   if (batch.modality === "spreadsheet") {
-    return encodeSpreadsheetArtifactCommandBatch({ version: 1, commands: batch.commands });
+    return encodeSpreadsheetArtifactCommandBatch({
+      version: SPREADSHEET_ARTIFACT_COMMAND_VERSION,
+      commands: batch.commands,
+    });
   }
   if (batch.modality === "document") {
-    return encodeDocumentArtifactCommandBatch({ version: 1, commands: batch.commands });
+    return encodeDocumentArtifactCommandBatch({
+      version: DOCUMENT_ARTIFACT_COMMAND_VERSION,
+      commands: batch.commands,
+    });
   }
-  return encodePresentationArtifactCommandBatch({ version: 1, commands: batch.commands });
+  return encodePresentationArtifactCommandBatch({
+    version: PRESENTATION_ARTIFACT_COMMAND_VERSION,
+    commands: batch.commands,
+  });
 }
 
 function encodeQuery(request: EditableArtifactAgentQuery): Uint8Array {
@@ -595,6 +640,7 @@ function commandProtocolVersion(modality: EditableArtifactModality): number {
 function projectArtifact(artifact: EditableArtifact): EditableArtifactAgentMetadata {
   return Object.freeze({
     id: artifact.id,
+    artifactReference: `[Open report](/workspaces/${artifact.scope.workspaceId}/artifacts/editable/${artifact.id})`,
     modality: artifact.modality,
     title: artifact.title,
     lifecycle: artifact.lifecycle,