@raybase/core 0.0.2 → 0.3.4

package/dist/operator-mcp.js

@@ -0,0 +1,2828 @@
+import { z } from "zod";
+import { isHostUserId } from "./host-user.js";
+import { normalizeStoredAdminRole } from "./admin-role.js";
+import { audit, authSecret, createInvite, normalizeRoles } from "./auth.js";
+import { agentTokenClaims, raybaseAgentInternalReadPath, signAgentToken } from "./agent.js";
+import { raybaseRemoteMcpSystemTables, remoteMcpSecretNameFor } from "./agent-remote-mcp.js";
+import { bindAgentRemoteMcpServer, findInstalledRemoteMcpServerRow, installRemoteMcpServer, installedRemoteMcpOverview, parseRemoteMcpAccessSpec, rediscoverRemoteMcpServer, remoteMcpBindingView, remoteMcpInstallFindings, setInstalledRemoteMcpServerStatus, unbindAgentRemoteMcpServer } from "./agent-remote-mcp-install.js";
+import { RemoteMcpCredentialStore, remoteMcpCredentialStatus, remoteMcpKeyFromEnv } from "./agent-remote-mcp-credentials.js";
+import { beginRemoteMcpOAuthConnect, discoverRemoteMcpOAuth } from "./agent-remote-mcp-oauth.js";
+import { discoverAgentSkills } from "./agent-skill-discovery.js";
+import { applyAgentSkills, refreshAgentSkill, syncDueAgentSkillSources } from "./agent-skill-import.js";
+import { createAgentSkillUpload, deleteAgentSkill, editAgentSkill, findAgentSkill, listAgentSkillFiles, listAgentSkills, raybaseAgentSkillSystemTables, readAgentSkillFile, removeManagedAgentSkillSource, setAgentSkillEnabled } from "./agent-skill-store.js";
+import { auditArchiveEnabled, parseAuditHotDays } from "./audit-archive.js";
+import { inputSchemaForTable } from "./data-client.js";
+import { redactSecretValue } from "./data-secrets.js";
+import { controlTableNames, createRaybaseDb, dataStub, isRaybaseBackupOperationalTableName } from "./db.js";
+import { importRowsTableName, importRunsTableName } from "./imports.js";
+import { raybaseAgentConversationName, raybaseRuntimeSettingsAppId } from "./platform.js";
+import { describePolicy } from "./policies.js";
+import { pitrRetentionMs, pitrUnavailableReason } from "./pitr.js";
+import { getReferenceName } from "./schema.js";
+import { compileOperatorAppDataQuery, operatorAppDataQueryInput, redactCompiledQueryParams, tableByInput } from "./operator-data-query.js";
+import { retrievalIndexDetail, retrievalIndexesSummary, retrievalReindexRunsQuery } from "./retrieval.js";
+import { raybaseRuntimeErrorEventsTableName, runtimeErrorDetailQuery, runtimeErrorRetentionDays, runtimeErrorSummaryQuery } from "./runtime-errors.js";
+import { searchIndex, searchIndexDetail, searchIndexesSummary, searchReindexRunsQuery, updateSearchForDataChange } from "./search.js";
+import { appSettingsSubjectId, canWriteCoreSetting, createSqlSettingsStorage, resetRaybaseSettingOverride, setRaybaseSettingOverride, settingAuditMetadata, settingValueChanged } from "./settings.js";
+import { raybaseFilesTableName } from "./storage.js";
+import { raybaseSupportRequestsTableName } from "./support.js";
+import { listMcpGrants } from "./mcp.js";
+import { nowIso, q } from "./sql.js";
+import { ensureManifestTables } from "./system-tables.js";
+import { validateOutboundOrigin } from "./outbound-https.js";
+const listInput = z
+    .object({
+    limit: z.coerce.number().int().min(1).max(500).default(50),
+    offset: z.coerce.number().int().min(0).default(0)
+})
+    .strict();
+const sampleListInput = z
+    .object({
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    offset: z.coerce.number().int().min(0).default(0)
+})
+    .strict();
+const timeRangeInput = {
+    from: z.string().optional(),
+    to: z.string().optional()
+};
+const auditQueryInput = listInput
+    .extend({
+    ...timeRangeInput,
+    action: z.string().optional(),
+    targetType: z.string().optional(),
+    targetId: z.string().optional(),
+    actorId: z.string().optional(),
+    actorEmail: z.string().optional(),
+    search: z.string().optional()
+})
+    .strict();
+const jobRunsQueryInput = listInput
+    .extend({
+    ...timeRangeInput,
+    status: z.string().optional(),
+    jobName: z.string().optional(),
+    actorId: z.string().optional(),
+    runId: z.string().optional(),
+    batchId: z.string().optional()
+})
+    .strict();
+const jobRunDetailInput = z.object({ runId: z.string().min(1) }).strict();
+const jobBatchesQueryInput = z
+    .object({
+    limit: z.coerce.number().int().min(1).max(500).default(50),
+    status: z.enum(["open", "sealed", "completed"]).optional(),
+    name: z.string().optional(),
+    key: z.string().optional()
+})
+    .strict();
+const jobBatchDetailInput = z
+    .object({
+    batchId: z.string().min(1),
+    status: z.enum(["queued", "leased", "running", "succeeded", "failed", "denied", "cancelled", "expired"]).optional(),
+    cursor: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(50)
+})
+    .strict();
+const retrievalIndexDetailInput = z.object({ indexName: z.string().min(1) }).strict();
+const retrievalRunsQueryInput = listInput
+    .extend({
+    indexName: z.string().optional(),
+    backend: z.enum(["vectorize", "sqlite"]).optional(),
+    namespace: z.string().optional()
+})
+    .strict();
+const searchIndexDetailInput = z.object({ indexName: z.string().min(1) }).strict();
+const searchRunsQueryInput = listInput
+    .extend({
+    indexName: z.string().optional(),
+    status: z.string().optional()
+})
+    .strict();
+const importRunsQueryInput = listInput
+    .extend({
+    ...timeRangeInput,
+    table: z.string().optional(),
+    status: z.string().optional(),
+    actorId: z.string().optional(),
+    runId: z.string().optional()
+})
+    .strict();
+const importRunDetailInput = z.object({ runId: z.string().min(1) }).strict();
+const userDetailInput = z
+    .object({
+    id: z.string().optional(),
+    email: z.string().email().optional()
+})
+    .refine((value) => Boolean(value.id || value.email), "id or email is required");
+const appDataSearchInput = listInput
+    .extend({
+    indexName: z.string().default("app"),
+    table: z.string().optional(),
+    query: z.string().min(1)
+})
+    .strict();
+const appRecordDetailInput = z.object({ table: z.string().min(1), id: z.string().min(1) }).strict();
+const appDataCreateInput = z
+    .object({
+    table: z.string().min(1),
+    values: z.record(z.string(), z.unknown())
+})
+    .strict();
+const appDataUpdateInput = z
+    .object({
+    table: z.string().min(1),
+    id: z.string().min(1),
+    patch: z.record(z.string(), z.unknown())
+})
+    .strict();
+const appDataDeleteInput = z
+    .object({
+    table: z.string().min(1),
+    id: z.string().min(1),
+    confirm: z.literal(true)
+})
+    .strict();
+const appSettingSetInput = z
+    .object({
+    key: z.string().min(1),
+    value: z.unknown()
+})
+    .strict();
+const appSettingResetInput = z.object({ key: z.string().min(1) }).strict();
+const userInviteCreateInput = z
+    .object({
+    email: z.string().email(),
+    appRoles: z.array(z.string().min(1)).optional(),
+    name: z.string().min(1).optional()
+})
+    .strict();
+const userDeactivateInput = z
+    .object({
+    id: z.string().min(1).optional(),
+    email: z.string().email().optional(),
+    reason: z.string().min(1).max(500).optional(),
+    confirm: z.literal(true)
+})
+    .strict()
+    .refine((value) => Boolean(value.id || value.email), "id or email is required");
+const userReactivateInput = z
+    .object({
+    id: z.string().min(1).optional(),
+    email: z.string().email().optional()
+})
+    .strict()
+    .refine((value) => Boolean(value.id || value.email), "id or email is required");
+const userSessionsRevokeInput = z
+    .object({
+    id: z.string().min(1).optional(),
+    email: z.string().email().optional(),
+    reason: z.string().min(1).max(500).optional(),
+    confirm: z.literal(true)
+})
+    .strict()
+    .refine((value) => Boolean(value.id || value.email), "id or email is required");
+const findingQueryInput = listInput
+    .extend({
+    status: z.string().optional(),
+    severity: z.string().optional(),
+    confidence: z.string().optional(),
+    route: z.string().optional(),
+    action: z.string().optional(),
+    job: z.string().optional(),
+    table: z.string().optional()
+})
+    .strict();
+const findingDetailInput = z.object({ id: z.string().min(1) }).strict();
+const agentConversationsQueryInput = listInput
+    .extend({
+    ...timeRangeInput,
+    agentName: z.string().min(1).optional(),
+    runtime: z.string().optional(),
+    triggerType: z.string().optional(),
+    status: z.enum(["active", "cleanupRequested", "deleting", "cleanupError", "deleted", "archived"]).optional(),
+    lifecycleState: z.enum(["active", "cleanup", "deleted", "archived"]).optional(),
+    principalKind: z.enum(["user", "public"]).optional(),
+    userId: z.string().optional(),
+    publicScopeHash: z.string().optional(),
+    organizationId: z.string().optional(),
+    surface: z.string().optional(),
+    route: z.string().optional(),
+    search: z.string().optional()
+})
+    .strict();
+const agentConversationReadInput = listInput
+    .extend({
+    conversationId: z.string().min(1),
+    agentName: z.string().min(1).optional()
+})
+    .strict();
+const agentRunsQueryInput = listInput
+    .extend({
+    ...timeRangeInput,
+    conversationId: z.string().optional(),
+    agentName: z.string().optional(),
+    status: z.string().optional(),
+    triggerType: z.string().optional(),
+    runId: z.string().optional()
+})
+    .strict();
+const aiUsageQueryInput = listInput
+    .extend({
+    ...timeRangeInput,
+    conversationId: z.string().optional(),
+    agent: z.string().optional(),
+    model: z.string().optional(),
+    requestKind: z.string().optional(),
+    status: z.enum(["ok", "error"]).optional(),
+    principalKind: z.enum(["user", "public", "service"]).optional(),
+    userId: z.string().optional(),
+    serviceName: z.string().optional(),
+    jobName: z.string().optional(),
+    jobRunId: z.string().optional()
+})
+    .strict();
+const runtimeErrorsSummaryInput = listInput
+    .extend({
+    ...timeRangeInput,
+    source: z.enum(["server", "client"]).optional(),
+    route: z.string().optional(),
+    release: z.string().optional(),
+    kind: z.string().optional()
+})
+    .strict();
+const runtimeErrorDetailInput = sampleListInput
+    .extend({
+    fingerprint: z.string().min(1),
+    source: z.enum(["server", "client"]).optional(),
+    route: z.string().optional(),
+    release: z.string().optional()
+})
+    .strict();
+const supportRequestsQueryInput = listInput
+    .extend({
+    ...timeRangeInput,
+    status: z.string().optional(),
+    sourceKind: z.string().optional(),
+    agentName: z.string().optional(),
+    conversationId: z.string().optional(),
+    runId: z.string().optional(),
+    userId: z.string().optional(),
+    organizationId: z.string().optional(),
+    surface: z.string().optional(),
+    route: z.string().optional(),
+    search: z.string().optional()
+})
+    .strict();
+const supportRequestDetailInput = z.object({ id: z.string().min(1) }).strict();
+const agentReadScopes = ["operator:agent:read"];
+const sensitiveKeyPattern = /password|token|secret|accessToken|refreshToken|idToken|codeHash|tokenHash|verification|publicKey|credentialID|credentialId|authorization/i;
+const maxStringLength = 2000;
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function parseJson(value) {
+    if (typeof value !== "string" || !value.trim())
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function parseRoles(value) {
+    if (Array.isArray(value))
+        return normalizeRoles(value.map(String));
+    if (typeof value === "string" && value.trim()) {
+        const parsed = parseJson(value);
+        if (Array.isArray(parsed))
+            return normalizeRoles(parsed.map(String));
+        return normalizeRoles(value.split(",").map((role) => role.trim()).filter(Boolean));
+    }
+    return ["user"];
+}
+function truncateString(value) {
+    if (value.length <= maxStringLength)
+        return { value, truncated: false };
+    return { value: `${value.slice(0, maxStringLength)}...[truncated]`, truncated: true };
+}
+function redactValue(key, value, depth = 0) {
+    if (sensitiveKeyPattern.test(key))
+        return { value: "[redacted]", redacted: true, truncated: false };
+    if (value === null || value === undefined || typeof value === "number" || typeof value === "boolean") {
+        return { value, redacted: false, truncated: false };
+    }
+    if (typeof value === "string") {
+        const truncated = truncateString(value);
+        return { value: truncated.value, redacted: false, truncated: truncated.truncated };
+    }
+    if (depth > 5)
+        return { value: "[truncated]", redacted: false, truncated: true };
+    if (Array.isArray(value)) {
+        let truncated = value.length > 50;
+        const items = value.slice(0, 50).map((item, index) => {
+            const result = redactValue(String(index), item, depth + 1);
+            truncated ||= result.truncated;
+            return result.value;
+        });
+        return { value: items, redacted: false, truncated };
+    }
+    const output = {};
+    let redacted = false;
+    let truncated = false;
+    for (const [childKey, childValue] of Object.entries(asRecord(value))) {
+        const result = redactValue(childKey, childValue, depth + 1);
+        output[childKey] = result.value;
+        redacted ||= result.redacted;
+        truncated ||= result.truncated;
+    }
+    return { value: output, redacted, truncated };
+}
+function redactRow(row) {
+    const output = {};
+    const redactedColumns = [];
+    const truncatedColumns = [];
+    let truncated = false;
+    for (const [key, value] of Object.entries(row)) {
+        const result = redactValue(key, parseJson(value));
+        output[key] = result.value;
+        if (result.redacted)
+            redactedColumns.push(key);
+        if (result.truncated)
+            truncatedColumns.push(key);
+        truncated ||= result.truncated;
+    }
+    return { row: output, redactedColumns, truncatedColumns, truncated };
+}
+function operatorBatchSummary(batch) {
+    const settled = batch.counts.total - batch.counts.pending;
+    return redactRow({
+        ...batch,
+        progress: {
+            settled,
+            total: batch.counts.total,
+            percent: batch.counts.total ? Math.round((settled / batch.counts.total) * 100) : batch.status === "completed" ? 100 : 0
+        }
+    }).row;
+}
+function redactRows(rows) {
+    const redacted = rows.map(redactRow);
+    return {
+        rows: redacted.map((entry) => entry.row),
+        redactedColumns: [...new Set(redacted.flatMap((entry) => entry.redactedColumns))],
+        truncatedColumns: [...new Set(redacted.flatMap((entry) => entry.truncatedColumns))],
+        truncated: redacted.some((entry) => entry.truncated)
+    };
+}
+function normalizeSelectedAppRows(table, selectedColumns, rows) {
+    return rows.map((row) => {
+        const output = {};
+        for (const columnName of selectedColumns) {
+            const column = table.columns[columnName];
+            const value = row[columnName];
+            if (column?.kind === "secret") {
+                output[columnName] = redactSecretValue(value);
+            }
+            else if (column?.kind === "boolean" && value !== null && value !== undefined) {
+                output[columnName] = Boolean(value);
+            }
+            else if (column?.kind === "json") {
+                output[columnName] = parseJson(value);
+            }
+            else {
+                output[columnName] = value;
+            }
+        }
+        return output;
+    });
+}
+function operatorText(summary) {
+    return [{ type: "text", text: summary }];
+}
+function toolResult(summary, structuredContent, isError = false) {
+    return {
+        content: operatorText(summary),
+        structuredContent: {
+            generatedAt: nowIso(),
+            ...structuredContent
+        },
+        isError
+    };
+}
+function unavailableResult(provider, scope) {
+    return toolResult(`${provider} evidence is not installed for this Raybase app.`, {
+        unavailable: true,
+        provider,
+        requiredScope: scope,
+        appliedFilters: {},
+        rowCount: 0,
+        returned: 0,
+        truncated: false,
+        suggestedNextInspection: "Install the relevant evidence provider and register it with Operator MCP."
+    });
+}
+function normalizeDateInput(value, label) {
+    if (!value)
+        return null;
+    const time = new Date(value).getTime();
+    if (!Number.isFinite(time))
+        throw new Error(`${label} must be an ISO timestamp`);
+    return new Date(time).toISOString();
+}
+function addTimeRange(where, params, column, input) {
+    const applied = {};
+    const from = normalizeDateInput(input.from, "from");
+    const to = normalizeDateInput(input.to, "to");
+    if (from) {
+        where.push(`${column} >= ?`);
+        params.push(from);
+        applied.from = from;
+    }
+    if (to) {
+        where.push(`${column} <= ?`);
+        params.push(to);
+        applied.to = to;
+    }
+    return applied;
+}
+function sqlString(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+async function tableExists(db, tableName) {
+    const row = await db.first(`SELECT "name" FROM "sqlite_master" WHERE "type" = 'table' AND "name" = ?`, [tableName]);
+    return Boolean(row);
+}
+function shortExcerpt(value, maxChars = 320) {
+    if (typeof value !== "string" || !value.trim())
+        return { value: null, truncated: false, redacted: false };
+    let redacted = false;
+    const safe = redactRow({ excerpt: value });
+    let text = String(safe.row.excerpt ?? "");
+    text = text.replace(/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, () => {
+        redacted = true;
+        return "Bearer [redacted]";
+    });
+    text = text.replace(/\b(password|passwd|token|secret|authorization|auth|cookie|code|otp|api[-_]?key)=([^&\s]+)/gi, (_match, key) => {
+        redacted = true;
+        return `${key}=[redacted]`;
+    });
+    const truncated = text.length > maxChars || safe.truncated;
+    return {
+        value: text.length > maxChars ? `${text.slice(0, maxChars)}...[truncated]` : text,
+        truncated,
+        redacted: redacted || safe.redactedColumns.includes("excerpt")
+    };
+}
+function supportRequestListRow(row) {
+    const bodyExcerpt = shortExcerpt(row.body);
+    return {
+        id: row.id,
+        status: row.status,
+        sourceKind: row.sourceKind,
+        sourceId: row.sourceId ?? null,
+        subject: row.subject,
+        category: row.category ?? null,
+        confidence: row.confidence ?? null,
+        principalKind: row.principalKind ?? null,
+        userId: row.userId ?? null,
+        organizationId: row.organizationId ?? null,
+        publicIdentity: row.publicIdentity ?? null,
+        surface: row.surface ?? null,
+        route: row.route ?? null,
+        agentName: row.agentName ?? null,
+        conversationId: row.conversationId ?? null,
+        runId: row.runId ?? null,
+        requestId: row.requestId ?? null,
+        toolCallId: row.toolCallId ?? null,
+        contactEmail: row.contactEmail ?? null,
+        bodyExcerpt: bodyExcerpt.value,
+        bodyExcerptTruncated: bodyExcerpt.truncated,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt
+    };
+}
+function supportRequestDetailRow(row, auditRows) {
+    const body = shortExcerpt(row.body, 4000);
+    const transcriptSummary = shortExcerpt(row.transcriptSummary, 2000);
+    const transcriptEvidence = shortExcerpt(row.transcriptEvidence, 4000);
+    const escalationReason = shortExcerpt(row.escalationReason, 2000);
+    const suggestedHumanReply = shortExcerpt(row.suggestedHumanReply, 4000);
+    const metadata = redactRow({
+        docsConsultedJson: parseJson(row.docsConsultedJson),
+        sourcesJson: parseJson(row.sourcesJson),
+        metadataJson: parseJson(row.metadataJson)
+    });
+    return {
+        id: row.id,
+        status: row.status,
+        sourceKind: row.sourceKind,
+        sourceId: row.sourceId ?? null,
+        subject: row.subject,
+        category: row.category ?? null,
+        confidence: row.confidence ?? null,
+        principalKind: row.principalKind ?? null,
+        userId: row.userId ?? null,
+        organizationId: row.organizationId ?? null,
+        publicIdentity: row.publicIdentity ?? null,
+        surface: row.surface ?? null,
+        route: row.route ?? null,
+        agentName: row.agentName ?? null,
+        agentInstanceId: row.agentInstanceId ?? null,
+        conversationId: row.conversationId ?? null,
+        runId: row.runId ?? null,
+        requestId: row.requestId ?? null,
+        toolCallId: row.toolCallId ?? null,
+        createdMessageId: row.createdMessageId ?? null,
+        contactEmail: row.contactEmail ?? null,
+        body: body.value,
+        transcriptSummary: transcriptSummary.value,
+        transcriptEvidence: transcriptEvidence.value,
+        escalationReason: escalationReason.value,
+        suggestedHumanReply: suggestedHumanReply.value,
+        docsConsulted: metadata.row.docsConsultedJson ?? null,
+        sources: metadata.row.sourcesJson ?? null,
+        metadata: metadata.row.metadataJson ?? null,
+        redaction: {
+            truncated: body.truncated || transcriptSummary.truncated || transcriptEvidence.truncated || escalationReason.truncated || suggestedHumanReply.truncated || metadata.truncated,
+            redactedColumns: metadata.redactedColumns,
+            truncatedColumns: [
+                body.truncated ? "body" : null,
+                transcriptSummary.truncated ? "transcriptSummary" : null,
+                transcriptEvidence.truncated ? "transcriptEvidence" : null,
+                escalationReason.truncated ? "escalationReason" : null,
+                suggestedHumanReply.truncated ? "suggestedHumanReply" : null,
+                ...metadata.truncatedColumns
+            ].filter(Boolean)
+        },
+        adjacentEvidence: {
+            conversationId: row.conversationId ?? null,
+            runId: row.runId ?? null,
+            sourceKind: row.sourceKind,
+            route: row.route ?? null,
+            surface: row.surface ?? null,
+            recentAudit: auditRows
+        },
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt
+    };
+}
+async function safeCount(db, tableName) {
+    try {
+        const row = await db.first(`SELECT COUNT(*) as "count" FROM ${q(tableName)}`);
+        return Number(row?.count ?? 0);
+    }
+    catch {
+        return null;
+    }
+}
+async function singleColumnUniqueIndexes(db, tableName) {
+    const indexes = await db.all(`PRAGMA index_list(${sqlString(tableName)})`);
+    const uniques = new Map();
+    for (const index of indexes) {
+        if (!Boolean(index.unique) || String(index.origin ?? "") === "pk")
+            continue;
+        const indexName = String(index.name);
+        const indexedColumns = await db.all(`PRAGMA index_info(${sqlString(indexName)})`);
+        if (indexedColumns.length === 1)
+            uniques.set(String(indexedColumns[0].name), indexName);
+    }
+    return uniques;
+}
+async function databaseSchemaSummary(db, schema, systemTableNames, options = {}) {
+    const appTableNames = new Set(Object.values(schema.tables).map((table) => table.name));
+    const rows = (await db.all(`PRAGMA table_list`))
+        .filter((row) => row.schema === "main" && row.type === "table")
+        .filter((row) => !row.name.startsWith("sqlite_") && !row.name.startsWith("_cf_") && row.name !== "_do_migrations")
+        .filter((row) => !isRaybaseBackupOperationalTableName(row.name))
+        .filter((row) => options.appOnly ? appTableNames.has(row.name) : true)
+        .filter((row) => options.systemOnly ? systemTableNames.has(row.name) : true)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    const tables = [];
+    for (const row of rows) {
+        const name = String(row.name);
+        const columns = await db.all(`PRAGMA table_info(${sqlString(name)})`);
+        const foreignKeys = await db.all(`PRAGMA foreign_key_list(${sqlString(name)})`);
+        const indexes = await db.all(`PRAGMA index_list(${sqlString(name)})`);
+        const uniqueColumns = await singleColumnUniqueIndexes(db, name);
+        tables.push({
+            name,
+            appDefined: appTableNames.has(name),
+            system: systemTableNames.has(name),
+            rowCount: await safeCount(db, name),
+            columns: columns.map((column) => {
+                const columnName = String(column.name);
+                const reference = foreignKeys.find((foreignKey) => String(foreignKey.from) === columnName);
+                return {
+                    name: columnName,
+                    type: String(column.type || "TEXT").toUpperCase(),
+                    notNull: Boolean(column.notnull),
+                    primaryKey: Boolean(column.pk),
+                    unique: uniqueColumns.has(columnName),
+                    defaultValue: column.dflt_value ?? null,
+                    references: reference ? { table: String(reference.table), column: String(reference.to || "id") } : null
+                };
+            }),
+            indexes: indexes.map((index) => ({
+                name: String(index.name),
+                unique: Boolean(index.unique),
+                origin: String(index.origin ?? "")
+            }))
+        });
+    }
+    return tables;
+}
+function safeAgentConversation(row, transcriptCount) {
+    const metadata = parseJson(row.metadataJson);
+    const safe = redactRow({ ...row, metadataJson: undefined, metadata });
+    return {
+        ...safe.row,
+        principal: {
+            kind: row.principalKind,
+            userId: row.userId ?? null,
+            publicScopeHash: row.publicScopeHash ?? null,
+            organizationId: row.organizationId ?? null
+        },
+        archive: {
+            status: row.status === "archived" ? "archived" : row.status === "deleted" ? "deleted" : "hot",
+            deletedAt: row.deletedAt ?? null
+        },
+        transcriptCount: transcriptCount ?? null
+    };
+}
+function agentRunListRow(row) {
+    const errorExcerpt = shortExcerpt(row.error, 2000);
+    const startedMs = new Date(String(row.startedAt ?? "")).getTime();
+    const finishedMs = typeof row.finishedAt === "string" && row.finishedAt ? new Date(row.finishedAt).getTime() : Number.NaN;
+    return {
+        runId: row.runId,
+        conversationId: row.conversationId,
+        agentName: row.agentName,
+        requestId: row.requestId,
+        triggerType: row.triggerType,
+        inputMessageId: row.inputMessageId ?? null,
+        status: row.status,
+        startedAt: row.startedAt,
+        finishedAt: row.finishedAt ?? null,
+        durationMs: Number.isFinite(startedMs) && Number.isFinite(finishedMs) ? Math.max(0, finishedMs - startedMs) : null,
+        error: errorExcerpt.value,
+        errorTruncated: errorExcerpt.truncated,
+        usageEventId: row.usageEventId ?? null,
+        auditEventId: row.auditEventId ?? null,
+        metadata: redactValue("metadata", parseJson(row.metadataJson)).value
+    };
+}
+function aiUsageListRow(row) {
+    const errorExcerpt = shortExcerpt(row.error, 2000);
+    const metadata = redactValue("metadata", parseJson(row.metadata));
+    return {
+        id: row.id,
+        principalKind: row.principalKind ?? null,
+        userId: row.userId ?? null,
+        publicScopeHash: row.publicScopeHash ?? null,
+        serviceName: row.serviceName ?? null,
+        agent: row.agent ?? null,
+        conversationId: row.conversationId ?? null,
+        model: row.model,
+        requestKind: row.requestKind,
+        gatewayId: row.gatewayId ?? null,
+        gatewayLogId: row.gatewayLogId ?? null,
+        inputChars: Number(row.inputChars ?? 0),
+        floorChars: row.floorChars ?? null,
+        tailChars: row.tailChars ?? null,
+        outputChars: Number(row.outputChars ?? 0),
+        estimatedInputTokens: Number(row.estimatedInputTokens ?? 0),
+        estimatedOutputTokens: Number(row.estimatedOutputTokens ?? 0),
+        estimatedNeurons: row.estimatedNeurons ?? null,
+        modelParams: parseJson(row.modelParams),
+        metadata: metadata.value,
+        metadataTruncated: metadata.truncated,
+        status: row.status,
+        error: errorExcerpt.value,
+        errorTruncated: errorExcerpt.truncated,
+        durationMs: Number(row.durationMs ?? 0),
+        createdAt: row.createdAt
+    };
+}
+function agentNamespace(env) {
+    const namespace = asRecord(env).RAYBASE_AI_CHAT_AGENT;
+    return namespace && typeof namespace === "object" && "idFromName" in namespace && "get" in namespace ? namespace : null;
+}
+async function readActiveAgentTranscript(ctx, instance, input) {
+    if (instance.status !== "active") {
+        return {
+            messages: [],
+            toolEvents: [],
+            sources: [],
+            citations: [],
+            supportMarkers: [],
+            rowCount: 0,
+            returned: 0,
+            truncated: false,
+            redacted: false,
+            appliedLimits: input
+        };
+    }
+    const namespace = agentNamespace(ctx.env);
+    if (!namespace)
+        return { unavailable: true, error: "RAYBASE_AI_CHAT_AGENT Durable Object binding is missing." };
+    const token = await signAgentToken(authSecret(ctx.env), agentTokenClaims({
+        purpose: "agent-internal",
+        agent: { name: instance.agentName },
+        instance,
+        ttlSeconds: 60
+    }));
+    const response = await namespace.get(namespace.idFromName(raybaseAgentConversationName(ctx.env, {
+        instanceKey: instance.instanceKey,
+        agentName: instance.agentName,
+        conversationId: instance.conversationId,
+        // undefined keeps the environment-derived scope; a layered runtime's
+        // operator surface runs on an unscoped env and must supply it per call.
+        scope: ctx.agentConversationScope
+    }))).fetch(new Request(`https://raybase.local${raybaseAgentInternalReadPath}`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            "x-raybase-agent-context": token
+        },
+        body: JSON.stringify(input)
+    }));
+    if (!response.ok)
+        return { unavailable: true, error: await response.text() };
+    return await response.json();
+}
+function systemTableNames(options) {
+    return new Set([...controlTableNames, "_oauth_clients", "_oauth_authorization_codes", "_oauth_access_tokens", "_oauth_refresh_tokens", "_mcp_grants", "_mcp_grant_events", "_mcp_pending_authorizations", "_mcp_approval_tickets", ...(options.systemTables ?? []).map((table) => table.name)]);
+}
+function envRecord(env) {
+    return asRecord(env);
+}
+function operatorDb(ctx, options) {
+    return createRaybaseDb(ctx.env, options.schema, options.appMigrations);
+}
+function operatorMutationDb(ctx, options) {
+    const realtimeEnabled = options.realtime?.config.enabled === true;
+    const search = options.search;
+    const db = createRaybaseDb(ctx.env, options.schema, options.appMigrations, {
+        ...(realtimeEnabled ? { realtime: options.realtime?.config } : {}),
+        ...(search
+            ? {
+                afterMutation: async (change) => {
+                    const searchDb = createRaybaseDb(ctx.env, options.schema, options.appMigrations);
+                    await updateSearchForDataChange({
+                        schema: options.schema,
+                        control: searchDb.control,
+                        search,
+                        change
+                    });
+                }
+            }
+            : {})
+    });
+    return db.for({
+        user: ctx.user,
+        adminOverride: true,
+        source: { surface: "operator-mcp", requestId: ctx.request.headers.get("cf-ray") ?? undefined },
+        audit: (entry) => audit(db.control, ctx.user.id, entry.action, entry.target.type, entry.target.id ?? undefined, { ...redactRow(asRecord(entry.metadata)).row, ...ctx.mcp.auditMetadata }),
+        notify: realtimeEnabled
+            ? async (change) => {
+                if (!("seq" in change))
+                    return;
+                await dataStub(ctx.env).notifyDataChange({
+                    change: change,
+                    config: options.realtime.config,
+                    schema: options.realtime.schema
+                });
+            }
+            : undefined,
+        realtime: options.realtime?.config
+    });
+}
+function mutationAuditMetadata(ctx, metadata = {}) {
+    return { ...metadata, ...ctx.mcp.auditMetadata };
+}
+function disableUserDisabledReason(actor, target) {
+    if (!isHostUserId(target.id) && normalizeStoredAdminRole(target.operatorRole) === "owner")
+        return "Owner accounts cannot be disabled.";
+    if (actor.id === String(target.id))
+        return "You cannot disable your own account.";
+    return null;
+}
+async function resolveUserTarget(control, input) {
+    const row = input.id
+        ? await control.first(`SELECT "id", "email", "name", "emailVerified", "operatorRole", "appRoles", "banned", "banReason", "createdAt", "updatedAt" FROM "_auth_users" WHERE "id" = ?`, [input.id])
+        : await control.first(`SELECT "id", "email", "name", "emailVerified", "operatorRole", "appRoles", "banned", "banReason", "createdAt", "updatedAt" FROM "_auth_users" WHERE lower("email") = lower(?)`, [input.email ?? ""]);
+    if (!row)
+        throw new Error("User not found");
+    if (input.email && String(row.email).toLowerCase() !== input.email.toLowerCase())
+        throw new Error("User id and email do not refer to the same account");
+    return row;
+}
+async function activeSessionCount(control, userId) {
+    const row = await control.first(`SELECT COUNT(*) as "count" FROM "_auth_sessions" WHERE "userId" = ?`, [userId]);
+    return Number(row?.count ?? 0);
+}
+function operatorTool(input) {
+    return {
+        name: input.name,
+        description: input.description,
+        inputSchema: input.inputSchema,
+        annotations: input.annotations ?? { readOnlyHint: true },
+        scopes: [input.scope],
+        handler: input.handler
+    };
+}
+const agentSkillSourceInput = z.object({ kind: z.enum(["manifest-url", "website", "direct-url", "github", "upload", "upload-inline"]) }).passthrough();
+const agentSkillIdentityInput = z.object({ agentName: z.string().min(1), name: z.string().min(1) }).strict();
+function createAgentSkillOperatorTools(options) {
+    const db = async (ctx) => { await ensureManifestTables(ctx.control, raybaseAgentSkillSystemTables); return ctx.control; };
+    const source = (value) => agentSkillSourceInput.parse(value);
+    const noPackages = (value) => ({ ...value, candidates: value.candidates.map(({ package: _package, ...candidate }) => candidate) });
+    return [
+        operatorTool({
+            name: "agent_skills_list", description: "List database-backed Agent Skills with source, mode, enabled state, revision, sync status, and provenance summary.", scope: "operator:agent-skills:read",
+            inputSchema: z.object({ agentName: z.string().optional() }).strict(), handler: async (args, ctx) => { const rows = await listAgentSkills(await db(ctx), args.agentName); return toolResult(`Found ${rows.length} Agent Skill row(s).`, { skills: rows.map(skillOperatorProjection), rowCount: rows.length, returned: rows.length, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_read", description: "Read a database-backed Agent Skill, its immutable provenance, revision, supporting-file list, or one supporting file.", scope: "operator:agent-skills:read",
+            inputSchema: agentSkillIdentityInput.extend({ path: z.string().optional() }).strict(), handler: async (args, ctx) => { const control = await db(ctx); const row = await findAgentSkill(control, args.agentName, args.name); if (!row)
+                throw new Error("Agent Skill not found"); if (args.path) {
+                const file = await readAgentSkillFile(control, row.id, args.path);
+                if (!file)
+                    throw new Error("Agent Skill file not found");
+                return toolResult(`Read ${args.name}/${args.path}.`, { skill: skillOperatorProjection(row), file, rowCount: 1, returned: 1, truncated: false });
+            } const files = await listAgentSkillFiles(control, row.id); return toolResult(`Read Agent Skill ${args.name}.`, { skill: { ...row, files }, rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_sources_list", description: "List managed Agent Skill sources including sync state and artifact-origin policy.", scope: "operator:agent-skills:read",
+            inputSchema: z.object({ agentName: z.string().optional() }).strict(), handler: async (args, ctx) => { const control = await db(ctx); const rows = await control.all(`SELECT * FROM "_agent_skill_sources"${args.agentName ? ` WHERE "agentName"=?` : ""} ORDER BY "agentName","createdAt"`, args.agentName ? [args.agentName] : []); return toolResult(`Found ${rows.length} managed Agent Skill source(s).`, { sources: rows, rowCount: rows.length, returned: rows.length, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_discover", description: "Perform state-free, network-active Agent Skill discovery. website uses RFC 8615 origin-root discovery; GitHub root skills.json is a Raybase repository convention using the unchanged discovery v0.2.0 schema.", scope: "operator:agent-skills:read",
+            inputSchema: z.object({ agentName: z.string().min(1), source: agentSkillSourceInput, requestedNames: z.array(z.string()).optional() }).strict(), handler: async (args, ctx) => { const result = await discoverAgentSkills({ agentName: args.agentName, source: source(args.source), requestedNames: args.requestedNames, control: await db(ctx), fetcher: fetch }); return toolResult(`Skill discovery returned ${result.status}.`, { discovery: noPackages(result), rowCount: result.totalCandidates, returned: result.candidates.length, truncated: result.truncated }, result.status === "invalid"); }
+        }),
+        operatorTool({
+            name: "agent_skills_apply", description: "Atomically apply a prior digest-bound Agent Skill discovery selection.", scope: "operator:agent-skills:write",
+            inputSchema: z.object({ agentName: z.string().min(1), source: agentSkillSourceInput, expectedSourceDigest: z.string().min(1), requestedNames: z.array(z.string()).optional(), conflictPolicy: z.enum(["fail", "replace"]).optional(), expectedReplacedRevisions: z.record(z.string(), z.number().int()).optional(), mode: z.enum(["include", "available"]).optional(), enable: z.boolean().optional() }).strict(), annotations: { idempotentHint: true },
+            handler: async (args, ctx) => { const result = await applyAgentSkills({ agentName: args.agentName, source: source(args.source), expectedSourceDigest: args.expectedSourceDigest, requestedNames: args.requestedNames, conflictPolicy: args.conflictPolicy, expectedReplacedRevisions: args.expectedReplacedRevisions, mode: args.mode, enable: args.enable, control: await db(ctx), actorKind: "operator", actor: ctx.user.id, ownerKind: "operator", fetcher: fetch }); await audit(ctx.control, ctx.user.id, "agent.skills.apply", "_agent_skills", undefined, mutationAuditMetadata(ctx, { agentName: args.agentName, sourceKind: args.source.kind, sourceDigest: args.expectedSourceDigest, applied: result.applied.map((item) => item.name) })); return toolResult(result.ok ? `Applied ${result.applied.length} Agent Skill(s).` : `Agent Skill apply failed: ${result.error?.message}`, { ...result, discovery: noPackages(result.discovery), rowCount: result.applied.length, returned: result.applied.length, truncated: false }, !result.ok); }
+        }),
+        operatorTool({
+            name: "agent_skills_upload_create", description: "Create an explicit write-scoped short-lived Agent Skill upload session from a base64 payload (up to 1 MiB over MCP).", scope: "operator:agent-skills:write",
+            inputSchema: z.object({ agentName: z.string().min(1), filename: z.string().min(1), contentBase64: z.string().min(1) }).strict(), annotations: { idempotentHint: false }, handler: async (args, ctx) => { const bytes = base64Bytes(args.contentBase64); if (bytes.byteLength > 1024 * 1024)
+                throw new Error("MCP inline upload exceeds 1 MiB"); const result = await createAgentSkillUpload(await db(ctx), { agentName: args.agentName, filename: args.filename, bytes, createdByUserId: ctx.user.id }); await audit(ctx.control, ctx.user.id, "agent.skills.upload.create", "_agent_skill_uploads", result.uploadId, mutationAuditMetadata(ctx, { agentName: args.agentName, filename: args.filename, bytes: result.bytes, sha256: result.sha256 })); return toolResult("Created Agent Skill upload session.", { ...result, rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_refresh", description: "Refresh an imported local Agent Skill from its immutable origin anchor with revision and local-modification guards.", scope: "operator:agent-skills:write",
+            inputSchema: agentSkillIdentityInput.extend({ expectedRevision: z.number().int(), overwriteLocalEdits: z.boolean().optional() }).strict(), annotations: { idempotentHint: true }, handler: async (args, ctx) => { const result = await refreshAgentSkill({ control: await db(ctx), agentName: args.agentName, name: args.name, expectedRevision: args.expectedRevision, overwriteLocalEdits: args.overwriteLocalEdits, actorKind: "operator", actor: ctx.user.id, fetcher: fetch }); await audit(ctx.control, ctx.user.id, "agent.skills.refresh", "_agent_skills", args.name, mutationAuditMetadata(ctx, { agentName: args.agentName, expectedRevision: args.expectedRevision, overwriteLocalEdits: args.overwriteLocalEdits === true })); return toolResult(result.ok ? `Refreshed Agent Skill ${args.name}.` : `Refresh failed: ${result.error?.message}`, { ...result, discovery: noPackages(result.discovery), rowCount: result.applied.length, returned: result.applied.length, truncated: false }, !result.ok); }
+        }),
+        operatorTool({
+            name: "agent_skills_edit", description: "CAS-edit an operator-visible local Agent Skill; code and managed guidance remain reconcile/sync owned.", scope: "operator:agent-skills:write",
+            inputSchema: agentSkillIdentityInput.extend({ expectedRevision: z.number().int(), edit: z.object({ title: z.string().nullable().optional(), description: z.string().optional(), mode: z.enum(["include", "available"]).optional(), ephemeral: z.boolean().optional(), replaceGuidance: z.string().optional(), findText: z.string().optional(), replaceWith: z.string().optional() }).strict() }).strict(), annotations: { idempotentHint: true }, handler: async (args, ctx) => { const row = await editAgentSkill(await db(ctx), { agentName: args.agentName, name: args.name, expectedRevision: args.expectedRevision, actorKind: "operator", actor: ctx.user.id, ...args.edit }); await audit(ctx.control, ctx.user.id, "agent.skills.edit", "_agent_skills", row.id, mutationAuditMetadata(ctx, { agentName: args.agentName, name: args.name, revision: row.revision, contentDigest: row.contentDigest })); return toolResult(`Edited Agent Skill ${args.name}.`, { skill: skillOperatorProjection(row), rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_delete", description: "CAS-delete a local Agent Skill. Managed and code rows cannot be deleted directly.", scope: "operator:agent-skills:write",
+            inputSchema: agentSkillIdentityInput.extend({ expectedRevision: z.number().int() }).strict(), annotations: { destructiveHint: true, idempotentHint: false }, handler: async (args, ctx) => { await deleteAgentSkill(await db(ctx), { ...args, actorKind: "operator", actor: ctx.user.id }); await audit(ctx.control, ctx.user.id, "agent.skills.delete", "_agent_skills", args.name, mutationAuditMetadata(ctx, { agentName: args.agentName, name: args.name, expectedRevision: args.expectedRevision })); return toolResult(`Deleted Agent Skill ${args.name}.`, { deleted: true, name: args.name, rowCount: 1, returned: 0, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_set_enabled", description: "CAS-toggle any Agent Skill. Managed sync preserves this operator-owned enabled state.", scope: "operator:agent-skills:write",
+            inputSchema: agentSkillIdentityInput.extend({ enabled: z.boolean(), expectedRevision: z.number().int() }).strict(), annotations: { idempotentHint: true }, handler: async (args, ctx) => { const row = await setAgentSkillEnabled(await db(ctx), { ...args, actorKind: "operator", actor: ctx.user.id }); await audit(ctx.control, ctx.user.id, args.enabled ? "agent.skills.enable" : "agent.skills.disable", "_agent_skills", row.id, mutationAuditMetadata(ctx, { agentName: args.agentName, name: args.name, revision: row.revision })); return toolResult(`${args.enabled ? "Enabled" : "Disabled"} Agent Skill ${args.name}.`, { skill: skillOperatorProjection(row), rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_source_register", description: "Register an operator-only website, exact manifest URL, or GitHub manifest as a managed source after digest-bound discovery, and apply its initial selection.", scope: "operator:agent-skills:write",
+            inputSchema: z.object({ agentName: z.string().min(1), source: agentSkillSourceInput, expectedSourceDigest: z.string().min(1), selection: z.union([z.literal("all"), z.array(z.string())]), syncEveryMs: z.number().int().min(900000).optional(), authSecretName: z.string().optional(), allowedArtifactOrigins: z.array(z.string()).max(8).optional(), artifactAuth: z.array(z.object({ origin: z.string(), secretName: z.string() })).optional() }).strict(), annotations: { idempotentHint: false }, handler: async (args, ctx) => { const control = await db(ctx); let descriptor = source(args.source); if (descriptor.kind !== "manifest-url" && descriptor.kind !== "website" && descriptor.kind !== "github")
+                throw new Error("Managed source must be manifest-url, website, or GitHub manifest"); if (descriptor.kind === "github" && (args.allowedArtifactOrigins?.length || args.artifactAuth?.length || args.authSecretName))
+                throw new Error("GitHub managed sources use the fixed public host set and do not accept custom credentials or origins"); if (descriptor.kind !== "github" && args.allowedArtifactOrigins?.length)
+                descriptor = { ...descriptor, allowedOrigins: args.allowedArtifactOrigins }; let requestedNames = args.selection === "all" ? undefined : args.selection; let preview = await discoverAgentSkills({ agentName: args.agentName, source: descriptor, requestedNames, control, fetcher: fetch, env: ctx.env, indexAuthSecretName: args.authSecretName, artifactAuth: args.artifactAuth }); if (args.selection === "all") {
+                requestedNames = preview.candidates.filter((candidate) => candidate.valid).map((candidate) => candidate.name);
+                if (requestedNames.length)
+                    preview = await discoverAgentSkills({ agentName: args.agentName, source: descriptor, requestedNames, control, fetcher: fetch, env: ctx.env, indexAuthSecretName: args.authSecretName, artifactAuth: args.artifactAuth });
+            } if (preview.status !== "ready" || preview.sourceDigest !== args.expectedSourceDigest || preview.classification !== "managed-manifest")
+                throw new Error("Managed source discovery is not ready or digest changed"); const sourceId = `skill_source_${crypto.randomUUID().replace(/-/g, "")}`; const now = nowIso(); const url = preview.indexUrl ?? (preview.github ? `github:${preview.github.repo}@${preview.github.requestedRef ?? "default"}:${preview.github.manifestPath}` : ""); if (!control.runTransaction)
+                throw new Error("Managed source registration requires transaction support"); const statements = [{ sql: `INSERT INTO "_agent_skill_sources" ("id","agentName","sourceType","url","registeredBy","enabled","revision","syncEveryMs","authSecretName","allowedArtifactOriginsJson","artifactAuthJson","selectionMode","selectedNamesJson","repo","manifestPath","requestedRef","refKind","defaultBranch","resolvedCommit","createdAt","updatedAt") VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`, params: [sourceId, args.agentName, preview.github ? "github" : "http-index", url, "operator", 1, 1, args.syncEveryMs ?? 21600000, args.authSecretName ?? null, JSON.stringify(args.allowedArtifactOrigins ?? []), JSON.stringify(args.artifactAuth ?? []), args.selection === "all" ? "all" : "named", JSON.stringify(requestedNames ?? []), preview.github?.repo ?? null, preview.github?.manifestPath ?? null, preview.github?.requestedRef ?? null, preview.github?.refKind ?? null, preview.github?.defaultBranch ?? null, preview.resolvedCommit ?? null, now, now] }]; const transactionControl = { all: control.all.bind(control), first: control.first.bind(control), run: control.run.bind(control), runTransaction: async (batch) => { statements.push(...batch); } }; const result = await applyAgentSkills({ agentName: args.agentName, source: descriptor, requestedNames, expectedSourceDigest: args.expectedSourceDigest, control: transactionControl, actorKind: "operator", actor: ctx.user.id, managedSourceId: sourceId, fetcher: fetch, env: ctx.env, indexAuthSecretName: args.authSecretName, artifactAuth: args.artifactAuth }); if (!result.ok)
+                throw new Error(result.error?.message ?? "Managed source apply failed"); await control.runTransaction(statements); await audit(control, ctx.user.id, "agent.skills.source.register", "_agent_skill_sources", sourceId, mutationAuditMetadata(ctx, { agentName: args.agentName, sourceDigest: args.expectedSourceDigest, allowedArtifactOrigins: args.allowedArtifactOrigins ?? [], repo: preview.github?.repo, resolvedCommit: preview.resolvedCommit })); return toolResult("Registered managed Agent Skill source.", { sourceId, revision: 1, applied: result.applied, rowCount: result.applied.length, returned: result.applied.length, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_source_update", description: "Update operator-owned managed source scheduling, enablement, selection, and artifact-origin policy without fetching it.", scope: "operator:agent-skills:write",
+            inputSchema: z.object({ sourceId: z.string().min(1), expectedRevision: z.number().int(), enabled: z.boolean().optional(), syncEveryMs: z.number().int().min(900000).optional(), selection: z.union([z.literal("all"), z.array(z.string())]).optional(), authSecretName: z.string().nullable().optional(), allowedArtifactOrigins: z.array(z.string()).max(8).optional(), artifactAuth: z.array(z.object({ origin: z.string(), secretName: z.string() })).optional() }).strict(), annotations: { idempotentHint: true },
+            handler: async (args, ctx) => { const control = await db(ctx); const current = await control.first(`SELECT * FROM "_agent_skill_sources" WHERE "id"=? AND "registeredBy"='operator'`, [args.sourceId]); if (!current)
+                throw new Error("Operator-owned managed source not found"); const selectionMode = args.selection === undefined ? current.selectionMode : args.selection === "all" ? "all" : "named"; const selectedNames = args.selection === undefined ? current.selectedNamesJson : JSON.stringify(args.selection === "all" ? [] : args.selection); const allowedArtifactOrigins = args.allowedArtifactOrigins === undefined ? current.allowedArtifactOriginsJson : JSON.stringify(args.allowedArtifactOrigins.map(validateOutboundOrigin)); const artifactAuth = args.artifactAuth === undefined ? current.artifactAuthJson : JSON.stringify(args.artifactAuth.map((entry) => { const origin = validateOutboundOrigin(entry.origin); if (!/^[A-Z][A-Z0-9_]*$/.test(entry.secretName))
+                throw new Error("artifactAuth secretName must be an uppercase environment binding name"); return { origin, secretName: entry.secretName }; })); const updated = await control.first(`UPDATE "_agent_skill_sources" SET "enabled"=?,"revision"="revision"+1,"syncEveryMs"=?,"authSecretName"=?,"allowedArtifactOriginsJson"=?,"artifactAuthJson"=?,"selectionMode"=?,"selectedNamesJson"=?,"updatedAt"=? WHERE "id"=? AND "registeredBy"='operator' AND "revision"=? RETURNING *`, [args.enabled === undefined ? current.enabled : args.enabled ? 1 : 0, args.syncEveryMs ?? current.syncEveryMs, args.authSecretName === undefined ? current.authSecretName : args.authSecretName, allowedArtifactOrigins, artifactAuth, selectionMode, selectedNames, nowIso(), args.sourceId, args.expectedRevision]); if (!updated)
+                throw new Error("Managed source revision changed; refresh and retry"); await audit(control, ctx.user.id, "agent.skills.source.update", "_agent_skill_sources", args.sourceId, mutationAuditMetadata(ctx, { expectedRevision: args.expectedRevision, revision: updated.revision, enabled: args.enabled, syncEveryMs: args.syncEveryMs, selection: args.selection, allowedArtifactOrigins: args.allowedArtifactOrigins, artifactAuthOrigins: args.artifactAuth?.map((entry) => entry.origin) })); return toolResult("Updated managed Agent Skill source.", { source: updated, rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_skills_source_sync_now", description: "Synchronize one managed Agent Skill source immediately while retaining its last good snapshot on failure.", scope: "operator:agent-skills:write",
+            inputSchema: z.object({ sourceId: z.string().min(1) }).strict(), annotations: { idempotentHint: true },
+            handler: async (args, ctx) => { const result = await syncDueAgentSkillSources({ control: await db(ctx), fetcher: fetch, env: ctx.env, sourceId: args.sourceId }); await audit(ctx.control, ctx.user.id, "agent.skills.source.sync", "_agent_skill_sources", args.sourceId, mutationAuditMetadata(ctx, result)); return toolResult(result.failed.length ? "Managed Agent Skill source sync failed; the last good snapshot remains active." : "Synchronized managed Agent Skill source.", { ...result, rowCount: result.synced.length, returned: result.synced.length, truncated: false }, result.failed.length > 0); }
+        }),
+        operatorTool({
+            name: "agent_skills_source_remove", description: "Remove a managed Agent Skill source; by default its rows are retained disabled and orphaned.", scope: "operator:agent-skills:write",
+            inputSchema: z.object({ sourceId: z.string().min(1), expectedRevision: z.number().int(), deleteSkills: z.boolean().optional() }).strict(), annotations: { destructiveHint: true, idempotentHint: false }, handler: async (args, ctx) => { const control = await db(ctx); await removeManagedAgentSkillSource(control, { sourceId: args.sourceId, expectedRevision: args.expectedRevision, deleteSkills: args.deleteSkills }); await audit(control, ctx.user.id, "agent.skills.source.remove", "_agent_skill_sources", args.sourceId, mutationAuditMetadata(ctx, { expectedRevision: args.expectedRevision, deleteSkills: args.deleteSkills === true })); return toolResult("Removed managed Agent Skill source.", { sourceId: args.sourceId, deletedSkills: args.deleteSkills === true, rowCount: 1, returned: 0, truncated: false }); }
+        })
+    ];
+}
+/**
+ * Runtime-installable remote MCP servers. Install and rediscover reach the
+ * server once, on the operator's word; bind is a separate, closed allowlist per
+ * agent. No credential value ever passes through these tools — only a name.
+ */
+function createAgentRemoteMcpOperatorTools(options) {
+    const db = async (ctx) => { await ensureManifestTables(ctx.control, raybaseRemoteMcpSystemTables); return ctx.control; };
+    const accessInput = z.record(z.string(), z.string()).optional();
+    const access = (value) => value ? Object.fromEntries(Object.entries(value).map(([toolName, spec]) => [toolName, parseRemoteMcpAccessSpec(spec)])) : undefined;
+    return [
+        operatorTool({
+            name: "agent_remote_mcp_list", description: "List runtime-installed remote MCP servers, their pinned tools, agent bindings, and install findings. Credential references are names only.", scope: "operator:agent-remote-mcp:read",
+            inputSchema: z.object({}).strict(),
+            handler: async (_args, ctx) => { const control = await db(ctx); const overview = await installedRemoteMcpOverview(control); const findings = await remoteMcpInstallFindings({ control, env: ctx.env }); return toolResult(`Found ${overview.servers.length} installed remote MCP server(s).`, { ...overview, findings, rowCount: overview.servers.length, returned: overview.servers.length, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_install", description: "Install a remote MCP server with an explicit credential mode and transport. Secret values are never accepted by this model-visible tool.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ name: z.string().min(1), endpoint: z.string().min(1), credential: z.enum(["none", "secret", "stored", "oauth"]).optional(), secretName: z.string().optional(), scheme: z.enum(["bearer", "raw"]).optional(), transport: z.enum(["stateless", "sessioned"]).optional(), clientId: z.string().optional(), authorizationServer: z.string().optional(), access: accessInput }).strict(),
+            annotations: { idempotentHint: false },
+            handler: async (args, ctx) => {
+                const control = await db(ctx);
+                const mode = args.credential ?? "secret";
+                const oauthDiscovery = mode === "oauth" ? await discoverRemoteMcpOAuth({ endpoint: args.endpoint, clientId: args.clientId, authorizationServer: args.authorizationServer, fetcher: fetch }) : undefined;
+                const result = await installRemoteMcpServer({
+                    control, name: args.name, endpoint: args.endpoint,
+                    credential: mode === "none" ? { type: "none" } : mode === "secret" ? { type: "secret", name: args.secretName ?? remoteMcpSecretNameFor(args.name), scheme: args.scheme ?? "bearer" } : { type: "stored" },
+                    transport: args.transport ?? "stateless",
+                    oauthDiscovery,
+                    access: access(args.access), reservedServerNames: options.remoteMcp?.serverNames ?? [],
+                    actor: ctx.user.id, env: ctx.env, fetcher: fetch
+                });
+                await audit(control, ctx.user.id, "agent.remote_mcp.install", "_agent_remote_mcp_servers", result.row.id, mutationAuditMetadata(ctx, { serverName: args.name, endpointHost: result.server.endpointHost, secretName: result.secretName, toolNames: result.server.tools.map((tool) => tool.name), discoveryHash: result.row.discoveryHash }));
+                return toolResult(`Installed remote MCP server ${args.name} with ${result.server.tools.length} pinned tool(s).`, { server: result.server, secretName: result.secretName, rejected: result.discovery.rejected, rowCount: 1, returned: 1, truncated: false });
+            }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_credential_status", description: "Read safe runtime credential status. This never returns an encrypted envelope, token, verifier, code, or client secret.", scope: "operator:agent-remote-mcp:read",
+            inputSchema: z.object({ name: z.string().min(1) }).strict(),
+            handler: async (args, ctx) => { const control = await db(ctx); const status = await remoteMcpCredentialStatus(control, args.name); return toolResult(status ? `Credential for ${args.name} is ${status.state}.` : `No stored credential exists for ${args.name}.`, { credential: status, rowCount: status ? 1 : 0, returned: status ? 1 : 0, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_credential_set", description: "Issue a short-lived authenticated-admin upload link for a static credential. The token itself must never be passed to this tool.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ name: z.string().min(1), scheme: z.enum(["bearer", "raw"]).optional() }).strict(), annotations: { idempotentHint: false },
+            handler: async (args, ctx) => { const control = await db(ctx); if (!await findInstalledRemoteMcpServerRow(control, args.name))
+                throw new Error("Remote MCP server is not installed"); const issued = await new RemoteMcpCredentialStore(control, remoteMcpKeyFromEnv(ctx.env)).issueUploadTicket({ serverName: args.name, scheme: args.scheme ?? "bearer", actor: ctx.user.id }); const origin = new URL(ctx.request.url).origin; return toolResult(`Open the upload link while signed in as an operator. It expires at ${issued.expiresAt}.`, { uploadUrl: `${origin}/admin/agents#remote-mcp-credential=${encodeURIComponent(issued.ticket)}`, expiresAt: issued.expiresAt, rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_credential_clear", description: "Clear a stored remote MCP credential and invalidate its generation.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ name: z.string().min(1) }).strict(), annotations: { destructiveHint: true, idempotentHint: true },
+            handler: async (args, ctx) => { const control = await db(ctx); const status = await new RemoteMcpCredentialStore(control, remoteMcpKeyFromEnv(ctx.env)).clear(args.name, ctx.user.id); await audit(control, ctx.user.id, "agent.remote_mcp.credential.clear", "_agent_remote_mcp_credentials", undefined, mutationAuditMetadata(ctx, { serverName: args.name, generation: status.generation })); return toolResult(`Cleared credential for ${args.name}.`, { credential: status, rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_oauth_connect", description: "Begin the browser OAuth connection for an installed OAuth remote MCP server. Client secrets are not accepted by this tool.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ name: z.string().min(1), clientId: z.string().optional(), scopes: z.array(z.string()).max(64).optional() }).strict(), annotations: { idempotentHint: false },
+            handler: async (args, ctx) => { const control = await db(ctx); const row = await findInstalledRemoteMcpServerRow(control, args.name); if (!row?.oauthMetadataJson)
+                throw new Error("Remote MCP server is not configured for OAuth"); const result = await beginRemoteMcpOAuthConnect({ control, key: remoteMcpKeyFromEnv(ctx.env), serverName: args.name, discovery: JSON.parse(row.oauthMetadataJson), client: { ...(args.clientId ? { clientId: args.clientId } : {}), redirectUri: `${new URL(ctx.request.url).origin}/api/agents/remote-mcp/oauth/callback`, ...(args.scopes ? { scopes: args.scopes } : {}) }, actor: ctx.user.id, fetcher: fetch }); return toolResult("Open the authorization URL to connect the remote MCP server.", { authorizationUrl: result.authorizationUrl, expiresAt: result.expiresAt, rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_oauth_disconnect", description: "Disconnect a remote MCP OAuth identity and invalidate its credential generation.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ name: z.string().min(1) }).strict(), annotations: { destructiveHint: true, idempotentHint: true },
+            handler: async (args, ctx) => { const control = await db(ctx); const status = await new RemoteMcpCredentialStore(control, remoteMcpKeyFromEnv(ctx.env)).clear(args.name, ctx.user.id); return toolResult(`Disconnected OAuth for ${args.name}.`, { credential: status, rowCount: 1, returned: 1, truncated: false }); }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_rediscover", description: "Re-read a server's tools/list and show the diff. Without confirm nothing changes; with confirm the new set is pinned and bindings to a tool that disappeared are disabled.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ name: z.string().min(1), confirm: z.boolean().optional() }).strict(), annotations: { idempotentHint: true },
+            handler: async (args, ctx) => {
+                const control = await db(ctx);
+                const result = await rediscoverRemoteMcpServer({ control, name: args.name, confirm: args.confirm === true, actor: ctx.user.id, env: ctx.env, fetcher: fetch });
+                if (result.applied)
+                    await audit(control, ctx.user.id, "agent.remote_mcp.rediscover", "_agent_remote_mcp_servers", args.name, mutationAuditMetadata(ctx, { serverName: args.name, diff: result.diff, disabledBindings: result.disabledBindings.map((binding) => `${binding.agentName}/${binding.serverName}`) }));
+                return toolResult(result.applied ? `Pinned the new tool set for ${args.name}.` : `Previewed the tool diff for ${args.name}; pass confirm to pin it.`, { ...result, rowCount: 1, returned: 1, truncated: false });
+            }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_disable", description: "Disable or re-enable an installed remote MCP server. A disabled server offers no tools to any agent.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ name: z.string().min(1), enabled: z.boolean().optional() }).strict(), annotations: { idempotentHint: true },
+            handler: async (args, ctx) => {
+                const control = await db(ctx);
+                const status = args.enabled === true ? "installed" : "disabled";
+                const row = await setInstalledRemoteMcpServerStatus({ control, name: args.name, status });
+                await audit(control, ctx.user.id, status === "disabled" ? "agent.remote_mcp.disable" : "agent.remote_mcp.enable", "_agent_remote_mcp_servers", row.id, mutationAuditMetadata(ctx, { serverName: row.name }));
+                return toolResult(`${status === "disabled" ? "Disabled" : "Enabled"} remote MCP server ${args.name}.`, { name: row.name, status: row.status, rowCount: 1, returned: 1, truncated: false });
+            }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_bind", description: "Bind pinned tools of an installed remote MCP server to one agent. The tool list is a closed allowlist; a duplicate model tool name refuses.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ agentName: z.string().min(1), serverName: z.string().min(1), toolNames: z.array(z.string()).min(1) }).strict(), annotations: { idempotentHint: true },
+            handler: async (args, ctx) => {
+                const control = await db(ctx);
+                const binding = await bindAgentRemoteMcpServer({ control, agentName: args.agentName, serverName: args.serverName, toolNames: args.toolNames, reservedModelToolNames: options.remoteMcp?.agentModelToolNames?.[args.agentName] ?? [], actor: ctx.user.id });
+                await audit(control, ctx.user.id, "agent.remote_mcp.bind", "_agent_remote_mcp_bindings", binding.id, mutationAuditMetadata(ctx, { agentName: args.agentName, serverName: args.serverName, toolNames: args.toolNames }));
+                return toolResult(`Bound ${args.serverName} to ${args.agentName}.`, { binding: remoteMcpBindingView(binding), rowCount: 1, returned: 1, truncated: false });
+            }
+        }),
+        operatorTool({
+            name: "agent_remote_mcp_unbind", description: "Remove one agent's binding to an installed remote MCP server.", scope: "operator:agent-remote-mcp:write",
+            inputSchema: z.object({ agentName: z.string().min(1), serverName: z.string().min(1) }).strict(), annotations: { destructiveHint: true, idempotentHint: true },
+            handler: async (args, ctx) => {
+                const control = await db(ctx);
+                const removed = await unbindAgentRemoteMcpServer({ control, agentName: args.agentName, serverName: args.serverName });
+                if (removed)
+                    await audit(control, ctx.user.id, "agent.remote_mcp.unbind", "_agent_remote_mcp_bindings", undefined, mutationAuditMetadata(ctx, { agentName: args.agentName, serverName: args.serverName }));
+                return toolResult(removed ? `Unbound ${args.serverName} from ${args.agentName}.` : `${args.agentName} was not bound to ${args.serverName}.`, { removed, rowCount: removed ? 1 : 0, returned: 0, truncated: false });
+            }
+        })
+    ];
+}
+function skillOperatorProjection(row) { return { name: row.name, agentName: row.agentName, title: row.title, description: row.description, source: row.source, mode: row.mode, ephemeral: row.ephemeral === 1, enabled: row.enabled === 1, revision: row.revision, contentDigest: row.contentDigest, lastImportedContentDigest: row.lastImportedContentDigest, ownerKind: row.ownerKind, ownerAgentName: row.ownerAgentName, provenance: { originKind: row.originKind, originUrl: row.originUrl, originRef: row.originRef, originRefKind: row.originRefKind, originCommit: row.originCommit, originRepo: row.originRepo, originManifestPath: row.originManifestPath, originSkillPath: row.originSkillPath, originDigest: row.originDigest, importedAt: row.importedAt }, sync: { sourceId: row.sourceId, remoteSha256: row.remoteSha256, syncedAt: row.syncedAt, status: row.syncStatus, error: row.syncError }, updatedAt: row.updatedAt }; }
+function base64Bytes(value) { const binary = atob(value); return Uint8Array.from(binary, (char) => char.charCodeAt(0)); }
+export function createCoreOperatorMcpTools(options) {
+    const tools = [
+        operatorTool({
+            name: "app_health_summary",
+            description: "Summarize Raybase app health, environment, storage, jobs, and recent failure evidence.",
+            scope: "operator:health:read",
+            inputSchema: z.object({}).strict(),
+            handler: async (_args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const env = envRecord(ctx.env);
+                let databaseReachable = false;
+                let databaseSizeBytes = null;
+                try {
+                    await dataStub(ctx.env).ping();
+                    databaseReachable = true;
+                    databaseSizeBytes = await dataStub(ctx.env).databaseSize();
+                }
+                catch {
+                    databaseReachable = false;
+                }
+                const recentErrors = await db.control.first(`SELECT COUNT(*) as "count" FROM "_audit" WHERE "createdAt" >= ? AND ("action" LIKE '%fail%' OR "action" LIKE '%deny%' OR "action" LIKE '%error%')`, [new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString()]).catch(() => null);
+                const jobFailures = await dataStub(ctx.env)
+                    .first(`SELECT COUNT(*) as "count" FROM "_job_runs" WHERE "status" IN ('failed','denied','expired')`)
+                    .catch(() => null);
+                const runtimeErrors24h = await db.control.first(`SELECT COUNT(*) as "count" FROM ${q(raybaseRuntimeErrorEventsTableName)} WHERE "expiresAt" > ? AND "createdAt" >= ?`, [nowIso(), new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString()]).catch(() => null);
+                return toolResult(`App ${options.config.appName} is ${databaseReachable ? "reachable" : "not reachable"}.`, {
+                    appName: options.config.appName,
+                    environment: env.RAYBASE_ENV ?? "production",
+                    url: new URL(ctx.request.url).origin,
+                    coreVersion: options.coreVersion ?? "0.1.0",
+                    packageVersions: { "@raybase/core": options.coreVersion ?? "0.1.0" },
+                    database: { reachable: databaseReachable, sizeBytes: databaseSizeBytes },
+                    storage: { enabled: Boolean(options.storage), r2BindingPresent: Boolean(env.RAYBASE_FILES) },
+                    features: {
+                        aiEnabled: options.config.ai?.enabled === true,
+                        realtimeEnabled: options.config.realtime?.enabled === true,
+                        jobsEnabled: options.config.jobs?.enabled === true || Boolean(options.jobs && Object.keys(options.jobs).length)
+                    },
+                    recentFailureCounts: {
+                        audit24h: Number(recentErrors?.count ?? 0),
+                        jobs: Number(jobFailures?.count ?? 0),
+                        runtimeErrors24h: Number(runtimeErrors24h?.count ?? 0)
+                    },
+                    appliedFilters: { window: "24h" },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false,
+                    suggestedNextInspection: "Use deployment_history, audit_query, and job_runs_query for recent failures."
+                });
+            }
+        }),
+        operatorTool({
+            name: "deployment_history",
+            description: "Inspect deployment and schema-version evidence without inventing missing deploy history.",
+            scope: "operator:health:read",
+            inputSchema: listInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const schemaVersions = await db.control.all(`SELECT * FROM "_schema_versions" ORDER BY "updatedAt" DESC LIMIT ? OFFSET ?`, [args.limit, args.offset]).catch(() => []);
+                const deployAudit = await db.control.all(`SELECT "id", "action", "targetType", "targetId", "metadata", "createdAt" FROM "_audit"
+           WHERE "action" LIKE '%deploy%' OR "action" LIKE '%migration%' OR "action" LIKE '%schema%'
+           ORDER BY "createdAt" DESC LIMIT ?`, [args.limit]).catch(() => []);
+                return toolResult(schemaVersions.length || deployAudit.length ? "Deployment evidence found." : "No deploy ledger was found for this app.", {
+                    schemaVersions: schemaVersions.map((row) => redactRow(row).row),
+                    auditDeployMarkers: deployAudit.map((row) => ({ ...redactRow(row).row, metadata: parseJson(row.metadata) })),
+                    packageVersions: { "@raybase/core": options.coreVersion ?? "0.1.0" },
+                    appliedFilters: { limit: args.limit, offset: args.offset },
+                    rowCount: schemaVersions.length + deployAudit.length,
+                    returned: schemaVersions.length + deployAudit.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use schema_summary and audit_query around deploy timestamps."
+                });
+            }
+        }),
+        operatorTool({
+            name: "schema_summary",
+            description: "Summarize app and Raybase system schema with columns, indexes, references, and row counts.",
+            scope: "operator:schema:read",
+            inputSchema: z.object({ includeSystem: z.boolean().default(true) }).strict(),
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const tables = await databaseSchemaSummary(db.control, options.schema, systemTableNames(options), { systemOnly: args.includeSystem ? undefined : false });
+                const filtered = args.includeSystem ? tables : tables.filter((table) => table.appDefined);
+                return toolResult(`Found ${filtered.length} schema table(s).`, {
+                    tables: filtered,
+                    appliedFilters: { includeSystem: args.includeSystem },
+                    rowCount: filtered.length,
+                    returned: filtered.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use app_data_table_summary before querying app rows."
+                });
+            }
+        }),
+        operatorTool({
+            name: "policy_summary",
+            description: "Summarize app table policies from Raybase schema metadata.",
+            scope: "operator:policy:read",
+            inputSchema: z.object({}).strict(),
+            handler: async () => {
+                const actions = ["read", "create", "update", "delete"];
+                const tables = Object.values(options.schema.tables).map((table) => ({
+                    name: table.name,
+                    label: table.label ?? null,
+                    policies: Object.fromEntries(actions.map((action) => [action, describePolicy(table.policies?.[action])])),
+                    missingActions: actions.filter((action) => !table.policies?.[action])
+                }));
+                return toolResult(`Summarized policies for ${tables.length} app table(s).`, {
+                    introspection: "partial",
+                    tables,
+                    appliedFilters: {},
+                    rowCount: tables.length,
+                    returned: tables.length,
+                    truncated: false,
+                    suggestedNextInspection: "Treat partial policy summaries as labels; inspect source policy definitions for full behavior."
+                });
+            }
+        }),
+        operatorTool({
+            name: "users_summary",
+            description: "Summarize users, statuses, operator roles, app roles, invites, and recent sessions.",
+            scope: "operator:users:read",
+            inputSchema: listInput.extend({ search: z.string().optional() }).strict(),
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const where = args.search ? `WHERE "email" LIKE ? OR "name" LIKE ?` : "";
+                const params = args.search ? [`%${args.search}%`, `%${args.search}%`, args.limit, args.offset] : [args.limit, args.offset];
+                const users = await db.control.all(`SELECT "id", "name", "email", "emailVerified", "operatorRole", "appRoles", "banned", "createdAt", "updatedAt"
+           FROM "_auth_users" ${where} ORDER BY "createdAt" DESC LIMIT ? OFFSET ?`, params);
+                const byOperatorRole = await db.control.all(`SELECT CASE WHEN "operatorRole" IS NULL OR "operatorRole" = '' THEN 'none' ELSE "operatorRole" END as "role", COUNT(*) as "count" FROM "_auth_users" GROUP BY CASE WHEN "operatorRole" IS NULL OR "operatorRole" = '' THEN 'none' ELSE "operatorRole" END`);
+                const byStatus = await db.control.all(`SELECT CASE WHEN "banned" THEN 'disabled' ELSE 'active' END as "status", COUNT(*) as "count" FROM "_auth_users" GROUP BY CASE WHEN "banned" THEN 'disabled' ELSE 'active' END`);
+                const invites = await db.control.all(`SELECT "status", COUNT(*) as "count" FROM "_invites" GROUP BY "status"`).catch(() => []);
+                const recentSessions = await db.control.all(`SELECT s."id", s."userId", s."createdAt", s."updatedAt", s."expiresAt", u."email", u."name"
+           FROM "_auth_sessions" s LEFT JOIN "_auth_users" u ON u."id" = s."userId"
+           ORDER BY s."updatedAt" DESC LIMIT 20`).catch(() => []);
+                const safeUsers = users.map((user) => ({
+                    id: user.id,
+                    name: user.name,
+                    email: user.email,
+                    emailVerified: Boolean(user.emailVerified),
+                    operatorRole: normalizeStoredAdminRole(user.operatorRole),
+                    appRoles: parseRoles(user.appRoles),
+                    disabled: Boolean(user.banned),
+                    createdAt: user.createdAt,
+                    updatedAt: user.updatedAt
+                }));
+                return toolResult(`Returned ${safeUsers.length} user(s).`, {
+                    counts: { byOperatorRole, byStatus, invitesByStatus: invites },
+                    recentSessions: recentSessions.map((session) => redactRow(session).row),
+                    users: safeUsers,
+                    appliedFilters: { search: args.search ?? null, limit: args.limit, offset: args.offset },
+                    rowCount: safeUsers.length,
+                    returned: safeUsers.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use user_detail for one user and audit_query for user actions."
+                });
+            }
+        }),
+        operatorTool({
+            name: "user_detail",
+            description: "Inspect one user's roles, sessions, audit ids, and MCP grants without returning secrets.",
+            scope: "operator:users:read",
+            inputSchema: userDetailInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const user = args.id
+                    ? await db.control.first(`SELECT "id", "name", "email", "emailVerified", "operatorRole", "appRoles", "banned", "createdAt", "updatedAt" FROM "_auth_users" WHERE "id" = ?`, [args.id])
+                    : await db.control.first(`SELECT "id", "name", "email", "emailVerified", "operatorRole", "appRoles", "banned", "createdAt", "updatedAt" FROM "_auth_users" WHERE "email" = ?`, [args.email]);
+                if (!user)
+                    return toolResult("User not found.", { appliedFilters: args, rowCount: 0, returned: 0, truncated: false }, true);
+                const sessionCount = await db.control.first(`SELECT COUNT(*) as "count" FROM "_auth_sessions" WHERE "userId" = ?`, [String(user.id)]);
+                const recentAudit = await db.control.all(`SELECT "id", "action", "targetType", "targetId", "createdAt" FROM "_audit" WHERE "actorId" = ? ORDER BY "createdAt" DESC LIMIT 20`, [String(user.id)]);
+                const grants = await db.control.all(`SELECT "id", "subjectType", "subjectId", "clientId", "clientName", "scopes", "resource", "createdAt", "expiresAt", "revokedAt", "lastUsedAt"
+           FROM "_mcp_grants" WHERE "userId" = ? OR "subjectId" = ? ORDER BY "createdAt" DESC LIMIT 50`, [String(user.id), String(user.id)]).catch(() => []);
+                return toolResult(`Loaded user ${String(user.email)}.`, {
+                    user: {
+                        id: user.id,
+                        name: user.name,
+                        email: user.email,
+                        emailVerified: Boolean(user.emailVerified),
+                        operatorRole: normalizeStoredAdminRole(user.operatorRole),
+                        appRoles: parseRoles(user.appRoles),
+                        disabled: Boolean(user.banned),
+                        createdAt: user.createdAt,
+                        updatedAt: user.updatedAt
+                    },
+                    sessionCount: Number(sessionCount?.count ?? 0),
+                    recentAudit,
+                    activeMcpGrants: grants.map((grant) => ({ ...grant, scopes: parseJson(grant.scopes), revokedAt: grant.revokedAt ?? null })),
+                    memberships: [],
+                    appliedFilters: args,
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false,
+                    suggestedNextInspection: "Use audit_query filtered by actorId for complete action history."
+                });
+            }
+        }),
+        operatorTool({
+            name: "audit_query",
+            description: "Query hot Raybase audit rows by safe filters with parsed metadata.",
+            scope: "operator:audit:read",
+            inputSchema: auditQueryInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const where = [];
+                const params = [];
+                const applied = { ...addTimeRange(where, params, `a."createdAt"`, args), limit: args.limit, offset: args.offset };
+                if (args.action) {
+                    where.push(`a."action" = ?`);
+                    params.push(args.action);
+                    applied.action = args.action;
+                }
+                if (args.targetType) {
+                    where.push(`a."targetType" = ?`);
+                    params.push(args.targetType);
+                    applied.targetType = args.targetType;
+                }
+                if (args.targetId) {
+                    where.push(`a."targetId" = ?`);
+                    params.push(args.targetId);
+                    applied.targetId = args.targetId;
+                }
+                if (args.actorId) {
+                    where.push(`a."actorId" = ?`);
+                    params.push(args.actorId);
+                    applied.actorId = args.actorId;
+                }
+                if (args.actorEmail) {
+                    where.push(`u."email" = ?`);
+                    params.push(args.actorEmail);
+                    applied.actorEmail = args.actorEmail;
+                }
+                if (args.search) {
+                    where.push(`(a."action" LIKE ? OR a."targetType" LIKE ? OR a."targetId" LIKE ?)`);
+                    params.push(`%${args.search}%`, `%${args.search}%`, `%${args.search}%`);
+                    applied.search = args.search;
+                }
+                params.push(args.limit, args.offset);
+                const rows = await db.control.all(`SELECT a.*, u."name" AS "actorName", u."email" AS "actorEmail"
+           FROM "_audit" a LEFT JOIN "_auth_users" u ON u."id" = a."actorId"
+           ${where.length ? `WHERE ${where.join(" AND ")}` : ""}
+           ORDER BY a."createdAt" DESC LIMIT ? OFFSET ?`, params);
+                return toolResult(`Returned ${rows.length} audit row(s).`, {
+                    rows: rows.map((row) => ({ ...redactRow(row).row, metadata: parseJson(row.metadata) })),
+                    appliedFilters: applied,
+                    rowCount: rows.length,
+                    returned: rows.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use targetType/targetId filters or user_detail for actor-focused evidence."
+                });
+            }
+        }),
+        operatorTool({
+            name: "audit_archive_status",
+            description: "Inspect audit archive configuration, manifests, retention, and missing binding warnings.",
+            scope: "operator:audit:read",
+            inputSchema: z.object({ limit: z.coerce.number().int().min(1).max(100).default(20) }).strict(),
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const env = envRecord(ctx.env);
+                const manifests = await db.control.all(`SELECT * FROM "_audit_archives" ORDER BY "windowStart" DESC LIMIT ?`, [args.limit]).catch(() => []);
+                return toolResult(`Audit archive is ${auditArchiveEnabled(String(env.RAYBASE_AUDIT_ARCHIVE_ENABLED ?? "")) ? "enabled" : "disabled"}.`, {
+                    enabled: auditArchiveEnabled(String(env.RAYBASE_AUDIT_ARCHIVE_ENABLED ?? "")),
+                    hotRetentionDays: parseAuditHotDays(typeof env.RAYBASE_AUDIT_HOT_DAYS === "string" ? env.RAYBASE_AUDIT_HOT_DAYS : undefined),
+                    r2BindingPresent: Boolean(env.RAYBASE_AUDIT_ARCHIVE),
+                    manifests,
+                    lastArchivedWindow: manifests[0] ?? null,
+                    warnings: [env.RAYBASE_AUDIT_ARCHIVE ? null : "RAYBASE_AUDIT_ARCHIVE binding is missing"].filter(Boolean),
+                    appliedFilters: { limit: args.limit },
+                    rowCount: manifests.length,
+                    returned: manifests.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use audit_query for hot rows; v1 does not download archive objects."
+                });
+            }
+        }),
+        operatorTool({
+            name: "import_runs_query",
+            description: "Query admin CSV import runs with row counts, actor, file metadata, status, and suggested inspection.",
+            scope: "operator:imports:read",
+            inputSchema: importRunsQueryInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                if (!(await tableExists(db.control, importRunsTableName))) {
+                    return toolResult("CSV import history is not installed for this app.", {
+                        unavailable: true,
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Open /admin/data once after deploying the import feature so the Durable Object bootstrap can create import tables."
+                    });
+                }
+                const where = [];
+                const params = [];
+                const applied = { ...addTimeRange(where, params, `"createdAt"`, args), limit: args.limit, offset: args.offset };
+                if (args.table) {
+                    where.push(`"tableName" = ?`);
+                    params.push(args.table);
+                    applied.table = args.table;
+                }
+                if (args.status) {
+                    where.push(`"status" = ?`);
+                    params.push(args.status);
+                    applied.status = args.status;
+                }
+                if (args.actorId) {
+                    where.push(`"actorId" = ?`);
+                    params.push(args.actorId);
+                    applied.actorId = args.actorId;
+                }
+                if (args.runId) {
+                    where.push(`"id" = ?`);
+                    params.push(args.runId);
+                    applied.runId = args.runId;
+                }
+                const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+                const count = await db.control.first(`SELECT COUNT(*) as "count" FROM ${q(importRunsTableName)} ${whereSql}`, params);
+                const runs = await db.control.all(`SELECT * FROM ${q(importRunsTableName)} ${whereSql} ORDER BY "createdAt" DESC LIMIT ? OFFSET ?`, [...params, args.limit, args.offset]);
+                const failedExamples = await db.control.all(`SELECT "runId", "rowNumber", "status", "targetId", "errorJson", "createdAt"
+           FROM ${q(importRowsTableName)}
+           WHERE "status" IN ('invalid','failed')
+           ORDER BY "createdAt" DESC LIMIT 20`).catch(() => []);
+                return toolResult(`Returned ${runs.length} import run(s).`, {
+                    runs: runs.map((run) => ({
+                        ...redactRow(run).row,
+                        mappingJson: parseJson(run.mappingJson),
+                        optionsJson: parseJson(run.optionsJson),
+                        summaryJson: parseJson(run.summaryJson),
+                        errorJson: parseJson(run.errorJson)
+                    })),
+                    failedRowExamples: failedExamples.map((row) => ({ ...redactRow(row).row, errorJson: parseJson(row.errorJson) })),
+                    appliedFilters: applied,
+                    rowCount: Number(count?.count ?? runs.length),
+                    returned: runs.length,
+                    truncated: args.offset + runs.length < Number(count?.count ?? runs.length),
+                    suggestedNextInspection: "Use import_run_detail with one run id, then audit_query for admin.import.* audit events."
+                });
+            }
+        }),
+        operatorTool({
+            name: "import_run_detail",
+            description: "Inspect one admin CSV import run with bounded failed row examples and revert status.",
+            scope: "operator:imports:read",
+            inputSchema: importRunDetailInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                if (!(await tableExists(db.control, importRunsTableName))) {
+                    return toolResult("CSV import history is not installed for this app.", {
+                        unavailable: true,
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Open /admin/data once after deploying the import feature so the Durable Object bootstrap can create import tables."
+                    }, true);
+                }
+                const run = await db.control.first(`SELECT * FROM ${q(importRunsTableName)} WHERE "id" = ?`, [args.runId]);
+                if (!run)
+                    return toolResult("Import run not found.", { appliedFilters: args, rowCount: 0, returned: 0, truncated: false }, true);
+                const rows = await db.control.all(`SELECT "id", "runId", "rowNumber", "status", "targetId", "inputJson", "errorJson", "createdAt"
+           FROM ${q(importRowsTableName)}
+           WHERE "runId" = ?
+           ORDER BY "rowNumber" ASC, "createdAt" ASC LIMIT 500`, [args.runId]).catch(() => []);
+                const auditRows = await db.control.all(`SELECT "id", "action", "targetType", "targetId", "metadata", "createdAt"
+           FROM "_audit"
+           WHERE "targetId" = ? OR "metadata" LIKE ?
+           ORDER BY "createdAt" DESC LIMIT 50`, [args.runId, `%${args.runId}%`]).catch(() => []);
+                return toolResult(`Loaded import run ${args.runId}.`, {
+                    run: {
+                        ...redactRow(run).row,
+                        mappingJson: parseJson(run.mappingJson),
+                        optionsJson: parseJson(run.optionsJson),
+                        summaryJson: parseJson(run.summaryJson),
+                        errorJson: parseJson(run.errorJson)
+                    },
+                    rows: rows.map((row) => ({
+                        ...redactRow({
+                            ...row,
+                            inputJson: parseJson(row.inputJson),
+                            errorJson: parseJson(row.errorJson)
+                        }).row
+                    })),
+                    recentAudit: auditRows.map((row) => ({ ...redactRow(row).row, metadata: parseJson(row.metadata) })),
+                    revert: {
+                        status: run.status === "reverted" ? "reverted" : Number(run.insertedRows ?? 0) > Number(run.revertedRows ?? 0) ? "available_in_admin" : "not_available",
+                        insertedRows: Number(run.insertedRows ?? 0),
+                        revertedRows: Number(run.revertedRows ?? 0)
+                    },
+                    appliedFilters: args,
+                    rowCount: Number(run.totalRows ?? rows.length),
+                    returned: rows.length,
+                    truncated: rows.length >= 500,
+                    suggestedNextInspection: "Use app_record_detail for inserted target ids or audit_query for admin.import.* events."
+                });
+            }
+        }),
+        operatorTool({
+            name: "job_runs_query",
+            description: "Query Raybase job runs, registered job names, status counts, and failure summaries.",
+            scope: "operator:jobs:read",
+            inputSchema: jobRunsQueryInput,
+            handler: async (args, ctx) => {
+                const stub = dataStub(ctx.env);
+                const where = [];
+                const params = [];
+                const applied = { ...addTimeRange(where, params, `"createdAt"`, args), limit: args.limit, offset: args.offset };
+                if (args.status) {
+                    where.push(`"status" = ?`);
+                    params.push(args.status);
+                    applied.status = args.status;
+                }
+                if (args.jobName) {
+                    where.push(`"jobName" = ?`);
+                    params.push(args.jobName);
+                    applied.jobName = args.jobName;
+                }
+                if (args.actorId) {
+                    where.push(`"actorId" = ?`);
+                    params.push(args.actorId);
+                    applied.actorId = args.actorId;
+                }
+                if (args.runId) {
+                    where.push(`"id" = ?`);
+                    params.push(args.runId);
+                    applied.runId = args.runId;
+                }
+                if (args.batchId) {
+                    where.push(`"batchId" = ?`);
+                    params.push(args.batchId);
+                    applied.batchId = args.batchId;
+                }
+                params.push(args.limit, args.offset);
+                const runs = await stub.all(`SELECT * FROM "_job_runs" ${where.length ? `WHERE ${where.join(" AND ")}` : ""} ORDER BY "createdAt" DESC LIMIT ? OFFSET ?`, params).catch(() => []);
+                const counts = await stub.all(`SELECT "status", COUNT(*) as "count" FROM "_job_runs" GROUP BY "status" ORDER BY "status"`).catch(() => []);
+                const failures = runs.filter((run) => ["failed", "denied", "expired"].includes(run.status)).slice(0, 20);
+                return toolResult(`Returned ${runs.length} job run(s).`, {
+                    runs: runs.map((run) => redactRow(run).row),
+                    statusCounts: counts,
+                    registeredJobs: Object.keys(options.jobs ?? {}),
+                    databaseSizeBytes: await stub.databaseSize().catch(() => null),
+                    failureSummaries: failures.map((run) => ({ id: run.id, jobName: run.jobName, status: run.status, endedAt: run.endedAt, error: parseJson(run.errorJson) })),
+                    appliedFilters: applied,
+                    rowCount: runs.length,
+                    returned: runs.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use job_run_detail for one failed run."
+                });
+            }
+        }),
+        operatorTool({
+            name: "job_run_detail",
+            description: "Inspect one job run with compact event history and redacted input/result/error fields.",
+            scope: "operator:jobs:read",
+            inputSchema: jobRunDetailInput,
+            handler: async (args, ctx) => {
+                const stub = dataStub(ctx.env);
+                const run = await stub.first(`SELECT * FROM "_job_runs" WHERE "id" = ?`, [args.runId]).catch(() => null);
+                if (!run)
+                    return toolResult("Job run not found.", { appliedFilters: args, rowCount: 0, returned: 0, truncated: false }, true);
+                const events = await stub.all(`SELECT * FROM "_job_events" WHERE "runId" = ? ORDER BY "createdAt" ASC LIMIT 500`, [run.id]).catch(() => []);
+                const safeRun = redactRow({
+                    ...run,
+                    inputJson: parseJson(run.inputJson),
+                    resultJson: parseJson(run.resultJson),
+                    errorJson: parseJson(run.errorJson),
+                    artifactJson: parseJson(run.artifactJson),
+                    progressJson: parseJson(run.progressJson)
+                });
+                return toolResult(`Loaded job run ${run.id}.`, {
+                    run: safeRun.row,
+                    events: events.map((event) => redactRow({ ...event, dataJson: parseJson(event.dataJson) }).row),
+                    lineage: { retryOfRunId: run.retryOfRunId, batchId: run.batchId ?? null, continuationOfBatchId: run.continuationOfBatchId ?? null },
+                    appliedFilters: args,
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: safeRun.truncated,
+                    suggestedNextInspection: run.batchId || run.continuationOfBatchId
+                        ? "Use job_batch_detail with the batch id for siblings and the continuation run."
+                        : "Use audit_query with targetId equal to this run id."
+                });
+            }
+        }),
+        operatorTool({
+            name: "job_batches_query",
+            description: "Query Raybase job batches (fan-out and join) with child counts, progress, and continuation run status.",
+            scope: "operator:jobs:read",
+            inputSchema: jobBatchesQueryInput,
+            handler: async (args, ctx) => {
+                const stub = dataStub(ctx.env);
+                const result = await stub.listJobBatches({ status: args.status, name: args.name, key: args.key, limit: args.limit })
+                    .catch(() => ({ batches: [], counts: [] }));
+                return toolResult(`Returned ${result.batches.length} job batch(es).`, {
+                    batches: result.batches.map(operatorBatchSummary),
+                    statusCounts: result.counts,
+                    appliedFilters: args,
+                    rowCount: result.batches.length,
+                    returned: result.batches.length,
+                    truncated: result.batches.length >= args.limit,
+                    suggestedNextInspection: "Use job_batch_detail for one batch's children and continuation run."
+                });
+            }
+        }),
+        operatorTool({
+            name: "job_batch_detail",
+            description: "Inspect one job batch: counts, a cursor-paginated page of child runs with redacted results and errors, and the continuation run.",
+            scope: "operator:jobs:read",
+            inputSchema: jobBatchDetailInput,
+            handler: async (args, ctx) => {
+                const stub = dataStub(ctx.env);
+                const batch = await stub.getJobBatch(args.batchId).catch(() => null);
+                if (!batch)
+                    return toolResult("Job batch not found.", { appliedFilters: args, rowCount: 0, returned: 0, truncated: false }, true);
+                const page = await stub.listJobBatchChildren({ batchId: batch.id, status: args.status, cursor: args.cursor ?? null, limit: args.limit });
+                const continuationRun = batch.continuationRunId
+                    ? await stub.first(`SELECT * FROM "_job_runs" WHERE "id" = ?`, [batch.continuationRunId]).catch(() => null)
+                    : null;
+                return toolResult(`Loaded job batch ${batch.key}.`, {
+                    batch: operatorBatchSummary(batch),
+                    children: page.children.map((child) => redactRow(child).row),
+                    nextCursor: page.cursor,
+                    continuationRun: continuationRun
+                        ? redactRow({ ...continuationRun, inputJson: parseJson(continuationRun.inputJson), resultJson: parseJson(continuationRun.resultJson), errorJson: parseJson(continuationRun.errorJson) }).row
+                        : null,
+                    appliedFilters: args,
+                    rowCount: batch.counts.total,
+                    returned: page.children.length,
+                    truncated: page.cursor !== null,
+                    suggestedNextInspection: page.cursor
+                        ? "Call job_batch_detail again with cursor set to nextCursor for more children."
+                        : "Use job_run_detail for one child or the continuation run."
+                });
+            }
+        }),
+        operatorTool({
+            name: "retrieval_indexes_summary",
+            description: "Summarize declared Raybase retrieval indexes, backend configuration, chunk counts, and last reindex evidence.",
+            scope: "operator:retrieval:read",
+            inputSchema: z.object({}).strict(),
+            handler: async (_args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const summary = await retrievalIndexesSummary({
+                    control: db.control,
+                    retrieval: options.retrieval,
+                    env: ctx.env,
+                    appId: options.config.appName
+                });
+                return toolResult(`Returned ${summary.indexes.length} retrieval index(es).`, {
+                    ...summary,
+                    rowCount: summary.indexes.length,
+                    returned: summary.indexes.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use retrieval_index_detail with an indexName for recent errors and reindex runs."
+                });
+            }
+        }),
+        operatorTool({
+            name: "retrieval_index_detail",
+            description: "Inspect one retrieval index with redacted chunk error summaries and recent reindex runs.",
+            scope: "operator:retrieval:read",
+            inputSchema: retrievalIndexDetailInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const detail = await retrievalIndexDetail({
+                    control: db.control,
+                    retrieval: options.retrieval,
+                    indexName: args.indexName,
+                    env: ctx.env,
+                    appId: options.config.appName
+                });
+                return toolResult(`Loaded retrieval index ${args.indexName}.`, {
+                    ...detail,
+                    recentErrors: detail.recentErrors.map((row) => redactRow(row).row),
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false,
+                    suggestedNextInspection: "Use retrieval_reindex_runs_query for broader reindex history."
+                });
+            }
+        }),
+        operatorTool({
+            name: "retrieval_reindex_runs_query",
+            description: "Query retrieval reindex run history without exposing raw vector ids, values, or metadata.",
+            scope: "operator:retrieval:read",
+            inputSchema: retrievalRunsQueryInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const result = await retrievalReindexRunsQuery({
+                    control: db.control,
+                    indexName: args.indexName,
+                    backend: args.backend,
+                    namespace: args.namespace,
+                    limit: args.limit,
+                    offset: args.offset
+                });
+                return toolResult(`Returned ${result.runs.length} retrieval reindex run(s).`, {
+                    runs: result.runs.map((row) => ({ ...redactRow(row).row, summaryJson: parseJson(row.summaryJson) })),
+                    appliedFilters: args,
+                    rowCount: result.runs.length,
+                    returned: result.runs.length,
+                    truncated: result.runs.length >= args.limit,
+                    suggestedNextInspection: "Use retrieval_index_detail for current chunk status counts."
+                });
+            }
+        }),
+        operatorTool({
+            name: "search_indexes_summary",
+            description: "Summarize SQL full-text search indexes, source tables, document counts, and last reindex evidence.",
+            scope: "operator:search:read",
+            inputSchema: z.object({}).strict(),
+            handler: async (_args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const result = await searchIndexesSummary({ control: db.control, search: options.search });
+                return toolResult(`Found ${result.indexes.length} search index(es).`, {
+                    ...result,
+                    rowCount: result.indexes.length,
+                    returned: result.indexes.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use search_index_detail with an indexName for recent errors and reindex runs."
+                });
+            }
+        }),
+        operatorTool({
+            name: "search_index_detail",
+            description: "Inspect one SQL full-text search index, including source coverage, recent errors, and reindex runs.",
+            scope: "operator:search:read",
+            inputSchema: searchIndexDetailInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const detail = await searchIndexDetail({ control: db.control, search: options.search, indexName: args.indexName });
+                return toolResult(`Loaded search index ${args.indexName}.`, {
+                    ...detail,
+                    recentErrors: detail.recentErrors.map((row) => redactRow(row).row),
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false,
+                    suggestedNextInspection: "Use app_data_search with a bounded query to inspect policy-hydrated result snippets."
+                });
+            }
+        }),
+        operatorTool({
+            name: "search_reindex_runs_query",
+            description: "Query SQL full-text search reindex run history without exposing raw document bodies.",
+            scope: "operator:search:read",
+            inputSchema: searchRunsQueryInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const result = await searchReindexRunsQuery({
+                    control: db.control,
+                    indexName: args.indexName,
+                    status: args.status,
+                    limit: args.limit,
+                    offset: args.offset
+                });
+                return toolResult(`Returned ${result.runs.length} search reindex run(s).`, {
+                    runs: result.runs.map((row) => ({ ...redactRow(row).row, summaryJson: parseJson(row.summaryJson) })),
+                    appliedFilters: args,
+                    rowCount: result.runs.length,
+                    returned: result.runs.length,
+                    truncated: result.runs.length >= args.limit,
+                    suggestedNextInspection: "Use search_index_detail for current document status counts."
+                });
+            }
+        }),
+        operatorTool({
+            name: "mcp_grants_summary",
+            description: "Summarize app-user and operator MCP grants plus recent grant events.",
+            scope: "operator:mcp-grants:read",
+            inputSchema: listInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const grants = (await listMcpGrants(db.control)).slice(args.offset, args.offset + args.limit);
+                const events = await db.control.all(`SELECT * FROM "_mcp_grant_events" ORDER BY "createdAt" DESC LIMIT ?`, [Math.min(args.limit, 100)]).catch(() => []);
+                return toolResult(`Returned ${grants.length} MCP grant(s).`, {
+                    grants: grants.map((grant) => ({ ...grant, scopes: parseJson(grant.scopes), surface: String(grant.subjectType).includes("operator") ? "operator" : "app" })),
+                    counts: {
+                        active: grants.filter((grant) => !grant.revokedAt).length,
+                        revoked: grants.filter((grant) => grant.revokedAt).length,
+                        operator: grants.filter((grant) => String(grant.subjectType).includes("operator")).length,
+                        app: grants.filter((grant) => !String(grant.subjectType).includes("operator")).length
+                    },
+                    recentEvents: events.map((event) => ({ ...redactRow(event).row, metadata: parseJson(event.metadata) })),
+                    appliedFilters: { limit: args.limit, offset: args.offset },
+                    rowCount: grants.length,
+                    returned: grants.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use audit_query action operator_mcp.tool.call for operator activity."
+                });
+            }
+        }),
+        operatorTool({
+            name: "backup_status",
+            description: "Inspect backup, PITR, audit archive, and storage metadata caveats without creating or downloading backups.",
+            scope: "operator:backups:read",
+            inputSchema: z.object({}).strict(),
+            handler: async (_args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const env = envRecord(ctx.env);
+                const now = new Date();
+                const auditEvents = await db.control.all(`SELECT "id", "action", "targetType", "targetId", "createdAt" FROM "_audit"
+           WHERE "action" IN ('database.backup','database.restore','database.pitr.restore')
+           ORDER BY "createdAt" DESC LIMIT 20`).catch(() => []);
+                return toolResult("Backup status inspected without creating a backup.", {
+                    encryptedBackup: {
+                        availableFromAdmin: true,
+                        archiveFormat: 2,
+                        encrypted: true,
+                        caveat: options.storage ? "Encrypted backups include file metadata only, not R2 file bytes." : null
+                    },
+                    pitr: {
+                        supported: !pitrUnavailableReason(ctx.env),
+                        reason: pitrUnavailableReason(ctx.env),
+                        earliestRestoreTime: new Date(now.getTime() - pitrRetentionMs).toISOString()
+                    },
+                    auditArchive: {
+                        enabled: auditArchiveEnabled(String(env.RAYBASE_AUDIT_ARCHIVE_ENABLED ?? "")),
+                        r2BindingPresent: Boolean(env.RAYBASE_AUDIT_ARCHIVE)
+                    },
+                    recentBackupRestoreAuditEvents: auditEvents,
+                    appliedFilters: {},
+                    rowCount: auditEvents.length,
+                    returned: auditEvents.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use audit_archive_status for archive manifests."
+                });
+            }
+        }),
+        operatorTool({
+            name: "storage_usage_summary",
+            description: "Summarize file metadata counts, aggregate sizes, configured buckets, and storage warnings without downloading bytes.",
+            scope: "operator:storage:read",
+            inputSchema: z.object({}).strict(),
+            handler: async (_args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const exists = await tableExists(db.control, raybaseFilesTableName);
+                const aggregates = exists
+                    ? await db.control.all(`SELECT "bucket", "status", COUNT(*) as "count", COALESCE(SUM("size"), 0) as "sizeBytes"
+               FROM "_files" GROUP BY "bucket", "status" ORDER BY "bucket", "status"`)
+                    : [];
+                const orphanErrors = exists
+                    ? await db.control.all(`SELECT "bucket", COUNT(*) as "count" FROM "_files"
+               WHERE "deleteError" IS NOT NULL OR "status" IN ('uploading','deleting','quarantined')
+               GROUP BY "bucket"`)
+                    : [];
+                return toolResult(`Storage metadata has ${aggregates.length} aggregate row(s).`, {
+                    enabled: Boolean(options.storage),
+                    r2BindingPresent: Boolean(envRecord(ctx.env).RAYBASE_FILES),
+                    buckets: Object.values(options.storage?.buckets ?? {}).map((bucket) => ({
+                        name: bucket.name,
+                        label: bucket.label ?? null,
+                        maxSizeBytes: bucket.maxSizeBytes ?? null,
+                        accept: bucket.accept ?? []
+                    })),
+                    metadataTablePresent: exists,
+                    aggregates,
+                    indicators: { orphanOrErrorCounts: orphanErrors },
+                    appliedFilters: {},
+                    rowCount: aggregates.length,
+                    returned: aggregates.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use app audit/file metadata admin views for one file id; v1 does not download bytes."
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_data_table_summary",
+            description: "List app-defined tables, counts, columns, labels, references, and Operator MCP query safety.",
+            scope: "operator:app-data:read",
+            inputSchema: z.object({}).strict(),
+            handler: async (_args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const tables = await Promise.all(Object.entries(options.schema.tables).map(async ([key, table]) => ({
+                    key,
+                    name: table.name,
+                    label: table.label ?? null,
+                    rowCount: await safeCount(db.control, table.name),
+                    safeToQuery: true,
+                    columns: Object.entries(table.columns).map(([name, column]) => ({
+                        name,
+                        kind: column.kind,
+                        required: Boolean(column.required),
+                        primaryKey: Boolean(column.primaryKey),
+                        label: column.label ?? null,
+                        references: getReferenceName(column)
+                    }))
+                })));
+                return toolResult(`Found ${tables.length} app data table(s).`, {
+                    tables,
+                    appliedFilters: {},
+                    rowCount: tables.length,
+                    returned: tables.length,
+                    truncated: false,
+                    suggestedNextInspection: "Use app_data_query with { from, select, where, limit } for bounded relational evidence queries."
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_data_query",
+            description: "Read bounded app table rows through a schema-validated relational JSON AST compiled to parameterized SELECT SQL.",
+            scope: "operator:app-data:read",
+            inputSchema: operatorAppDataQueryInput,
+            handler: async (args, ctx) => {
+                const compiled = compileOperatorAppDataQuery({
+                    schema: options.schema,
+                    systemTableNames: systemTableNames(options)
+                }, args);
+                const { table } = tableByInput(options.schema, compiled.appliedQuery.from);
+                const db = operatorDb(ctx, options);
+                const [rows, countRow] = await Promise.all([
+                    db.control.all(compiled.sql, compiled.params),
+                    db.control.first(compiled.countSql, compiled.countParams)
+                ]);
+                const safe = redactRows(normalizeSelectedAppRows(table, compiled.selectedColumns, rows));
+                const rowIds = safe.rows.map((row) => row.id).filter(Boolean);
+                return toolResult(`Returned ${safe.rows.length} row(s) from ${table.name}.`, {
+                    table: table.name,
+                    tablesTouched: compiled.tablesTouched,
+                    rows: safe.rows,
+                    rowIds,
+                    sql: compiled.sql,
+                    params: redactCompiledQueryParams(compiled),
+                    appliedQuery: compiled.appliedQuery,
+                    redactedColumns: safe.redactedColumns,
+                    truncatedColumns: safe.truncatedColumns,
+                    referenceValidation: compiled.referenceValidation,
+                    rowCount: Number(countRow?.count ?? safe.rows.length),
+                    returned: safe.rows.length,
+                    truncated: safe.truncated || rows.length >= compiled.appliedQuery.limit,
+                    suggestedNextInspection: rowIds.length
+                        ? "Use app_record_detail with one row id for linked evidence."
+                        : "Use app_data_table_summary or a narrower app_data_query for additional evidence."
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_data_search",
+            description: "Search app data through Raybase SQL FTS and return bounded, redacted snippets hydrated through app policies.",
+            scope: "operator:app-data:read",
+            inputSchema: appDataSearchInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                const table = args.table ? tableByInput(options.schema, args.table).table : null;
+                const client = db.for({ user: ctx.user, adminOverride: true });
+                const result = await searchIndex({
+                    schema: options.schema,
+                    db: client,
+                    control: db.control,
+                    search: options.search,
+                    indexName: args.indexName,
+                    query: args.query,
+                    limit: args.limit,
+                    sourceTables: table ? [table.name] : undefined
+                });
+                const safeResults = result.results.map((entry) => {
+                    const safe = redactRow({
+                        title: entry.title,
+                        url: entry.url,
+                        snippet: entry.snippet,
+                        metadata: entry.metadata
+                    });
+                    return {
+                        ...entry,
+                        title: safe.row.title,
+                        url: safe.row.url,
+                        snippet: safe.row.snippet,
+                        metadata: safe.row.metadata
+                    };
+                });
+                return toolResult(`Returned ${safeResults.length} app data search result(s).`, {
+                    results: safeResults,
+                    appliedFilters: { indexName: args.indexName, table: table?.name ?? null, query: args.query, limit: args.limit, offset: args.offset },
+                    rowCount: safeResults.length,
+                    returned: safeResults.length,
+                    truncated: safeResults.length >= args.limit,
+                    suggestedNextInspection: "Use app_record_detail with one returned sourceId for full redacted row context."
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_record_detail",
+            description: "Read one app table row by id with redaction, reference labels, and recent audit ids.",
+            scope: "operator:app-data:read",
+            inputSchema: appRecordDetailInput,
+            handler: async (args, ctx) => {
+                const { key, table } = tableByInput(options.schema, args.table);
+                const db = operatorDb(ctx, options);
+                const client = db.for({ user: ctx.user, adminOverride: true });
+                const row = await client.get(key, args.id);
+                if (!row)
+                    return toolResult("App record not found.", { appliedFilters: args, rowCount: 0, returned: 0, truncated: false }, true);
+                const safe = redactRow(row);
+                const auditIds = await db.control.all(`SELECT "id", "action", "createdAt" FROM "_audit" WHERE "targetType" = ? AND "targetId" = ? ORDER BY "createdAt" DESC LIMIT 20`, [table.name, args.id]).catch(() => []);
+                return toolResult(`Loaded ${table.name} ${args.id}.`, {
+                    table: table.name,
+                    row: safe.row,
+                    redactedColumns: safe.redactedColumns,
+                    truncatedColumns: safe.truncatedColumns,
+                    references: Object.entries(table.columns)
+                        .map(([name, column]) => ({ column: name, references: getReferenceName(column), value: row[name] }))
+                        .filter((entry) => entry.references),
+                    recentAudit: auditIds,
+                    appliedFilters: args,
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: safe.truncated,
+                    suggestedNextInspection: "Use audit_query for the returned recent audit ids."
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_data_create",
+            description: "Create one app-defined table row through schema validation, policies, invariants, realtime/search hooks, and audited admin metadata.",
+            scope: "operator:app-data:write",
+            inputSchema: appDataCreateInput,
+            annotations: { idempotentHint: false },
+            handler: async (args, ctx) => {
+                const { key, table } = tableByInput(options.schema, args.table);
+                const values = inputSchemaForTable(table, "create").parse(args.values);
+                const row = await operatorMutationDb(ctx, options).create(key, values);
+                const safe = redactRow(row);
+                return toolResult(`Created ${table.name} ${String(row.id)}.`, {
+                    operation: "create",
+                    table: table.name,
+                    id: row.id,
+                    row: safe.row,
+                    redactedColumns: safe.redactedColumns,
+                    truncatedColumns: safe.truncatedColumns,
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { table: table.name },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: safe.truncated
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_data_update",
+            description: "Update one app-defined table row through schema validation, policies, invariants, realtime/search hooks, and audited admin metadata.",
+            scope: "operator:app-data:write",
+            inputSchema: appDataUpdateInput,
+            annotations: { idempotentHint: true },
+            handler: async (args, ctx) => {
+                const { key, table } = tableByInput(options.schema, args.table);
+                const patch = inputSchemaForTable(table, "update").partial().parse(args.patch);
+                const row = await operatorMutationDb(ctx, options).update(key, args.id, patch);
+                const safe = redactRow(row);
+                return toolResult(`Updated ${table.name} ${String(row.id)}.`, {
+                    operation: "update",
+                    table: table.name,
+                    id: row.id,
+                    row: safe.row,
+                    redactedColumns: safe.redactedColumns,
+                    truncatedColumns: safe.truncatedColumns,
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { table: table.name, id: args.id },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: safe.truncated
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_data_delete",
+            description: "Delete one app-defined table row after explicit confirmation through policies, realtime/search hooks, and audited admin metadata.",
+            scope: "operator:app-data:delete",
+            inputSchema: appDataDeleteInput,
+            annotations: { destructiveHint: true, idempotentHint: false },
+            handler: async (args, ctx) => {
+                const { key, table } = tableByInput(options.schema, args.table);
+                await operatorMutationDb(ctx, options).delete(key, args.id);
+                return toolResult(`Deleted ${table.name} ${args.id}.`, {
+                    operation: "delete",
+                    table: table.name,
+                    id: args.id,
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { table: table.name, id: args.id, confirm: true },
+                    rowCount: 1,
+                    returned: 0,
+                    truncated: false
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_setting_set",
+            description: "Set one editable app-scoped Raybase setting override with existing setting validation and audited metadata.",
+            scope: "operator:settings:write",
+            inputSchema: appSettingSetInput,
+            annotations: { idempotentHint: true },
+            handler: async (args, ctx) => {
+                const definitions = options.settings ?? {};
+                if (!Object.keys(definitions).length)
+                    throw new Error("No Raybase settings definitions are registered for this app");
+                const definition = definitions[args.key];
+                if (!definition)
+                    throw new Error(`Unknown setting: ${args.key}`);
+                if (!canWriteCoreSetting(ctx.user, definition, "app"))
+                    throw new Error("Setting is read-only");
+                const settingsAppId = raybaseRuntimeSettingsAppId(ctx.env);
+                const result = await setRaybaseSettingOverride({
+                    env: ctx.env,
+                    definitions,
+                    config: options.config,
+                    storage: createSqlSettingsStorage(ctx.control),
+                    user: ctx.user,
+                    appId: settingsAppId,
+                    key: args.key,
+                    scope: "app",
+                    subjectId: appSettingsSubjectId,
+                    value: args.value,
+                    updatedBy: ctx.user.id
+                });
+                const metadata = settingAuditMetadata({
+                    key: args.key,
+                    appId: settingsAppId,
+                    scope: "app",
+                    subjectId: appSettingsSubjectId,
+                    type: result.after.type,
+                    sourceBefore: result.before.source,
+                    sourceAfter: result.after.source,
+                    valueChanged: settingValueChanged(result.before, result.after)
+                });
+                await audit(ctx.control, ctx.user.id, "setting.override.set", "_settings", args.key, mutationAuditMetadata(ctx, metadata));
+                return toolResult(`Set app setting ${args.key}.`, {
+                    operation: "set",
+                    key: args.key,
+                    type: result.after.type,
+                    sourceBefore: result.before.source,
+                    sourceAfter: result.after.source,
+                    valueChanged: metadata.valueChanged,
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { key: args.key, scope: "app" },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false
+                });
+            }
+        }),
+        operatorTool({
+            name: "app_setting_reset",
+            description: "Reset one editable app-scoped Raybase setting override to its default or inherited source with audited metadata.",
+            scope: "operator:settings:write",
+            inputSchema: appSettingResetInput,
+            annotations: { idempotentHint: true },
+            handler: async (args, ctx) => {
+                const definitions = options.settings ?? {};
+                if (!Object.keys(definitions).length)
+                    throw new Error("No Raybase settings definitions are registered for this app");
+                const definition = definitions[args.key];
+                if (!definition)
+                    throw new Error(`Unknown setting: ${args.key}`);
+                if (!canWriteCoreSetting(ctx.user, definition, "app"))
+                    throw new Error("Setting is read-only");
+                const settingsAppId = raybaseRuntimeSettingsAppId(ctx.env);
+                const result = await resetRaybaseSettingOverride({
+                    env: ctx.env,
+                    definitions,
+                    config: options.config,
+                    storage: createSqlSettingsStorage(ctx.control),
+                    user: ctx.user,
+                    appId: settingsAppId,
+                    key: args.key,
+                    scope: "app",
+                    subjectId: appSettingsSubjectId
+                });
+                const metadata = settingAuditMetadata({
+                    key: args.key,
+                    appId: settingsAppId,
+                    scope: "app",
+                    subjectId: appSettingsSubjectId,
+                    type: result.after.type,
+                    sourceBefore: result.before.source,
+                    sourceAfter: result.after.source,
+                    valueChanged: settingValueChanged(result.before, result.after)
+                });
+                await audit(ctx.control, ctx.user.id, "setting.override.reset", "_settings", args.key, mutationAuditMetadata(ctx, metadata));
+                return toolResult(`Reset app setting ${args.key}.`, {
+                    operation: "reset",
+                    key: args.key,
+                    type: result.after.type,
+                    sourceBefore: result.before.source,
+                    sourceAfter: result.after.source,
+                    valueChanged: metadata.valueChanged,
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { key: args.key, scope: "app" },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false
+                });
+            }
+        }),
+        operatorTool({
+            name: "user_invite_create",
+            description: "Create a normal app-user invite with app roles only; operator roles cannot be assigned and the operation is audited.",
+            scope: "operator:users:invite",
+            inputSchema: userInviteCreateInput,
+            annotations: { idempotentHint: false },
+            handler: async (args, ctx) => {
+                const email = args.email.trim().toLowerCase();
+                const roles = normalizeRoles(args.appRoles?.length ? args.appRoles.map(String) : ["user"]);
+                const invite = await createInvite(ctx.control, authSecret(ctx.env), {
+                    email,
+                    role: roles.find((role) => role !== "user") || roles[0],
+                    roles,
+                    operatorRole: null,
+                    createdBy: ctx.user.id
+                });
+                const url = new URL(`/invite/${invite.token}`, new URL(ctx.request.url).origin).toString();
+                await audit(ctx.control, ctx.user.id, "invite.create", "_invites", undefined, mutationAuditMetadata(ctx, {
+                    email,
+                    appRoles: roles,
+                    emailQueued: false
+                }));
+                return toolResult(`Created invite for ${email}.`, {
+                    operation: "invite",
+                    email,
+                    appRoles: roles,
+                    url,
+                    expiresAt: invite.expiresAt,
+                    emailQueued: false,
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { email },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false
+                });
+            }
+        }),
+        operatorTool({
+            name: "user_deactivate",
+            description: "Deactivate one non-owner user after explicit confirmation, delete their sessions, and audit the lifecycle operation.",
+            scope: "operator:users:lifecycle",
+            inputSchema: userDeactivateInput,
+            annotations: { destructiveHint: true, idempotentHint: false },
+            handler: async (args, ctx) => {
+                const target = await resolveUserTarget(ctx.control, args);
+                const disabledReason = disableUserDisabledReason(ctx.user, target);
+                if (disabledReason)
+                    throw new Error(disabledReason);
+                const targetId = String(target.id);
+                const sessionsBefore = await activeSessionCount(ctx.control, targetId);
+                const reason = args.reason?.trim() || "Disabled by Raybase Operator MCP";
+                await ctx.control.run(`UPDATE "_auth_users" SET "banned" = 1, "banReason" = ?, "updatedAt" = ? WHERE "id" = ?`, [reason, Date.now(), targetId]);
+                await ctx.control.run(`DELETE FROM "_auth_sessions" WHERE "userId" = ?`, [targetId]);
+                await audit(ctx.control, ctx.user.id, "user.disable", "user", targetId, mutationAuditMetadata(ctx, {
+                    reason,
+                    sessionsRevoked: sessionsBefore
+                }));
+                return toolResult(`Deactivated user ${String(target.email)}.`, {
+                    operation: "deactivate",
+                    user: { id: targetId, email: target.email, disabled: true },
+                    sessionsRevoked: sessionsBefore,
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { id: args.id ?? null, email: args.email ?? null, confirm: true },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false
+                });
+            }
+        }),
+        operatorTool({
+            name: "user_reactivate",
+            description: "Reactivate one user account by clearing disabled fields and audit the lifecycle operation.",
+            scope: "operator:users:lifecycle",
+            inputSchema: userReactivateInput,
+            annotations: { idempotentHint: true },
+            handler: async (args, ctx) => {
+                const target = await resolveUserTarget(ctx.control, args);
+                const targetId = String(target.id);
+                await ctx.control.run(`UPDATE "_auth_users" SET "banned" = 0, "banReason" = NULL, "banExpires" = NULL, "updatedAt" = ? WHERE "id" = ?`, [Date.now(), targetId]);
+                await audit(ctx.control, ctx.user.id, "user.enable", "user", targetId, mutationAuditMetadata(ctx));
+                return toolResult(`Reactivated user ${String(target.email)}.`, {
+                    operation: "reactivate",
+                    user: { id: targetId, email: target.email, disabled: false },
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { id: args.id ?? null, email: args.email ?? null },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false
+                });
+            }
+        }),
+        operatorTool({
+            name: "user_sessions_revoke",
+            description: "Revoke sessions for one user after explicit confirmation and audit the lifecycle operation.",
+            scope: "operator:users:lifecycle",
+            inputSchema: userSessionsRevokeInput,
+            annotations: { destructiveHint: true, idempotentHint: true },
+            handler: async (args, ctx) => {
+                const target = await resolveUserTarget(ctx.control, args);
+                const targetId = String(target.id);
+                const sessionsBefore = await activeSessionCount(ctx.control, targetId);
+                await ctx.control.run(`DELETE FROM "_auth_sessions" WHERE "userId" = ?`, [targetId]);
+                await audit(ctx.control, ctx.user.id, "user.sessions.revoke", "user", targetId, mutationAuditMetadata(ctx, {
+                    reason: args.reason?.trim() || null,
+                    sessionsRevoked: sessionsBefore
+                }));
+                return toolResult(`Revoked ${sessionsBefore} session(s) for ${String(target.email)}.`, {
+                    operation: "sessions_revoke",
+                    user: { id: targetId, email: target.email },
+                    sessionsRevoked: sessionsBefore,
+                    audit: { mcpGrantId: ctx.mcp.grantId, mcpClientId: ctx.mcp.clientId },
+                    appliedFilters: { id: args.id ?? null, email: args.email ?? null, confirm: true },
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false
+                });
+            }
+        }),
+        {
+            name: "agent_conversations_query",
+            description: "Query Raybase Agent conversation catalog rows with lifecycle, principal, route, surface, and organization filters.",
+            inputSchema: agentConversationsQueryInput,
+            annotations: { readOnlyHint: true },
+            scopes: [...agentReadScopes],
+            handler: async (rawArgs, ctx) => {
+                const args = rawArgs;
+                // ctx.control so layered runtimes (Pro) can swap in an org-scoped executor.
+                const control = ctx.control;
+                if (!(await tableExists(control, "_agent_instances"))) {
+                    return toolResult("Agent conversation catalog is not installed for this app.", {
+                        unavailable: true,
+                        provider: "Agent conversations",
+                        requiredScope: "operator:agent:read",
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Enable a Raybase Agent such as Guide so _agent_instances is registered."
+                    });
+                }
+                const where = [];
+                const params = [];
+                const applied = { ...addTimeRange(where, params, `"createdAt"`, args), limit: args.limit, offset: args.offset };
+                if (args.agentName) {
+                    where.push(`"agentName" = ?`);
+                    params.push(args.agentName);
+                    applied.agentName = args.agentName;
+                }
+                if (args.runtime) {
+                    where.push(`"runtime" = ?`);
+                    params.push(args.runtime);
+                    applied.runtime = args.runtime;
+                }
+                if (args.triggerType) {
+                    where.push(`"triggerType" = ?`);
+                    params.push(args.triggerType);
+                    applied.triggerType = args.triggerType;
+                }
+                if (args.status) {
+                    where.push(`"status" = ?`);
+                    params.push(args.status);
+                    applied.status = args.status;
+                }
+                if (args.lifecycleState) {
+                    if (args.lifecycleState === "cleanup")
+                        where.push(`"status" IN ('cleanupRequested', 'deleting', 'cleanupError')`);
+                    else
+                        where.push(`"status" = ?`);
+                    if (args.lifecycleState !== "cleanup")
+                        params.push(args.lifecycleState);
+                    applied.lifecycleState = args.lifecycleState;
+                }
+                if (args.principalKind) {
+                    where.push(`"principalKind" = ?`);
+                    params.push(args.principalKind);
+                    applied.principalKind = args.principalKind;
+                }
+                if (args.userId) {
+                    where.push(`"userId" = ?`);
+                    params.push(args.userId);
+                    applied.userId = args.userId;
+                }
+                if (args.publicScopeHash) {
+                    where.push(`"publicScopeHash" = ?`);
+                    params.push(args.publicScopeHash);
+                    applied.publicScopeHash = args.publicScopeHash;
+                }
+                if (args.organizationId) {
+                    where.push(`"organizationId" = ?`);
+                    params.push(args.organizationId);
+                    applied.organizationId = args.organizationId;
+                }
+                if (args.surface) {
+                    where.push(`"surface" = ?`);
+                    params.push(args.surface);
+                    applied.surface = args.surface;
+                }
+                if (args.route) {
+                    where.push(`"route" = ?`);
+                    params.push(args.route);
+                    applied.route = args.route;
+                }
+                if (args.search) {
+                    where.push(`("conversationId" = ? OR "agentTitle" LIKE ? OR "route" LIKE ? OR "metadataJson" LIKE ? OR "lastError" LIKE ?)`);
+                    params.push(args.search, `%${args.search}%`, `%${args.search}%`, `%${args.search}%`, `%${args.search}%`);
+                    applied.search = args.search;
+                }
+                const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+                const count = await control.first(`SELECT COUNT(*) as "count" FROM ${q("_agent_instances")} ${whereSql}`, params);
+                const rows = await control.all(`SELECT * FROM ${q("_agent_instances")} ${whereSql}
+           ORDER BY "updatedAt" DESC LIMIT ? OFFSET ?`, [...params, args.limit, args.offset]);
+                return toolResult(`Returned ${rows.length} Agent conversation(s).`, {
+                    conversations: rows.map((row) => safeAgentConversation(row)),
+                    appliedFilters: applied,
+                    rowCount: Number(count?.count ?? rows.length),
+                    returned: rows.length,
+                    truncated: args.offset + rows.length < Number(count?.count ?? rows.length),
+                    suggestedNextInspection: "Use agent_runs_query with a conversationId for per-turn status and error evidence, or agent_conversation_read for bounded active transcript content."
+                });
+            }
+        },
+        {
+            name: "agent_conversation_read",
+            description: "Read one Raybase Agent conversation catalog row plus bounded redacted active transcript content.",
+            inputSchema: agentConversationReadInput,
+            annotations: { readOnlyHint: true },
+            scopes: [...agentReadScopes],
+            handler: async (rawArgs, ctx) => {
+                const args = rawArgs;
+                // ctx.control so layered runtimes (Pro) can swap in an org-scoped executor.
+                const control = ctx.control;
+                if (!(await tableExists(control, "_agent_instances"))) {
+                    return toolResult("Agent conversation catalog is not installed for this app.", {
+                        unavailable: true,
+                        provider: "Agent conversations",
+                        requiredScope: "operator:agent:read",
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Enable a Raybase Agent such as Guide so _agent_instances is registered."
+                    });
+                }
+                const params = [args.conversationId];
+                const agentWhere = args.agentName ? ` AND "agentName" = ?` : "";
+                if (args.agentName)
+                    params.push(args.agentName);
+                const instance = await control.first(`SELECT * FROM ${q("_agent_instances")} WHERE "conversationId" = ?${agentWhere} LIMIT 1`, params);
+                if (!instance)
+                    return toolResult("Agent conversation not found.", { appliedFilters: args, rowCount: 0, returned: 0, truncated: false }, true);
+                const scopedOrganizationId = ctx.agentConversationScope?.organizationId;
+                if (scopedOrganizationId && instance.organizationId && instance.organizationId !== scopedOrganizationId) {
+                    throw new Error("Conversation does not belong to the requested organization");
+                }
+                const transcript = await readActiveAgentTranscript(ctx, instance, { limit: args.limit, offset: args.offset });
+                if (transcript.unavailable) {
+                    return toolResult("Agent transcript storage is unavailable.", {
+                        conversation: safeAgentConversation(instance),
+                        unavailable: true,
+                        error: transcript.error,
+                        appliedFilters: args,
+                        rowCount: 1,
+                        returned: 1,
+                        truncated: false,
+                        suggestedNextInspection: "Check RAYBASE_AI_CHAT_AGENT binding and Agent Durable Object health."
+                    }, true);
+                }
+                return toolResult(`Loaded Agent conversation ${instance.conversationId}.`, {
+                    conversation: safeAgentConversation(instance, transcript.rowCount ?? null),
+                    messages: transcript.messages ?? [],
+                    toolEvents: transcript.toolEvents ?? [],
+                    sources: transcript.sources ?? [],
+                    citations: transcript.citations ?? [],
+                    supportMarkers: transcript.supportMarkers ?? [],
+                    redaction: {
+                        redacted: transcript.redacted === true,
+                        truncated: transcript.truncated === true
+                    },
+                    archiveStatus: instance.status === "archived" ? "archived" : instance.status === "deleted" ? "deleted" : "hot",
+                    appliedFilters: args,
+                    rowCount: transcript.rowCount ?? 0,
+                    returned: transcript.returned ?? 0,
+                    truncated: transcript.truncated === true,
+                    suggestedNextInspection: "Use agent_runs_query with this conversationId for per-turn status, error, and timing evidence, or audit_query around the conversation updatedAt timestamp for adjacent runtime events."
+                });
+            }
+        },
+        {
+            name: "agent_runs_query",
+            description: "Query Raybase Agent run history with per-turn status, error, timing, and trigger evidence.",
+            inputSchema: agentRunsQueryInput,
+            annotations: { readOnlyHint: true },
+            scopes: [...agentReadScopes],
+            handler: async (rawArgs, ctx) => {
+                const args = rawArgs;
+                // ctx.control so layered runtimes (Pro) can swap in an org-scoped executor.
+                const control = ctx.control;
+                if (!(await tableExists(control, "_agent_runs"))) {
+                    return toolResult("Agent run history is not installed for this app.", {
+                        unavailable: true,
+                        provider: "Agent runs",
+                        requiredScope: "operator:agent:read",
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Enable a Raybase Agent such as Guide so _agent_runs is registered."
+                    });
+                }
+                const where = [];
+                const params = [];
+                const applied = { ...addTimeRange(where, params, `"startedAt"`, args), limit: args.limit, offset: args.offset };
+                for (const [key, column] of Object.entries({
+                    conversationId: "conversationId",
+                    agentName: "agentName",
+                    status: "status",
+                    triggerType: "triggerType",
+                    runId: "runId"
+                })) {
+                    const value = args[key];
+                    if (typeof value === "string" && value) {
+                        where.push(`${q(column)} = ?`);
+                        params.push(value);
+                        applied[key] = value;
+                    }
+                }
+                const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+                const count = await control.first(`SELECT COUNT(*) as "count" FROM ${q("_agent_runs")} ${whereSql}`, params);
+                const rows = await control.all(`SELECT * FROM ${q("_agent_runs")} ${whereSql} ORDER BY "startedAt" DESC LIMIT ? OFFSET ?`, [...params, args.limit, args.offset]);
+                return toolResult(`Returned ${rows.length} Agent run(s).`, {
+                    runs: rows.map(agentRunListRow),
+                    appliedFilters: applied,
+                    rowCount: Number(count?.count ?? rows.length),
+                    returned: rows.length,
+                    truncated: args.offset + rows.length < Number(count?.count ?? rows.length),
+                    suggestedNextInspection: "Use ai_usage_query with the conversationId and the run's startedAt/finishedAt window for per-step model evidence, or agent_conversation_read for transcript content."
+                });
+            }
+        },
+        operatorTool({
+            name: "ai_usage_query",
+            description: "Query content-free AI usage events (model, request kind, sizes with the agent prompt floor/tail split, timing, status, gateway log ids) without message text.",
+            scope: "operator:ai:read",
+            inputSchema: aiUsageQueryInput,
+            handler: async (args, ctx) => {
+                // ctx.control so layered runtimes (Pro) can swap in an org-scoped executor.
+                const control = ctx.control;
+                if (!(await tableExists(control, "_ai_usage_events"))) {
+                    return toolResult("AI usage evidence is not installed for this app.", {
+                        unavailable: true,
+                        provider: "AI usage",
+                        requiredScope: "operator:ai:read",
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Enable Raybase AI (config.ai.enabled) or deploy a version that includes _ai_usage_events."
+                    });
+                }
+                const where = [];
+                const params = [];
+                const applied = { ...addTimeRange(where, params, `"createdAt"`, args), limit: args.limit, offset: args.offset };
+                for (const [key, column] of Object.entries({
+                    conversationId: "conversationId",
+                    agent: "agent",
+                    model: "model",
+                    requestKind: "requestKind",
+                    status: "status",
+                    principalKind: "principalKind",
+                    serviceName: "serviceName",
+                    userId: "userId"
+                })) {
+                    const value = args[key];
+                    if (typeof value === "string" && value) {
+                        where.push(`${q(column)} = ?`);
+                        params.push(value);
+                        applied[key] = value;
+                    }
+                }
+                for (const [key, path] of Object.entries({ jobName: "$.jobName", jobRunId: "$.jobRunId" })) {
+                    const value = args[key];
+                    if (typeof value === "string" && value) {
+                        where.push(`json_extract(${q("metadata")}, ?) = ?`);
+                        params.push(path, value);
+                        applied[key] = value;
+                    }
+                }
+                const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+                const count = await control.first(`SELECT COUNT(*) as "count" FROM ${q("_ai_usage_events")} ${whereSql}`, params);
+                const rows = await control.all(`SELECT * FROM ${q("_ai_usage_events")} ${whereSql} ORDER BY "createdAt" DESC LIMIT ? OFFSET ?`, [...params, args.limit, args.offset]);
+                return toolResult(`Returned ${rows.length} AI usage event(s).`, {
+                    events: rows.map(aiUsageListRow),
+                    appliedFilters: applied,
+                    rowCount: Number(count?.count ?? rows.length),
+                    returned: rows.length,
+                    truncated: args.offset + rows.length < Number(count?.count ?? rows.length),
+                    suggestedNextInspection: "Use a returned gatewayLogId with your AI gateway or provider generation API for effective request parameters and finish reason, or agent_runs_query for run-level status."
+                });
+            }
+        }),
+        operatorTool({
+            name: "runtime_errors_summary",
+            description: "Group short-retention server and opt-in client runtime error events by fingerprint, source, route, and release.",
+            scope: "operator:health:read",
+            inputSchema: runtimeErrorsSummaryInput,
+            handler: async (args, ctx) => {
+                // ctx.control so layered runtimes (Pro) can swap in an org-scoped executor.
+                const control = ctx.control;
+                if (!(await tableExists(control, raybaseRuntimeErrorEventsTableName))) {
+                    return toolResult("Runtime error evidence is not installed for this app.", {
+                        unavailable: true,
+                        provider: "Runtime errors",
+                        requiredScope: "operator:health:read",
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        retentionDays: runtimeErrorRetentionDays(options.config),
+                        suggestedNextInspection: "Enable Core runtime error evidence or deploy a version that includes _runtime_error_events."
+                    });
+                }
+                const result = await runtimeErrorSummaryQuery(control, args, options.config);
+                return toolResult(`Returned ${result.groups.length} runtime error group(s).`, {
+                    groups: result.groups,
+                    appliedFilters: result.appliedFilters,
+                    rowCount: result.rowCount,
+                    returned: result.returned,
+                    truncated: result.truncated,
+                    retentionDays: result.retentionDays,
+                    suggestedNextInspection: "Use runtime_error_detail with a fingerprint, then inspect audit_query, job_run_detail, support_request_detail, or agent_conversation_read for adjacent evidence."
+                });
+            }
+        }),
+        operatorTool({
+            name: "runtime_error_detail",
+            description: "Read bounded redacted event samples for one runtime error fingerprint.",
+            scope: "operator:health:read",
+            inputSchema: runtimeErrorDetailInput,
+            handler: async (args, ctx) => {
+                // ctx.control so layered runtimes (Pro) can swap in an org-scoped executor.
+                const control = ctx.control;
+                if (!(await tableExists(control, raybaseRuntimeErrorEventsTableName))) {
+                    return toolResult("Runtime error evidence is not installed for this app.", {
+                        unavailable: true,
+                        provider: "Runtime errors",
+                        requiredScope: "operator:health:read",
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Enable Core runtime error evidence or deploy a version that includes _runtime_error_events."
+                    }, true);
+                }
+                const result = await runtimeErrorDetailQuery(control, args);
+                return toolResult(`Returned ${result.rows.length} runtime error event sample(s).`, {
+                    events: result.rows,
+                    redaction: {
+                        redacted: true,
+                        truncated: result.truncated,
+                        notes: ["Messages, stack samples, routes, user agents, and metadata are sanitized at insert time."]
+                    },
+                    appliedFilters: result.appliedFilters,
+                    rowCount: result.rowCount,
+                    returned: result.returned,
+                    truncated: result.truncated,
+                    suggestedNextInspection: "Inspect audit_query around event timestamps; use job_run_detail for job routes, support_request_detail for user escalation context, or agent_conversation_read when conversationId metadata is present."
+                });
+            }
+        }),
+        operatorTool({
+            name: "support_requests_query",
+            description: "Query persisted support request rows with bounded excerpts and conversation/run pointers.",
+            scope: "operator:support:read",
+            inputSchema: supportRequestsQueryInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                if (!(await tableExists(db.control, raybaseSupportRequestsTableName))) {
+                    return toolResult("Support request evidence is not installed for this Raybase app.", {
+                        unavailable: true,
+                        provider: "Support requests",
+                        requiredScope: "operator:support:read",
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Enable the Core support module or deploy a version that includes _support_requests."
+                    });
+                }
+                const where = [];
+                const params = [];
+                const applied = { ...addTimeRange(where, params, `"createdAt"`, args), limit: args.limit, offset: args.offset };
+                for (const [key, column] of Object.entries({
+                    status: "status",
+                    sourceKind: "sourceKind",
+                    agentName: "agentName",
+                    conversationId: "conversationId",
+                    runId: "runId",
+                    userId: "userId",
+                    organizationId: "organizationId",
+                    surface: "surface",
+                    route: "route"
+                })) {
+                    const value = args[key];
+                    if (typeof value === "string" && value) {
+                        where.push(`${q(column)} = ?`);
+                        params.push(value);
+                        applied[key] = value;
+                    }
+                }
+                if (args.search) {
+                    where.push(`("subject" LIKE ? OR "body" LIKE ? OR "transcriptSummary" LIKE ? OR "category" LIKE ?)`);
+                    params.push(`%${args.search}%`, `%${args.search}%`, `%${args.search}%`, `%${args.search}%`);
+                    applied.search = args.search;
+                }
+                const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+                const count = await db.control.first(`SELECT COUNT(*) as "count" FROM ${q(raybaseSupportRequestsTableName)} ${whereSql}`, params);
+                const rows = await db.control.all(`SELECT "id", "status", "sourceKind", "sourceId", "conversationId", "agentName", "agentInstanceId", "runId", "requestId", "toolCallId",
+                  "userId", "organizationId", "principalKind", "publicIdentity", "surface", "route", "subject", "body", "category", "confidence",
+                  "contactEmail", "createdAt", "updatedAt"
+           FROM ${q(raybaseSupportRequestsTableName)}
+           ${whereSql}
+           ORDER BY "updatedAt" DESC, "createdAt" DESC
+           LIMIT ? OFFSET ?`, [...params, args.limit, args.offset]);
+                return toolResult(`Returned ${rows.length} support request(s).`, {
+                    requests: rows.map(supportRequestListRow),
+                    appliedFilters: applied,
+                    rowCount: Number(count?.count ?? rows.length),
+                    returned: rows.length,
+                    truncated: args.offset + rows.length < Number(count?.count ?? rows.length),
+                    suggestedNextInspection: "Use support_request_detail with an id, then agent_conversation_read or audit_query for adjacent evidence."
+                });
+            }
+        }),
+        operatorTool({
+            name: "support_request_detail",
+            description: "Read one persisted support request with bounded redacted body, transcript evidence, sources, and adjacent evidence pointers.",
+            scope: "operator:support:read",
+            inputSchema: supportRequestDetailInput,
+            handler: async (args, ctx) => {
+                const db = operatorDb(ctx, options);
+                if (!(await tableExists(db.control, raybaseSupportRequestsTableName))) {
+                    return toolResult("Support request evidence is not installed for this Raybase app.", {
+                        unavailable: true,
+                        provider: "Support requests",
+                        requiredScope: "operator:support:read",
+                        appliedFilters: args,
+                        rowCount: 0,
+                        returned: 0,
+                        truncated: false,
+                        suggestedNextInspection: "Enable the Core support module or deploy a version that includes _support_requests."
+                    }, true);
+                }
+                const row = await db.control.first(`SELECT * FROM ${q(raybaseSupportRequestsTableName)} WHERE "id" = ?`, [args.id]);
+                if (!row)
+                    return toolResult("Support request not found.", { appliedFilters: args, rowCount: 0, returned: 0, truncated: false }, true);
+                const auditRows = await db.control.all(`SELECT "id", "action", "targetType", "targetId", "metadata", "createdAt"
+           FROM "_audit"
+           WHERE ("targetType" = ? AND "targetId" = ?) OR "metadata" LIKE ?
+           ORDER BY "createdAt" DESC LIMIT 20`, [raybaseSupportRequestsTableName, args.id, `%${args.id}%`]).catch(() => []);
+                return toolResult(`Loaded support request ${args.id}.`, {
+                    supportRequest: supportRequestDetailRow(row, auditRows.map((auditRow) => ({ ...redactRow(auditRow).row, metadata: parseJson(auditRow.metadata) }))),
+                    appliedFilters: args,
+                    rowCount: 1,
+                    returned: 1,
+                    truncated: false,
+                    suggestedNextInspection: "Use agent_conversation_read for conversationId/run context or audit_query action support.request.create."
+                });
+            }
+        }),
+        operatorTool({
+            name: "improvement_inbox_query",
+            description: "Query Improvement Inbox findings when the provider is installed; otherwise explain unavailability.",
+            scope: "operator:findings:read",
+            inputSchema: findingQueryInput,
+            handler: async () => unavailableResult("Improvement Inbox", "operator:findings:read")
+        }),
+        operatorTool({
+            name: "finding_detail",
+            description: "Read one Improvement Inbox finding when the provider is installed; otherwise explain unavailability.",
+            scope: "operator:findings:read",
+            inputSchema: findingDetailInput,
+            handler: async () => unavailableResult("Improvement Inbox", "operator:findings:read")
+        })
+    ];
+    const providerTools = (options.providers ?? []).flatMap((provider) => provider.tools);
+    const providerToolNames = new Set(providerTools.map((tool) => tool.name));
+    const skillTools = createAgentSkillOperatorTools(options);
+    const remoteMcpTools = createAgentRemoteMcpOperatorTools(options);
+    return [...tools.filter((tool) => !providerToolNames.has(tool.name)), ...skillTools, ...remoteMcpTools, ...providerTools];
+}
+function embeddedJson(uri, result) {
+    return {
+        uri,
+        mimeType: "application/json",
+        text: JSON.stringify(result.structuredContent ?? {}, null, 2)
+    };
+}
+function findTool(tools, name) {
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool)
+        throw new Error(`Operator tool ${name} is not registered`);
+    return tool;
+}
+export function createCoreOperatorMcpResources(options, tools) {
+    const resources = [
+        {
+            uri: "raybase://operator/summary",
+            name: "Operator summary",
+            description: "Compact Raybase Operator MCP health summary.",
+            mimeType: "application/json",
+            scopes: ["operator:health:read"],
+            read: async (ctx) => embeddedJson("raybase://operator/summary", await findTool(tools, "app_health_summary").handler({}, ctx))
+        },
+        {
+            uri: "raybase://schema/summary",
+            name: "Schema summary",
+            description: "Raybase app and system schema summary.",
+            mimeType: "application/json",
+            scopes: ["operator:schema:read"],
+            read: async (ctx) => embeddedJson("raybase://schema/summary", await findTool(tools, "schema_summary").handler({ includeSystem: true }, ctx))
+        },
+        {
+            uri: "raybase://audit/recent",
+            name: "Recent audit",
+            description: "Recent Raybase audit rows.",
+            mimeType: "application/json",
+            scopes: ["operator:audit:read"],
+            read: async (ctx) => embeddedJson("raybase://audit/recent", await findTool(tools, "audit_query").handler({ limit: 50, offset: 0 }, ctx))
+        },
+        {
+            uri: "raybase://imports/recent",
+            name: "Recent imports",
+            description: "Recent admin CSV import runs and failed row examples.",
+            mimeType: "application/json",
+            scopes: ["operator:imports:read"],
+            read: async (ctx) => embeddedJson("raybase://imports/recent", await findTool(tools, "import_runs_query").handler({ limit: 50, offset: 0 }, ctx))
+        },
+        {
+            uri: "raybase://jobs/failures",
+            name: "Job failures",
+            description: "Recent failed, denied, or expired job runs.",
+            mimeType: "application/json",
+            scopes: ["operator:jobs:read"],
+            read: async (ctx) => embeddedJson("raybase://jobs/failures", await findTool(tools, "job_runs_query").handler({ limit: 50, offset: 0, status: "failed" }, ctx))
+        },
+        {
+            uri: "raybase://retrieval/summary",
+            name: "Retrieval summary",
+            description: "Raybase semantic retrieval index status and last reindex evidence.",
+            mimeType: "application/json",
+            scopes: ["operator:retrieval:read"],
+            read: async (ctx) => embeddedJson("raybase://retrieval/summary", await findTool(tools, "retrieval_indexes_summary").handler({}, ctx))
+        },
+        {
+            uri: "raybase://search/summary",
+            name: "Search summary",
+            description: "Raybase SQL full-text search index status and last reindex evidence.",
+            mimeType: "application/json",
+            scopes: ["operator:search:read"],
+            read: async (ctx) => embeddedJson("raybase://search/summary", await findTool(tools, "search_indexes_summary").handler({}, ctx))
+        },
+        {
+            uri: "raybase://mcp/grants",
+            name: "MCP grants",
+            description: "Recent app and operator MCP grants.",
+            mimeType: "application/json",
+            scopes: ["operator:mcp-grants:read"],
+            read: async (ctx) => embeddedJson("raybase://mcp/grants", await findTool(tools, "mcp_grants_summary").handler({ limit: 50, offset: 0 }, ctx))
+        },
+        {
+            uri: "raybase://agents/conversations/recent",
+            name: "Recent Agent conversations",
+            description: "Recent Raybase Agent conversation catalog rows with lifecycle metadata.",
+            mimeType: "application/json",
+            scopes: [...agentReadScopes],
+            read: async (ctx) => embeddedJson("raybase://agents/conversations/recent", await findTool(tools, "agent_conversations_query").handler({ limit: 50, offset: 0 }, ctx))
+        },
+        {
+            uri: "raybase://runtime-errors/recent",
+            name: "Recent runtime errors",
+            description: "Short-retention server and opt-in client runtime error groups.",
+            mimeType: "application/json",
+            scopes: ["operator:health:read"],
+            read: async (ctx) => embeddedJson("raybase://runtime-errors/recent", await findTool(tools, "runtime_errors_summary").handler({ limit: 50, offset: 0 }, ctx))
+        },
+        {
+            uri: "raybase://support/requests/open",
+            name: "Open support requests",
+            description: "Persisted open support requests with bounded excerpts.",
+            mimeType: "application/json",
+            scopes: ["operator:support:read"],
+            read: async (ctx) => embeddedJson("raybase://support/requests/open", await findTool(tools, "support_requests_query").handler({ limit: 50, offset: 0, status: "open" }, ctx))
+        },
+        {
+            uri: "raybase://findings/open",
+            name: "Open findings",
+            description: "Open Improvement Inbox findings when the provider is installed.",
+            mimeType: "application/json",
+            scopes: ["operator:findings:read"],
+            read: async (ctx) => embeddedJson("raybase://findings/open", await findTool(tools, "improvement_inbox_query").handler({ limit: 50, offset: 0, status: "open" }, ctx))
+        }
+    ];
+    const providerResources = (options.providers ?? []).flatMap((provider) => provider.resources ?? []);
+    const providerResourceUris = new Set(providerResources.map((resource) => resource.uri));
+    return [...resources.filter((resource) => !providerResourceUris.has(resource.uri)), ...providerResources];
+}
+//# sourceMappingURL=operator-mcp.js.map