@polka-codes/core 0.10.13 → 0.10.16

package/dist/skills/tools/loadSkill.js

@@ -0,0 +1,86 @@
+// generated by polka.codes
+import { z } from 'zod';
+import { validateSkillReferences, validateSkillSecurity } from '../validation';
+/**
+ * Tool input parameters for loading a skill
+ */
+export const LoadSkillInputSchema = z.object({
+    skillName: z.string().describe('The name of the skill to load'),
+});
+/**
+ * Tool output for loading a skill
+ */
+export const LoadSkillOutputSchema = z.object({
+    success: z.boolean(),
+    skill: z
+        .object({
+        name: z.string(),
+        description: z.string(),
+        content: z.string(),
+        availableFiles: z.array(z.string()),
+    })
+        .optional(),
+    error: z.string().optional(),
+    warnings: z.array(z.string()).optional(),
+});
+/**
+ * Load a skill by name to access its instructions and resources
+ *
+ * This tool enables agents to autonomously load specialized knowledge
+ * and capabilities based on task context.
+ */
+export async function loadSkill(input, context) {
+    const { skillName } = input;
+    // Find the skill reference
+    const skillRef = context.availableSkills.find((s) => s.metadata.name === skillName);
+    if (!skillRef) {
+        return {
+            success: false,
+            error: `Skill '${skillName}' not found`,
+        };
+    }
+    try {
+        // Load the full skill
+        const skill = await context.loadSkill(skillName);
+        if (!skill) {
+            return {
+                success: false,
+                error: `Failed to load skill '${skillName}'`,
+            };
+        }
+        // Validate security
+        validateSkillSecurity(skill);
+        // Check for reference warnings
+        const warnings = validateSkillReferences(skill);
+        // Load the skill as active
+        context.activeSkill = skill;
+        context.skillLoadingHistory.push(skillName);
+        return {
+            success: true,
+            skill: {
+                name: skill.metadata.name,
+                description: skill.metadata.description,
+                content: skill.content,
+                availableFiles: Array.from(skill.files.keys()),
+            },
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            success: false,
+            error: `Failed to load skill '${skillName}': ${message}`,
+        };
+    }
+}
+/**
+ * Tool info for loadSkill (used in agent workflow)
+ */
+export const loadSkillToolInfo = {
+    name: 'loadSkill',
+    description: 'Load a skill by name to access its instructions and resources. Use this when you need specialized knowledge or capabilities for a specific task.',
+    parameters: LoadSkillInputSchema,
+    returns: LoadSkillOutputSchema,
+};
+//# sourceMappingURL=loadSkill.js.map

package/dist/skills/tools/loadSkill.js.map

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

package/dist/skills/tools/readSkillFile.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { SkillContext } from '../types';
+/**
+ * Tool input parameters for reading a skill file
+ */
+export declare const ReadSkillFileInputSchema: z.ZodObject<{
+    skillName: z.ZodString;
+    filename: z.ZodString;
+}, z.core.$strip>;
+export type ReadSkillFileInput = z.infer<typeof ReadSkillFileInputSchema>;
+/**
+ * Tool output for reading a skill file
+ */
+export declare const ReadSkillFileOutputSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    content: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ReadSkillFileOutput = z.infer<typeof ReadSkillFileOutputSchema>;
+/**
+ * Read a supporting file from a loaded skill
+ *
+ * This tool enables agents to access supporting files bundled with skills,
+ * such as reference documentation, examples, scripts, or templates.
+ * Files are returned as plain text content.
+ */
+export declare function readSkillFile(input: ReadSkillFileInput, context: SkillContext): Promise<ReadSkillFileOutput>;
+/**
+ * Tool info for readSkillFile (used in agent workflow)
+ */
+export declare const readSkillFileToolInfo: {
+    readonly name: "readSkillFile";
+    readonly description: "Read a supporting file from a skill. Use this to access reference documentation, examples, scripts, or templates bundled with a skill. First use loadSkill to see available files, then use this tool to read specific files.";
+    readonly parameters: z.ZodObject<{
+        skillName: z.ZodString;
+        filename: z.ZodString;
+    }, z.core.$strip>;
+    readonly returns: z.ZodObject<{
+        success: z.ZodBoolean;
+        content: z.ZodOptional<z.ZodString>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+};

package/dist/skills/tools/readSkillFile.js

@@ -0,0 +1,68 @@
+// generated by polka.codes
+import { z } from 'zod';
+/**
+ * Tool input parameters for reading a skill file
+ */
+export const ReadSkillFileInputSchema = z.object({
+    skillName: z.string().describe('The name of the skill'),
+    filename: z.string().describe('The name of the file to read (e.g., "reference.md", "scripts/helper.py")'),
+});
+/**
+ * Tool output for reading a skill file
+ */
+export const ReadSkillFileOutputSchema = z.object({
+    success: z.boolean(),
+    content: z.string().optional(),
+    error: z.string().optional(),
+});
+/**
+ * Read a supporting file from a loaded skill
+ *
+ * This tool enables agents to access supporting files bundled with skills,
+ * such as reference documentation, examples, scripts, or templates.
+ * Files are returned as plain text content.
+ */
+export async function readSkillFile(input, context) {
+    const { skillName, filename } = input;
+    // Check if active skill matches
+    let skill = context.activeSkill && context.activeSkill.metadata.name === skillName ? context.activeSkill : null;
+    // If not active, try to load it
+    if (!skill) {
+        try {
+            skill = await context.loadSkill(skillName);
+        }
+        catch (_error) {
+            // Ignore load error, will be handled by null check
+        }
+    }
+    if (!skill) {
+        return {
+            success: false,
+            error: `Skill '${skillName}' not found or could not be loaded. Use loadSkill first.`,
+        };
+    }
+    // Check if file exists in skill
+    if (!skill.files.has(filename)) {
+        const availableFiles = Array.from(skill.files.keys()).sort();
+        return {
+            success: false,
+            error: `File '${filename}' not found in skill '${skillName}'. Available files: ${availableFiles.join(', ') || 'none'}`,
+        };
+    }
+    // Return file content
+    const content = skill.files.get(filename);
+    return {
+        success: true,
+        content,
+    };
+}
+/**
+ * Tool info for readSkillFile (used in agent workflow)
+ */
+export const readSkillFileToolInfo = {
+    name: 'readSkillFile',
+    description: 'Read a supporting file from a skill. Use this to access reference documentation, examples, scripts, or templates bundled with a skill. First use loadSkill to see available files, then use this tool to read specific files.',
+    parameters: ReadSkillFileInputSchema,
+    returns: ReadSkillFileOutputSchema,
+};
+//# sourceMappingURL=readSkillFile.js.map

package/dist/skills/tools/readSkillFile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readSkillFile.js","sourceRoot":"","sources":["../../../src/skills/tools/readSkillFile.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uBAAuB,CAAC;IACvD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0EAA0E,CAAC;CAC1G,CAAC,CAAA;AAIF;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAA;AAIF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAyB,EAAE,OAAqB;IAClF,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAA;IAErC,gCAAgC;IAChC,IAAI,KAAK,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAA;IAE/G,gCAAgC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAA;QAC5C,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,mDAAmD;QACrD,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,UAAU,SAAS,0DAA0D;SACrF,CAAA;IACH,CAAC;IAED,gCAAgC;IAChC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/B,MAAM,cAAc,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;QAC5D,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,SAAS,QAAQ,yBAAyB,SAAS,uBAAuB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,EAAE;SACvH,CAAA;IACH,CAAC;IAED,sBAAsB;IACtB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;IAEzC,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO;KACR,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,IAAI,EAAE,eAAe;IACrB,WAAW,EACT,+NAA+N;IACjO,UAAU,EAAE,wBAAwB;IACpC,OAAO,EAAE,yBAAyB;CAC1B,CAAA"}

package/dist/skills/types.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+/**
+ * Zod schema for skill metadata (YAML frontmatter in SKILL.md)
+ */
+export declare const skillMetadataSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type SkillMetadata = z.infer<typeof skillMetadataSchema>;
+/**
+ * Represents a reference to a discovered skill (metadata only)
+ */
+export interface SkillReference {
+    /**
+     * Parsed metadata from SKILL.md frontmatter
+     */
+    metadata: SkillMetadata;
+    /**
+     * Absolute path to the skill directory on disk
+     */
+    path: string;
+    /**
+     * Where the skill was loaded from
+     */
+    source: 'personal' | 'project' | 'plugin';
+}
+/**
+ * Represents a loaded Agent Skill with all its content
+ */
+export interface Skill extends SkillReference {
+    /**
+     * Main instructions content (SKILL.md without frontmatter)
+     */
+    content: string;
+    /**
+     * Additional files bundled with the skill
+     * Key is relative path from skill directory (e.g., "reference.md", "scripts/helper.py")
+     * Value is file content
+     */
+    files: Map<string, string>;
+}
+/**
+ * Context object passed to agents and tools for skill operations
+ */
+export interface SkillContext {
+    /**
+     * Currently active/loaded skill (if any)
+     */
+    activeSkill: Skill | null;
+    /**
+     * All available skills discovered from all sources (metadata only)
+     */
+    availableSkills: SkillReference[];
+    /**
+     * History of skills loaded during the session (for debugging/telemetry)
+     */
+    skillLoadingHistory: string[];
+    /**
+     * Load a skill by name
+     */
+    loadSkill: (name: string) => Promise<Skill | null>;
+}
+/**
+ * Error thrown when skill discovery fails
+ *
+ * Note: This error has a custom `path` property that is accessed by callers.
+ * Keeping as a class since the error factory doesn't support custom properties.
+ */
+export declare class SkillDiscoveryError extends Error {
+    path: string;
+    constructor(message: string, path: string);
+}
+/**
+ * Error thrown when skill validation fails
+ *
+ * Note: This error has a custom `path` property that is accessed by callers.
+ * Keeping as a class since the error factory doesn't support custom properties.
+ */
+export declare class SkillValidationError extends Error {
+    path: string;
+    constructor(message: string, path: string);
+}

package/dist/skills/types.js

@@ -0,0 +1,42 @@
+// generated by polka.codes
+import { z } from 'zod';
+/**
+ * Zod schema for skill metadata (YAML frontmatter in SKILL.md)
+ */
+export const skillMetadataSchema = z.object({
+    name: z
+        .string()
+        .regex(/^[a-z0-9-]+$/, 'Skill name must be lowercase letters, numbers, and hyphens')
+        .max(64, 'Skill name must be at most 64 characters'),
+    description: z.string().max(1024, 'Description must be at most 1024 characters'),
+    allowedTools: z.array(z.string()).optional(),
+});
+/**
+ * Error thrown when skill discovery fails
+ *
+ * Note: This error has a custom `path` property that is accessed by callers.
+ * Keeping as a class since the error factory doesn't support custom properties.
+ */
+export class SkillDiscoveryError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'SkillDiscoveryError';
+    }
+}
+/**
+ * Error thrown when skill validation fails
+ *
+ * Note: This error has a custom `path` property that is accessed by callers.
+ * Keeping as a class since the error factory doesn't support custom properties.
+ */
+export class SkillValidationError extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'SkillValidationError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/skills/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/skills/types.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC1C,IAAI,EAAE,CAAC;SACJ,MAAM,EAAE;SACR,KAAK,CAAC,cAAc,EAAE,4DAA4D,CAAC;SACnF,GAAG,CAAC,EAAE,EAAE,0CAA0C,CAAC;IACtD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,6CAA6C,CAAC;IAChF,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAA;AAkEF;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAGnC;IAFT,YACE,OAAe,EACR,IAAY;QAEnB,KAAK,CAAC,OAAO,CAAC,CAAA;QAFP,SAAI,GAAJ,IAAI,CAAQ;QAGnB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAGpC;IAFT,YACE,OAAe,EACR,IAAY;QAEnB,KAAK,CAAC,OAAO,CAAC,CAAA;QAFP,SAAI,GAAJ,IAAI,CAAQ;QAGnB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACpC,CAAC;CACF"}

package/dist/skills/validation.d.ts

@@ -0,0 +1,30 @@
+import type { Skill } from './types';
+/**
+ * Validate a skill's security constraints
+ *
+ * @throws {SkillValidationError} if validation fails
+ */
+export declare function validateSkillSecurity(skill: Skill): void;
+/**
+ * Validate file references in skill content
+ *
+ * Warns about external references and absolute paths
+ */
+export declare function validateSkillReferences(skill: Skill): string[];
+/**
+ * Validate a skill's metadata
+ * Note: Zod already validates name format, max length, and description max length
+ * This function only validates requirements not covered by Zod
+ */
+export declare function validateSkillMetadata(skill: Skill): string[];
+/**
+ * Get file statistics for a skill
+ */
+export declare function getSkillStats(skill: Skill): {
+    totalSize: number;
+    fileCount: number;
+    largestFile: {
+        name: string;
+        size: number;
+    };
+};

package/dist/skills/validation.js

@@ -0,0 +1,133 @@
+import { join, normalize } from 'node:path';
+import { SKILL_LIMITS, SUSPICIOUS_PATTERNS } from './constants';
+import { SkillValidationError } from './types';
+/**
+ * Validate a skill's security constraints
+ *
+ * @throws {SkillValidationError} if validation fails
+ */
+export function validateSkillSecurity(skill) {
+    const { MAX_FILE_SIZE, MAX_SKILL_SIZE } = SKILL_LIMITS;
+    // Check file sizes
+    let totalSize = 0;
+    // Check main content size
+    const contentSize = Buffer.byteLength(skill.content, 'utf8');
+    if (contentSize > MAX_FILE_SIZE) {
+        throw new SkillValidationError(`SKILL.md content exceeds size limit (${contentSize} > ${MAX_FILE_SIZE})`, join(skill.path, 'SKILL.md'));
+    }
+    totalSize += contentSize;
+    // Check supporting file sizes
+    for (const [filename, content] of skill.files) {
+        const fileSize = Buffer.byteLength(content, 'utf8');
+        if (fileSize > MAX_FILE_SIZE) {
+            throw new SkillValidationError(`File ${filename} exceeds size limit (${fileSize} > ${MAX_FILE_SIZE})`, join(skill.path, filename));
+        }
+        totalSize += fileSize;
+    }
+    // Check total skill size
+    if (totalSize > MAX_SKILL_SIZE) {
+        throw new SkillValidationError(`Skill total size exceeds limit (${totalSize} > ${MAX_SKILL_SIZE})`, skill.path);
+    }
+    // Check for suspicious patterns in all files
+    validateContentSecurity(skill.content, skill.path);
+    for (const [filename, content] of skill.files) {
+        validateContentSecurity(content, join(skill.path, filename));
+    }
+}
+/**
+ * Validate content for suspicious patterns
+ */
+function validateContentSecurity(content, path) {
+    for (const pattern of SUSPICIOUS_PATTERNS) {
+        if (pattern.test(content)) {
+            throw new SkillValidationError('Suspicious content detected', path);
+        }
+    }
+}
+/**
+ * Validate file references in skill content
+ *
+ * Warns about external references and absolute paths
+ */
+export function validateSkillReferences(skill) {
+    const warnings = [];
+    // Check for external network references
+    const externalRefs = skill.content.match(/https?:\/\/[^\s\])]+/g) || [];
+    if (externalRefs.length > 0 && !skill.metadata.description.toLowerCase().includes('external')) {
+        warnings.push(`Skill '${skill.metadata.name}' contains external references. Consider adding 'external' to description for transparency.`);
+    }
+    // Check for absolute paths in file references (markdown links and code)
+    // Only look in code blocks and markdown links to avoid false positives
+    const codeBlocks = skill.content.match(/```[\s\S]*?```/g) || [];
+    for (const block of codeBlocks) {
+        // Look for absolute paths starting with / but not common exceptions
+        const pathsInCode = block.match(/\/[a-zA-Z][\w./-]*/g) || [];
+        for (const path of pathsInCode) {
+            // Skip system paths and common non-filesystem patterns
+            if (!path.startsWith('/dev') && !path.startsWith('/proc') && !path.startsWith('/sys') && !path.startsWith('//')) {
+                warnings.push(`Skill '${skill.metadata.name}' contains possible absolute path '${path}'. Use relative paths instead.`);
+            }
+        }
+    }
+    // Validate that referenced files exist
+    // Use a safe regex that extracts markdown link URLs
+    // Matches [text](url) where url can contain spaces but not unbalanced parentheses
+    // This prevents ReDoS vulnerabilities while supporting common markdown link patterns
+    const linkRegex = /\[[^\]]+\]\(([^)]+(?:\s+[^)]+)*)\)/g;
+    let match;
+    match = linkRegex.exec(skill.content);
+    while (match !== null) {
+        const filepath = match[1];
+        match = linkRegex.exec(skill.content);
+        // Skip external URLs and anchor links
+        if (filepath.startsWith('http://') || filepath.startsWith('https://') || filepath.startsWith('#')) {
+            continue;
+        }
+        // Normalize the filepath to handle ./prefix and redundant slashes
+        // Then convert backslashes to forward slashes for consistent lookup
+        // (discovery.ts always uses forward slashes in map keys)
+        const normalizedPath = normalize(filepath)
+            .replace(/^\.?\//, '')
+            .replace(/\\/g, '/');
+        // Check if referenced file exists
+        if (!skill.files.has(normalizedPath)) {
+            warnings.push(`Referenced file not found: ${filepath}`);
+        }
+    }
+    return warnings;
+}
+/**
+ * Validate a skill's metadata
+ * Note: Zod already validates name format, max length, and description max length
+ * This function only validates requirements not covered by Zod
+ */
+export function validateSkillMetadata(skill) {
+    const errors = [];
+    // Check that description is meaningful (Zod doesn't validate min length)
+    if (skill.metadata.description.length < 20) {
+        errors.push(`Description too short: ${skill.metadata.description.length} < 20`);
+    }
+    return errors;
+}
+/**
+ * Get file statistics for a skill
+ */
+export function getSkillStats(skill) {
+    let totalSize = Buffer.byteLength(skill.content, 'utf8');
+    let largestFile = { name: 'SKILL.md', size: totalSize };
+    let fileCount = 1; // SKILL.md
+    for (const [name, content] of skill.files) {
+        const size = Buffer.byteLength(content, 'utf8');
+        totalSize += size;
+        fileCount++;
+        if (size > largestFile.size) {
+            largestFile = { name, size };
+        }
+    }
+    return {
+        totalSize,
+        fileCount,
+        largestFile,
+    };
+}
+//# sourceMappingURL=validation.js.map

package/dist/skills/validation.js.map

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

package/dist/tool.d.ts

@@ -0,0 +1,51 @@
+import type { JSONValue } from '@ai-sdk/provider';
+import type { z } from 'zod';
+export type ToolParameterValue = string | {
+    [key: string]: ToolParameterValue;
+} | ToolParameterValue[];
+export type ToolParameter = {
+    name: string;
+    description: string;
+    required: boolean;
+    usageValue?: string;
+    allowMultiple?: boolean;
+    children?: ToolParameter[];
+};
+export type ToolInfo = {
+    name: string;
+    description: string;
+    parameters: z.ZodObject<any>;
+};
+export type FullToolInfo = ToolInfo & {
+    handler: ToolHandler<ToolInfo, any>;
+};
+export type ToolResponseResultMedia = {
+    type: 'media';
+    data: string;
+    mediaType: string;
+    url: string;
+};
+export type ToolResponseResult = {
+    type: 'text';
+    value: string;
+} | {
+    type: 'json';
+    value: JSONValue;
+} | {
+    type: 'error-text';
+    value: string;
+} | {
+    type: 'error-json';
+    value: JSONValue;
+} | {
+    type: 'content';
+    value: Array<{
+        type: 'text';
+        text: string;
+    } | ToolResponseResultMedia>;
+};
+export type ToolResponse = {
+    success: boolean;
+    message: ToolResponseResult;
+};
+export type ToolHandler<_T, P> = (provider: P, args: Partial<Record<string, ToolParameterValue>>) => Promise<ToolResponse>;

package/dist/tool.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":""}

package/dist/tools/askFollowupQuestion.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import type { ToolHandler } from '../tool';
+import type { InteractionProvider } from './provider';
+export declare const toolInfo: {
+    readonly name: "askFollowupQuestion";
+    readonly description: "Call this when vital details are missing. Pose each follow-up as one direct, unambiguous question. If it speeds the reply, add up to five short, mutually-exclusive answer options. Group any related questions in the same call to avoid a back-and-forth chain.";
+    readonly parameters: z.ZodObject<{
+        questions: z.ZodArray<z.ZodObject<{
+            prompt: z.ZodString;
+            options: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+export declare const handler: ToolHandler<typeof toolInfo, InteractionProvider>;
+declare const _default: {
+    handler: ToolHandler<{
+        readonly name: "askFollowupQuestion";
+        readonly description: "Call this when vital details are missing. Pose each follow-up as one direct, unambiguous question. If it speeds the reply, add up to five short, mutually-exclusive answer options. Group any related questions in the same call to avoid a back-and-forth chain.";
+        readonly parameters: z.ZodObject<{
+            questions: z.ZodArray<z.ZodObject<{
+                prompt: z.ZodString;
+                options: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+    }, InteractionProvider>;
+    name: "askFollowupQuestion";
+    description: "Call this when vital details are missing. Pose each follow-up as one direct, unambiguous question. If it speeds the reply, add up to five short, mutually-exclusive answer options. Group any related questions in the same call to avoid a back-and-forth chain.";
+    parameters: z.ZodObject<{
+        questions: z.ZodArray<z.ZodObject<{
+            prompt: z.ZodString;
+            options: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+};
+export default _default;