@revealui/ai 0.1.0

package/dist/templates/prompt-spec.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Prompt Specification Template
+ *
+ * Zod-validated schema for prompt templates. Every prompt must declare
+ * its variables, guardrails, security constraints, and include at least
+ * one example. This prevents prompt injection, enforces output quality,
+ * and ensures all prompts are documented and testable.
+ */
+import { z } from 'zod';
+export declare const PromptVariableSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        object: "object";
+        array: "array";
+    }>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    description: z.ZodString;
+    defaultValue: z.ZodOptional<z.ZodUnknown>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    validationPattern: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PromptVariable = z.infer<typeof PromptVariableSchema>;
+export declare const PromptGuardrailsSchema: z.ZodObject<{
+    maxInputTokens: z.ZodDefault<z.ZodNumber>;
+    maxOutputTokens: z.ZodDefault<z.ZodNumber>;
+    prohibitedContent: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    requiredContent: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    temperature: z.ZodDefault<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+    stopSequences: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type PromptGuardrails = z.infer<typeof PromptGuardrailsSchema>;
+export declare const PromptSecuritySchema: z.ZodObject<{
+    allowCodeExecution: z.ZodDefault<z.ZodBoolean>;
+    allowExternalUrls: z.ZodDefault<z.ZodBoolean>;
+    piiHandling: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        mask: "mask";
+        redact: "redact";
+    }>>;
+    injectionProtection: z.ZodDefault<z.ZodBoolean>;
+    sanitizeVariables: z.ZodDefault<z.ZodBoolean>;
+    rateLimitPerMinute: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PromptSecurity = z.infer<typeof PromptSecuritySchema>;
+export declare const PromptExampleSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    expectedOutput: z.ZodString;
+}, z.core.$strip>;
+export type PromptExample = z.infer<typeof PromptExampleSchema>;
+export declare const PromptSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    template: z.ZodString;
+    variables: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            object: "object";
+            array: "array";
+        }>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodString;
+        defaultValue: z.ZodOptional<z.ZodUnknown>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        validationPattern: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    guardrails: z.ZodObject<{
+        maxInputTokens: z.ZodDefault<z.ZodNumber>;
+        maxOutputTokens: z.ZodDefault<z.ZodNumber>;
+        prohibitedContent: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        requiredContent: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        temperature: z.ZodDefault<z.ZodNumber>;
+        topP: z.ZodOptional<z.ZodNumber>;
+        stopSequences: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>;
+    security: z.ZodObject<{
+        allowCodeExecution: z.ZodDefault<z.ZodBoolean>;
+        allowExternalUrls: z.ZodDefault<z.ZodBoolean>;
+        piiHandling: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            mask: "mask";
+            redact: "redact";
+        }>>;
+        injectionProtection: z.ZodDefault<z.ZodBoolean>;
+        sanitizeVariables: z.ZodDefault<z.ZodBoolean>;
+        rateLimitPerMinute: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    examples: z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        expectedOutput: z.ZodString;
+    }, z.core.$strip>>;
+    author: z.ZodString;
+    category: z.ZodString;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+}, z.core.$strip>;
+export type PromptSpec = z.infer<typeof PromptSpecSchema>;
+/**
+ * Validate a prompt specification.
+ * Returns the validated spec or throws with detailed error messages.
+ */
+export declare function validatePromptSpec(input: unknown): PromptSpec;
+/**
+ * Safely validate a prompt specification.
+ */
+export declare function safeValidatePromptSpec(input: unknown): {
+    success: true;
+    data: PromptSpec;
+} | {
+    success: false;
+    errors: string[];
+};
+/**
+ * Create a prompt spec with sensible defaults.
+ */
+export declare function createPromptSpec(partial: Pick<PromptSpec, 'id' | 'name' | 'version' | 'description' | 'template' | 'author' | 'category' | 'examples'> & Partial<PromptSpec>): PromptSpec;
+/**
+ * Render a prompt template with variable values.
+ * Validates variables against the spec before rendering.
+ * Applies injection protection if enabled.
+ */
+export declare function renderPromptTemplate(spec: PromptSpec, values: Record<string, unknown>): {
+    success: true;
+    rendered: string;
+} | {
+    success: false;
+    errors: string[];
+};
+//# sourceMappingURL=prompt-spec.d.ts.map

package/dist/templates/prompt-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-spec.d.ts","sourceRoot":"","sources":["../../src/templates/prompt-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;iBAe/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAIjE,eAAO,MAAM,sBAAsB;;;;;;;;iBAejC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAIrE,eAAO,MAAM,oBAAoB;;;;;;;;;;;iBAa/B,CAAA;AAEF,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAA;AAIjE,eAAO,MAAM,mBAAmB;;;;iBAO9B,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAI/D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiC3B,CAAA;AAEF,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAA;AAIzD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAE7D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAS5E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,IAAI,CACX,UAAU,EACV,IAAI,GAAG,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAC5F,GACC,OAAO,CAAC,UAAU,CAAC,GACpB,UAAU,CAWZ;AAID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CA4E5E"}

package/dist/templates/prompt-spec.js

@@ -0,0 +1,210 @@
+/**
+ * Prompt Specification Template
+ *
+ * Zod-validated schema for prompt templates. Every prompt must declare
+ * its variables, guardrails, security constraints, and include at least
+ * one example. This prevents prompt injection, enforces output quality,
+ * and ensures all prompts are documented and testable.
+ */
+import { z } from 'zod';
+// ─── Prompt Variable Schema ─────────────────────────────────────────────────
+export const PromptVariableSchema = z.object({
+    /** Variable name (used in template as {{name}}) */
+    name: z.string().min(1).max(50),
+    /** Variable type for validation */
+    type: z.enum(['string', 'number', 'boolean', 'array', 'object']),
+    /** Whether this variable is required */
+    required: z.boolean().default(true),
+    /** What this variable represents */
+    description: z.string().min(1),
+    /** Default value if not provided */
+    defaultValue: z.unknown().optional(),
+    /** Maximum length for string variables */
+    maxLength: z.number().int().positive().optional(),
+    /** Regex pattern the value must match (strings only) */
+    validationPattern: z.string().optional(),
+});
+// ─── Prompt Guardrails ──────────────────────────────────────────────────────
+export const PromptGuardrailsSchema = z.object({
+    /** Maximum tokens in the rendered prompt (input) */
+    maxInputTokens: z.number().int().positive().default(4096),
+    /** Maximum tokens in the LLM response (output) */
+    maxOutputTokens: z.number().int().positive().default(4096),
+    /** Strings/patterns that MUST NOT appear in the prompt or output */
+    prohibitedContent: z.array(z.string()).default([]),
+    /** Strings that MUST appear in the rendered prompt */
+    requiredContent: z.array(z.string()).default([]),
+    /** LLM temperature setting */
+    temperature: z.number().min(0).max(2).default(0.7),
+    /** LLM top-p setting */
+    topP: z.number().min(0).max(1).optional(),
+    /** Stop sequences */
+    stopSequences: z.array(z.string()).default([]),
+});
+// ─── Prompt Security ────────────────────────────────────────────────────────
+export const PromptSecuritySchema = z.object({
+    /** Whether the prompt output may contain executable code */
+    allowCodeExecution: z.boolean().default(false),
+    /** Whether the prompt may reference external URLs */
+    allowExternalUrls: z.boolean().default(false),
+    /** How PII in variables is handled */
+    piiHandling: z.enum(['none', 'mask', 'redact']).default('none'),
+    /** Enable prompt injection protection (escaping, sandboxing) */
+    injectionProtection: z.boolean().default(true),
+    /** Whether variable values are sanitized before template interpolation */
+    sanitizeVariables: z.boolean().default(true),
+    /** Maximum number of times this prompt can be called per minute */
+    rateLimitPerMinute: z.number().int().positive().optional(),
+});
+// ─── Prompt Example Schema ──────────────────────────────────────────────────
+export const PromptExampleSchema = z.object({
+    /** What this example demonstrates */
+    description: z.string().optional(),
+    /** Input variable values */
+    input: z.record(z.string(), z.unknown()),
+    /** Expected output (for testing and documentation) */
+    expectedOutput: z.string(),
+});
+// ─── Full Prompt Specification ──────────────────────────────────────────────
+export const PromptSpecSchema = z.object({
+    /** Unique prompt identifier */
+    id: z.string().min(1).max(100),
+    /** Human-readable prompt name */
+    name: z.string().min(1).max(100),
+    /** Semantic version */
+    version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Must be semver (e.g., 1.0.0)'),
+    /** What this prompt template does */
+    description: z.string().min(10).max(500),
+    /** The prompt template string (variables as {{name}}) */
+    template: z.string().min(10),
+    /** Declared variables used in the template */
+    variables: z.array(PromptVariableSchema).default([]),
+    /** Behavioral guardrails */
+    guardrails: PromptGuardrailsSchema,
+    /** Security constraints */
+    security: PromptSecuritySchema,
+    /** Examples — at least one required for documentation and testing */
+    examples: z.array(PromptExampleSchema).min(1, 'At least one example is required'),
+    /** Who created this prompt */
+    author: z.string().min(1),
+    /** Category (e.g., 'summarization', 'code-generation', 'analysis') */
+    category: z.string().min(1),
+    /** Tags for search/filtering */
+    tags: z.array(z.string()).default([]),
+    /** When this spec was created */
+    createdAt: z.date(),
+    /** When this spec was last updated */
+    updatedAt: z.date(),
+});
+// ─── Validation ─────────────────────────────────────────────────────────────
+/**
+ * Validate a prompt specification.
+ * Returns the validated spec or throws with detailed error messages.
+ */
+export function validatePromptSpec(input) {
+    return PromptSpecSchema.parse(input);
+}
+/**
+ * Safely validate a prompt specification.
+ */
+export function safeValidatePromptSpec(input) {
+    const result = PromptSpecSchema.safeParse(input);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return {
+        success: false,
+        errors: result.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`),
+    };
+}
+/**
+ * Create a prompt spec with sensible defaults.
+ */
+export function createPromptSpec(partial) {
+    const now = new Date();
+    return PromptSpecSchema.parse({
+        variables: [],
+        guardrails: {},
+        security: {},
+        tags: [],
+        createdAt: now,
+        updatedAt: now,
+        ...partial,
+    });
+}
+// ─── Template Rendering ─────────────────────────────────────────────────────
+/**
+ * Render a prompt template with variable values.
+ * Validates variables against the spec before rendering.
+ * Applies injection protection if enabled.
+ */
+export function renderPromptTemplate(spec, values) {
+    const errors = [];
+    // Validate required variables are present
+    for (const variable of spec.variables) {
+        if (variable.required && !(variable.name in values)) {
+            if (variable.defaultValue === undefined) {
+                errors.push(`Missing required variable: ${variable.name}`);
+            }
+        }
+    }
+    if (errors.length > 0) {
+        return { success: false, errors };
+    }
+    // Build resolved values (with defaults)
+    const resolved = {};
+    for (const variable of spec.variables) {
+        const value = values[variable.name] ?? variable.defaultValue;
+        let stringValue = String(value ?? '');
+        // Sanitize if injection protection is enabled
+        if (spec.security.sanitizeVariables) {
+            stringValue = sanitizeForTemplate(stringValue);
+        }
+        // Validate max length
+        if (variable.maxLength && stringValue.length > variable.maxLength) {
+            errors.push(`Variable "${variable.name}" exceeds max length (${stringValue.length} > ${variable.maxLength})`);
+        }
+        // Validate pattern
+        if (variable.validationPattern) {
+            const regex = new RegExp(variable.validationPattern);
+            if (!regex.test(stringValue)) {
+                errors.push(`Variable "${variable.name}" does not match pattern: ${variable.validationPattern}`);
+            }
+        }
+        resolved[variable.name] = stringValue;
+    }
+    if (errors.length > 0) {
+        return { success: false, errors };
+    }
+    // Render template
+    let rendered = spec.template;
+    for (const [name, value] of Object.entries(resolved)) {
+        rendered = rendered.replaceAll(`{{${name}}}`, value);
+    }
+    // Check prohibited content
+    for (const pattern of spec.guardrails.prohibitedContent) {
+        if (rendered.includes(pattern)) {
+            errors.push(`Rendered prompt contains prohibited content: "${pattern}"`);
+        }
+    }
+    // Check required content
+    for (const required of spec.guardrails.requiredContent) {
+        if (!rendered.includes(required)) {
+            errors.push(`Rendered prompt missing required content: "${required}"`);
+        }
+    }
+    if (errors.length > 0) {
+        return { success: false, errors };
+    }
+    return { success: true, rendered };
+}
+/**
+ * Basic sanitization to prevent prompt injection via variables.
+ * Escapes common injection patterns.
+ */
+function sanitizeForTemplate(input) {
+    return input
+        .replace(/\{\{/g, '{ {') // Prevent nested template injection
+        .replace(/\}\}/g, '} }')
+        .replace(/\n{3,}/g, '\n\n'); // Collapse excessive newlines
+}

package/dist/templates/skill-spec.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Skill Specification Template
+ *
+ * Zod-validated schema for agent skills. Every skill must declare its
+ * inputs/outputs, required permissions, security constraints, and include
+ * at least one test case. This ensures quality and security before any
+ * skill is activated in production.
+ */
+import { z } from 'zod';
+export declare const SkillPermissionsSchema: z.ZodObject<{
+    requiredTools: z.ZodArray<z.ZodString>;
+    requiredMemoryAccess: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        semantic: "semantic";
+        working: "working";
+        episodic: "episodic";
+    }>>>;
+    networkRequired: z.ZodDefault<z.ZodBoolean>;
+    estimatedTokenCost: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SkillPermissions = z.infer<typeof SkillPermissionsSchema>;
+export declare const SkillSecuritySchema: z.ZodObject<{
+    sanitizeInput: z.ZodDefault<z.ZodBoolean>;
+    sanitizeOutput: z.ZodDefault<z.ZodBoolean>;
+    maxExecutionTimeMs: z.ZodDefault<z.ZodNumber>;
+    retryable: z.ZodDefault<z.ZodBoolean>;
+    maxRetries: z.ZodDefault<z.ZodNumber>;
+    handlesPII: z.ZodDefault<z.ZodBoolean>;
+    dataRetention: z.ZodDefault<z.ZodEnum<{
+        none: "none";
+        session: "session";
+        persistent: "persistent";
+    }>>;
+}, z.core.$strip>;
+export type SkillSecurity = z.infer<typeof SkillSecuritySchema>;
+export declare const SkillTestCaseSchema: z.ZodObject<{
+    description: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    expectedOutput: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    shouldPass: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SkillTestCase = z.infer<typeof SkillTestCaseSchema>;
+export declare const SkillSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    version: z.ZodString;
+    description: z.ZodString;
+    usage: z.ZodOptional<z.ZodString>;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    outputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    permissions: z.ZodObject<{
+        requiredTools: z.ZodArray<z.ZodString>;
+        requiredMemoryAccess: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            semantic: "semantic";
+            working: "working";
+            episodic: "episodic";
+        }>>>;
+        networkRequired: z.ZodDefault<z.ZodBoolean>;
+        estimatedTokenCost: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    security: z.ZodObject<{
+        sanitizeInput: z.ZodDefault<z.ZodBoolean>;
+        sanitizeOutput: z.ZodDefault<z.ZodBoolean>;
+        maxExecutionTimeMs: z.ZodDefault<z.ZodNumber>;
+        retryable: z.ZodDefault<z.ZodBoolean>;
+        maxRetries: z.ZodDefault<z.ZodNumber>;
+        handlesPII: z.ZodDefault<z.ZodBoolean>;
+        dataRetention: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            session: "session";
+            persistent: "persistent";
+        }>>;
+    }, z.core.$strip>;
+    testCases: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+        input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        expectedOutput: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        shouldPass: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    author: z.ZodString;
+    license: z.ZodDefault<z.ZodString>;
+    category: z.ZodString;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    createdAt: z.ZodDate;
+    updatedAt: z.ZodDate;
+}, z.core.$strip>;
+export type SkillSpec = z.infer<typeof SkillSpecSchema>;
+/**
+ * Validate a skill specification.
+ * Returns the validated spec or throws with detailed error messages.
+ */
+export declare function validateSkillSpec(input: unknown): SkillSpec;
+/**
+ * Safely validate a skill specification.
+ */
+export declare function safeValidateSkillSpec(input: unknown): {
+    success: true;
+    data: SkillSpec;
+} | {
+    success: false;
+    errors: string[];
+};
+/**
+ * Create a skill spec with sensible defaults.
+ */
+export declare function createSkillSpec(partial: Pick<SkillSpec, 'id' | 'name' | 'version' | 'description' | 'author' | 'category' | 'inputSchema' | 'outputSchema' | 'testCases'> & Partial<SkillSpec>): SkillSpec;
+//# sourceMappingURL=skill-spec.d.ts.map

package/dist/templates/skill-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-spec.d.ts","sourceRoot":"","sources":["../../src/templates/skill-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAIvB,eAAO,MAAM,sBAAsB;;;;;;;;;iBASjC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAIrE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;iBAe9B,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAI/D,eAAO,MAAM,mBAAmB;;;;;iBAS9B,CAAA;AAEF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAI/D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqC1B,CAAA;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAA;AAIvD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAE3D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAS3E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,IAAI,CACX,SAAS,EACP,IAAI,GACJ,MAAM,GACN,SAAS,GACT,aAAa,GACb,QAAQ,GACR,UAAU,GACV,aAAa,GACb,cAAc,GACd,WAAW,CACd,GACC,OAAO,CAAC,SAAS,CAAC,GACnB,SAAS,CAWX"}

package/dist/templates/skill-spec.js

@@ -0,0 +1,119 @@
+/**
+ * Skill Specification Template
+ *
+ * Zod-validated schema for agent skills. Every skill must declare its
+ * inputs/outputs, required permissions, security constraints, and include
+ * at least one test case. This ensures quality and security before any
+ * skill is activated in production.
+ */
+import { z } from 'zod';
+// ─── Skill Permissions ──────────────────────────────────────────────────────
+export const SkillPermissionsSchema = z.object({
+    /** Tools this skill requires to function */
+    requiredTools: z.array(z.string().min(1)),
+    /** Memory access needed */
+    requiredMemoryAccess: z.array(z.enum(['working', 'episodic', 'semantic'])).default([]),
+    /** Whether this skill needs network access */
+    networkRequired: z.boolean().default(false),
+    /** Estimated token cost per invocation (for budgeting) */
+    estimatedTokenCost: z.number().int().positive().optional(),
+});
+// ─── Skill Security ─────────────────────────────────────────────────────────
+export const SkillSecuritySchema = z.object({
+    /** Sanitize all inputs before processing */
+    sanitizeInput: z.boolean().default(true),
+    /** Sanitize all outputs before returning */
+    sanitizeOutput: z.boolean().default(true),
+    /** Maximum execution time in milliseconds */
+    maxExecutionTimeMs: z.number().int().positive().default(30_000),
+    /** Whether this skill can be retried on failure */
+    retryable: z.boolean().default(true),
+    /** Maximum retry attempts */
+    maxRetries: z.number().int().min(0).default(3),
+    /** Whether this skill handles PII */
+    handlesPII: z.boolean().default(false),
+    /** Data retention policy for skill outputs */
+    dataRetention: z.enum(['none', 'session', 'persistent']).default('session'),
+});
+// ─── Test Case Schema ───────────────────────────────────────────────────────
+export const SkillTestCaseSchema = z.object({
+    /** What this test verifies */
+    description: z.string().min(1),
+    /** Input parameters */
+    input: z.record(z.string(), z.unknown()),
+    /** Expected output (for assertion) */
+    expectedOutput: z.record(z.string(), z.unknown()).optional(),
+    /** Whether this test case should pass or fail */
+    shouldPass: z.boolean().default(true),
+});
+// ─── Full Skill Specification ───────────────────────────────────────────────
+export const SkillSpecSchema = z.object({
+    /** Unique skill identifier */
+    id: z.string().min(1).max(100),
+    /** Human-readable skill name */
+    name: z.string().min(1).max(100),
+    /** Semantic version */
+    version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Must be semver (e.g., 1.0.0)'),
+    /** What this skill does */
+    description: z.string().min(10).max(500),
+    /** Detailed instructions for how to use this skill */
+    usage: z.string().min(10).optional(),
+    /** Input parameter schema (JSON Schema-compatible) */
+    inputSchema: z.record(z.string(), z.unknown()),
+    /** Output schema (JSON Schema-compatible) */
+    outputSchema: z.record(z.string(), z.unknown()),
+    /** Permission requirements */
+    permissions: SkillPermissionsSchema,
+    /** Security constraints */
+    security: SkillSecuritySchema,
+    /** Test cases — at least one required */
+    testCases: z.array(SkillTestCaseSchema).min(1, 'At least one test case is required'),
+    /** Who created this skill */
+    author: z.string().min(1),
+    /** License for this skill */
+    license: z.string().default('MIT'),
+    /** Category for skill catalog */
+    category: z.string().min(1),
+    /** Tags for search/filtering */
+    tags: z.array(z.string()).default([]),
+    /** When this spec was created */
+    createdAt: z.date(),
+    /** When this spec was last updated */
+    updatedAt: z.date(),
+});
+// ─── Validation ─────────────────────────────────────────────────────────────
+/**
+ * Validate a skill specification.
+ * Returns the validated spec or throws with detailed error messages.
+ */
+export function validateSkillSpec(input) {
+    return SkillSpecSchema.parse(input);
+}
+/**
+ * Safely validate a skill specification.
+ */
+export function safeValidateSkillSpec(input) {
+    const result = SkillSpecSchema.safeParse(input);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return {
+        success: false,
+        errors: result.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`),
+    };
+}
+/**
+ * Create a skill spec with sensible defaults.
+ */
+export function createSkillSpec(partial) {
+    const now = new Date();
+    return SkillSpecSchema.parse({
+        permissions: { requiredTools: [] },
+        security: {},
+        license: 'MIT',
+        tags: [],
+        createdAt: now,
+        updatedAt: now,
+        ...partial,
+    });
+}

package/dist/tools/base.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Tool Base Interface
+ *
+ * Defines the structure for tools that agents can use
+ */
+import type { z } from 'zod/v4';
+export interface ToolResult {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    /**
+     * Concise text summary for the LLM context window.
+     * When set, the runtime sends this to the model instead of serializing `data`.
+     * Use this to keep tool results token-efficient while preserving full data in `data`.
+     */
+    content?: string;
+    metadata?: {
+        executionTime?: number;
+        cost?: number;
+        tokensUsed?: number;
+        [key: string]: unknown;
+    };
+}
+export interface Tool {
+    /**
+     * Unique tool name (used in LLM tool calls and deduplication)
+     */
+    name: string;
+    /**
+     * Human-readable display name shown in UI. Falls back to `name` if omitted.
+     */
+    label?: string;
+    /**
+     * Tool description (used for LLM tool selection)
+     */
+    description: string;
+    /**
+     * Zod schema for tool parameters
+     */
+    parameters: z.ZodSchema;
+    /**
+     * Execute the tool with given parameters
+     */
+    execute(params: unknown): Promise<ToolResult>;
+    /**
+     * Optional: Validate parameters before execution
+     */
+    validate?(params: unknown): boolean;
+    /**
+     * Optional: Get tool metadata
+     */
+    getMetadata?(): {
+        category?: string;
+        version?: string;
+        author?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Tool execution context
+ */
+export interface ToolContext {
+    agentId?: string;
+    userId?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Tool with context
+ */
+export interface ContextualTool extends Tool {
+    executeWithContext(params: unknown, context: ToolContext): Promise<ToolResult>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/tools/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/tools/base.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAA;AAE/B,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE;QACT,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;CACF;AAED,MAAM,WAAW,IAAI;IACnB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAA;IAEZ;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAA;IAEnB;;OAEG;IACH,UAAU,EAAE,CAAC,CAAC,SAAS,CAAA;IAEvB;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE7C;;OAEG;IACH,QAAQ,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;IAEnC;;OAEG;IACH,WAAW,CAAC,IAAI;QACd,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KACvB,CAAA;CACF;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,cAAe,SAAQ,IAAI;IAC1C,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;CAC/E"}

package/dist/tools/base.js

@@ -0,0 +1,6 @@
+/**
+ * Tool Base Interface
+ *
+ * Defines the structure for tools that agents can use
+ */
+export {};