@agenticc/core 1.0.0

package/dist/types/response.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Agent Response Type Definitions
+ *
+ * Defines the different types of responses the Agent can return.
+ * Each response type represents a different interaction pattern with the user.
+ */
+/**
+ * All possible response types
+ */
+export declare const RESPONSE_TYPES: readonly ["execute", "clarify", "knowledge_request", "confirm", "options"];
+/**
+ * Response type literal union
+ */
+export type ResponseType = (typeof RESPONSE_TYPES)[number];
+/**
+ * Execute Response - Agent has completed an action
+ *
+ * Returned when the Agent has sufficient knowledge and confidence
+ * to execute the requested action.
+ */
+export interface ExecuteResponse {
+    type: 'execute';
+    /** Human-readable result message */
+    message: string;
+    /** Optional structured data from the execution */
+    data?: unknown;
+    /** Tool calls that were made during execution */
+    toolCalls?: ToolCallRecord[];
+}
+/**
+ * Record of a tool call made during execution
+ */
+export interface ToolCallRecord {
+    toolName: string;
+    arguments: Record<string, unknown>;
+    result: {
+        success: boolean;
+        content: string;
+        data?: unknown;
+    };
+}
+/**
+ * Clarify Response - Agent needs more information
+ *
+ * Returned when the user's request is ambiguous and the Agent
+ * needs clarification before proceeding.
+ */
+export interface ClarifyResponse {
+    type: 'clarify';
+    /** Explanation of why clarification is needed */
+    message: string;
+    /** Specific questions to ask the user */
+    questions: string[];
+}
+/**
+ * Knowledge Request Response - Agent lacks required knowledge
+ *
+ * Returned when the Agent doesn't have sufficient knowledge
+ * to complete the request and needs the user to provide information.
+ */
+export interface KnowledgeRequestResponse {
+    type: 'knowledge_request';
+    /** Explanation of what knowledge is missing */
+    message: string;
+    /** Details about the missing knowledge */
+    missing: {
+        /** Topic area that's missing */
+        topic: string;
+        /** Description of what information is needed */
+        description: string;
+    };
+    /** Options for how the user can provide the knowledge */
+    options: KnowledgeOption[];
+}
+/**
+ * Options for providing knowledge to the Agent
+ */
+export interface KnowledgeOption {
+    /** Unique identifier for this option */
+    id: string;
+    /** Type of knowledge input */
+    type: 'provide_text' | 'upload_file' | 'provide_url' | 'skip' | 'try_anyway';
+    /** Human-readable label for the option */
+    label: string;
+    /** Optional description of what this option does */
+    description?: string;
+}
+/**
+ * Confirm Response - Agent needs user confirmation
+ *
+ * Returned when the Agent is about to perform a high-risk operation
+ * and needs explicit user confirmation.
+ */
+export interface ConfirmResponse {
+    type: 'confirm';
+    /** Explanation of what action will be taken */
+    message: string;
+    /** Details of the action to be confirmed */
+    action: {
+        /** Type of action (e.g., 'update', 'delete', 'create') */
+        type: string;
+        /** Target of the action (e.g., file path, entity name) */
+        target: string;
+        /** Parameters for the action */
+        params: Record<string, unknown>;
+    };
+    /** Risk level of the operation */
+    risk: 'low' | 'medium' | 'high';
+    /** Optional preview of the changes */
+    preview?: string;
+}
+/**
+ * Options Response - Agent presents choices to user
+ *
+ * Returned when multiple valid options exist and the Agent
+ * needs the user to make a selection.
+ */
+export interface OptionsResponse {
+    type: 'options';
+    /** Explanation of why options are being presented */
+    message: string;
+    /** Available options for the user to choose from */
+    options: SelectableOption[];
+}
+/**
+ * A selectable option in an Options response
+ */
+export interface SelectableOption {
+    /** Unique identifier for this option */
+    id: string;
+    /** Human-readable label */
+    label: string;
+    /** Detailed description of what this option does */
+    description: string;
+    /** Optional metadata for the option */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Union type of all possible Agent responses
+ */
+export type AgentResponse = ExecuteResponse | ClarifyResponse | KnowledgeRequestResponse | ConfirmResponse | OptionsResponse;
+/**
+ * Type guard to check if a response is an ExecuteResponse
+ */
+export declare function isExecuteResponse(response: AgentResponse): response is ExecuteResponse;
+/**
+ * Type guard to check if a response is a ClarifyResponse
+ */
+export declare function isClarifyResponse(response: AgentResponse): response is ClarifyResponse;
+/**
+ * Type guard to check if a response is a KnowledgeRequestResponse
+ */
+export declare function isKnowledgeRequestResponse(response: AgentResponse): response is KnowledgeRequestResponse;
+/**
+ * Type guard to check if a response is a ConfirmResponse
+ */
+export declare function isConfirmResponse(response: AgentResponse): response is ConfirmResponse;
+/**
+ * Type guard to check if a response is an OptionsResponse
+ */
+export declare function isOptionsResponse(response: AgentResponse): response is OptionsResponse;
+/**
+ * Validates that a response object has a valid response type
+ */
+export declare function isValidResponseType(type: unknown): type is ResponseType;
+/**
+ * Creates an ExecuteResponse
+ */
+export declare function createExecuteResponse(message: string, data?: unknown, toolCalls?: ToolCallRecord[]): ExecuteResponse;
+/**
+ * Creates a ClarifyResponse
+ */
+export declare function createClarifyResponse(message: string, questions: string[]): ClarifyResponse;
+/**
+ * Creates a KnowledgeRequestResponse
+ */
+export declare function createKnowledgeRequestResponse(message: string, topic: string, description: string, options?: KnowledgeOption[]): KnowledgeRequestResponse;
+/**
+ * Creates a ConfirmResponse
+ */
+export declare function createConfirmResponse(message: string, actionType: string, target: string, params: Record<string, unknown>, risk: 'low' | 'medium' | 'high', preview?: string): ConfirmResponse;
+/**
+ * Creates an OptionsResponse
+ */
+export declare function createOptionsResponse(message: string, options: SelectableOption[]): OptionsResponse;
+//# sourceMappingURL=response.d.ts.map

package/dist/types/response.d.ts.map

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

package/dist/types/response.js

@@ -0,0 +1,99 @@
+/**
+ * Agent Response Type Definitions
+ *
+ * Defines the different types of responses the Agent can return.
+ * Each response type represents a different interaction pattern with the user.
+ */
+/**
+ * All possible response types
+ */
+export const RESPONSE_TYPES = [
+    'execute',
+    'clarify',
+    'knowledge_request',
+    'confirm',
+    'options',
+];
+/**
+ * Type guard to check if a response is an ExecuteResponse
+ */
+export function isExecuteResponse(response) {
+    return response.type === 'execute';
+}
+/**
+ * Type guard to check if a response is a ClarifyResponse
+ */
+export function isClarifyResponse(response) {
+    return response.type === 'clarify';
+}
+/**
+ * Type guard to check if a response is a KnowledgeRequestResponse
+ */
+export function isKnowledgeRequestResponse(response) {
+    return response.type === 'knowledge_request';
+}
+/**
+ * Type guard to check if a response is a ConfirmResponse
+ */
+export function isConfirmResponse(response) {
+    return response.type === 'confirm';
+}
+/**
+ * Type guard to check if a response is an OptionsResponse
+ */
+export function isOptionsResponse(response) {
+    return response.type === 'options';
+}
+/**
+ * Validates that a response object has a valid response type
+ */
+export function isValidResponseType(type) {
+    return typeof type === 'string' && RESPONSE_TYPES.includes(type);
+}
+/**
+ * Creates an ExecuteResponse
+ */
+export function createExecuteResponse(message, data, toolCalls) {
+    return { type: 'execute', message, data, toolCalls };
+}
+/**
+ * Creates a ClarifyResponse
+ */
+export function createClarifyResponse(message, questions) {
+    return { type: 'clarify', message, questions };
+}
+/**
+ * Creates a KnowledgeRequestResponse
+ */
+export function createKnowledgeRequestResponse(message, topic, description, options) {
+    const defaultOptions = [
+        { id: 'provide_text', type: 'provide_text', label: '提供文本信息' },
+        { id: 'skip', type: 'skip', label: '跳过此步骤' },
+        { id: 'try_anyway', type: 'try_anyway', label: '尝试继续' },
+    ];
+    return {
+        type: 'knowledge_request',
+        message,
+        missing: { topic, description },
+        options: options ?? defaultOptions,
+    };
+}
+/**
+ * Creates a ConfirmResponse
+ */
+export function createConfirmResponse(message, actionType, target, params, risk, preview) {
+    return {
+        type: 'confirm',
+        message,
+        action: { type: actionType, target, params },
+        risk,
+        preview,
+    };
+}
+/**
+ * Creates an OptionsResponse
+ */
+export function createOptionsResponse(message, options) {
+    return { type: 'options', message, options };
+}
+//# sourceMappingURL=response.js.map

package/dist/types/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/types/response.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,SAAS;IACT,SAAS;IACT,mBAAmB;IACnB,SAAS;IACT,SAAS;CACD,CAAC;AAoJX;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAuB;IAEvB,OAAO,QAAQ,CAAC,IAAI,KAAK,mBAAmB,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,OAAO,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC;AACrC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,cAAc,CAAC,QAAQ,CAAC,IAAoB,CAAC,CAAC;AACnF,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,IAAc,EACd,SAA4B;IAE5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,SAAmB;IACxE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,8BAA8B,CAC5C,OAAe,EACf,KAAa,EACb,WAAmB,EACnB,OAA2B;IAE3B,MAAM,cAAc,GAAsB;QACxC,EAAE,EAAE,EAAE,cAAc,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,QAAQ,EAAE;QAC7D,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE;QAC5C,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,EAAE;KACxD,CAAC;IACF,OAAO;QACL,IAAI,EAAE,mBAAmB;QACzB,OAAO;QACP,OAAO,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE;QAC/B,OAAO,EAAE,OAAO,IAAI,cAAc;KACnC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,UAAkB,EAClB,MAAc,EACd,MAA+B,EAC/B,IAA+B,EAC/B,OAAgB;IAEhB,OAAO;QACL,IAAI,EAAE,SAAS;QACf,OAAO;QACP,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE;QAC5C,IAAI;QACJ,OAAO;KACR,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,OAA2B;IAE3B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC/C,CAAC"}