@auxx/sdk 0.0.12 → 0.0.14

package/lib/commands/dev/upload.js

@@ -5,7 +5,7 @@ import { combineAsync, complete, isErrored } from '../../errors.js';
 import { calculateBundleSha } from '../../util/calculate-bundle-sha.js';
 import { spinnerify } from '../../util/spinner.js';
 import { uploadBundle } from '../../util/upload-bundle.js';
-export async function upload({ contents, appId, targetOrganizationId, environmentVariables, cliVersion, settingsSchema, }) {
+export async function upload({ contents, appId, targetOrganizationId, environmentVariables, cliVersion, settingsSchema, catalog, }) {
     return await spinnerify('Uploading...', () => `Upload complete at ${new Date().toLocaleTimeString()}`, async () => {
         const [clientBundle, serverBundle] = contents;
         const clientSha = calculateBundleSha(clientBundle);
@@ -34,6 +34,9 @@ export async function upload({ contents, appId, targetOrganizationId, environmen
         if (settingsSchema) {
             process.stdout.write(`${chalk.green('✓ ')}Settings schema included\n`);
         }
+        if (catalog && (catalog.tools.length || catalog.toolsets.length)) {
+            process.stdout.write(`${chalk.green('✓ ')}Catalog extracted (${catalog.tools.length} tools, ${catalog.toolsets.length} toolsets, ${catalog.workflow.blocks.length} blocks, ${catalog.triggers.length} triggers, ${catalog.actions.length} actions)\n`);
+        }
         const deployResult = await api.createDeployment({
             appId,
             clientBundleSha: clientSha,
@@ -42,6 +45,7 @@ export async function upload({ contents, appId, targetOrganizationId, environmen
             targetOrganizationId,
             environmentVariables,
             settingsSchema,
+            catalog,
             metadata: { cliVersion },
         });
         if (isErrored(deployResult)) {

package/lib/commands/dev.js

@@ -9,6 +9,7 @@ import { isErrored } from '../errors.js';
 import { printUploadError } from '../print-errors.js';
 import { addAuxxHiddenDirectoryToTsConfig } from '../util/add-auxx-hidden-directory-to-ts-config.js';
 import { ensureAppEntryPoint } from '../util/ensure-app-entry-point.js';
+import { ensureAppFieldsTypes } from '../util/ensure-app-fields-types.js';
 import { generateAppEnvTypes } from '../util/generate-app-env-types.js';
 import { generateGitignore } from '../util/generate-gitignore.js';
 import { generateSettingsFiles } from '../util/generate-settings-files.js';
@@ -69,6 +70,7 @@ export const dev = new Command('dev')
     else if (appEnvTypesResult.value === 'skipped_unmanaged') {
         process.stderr.write(chalk.yellow('Skipping src/auxx-env.d.ts generation because the existing file is unmanaged. Add imports for @auxx/sdk/client and @auxx/sdk/global manually.\n'));
     }
+    await ensureAppFieldsTypes();
     if (USE_SETTINGS) {
         const updateTsconfigResult = await addAuxxHiddenDirectoryToTsConfig();
         if (isErrored(updateTsconfigResult)) {
@@ -129,7 +131,7 @@ export const dev = new Command('dev')
         });
         cleanupFunctions.push(cleanupTs);
         let haveBundlingErrors = false;
-        const cleanupJs = bundleJavaScript(async (contents, settingsSchema) => {
+        const cleanupJs = bundleJavaScript(async (contents, settingsSchema, catalog) => {
             if (haveBundlingErrors) {
                 process.stdout.write(`${chalk.green('✓')} Bundling errors fixed\n`);
                 haveBundlingErrors = false;
@@ -141,6 +143,7 @@ export const dev = new Command('dev')
                 environmentVariables,
                 cliVersion,
                 settingsSchema,
+                catalog,
             });
             if (isErrored(uploadResult)) {
                 printUploadError(uploadResult);

package/lib/commands/version/create/bundle-javascript.js

@@ -1,4 +1,5 @@
 import { complete, errored, isErrored } from '../../../errors.js';
+import { compileAndExtractCatalog, } from '../../../util/compile-and-extract-catalog.js';
 import { compileAndExtractSettingsSchema } from '../../../util/compile-and-extract-settings.js';
 import { prepareBuildContext } from '../../dev/prepare-build-context.js';
 export async function bundleJavaScript() {
@@ -26,8 +27,17 @@ export async function bundleJavaScript() {
         });
     }
     const settingsSchema = await compileAndExtractSettingsSchema();
+    const catalogResult = await compileAndExtractCatalog();
+    if (isErrored(catalogResult)) {
+        return errored({
+            code: 'ERROR_EXTRACTING_CATALOG',
+            error: catalogResult.error,
+        });
+    }
+    const catalog = catalogResult.value;
     return complete({
         bundles: [builds.client.outputFiles[0].text, builds.server.outputFiles[0].text],
         settingsSchema,
+        catalog,
     });
 }

package/lib/commands/version/create.js

@@ -16,11 +16,13 @@ import { loadAuxxCliVersion } from '../../util/load-auxx-cli-version.js';
 import { spinnerify } from '../../util/spinner.js';
 import { printJsError } from '../../util/typescript.js';
 import { uploadBundle } from '../../util/upload-bundle.js';
+import { validateTypeScriptOrExit } from '../build/validate-typescript.js';
 import { printBuildContextError } from '../dev/prepare-build-context.js';
 import { bundleJavaScript } from './create/bundle-javascript.js';
 export const versionCreate = new Command('create')
     .description('Create a new deployment of your auxx app')
-    .action(async () => {
+    .option('--publish', 'Submit the deployment for review and publish it once approved')
+    .action(async (options) => {
     if (USE_APP_TS) {
         const appEntryPointResult = await ensureAppEntryPoint();
         if (isErrored(appEntryPointResult)) {
@@ -33,6 +35,7 @@ export const versionCreate = new Command('create')
             exitWithMissingAppSettings();
         }
     }
+    await validateTypeScriptOrExit();
     await authenticator.ensureAuthed();
     const appSlugResult = await getAppSlugFromPackageJson();
     if (isErrored(appSlugResult)) {
@@ -59,16 +62,28 @@ export const versionCreate = new Command('create')
                 printBuildContextError(error);
             }
         }
+        else if (bundleResult.error.code === 'ERROR_EXTRACTING_CATALOG') {
+            const catalogError = bundleResult.error.error;
+            const detail = 'message' in catalogError
+                ? catalogError.message
+                : 'error' in catalogError
+                    ? catalogError.error.message
+                    : '';
+            process.stderr.write(`${chalk.red('✖ ')}Catalog extraction failed (${catalogError.code})${detail ? `: ${detail}` : ''}\n`);
+        }
         else {
             printBuildContextError(bundleResult.error.error);
         }
         process.exit(1);
     }
-    const { bundles, settingsSchema } = bundleResult.value;
+    const { bundles, settingsSchema, catalog } = bundleResult.value;
     const [clientBundle, serverBundle] = bundles;
     if (settingsSchema) {
         process.stdout.write(`${chalk.green('✓ ')}Settings schema extracted\n`);
     }
+    if (catalog && (catalog.tools.length || catalog.toolsets.length)) {
+        process.stdout.write(`${chalk.green('✓ ')}Catalog extracted (${catalog.tools.length} tools, ${catalog.toolsets.length} toolsets, ${catalog.workflow.blocks.length} blocks, ${catalog.triggers.length} triggers, ${catalog.actions.length} actions)\n`);
+    }
     const deployResult = await spinnerify('Uploading...', 'Upload complete', async () => {
         const cliVersionResult = loadAuxxCliVersion();
         if (isErrored(cliVersionResult)) {
@@ -112,7 +127,9 @@ export const versionCreate = new Command('create')
             serverBundleSha: serverSha,
             deploymentType: 'production',
             settingsSchema,
+            catalog,
             metadata: { cliVersion },
+            publish: options.publish,
         });
         if (isErrored(result)) {
             printFetcherError('Error creating deployment', result);
@@ -125,6 +142,26 @@ export const versionCreate = new Command('create')
         process.exit(1);
     }
     const deployment = deployResult.value;
-    process.stdout.write(`\nDeployment ${chalk.green(deployment.version ?? deployment.deploymentId)} created!\n\n`);
+    if (deployment.unchanged) {
+        process.stdout.write(`\n${chalk.gray('●')} Unchanged — skipped (${deployment.version ?? deployment.deploymentId})\n\n`);
+        process.exit(0);
+    }
+    process.stdout.write(`\nDeployment ${chalk.green(deployment.version ?? deployment.deploymentId)} created!\n`);
+    if (options.publish) {
+        if (deployment.publishError) {
+            process.stderr.write(`${chalk.red('✖ ')}Publish failed: ${deployment.publishError}\n`);
+            process.exit(1);
+        }
+        if (deployment.status === 'published') {
+            process.stdout.write(`${chalk.green('✓ ')}Published — live for installed organizations\n`);
+        }
+        else if (deployment.status === 'pending-review') {
+            process.stdout.write(`${chalk.yellow('● ')}Submitted for review (publishes on approval)\n`);
+        }
+        else if (deployment.status) {
+            process.stdout.write(`Status: ${deployment.status}\n`);
+        }
+    }
+    process.stdout.write('\n');
     process.exit(0);
 });

package/lib/constants/app-fields-files.js

@@ -0,0 +1 @@
+export const APP_FIELDS_TYPES_FILENAME = 'app-fields.d.ts';

package/lib/env-loader.js

@@ -1,2 +1,18 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import dotenv from 'dotenv';
-dotenv.config();
+function findEnvFile() {
+    let dir = resolve(process.cwd());
+    const root = dirname(dir) === dir ? dir : '/';
+    while (true) {
+        const candidate = join(dir, '.env');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir || dir === root)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+dotenv.config({ path: findEnvFile() });

package/lib/env.js

@@ -6,3 +6,4 @@ export const AUTH_API = `${APP_URL}/api/auth`;
 export const USE_APP_TS = process.env.USE_APP_TS !== 'false';
 export const USE_SETTINGS = process.env.USE_SETTINGS !== 'false';
 export const SDK_CLIENT_ID = process.env.AUXX_SDK_CLIENT_ID || 'auxx-sdk-cli';
+export const AUXX_API_KEY = process.env.AUXX_API_KEY;

package/lib/root/app.d.ts

@@ -1,6 +1,8 @@
 import type { BulkRecordAction, RecordAction, RecordWidget } from '../client/record-actions.js';
+import type { AppFieldDefinition } from './fields/index.js';
 import type { ScopedSettingsSchema } from './settings/settings-schema.js';
-import type { WorkflowBlock, WorkflowTrigger } from './workflow/types.js';
+import type { ToolDefinition, Toolset } from './tools/types.js';
+import type { Trigger, WorkflowBlock } from './workflow/types.js';
 export interface Permission {
     resource: 'records' | 'workflows' | 'api' | 'storage' | 'users';
     actions: ('read' | 'write' | 'delete')[];
@@ -43,8 +45,11 @@ export interface App {
     };
     readonly workflow?: {
         readonly blocks?: WorkflowBlock[];
-        readonly triggers?: WorkflowTrigger[];
+        readonly triggers?: Trigger[];
     };
+    readonly tools?: ReadonlyArray<ToolDefinition>;
+    readonly toolsets?: ReadonlyArray<Toolset>;
+    readonly fields?: ReadonlyArray<AppFieldDefinition>;
     readonly settings?: {
         readonly organization?: ScopedSettingsSchema;
     };

package/lib/root/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/root/app.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAE/F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAIzE,MAAM,WAAW,UAAU;IAEzB,QAAQ,EAAE,SAAS,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,CAAA;IAE/D,OAAO,EAAE,CAAC,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC,EAAE,CAAA;IAExC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAKD,MAAM,WAAW,WAAW;IAE1B,IAAI,EAAE,MAAM,CAAA;IAEZ,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAE1B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAuBD,MAAM,CAAC,OAAO,WAAW,GAAG,CAAC;IAC3B,UAAU,MAAM,CAAC;QACf,KAAK,MAAM,GAAG,YAAY,CAAA;QAC1B,KAAK,UAAU,GAAG,gBAAgB,CAAA;QAClC,KAAK,MAAM,GAAG,YAAY,CAAA;KAC3B;IACD,UAAU,QAAQ,CAAC,GAAE;IACrB,UAAU,QAAQ,CAAC,GAAE;CACtB;AAED,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;KAC5C,CAAA;IAED,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,OAAO,CAAC,EAAE;YACjB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACpC,CAAA;QACD,QAAQ,CAAC,OAAO,CAAC,EAAE;YACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACrC,CAAA;QACD,QAAQ,CAAC,UAAU,CAAC,EAAE;YACpB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACpC,CAAA;KACF,CAAA;IAED,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAElB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,CAAA;QAEjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAA;KACtC,CAAA;IACD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;KAC7C,CAAA;CAIF"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/root/app.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC/F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAC3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AACzE,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAIjE,MAAM,WAAW,UAAU;IAEzB,QAAQ,EAAE,SAAS,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,CAAA;IAE/D,OAAO,EAAE,CAAC,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC,EAAE,CAAA;IAExC,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAKD,MAAM,WAAW,WAAW;IAE1B,IAAI,EAAE,MAAM,CAAA;IAEZ,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;IAE1B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAuBD,MAAM,CAAC,OAAO,WAAW,GAAG,CAAC;IAC3B,UAAU,MAAM,CAAC;QACf,KAAK,MAAM,GAAG,YAAY,CAAA;QAC1B,KAAK,UAAU,GAAG,gBAAgB,CAAA;QAClC,KAAK,MAAM,GAAG,YAAY,CAAA;KAC3B;IACD,UAAU,QAAQ,CAAC,GAAE;IACrB,UAAU,QAAQ,CAAC,GAAE;CACtB;AAED,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAC3C,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;KAC5C,CAAA;IAED,QAAQ,CAAC,aAAa,CAAC,EAAE;QACvB,QAAQ,CAAC,OAAO,CAAC,EAAE;YACjB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACpC,CAAA;QACD,QAAQ,CAAC,OAAO,CAAC,EAAE;YACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACrC,CAAA;QACD,QAAQ,CAAC,UAAU,CAAC,EAAE;YACpB,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;SACpC,CAAA;KACF,CAAA;IAED,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAElB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,CAAA;QAEjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAA;KAC9B,CAAA;IAOD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;IAK9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAA;IAQ1C,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;IAEnD,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;KAC7C,CAAA;CAIF"}

package/lib/root/fields/define-field.d.ts

@@ -0,0 +1,67 @@
+import type { EntityRefKind } from '../tools/types.js';
+import type { FieldCapabilities, FieldScope, FieldSelectOption, FieldType } from './field-types.js';
+type SelectFieldType = 'SINGLE_SELECT' | 'MULTI_SELECT' | 'TAGS';
+type ScalarFieldType = Exclude<FieldType, SelectFieldType | 'RELATIONSHIP' | 'CALC' | 'ACTOR'>;
+interface BaseAppFieldDefinition {
+    readonly appFieldKey: string;
+    readonly targetEntity: EntityRefKind;
+    readonly scope: FieldScope;
+    readonly name: string;
+    readonly description?: string;
+    readonly capabilities?: FieldCapabilities;
+}
+interface ScalarAppFieldDefinition extends BaseAppFieldDefinition {
+    readonly type: ScalarFieldType;
+    readonly options?: never;
+    readonly relationship?: never;
+    readonly calc?: never;
+}
+interface SelectAppFieldDefinition extends BaseAppFieldDefinition {
+    readonly type: SelectFieldType;
+    readonly options: readonly FieldSelectOption[];
+    readonly relationship?: never;
+    readonly calc?: never;
+}
+interface RelationshipAppFieldDefinition extends BaseAppFieldDefinition {
+    readonly type: 'RELATIONSHIP';
+    readonly relationship: {
+        readonly targetEntity: EntityRefKind;
+        readonly cardinality: 'one' | 'many';
+    };
+    readonly options?: never;
+    readonly calc?: never;
+}
+interface CalcAppFieldDefinition extends BaseAppFieldDefinition {
+    readonly type: 'CALC';
+    readonly calc: {
+        readonly expression: string;
+    };
+    readonly options?: never;
+    readonly relationship?: never;
+}
+export type AppFieldDefinition = ScalarAppFieldDefinition | SelectAppFieldDefinition | RelationshipAppFieldDefinition | CalcAppFieldDefinition;
+export declare function defineField<const F extends AppFieldDefinition>(field: F): F;
+export declare function defineFields<const F extends readonly AppFieldDefinition[]>(fields: F): F;
+type OptionValues<F> = F extends {
+    options: readonly (infer O)[];
+} ? O extends {
+    value: infer V;
+} ? V : string : string;
+export type FieldValueType<F extends AppFieldDefinition> = F extends {
+    type: 'SINGLE_SELECT';
+} ? OptionValues<F> : F extends {
+    type: 'MULTI_SELECT' | 'TAGS';
+} ? OptionValues<F>[] : F extends {
+    type: 'NUMBER' | 'CURRENCY';
+} ? number : F extends {
+    type: 'CHECKBOX';
+} ? boolean : F extends {
+    type: 'JSON';
+} ? unknown : F extends {
+    type: 'RELATIONSHIP';
+} ? string : string;
+export type AppFieldValues<F extends readonly AppFieldDefinition[]> = {
+    [K in F[number] as K['appFieldKey']]: FieldValueType<K>;
+};
+export {};
+//# sourceMappingURL=define-field.d.ts.map

package/lib/root/fields/define-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-field.d.ts","sourceRoot":"","sources":["../../../src/root/fields/define-field.ts"],"names":[],"mappings":"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"}

package/lib/root/fields/define-field.js

@@ -0,0 +1,21 @@
+const APP_FIELD_KEY_RE = /^[a-zA-Z][a-zA-Z0-9_]{0,63}$/;
+export function defineField(field) {
+    if (!APP_FIELD_KEY_RE.test(field.appFieldKey)) {
+        throw new Error(`defineField: invalid appFieldKey "${field.appFieldKey}" — must match ${APP_FIELD_KEY_RE.source}`);
+    }
+    return field;
+}
+export function defineFields(fields) {
+    const seen = new Set();
+    for (const field of fields) {
+        if (!APP_FIELD_KEY_RE.test(field.appFieldKey)) {
+            throw new Error(`defineFields: invalid appFieldKey "${field.appFieldKey}" — must match ${APP_FIELD_KEY_RE.source}`);
+        }
+        const dedupeKey = `${field.targetEntity}:${field.appFieldKey}`;
+        if (seen.has(dedupeKey)) {
+            throw new Error(`defineFields: duplicate appFieldKey "${field.appFieldKey}" on entity "${field.targetEntity}"`);
+        }
+        seen.add(dedupeKey);
+    }
+    return fields;
+}

package/lib/root/fields/field-types.d.ts

@@ -0,0 +1,47 @@
+export declare const FIELD_TYPES: readonly ["TEXT", "EMAIL", "URL", "RICH_TEXT", "PHONE", "PHONE_INTL", "ADDRESS", "ADDRESS_STRUCT", "FILE", "DATE", "DATETIME", "TIME", "NUMBER", "CURRENCY", "CHECKBOX", "JSON", "NAME", "SINGLE_SELECT", "MULTI_SELECT", "TAGS", "RELATIONSHIP", "CALC", "ACTOR"];
+export type FieldType = (typeof FIELD_TYPES)[number];
+export interface FieldCapabilities {
+    filterable?: boolean;
+    sortable?: boolean;
+    creatable?: boolean;
+    updatable?: boolean;
+    required?: boolean;
+    unique?: boolean;
+    computed?: boolean;
+    hidden?: boolean;
+}
+export type FieldScope = 'installation' | 'connection';
+export interface FieldSelectOption {
+    value: string;
+    label?: string;
+    color?: string;
+}
+export interface FieldTypeValueMap {
+    TEXT: string;
+    EMAIL: string;
+    URL: string;
+    RICH_TEXT: string;
+    PHONE: string;
+    PHONE_INTL: string;
+    ADDRESS: string;
+    DATE: string;
+    DATETIME: string;
+    TIME: string;
+    NUMBER: number;
+    CURRENCY: number;
+    CHECKBOX: boolean;
+    JSON: unknown;
+    NAME: string;
+    SINGLE_SELECT: string;
+    MULTI_SELECT: string[];
+    TAGS: string[];
+    ADDRESS_STRUCT: Record<string, unknown>;
+    FILE: {
+        url: string;
+        name?: string;
+    };
+    RELATIONSHIP: string;
+    CALC: string | number;
+    ACTOR: string | string[];
+}
+//# sourceMappingURL=field-types.d.ts.map

package/lib/root/fields/field-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../../src/root/fields/field-types.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,WAAW,oQAwBd,CAAA;AAGV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAOpD,MAAM,WAAW,iBAAiB;IAEhC,UAAU,CAAC,EAAE,OAAO,CAAA;IAEpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB,SAAS,CAAC,EAAE,OAAO,CAAA;IAGnB,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAIlB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAGD,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG,YAAY,CAAA;AAGtD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAQD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,OAAO,CAAA;IACjB,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;IACrB,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;CACzB"}

package/lib/root/fields/field-types.js

@@ -0,0 +1,25 @@
+export const FIELD_TYPES = [
+    'TEXT',
+    'EMAIL',
+    'URL',
+    'RICH_TEXT',
+    'PHONE',
+    'PHONE_INTL',
+    'ADDRESS',
+    'ADDRESS_STRUCT',
+    'FILE',
+    'DATE',
+    'DATETIME',
+    'TIME',
+    'NUMBER',
+    'CURRENCY',
+    'CHECKBOX',
+    'JSON',
+    'NAME',
+    'SINGLE_SELECT',
+    'MULTI_SELECT',
+    'TAGS',
+    'RELATIONSHIP',
+    'CALC',
+    'ACTOR',
+];

package/lib/root/fields/index.d.ts

@@ -0,0 +1,3 @@
+export { type AppFieldDefinition, type AppFieldValues, defineField, defineFields, type FieldValueType, } from './define-field.js';
+export { FIELD_TYPES, type FieldCapabilities, type FieldScope, type FieldSelectOption, type FieldType, type FieldTypeValueMap, } from './field-types.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/root/fields/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/root/fields/index.ts"],"names":[],"mappings":"AA0BA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,WAAW,EACX,YAAY,EACZ,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EACL,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAA"}

package/lib/root/fields/index.js

@@ -0,0 +1,2 @@
+export { defineField, defineFields, } from './define-field.js';
+export { FIELD_TYPES, } from './field-types.js';

package/lib/root/index.d.ts

@@ -1,8 +1,11 @@
 export type { BulkRecordAction, RecordAction, RecordActionContext, } from '../client/record-actions.js';
 export type { TriggerContext, WorkflowContext, WorkflowInput, WorkflowOutput, } from '../server/workflow/index.js';
 export type { App, AppSettings, Permission } from './app.js';
+export { type AppFieldDefinition, type AppFieldValues, defineField, defineFields, FIELD_TYPES, type FieldCapabilities, type FieldScope, type FieldSelectOption, type FieldType, type FieldTypeValueMap, type FieldValueType, } from './fields/index.js';
 export { Settings } from './settings/index.js';
 export type { BaseSettingOptions, BooleanSettingOptions, NumberSettingOptions, SelectSettingOptions, SettingsBooleanNode, SettingsNode, SettingsNumberNode, SettingsSchema, SettingsSelectNode, SettingsStringNode, SettingsStructNode, StringSettingOptions, StructSettingOptions, } from './settings/settings-schema.js';
-export type { ArrayInputOptions, BaseType, BaseWorkflowFieldOptions, BooleanInputOptions, Connection, InferFieldType, InferWorkflowInput, InferWorkflowOutput, NumberInputOptions, SelectInputOptions, SelectOption, StringInputOptions, StructInputOptions, WorkflowArrayNode, WorkflowBlock, WorkflowBlockConfig, WorkflowBooleanNode, WorkflowCategory, WorkflowExecuteFunction, WorkflowExecutionContext, WorkflowFieldNode, WorkflowNode, WorkflowNodeProps, WorkflowNumberNode, WorkflowOrganization, WorkflowPanelProps, WorkflowSchema, WorkflowSDK, WorkflowSelectNode, WorkflowStringNode, WorkflowStructNode, WorkflowTrigger, WorkflowUser, } from './workflow/index.js';
-export { Workflow } from './workflow/index.js';
+export type { AuxxRefMeta, EntityRefKind, ToolActionContext, ToolActionEntity, ToolActionParticipant, ToolActionSurface, ToolAgentSurface, ToolConfig, ToolDefinition, ToolExecuteContext, Toolset, } from './tools/index.js';
+export { defineTool, refs, z } from './tools/index.js';
+export type { ArrayInputOptions, BaseType, BaseWorkflowFieldOptions, BooleanInputOptions, Connection, InferFieldType, InferWorkflowInput, InferWorkflowOutput, NumberInputOptions, SelectInputOptions, SelectOption, StringInputOptions, StructInputOptions, Trigger, TriggerAgentSurface, TriggerWorkflowSurface, WorkflowArrayNode, WorkflowBlock, WorkflowBlockConfig, WorkflowBooleanNode, WorkflowCategory, WorkflowExecuteContext, WorkflowExecuteFunction, WorkflowExecutionContext, WorkflowFieldNode, WorkflowNode, WorkflowNodeProps, WorkflowNumberNode, WorkflowOrganization, WorkflowPanelProps, WorkflowSchema, WorkflowSDK, WorkflowSelectNode, WorkflowStringNode, WorkflowStructNode, WorkflowUser, } from './workflow/index.js';
+export { defineTrigger, Workflow } from './workflow/index.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/root/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/root/index.ts"],"names":[],"mappings":"AASA,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,6BAA6B,CAAA;AACpC,YAAY,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAE9C,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EAEZ,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EAEjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,YAAY,GACb,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/root/index.ts"],"names":[],"mappings":"AASA,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,GACf,MAAM,6BAA6B,CAAA;AACpC,YAAY,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE5D,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,iBAAiB,EACtB,KAAK,cAAc,GACpB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAE9C,YAAY,EACV,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,+BAA+B,CAAA;AACtC,YAAY,EACV,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,OAAO,GACR,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,kBAAkB,CAAA;AACtD,YAAY,EACV,iBAAiB,EACjB,QAAQ,EACR,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EAEZ,kBAAkB,EAClB,kBAAkB,EAClB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EAEjB,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,GACb,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA"}

package/lib/root/index.js

@@ -1,2 +1,4 @@
+export { defineField, defineFields, FIELD_TYPES, } from './fields/index.js';
 export { Settings } from './settings/index.js';
-export { Workflow } from './workflow/index.js';
+export { defineTool, refs, z } from './tools/index.js';
+export { defineTrigger, Workflow } from './workflow/index.js';

package/lib/root/tools/define-tool.d.ts

@@ -0,0 +1,4 @@
+import type { z } from 'zod/v4';
+import type { ToolDefinition } from './types.js';
+export declare function defineTool<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny>(tool: ToolDefinition<TInput, TOutput>): ToolDefinition<TInput, TOutput>;
+//# sourceMappingURL=define-tool.d.ts.map

package/lib/root/tools/define-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-tool.d.ts","sourceRoot":"","sources":["../../../src/root/tools/define-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAkBhD,wBAAgB,UAAU,CAAC,MAAM,SAAS,CAAC,CAAC,UAAU,EAAE,OAAO,SAAS,CAAC,CAAC,UAAU,EAClF,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BjC"}

package/lib/root/tools/define-tool.js

@@ -0,0 +1,21 @@
+const TOOL_ID_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+export function defineTool(tool) {
+    if (!TOOL_ID_RE.test(tool.id)) {
+        throw new Error(`defineTool: invalid id "${tool.id}" — must match ${TOOL_ID_RE.source}`);
+    }
+    if (tool.exampleOutput !== undefined) {
+        const parsed = tool.outputs.safeParse(tool.exampleOutput);
+        if (!parsed.success) {
+            throw new Error(`defineTool: tool "${tool.id}" exampleOutput does not satisfy its outputs schema — ${parsed.error.message}`);
+        }
+        try {
+            if (JSON.stringify(tool.exampleOutput) === undefined) {
+                throw new Error('serializes to undefined (function or top-level undefined)');
+            }
+        }
+        catch (err) {
+            throw new Error(`defineTool: tool "${tool.id}" exampleOutput is not JSON-serializable — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return tool;
+}

package/lib/root/tools/index.d.ts

@@ -0,0 +1,5 @@
+export { z } from 'zod/v4';
+export { defineTool } from './define-tool.js';
+export { type AuxxRefMeta, refs } from './refs.js';
+export type { EntityRefKind, ToolActionContext, ToolActionEntity, ToolActionParticipant, ToolActionSurface, ToolAgentSurface, ToolConfig, ToolDefinition, ToolExecuteContext, Toolset, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/root/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/root/tools/index.ts"],"names":[],"mappings":"AA0BA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,KAAK,WAAW,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAClD,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,OAAO,GACR,MAAM,YAAY,CAAA"}

package/lib/root/tools/index.js

@@ -0,0 +1,3 @@
+export { z } from 'zod/v4';
+export { defineTool } from './define-tool.js';
+export { refs } from './refs.js';

package/lib/root/tools/refs.d.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod/v4';
+import type { EntityRefKind } from './types.js';
+export interface AuxxRefMeta {
+    readonly kind: EntityRefKind;
+}
+export declare const refs: {
+    entity: <K extends EntityRefKind>(kind: K) => z.ZodString;
+};
+//# sourceMappingURL=refs.d.ts.map

package/lib/root/tools/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../../src/root/tools/refs.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAC1B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAU/C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAC7B;AAOD,eAAO,MAAM,IAAI;aACN,CAAC,SAAS,aAAa,QAAQ,CAAC;CAE1C,CAAA"}

package/lib/root/tools/refs.js

@@ -0,0 +1,4 @@
+import { z } from 'zod/v4';
+export const refs = {
+    entity: (kind) => z.string().meta({ auxxRef: { kind } }),
+};

package/lib/root/tools/types.d.ts

@@ -0,0 +1,91 @@
+import type { ComponentType } from 'react';
+import type { z } from 'zod/v4';
+export interface ToolActionEntity {
+    id: string;
+    entityDefinitionId: string;
+    entityDefinitionSlug: string;
+    displayName: string;
+    fields: Record<string, unknown>;
+}
+export interface ToolActionParticipant {
+    email: string;
+    name?: string;
+    isInternal: boolean;
+    contact?: ToolActionEntity;
+}
+export interface ToolActionContext {
+    threadId: string;
+    ticket?: ToolActionEntity;
+    participants: ToolActionParticipant[];
+    entities: ToolActionEntity[];
+}
+export type EntityRefKind = 'contact' | 'company' | 'deal' | 'ticket' | 'task' | 'user' | 'article' | 'thread';
+export interface ToolConfig {
+    readonly requiresConnection?: boolean;
+    readonly timeout?: number;
+    readonly idempotent?: boolean;
+    readonly streaming?: boolean;
+}
+export type AgentSurface = 'internal' | 'chat' | 'email' | 'builder';
+export interface ToolAgentSurface {
+    readonly name?: string;
+    readonly description?: string;
+    readonly toolsetSlug?: string;
+    readonly streaming?: boolean;
+    readonly idempotent?: boolean;
+    readonly surfaces?: AgentSurface[];
+    readonly externalSafe?: boolean;
+    readonly inputBindings?: ReadonlyArray<{
+        name: string;
+        default: {
+            kind: 'var';
+            ref: string | readonly string[];
+        } | {
+            kind: 'const';
+            value: unknown;
+        } | {
+            kind: 'model';
+        };
+    }>;
+}
+export interface ToolActionSurface {
+    readonly label: string;
+    readonly description?: string;
+    readonly icon?: string | ComponentType;
+    readonly color?: string;
+    readonly surface: 'ticket-header' | 'email-editor';
+    readonly requiresConfirmation?: boolean;
+    readonly confirmationMessage?: string;
+    readonly shouldShow?: (ctx: ToolActionContext) => boolean;
+    readonly getDefaults?: (ctx: ToolActionContext) => Record<string, unknown>;
+}
+export interface ToolDefinition<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string | ComponentType;
+    readonly inputs: TInput;
+    readonly outputs: TOutput;
+    readonly exampleOutput?: z.output<TOutput>;
+    readonly config?: ToolConfig;
+    readonly execute: (input: z.input<TInput>, ctx: ToolExecuteContext) => Promise<z.output<TOutput>> | AsyncGenerator<unknown, z.output<TOutput>>;
+    readonly agent?: ToolAgentSurface;
+    readonly action?: ToolActionSurface;
+}
+export interface Toolset {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly icon?: string | ComponentType;
+    readonly tools: readonly string[];
+    readonly subGroup?: string;
+}
+export interface ToolExecuteContext {
+    readonly organizationId: string;
+    readonly userId: string | null;
+    readonly appInstallationId: string;
+    readonly sessionId: string;
+    readonly agentId: string | null;
+    readonly triggerId: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/root/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/root/tools/types.ts"],"names":[],"mappings":"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"}