@cossistant/types 0.1.0 → 0.1.2

package/api/ai-agent-capabilities.js

@@ -8,12 +8,14 @@ const AI_AGENT_TOOL_CATEGORIES = [
 	"context",
 	"analysis"
 ];
+const AI_AGENT_TOOL_GROUPS = ["behavior", "actions"];
 const AI_AGENT_TOOL_IDS = [
 	"searchKnowledgeBase",
 	"identifyVisitor",
 	"updateConversationTitle",
 	"updateSentiment",
 	"setPriority",
+	"categorizeConversation",
 	"sendMessage",
 	"sendPrivateMessage",
 	"respond",
@@ -27,406 +29,333 @@ const AI_AGENT_BEHAVIOR_SETTING_KEYS = [
 	"canMarkSpam",
 	"canSetPriority",
 	"canEscalate",
+	"autoCategorize",
 	"autoGenerateTitle",
 	"autoAnalyzeSentiment"
 ];
-const AI_AGENT_TOOL_CATALOG = [
+const AI_AGENT_TOOL_CATALOG_RAW = [
 	{
 		id: "searchKnowledgeBase",
 		label: "Search Knowledge Base",
-		description: "Looks up product or policy facts in your trained knowledge before answering.",
+		description: "Retrieve relevant knowledge snippets by keyword query.",
 		category: "context",
+		group: "behavior",
+		order: 1,
 		isSystem: true,
 		isRequired: true,
 		isToggleable: false,
 		behaviorSettingKey: null,
-		defaultTemplateNames: ["deep-research.md", "grounded-answers.md"]
+		defaultSkill: {
+			name: "search-knowledge-base.md",
+			label: "Search Knowledge Base",
+			description: "Keyword query patterns and result interpretation.",
+			content: `## Query Tactics
+
+- Use short keyword queries (2-6 words).
+- Retry with synonyms when results are weak.
+- Prefer specific product/feature terms over full sentences.
+
+## Result Use
+
+- Prioritize high-similarity results that directly answer the request.
+- Use title/source metadata when it clarifies confidence.`
+		}
 	},
 	{
 		id: "identifyVisitor",
 		label: "Identify Visitor",
-		description: "Links visitor details to a contact record when name and email are collected.",
+		description: "Attach visitor name/email to the conversation record.",
 		category: "context",
+		group: "behavior",
+		order: 2,
 		isSystem: true,
 		isRequired: true,
 		isToggleable: false,
 		behaviorSettingKey: null,
-		defaultTemplateNames: ["visitor-identification.md"]
+		defaultSkill: {
+			name: "identify-visitor.md",
+			label: "Identify Visitor",
+			description: "Input hygiene for profile linking.",
+			content: `## Input Hygiene
+
+- Pass clean name/email values without extra text.
+- Use the latest visitor-provided values if they correct earlier info.
+- Avoid duplicate calls when identity is already up to date.`
+		}
 	},
 	{
 		id: "updateConversationTitle",
 		label: "Update Conversation Title",
-		description: "Sets or refreshes the conversation title once the topic is clear.",
+		description: "Set a concise title for the conversation topic.",
 		category: "analysis",
+		group: "behavior",
+		order: 3,
 		isSystem: false,
 		isRequired: false,
 		isToggleable: true,
 		behaviorSettingKey: "autoGenerateTitle",
-		defaultTemplateNames: ["title-hygiene.md"]
+		defaultSkill: {
+			name: "update-conversation-title.md",
+			label: "Update Conversation Title",
+			description: "Title formatting conventions.",
+			content: `## Title Formatting
+
+- Keep titles short and issue-focused.
+- Use concrete nouns (feature, error, account area).
+- Update only when the conversation topic is clear and stable across recent messages.
+- Skip vague, transitional, or generic titles.
+- Do not replace a title unless the newer title is meaningfully better.`
+		}
 	},
 	{
 		id: "updateSentiment",
 		label: "Update Sentiment",
-		description: "Tracks tone shifts and keeps conversation sentiment metadata up to date.",
+		description: "Record meaningful sentiment changes for conversation analytics.",
 		category: "analysis",
+		group: "behavior",
+		order: 4,
 		isSystem: false,
 		isRequired: false,
 		isToggleable: true,
 		behaviorSettingKey: "autoAnalyzeSentiment",
-		defaultTemplateNames: ["sentiment-tracking.md"]
+		defaultSkill: {
+			name: "update-sentiment.md",
+			label: "Update Sentiment",
+			description: "When sentiment updates add signal.",
+			content: `## Sentiment Updates
+
+- Update only for clear tone shifts.
+- Keep rationale short and evidence-based.
+- Skip minor wording changes with no practical impact.`
+		}
 	},
 	{
 		id: "setPriority",
 		label: "Set Priority",
-		description: "Adjusts urgency level for critical issues so teams can triage quickly.",
+		description: "Set operational urgency for the conversation.",
 		category: "analysis",
+		group: "behavior",
+		order: 5,
 		isSystem: false,
 		isRequired: false,
 		isToggleable: true,
 		behaviorSettingKey: "canSetPriority",
-		defaultTemplateNames: ["priority-triage.md"]
+		defaultSkill: {
+			name: "set-priority.md",
+			label: "Set Priority",
+			description: "Priority mapping by impact and urgency.",
+			content: `## Priority Mapping
+
+- Urgent: outage, security, or severe business impact.
+- High: blocked workflow with no practical workaround.
+- Normal: standard support work.
+- Low: informational, non-blocking requests.`
+		}
+	},
+	{
+		id: "categorizeConversation",
+		label: "Categorize Conversation",
+		description: "Add the conversation to one matching saved view.",
+		category: "analysis",
+		group: "behavior",
+		order: 6,
+		isSystem: false,
+		isRequired: false,
+		isToggleable: true,
+		behaviorSettingKey: "autoCategorize",
+		defaultSkill: {
+			name: "categorize-conversation.md",
+			label: "Categorize Conversation",
+			description: "How to choose the best matching saved view.",
+			content: `## Categorization Rules
+
+- Use only one saved view when the match is clear.
+- Match the conversation to the closest existing view prompt and description.
+- Skip when no view clearly fits.
+- Prefer stable themes over one-off phrases from a single message.`
+		}
 	},
 	{
 		id: "sendMessage",
-		label: "Send Public Message",
-		description: "Sends a visible reply to the visitor.",
+		label: "Send Chat Message",
+		description: "Send one short customer-visible chat message. Use up to 3 when shorter bubbles read better.",
 		category: "messaging",
+		group: "behavior",
+		order: 7,
 		isSystem: true,
 		isRequired: true,
 		isToggleable: false,
 		behaviorSettingKey: null,
-		defaultTemplateNames: ["tone-and-voice.md", "short-clear-replies.md"]
+		defaultSkill: {
+			name: "send-message.md",
+			label: "Send Chat Message",
+			description: "Short chat-bubble reply rules.",
+			content: `## Role
+
+- Use this for every visitor-facing reply.
+- Prefer short chat bubbles over one dense block of text.
+- Use 2 or 3 separate calls when splitting improves readability.
+- Do not exceed 3 public chat messages in one run.`
+		}
 	},
 	{
 		id: "sendPrivateMessage",
 		label: "Send Private Note",
-		description: "Adds internal-only notes for teammates that visitors cannot see.",
+		description: "Send internal notes to teammates that visitors cannot see.",
 		category: "messaging",
+		group: "behavior",
+		order: 8,
 		isSystem: true,
 		isRequired: true,
 		isToggleable: false,
 		behaviorSettingKey: null,
-		defaultTemplateNames: ["handoff-notes.md"]
+		defaultSkill: {
+			name: "send-private-message.md",
+			label: "Send Private Note",
+			description: "Internal-note structure for handoff quality.",
+			content: `## Internal Note Structure
+
+- Include issue summary, key facts, and actions already attempted.
+- Keep notes scannable for fast teammate handoff.
+- Use internal operational tone (not customer-facing copy).`
+		}
 	},
 	{
 		id: "respond",
 		label: "Finish: Respond",
-		description: "Marks turn complete after responding to the visitor.",
+		description: "Finish the run after sending a complete public response.",
 		category: "action",
+		group: "actions",
+		order: 1,
 		isSystem: true,
 		isRequired: true,
 		isToggleable: false,
 		behaviorSettingKey: null,
-		defaultTemplateNames: ["reply-or-stay-silent.md"]
+		defaultSkill: {
+			name: "respond.md",
+			label: "Finish Respond",
+			description: "When to select the respond finish action.",
+			content: `## Finish Semantics
+
+- Choose this when the turn is complete and no escalation/closure state change is required.
+- Use this as the terminal action for normal reply flows.`
+		}
 	},
 	{
 		id: "escalate",
 		label: "Finish: Escalate",
-		description: "Hands off the conversation to a human agent when needed.",
+		description: "Escalate to a human when AI should not complete the request.",
 		category: "action",
+		group: "actions",
+		order: 2,
 		isSystem: false,
 		isRequired: false,
 		isToggleable: true,
 		behaviorSettingKey: "canEscalate",
-		defaultTemplateNames: ["escalation-playbook.md"]
+		defaultSkill: {
+			name: "escalate.md",
+			label: "Finish Escalate",
+			description: "When to select the escalate finish action.",
+			content: `## Finish Semantics
+
+- Choose this when human intervention is required.
+- Include a clear escalation reason payload for teammate routing.`
+		}
 	},
 	{
 		id: "resolve",
 		label: "Finish: Resolve",
-		description: "Marks the conversation as resolved when it is fully handled.",
+		description: "Mark conversation resolved once the issue is fully handled.",
 		category: "action",
+		group: "actions",
+		order: 3,
 		isSystem: false,
 		isRequired: false,
 		isToggleable: true,
 		behaviorSettingKey: "canResolve",
-		defaultTemplateNames: ["resolution-checklist.md"]
+		defaultSkill: {
+			name: "resolve.md",
+			label: "Finish Resolve",
+			description: "When to select the resolve finish action.",
+			content: `## Finish Semantics
+
+- Choose this when the issue is closed and the conversation can be marked resolved.
+- Use resolution-oriented reasoning in the payload.`
+		}
 	},
 	{
 		id: "markSpam",
 		label: "Finish: Mark Spam",
-		description: "Flags obvious spam or abuse and closes the conversation.",
+		description: "Mark obvious abuse/spam and close quickly.",
 		category: "action",
+		group: "actions",
+		order: 4,
 		isSystem: false,
 		isRequired: false,
 		isToggleable: true,
 		behaviorSettingKey: "canMarkSpam",
-		defaultTemplateNames: ["spam-detection.md"]
+		defaultSkill: {
+			name: "mark-spam.md",
+			label: "Finish Mark Spam",
+			description: "When to select the spam finish action.",
+			content: `## Finish Semantics
+
+- Choose this for clear spam/abuse/bot traffic.
+- Capture concise evidence in reasoning for auditability.`
+		}
 	},
 	{
 		id: "skip",
 		label: "Finish: Skip",
-		description: "Intentionally stays silent when no response is needed from AI.",
+		description: "Finish without a public response when silence is better.",
 		category: "action",
+		group: "actions",
+		order: 5,
 		isSystem: true,
 		isRequired: true,
 		isToggleable: false,
 		behaviorSettingKey: null,
-		defaultTemplateNames: ["reply-or-stay-silent.md"]
+		defaultSkill: {
+			name: "skip.md",
+			label: "Finish Skip",
+			description: "When to select the skip finish action.",
+			content: `## Finish Semantics
+
+- Choose this when no additional assistant output is needed for this run.
+- Use reasoning that explains why silence is intentional.`
+		}
 	}
 ];
-const AI_AGENT_DEFAULT_SKILL_TEMPLATE_DEFINITIONS = [
-	{
-		name: "reply-or-stay-silent.md",
-		label: "Reply Or Stay Silent",
-		description: "Defines when the AI should answer and when it should intentionally stay silent.",
-		content: `## Reply Decision
-
-- Reply when the visitor still needs a clear, concrete answer.
-- Stay silent when a human already answered well or when the message is only acknowledgement.
-- If unsure whether to reply, prefer one short helpful message over multiple partial replies.
-
-## Tool Notes
-
-- Use [@Send Public Message](mention:tool:sendMessage) only when a reply adds value.
-- Finish with [@Finish: Respond](mention:tool:respond) after replying.
-- Use [@Finish: Skip](mention:tool:skip) when no reply is required.`,
-		suggestedToolIds: [
-			"sendMessage",
-			"respond",
-			"skip"
-		]
-	},
-	{
-		name: "tone-and-voice.md",
-		label: "Tone And Voice",
-		description: "Keeps replies concise, empathetic, and aligned with a support tone.",
-		content: `## Tone
-
-- Be concise, direct, and calm.
-- Prefer plain language over jargon.
-- Keep messages to 1-2 short sentences when possible.
-
-## Empathy
-
-- Acknowledge frustration without over-apologizing.
-- Focus on the next useful action.
-
-## Tool Notes
-
-- Send customer-visible text through [@Send Public Message](mention:tool:sendMessage).`,
-		suggestedToolIds: ["sendMessage"]
-	},
-	{
-		name: "short-clear-replies.md",
-		label: "Short Clear Replies",
-		description: "Enforces short, structured customer-facing responses.",
-		content: `## Message Shape
-
-- First sentence: direct answer.
-- Optional second sentence: next step or clarifying question.
-- Avoid multi-paragraph replies unless the question is complex.
-
-## Tool Notes
-
-- Send the final customer reply with [@Send Public Message](mention:tool:sendMessage).`,
-		suggestedToolIds: ["sendMessage"]
-	},
-	{
-		name: "deep-research.md",
-		label: "Deep Research",
-		description: "Guides multi-pass retrieval before giving factual or policy answers.",
-		content: `## Research Workflow
-
-- For factual/product/policy questions, search before answering.
-- Start with a short focused query, then broaden if needed.
-- Use at least one follow-up search if confidence is low.
-
-## Tool Notes
-
-- Use [@Search Knowledge Base](mention:tool:searchKnowledgeBase) for retrieval.
-- Only send final claims after grounding them in retrieved context.`,
-		suggestedToolIds: ["searchKnowledgeBase"]
-	},
-	{
-		name: "grounded-answers.md",
-		label: "Grounded Answers",
-		description: "Prevents hallucinations and enforces transparent uncertainty.",
-		content: `## Grounding Rules
-
-- Do not invent product, policy, or pricing details.
-- If information is missing, say so clearly and offer escalation.
-- Prefer partial certainty over confident guessing.
-
-## Tool Notes
-
-- Validate facts with [@Search Knowledge Base](mention:tool:searchKnowledgeBase).
-- If unsupported, use [@Finish: Escalate](mention:tool:escalate) when available.`,
-		suggestedToolIds: ["searchKnowledgeBase", "escalate"]
-	},
-	{
-		name: "visitor-identification.md",
-		label: "Visitor Identification",
-		description: "Controls when and how to request name/email and identify the visitor.",
-		content: `## Identification Policy
-
-- Ask for name and email only when needed for account-specific help.
-- Validate that the name field contains a name and email field contains an email.
-- Update details if the visitor corrects their information.
-
-## Tool Notes
-
-- Link identity with [@Identify Visitor](mention:tool:identifyVisitor).`,
-		suggestedToolIds: ["identifyVisitor"]
-	},
-	{
-		name: "escalation-playbook.md",
-		label: "Escalation Playbook",
-		description: "Defines when escalation is mandatory and what to include in handoff.",
-		content: `## Escalate When
-
-- The visitor asks for a human.
-- You cannot find reliable information.
-- Legal, compliance, billing, or high-risk judgment is required.
-
-## Handoff Quality
-
-- Tell the visitor what happens next.
-- Leave concise internal context for teammates.
-
-## Tool Notes
-
-- Notify visitor with [@Send Public Message](mention:tool:sendMessage).
-- Add handoff context via [@Send Private Note](mention:tool:sendPrivateMessage).
-- Finish with [@Finish: Escalate](mention:tool:escalate).`,
-		suggestedToolIds: [
-			"sendMessage",
-			"sendPrivateMessage",
-			"escalate"
-		]
-	},
-	{
-		name: "resolution-checklist.md",
-		label: "Resolution Checklist",
-		description: "Ensures conversations are only resolved after clear completion criteria.",
-		content: `## Resolve Criteria
-
-- The visitor's request is fully addressed.
-- No unresolved dependency remains.
-- The final response includes a clear closure.
-
-## Tool Notes
-
-- Send closure text with [@Send Public Message](mention:tool:sendMessage).
-- Finish with [@Finish: Resolve](mention:tool:resolve).`,
-		suggestedToolIds: ["sendMessage", "resolve"]
-	},
-	{
-		name: "spam-detection.md",
-		label: "Spam Detection",
-		description: "Sets strict criteria for spam classification.",
-		content: `## Spam Heuristics
-
-- Mark as spam only for obvious bot, phishing, or abusive noise.
-- Do not mark difficult but valid customer requests as spam.
-
-## Tool Notes
-
-- Use [@Finish: Mark Spam](mention:tool:markSpam) only when highly confident.`,
-		suggestedToolIds: ["markSpam"]
-	},
-	{
-		name: "priority-triage.md",
-		label: "Priority Triage",
-		description: "Standardizes urgency assignment for incoming issues.",
-		content: `## Priority Rules
-
-- Urgent: outages, security incidents, severe business impact.
-- High: blocked workflow with no workaround.
-- Normal: standard product support requests.
-- Low: informational or minor questions.
-
-## Tool Notes
-
-- Set urgency with [@Set Priority](mention:tool:setPriority).`,
-		suggestedToolIds: ["setPriority"]
-	},
-	{
-		name: "sentiment-tracking.md",
-		label: "Sentiment Tracking",
-		description: "Encourages sentiment updates when tone changes.",
-		content: `## Sentiment Updates
-
-- Update sentiment when tone shifts meaningfully.
-- Keep reason short and factual.
-- Avoid over-updating on minor wording changes.
-
-## Tool Notes
-
-- Record tone with [@Update Sentiment](mention:tool:updateSentiment).`,
-		suggestedToolIds: ["updateSentiment"]
-	},
-	{
-		name: "title-hygiene.md",
-		label: "Title Hygiene",
-		description: "Keeps conversation titles clear and actionable.",
-		content: `## Title Standards
-
-- Keep titles short and specific.
-- Reflect the primary issue, not generic phrases.
-- Update title if topic changes significantly.
-
-## Tool Notes
-
-- Use [@Update Conversation Title](mention:tool:updateConversationTitle).`,
-		suggestedToolIds: ["updateConversationTitle"]
-	},
-	{
-		name: "handoff-notes.md",
-		label: "Handoff Notes",
-		description: "Improves private notes shared with human teammates.",
-		content: `## Private Note Checklist
-
-- Include issue summary, key facts, and what was already tried.
-- Add urgency and expected next action.
-- Keep notes scannable and concise.
-
-## Tool Notes
-
-- Send internal details with [@Send Private Note](mention:tool:sendPrivateMessage).`,
-		suggestedToolIds: ["sendPrivateMessage"]
+const AI_AGENT_TOOL_CATALOG = AI_AGENT_TOOL_CATALOG_RAW.map((tool) => ({
+	...tool,
+	defaultSkill: {
+		...tool.defaultSkill,
+		content: serializeSkillFileContent({
+			name: stripSkillMarkdownExtension(tool.defaultSkill.name),
+			description: tool.defaultSkill.description,
+			body: tool.defaultSkill.content
+		})
 	}
-];
-const AI_AGENT_DEFAULT_SKILL_TEMPLATES = AI_AGENT_DEFAULT_SKILL_TEMPLATE_DEFINITIONS.map((template) => ({
-	...template,
-	content: serializeSkillFileContent({
-		name: stripSkillMarkdownExtension(template.name),
-		description: template.description,
-		body: template.content
-	})
 }));
-const AI_AGENT_SYSTEM_SKILL_METADATA = [
-	{
-		name: "agent.md",
-		label: "Agent Identity",
-		description: "Core role, persona, and mission of the assistant."
-	},
-	{
-		name: "security.md",
-		label: "Security Guardrails",
-		description: "Critical safety and confidentiality rules that should stay strict."
-	},
-	{
-		name: "behaviour.md",
-		label: "Behavior Policy",
-		description: "Runtime behavior and mode-specific operating guidance."
-	},
-	{
-		name: "participation.md",
-		label: "Participation Policy",
-		description: "Rules for when AI should participate versus intentionally stay silent."
-	},
-	{
-		name: "grounding.md",
-		label: "Grounding Policy",
-		description: "Instructions for factual grounding and knowledge retrieval discipline."
-	},
-	{
-		name: "capabilities.md",
-		label: "Capabilities Contract",
-		description: "Capability boundaries and references to optional behavior skills."
-	}
+const AI_AGENT_RESERVED_TOOL_SKILL_TEMPLATE_NAMES = [...new Set(AI_AGENT_TOOL_CATALOG.map((tool) => tool.defaultSkill.name))];
+const AI_AGENT_DROPPED_SKILL_TEMPLATE_NAMES = [
+	"reply-or-stay-silent.md",
+	"send-message-behavior.md",
+	"deep-research.md",
+	"grounded-answers.md",
+	"visitor-identification.md",
+	"escalation-playbook.md",
+	"resolution-checklist.md",
+	"spam-detection.md",
+	"priority-triage.md",
+	"sentiment-tracking.md",
+	"title-hygiene.md",
+	"handoff-notes.md",
+	"tone-and-voice.md",
+	"short-clear-replies.md",
+	"wait.md"
 ];
 
 //#endregion
-export { AI_AGENT_BEHAVIOR_SETTING_KEYS, AI_AGENT_DEFAULT_SKILL_TEMPLATES, AI_AGENT_SYSTEM_SKILL_METADATA, AI_AGENT_TOOL_CATALOG, AI_AGENT_TOOL_CATEGORIES, AI_AGENT_TOOL_IDS };
+export { AI_AGENT_BEHAVIOR_SETTING_KEYS, AI_AGENT_DROPPED_SKILL_TEMPLATE_NAMES, AI_AGENT_RESERVED_TOOL_SKILL_TEMPLATE_NAMES, AI_AGENT_TOOL_CATALOG, AI_AGENT_TOOL_CATEGORIES, AI_AGENT_TOOL_GROUPS, AI_AGENT_TOOL_IDS };
 //# sourceMappingURL=ai-agent-capabilities.js.map