@agentic-kit/pi 0.9.2 → 0.10.1

package/esm/tools/manage-entity-types.js

@@ -0,0 +1,203 @@
+import { z } from 'zod';
+import { resolveProjectContext } from '../context';
+import { toolSchema } from '../tool-schema';
+const ManageEntityTypesZod = z.object({
+    action: z
+        .enum(['list', 'create', 'delete'])
+        .describe('list: show the entity types provisioned in this database. create: provision a new entity type (creates its entity table + membership wiring). delete: remove the provision registration. Registrations are immutable once provisioned — there is no update; to change one, delete it and create a new one.'),
+    name: z.string().describe('Entity type name. Required for create.').optional(),
+    entity_type_id: z
+        .string()
+        .describe('Entity type provision id. Required for delete — get it from action "list".')
+        .optional(),
+    description: z
+        .string()
+        .describe('Human-readable description of the entity type. Create only.')
+        .optional(),
+    prefix: z
+        .string()
+        .describe('Table-name prefix for the provisioned tables (e.g. "org" → org table, org_memberships). Create only; defaults to the snake_case of name.')
+        .optional(),
+    parent_entity: z
+        .string()
+        .describe('Parent entity table name, for hierarchical types (e.g. a "team" under an "org"). Create only; the backend defaults it to the root entity (org).')
+        .optional(),
+    is_visible: z
+        .boolean()
+        .describe('Whether the type shows up in end-user entity listings. Create only.')
+        .optional(),
+    has_invites: z
+        .boolean()
+        .describe('Provision an invites module ({prefix}_invites + claimed invites). Create only.')
+        .optional(),
+    has_profiles: z
+        .boolean()
+        .describe('Provision a profiles table for members of this type. Create only.')
+        .optional(),
+    has_limits: z
+        .boolean()
+        .describe('Provision usage-limits tracking for this type. Create only.')
+        .optional(),
+    has_levels: z
+        .boolean()
+        .describe('Provision levels/achievements support for this type. Create only.')
+        .optional(),
+    has_storage: z
+        .boolean()
+        .describe('Provision a storage module (files + buckets tables) for this type. Create only.')
+        .optional(),
+});
+const ManageEntityTypesSchema = toolSchema(ManageEntityTypesZod);
+const SUMMARY_SELECT = {
+    id: true,
+    name: true,
+    description: true,
+    prefix: true,
+    parentEntity: true,
+    isVisible: true,
+    outEntityTableName: true,
+    outInstalledModules: true,
+};
+function toSummary(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        description: row.description,
+        prefix: row.prefix,
+        parentEntity: row.parentEntity,
+        isVisible: row.isVisible,
+        entityTableName: row.outEntityTableName,
+        installedModules: row.outInstalledModules,
+    };
+}
+function formatSummary(s) {
+    const parts = [
+        `- ${s.name ?? '?'} (id: ${s.id})`,
+        `  table: ${s.entityTableName ?? '?'}, prefix: ${s.prefix ?? '?'}`,
+    ];
+    if (s.parentEntity)
+        parts.push(`  parent: ${s.parentEntity}`);
+    if (s.description)
+        parts.push(`  description: ${s.description}`);
+    if (s.installedModules?.length)
+        parts.push(`  modules: ${s.installedModules.join(', ')}`);
+    return parts.join('\n');
+}
+export function defaultPrefix(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+export function validateManageEntityTypes(params) {
+    switch (params.action) {
+        case 'create':
+            if (!params.name?.trim())
+                return 'create requires "name".';
+            if (params.entity_type_id)
+                return 'create does not take "entity_type_id" — it mints a new one.';
+            return null;
+        case 'delete':
+            if (!params.entity_type_id)
+                return 'delete requires "entity_type_id" (use action "list" to find it).';
+            return null;
+        default:
+            return null;
+    }
+}
+export const manageEntityTypesTool = {
+    name: 'manage_entity_types',
+    label: 'Manage entity types',
+    description: 'List, create, or delete entity types in the project database. An entity type (e.g. organization, team, project) provisions its own entity table plus membership wiring, and is the unit that API keys can be scoped to. Registrations are immutable once provisioned — to change one, delete it and create a new one. Deleting removes the registration; the already-provisioned entity table stays in the API schema.',
+    promptSnippet: 'manage_entity_types: list/create/delete entity types (orgs, teams, …) in the project database. list is free; create/delete are gated.',
+    parameters: ManageEntityTypesSchema,
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context) {
+            return {
+                content: [{ type: 'text', text: resolved.reason }],
+                details: { success: false, message: resolved.reason },
+            };
+        }
+        const invalid = validateManageEntityTypes(params);
+        if (invalid) {
+            return {
+                content: [{ type: 'text', text: invalid }],
+                details: { success: false, message: invalid },
+            };
+        }
+        const { modules, databaseId } = resolved.context;
+        try {
+            switch (params.action) {
+                case 'list': {
+                    const result = await modules.entityTypeProvision
+                        .findMany({
+                        where: { databaseId: { equalTo: databaseId } },
+                        select: SUMMARY_SELECT,
+                    })
+                        .unwrap();
+                    const entityTypes = result.entityTypeProvisions.nodes.map((row) => toSummary(row));
+                    const message = entityTypes.length === 0
+                        ? 'No entity types are provisioned in this database yet.'
+                        : `${entityTypes.length} entity type${entityTypes.length === 1 ? '' : 's'}:\n${entityTypes.map(formatSummary).join('\n')}`;
+                    return {
+                        content: [{ type: 'text', text: message }],
+                        details: { success: true, message, entityTypes },
+                    };
+                }
+                case 'create': {
+                    const name = params.name.trim();
+                    const result = await modules.entityTypeProvision
+                        .create({
+                        data: {
+                            databaseId,
+                            name,
+                            prefix: params.prefix?.trim() || defaultPrefix(name),
+                            ...(params.description !== undefined && { description: params.description }),
+                            ...(params.parent_entity !== undefined && { parentEntity: params.parent_entity }),
+                            ...(params.is_visible !== undefined && { isVisible: params.is_visible }),
+                            ...(params.has_invites !== undefined && { hasInvites: params.has_invites }),
+                            ...(params.has_profiles !== undefined && { hasProfiles: params.has_profiles }),
+                            ...(params.has_limits !== undefined && { hasLimits: params.has_limits }),
+                            ...(params.has_levels !== undefined && { hasLevels: params.has_levels }),
+                            ...(params.has_storage && {
+                                storage: [{}],
+                            }),
+                        },
+                        select: SUMMARY_SELECT,
+                    })
+                        .unwrap();
+                    const row = result.createEntityTypeProvision?.entityTypeProvision;
+                    if (!row)
+                        throw new Error('createEntityTypeProvision returned no row.');
+                    const summary = toSummary(row);
+                    const message = `Created entity type "${summary.name}" (id: ${summary.id}) — entity table "${summary.entityTableName}"${summary.installedModules?.length ? `, modules: ${summary.installedModules.join(', ')}` : ''}. Run run_codegen to pull it into the typed SDK.`;
+                    return {
+                        content: [{ type: 'text', text: message }],
+                        details: { success: true, message, entityTypes: [summary] },
+                    };
+                }
+                case 'delete': {
+                    const result = await modules.entityTypeProvision
+                        .delete({
+                        where: { id: params.entity_type_id },
+                        select: { id: true, name: true, outEntityTableName: true },
+                    })
+                        .unwrap();
+                    const row = result.deleteEntityTypeProvision?.entityTypeProvision;
+                    const name = row?.name ?? params.entity_type_id;
+                    const message = `Deleted entity type registration "${name}". Note: the provisioned entity table${row?.outEntityTableName ? ` "${row.outEntityTableName}"` : ''} remains in the API schema with its data.`;
+                    return {
+                        content: [{ type: 'text', text: message }],
+                        details: { success: true, message },
+                    };
+                }
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to manage entity types';
+            return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+        }
+    },
+};

package/esm/tools/provision-database.js

@@ -109,7 +109,7 @@ export const provisionDatabaseTool = {
         // with no usable bearer errors out here rather than silently minting a
         // throwaway owner. Gate BEFORE prewarm so an error return doesn't leak a
         // detached background scaffold/install.
-        const credential = selectProvisionCredential(host.account());
+        const credential = selectProvisionCredential(host.account(), host.signInHint);
         if (credential.mode === 'error') {
             return fail(`Cannot provision a database: ${credential.reason}`);
         }
@@ -129,6 +129,7 @@ export const provisionDatabaseTool = {
                 endpoint: apiEndpoint,
                 bearer: credential.bearer,
                 databaseId: existingEnv.DATABASE_ID,
+                signInHint: host.signInHint,
             });
             if (probe.outcome === 'unreachable') {
                 return fail(`Cannot verify the existing database binding: backend unreachable (${probe.detail}). Check the Constructive backend is running, then retry — do not reprovision on an unreachable backend.`);

package/host.d.ts

@@ -48,6 +48,29 @@ export interface HostProvisionOverlay {
     add?: (string | [string, Record<string, unknown>])[];
     remove?: string[];
 }
+/**
+ * A minted secret handed to the host for out-of-band delivery (.env write +
+ * one-time reveal). The plaintext never enters tool results or the transcript;
+ * pi forgets it after this call.
+ */
+export type SecretDelivery = {
+    databaseId: string;
+    /** Project directory whose `.env` receives the key. */
+    cwd: string;
+    envVar: string;
+    plaintext: string;
+    keyId: string;
+    expiresAt?: string;
+};
+/**
+ * Context for a host-side step-up: enough to derive the per-database auth
+ * endpoint and look up the app session without re-resolving the project.
+ */
+export type StepUpRequest = {
+    databaseId: string;
+    databaseName: string;
+    apiEndpoint: string;
+};
 export interface PiToolsHost {
     /** Signed-in platform account, or null/undefined when signed out. */
     account(): HostAccount | null | undefined;
@@ -55,6 +78,12 @@ export interface PiToolsHost {
     backendConfig(): HostBackendConfig | null | undefined;
     /** Optional data-plane token broker (see DataAuthBroker). */
     dataAuthBroker?: DataAuthBroker;
+    /**
+     * Host-specific sign-in instruction, substituted into signed-out failure
+     * reasons (e.g. the CLI's "Run `agent login` to sign in."). Absent hosts get
+     * the desktop wording.
+     */
+    signInHint?: string;
     /** Harvest an end-user token from the host's app preview, if it has one. */
     previewToken?(): Promise<PreviewToken | null>;
     /** Treat tokens expiring within this window as already expired. Default 30s. */
@@ -66,6 +95,17 @@ export interface PiToolsHost {
      * (e.g. materialized from appstash / a pinned git ref), never as code.
      */
     provisionOverlay?(): HostProvisionOverlay | null | undefined | Promise<HostProvisionOverlay | null | undefined>;
+    /**
+     * Complete MFA step-up for the database's app session in the host's own
+     * process (password dialog + verifyPassword). The password never passes
+     * through pi or the model. Resolve true when step-up succeeded.
+     */
+    requestStepUp?(request: StepUpRequest): Promise<boolean>;
+    /**
+     * Deliver a minted secret to the user (.env write + one-time reveal).
+     * Required for create_api_key — without it the tool refuses to mint.
+     */
+    deliverSecret?(delivery: SecretDelivery): Promise<void>;
 }
 export declare const DEFAULT_DATA_TOKEN_SKEW_MS = 30000;
 export declare function configureHost(host: PiToolsHost): void;

package/index.d.ts

@@ -4,7 +4,7 @@ export declare const dbTools: ExtensionFactory;
 /** Configure the host and get the extension in one call. */
 export declare function createDbTools(host: PiToolsHost): ExtensionFactory;
 export { type ConfirmGate, type ConfirmGateDeps, createConfirmGate } from './confirm-gate';
-export { type ModulesClient, type ProjectContext, resolveDataToken, resolveProjectContext, } from './context';
+export { deriveSubdomainEndpoint, type ModulesClient, type ProjectContext, resolveDataToken, resolveProjectContext, } from './context';
 export { type ActiveDataToken, configureHost, type DataAuthBroker, getHost, type HostAccount, type HostBackendConfig, type HostProvisionOverlay, type PiToolsHost, type PreviewToken, } from './host';
 export { loadProvisionManifest, parseProvisionManifest, PROVISION_MANIFEST_FILE, type ProvisionManifest, } from './provision-database/manifest';
 export { allModulePresets, DEFAULT_PROVISION_PRESET, getModulePreset, type ModulePreset, type ProvisionModule, } from './provision-database/presets';

package/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTemplatePreviewTables = exports.toolSchema = exports.resolveProvisionModules = exports.moduleKey = exports.getModulePreset = exports.DEFAULT_PROVISION_PRESET = exports.allModulePresets = exports.PROVISION_MANIFEST_FILE = exports.parseProvisionManifest = exports.loadProvisionManifest = exports.getHost = exports.configureHost = exports.resolveProjectContext = exports.resolveDataToken = exports.createConfirmGate = exports.dbTools = void 0;
+exports.createTemplatePreviewTables = exports.toolSchema = exports.resolveProvisionModules = exports.moduleKey = exports.getModulePreset = exports.DEFAULT_PROVISION_PRESET = exports.allModulePresets = exports.PROVISION_MANIFEST_FILE = exports.parseProvisionManifest = exports.loadProvisionManifest = exports.getHost = exports.configureHost = exports.resolveProjectContext = exports.resolveDataToken = exports.deriveSubdomainEndpoint = exports.createConfirmGate = exports.dbTools = void 0;
 exports.createDbTools = createDbTools;
 const confirm_gate_1 = require("./confirm-gate");
 const context_1 = require("./context");
@@ -8,7 +8,9 @@ const host_1 = require("./host");
 const add_policies_1 = require("./tools/add-policies");
 const add_records_1 = require("./tools/add-records");
 const add_relation_1 = require("./tools/add-relation");
+const create_api_key_1 = require("./tools/create-api-key");
 const describe_schema_1 = require("./tools/describe-schema");
+const manage_entity_types_1 = require("./tools/manage-entity-types");
 const mutations_1 = require("./tools/mutations");
 const provision_blueprint_1 = require("./tools/provision-blueprint");
 const provision_database_1 = require("./tools/provision-database");
@@ -30,6 +32,8 @@ const dbTools = (pi) => {
     pi.registerTool(templates_1.updateTemplateTool);
     pi.registerTool(templates_1.deleteTemplateTool);
     pi.registerTool(add_records_1.addRecordsTool);
+    pi.registerTool(manage_entity_types_1.manageEntityTypesTool);
+    pi.registerTool(create_api_key_1.createApiKeyTool);
     pi.registerTool(run_codegen_1.runCodegenTool);
     const gate = (0, confirm_gate_1.createConfirmGate)({
         resolveProjectContext: context_1.resolveProjectContext,
@@ -48,6 +52,7 @@ function createDbTools(host) {
 var confirm_gate_2 = require("./confirm-gate");
 Object.defineProperty(exports, "createConfirmGate", { enumerable: true, get: function () { return confirm_gate_2.createConfirmGate; } });
 var context_2 = require("./context");
+Object.defineProperty(exports, "deriveSubdomainEndpoint", { enumerable: true, get: function () { return context_2.deriveSubdomainEndpoint; } });
 Object.defineProperty(exports, "resolveDataToken", { enumerable: true, get: function () { return context_2.resolveDataToken; } });
 Object.defineProperty(exports, "resolveProjectContext", { enumerable: true, get: function () { return context_2.resolveProjectContext; } });
 var host_2 = require("./host");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-kit/pi",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "description": "Pi adapter for agentic-kit — the Constructive typed db tools (provision, blueprint, codegen, records, policies, templates) and confirm gate as a pi coding-agent extension",
   "main": "index.js",
@@ -29,9 +29,9 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@agentic-kit/harness": "^0.9.0",
-    "@constructive-io/graphql-query": "^4.12.2",
-    "@constructive-io/sdk": "^1.11.2",
+    "@agentic-kit/harness": "^0.10.1",
+    "@constructive-io/graphql-query": "^4.12.4",
+    "@constructive-io/sdk": "^1.11.4",
     "node-type-registry": "^1.14.1",
     "zod": "^4.4.3"
   },
@@ -48,5 +48,5 @@
     "coding-agent",
     "constructive"
   ],
-  "gitHead": "c9dcb0c96174dfb0bc6fd63e46cc7776ea7af173"
+  "gitHead": "0d9f0718a8c768cc8b7659525953dc762833bd6b"
 }

package/provision-database/credential.d.ts

@@ -11,4 +11,4 @@ export type ProvisionCredential = {
     mode: 'error';
     reason: string;
 };
-export declare function selectProvisionCredential(account: AccountCredential | null | undefined): ProvisionCredential;
+export declare function selectProvisionCredential(account: AccountCredential | null | undefined, signInHint?: string): ProvisionCredential;

package/provision-database/credential.js

@@ -10,13 +10,13 @@
 // Side-effect-free so the branch is unit-testable without runtime/network.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.selectProvisionCredential = selectProvisionCredential;
-function selectProvisionCredential(account) {
+function selectProvisionCredential(account, signInHint) {
     const bearer = account?.apiKey ?? account?.accessToken;
     if (account?.userId && bearer) {
         return { mode: 'account', ownerId: account.userId, bearer };
     }
     return {
         mode: 'error',
-        reason: 'No usable account credential. Sign in (or unlock your session) before provisioning a database.',
+        reason: `No usable account credential. ${signInHint ?? 'Sign in (or unlock your session) before provisioning a database.'}`,
     };
 }

package/tools/create-api-key.d.ts

@@ -0,0 +1,18 @@
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+declare const CreateApiKeySchema: import("typebox/type").TSchema;
+export type CreateApiKeyDetails = {
+    success: boolean;
+    message: string;
+    keyId?: string;
+    envVar?: string;
+    expiresAt?: string;
+    principalId?: string;
+    principalName?: string;
+    scope?: string;
+    needsAuth?: boolean;
+};
+export declare function toEnvVar(keyName: string): string;
+export declare function isStepUpError(messages: string[]): boolean;
+export declare function describeScope(entityIds: string[] | undefined, readOnly: boolean): string;
+export declare const createApiKeyTool: ToolDefinition<typeof CreateApiKeySchema, CreateApiKeyDetails>;
+export {};

package/tools/create-api-key.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiKeyTool = void 0;
+exports.toEnvVar = toEnvVar;
+exports.isStepUpError = isStepUpError;
+exports.describeScope = describeScope;
+const sdk_1 = require("@constructive-io/sdk");
+const zod_1 = require("zod");
+const context_1 = require("../context");
+const host_1 = require("../host");
+const tool_schema_1 = require("../tool-schema");
+const CreateApiKeyZod = zod_1.z.object({
+    key_name: zod_1.z
+        .string()
+        .describe('Name for the API key (e.g. "deploy bot"). The .env variable name derives from it (UPPER_SNAKE + _API_KEY).'),
+    principal_name: zod_1.z
+        .string()
+        .describe('Machine identity (principal) that owns the key. Defaults to key_name. An existing principal with this name is reused for unscoped keys.')
+        .optional(),
+    entity_ids: zod_1.z
+        .array(zod_1.z.string())
+        .describe('Entity row UUIDs to scope the principal to. Omit for a personal (unscoped) key that acts as the signed-in app user.')
+        .optional(),
+    read_only: zod_1.z
+        .boolean()
+        .describe('Restrict the principal and key to read-only operations.')
+        .optional(),
+    expires_in_days: zod_1.z
+        .number()
+        .int()
+        .positive()
+        .describe('Key lifetime in days. Default 90.')
+        .optional(),
+});
+const CreateApiKeySchema = (0, tool_schema_1.toolSchema)(CreateApiKeyZod);
+function fail(message, extra) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: false, message, ...extra },
+    };
+}
+function toEnvVar(keyName) {
+    const base = keyName
+        .trim()
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+    return base.endsWith('_API_KEY') ? base : `${base}_API_KEY`;
+}
+function isStepUpError(messages) {
+    return messages.some((m) => /step[\s_-]?up/i.test(m));
+}
+function describeScope(entityIds, readOnly) {
+    const parts = [];
+    parts.push(entityIds?.length
+        ? `scoped to ${entityIds.length} entit${entityIds.length === 1 ? 'y' : 'ies'}`
+        : 'unscoped (acts as the signed-in app user)');
+    if (readOnly)
+        parts.push('read-only');
+    return parts.join(', ');
+}
+async function rawGraphql(endpoint, token, query, variables) {
+    const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+        body: JSON.stringify({ query, variables }),
+    });
+    return (await res.json());
+}
+async function createPrincipalInputFields(endpoint) {
+    const probe = await rawGraphql(endpoint, undefined, '{ __type(name: "CreatePrincipalInput") { inputFields { name } } }');
+    const type = probe.data?.__type;
+    return new Set((type?.inputFields ?? []).map((f) => f.name));
+}
+exports.createApiKeyTool = {
+    name: 'create_api_key',
+    label: 'Create API key',
+    description: 'Mint an API key for the project database, owned by a machine principal. Optionally scope it to specific entity rows and/or read-only. The human confirms the mint, completes MFA step-up in the app when required, and receives the key via .env + a one-time reveal — the plaintext key never appears in this conversation. Requires the user to be signed in to their app in the Preview.',
+    promptSnippet: 'create_api_key: mint an entity-scoped API key for the project database. Gated; the plaintext goes to .env + a one-time reveal, never into the chat — reference it as its env var.',
+    parameters: CreateApiKeySchema,
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+        const keyName = params.key_name?.trim();
+        if (!keyName)
+            return fail('create_api_key requires "key_name".');
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd, { plane: 'data' });
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { databaseId, databaseName, apiEndpoint } = resolved.context;
+        if (!databaseName) {
+            return fail('Cannot resolve the app auth endpoint (DATABASE_NAME missing from .env). Re-provision the database, then retry.');
+        }
+        const host = (0, host_1.getHost)();
+        if (!host.deliverSecret) {
+            return fail('This host cannot deliver secrets (no .env write + reveal flow), so no key was minted. Create the key from a host that supports secret delivery.');
+        }
+        const token = await (0, context_1.resolveDataToken)(resolved.context);
+        if (!token.token) {
+            return fail(token.reason ?? 'Sign in to the app database to create an API key.', {
+                needsAuth: true,
+            });
+        }
+        const authEndpoint = (0, context_1.deriveSubdomainEndpoint)(apiEndpoint, `auth-${databaseName}`);
+        if (!authEndpoint)
+            return fail('Cannot derive the app auth endpoint.');
+        const scoped = Boolean(params.entity_ids?.length) || params.read_only === true;
+        try {
+            if (scoped) {
+                const fields = await createPrincipalInputFields(authEndpoint);
+                const missing = [
+                    ...(params.entity_ids?.length && !fields.has('entityIds') ? ['entityIds'] : []),
+                    ...(params.read_only === true && !fields.has('isReadOnly') ? ['isReadOnly'] : []),
+                ];
+                if (missing.length) {
+                    return fail(`This deployment does not support scoping a principal at create time (no ${missing.join(', ')} on createPrincipal). No key was minted. If an unscoped key that acts as the signed-in user is acceptable, ask for one explicitly.`);
+                }
+            }
+            const dbAuth = sdk_1.auth.createClient({
+                endpoint: authEndpoint,
+                headers: { Authorization: `Bearer ${token.token}` },
+            });
+            const principalName = params.principal_name?.trim() || keyName;
+            const existing = await dbAuth.principal
+                .findFirst({
+                where: { name: { equalTo: principalName } },
+                select: { id: true, name: true, userId: true, isReadOnly: true },
+            })
+                .unwrap();
+            // createApiKey (like createPrincipal.result) takes the principal's
+            // identity userId; principal_entity.principalId references the row id.
+            let principalId = existing.principal?.userId;
+            if (existing.principal && scoped) {
+                return fail(`Principal "${principalName}" already exists, and its scope cannot be verified against the requested one. No key was minted. Use a new principal_name for a scoped key, or mint an unscoped key on the existing principal explicitly.`);
+            }
+            if (existing.principal) {
+                const scopeRow = await dbAuth.principalEntity
+                    .findFirst({
+                    where: { principalId: { equalTo: existing.principal.id } },
+                    select: { id: true },
+                })
+                    .unwrap();
+                if (scopeRow.principalEntity || existing.principal?.isReadOnly) {
+                    return fail(`Principal "${principalName}" already exists with a narrower scope (entity-scoped or read-only), so a key minted under it would not act as the signed-in user. No key was minted. Use a new principal_name for an unscoped key.`);
+                }
+            }
+            if (!principalId) {
+                // The SDK's PrincipalModel.create sends a nested {principal} input, but
+                // the live CreatePrincipalInput is flat and its payload only exposes
+                // `result: UUID` — raw GraphQL is the only working surface.
+                const created = await rawGraphql(authEndpoint, token.token, 'mutation ($input: CreatePrincipalInput!) { createPrincipal(input: $input) { result } }', {
+                    input: {
+                        name: principalName,
+                        ...(params.entity_ids?.length && { entityIds: params.entity_ids }),
+                        ...(params.read_only !== undefined && { isReadOnly: params.read_only }),
+                    },
+                });
+                if (created.errors?.length) {
+                    return fail(`createPrincipal failed: ${created.errors.map((e) => e.message).join('; ')}`);
+                }
+                const payload = created.data?.createPrincipal;
+                principalId = payload?.result;
+                if (!principalId)
+                    return fail('createPrincipal returned no principal id.');
+            }
+            const mint = () => dbAuth.mutation
+                .createApiKey({
+                input: {
+                    principalId: principalId,
+                    keyName,
+                    ...(params.read_only && { accessLevel: 'read_only' }),
+                    expiresIn: { days: params.expires_in_days ?? 90 },
+                },
+            }, { select: { result: { select: { apiKey: true, keyId: true, expiresAt: true } } } })
+                .execute();
+            let minted = await mint();
+            if (!minted.ok && isStepUpError(minted.errors.map((e) => e.message))) {
+                if (!host.requestStepUp) {
+                    return fail('Creating this key requires MFA step-up, and this host has no step-up flow. Complete step-up in the app (verify your password), then retry.');
+                }
+                const verified = await host.requestStepUp({ databaseId, databaseName, apiEndpoint });
+                if (!verified)
+                    return fail('Step-up verification was not completed. No key was minted.');
+                minted = await mint();
+            }
+            if (!minted.ok) {
+                return fail(`createApiKey failed: ${minted.errors.map((e) => e.message).join('; ')}`);
+            }
+            const record = minted.data?.createApiKey?.result;
+            if (!record?.apiKey || !record.keyId)
+                return fail('createApiKey returned no key.');
+            const envVar = toEnvVar(keyName);
+            await host.deliverSecret({
+                databaseId,
+                cwd: ctx.cwd,
+                envVar,
+                plaintext: record.apiKey,
+                keyId: record.keyId,
+                expiresAt: record.expiresAt ?? undefined,
+            });
+            const scope = describeScope(params.entity_ids, params.read_only === true);
+            const message = `Created API key "${keyName}" (keyId: ${record.keyId}) for principal "${principalName}" — ${scope}. The key was written to .env as ${envVar} and revealed once to the user; it is not in this conversation. Reference it as ${envVar}.${record.expiresAt ? ` Expires ${record.expiresAt}.` : ''}`;
+            return {
+                content: [{ type: 'text', text: message }],
+                details: {
+                    success: true,
+                    message,
+                    keyId: record.keyId,
+                    envVar,
+                    expiresAt: record.expiresAt ?? undefined,
+                    principalId,
+                    principalName,
+                    scope,
+                },
+            };
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to create the API key.');
+        }
+    },
+};

package/tools/manage-entity-types.d.ts

@@ -0,0 +1,41 @@
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { z } from 'zod';
+declare const ManageEntityTypesZod: z.ZodObject<{
+    action: z.ZodEnum<{
+        create: "create";
+        delete: "delete";
+        list: "list";
+    }>;
+    name: z.ZodOptional<z.ZodString>;
+    entity_type_id: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    prefix: z.ZodOptional<z.ZodString>;
+    parent_entity: z.ZodOptional<z.ZodString>;
+    is_visible: z.ZodOptional<z.ZodBoolean>;
+    has_invites: z.ZodOptional<z.ZodBoolean>;
+    has_profiles: z.ZodOptional<z.ZodBoolean>;
+    has_limits: z.ZodOptional<z.ZodBoolean>;
+    has_levels: z.ZodOptional<z.ZodBoolean>;
+    has_storage: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const ManageEntityTypesSchema: import("typebox/type").TSchema;
+export type EntityTypeSummary = {
+    id: string;
+    name: string | null;
+    description: string | null;
+    prefix: string | null;
+    parentEntity: string | null;
+    isVisible: boolean | null;
+    entityTableName: string | null;
+    installedModules: string[] | null;
+};
+export type ManageEntityTypesDetails = {
+    success: boolean;
+    message: string;
+    entityTypes?: EntityTypeSummary[];
+};
+export declare function defaultPrefix(name: string): string;
+type Params = z.infer<typeof ManageEntityTypesZod>;
+export declare function validateManageEntityTypes(params: Params): string | null;
+export declare const manageEntityTypesTool: ToolDefinition<typeof ManageEntityTypesSchema, ManageEntityTypesDetails>;
+export {};