@agentic-kit/db-tools 0.11.5 → 0.12.0

package/schema-model.js

@@ -0,0 +1,309 @@
+"use strict";
+// The live schema of a project's app tables, read from the metaschema in one
+// piece: every APP table with every field (whatever its category), keys,
+// checks, foreign keys and policies. The ids are the metaschema's own, so they
+// stay put across renames.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaReadError = void 0;
+exports.accessOf = accessOf;
+exports.readSchemaModel = readSchemaModel;
+const harness_1 = require("@agentic-kit/harness");
+const graphql_http_1 = require("./graphql-http");
+const normalize_1 = require("./schema-model/normalize");
+/** A read failed, so there is no model: a partial one would look like columns dropped outside. */
+class SchemaReadError extends Error {
+    step;
+    errors;
+    constructor(message, step, errors) {
+        super(message);
+        this.step = step;
+        this.errors = errors;
+        this.name = 'SchemaReadError';
+    }
+}
+exports.SchemaReadError = SchemaReadError;
+// ---- access ------------------------------------------------------------
+const CRUD = ['select', 'insert', 'update', 'delete'];
+const OWNER_FIELD = 'owner_id';
+// Keys the backend fills in when it stores an app-membership policy: where the
+// membership table lives, and that it's the app's (type 1, not an org's).
+const RESOLVED_KEYS = new Set(['sprt_table', 'sprt_schema']);
+const APP_MEMBERSHIP_TYPE = 1;
+// A parameter counts only when it narrows the policy: `is_admin: false` or
+// `levels: []` is the same as leaving it out.
+const isSet = (value) => Array.isArray(value)
+    ? value.length > 0
+    : typeof value === 'object' && value !== null
+        ? Object.keys(value).length > 0
+        : Boolean(value);
+/** Whether a policy parameter narrows who the policy lets in. */
+const narrows = (data, key) => {
+    if (key === 'owner_field' || RESOLVED_KEYS.has(key))
+        return false;
+    if (key === 'membership_type')
+        return Number(data[key]) !== APP_MEMBERSHIP_TYPE;
+    return isSet(data[key]);
+};
+function modeOf(policy) {
+    if (!policy.permissive || policy.role !== 'authenticated')
+        return null;
+    if (policy.withCheck && isSet(policy.withCheck))
+        return null;
+    const data = policy.data ?? {};
+    if (Object.keys(data).some((key) => narrows(data, key)))
+        return null;
+    if (policy.type === 'AuthzAppMembership')
+        return isSet(data.owner_field) ? null : 'shared';
+    if (policy.type === 'AuthzAppMemberOwner') {
+        const owner = data.owner_field;
+        return owner === undefined || owner === null || owner === OWNER_FIELD ? 'private' : null;
+    }
+    return null;
+}
+/**
+ * The access mode a table's policies amount to. `private` is the app-member
+ * owner policy on `owner_id` and `shared` the plain app-membership policy,
+ * each for the authenticated role over select, insert, update and delete.
+ * Anything else, no policies included, is `custom`. Disabled and internal
+ * policies don't count.
+ */
+function accessOf(policies) {
+    const live = policies.filter((policy) => !policy.disabled && !(0, harness_1.isInternalPolicy)(policy.type));
+    if (live.length === 0)
+        return 'custom';
+    const modes = new Set(live.map(modeOf));
+    if (modes.size !== 1 || modes.has(null))
+        return 'custom';
+    const covered = new Set(live.flatMap((policy) => {
+        const privilege = (policy.privilege ?? '').toLowerCase();
+        return privilege === 'all' ? CRUD : [privilege];
+    }));
+    return CRUD.every((privilege) => covered.has(privilege)) ? [...modes][0] : 'custom';
+}
+const nodesOf = (connection) => (connection?.nodes ?? []).filter((node) => Boolean(node));
+async function read(step, query) {
+    let result;
+    try {
+        result = await query.execute();
+    }
+    catch (err) {
+        throw new SchemaReadError(`Could not read ${step}: ${err instanceof Error ? err.message : String(err)}`, step);
+    }
+    if (!result.ok) {
+        throw new SchemaReadError(`Could not read ${step}: ${(0, graphql_http_1.errorsText)(result.errors ?? [])}`, step, result.errors);
+    }
+    return result.data;
+}
+const asRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+const groupBy = (rows) => {
+    const map = new Map();
+    for (const row of rows) {
+        const list = map.get(row.tableId) ?? [];
+        list.push(row);
+        map.set(row.tableId, list);
+    }
+    return map;
+};
+// The hash first: anything that changes the schema after this read moves it,
+// so a caller comparing hashes later never trusts a model older than it looks.
+async function readHash(context) {
+    try {
+        const data = await read('the database', context.api.database.findMany({
+            select: { id: true, hash: true },
+            where: { id: { equalTo: context.databaseId } },
+            first: 1,
+        }));
+        const node = nodesOf(data.databases)[0];
+        if (!node) {
+            throw new SchemaReadError(`Database ${context.databaseId} was not found on this backend.`, 'the database');
+        }
+        return node.hash ?? null;
+    }
+    catch (err) {
+        // A backend from before Database.hash.
+        if (err instanceof SchemaReadError && (err.errors ?? []).some((e) => /\bhash\b/.test(e?.message ?? ''))) {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * Read the APP tables of the context's database. All or nothing: any failed
+ * query throws `SchemaReadError`.
+ */
+async function readSchemaModel(context) {
+    const { api, databaseId } = context;
+    const hash = await readHash(context);
+    // Every table of the database, so a foreign key to a non-APP table (users)
+    // still names its target.
+    const tableData = await read('tables', api.table.findMany({
+        select: { id: true, name: true, category: true, label: true },
+        where: { databaseId: { equalTo: databaseId } },
+        orderBy: ['NAME_ASC'],
+    }));
+    const allTables = nodesOf(tableData.tables);
+    const tablesById = new Map(allTables.map((table) => [table.id, table]));
+    const appTables = allTables
+        .filter((table) => table.category === 'APP')
+        .sort((a, b) => a.name.localeCompare(b.name));
+    if (appTables.length === 0)
+        return { databaseId, hash, tables: [] };
+    const inApp = { tableId: { in: appTables.map((table) => table.id) } };
+    const [fieldData, pkData, uniqueData, checkData, fkData, policyData] = await Promise.all([
+        read('fields', api.field.findMany({
+            select: {
+                id: true,
+                name: true,
+                tableId: true,
+                category: true,
+                fieldOrder: true,
+                type: true,
+                isRequired: true,
+                defaultValue: true,
+                chk: true,
+                chkExpr: true,
+                generationType: true,
+                identityGeneration: true,
+                label: true,
+                description: true,
+                smartTags: true,
+            },
+            where: inApp,
+        })),
+        read('primary keys', api.primaryKeyConstraint.findMany({
+            select: { id: true, tableId: true, fieldIds: true },
+            where: inApp,
+        })),
+        read('unique constraints', api.uniqueConstraint.findMany({
+            select: { id: true, tableId: true, fieldIds: true },
+            where: inApp,
+        })),
+        read('check constraints', api.checkConstraint.findMany({
+            select: { id: true, tableId: true, fieldIds: true, expr: true },
+            where: inApp,
+        })),
+        read('foreign keys', api.foreignKeyConstraint.findMany({
+            select: {
+                id: true,
+                name: true,
+                tableId: true,
+                fieldIds: true,
+                refTableId: true,
+                refFieldIds: true,
+                deleteAction: true,
+                updateAction: true,
+            },
+            where: inApp,
+        })),
+        read('policies', api.policy.findMany({
+            select: {
+                id: true,
+                tableId: true,
+                policyType: true,
+                privilege: true,
+                granteeName: true,
+                permissive: true,
+                disabled: true,
+                data: true,
+                withCheck: true,
+            },
+            where: inApp,
+        })),
+    ]);
+    const fields = nodesOf(fieldData.fields);
+    const fieldNames = new Map(fields.map((field) => [field.id, field.name]));
+    const foreignKeys = nodesOf(fkData.foreignKeyConstraints);
+    // Columns a foreign key points at outside the APP tables (users.id).
+    const outside = [
+        ...new Set(foreignKeys.flatMap((fk) => fk.refFieldIds ?? []).filter((id) => !fieldNames.has(id))),
+    ];
+    if (outside.length > 0) {
+        const refData = await read('referenced fields', api.field.findMany({
+            select: { id: true, name: true },
+            where: { id: { in: outside } },
+        }));
+        for (const field of nodesOf(refData.fields))
+            fieldNames.set(field.id, field.name);
+    }
+    const fieldsByTable = groupBy(fields);
+    const pksByTable = groupBy(nodesOf(pkData.primaryKeyConstraints));
+    const uniquesByTable = groupBy(nodesOf(uniqueData.uniqueConstraints));
+    const checksByTable = groupBy(nodesOf(checkData.checkConstraints));
+    const fksByTable = groupBy(foreignKeys);
+    const policiesByTable = groupBy(nodesOf(policyData.policies));
+    const names = (ids) => (ids ?? []).map((id) => fieldNames.get(id) ?? id);
+    const tables = appTables.map((table) => {
+        const pkIds = new Set((pksByTable.get(table.id) ?? []).flatMap((pk) => pk.fieldIds ?? []));
+        const uniques = uniquesByTable.get(table.id) ?? [];
+        const uniqueIds = new Set(uniques.filter((u) => (u.fieldIds ?? []).length === 1).map((u) => (u.fieldIds ?? [])[0]));
+        const checks = checksByTable.get(table.id) ?? [];
+        const columns = (fieldsByTable.get(table.id) ?? [])
+            .map((field, index) => {
+            const chk = asRecord(field.chk);
+            const sources = [
+                chk && 'expression' in chk ? chk.expression : field.chk,
+                field.chkExpr,
+                ...checks.filter((c) => (c.fieldIds ?? []).length === 1 && c.fieldIds[0] === field.id).map((c) => c.expr),
+            ].map(normalize_1.readCheck);
+            const allowedValues = sources.find((source) => source.values)?.values;
+            const hasOtherCheck = sources.some((source) => source.other);
+            return {
+                id: field.id,
+                name: field.name,
+                category: field.category,
+                order: typeof field.fieldOrder === 'number' ? field.fieldOrder : index,
+                type: (0, normalize_1.normalizeType)(field.type),
+                rawType: asRecord(field.type),
+                isRequired: Boolean(field.isRequired),
+                default: (0, normalize_1.columnDefault)(field.defaultValue),
+                ...(allowedValues ? { allowedValues } : {}),
+                ...(hasOtherCheck ? { hasOtherCheck } : {}),
+                isPrimaryKey: pkIds.has(field.id),
+                isUnique: uniqueIds.has(field.id),
+                generated: Boolean(field.generationType || field.identityGeneration),
+                ...(field.label ? { label: field.label } : {}),
+                ...(field.description ? { description: field.description } : {}),
+                ...(field.smartTags ? { smartTags: field.smartTags } : {}),
+            };
+        })
+            .sort((a, b) => a.order - b.order || a.name.localeCompare(b.name));
+        const policies = (policiesByTable.get(table.id) ?? [])
+            .filter((policy) => !(0, harness_1.isInternalPolicy)(policy.policyType))
+            .map((policy) => ({
+            id: policy.id,
+            type: policy.policyType ?? '',
+            privilege: (policy.privilege ?? '').toLowerCase(),
+            role: policy.granteeName ?? '',
+            permissive: policy.permissive !== false,
+            disabled: policy.disabled === true,
+            data: asRecord(policy.data),
+            withCheck: asRecord(policy.withCheck),
+        }));
+        return {
+            id: table.id,
+            name: table.name,
+            category: table.category,
+            ...(table.label ? { label: table.label } : {}),
+            columns,
+            foreignKeys: (fksByTable.get(table.id) ?? []).map((fk) => {
+                const target = fk.refTableId ? tablesById.get(fk.refTableId) : undefined;
+                return {
+                    id: fk.id,
+                    ...(fk.name ? { name: fk.name } : {}),
+                    columnIds: fk.fieldIds ?? [],
+                    columns: names(fk.fieldIds),
+                    targetTableId: fk.refTableId ?? '',
+                    targetTable: target?.name ?? '',
+                    targetCategory: target?.category ?? null,
+                    targetColumns: names(fk.refFieldIds),
+                    onDelete: (0, normalize_1.fkAction)(fk.deleteAction),
+                    onUpdate: (0, normalize_1.fkAction)(fk.updateAction),
+                };
+            }),
+            uniqueConstraints: uniques.map((u) => ({ id: u.id, columns: names(u.fieldIds) })),
+            access: accessOf(policies),
+            policies,
+        };
+    });
+    return { databaseId, hash, tables };
+}

package/tools/add-policies.d.ts

@@ -5,10 +5,10 @@ declare const AddPoliciesZod: z.ZodObject<{
     policies: z.ZodArray<z.ZodObject<{
         policy_type: z.ZodString;
         operations: z.ZodArray<z.ZodEnum<{
+            delete: "delete";
             create: "create";
             read: "read";
             update: "update";
-            delete: "delete";
         }>>;
         role_name: z.ZodOptional<z.ZodString>;
         is_permissive: z.ZodOptional<z.ZodBoolean>;

package/tools/add-records.d.ts

@@ -9,6 +9,7 @@ export type AddRecordsDetails = {
     createdCount?: number;
     asOf?: string;
     needsAuth?: boolean;
+    code?: 'database-unavailable';
 };
 declare const AddRecordsZod: z.ZodObject<{
     table_name: z.ZodString;

package/tools/add-records.js

@@ -2,13 +2,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addRecordsTool = void 0;
 const generators_1 = require("@constructive-io/graphql-query/generators");
-const sdk_1 = require("@constructive-io/sdk");
 const zod_1 = require("zod");
 const context_1 = require("../context");
+const graphql_http_1 = require("../graphql-http");
 const meta_1 = require("../records/meta");
 function fail(message) {
     return { content: [{ type: 'text', text: message }], details: { success: false, message } };
 }
+const UNAVAILABLE = "The app database is unavailable: the backend answered ACCESS_SUSPENDED, so it was deleted or is suspended. Retrying won't help until it is restored.";
+function unavailable(inserted = 0) {
+    const message = inserted > 0 ? `${UNAVAILABLE} ${inserted} row(s) were inserted before it stopped.` : `${UNAVAILABLE} No rows were inserted.`;
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: false, message, code: 'database-unavailable', ...(inserted > 0 ? { createdCount: inserted } : {}) },
+    };
+}
+const isSuspended = (errors) => (0, graphql_http_1.classifyBackendErrors)(errors) === 'suspended';
 function needsAuth(message) {
     return {
         content: [{ type: 'text', text: message }],
@@ -53,14 +62,15 @@ exports.addRecordsTool = {
         const token = await (0, context_1.resolveDataToken)(resolved.context);
         if (!token.token)
             return needsAuth(token.reason ?? 'Sign in to the database to insert records.');
-        const adapter = new sdk_1.objects.FetchAdapter(dataEndpoint, {
-            Authorization: `Bearer ${token.token}`,
-        });
+        // Keeps the status and extensions.code that the SDK adapter drops.
+        const adapter = (0, graphql_http_1.statusAdapter)(dataEndpoint, { Authorization: `Bearer ${token.token}` });
         let tables;
         try {
             const meta = await adapter.execute(meta_1.META_QUERY);
             if (!meta.ok) {
-                return fail(`Failed to read schema from the app database: ${meta.errors.map((e) => e.message).join('; ')}`);
+                if (isSuspended(meta.errors))
+                    return unavailable();
+                return fail(`Failed to read schema from the app database: ${(0, graphql_http_1.errorsText)(meta.errors)}`);
             }
             tables = (meta.data._meta?.tables ?? []).filter((t) => Boolean(t));
         }
@@ -91,7 +101,9 @@ exports.addRecordsTool = {
             try {
                 const result = await adapter.execute(mutation, variables);
                 if (!result.ok) {
-                    errors.push(result.errors.map((e) => e.message).join('; '));
+                    if (isSuspended(result.errors))
+                        return unavailable(created.length);
+                    errors.push((0, graphql_http_1.errorsText)(result.errors));
                     continue;
                 }
                 const payload = result.data[mutationName];

package/tools/add-relation.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.addRelationTool = void 0;
 const harness_1 = require("@agentic-kit/harness");
+const blueprint_construction_1 = require("../blueprint-construction");
 const context_1 = require("../context");
 const schema_resolve_1 = require("../schema-resolve");
 const add_relation_schema_1 = require("./add-relation-schema");
@@ -58,9 +59,7 @@ exports.addRelationTool = {
             const blueprintId = created.createBlueprint?.blueprint?.id;
             if (!blueprintId)
                 throw new Error('Failed to create relation blueprint');
-            await modules.mutation
-                .constructBlueprint({ input: { blueprintId, schemaId } }, { select: { result: true } })
-                .unwrap();
+            await (0, blueprint_construction_1.buildBlueprint)(modules, { blueprintId, schemaId }, { signal: ctx.signal });
         }
         catch (err) {
             return fail(`Failed to add relation: ${err instanceof Error ? err.message : String(err)}`);

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

@@ -17,6 +17,8 @@ export type CreateApiKeyDetails = {
     principalName?: string;
     scope?: string;
     needsAuth?: boolean;
+    /** The app API answered ACCESS_SUSPENDED: the database is deleted or suspended. */
+    code?: 'database-unavailable';
 };
 export declare function toEnvVar(keyName: string): string;
 export declare function isStepUpError(messages: string[]): boolean;

package/tools/create-api-key.js

@@ -7,6 +7,7 @@ exports.describeScope = describeScope;
 const sdk_1 = require("@constructive-io/sdk");
 const zod_1 = require("zod");
 const context_1 = require("../context");
+const graphql_http_1 = require("../graphql-http");
 const host_1 = require("../host");
 const CreateApiKeyZod = zod_1.z.object({
     key_name: zod_1.z
@@ -57,19 +58,25 @@ function describeScope(entityIds, readOnly) {
         parts.push('read-only');
     return parts.join(', ');
 }
+// The plain fetch, read at call time. postGraphQL keeps a 403's body, so a
+// deleted or suspended database's ACCESS_SUSPENDED reaches the caller.
 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 }),
+    const result = await (0, graphql_http_1.postGraphQL)({
+        endpoint,
+        headers: token ? { Authorization: `Bearer ${token}` } : {},
+        query,
+        variables,
+        fetchFn: (input, init) => fetch(input, init),
     });
-    return (await res.json());
+    return { data: result.data ?? undefined, errors: result.errors.length > 0 ? result.errors : undefined };
 }
+const UNAVAILABLE_MESSAGE = 'The app database is unavailable: the backend answered ACCESS_SUSPENDED, so it was deleted or is suspended. No key was minted.';
+const isSuspended = (errors) => Boolean(errors?.length) && (0, graphql_http_1.classifyBackendErrors)(errors) === 'suspended';
+const unavailable = () => fail(UNAVAILABLE_MESSAGE, { code: 'database-unavailable' });
 async function createPrincipalInputFields(endpoint) {
     const probe = await rawGraphql(endpoint, undefined, '{ __type(name: "CreatePrincipalInput") { inputFields { name } } }');
+    if (isSuspended(probe.errors))
+        return 'unavailable';
     const type = probe.data?.__type;
     return new Set((type?.inputFields ?? []).map((f) => f.name));
 }
@@ -107,6 +114,8 @@ exports.createApiKeyTool = {
         try {
             if (scoped) {
                 const fields = await createPrincipalInputFields(authEndpoint);
+                if (fields === 'unavailable')
+                    return unavailable();
                 const missing = [
                     ...(params.entity_ids?.length && !fields.has('entityIds') ? ['entityIds'] : []),
                     ...(params.read_only === true && !fields.has('isReadOnly') ? ['isReadOnly'] : []),
@@ -116,8 +125,7 @@ exports.createApiKeyTool = {
                 }
             }
             const dbAuth = sdk_1.auth.createClient({
-                endpoint: authEndpoint,
-                headers: { Authorization: `Bearer ${token.token}` },
+                adapter: (0, graphql_http_1.statusAdapter)(authEndpoint, { Authorization: `Bearer ${token.token}` }),
             });
             const principalName = params.principal_name?.trim() || keyName;
             const existing = await dbAuth.principal
@@ -154,8 +162,10 @@ exports.createApiKeyTool = {
                         ...(params.read_only !== undefined && { isReadOnly: params.read_only }),
                     },
                 });
+                if (isSuspended(created.errors))
+                    return unavailable();
                 if (created.errors?.length) {
-                    return fail(`createPrincipal failed: ${created.errors.map((e) => e.message).join('; ')}`);
+                    return fail(`createPrincipal failed: ${(0, graphql_http_1.errorsText)(created.errors)}`);
                 }
                 const payload = created.data?.createPrincipal;
                 principalId = payload?.result;
@@ -183,7 +193,9 @@ exports.createApiKeyTool = {
                 minted = await mint();
             }
             if (!minted.ok) {
-                return fail(`createApiKey failed: ${minted.errors.map((e) => e.message).join('; ')}`);
+                if (isSuspended(minted.errors))
+                    return unavailable();
+                return fail(`createApiKey failed: ${(0, graphql_http_1.errorsText)(minted.errors)}`);
             }
             const record = minted.data?.createApiKey?.result;
             if (!record?.apiKey || !record.keyId)
@@ -214,6 +226,9 @@ exports.createApiKeyTool = {
             };
         }
         catch (err) {
+            // The SDK's unwrap() throws its errors as `errors`.
+            if (isSuspended(err?.errors))
+                return unavailable();
             return fail(err instanceof Error ? err.message : 'Failed to create the API key.');
         }
     },

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

@@ -2,8 +2,8 @@ import type { HarnessTool } from '@agentic-kit/harness';
 import { z } from 'zod';
 declare const ManageEntityTypesZod: z.ZodObject<{
     action: z.ZodEnum<{
-        create: "create";
         delete: "delete";
+        create: "create";
         list: "list";
     }>;
     name: z.ZodOptional<z.ZodString>;

package/tools/provision-blueprint.d.ts

@@ -16,6 +16,12 @@ export type ProvisionBlueprintDetails = {
     total: number;
     tables: ProvisionedTable[];
     error: string | null;
+    /**
+     * The construction the backend queued, also when the build then failed or
+     * the wait gave up: the build carries on, so calling again would build the
+     * same tables twice. Null when nothing was queued.
+     */
+    constructionId: string | null;
 };
 export declare const provisionBlueprintTool: HarnessTool<typeof BlueprintZod, ProvisionBlueprintDetails>;
 export {};

package/tools/provision-blueprint.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.provisionBlueprintTool = void 0;
 const harness_1 = require("@agentic-kit/harness");
+const blueprint_construction_1 = require("../blueprint-construction");
 const context_1 = require("../context");
 function formatText(name, details) {
     if (details.error)
@@ -26,7 +27,13 @@ exports.provisionBlueprintTool = {
     promptSnippet: 'provision_blueprint: create new tables from scratch in a single call (fields + policies + relations). Call describe_schema first.',
     parameters: harness_1.BlueprintZod,
     async execute(params, ctx) {
-        const empty = { created: 0, total: 0, tables: [], error: null };
+        const empty = {
+            created: 0,
+            total: 0,
+            tables: [],
+            error: null,
+            constructionId: null,
+        };
         const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
         if (!resolved.context) {
             return { content: [{ type: 'text', text: resolved.reason }], details: empty };
@@ -57,9 +64,7 @@ exports.provisionBlueprintTool = {
             const blueprintId = createResult.createBlueprint?.blueprint?.id;
             if (!blueprintId)
                 throw new Error('Failed to create blueprint');
-            await modules.mutation
-                .constructBlueprint({ input: { blueprintId, schemaId } }, { select: { result: true } })
-                .unwrap();
+            const { constructionId } = await (0, blueprint_construction_1.buildBlueprint)(modules, { blueprintId, schemaId }, { signal: ctx.signal });
             const relations = params.definition.relations ?? [];
             const details = {
                 created: params.definition.tables.length,
@@ -76,6 +81,7 @@ exports.provisionBlueprintTool = {
                     relationCount: relations.filter((r) => r.source_table === t.table_name).length,
                 })),
                 error: null,
+                constructionId,
             };
             return { content: [{ type: 'text', text: formatText(params.name, details) }], details };
         }
@@ -86,6 +92,7 @@ exports.provisionBlueprintTool = {
                 total: params.definition.tables.length,
                 tables: [],
                 error: message,
+                constructionId: err instanceof blueprint_construction_1.BlueprintBuildError ? err.constructionId : null,
             };
             return { content: [{ type: 'text', text: formatText(params.name, details) }], details };
         }

package/tools/provision-database.d.ts

@@ -1,17 +1,14 @@
 import type { HarnessTool } from '@agentic-kit/harness';
 import { z } from 'zod';
+import { type RunCommand } from '../app-workspace';
+import { type ProvisionDatabaseDetails } from '../provision-database/provision';
+export type { ProvisionDatabaseDetails };
 declare const ProvisionDatabaseZod: z.ZodObject<{
     database_name: z.ZodString;
     reprovision: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
-export type ProvisionDatabaseDetails = {
-    success: boolean;
-    message: string;
-    databaseId?: string;
-    databaseName?: string;
-    ownerId?: string;
-    /** True when an existing live binding was kept — nothing changed. */
-    skipped?: boolean;
-};
-export declare const provisionDatabaseTool: HarnessTool<typeof ProvisionDatabaseZod, ProvisionDatabaseDetails>;
-export {};
+export declare function createProvisionDatabaseTool(exec?: RunCommand): HarnessTool<typeof ProvisionDatabaseZod, ProvisionDatabaseDetails>;
+export declare const provisionDatabaseTool: HarnessTool<z.ZodObject<{
+    database_name: z.ZodString;
+    reprovision: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>, ProvisionDatabaseDetails>;