@amodalai/core 0.1.0

package/dist/src/repo/tool-types.d.ts

@@ -0,0 +1,205 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { z } from 'zod';
+import { ResponseShapingSchema } from '../tools/http-tool-types.js';
+/** Regex for valid tool names — snake_case, starts with lowercase letter */
+export declare const TOOL_NAME_REGEX: RegExp;
+/**
+ * Schema for a tool.json file in the tools/ directory.
+ *
+ * `name` is optional — if omitted, the directory name is used.
+ * If provided, it must match the directory name.
+ */
+export declare const ToolJsonSchema: z.ZodObject<{
+    /** Tool name — snake_case, starts with lowercase letter. Optional; defaults to directory name. */
+    name: z.ZodOptional<z.ZodString>;
+    /** Description shown to the LLM */
+    description: z.ZodString;
+    /** JSON Schema describing the parameters the LLM should provide */
+    parameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    /** Confirmation behavior: false=no confirm, true=confirm before run, 'review'=show params, 'never'=hide from LLM */
+    confirm: z.ZodDefault<z.ZodUnion<[z.ZodLiteral<false>, z.ZodLiteral<true>, z.ZodLiteral<"review">, z.ZodLiteral<"never">]>>;
+    /** Execution timeout in milliseconds */
+    timeout: z.ZodDefault<z.ZodNumber>;
+    /** Environment variable names the handler is allowed to access */
+    env: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Optional response shaping configuration */
+    responseShaping: z.ZodOptional<z.ZodObject<{
+        path: z.ZodOptional<z.ZodString>;
+        maxLength: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        maxLength: number;
+        path?: string | undefined;
+    }, {
+        path?: string | undefined;
+        maxLength?: number | undefined;
+    }>>;
+    /** Sandbox configuration for hosted execution */
+    sandbox: z.ZodOptional<z.ZodObject<{
+        /** Base language runtime for the sandbox (default: 'typescript') */
+        language: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        language: string;
+    }, {
+        language?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    parameters: Record<string, unknown>;
+    timeout: number;
+    confirm: boolean | "never" | "review";
+    env: string[];
+    name?: string | undefined;
+    responseShaping?: {
+        maxLength: number;
+        path?: string | undefined;
+    } | undefined;
+    sandbox?: {
+        language: string;
+    } | undefined;
+}, {
+    description: string;
+    name?: string | undefined;
+    responseShaping?: {
+        path?: string | undefined;
+        maxLength?: number | undefined;
+    } | undefined;
+    parameters?: Record<string, unknown> | undefined;
+    timeout?: number | undefined;
+    confirm?: boolean | "never" | "review" | undefined;
+    env?: string[] | undefined;
+    sandbox?: {
+        language?: string | undefined;
+    } | undefined;
+}>;
+export type ToolJson = z.infer<typeof ToolJsonSchema>;
+/**
+ * A fully loaded custom tool ready for execution.
+ */
+export interface LoadedTool {
+    /** Tool name (from tool.json) */
+    name: string;
+    /** Description (from tool.json) */
+    description: string;
+    /** JSON Schema parameters (from tool.json) */
+    parameters: Record<string, unknown>;
+    /** Confirmation behavior */
+    confirm: false | true | 'review' | 'never';
+    /** Execution timeout in ms */
+    timeout: number;
+    /** Allowed environment variable names */
+    env: string[];
+    /** Absolute path to handler.ts */
+    handlerPath: string;
+    /** Directory containing the tool */
+    location: string;
+    /** Whether the tool has its own package.json */
+    hasPackageJson: boolean;
+    /** Whether the tool has a setup.sh script */
+    hasSetupScript: boolean;
+    /** Whether the tool has a requirements.txt */
+    hasRequirementsTxt: boolean;
+    /** Whether the tool has a Dockerfile */
+    hasDockerfile: boolean;
+    /** Sandbox language for hosted execution (default: 'typescript') */
+    sandboxLanguage: string;
+    /** Optional response shaping */
+    responseShaping?: z.infer<typeof ResponseShapingSchema>;
+}
+/**
+ * Context provided to custom tool handlers at execution time.
+ */
+export interface CustomToolContext {
+    /** Make an HTTP request through a configured connection */
+    request(connection: string, endpoint: string, params?: {
+        method?: string;
+        data?: unknown;
+        params?: Record<string, string>;
+    }): Promise<unknown>;
+    /** Execute a shell command (locally or in sandbox). Use to delegate to Python, Go, etc. */
+    exec(command: string, options?: {
+        cwd?: string;
+        timeout?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /** Read an environment variable (only if in the tool's env allowlist) */
+    env(name: string): string | undefined;
+    /** Log a message for debugging */
+    log(message: string): void;
+    /** Current user info */
+    user: {
+        roles: string[];
+        [key: string]: unknown;
+    };
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+}
+/**
+ * Definition object for a single-file tool handler.
+ *
+ * When a tool directory has no tool.json, the loader imports handler.ts
+ * and looks for either a ToolHandlerDefinition default export (from defineToolHandler)
+ * or individual named exports (description, parameters, handler, etc.).
+ */
+export interface ToolHandlerDefinition {
+    /** Marker so the loader knows this is a defineToolHandler result */
+    __toolHandler: true;
+    /** Description shown to the LLM */
+    description: string;
+    /** JSON Schema describing parameters */
+    parameters?: Record<string, unknown>;
+    /** Confirmation behavior */
+    confirm?: false | true | 'review' | 'never';
+    /** Execution timeout in ms */
+    timeout?: number;
+    /** Allowed environment variable names */
+    env?: string[];
+    /** The handler function */
+    handler: (params: Record<string, unknown>, ctx: CustomToolContext) => Promise<unknown>;
+}
+/**
+ * Helper for defining a typed tool handler in a single file.
+ *
+ * Usage in handler.ts:
+ * ```ts
+ * import { defineToolHandler } from '@amodalai/core'
+ *
+ * export default defineToolHandler({
+ *   description: 'Calculate weighted pipeline value',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { deal_ids: { type: 'array', items: { type: 'string' } } },
+ *     required: ['deal_ids'],
+ *   },
+ *   handler: async (params, ctx) => {
+ *     const deals = await ctx.request('crm', '/deals')
+ *     return { total: 42 }
+ *   },
+ * })
+ * ```
+ */
+export declare function defineToolHandler(def: Omit<ToolHandlerDefinition, '__toolHandler'>): ToolHandlerDefinition;
+/**
+ * Interface for executing custom tool handlers.
+ */
+export interface CustomToolExecutor {
+    execute(tool: LoadedTool, params: Record<string, unknown>, ctx: CustomToolContext): Promise<unknown>;
+    dispose?(): void;
+}
+/**
+ * Interface for executing shell commands.
+ */
+export interface CustomShellExecutor {
+    exec(command: string, timeout: number, signal: AbortSignal): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    dispose?(): void;
+}

package/dist/src/repo/tool-types.js

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { z } from 'zod';
+import { ResponseShapingSchema } from '../tools/http-tool-types.js';
+/** Regex for valid tool names — snake_case, starts with lowercase letter */
+export const TOOL_NAME_REGEX = /^[a-z][a-z0-9_]*$/;
+/**
+ * Schema for a tool.json file in the tools/ directory.
+ *
+ * `name` is optional — if omitted, the directory name is used.
+ * If provided, it must match the directory name.
+ */
+export const ToolJsonSchema = z.object({
+    /** Tool name — snake_case, starts with lowercase letter. Optional; defaults to directory name. */
+    name: z.string().regex(TOOL_NAME_REGEX, 'Tool name must be snake_case (lowercase letters, digits, underscores)').optional(),
+    /** Description shown to the LLM */
+    description: z.string().min(1),
+    /** JSON Schema describing the parameters the LLM should provide */
+    parameters: z.record(z.unknown()).default({}),
+    /** Confirmation behavior: false=no confirm, true=confirm before run, 'review'=show params, 'never'=hide from LLM */
+    confirm: z.union([z.literal(false), z.literal(true), z.literal('review'), z.literal('never')]).default(false),
+    /** Execution timeout in milliseconds */
+    timeout: z.number().int().positive().default(30000),
+    /** Environment variable names the handler is allowed to access */
+    env: z.array(z.string()).default([]),
+    /** Optional response shaping configuration */
+    responseShaping: ResponseShapingSchema.optional(),
+    /** Sandbox configuration for hosted execution */
+    sandbox: z.object({
+        /** Base language runtime for the sandbox (default: 'typescript') */
+        language: z.string().default('typescript'),
+    }).optional(),
+});
+/**
+ * Helper for defining a typed tool handler in a single file.
+ *
+ * Usage in handler.ts:
+ * ```ts
+ * import { defineToolHandler } from '@amodalai/core'
+ *
+ * export default defineToolHandler({
+ *   description: 'Calculate weighted pipeline value',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { deal_ids: { type: 'array', items: { type: 'string' } } },
+ *     required: ['deal_ids'],
+ *   },
+ *   handler: async (params, ctx) => {
+ *     const deals = await ctx.request('crm', '/deals')
+ *     return { total: 42 }
+ *   },
+ * })
+ * ```
+ */
+export function defineToolHandler(def) {
+    return { ...def, __toolHandler: true };
+}
+//# sourceMappingURL=tool-types.js.map

package/dist/src/repo/tool-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-types.js","sourceRoot":"","sources":["../../../src/repo/tool-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,qBAAqB,EAAC,MAAM,6BAA6B,CAAC;AAElE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,kGAAkG;IAClG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,eAAe,EAAE,uEAAuE,CAAC,CAAC,QAAQ,EAAE;IAC3H,mCAAmC;IACnC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9B,mEAAmE;IACnE,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IAC7C,oHAAoH;IACpH,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IAC7G,wCAAwC;IACxC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACnD,kEAAkE;IAClE,GAAG,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;IACpC,8CAA8C;IAC9C,eAAe,EAAE,qBAAqB,CAAC,QAAQ,EAAE;IACjD,iDAAiD;IACjD,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC;QAChB,oEAAoE;QACpE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,YAAY,CAAC;KAC3C,CAAC,CAAC,QAAQ,EAAE;CACd,CAAC,CAAC;AAwFH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAiD;IAEjD,OAAO,EAAC,GAAG,GAAG,EAAE,aAAa,EAAE,IAAI,EAAC,CAAC;AACvC,CAAC"}

package/dist/src/roles/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export { RoleDefinitionSchema, AutomationPermissionsSchema, ROLE_WILDCARD, type RoleDefinition, type AutomationPermissions, } from './role-types.js';
+export { isToolAllowedByRole, isSkillAllowedByRole, resolveActiveRole, } from './role-filter.js';

package/dist/src/roles/index.js

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export { RoleDefinitionSchema, AutomationPermissionsSchema, ROLE_WILDCARD, } from './role-types.js';
+export { isToolAllowedByRole, isSkillAllowedByRole, resolveActiveRole, } from './role-filter.js';
+//# sourceMappingURL=index.js.map

package/dist/src/roles/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/roles/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,GAGd,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC"}

package/dist/src/roles/role-filter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { type RoleDefinition } from './role-types.js';
+/**
+ * Checks whether a tool is allowed by the active role.
+ *
+ * Returns true (allowed) if:
+ * - No role is set (backward-compatible: all tools available)
+ * - The role's tools list contains the wildcard "*"
+ * - The role's tools list contains the tool name
+ */
+export declare function isToolAllowedByRole(toolName: string, role: RoleDefinition | undefined): boolean;
+/**
+ * Checks whether a skill is allowed by the active role.
+ *
+ * Returns true (allowed) if:
+ * - No role is set (backward-compatible: all skills available)
+ * - The role's skills list contains the wildcard "*"
+ * - The role's skills list contains the skill name
+ */
+export declare function isSkillAllowedByRole(skillName: string, role: RoleDefinition | undefined): boolean;
+/**
+ * Resolves the active role definition by name from a list of definitions.
+ *
+ * @param roleName - The name of the role to resolve (undefined = no role)
+ * @param definitions - Available role definitions
+ * @returns The matching RoleDefinition, or undefined if no role name given
+ * @throws Error if roleName is provided but not found in definitions
+ */
+export declare function resolveActiveRole(roleName: string | undefined, definitions: RoleDefinition[]): RoleDefinition | undefined;

package/dist/src/roles/role-filter.js

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { ROLE_WILDCARD } from './role-types.js';
+/**
+ * Checks whether a tool is allowed by the active role.
+ *
+ * Returns true (allowed) if:
+ * - No role is set (backward-compatible: all tools available)
+ * - The role's tools list contains the wildcard "*"
+ * - The role's tools list contains the tool name
+ */
+export function isToolAllowedByRole(toolName, role) {
+    if (!role)
+        return true;
+    if (role.tools.includes(ROLE_WILDCARD))
+        return true;
+    return role.tools.includes(toolName);
+}
+/**
+ * Checks whether a skill is allowed by the active role.
+ *
+ * Returns true (allowed) if:
+ * - No role is set (backward-compatible: all skills available)
+ * - The role's skills list contains the wildcard "*"
+ * - The role's skills list contains the skill name
+ */
+export function isSkillAllowedByRole(skillName, role) {
+    if (!role)
+        return true;
+    if (role.skills.includes(ROLE_WILDCARD))
+        return true;
+    return role.skills.includes(skillName);
+}
+/**
+ * Resolves the active role definition by name from a list of definitions.
+ *
+ * @param roleName - The name of the role to resolve (undefined = no role)
+ * @param definitions - Available role definitions
+ * @returns The matching RoleDefinition, or undefined if no role name given
+ * @throws Error if roleName is provided but not found in definitions
+ */
+export function resolveActiveRole(roleName, definitions) {
+    if (!roleName)
+        return undefined;
+    const role = definitions.find((d) => d.name === roleName);
+    if (!role) {
+        const available = definitions.map((d) => d.name).join(', ');
+        throw new Error(`Unknown role "${roleName}". Available roles: ${available || '(none)'}`);
+    }
+    return role;
+}
+//# sourceMappingURL=role-filter.js.map

package/dist/src/roles/role-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-filter.js","sourceRoot":"","sources":["../../../src/roles/role-filter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAuB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,IAAgC;IAEhC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAiB,EACjB,IAAgC;IAEhC,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC;QAAE,OAAO,IAAI,CAAC;IACrD,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAA4B,EAC5B,WAA6B;IAE7B,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC1D,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5D,MAAM,IAAI,KAAK,CACb,iBAAiB,QAAQ,uBAAuB,SAAS,IAAI,QAAQ,EAAE,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/roles/role-types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { z } from 'zod';
+/**
+ * Schema for automation permissions within a role.
+ */
+export declare const AutomationPermissionsSchema: z.ZodObject<{
+    /** Whether the role can view automation results */
+    can_view: z.ZodDefault<z.ZodBoolean>;
+    /** Whether the role can create new automations */
+    can_create: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    can_view: boolean;
+    can_create: boolean;
+}, {
+    can_view?: boolean | undefined;
+    can_create?: boolean | undefined;
+}>;
+/**
+ * Schema for a single role definition.
+ *
+ * A role determines which tools and skills a user can access.
+ * Tools requires at least one entry; use "*" for wildcard (allow all).
+ * Skills defaults to ["*"] (allow all) if not specified.
+ * Constraints is a generic record for domain-specific validation.
+ */
+export declare const RoleDefinitionSchema: z.ZodObject<{
+    /** Unique role name */
+    name: z.ZodString;
+    /** Allowed tool names — at least one required, "*" = wildcard */
+    tools: z.ZodArray<z.ZodString, "many">;
+    /** Allowed skill names — defaults to ["*"] (all) */
+    skills: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Automation permissions */
+    automations: z.ZodDefault<z.ZodObject<{
+        /** Whether the role can view automation results */
+        can_view: z.ZodDefault<z.ZodBoolean>;
+        /** Whether the role can create new automations */
+        can_create: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        can_view: boolean;
+        can_create: boolean;
+    }, {
+        can_view?: boolean | undefined;
+        can_create?: boolean | undefined;
+    }>>;
+    /** Domain-specific constraints (validated by business logic, not schema) */
+    constraints: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    tools: string[];
+    skills: string[];
+    automations: {
+        can_view: boolean;
+        can_create: boolean;
+    };
+    constraints: Record<string, unknown>;
+}, {
+    name: string;
+    tools: string[];
+    skills?: string[] | undefined;
+    automations?: {
+        can_view?: boolean | undefined;
+        can_create?: boolean | undefined;
+    } | undefined;
+    constraints?: Record<string, unknown> | undefined;
+}>;
+/** Inferred type for a role definition */
+export type RoleDefinition = z.infer<typeof RoleDefinitionSchema>;
+/** Inferred type for automation permissions */
+export type AutomationPermissions = z.infer<typeof AutomationPermissionsSchema>;
+/** Wildcard value that means "allow all" */
+export declare const ROLE_WILDCARD = "*";

package/dist/src/roles/role-types.js

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { z } from 'zod';
+/**
+ * Schema for automation permissions within a role.
+ */
+export const AutomationPermissionsSchema = z.object({
+    /** Whether the role can view automation results */
+    can_view: z.boolean().default(true),
+    /** Whether the role can create new automations */
+    can_create: z.boolean().default(false),
+});
+/**
+ * Schema for a single role definition.
+ *
+ * A role determines which tools and skills a user can access.
+ * Tools requires at least one entry; use "*" for wildcard (allow all).
+ * Skills defaults to ["*"] (allow all) if not specified.
+ * Constraints is a generic record for domain-specific validation.
+ */
+export const RoleDefinitionSchema = z.object({
+    /** Unique role name */
+    name: z.string().min(1),
+    /** Allowed tool names — at least one required, "*" = wildcard */
+    tools: z.array(z.string().min(1)).min(1),
+    /** Allowed skill names — defaults to ["*"] (all) */
+    skills: z.array(z.string().min(1)).default(['*']),
+    /** Automation permissions */
+    automations: AutomationPermissionsSchema.default({}),
+    /** Domain-specific constraints (validated by business logic, not schema) */
+    constraints: z.record(z.unknown()).default({}),
+});
+/** Wildcard value that means "allow all" */
+export const ROLE_WILDCARD = '*';
+//# sourceMappingURL=role-types.js.map

package/dist/src/roles/role-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-types.js","sourceRoot":"","sources":["../../../src/roles/role-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,mDAAmD;IACnD,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACnC,kDAAkD;IAClD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CACvC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,uBAAuB;IACvB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,iEAAiE;IACjE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxC,oDAAoD;IACpD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC;IACjD,6BAA6B;IAC7B,WAAW,EAAE,2BAA2B,CAAC,OAAO,CAAC,EAAE,CAAC;IACpD,4EAA4E;IAC5E,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC/C,CAAC,CAAC;AAQH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC"}

package/dist/src/runtime/connection-bridge.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { LoadedConnection } from '../repo/connection-types.js';
+import type { ConnectionsMap } from '../templates/connections.js';
+import type { AccessConfig } from '../repo/connection-schemas.js';
+/**
+ * Build a ConnectionsMap from LoadedConnections.
+ *
+ * Each entry has: base_url (from spec.baseUrl or spec.source), _request_config with auth details,
+ * and any injected credential values for {{VAR}} template resolution.
+ */
+export declare function buildConnectionsMap(connections: Map<string, LoadedConnection>, credentials?: Record<string, Record<string, string>>): ConnectionsMap;
+/**
+ * Build AccessConfig map keyed by connection name.
+ */
+export declare function buildAccessConfigs(connections: Map<string, LoadedConnection>): Map<string, AccessConfig>;

package/dist/src/runtime/connection-bridge.js

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Resolve an `env:VAR_NAME` reference to the actual value.
+ * Falls back to `{{VAR_NAME}}` template syntax for runtime resolution
+ * if the env var is not available at build time.
+ */
+function resolveEnvRef(value, credentials) {
+    if (!value.startsWith('env:')) {
+        return value;
+    }
+    const varName = value.slice(4);
+    // Check injected credentials first
+    if (credentials && credentials[varName] !== undefined) {
+        return credentials[varName];
+    }
+    // Fall back to process.env
+    const envVal = process.env[varName];
+    if (envVal !== undefined) {
+        return envVal;
+    }
+    // Leave as {{VAR}} template for runtime resolution
+    return `{{${varName}}}`;
+}
+/**
+ * Build a ConnectionsMap from LoadedConnections.
+ *
+ * Each entry has: base_url (from spec.baseUrl or spec.source), _request_config with auth details,
+ * and any injected credential values for {{VAR}} template resolution.
+ */
+export function buildConnectionsMap(connections, credentials) {
+    const result = {};
+    for (const [name, conn] of connections) {
+        const connCredentials = credentials?.[name];
+        const auth = buildAuthHeaders(conn, connCredentials);
+        // Use baseUrl if specified, otherwise fall back to source
+        const baseUrl = conn.spec.baseUrl ?? conn.spec.source;
+        const resolvedBaseUrl = resolveEnvRef(baseUrl, connCredentials);
+        const entry = {
+            base_url: resolvedBaseUrl,
+            _request_config: {
+                base_url_field: 'base_url',
+                auth,
+                default_headers: {},
+            },
+        };
+        // Merge credential values into the connection config so
+        // {{VAR}} templates in auth headers can be resolved at request time
+        if (connCredentials) {
+            for (const [key, val] of Object.entries(connCredentials)) {
+                entry[key] = val;
+            }
+        }
+        result[name] = entry;
+    }
+    return result;
+}
+/**
+ * Build AccessConfig map keyed by connection name.
+ */
+export function buildAccessConfigs(connections) {
+    const result = new Map();
+    for (const [name, conn] of connections) {
+        result.set(name, conn.access);
+    }
+    return result;
+}
+/**
+ * Build auth header entries from a connection's spec.auth configuration.
+ * Resolves env:VAR_NAME references in token values.
+ */
+function buildAuthHeaders(conn, credentials) {
+    const specAuth = conn.spec.auth;
+    if (!specAuth) {
+        return [];
+    }
+    const rawToken = specAuth.token ?? '';
+    const token = resolveEnvRef(rawToken, credentials);
+    if (specAuth.type === 'bearer') {
+        const header = specAuth.header ?? 'Authorization';
+        const prefix = specAuth.prefix ?? 'Bearer';
+        return [{ header, value_template: `${prefix} ${token}` }];
+    }
+    if (specAuth.type === 'api-key') {
+        const header = specAuth.header ?? 'X-API-Key';
+        return [{ header, value_template: token }];
+    }
+    if (specAuth.type === 'basic') {
+        // For basic auth, token should be the base64-encoded user:pass
+        // or two env:VAR refs separated by :
+        return [{ header: 'Authorization', value_template: `Basic ${token}` }];
+    }
+    if (specAuth.type === 'header') {
+        // Custom header auth (e.g., X-Shopify-Access-Token)
+        const header = specAuth.header ?? 'Authorization';
+        return [{ header, value_template: token }];
+    }
+    return [];
+}
+//# sourceMappingURL=connection-bridge.js.map

package/dist/src/runtime/connection-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-bridge.js","sourceRoot":"","sources":["../../../src/runtime/connection-bridge.ts"],"names":[],"mappings":"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"}

package/dist/src/runtime/context-compiler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { AmodalRepo } from '../repo/repo-types.js';
+import type { CompiledContext, SessionConfig } from './runtime-types.js';
+import type { TokenAllocator } from './token-allocator.js';
+/**
+ * Compiles system prompts from repo configuration and session state.
+ *
+ * Builds ordered, prioritized context sections and delegates to TokenAllocator
+ * for budget trimming.
+ */
+export declare class ContextCompiler {
+    private readonly repo;
+    private readonly allocator;
+    constructor(config: {
+        repo: AmodalRepo;
+        allocator: TokenAllocator;
+    });
+    /**
+     * Compile the full primary-agent system prompt.
+     */
+    compile(session: SessionConfig): CompiledContext;
+    /**
+     * Compile the explore sub-agent system prompt (subset of main).
+     */
+    compileExplore(session: SessionConfig): CompiledContext;
+    private section;
+    private buildConnectionsContent;
+    private buildSkillsContent;
+    private buildKnowledgeContent;
+    private buildResult;
+}